websocket

package module
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 11, 2026 License: MIT Imports: 17 Imported by: 0

README

Websocket

什么是WebSocket?

WebSocket 协议主要为了解决基于 HTTP/1.x 的 Web 应用无法实现服务端向客户端主动推送的问题, 为了兼容现有的设施, WebSocket 协议使用与 HTTP 协议相同的端口, 并使用 HTTP Upgrade 机制来进行 WebSocket 握手, 当握手完成之后, 通信双方便可以按照 WebSocket 协议的方式进行交互

WebSocket 使用 TCP 作为传输层协议, 与 HTTP 类似, WebSocket 也支持在 TCP 上层引入 TLS 层, 以建立加密数据传输通道, 即 WebSocket over TLS, WebSocket 的 URI 与 HTTP URI 的结构类似, 对于使用 80 端口的 WebSocket over TCP, 其 URI 的一般形式为 ws://host:port/path/query 对于使用 443 端口的 WebSocket over TLS, 其 URI 的一般形式为 wss://host:port/path/query

在 WebSocket 协议中, 帧 (frame) 是通信双方数据传输的基本单元, 与其它网络协议相同, frame 由 Header 和 Payload 两部分构成, frame 有多种类型, frame 的类型由其头部的 Opcode 字段 (将在下面讨论) 来指示, WebSocket 的 frame 可以分为两类, 一类是用于传输控制信息的 frame (如通知对方关闭 WebSocket 连接), 一类是用于传输应用数据的 frame, 使用 WebSocket 协议通信的双方都需要首先进行握手, 只有当握手成功之后才开始使用 frame 传输数据

参考资料

Documentation

Overview

Package websocket provides a WebSocket server that implements the transport.Server interface.

The server wraps a standard http.Server with a http.ServeMux and uses gorilla/websocket for the WebSocket upgrade. It supports:

  • Binary and text payload modes
  • Message handler registration with type-based dispatch
  • Session management with connect/disconnect callbacks
  • Broadcast and targeted message sending
  • Optional token injection via Sec-WebSocket-Protocol
  • HTTP middleware (compatible with transport/http middleware)

Usage:

import wsServer "github.com/tx7do/go-wind-plugins/transport/websocket"

srv := wsServer.NewServer(":8080",
    wsServer.WithPath("/ws"),
    wsServer.WithPayloadType(wsServer.PayloadTypeText),
)

// Register a message handler.
const MsgChat wsServer.NetMessageType = 1
srv.RegisterMessageHandler(MsgChat, func(sid wsServer.SessionID, msg wsServer.MessagePayload) error {
    fmt.Println("received:", msg)
    return nil
}, nil)

if err := srv.Start(ctx); err != nil { ... }

Index

Constants

View Source
const KindWebsocket = "websocket"

KindWebsocket 是 WebSocket 传输类型标识。

Variables

This section is empty.

Functions

func RegisterServerMessageHandler

func RegisterServerMessageHandler[T any](srv *Server, messageType NetMessageType, handler func(SessionID, *T) error)

RegisterServerMessageHandler 是 RegisterMessageHandler 的泛型便捷方法。 它自动创建 T 类型的载荷实例并调用 handler。

Types

type BinaryNetPacket

type BinaryNetPacket struct {
	Type    NetMessageType
	Payload []byte
}

BinaryNetPacket 是二进制模式下的消息包格式。 布局:[4 字节 Little-Endian uint32 类型][剩余字节为 payload]

func (*BinaryNetPacket) Marshal

func (m *BinaryNetPacket) Marshal() ([]byte, error)

Marshal 将 BinaryNetPacket 序列化为二进制格式。

func (*BinaryNetPacket) Unmarshal

func (m *BinaryNetPacket) Unmarshal(buf []byte) error

Unmarshal 从二进制数据反序列化 BinaryNetPacket。

type Creator

type Creator func() any

Creator 创建消息载荷的空实例,用于反序列化。

type MessageHandlerData

type MessageHandlerData struct {
	Handler NetMessageHandler
	Creator Creator
}

MessageHandlerData 包装了一个消息处理器及其载荷创建器。

func (*MessageHandlerData) Create

func (h *MessageHandlerData) Create() any

Create 调用 Creator 创建载荷实例。如果 Creator 为 nil 则返回 nil。

type MessagePayload

type MessagePayload any

MessagePayload 表示消息载荷的任意类型。

type Middleware

type Middleware = func(http.Handler) http.Handler

Middleware 是标准 HTTP 中间件类型。 使用类型别名使得 transport/http/middleware 下的中间件可以直接复用。

type NetMessageHandler

type NetMessageHandler func(SessionID, MessagePayload) error

NetMessageHandler 处理特定类型的 WebSocket 消息。

type NetMessageHandlerMap

type NetMessageHandlerMap map[NetMessageType]*MessageHandlerData

NetMessageHandlerMap 将消息类型映射到其处理器数据。

type NetMessageType

type NetMessageType uint32

NetMessageType 标识 WebSocket 消息的业务类型。

type NetPacketMarshaler

type NetPacketMarshaler func(messageType NetMessageType, message MessagePayload) ([]byte, error)

NetPacketMarshaler 将消息类型和载荷序列化为字节流。

type NetPacketUnmarshaler

type NetPacketUnmarshaler func(buf []byte) (*MessageHandlerData, MessagePayload, error)

NetPacketUnmarshaler 将字节流反序列化为处理器和载荷。

type Option

type Option func(*Server)

Option 是 WebSocket 服务器的配置选项。

func WithChannelBufferSize

func WithChannelBufferSize(size int) Option

WithChannelBufferSize 设置每个会话发送通道的缓冲大小。

func WithCheckOrigin

func WithCheckOrigin(domain string) Option

WithCheckOrigin 设置 Origin 检查函数,仅允许指定域名的连接。

func WithCodec

func WithCodec(name string) Option

WithCodec 设置编解码器名称(如 "json"、"proto" 等)。 codec 会通过 encoding.GetCodec(name) 获取。

func WithEnableCompression

func WithEnableCompression(enable bool) Option

WithEnableCompression 启用或禁用 WebSocket 压缩。

func WithHandshakeTimeout

func WithHandshakeTimeout(timeout time.Duration) Option

WithHandshakeTimeout 设置 WebSocket 握手超时时间。

func WithInjectTokenToQuery

func WithInjectTokenToQuery(enable bool, tokenKey string) Option

WithInjectTokenToQuery 配置是否将 Sec-WebSocket-Protocol 中的 token 注入到查询参数中。

func WithMessageMarshaler

func WithMessageMarshaler(m NetPacketMarshaler) Option

WithMessageMarshaler 设置自定义的消息序列化函数。

func WithMessageUnmarshaler

func WithMessageUnmarshaler(m NetPacketUnmarshaler) Option

WithMessageUnmarshaler 设置自定义的消息反序列化函数。

func WithMiddleware

func WithMiddleware(middlewares ...Middleware) Option

WithMiddleware 通过选项设置中间件,允许在创建 Server 时直接传入中间件。

func WithPath

func WithPath(path string) Option

WithPath 设置 WebSocket 的 HTTP 路由路径(默认 "/ws")。

func WithPayloadType

func WithPayloadType(payloadType PayloadType) Option

WithPayloadType 设置消息载荷类型(二进制或文本)。

func WithReadBufferSize

func WithReadBufferSize(size int) Option

WithReadBufferSize 设置 WebSocket 读取缓冲区大小。

func WithSocketConnectHandler

func WithSocketConnectHandler(h SocketConnectHandler) Option

WithSocketConnectHandler 设置连接建立/断开时的回调函数。

func WithSocketRawDataHandler

func WithSocketRawDataHandler(h SocketRawDataHandler) Option

WithSocketRawDataHandler 设置自定义的原始数据处理函数。 设置后将绕过默认的类型分发逻辑。

func WithTLS

func WithTLS(certFile, keyFile string) Option

WithTLS 从证书和私钥文件加载 TLS 配置,启用 WSS。

func WithTLSConfig

func WithTLSConfig(c *tls.Config) Option

WithTLSConfig 设置 TLS 配置,启用 WSS(WebSocket Secure)。

func WithWriteBufferSize

func WithWriteBufferSize(size int) Option

WithWriteBufferSize 设置 WebSocket 写入缓冲区大小。

type PayloadType

type PayloadType uint8

PayloadType 定义 WebSocket 消息的载荷格式。

const (
	// PayloadTypeBinary 二进制模式,使用 BinaryNetPacket 格式。
	PayloadTypeBinary PayloadType = 0
	// PayloadTypeText 文本模式,使用 JSON TextNetPacket 格式。
	PayloadTypeText PayloadType = 1
)

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server 是 WebSocket 服务器,实现 transport.Server 接口。

func NewServer

func NewServer(addr string, opts ...Option) *Server

NewServer 创建一个 WebSocket 服务器实例。 addr 是监听地址(如 ":8080")。

func (*Server) Addr

func (s *Server) Addr() string

Addr 返回配置的监听地址。

func (*Server) Broadcast

func (s *Server) Broadcast(messageType NetMessageType, message MessagePayload)

Broadcast 向所有活跃会话广播消息。

func (*Server) DeregisterMessageHandler

func (s *Server) DeregisterMessageHandler(messageType NetMessageType)

DeregisterMessageHandler 注销指定消息类型的处理器。

func (*Server) Endpoint

func (s *Server) Endpoint() string

Endpoint 返回服务器的访问地址。

func (*Server) GetMessageHandler

func (s *Server) GetMessageHandler(messageType NetMessageType) *MessageHandlerData

GetMessageHandler 返回指定消息类型的处理器数据。

func (*Server) HandleFunc

func (s *Server) HandleFunc(path string, h http.HandlerFunc)

HandleFunc 注册普通 HTTP 处理器到指定路径。

func (*Server) OnSessionAdded

func (s *Server) OnSessionAdded(session *Session)

OnSessionAdded 在新会话建立时调用。

func (*Server) OnSessionRemoved

func (s *Server) OnSessionRemoved(session *Session)

OnSessionRemoved 在会话断开时调用。

func (*Server) RegisterMessageHandler

func (s *Server) RegisterMessageHandler(messageType NetMessageType, handler NetMessageHandler, binder Creator)

RegisterMessageHandler 注册指定消息类型的处理器。 binder 用于创建载荷实例以进行反序列化;如果为 nil 则直接传递原始字节。

func (*Server) SendMessage

func (s *Server) SendMessage(sessionId SessionID, messageType NetMessageType, message MessagePayload) error

SendMessage 向指定会话发送带类型的消息。

func (*Server) SendRawMessage

func (s *Server) SendRawMessage(sessionId SessionID, message []byte) error

SendRawMessage 向指定会话发送原始字节消息。

func (*Server) SessionCount

func (s *Server) SessionCount() int

SessionCount 返回当前活跃会话数。

func (*Server) Start

func (s *Server) Start(ctx context.Context) error

Start 启动 WebSocket 服务器,阻塞直到 ctx 被取消。

func (*Server) Stop

func (s *Server) Stop(ctx context.Context) error

Stop 优雅关闭服务器并清理所有会话。

func (*Server) Use

func (s *Server) Use(middlewares ...Middleware)

Use 注册全局中间件,对所有路由生效。必须在 Start 之前调用。

type Session

type Session struct {
	// contains filtered or unexported fields
}

Session 封装单个 WebSocket 连接的生命周期。

func NewSession

func NewSession(hooks SessionHooks, conn *ws.Conn, vars url.Values) *Session

NewSession 创建一个 WebSocket 会话实例。

func (*Session) Close

func (s *Session) Close()

Close 关闭会话并注销。仅执行一次。

func (*Session) Conn

func (s *Session) Conn() *ws.Conn

Conn 返回底层 WebSocket 连接。

func (*Session) Listen

func (s *Session) Listen()

Listen 启动读写 goroutine。仅执行一次。

func (*Session) Queries

func (s *Session) Queries() url.Values

Queries 返回连接请求的查询参数。

func (*Session) SendMessage

func (s *Session) SendMessage(message []byte)

SendMessage 将消息加入发送队列。

func (*Session) SessionID

func (s *Session) SessionID() SessionID

SessionID 返回会话 ID。

func (*Session) Wait

func (s *Session) Wait()

Wait 等待读写 goroutine 结束。

type SessionHooks

type SessionHooks interface {
	// contains filtered or unexported methods
}

SessionHooks 定义了 Session 与上层 Server 交互所需的回调接口。

type SessionID

type SessionID string

SessionID 唯一标识一个 WebSocket 会话。

type SessionManager

type SessionManager struct {
	// contains filtered or unexported fields
}

SessionManager 管理所有活跃的 WebSocket 会话。

func NewSessionManager

func NewSessionManager(observer SessionObserver) *SessionManager

NewSessionManager 创建一个 SessionManager 实例。

func (*SessionManager) AddSession

func (sm *SessionManager) AddSession(session *Session)

AddSession 添加新会话并通知观察者。

func (*SessionManager) Clean

func (sm *SessionManager) Clean()

Clean 关闭并清空所有会话。

func (*SessionManager) Count

func (sm *SessionManager) Count() int

Count 返回活跃会话数量。

func (*SessionManager) GetSession

func (sm *SessionManager) GetSession(sessionId SessionID) *Session

GetSession 按 ID 获取会话。

func (*SessionManager) RangeSessions

func (sm *SessionManager) RangeSessions(fn func(SessionID, *Session) bool)

RangeSessions 遍历所有会话。

func (*SessionManager) RegisterObserver

func (sm *SessionManager) RegisterObserver(observer SessionObserver)

RegisterObserver 注册会话观察者。

func (*SessionManager) RemoveSession

func (sm *SessionManager) RemoveSession(session *Session)

RemoveSession 移除会话并通知观察者。

type SessionObserver

type SessionObserver interface {
	// OnSessionAdded 在新会话被添加时调用。
	OnSessionAdded(session *Session)
	// OnSessionRemoved 在会话被移除时调用。
	OnSessionRemoved(session *Session)
}

SessionObserver 观察会话的添加和移除事件。

type SocketConnectHandler

type SocketConnectHandler func(sessionId SessionID, queries url.Values, connect bool)

SocketConnectHandler 是连接建立/断开时的回调。 connect 为 true 表示连接建立,false 表示断开。

type SocketRawDataHandler

type SocketRawDataHandler func(sessionId SessionID, buf []byte) error

SocketRawDataHandler 处理从 WebSocket 接收到的原始数据。

type TextNetPacket

type TextNetPacket struct {
	Type    NetMessageType `json:"type" xml:"type"`
	Payload string         `json:"payload" xml:"payload"`
}

TextNetPacket 是文本模式下的消息包格式(JSON)。

func (*TextNetPacket) Marshal

func (m *TextNetPacket) Marshal() ([]byte, error)

Marshal 将 TextNetPacket 序列化为 JSON。

func (*TextNetPacket) Unmarshal

func (m *TextNetPacket) Unmarshal(buf []byte) error

Unmarshal 从 JSON 数据反序列化 TextNetPacket。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL