ws

package
v1.1.34 Latest Latest
Warning

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

 Go to latest Published: Aug 18, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DefaultWsRoute = "/ws" // 默认WebSocket路由路径
)

WebSocket客户端常量

Variables

This section is empty.

Functions

func ValidProtocolNonce 

func ValidProtocolNonce(nonce string) bool

ValidProtocolNonce 供测试与外部校验：Nonce 解码后须为 32 字节。

Types

type ClientEventHandler 

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

ClientEventHandler gws 客户端事件处理器

func (*ClientEventHandler) OnClose 

func (h *ClientEventHandler) OnClose(socket *gws.Conn, err error)

func (*ClientEventHandler) OnMessage 

func (h *ClientEventHandler) OnMessage(socket *gws.Conn, message *gws.Message)

func (*ClientEventHandler) OnOpen 

func (h *ClientEventHandler) OnOpen(socket *gws.Conn)

func (*ClientEventHandler) OnPing 

func (h *ClientEventHandler) OnPing(socket *gws.Conn, payload []byte)

func (*ClientEventHandler) OnPong 

func (h *ClientEventHandler) OnPong(socket *gws.Conn, payload []byte)

type MessageHandler 

type MessageHandler interface {
	HandleMessage(message *wire.JsonResp) error
}

MessageHandler 消息处理器接口

type SDK 

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

func New 

func New(domain string) *SDK

NewSocketSDK 创建新的WebSocket SDK实例并设置默认值

domain: API域名，如"api.example.com"

默认值: - timeout: 120秒 - maxReconnectAttempts: -1（无限重连，可由 SetReconnectConfig 改为有限次数） - reconnectInterval: 1秒 - maxReconnectInterval: 8秒 - HealthPing: 15秒（建议 10–15，内部不超过 15）

返回值:

  • *SDK: 初始化的WebSocket SDK实例

使用示例: 

sdk := NewSocketSDK("api.example.com")
sdk.AuthToken(AuthToken{...})
sdk.SetClientNo(12345)

func (*SDK) AuthObject 

func (s *SDK) AuthObject(object interface{})

AuthObject 设置WebSocket客户端的登录认证对象 用于存储用户名、密码等登录凭据，自动登录时会使用此对象调用登录接口 object: 认证对象，包含用户名密码等信息，请使用指针对象避免数据拷贝

func (*SDK) AuthToken 

func (s *SDK) AuthToken(object wire.AuthToken)

AuthToken 设置WebSocket客户端的JWT认证令牌 设置登录成功后获得的令牌，用于后续WebSocket消息的身份认证 object: AuthToken结构体，包含token、secret、expired字段

func (*SDK) Close 

func (s *SDK) Close()

Close 主动关闭整个 SDK（停止所有重连和连接），并等待所有 goroutine 退出。 必须先 rootCancel，再 wg.Wait：tokenMonitor 只监听 rootCtx.Done()， 若先 Wait 再 Cancel 会死锁，调用方（例如 admin 重连 job）会永久卡住。

func (*SDK) ConnectWebSocket 

func (s *SDK) ConnectWebSocket() error

ConnectWebSocket 建立WebSocket连接并启动相关服务（默认 /ws，可通过 SetWebSocketPath 覆盖）。 返回: 连接成功返回nil，否则返回连接失败的错误信息

func (*SDK) ConnectWebSocketWithRawAuth 

func (s *SDK) ConnectWebSocketWithRawAuth(path, authHeader string) error

ConnectWebSocketWithRawAuth 使用自定义 Authorization 头建立连接（适合 plan2 首连）。

func (*SDK) DisableReconnect 

func (s *SDK) DisableReconnect()

DisableReconnect 禁用自动重连

func (*SDK) DisconnectWebSocket 

func (s *SDK) DisconnectWebSocket()

DisconnectWebSocket 断开WebSocket连接，停止所有相关服务

func (*SDK) EnableReconnect 

func (s *SDK) EnableReconnect()

func (*SDK) ForceReconnect 

func (s *SDK) ForceReconnect() error

ForceReconnect 强制重新连接WebSocket，适用于连接异常恢复 返回: 重连成功返回nil，否则返回重连失败的错误信息

func (*SDK) GetAuth 

func (s *SDK) GetAuth() wire.AuthToken

func (*SDK) GetClientNo 

func (s *SDK) GetClientNo() int64

GetClientNo 返回当前客户端编号（只读）。

func (*SDK) GetDomain 

func (s *SDK) GetDomain() string

GetDomain 返回当前配置的域名/host（只读）。

func (*SDK) GetReconnectStatus 

func (s *SDK) GetReconnectStatus() (enabled bool, attempts int, maxAttempts int, reconnecting bool, nextReconnectTime time.Time)

func (*SDK) GetSSL 

func (s *SDK) GetSSL() bool

GetSSL 返回是否使用 wss（只读）。

func (*SDK) GetSubscriptions 

func (s *SDK) GetSubscriptions() map[string]*Subscription

GetSubscriptions 获取所有活跃的订阅

func (*SDK) GetWebSocketPlan2Auth 

func (s *SDK) GetWebSocketPlan2Auth(keyRouter string, timeout int64) (string, []byte, error)

GetWebSocketPlan2Auth 通过 /key 路由完成 key 协商，返回用于重连的 raw Authorization 与共享密钥。

func (*SDK) IsWebSocketConnected 

func (s *SDK) IsWebSocketConnected() bool

IsWebSocketConnected 检查WebSocket连接是否处于活跃状态 返回: true表示连接正常，false表示连接已断开

func (*SDK) LoginByWebSocketPlan2 

func (s *SDK) LoginByWebSocketPlan2(loginRouter string, requestObj interface{}, sharedKey []byte, timeout int64) error

LoginByWebSocketPlan2 通过 WebSocket plan2 登录，并自动写入 AuthToken。

func (*SDK) LoginByWebSocketPlan2Auto 

func (s *SDK) LoginByWebSocketPlan2Auto(keyRouter, loginRouter string, requestObj, responseObj interface{}, timeout int64) error

LoginByWebSocketPlan2Auto 自动完成 WS plan2 的 key + login 全流程，并将登录响应写入 responseObj。 连接路径默认使用 SDK 当前路径配置（默认 /ws，可通过 SetWebSocketPath 覆盖）。

func (*SDK) SendWebSocketMessage 

func (s *SDK) SendWebSocketMessage(router string, requestObj, responseObj interface{}, waitResponse, encryptRequest bool, timeout int64) error

SendWebSocketMessage 发送WebSocket业务消息并可选等待响应 router: 业务路由标识符，用于服务端路由分发 requestObj: 请求数据对象 responseObj: 响应数据对象，用于接收服务端返回数据（当waitResponse=true时） waitResponse: 是否等待服务端响应 encryptRequest: 是否对请求数据进行加密 timeout: 等待响应的超时时间(秒) 返回: 发送成功返回nil，否则返回发送失败的错误信息

func (*SDK) SendWebSocketPlan2Message 

func (s *SDK) SendWebSocketPlan2Message(router string, requestObj, responseObj interface{}, sharedKey []byte, timeout int64) error

SendWebSocketPlan2Message 发送 plan2 消息（AES-GCM + HMAC + ML-DSA），用于 key/login 等流程。

func (*SDK) SendWebSocketRawBody 

func (s *SDK) SendWebSocketRawBody(body *wire.JsonBody, waitResponse bool, timeout int64) (*wire.JsonResp, error)

SendWebSocketRawBody 直接发送已构造好的 JsonBody（用于 plan2/key-login 等自定义流程）。

func (*SDK) SetBroadcastKey 

func (s *SDK) SetBroadcastKey(key string)

SetBroadcastKey 广播数据密钥

func (*SDK) SetClientNo 

func (s *SDK) SetClientNo(clientNo int64)

func (*SDK) SetDisconnectCallback added in v1.1.34 

func (s *SDK) SetDisconnectCallback(callback func())

SetDisconnectCallback 注册 WebSocket 断开回调（网络断开、读失败等；不含 Plan2 key/login）。

func (*SDK) SetDomain 

func (s *SDK) SetDomain(domain string)

SetDomain 设置 WebSocket 连接的域名或 host:port（如 api.example.com 或 api.example.com:443）。

func (*SDK) SetHealthPing 

func (s *SDK) SetHealthPing(t int)

SetHealthPing 设置心跳间隔（秒）。建议 10–15 秒，与服务端读超时策略匹配；内部限制最大 15 秒，超过则按 15 秒生效。

func (*SDK) SetLanguage 

func (s *SDK) SetLanguage(language string)

SetLanguage 设置WebSocket请求的语言标识 language: 语言代码，如"zh-CN"、"en-US"，用于服务端国际化支持

func (*SDK) SetMLDSA87Object 

func (s *SDK) SetMLDSA87Object(usr int64, prkB64, peerPubB64 string) error

SetMLDSA87Object 配置 Plan2 WebSocket 客户端身份（与服务端 WsServer.AddCipher 镜像）。

func (*SDK) SetPushMessageCallback 

func (s *SDK) SetPushMessageCallback(callback func(router string, data []byte))

SetPushMessageCallback 设置服务端主动推送消息的回调函数

func (*SDK) SetRawAuthorization 

func (s *SDK) SetRawAuthorization(auth string)

SetRawAuthorization 设置连接时直接使用的 Authorization 头（如 plan2 场景）。

func (*SDK) SetReconnectConfig 

func (s *SDK) SetReconnectConfig(enabled bool, maxAttempts int, initialInterval, maxInterval time.Duration)

func (*SDK) SetSSL 

func (s *SDK) SetSSL(ssl bool)

func (*SDK) SetTimeout 

func (s *SDK) SetTimeout(timeout int64)

SetTimeout 设置WebSocket请求的超时时间 timeout: 超时时间(秒)，控制WebSocket消息发送和等待响应的最大时间

func (*SDK) SetTokenExpiredCallback 

func (s *SDK) SetTokenExpiredCallback(callback func())

func (*SDK) SetWebSocketPath 

func (s *SDK) SetWebSocketPath(path string) error

SetWebSocketPath 设置连接路径。默认固定 /ws，若要覆盖需显式调用本方法。

func (*SDK) SubscribeMessage 

func (s *SDK) SubscribeMessage(router string, handler MessageHandler) (subscriptionID string, err error)

SubscribeMessage 订阅指定路由的消息 SubscribeMessage 订阅指定路由的消息推送 router: 要订阅的路由标识符 handler: 消息处理函数，当接收到对应路由的消息时会被调用 返回: 订阅ID和可能的错误信息

func (*SDK) UnsubscribeMessage 

func (s *SDK) UnsubscribeMessage(router string) error

UnsubscribeMessage 取消消息订阅 UnsubscribeMessage 取消订阅指定路由的消息推送 router: 要取消订阅的路由标识符 返回: 取消订阅成功返回nil，否则返回错误信息

type Subscription 

type Subscription struct {
	ID      string
	Router  string
	Handler MessageHandler
	// contains filtered or unexported fields
}

Subscription 订阅信息

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.