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
- func RegisterServerMessageHandler[T any](srv *Server, messageType NetMessageType, handler func(SessionID, *T) error)
- type BinaryNetPacket
- type Creator
- type MessageHandlerData
- type MessagePayload
- type Middleware
- type NetMessageHandler
- type NetMessageHandlerMap
- type NetMessageType
- type NetPacketMarshaler
- type NetPacketUnmarshaler
- type Option
- func WithChannelBufferSize(size int) Option
- func WithCheckOrigin(domain string) Option
- func WithCodec(name string) Option
- func WithEnableCompression(enable bool) Option
- func WithHandshakeTimeout(timeout time.Duration) Option
- func WithInjectTokenToQuery(enable bool, tokenKey string) Option
- func WithMessageMarshaler(m NetPacketMarshaler) Option
- func WithMessageUnmarshaler(m NetPacketUnmarshaler) Option
- func WithMiddleware(middlewares ...Middleware) Option
- func WithPath(path string) Option
- func WithPayloadType(payloadType PayloadType) Option
- func WithReadBufferSize(size int) Option
- func WithSocketConnectHandler(h SocketConnectHandler) Option
- func WithSocketRawDataHandler(h SocketRawDataHandler) Option
- func WithTLS(certFile, keyFile string) Option
- func WithTLSConfig(c *tls.Config) Option
- func WithWriteBufferSize(size int) Option
- type PayloadType
- type Server
- func (s *Server) Addr() string
- func (s *Server) Broadcast(messageType NetMessageType, message MessagePayload)
- func (s *Server) DeregisterMessageHandler(messageType NetMessageType)
- func (s *Server) Endpoint() string
- func (s *Server) GetMessageHandler(messageType NetMessageType) *MessageHandlerData
- func (s *Server) HandleFunc(path string, h http.HandlerFunc)
- func (s *Server) OnSessionAdded(session *Session)
- func (s *Server) OnSessionRemoved(session *Session)
- func (s *Server) RegisterMessageHandler(messageType NetMessageType, handler NetMessageHandler, binder Creator)
- func (s *Server) SendMessage(sessionId SessionID, messageType NetMessageType, message MessagePayload) error
- func (s *Server) SendRawMessage(sessionId SessionID, message []byte) error
- func (s *Server) SessionCount() int
- func (s *Server) Start(ctx context.Context) error
- func (s *Server) Stop(ctx context.Context) error
- func (s *Server) Use(middlewares ...Middleware)
- type Session
- type SessionHooks
- type SessionID
- type SessionManager
- func (sm *SessionManager) AddSession(session *Session)
- func (sm *SessionManager) Clean()
- func (sm *SessionManager) Count() int
- func (sm *SessionManager) GetSession(sessionId SessionID) *Session
- func (sm *SessionManager) RangeSessions(fn func(SessionID, *Session) bool)
- func (sm *SessionManager) RegisterObserver(observer SessionObserver)
- func (sm *SessionManager) RemoveSession(session *Session)
- type SessionObserver
- type SocketConnectHandler
- type SocketRawDataHandler
- type TextNetPacket
Constants ¶
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 MessageHandlerData ¶
type MessageHandlerData struct {
Handler NetMessageHandler
Creator Creator
}
MessageHandlerData 包装了一个消息处理器及其载荷创建器。
func (*MessageHandlerData) Create ¶
func (h *MessageHandlerData) Create() any
Create 调用 Creator 创建载荷实例。如果 Creator 为 nil 则返回 nil。
type Middleware ¶
Middleware 是标准 HTTP 中间件类型。 使用类型别名使得 transport/http/middleware 下的中间件可以直接复用。
type NetMessageHandler ¶
type NetMessageHandler func(SessionID, MessagePayload) error
NetMessageHandler 处理特定类型的 WebSocket 消息。
type NetMessageHandlerMap ¶
type NetMessageHandlerMap map[NetMessageType]*MessageHandlerData
NetMessageHandlerMap 将消息类型映射到其处理器数据。
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 ¶
WithChannelBufferSize 设置每个会话发送通道的缓冲大小。
func WithCheckOrigin ¶
WithCheckOrigin 设置 Origin 检查函数,仅允许指定域名的连接。
func WithEnableCompression ¶
WithEnableCompression 启用或禁用 WebSocket 压缩。
func WithHandshakeTimeout ¶
WithHandshakeTimeout 设置 WebSocket 握手超时时间。
func WithInjectTokenToQuery ¶
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 WithPayloadType ¶
func WithPayloadType(payloadType PayloadType) Option
WithPayloadType 设置消息载荷类型(二进制或文本)。
func WithReadBufferSize ¶
WithReadBufferSize 设置 WebSocket 读取缓冲区大小。
func WithSocketConnectHandler ¶
func WithSocketConnectHandler(h SocketConnectHandler) Option
WithSocketConnectHandler 设置连接建立/断开时的回调函数。
func WithSocketRawDataHandler ¶
func WithSocketRawDataHandler(h SocketRawDataHandler) Option
WithSocketRawDataHandler 设置自定义的原始数据处理函数。 设置后将绕过默认的类型分发逻辑。
func WithTLSConfig ¶
WithTLSConfig 设置 TLS 配置,启用 WSS(WebSocket Secure)。
func WithWriteBufferSize ¶
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 (*Server) Broadcast ¶
func (s *Server) Broadcast(messageType NetMessageType, message MessagePayload)
Broadcast 向所有活跃会话广播消息。
func (*Server) DeregisterMessageHandler ¶
func (s *Server) DeregisterMessageHandler(messageType NetMessageType)
DeregisterMessageHandler 注销指定消息类型的处理器。
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 ¶
OnSessionAdded 在新会话建立时调用。
func (*Server) OnSessionRemoved ¶
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 ¶
SendRawMessage 向指定会话发送原始字节消息。
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 ¶
NewSession 创建一个 WebSocket 会话实例。
type SessionHooks ¶
type SessionHooks interface {
// contains filtered or unexported methods
}
SessionHooks 定义了 Session 与上层 Server 交互所需的回调接口。
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) 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 ¶
SocketConnectHandler 是连接建立/断开时的回调。 connect 为 true 表示连接建立,false 表示断开。
type SocketRawDataHandler ¶
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。