sdk

package
v1.1.22 Latest Latest
Warning

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

 Go to latest Published: May 19, 2026 License: MIT Imports: 30 Imported by: 3

Documentation

Index

Constants

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

WebSocket客户端常量

Variables

This section is empty.

Functions

func BuildRequestObject added in v1.0.146 

func BuildRequestObject(path string, requestObj interface{}, secret string, encrypted ...bool) ([]byte, error)

BuildRequestObject 构建标准的API请求数据 用于生成符合FreeGo协议的请求JSON数据

协议格式: 

{
  "d": "数据(Base64或AES加密)",
  "t": 时间戳,
  "n": Nonce随机数,
  "p": Plan模式(0=Base64, 1=AES),
  "s": HMAC-SHA256签名
}

构建流程: 1. JSON序列化请求对象 2. 根据encrypted参数选择编码方式 3. 生成时间戳和Nonce 4. 计算HMAC-SHA256签名 5. 构建完整的请求JSON

参数:

  • path: API路径，用于签名计算
  • requestObj: 请求数据对象，会被JSON序列化
  • secret: HMAC签名密钥
  • encrypted: 可选参数，是否使用AES加密 (默认false)

返回值:

  • []byte: 构建好的请求JSON字节数组
  • error: 构建失败时的错误信息

兼容性: - 这是早期版本的构建函数 - 新代码推荐使用PostByPlan01或PostByPlan2方法 - 主要用于向后兼容和简单场景

注意: - 不支持 ML-DSA 外层签名（仅 Plan2 路径使用） - 使用固定的AES-CBC加密 (非GCM模式) - HMAC签名算法略有不同

func ValidProtocolNonce added in v1.1.22 

func ValidProtocolNonce(nonce string) bool

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

Types

type AuthToken added in v1.0.98 

type AuthToken struct {
	Token   string `json:"token"`   // JWT认证令牌
	Secret  string `json:"secret"`  // 动态生成的AES密钥(Base64编码)
	Expired int64  `json:"expired"` // 令牌过期时间戳(Unix秒)
}

AuthToken 认证令牌结构体 包含JWT token、动态secret和过期时间

func (AuthToken) MarshalEasyJSON added in v1.1.12 

func (v AuthToken) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (AuthToken) MarshalJSON added in v1.1.12 

func (v AuthToken) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*AuthToken) UnmarshalEasyJSON added in v1.1.12 

func (v *AuthToken) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*AuthToken) UnmarshalJSON added in v1.1.12 

func (v *AuthToken) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type ClientEventHandler added in v1.1.12 

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

ClientEventHandler gws 客户端事件处理器

func (*ClientEventHandler) OnClose added in v1.1.12 

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

func (*ClientEventHandler) OnMessage added in v1.1.12 

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

func (*ClientEventHandler) OnOpen added in v1.1.12 

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

func (*ClientEventHandler) OnPing added in v1.1.12 

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

func (*ClientEventHandler) OnPong added in v1.1.12 

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

type HttpSDK 

type HttpSDK struct {
	Domain     string // API域名 (如: https://api.example.com)
	AuthDomain string // 认证域名 (可选，用于/key和/login接口)
	KeyPath    string // 公钥获取路径 (默认: /key)
	LoginPath  string // 登录路径 (默认: /login)

	ClientNo int64 // 客户端编号
	// contains filtered or unexported fields
}

HttpSDK FreeGo HTTP客户端SDK Plan0/1：JWT + HMAC（可选 AES-GCM）；Plan2：ML-KEM + ML-DSA + AES-GCM

使用模式: - PostByPlan2: Plan2 匿名访问（ML-KEM + ML-DSA，须 SetMLDSA87Object） - PostByPlan01: Plan0/1 登录后访问（JWT + HMAC，无外层 Valid）

func NewHttpSDK added in v1.1.0 

func NewHttpSDK() *HttpSDK

NewHttpSDK 创建新的HttpSDK实例并设置默认值 提供便捷的构造函数，避免手动初始化所有字段

默认值: - KeyPath: "/key" - LoginPath: "/login" - timeout: 120秒 - language: "zh-CN"

返回值:

  • *HttpSDK: 初始化的HttpSDK实例

使用示例: 

sdk := NewHttpSDK()
sdk.Domain = "https://api.example.com"
sdk.ClientNo = 12345

func (*HttpSDK) AuthObject added in v1.0.98 

func (s *HttpSDK) AuthObject(object func() (interface{}, error))

AuthObject 设置登录认证对象 用于存储用户名、密码等登录凭据 自动登录时会使用此对象调用登录接口

参数:

  • object: 认证对象，包含用户名密码等信息

注意: 请使用指针对象以避免数据拷贝

func (*HttpSDK) AuthToken added in v1.0.98 

func (s *HttpSDK) AuthToken(object AuthToken)

AuthToken 设置JWT认证令牌 设置登录成功后获得的令牌，用于后续API调用的身份认证

参数:

  • object: AuthToken结构体，包含token、secret、expired字段

安全特性: - Token: JWT令牌，用于身份验证 - Secret: 动态生成的AES密钥，用于数据加密 - Expired: 令牌过期时间

注意: 此方法会覆盖之前设置的令牌

func (*HttpSDK) GetAuth added in v1.1.3 

func (s *HttpSDK) GetAuth() AuthToken

func (*HttpSDK) GetPublicKey 

func (s *HttpSDK) GetPublicKey() (*crypto.MLKEM1024Object, *node.PublicKey, crypto.Cipher, error)

GetPublicKey 获取服务端 ML-KEM 封装公钥并执行客户端封装（Plan2 /key）。

func (*HttpSDK) PostByPlan01 added in v1.1.22 

func (s *HttpSDK) PostByPlan01(path string, requestObj, responseObj interface{}, encrypted bool) error

PostByPlan01 通过 JWT 认证发送 POST 请求（Plan0/1，无外层 Valid 签名） 适用于登录后的业务 API 调用，使用令牌进行身份认证

安全协议栈: 1. TLS 1.2+ (网络层加密) 2. JWT令牌认证 (身份验证) 3. AES-GCM或Base64 (数据加密，可选) 4. HMAC-SHA256 (数据完整性)

执行流程: 1. 检查认证状态，自动登录 (如果需要) 2. 获取认证令牌 (Token + Secret) 3. 根据encrypted参数选择加密方式 4. 生成HMAC-SHA256签名 5. 发送HTTP请求 (Authorization头) 6. 验证响应HMAC签名 7. 解密响应数据

参数:

  • path: API路径，如"/user/info"
  • requestObj: 请求数据对象
  • responseObj: 响应数据对象指针
  • encrypted: 是否使用AES-GCM加密 (true=Plan1, false=Plan0)

返回值:

  • error: 请求失败时的错误信息

安全特性: - JWT令牌认证: 身份验证和授权 - 动态Secret: 每次登录生成新的AES密钥 - 可选加密: 支持明文(Base64)和加密传输 - 外层 Valid 签名仅 Plan2（PostByPlan2）使用 ML-DSA

使用场景: - 用户登录后的业务API调用 - 需要身份认证的接口 - 中等安全要求的场景

性能特点: - 比 PostByPlan2（Plan2 / ML-KEM 协商）更快：复用令牌，无每请求协商 - 支持高并发 (令牌复用) - 适合高频API调用

注意: - 需要预先登录或设置有效的authToken - 会自动处理令牌过期和续期

func (*HttpSDK) PostByPlan2 added in v1.1.22 

func (s *HttpSDK) PostByPlan2(path string, requestObj, responseObj interface{}) error

PostByPlan2 通过 ML-KEM + HKDF + AES-GCM + ML-DSA 发送 POST（Plan2，匿名场景）

安全协议栈 (从下到上): 1. TLS 1.2+（传输层，由部署保证） 2. ML-KEM 共享秘密 + HKDF → 会话密钥，再 AES-256-GCM 3. HMAC-SHA256 完整性 4. 双向 ML-DSA

执行流程: 1. GetPublicKey：服务端 ML-KEM 封装公钥 + 客户端封装 2. ML-KEM 得到共享字节 3. HKDF 派生对称密钥 4. AES-GCM 加密请求体 5. HMAC-SHA256 6. ML-DSA 签名 7. 发送请求 8. 校验响应 HMAC / ML-DSA 9. AES-GCM 解密响应

参数:

  • path: API路径，如"/user/info"
  • requestObj: 请求数据对象 (会自动JSON序列化)
  • responseObj: 响应数据对象指针 (会自动JSON反序列化)

返回值:

  • error: 请求失败时的错误信息

安全特性: - 前向保密性 (PFS): 每次请求使用新密钥 - 完美前向保密: ML-KEM 每次协商独立共享秘密 - 双向认证: 客户端和服务端相互验证身份 - 防重放攻击: 时间戳 + Nonce机制

使用场景: - 金融交易API - 敏感数据传输 - 匿名访问但需要高安全性的接口

注意: - 每次调用都会执行完整的密钥协商流程 - 适合低频但高安全要求的API调用

func (*HttpSDK) ResetAuth added in v1.1.0 

func (s *HttpSDK) ResetAuth() error

func (*HttpSDK) SetClientNo added in v1.1.0 

func (s *HttpSDK) SetClientNo(usr int64)

func (*HttpSDK) SetLanguage added in v1.0.107 

func (s *HttpSDK) SetLanguage(language string)

SetLanguage 设置HTTP请求语言头 用于服务端国际化支持

参数:

  • language: 语言代码，如"zh-CN"、"en-US"等

HTTP头: 设置为"Language: {language}"

func (*HttpSDK) SetMLDSA87Object added in v1.1.22 

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

SetMLDSA87Object 配置 Plan2 客户端身份：本端 ML-DSA-87 私钥 + 服务端 ML-DSA 公钥（与 HttpNode.AddCipher 镜像）。

func (*HttpSDK) SetTimeout added in v1.0.101 

func (s *HttpSDK) SetTimeout(timeout int64)

SetTimeout 设置HTTP请求超时时间 控制单个API请求的最大等待时间

参数:

  • timeout: 超时时间(秒)，0表示使用默认120秒

默认值: 120秒 建议值: 根据网络状况设置，如30-300秒

type MessageHandler added in v1.1.0 

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

MessageHandler 消息处理器接口

type RPC added in v1.1.0 

type RPC struct {
	Address string
	SSL     bool
	// contains filtered or unexported fields
}

RPC FreeGo gRPC 客户端 SDK AddCipher：*crypto.MLDSA87Object（CreateMLDSA87WithBase64：本端私钥 + 对端公钥）。 当前仅支持明文 P=0：s = SHA256(规范字段)，e = ML-DSA.Sign(本端私钥, SHA256(规范字段))；暂不支持 P=1。

func NewRPC added in v1.1.0 

func NewRPC(address string) *RPC

func (*RPC) AddCipher added in v1.1.0 

func (r *RPC) AddCipher(usr int64, cipher crypto.Cipher) *RPC

AddCipher 注册 *crypto.MLDSA87Object。

func (*RPC) AddLocalCache added in v1.1.0 

func (r *RPC) AddLocalCache(_ cache.Cache) *RPC

AddLocalCache 明文 RPCX 当前不在客户端使用本地缓存；保留链式 API。

func (*RPC) Call added in v1.1.0 

func (r *RPC) Call(router string, requestObj, responseObj proto.Message, encrypted bool) error

func (*RPC) CallWithTimeout added in v1.1.0 

func (r *RPC) CallWithTimeout(router string, requestObj, responseObj proto.Message, encrypted bool, timeout int64) error

func (*RPC) Close added in v1.1.0 

func (r *RPC) Close() error

func (*RPC) Connect added in v1.1.0 

func (r *RPC) Connect() error

func (*RPC) SetClientNo added in v1.1.0 

func (r *RPC) SetClientNo(usr int64) *RPC

func (*RPC) SetLanguage added in v1.1.0 

func (r *RPC) SetLanguage(language string) *RPC

func (*RPC) SetSSL added in v1.1.0 

func (r *RPC) SetSSL(ssl bool) *RPC

func (*RPC) SetTimeout added in v1.1.0 

func (r *RPC) SetTimeout(timeout int64) *RPC

type SocketSDK added in v1.1.0 

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

func NewSocketSDK added in v1.1.0 

func NewSocketSDK(domain string) *SocketSDK

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

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

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

返回值:

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

使用示例: 

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

func (*SocketSDK) AuthObject added in v1.1.0 

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

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

func (*SocketSDK) AuthToken added in v1.1.0 

func (s *SocketSDK) AuthToken(object AuthToken)

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

func (*SocketSDK) Close added in v1.1.0 

func (s *SocketSDK) Close()

Close 主动关闭整个 SDK（停止所有重连和连接），并等待所有 goroutine 退出

func (*SocketSDK) ConnectWebSocket added in v1.1.0 

func (s *SocketSDK) ConnectWebSocket() error

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

func (*SocketSDK) ConnectWebSocketWithRawAuth added in v1.1.12 

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

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

func (*SocketSDK) DisableReconnect added in v1.1.0 

func (s *SocketSDK) DisableReconnect()

DisableReconnect 禁用自动重连

func (*SocketSDK) DisconnectWebSocket added in v1.1.0 

func (s *SocketSDK) DisconnectWebSocket()

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

func (*SocketSDK) EnableReconnect added in v1.1.0 

func (s *SocketSDK) EnableReconnect()

func (*SocketSDK) ForceReconnect added in v1.1.0 

func (s *SocketSDK) ForceReconnect() error

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

func (*SocketSDK) GetAuth added in v1.1.12 

func (s *SocketSDK) GetAuth() AuthToken

func (*SocketSDK) GetClientNo added in v1.1.14 

func (s *SocketSDK) GetClientNo() int64

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

func (*SocketSDK) GetDomain added in v1.1.14 

func (s *SocketSDK) GetDomain() string

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

func (*SocketSDK) GetReconnectStatus added in v1.1.0 

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

func (*SocketSDK) GetSSL added in v1.1.14 

func (s *SocketSDK) GetSSL() bool

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

func (*SocketSDK) GetSubscriptions added in v1.1.0 

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

GetSubscriptions 获取所有活跃的订阅

func (*SocketSDK) GetWebSocketPlan2Auth added in v1.1.12 

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

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

func (*SocketSDK) IsWebSocketConnected added in v1.1.0 

func (s *SocketSDK) IsWebSocketConnected() bool

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

func (*SocketSDK) LoginByWebSocketPlan2 added in v1.1.12 

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

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

func (*SocketSDK) LoginByWebSocketPlan2Auto added in v1.1.12 

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

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

func (*SocketSDK) SendWebSocketMessage added in v1.1.0 

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

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

func (*SocketSDK) SendWebSocketPlan2Message added in v1.1.12 

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

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

func (*SocketSDK) SendWebSocketRawBody added in v1.1.12 

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

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

func (*SocketSDK) SetBroadcastKey added in v1.1.5 

func (s *SocketSDK) SetBroadcastKey(key string)

SetBroadcastKey 广播数据密钥

func (*SocketSDK) SetClientNo added in v1.1.0 

func (s *SocketSDK) SetClientNo(clientNo int64)

func (*SocketSDK) SetDomain added in v1.1.14 

func (s *SocketSDK) SetDomain(domain string)

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

func (*SocketSDK) SetHealthPing added in v1.1.0 

func (s *SocketSDK) SetHealthPing(t int)

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

func (*SocketSDK) SetLanguage added in v1.1.0 

func (s *SocketSDK) SetLanguage(language string)

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

func (*SocketSDK) SetMLDSA87Object added in v1.1.22 

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

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

func (*SocketSDK) SetPushMessageCallback added in v1.1.0 

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

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

func (*SocketSDK) SetRawAuthorization added in v1.1.12 

func (s *SocketSDK) SetRawAuthorization(auth string)

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

func (*SocketSDK) SetReconnectConfig added in v1.1.0 

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

func (*SocketSDK) SetSSL added in v1.1.14 

func (s *SocketSDK) SetSSL(ssl bool)

func (*SocketSDK) SetTimeout added in v1.1.0 

func (s *SocketSDK) SetTimeout(timeout int64)

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

func (*SocketSDK) SetTokenExpiredCallback added in v1.1.0 

func (s *SocketSDK) SetTokenExpiredCallback(callback func())

func (*SocketSDK) SetWebSocketPath added in v1.1.12 

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

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

func (*SocketSDK) SubscribeMessage added in v1.1.0 

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

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

func (*SocketSDK) UnsubscribeMessage added in v1.1.0 

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

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

type Subscription added in v1.1.0 

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.