WebSocket Package (pkg/websocket)

主要特色

基礎使用

package main
import (
	"context"
	"log"
	hypcontext "github.com/maoxiaoyue/hypgo/pkg/context"
	"github.com/maoxiaoyue/hypgo/pkg/logger"
	"github.com/maoxiaoyue/hypgo/pkg/router"
	"github.com/maoxiaoyue/hypgo/pkg/websocket"
)
func main() {
	r := router.New()
	l := logger.NewLogger()
	// 1. 建立 Hub 來管理所有的連線
	hub := websocket.NewHub(l, websocket.DefaultConfig)
	// 2. 定義各種事件回呼 (Callbacks)
	hub.SetCallbacks(
		func(client *websocket.Client) {
			log.Printf("新連線加入!ID: %s, Codec: %s", client.ID, client.Codec().Name())
		},
		func(client *websocket.Client) {
			log.Printf("連線已中斷!ID: %s", client.ID)
		},
		func(client *websocket.Client, msg *websocket.Message) {
			log.Printf("收到訊息!Type: %s, Data: %s", msg.Type, string(msg.Data))
		},
	)
	// 3. 確保背景開始執行 Hub 的訊息分派與死連線清理機制
	ctx := context.Background()
	go hub.Run(ctx)
	// 4. 定義路由與 WebSocket 連線升級入口
	r.GET("/ws", func(c *hypcontext.Context) {
		hub.ServeHTTP(c)
	})
	// 啟動伺服器...
}

四協議支援 (JSON / Protobuf / FlatBuffers / MessagePack)

// JavaScript 客戶端 — JSON(預設)
const ws = new WebSocket("ws://localhost:8080/ws", ["json"]);
// Protobuf(二進制,最小載荷)
const ws = new WebSocket("ws://localhost:8080/ws", ["protobuf"]);
// FlatBuffers(零拷貝二進制)
const ws = new WebSocket("ws://localhost:8080/ws", ["flatbuffers"]);
// MessagePack(緊湊二進制)
const ws = new WebSocket("ws://localhost:8080/ws", ["msgpack"]);
// 不指定子協議時自動使用 JSON(向後兼容)
const ws = new WebSocket("ws://localhost:8080/ws");

// Go 客戶端 — 使用 Protobuf 子協議
dialer := websocket.Dialer{
	Subprotocols: []string{"protobuf"},
}
conn, _, err := dialer.Dial("ws://localhost:8080/ws", nil)

Codec 介面

type Codec interface {
	Name() string // "json", "protobuf", "flatbuffers", "msgpack"
	Index() int // 穩定唯一索引(用於快取鍵)
	Marshal(msg *Message) ([]byte, error) // 序列化
	Unmarshal(data []byte, msg *Message) error // 反序列化
	WebSocketMessageType() int // TextMessage (JSON) 或 BinaryMessage (其他)
}

hub.SetCallbacks(
	func(client *websocket.Client) {
		codec := client.Codec()
		log.Printf("客戶端 %s 使用 %s 編碼(索引 %d)", client.ID, codec.Name(), codec.Index())
	},
	nil, nil,
)

ControlDecoder 可選介面

type ControlDecoder interface {
	DecodeChannel(data []byte) string
	DecodeRoomID(data []byte) string
}

自訂子協議配置

config := websocket.DefaultConfig
config.Subprotocols = []string{"json"} // 僅允許 JSON
// 或
config.Subprotocols = []string{"json", "protobuf", "flatbuffers", "msgpack"} // 預設:四者皆支援
hub := websocket.NewHub(l, config)

Protobuf 訊息格式

message WsMessage {
 string type = 1; // 訊息類型
 string channel = 2; // 頻道名稱
 bytes data = 3; // 不透明載荷
 int64 timestamp = 4; // 伺服器時間戳
 string client_id = 5; // 客戶端標識
}

message ChannelRequest { string channel = 1; }
message RoomRequest { string room_id = 1; }

安全層 (AES-256-GCM + HMAC-SHA256)

配置

config := websocket.DefaultConfig
config.Security = &websocket.SecurityConfig{
	AESKey: myAES256Key, // 32 bytes,nil = 不加密
	HMACKey: myHMACKey, // 任意長度,nil = 不簽名
	SignThenEncrypt: true, // true(預設): 先簽名再加密
}
hub := websocket.NewHub(l, config)

安全管線

出站:codec.Marshal → HMAC-Sign → AES-Encrypt → wire
入站:wire → AES-Decrypt → HMAC-Verify → codec.Unmarshal

出站:codec.Marshal → AES-Encrypt → HMAC-Sign → wire
入站:wire → HMAC-Verify → AES-Decrypt → codec.Unmarshal

AES-256-GCM 加密

HMAC-SHA256 簽名

Per-client 金鑰覆寫

hub.SetCallbacks(
	func(client *websocket.Client) {
		// 根據認證結果設定客戶端專屬金鑰
		clientAESKey := deriveKeyForUser(client.ID)
		client.SetEncryptionKey(clientAESKey)
		clientHMACKey := deriveHMACKeyForUser(client.ID)
		client.SetHMACKey(clientHMACKey)
	},
	nil, nil,
)

獨立使用加解密函式

key := make([]byte, 32) // AES-256 金鑰
plaintext := []byte("sensitive data")
// 加密
ciphertext, err := websocket.Encrypt(plaintext, key)
// 解密
decrypted, err := websocket.Decrypt(ciphertext, key)
// 簽名
hmacKey := []byte("my-hmac-secret")
signed := websocket.Sign(plaintext, hmacKey)
// 驗證
verified, err := websocket.Verify(signed, hmacKey)

permessage-deflate 壓縮

配置

config := websocket.DefaultConfig
config.Compression = &websocket.CompressionConfig{
	Enabled: true, // 預設 true
	Level: 6, // flate 壓縮等級 1-9,0=預設
}
hub := websocket.NewHub(l, config)

WSS/TLS 支援

在 HypGo 框架中

獨立模式

config := websocket.DefaultConfig
config.TLS = &websocket.TLSConfig{
	CertFile: "/path/to/cert.pem",
	KeyFile: "/path/to/key.pem",
}
// 或提供預配置的 tls.Config
config.TLS = &websocket.TLSConfig{
	TLSConfig: myTLSConfig,
}
hub := websocket.NewHub(l, config)
handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	// ... 處理升級
})
// 啟動 WSS 伺服器
err := hub.ListenAndServeTLS(":8443", handler)

頻道與房間管理 (Channel & Rooms)

// 讓某個 Client 加入特定頻道
client.Subscribe("news")
// 針對某個頻道內的所有訂閱者推送結構化 Message(支援跨協議 + 安全管線)
msg := websocket.AcquireMessage()
msg.Type = "message"
msg.Channel = "news"
msg.Data = []byte(`{"headline": "Breaking News!"}`)
hub.PublishToChannel("news", msg)
msg.Release()
// 或使用原始位元組的向後兼容 API
hub.PublishToChannelRaw("news", []byte(`{"headline": "Breaking News!"}`))
// 加入遊戲或聊天室用的 Room
client.JoinRoom("room_101")
// 向全域廣播
hub.Broadcast([]byte(`{"event": "server_restart"}`))
// 發送給特定客戶端(自動使用該客戶端的 codec + 安全管線)
hub.SendToClient("client-123", msg)

完整配置範例

config := websocket.Config{
	ReadBufferSize: 1024,
	WriteBufferSize: 1024,
	MaxMessageSize: 65536,
	WriteWait: 10 * time.Second,
	PongWait: 60 * time.Second,
	PingPeriod: 54 * time.Second,
	EnableCompression: true,
	Subprotocols: []string{"json", "protobuf", "flatbuffers", "msgpack"},
	// 壓縮配置(覆寫 EnableCompression)
	Compression: &websocket.CompressionConfig{
		Enabled: true,
		Level: 6,
	},
	// 安全配置
	Security: &websocket.SecurityConfig{
		AESKey: aes256Key, // 32 bytes
		HMACKey: hmacSecret,
		SignThenEncrypt: true,
	},
	// TLS 配置(獨立模式)
	TLS: &websocket.TLSConfig{
		CertFile: "cert.pem",
		KeyFile: "key.pem",
	},
}
hub := websocket.NewHub(l, config)

檔案結構

pkg/websocket/
├── websocket.go # 核心:Client, Hub, Room, Config, readPump/writePump,
│ # TLS/Security/Compression 整合, ListenAndServeTLS
├── codec.go # Codec/ControlDecoder 介面, JSONCodec, ProtobufCodec,
│ # marshalForClients (map-based N-codec 快取 + 安全管線)
├── codec_flatbuffers.go # FlatBuffersCodec(手動 Builder API,零拷貝)
├── codec_msgpack.go # MsgpackCodec(vmihailenco/msgpack/v5)
├── security.go # AES-256-GCM 加解密, HMAC-SHA256 簽名/驗證, 安全管線
├── proto/
│ ├── message.proto # Protobuf schema 定義
│ └── message.pb.go # Protobuf 編解碼實作
├── codec_test.go # 跨 codec round-trip, marshalForClients, 索引唯一性
├── codec_flatbuffers_test.go # FlatBuffers 專屬測試
├── codec_msgpack_test.go # MessagePack 專屬測試
├── security_test.go # AES/HMAC/管線/per-client 金鑰測試
├── websocket_test.go # WebSocket 核心 + 子協議協商測試
└── README.md

依賴