模組二：WebSocket 服務架構 on Tarragon

2.1 read pump / write pump 模式

Wed, 22 Apr 2026 00:00:00 +0000

Read pump / write pump 的核心規則是單一 WebSocket 連線的讀取與寫入必須分成兩個協調的 goroutine。Read pump 擁有讀取權，write pump 擁有寫入權；其他元件不直接操作底層 connection，而是透過 channel 或 method 協作。

本章目標

學完本章後，你將能夠：

分辨 read pump、write pump、hub 的責任
避免多 goroutine 同時寫同一條 WebSocket connection
用 send channel 作為 server-to-client 推送邊界
設計 client unregister 與 close path
用 fake router 測試 read pump 的行為邊界

【觀察】WebSocket 是一條長生命週期雙向連線

WebSocket 連線的核心特徵是 client 和 server 都可能主動送訊息。Client 可能送 subscribe、unsubscribe、ping 或 command；server 可能推送 notification、status update 或 error。

若讀寫責任不分開，程式很容易出現這種結構：

 1func handleConnection(conn *websocket.Conn) {
 2    go func() {
 3        for msg := range serverMessages {
 4            conn.WriteJSON(msg)
 5        }
 6    }()
 7
 8    for {
 9        var msg ClientMessage
10        if err := conn.ReadJSON(&msg); err != nil {
11            return
12        }
13        if msg.Action == "subscribe" {
14            conn.WriteJSON(ServerMessage{Type: "subscribed"})
15        }
16    }
17}

這段程式的問題是多個路徑可能同時寫 connection：背景 goroutine 寫推送，read loop 裡也直接寫回應。多個 goroutine 同時寫 WebSocket 會讓錯誤、資料交錯與 close path 變得難以推理。

【判讀】read pump 和 write pump 是 ownership 邊界

Read pump / write pump 的核心價值是 ownership。Read pump 是唯一讀取者，write pump 是唯一寫入者，其他元件只能透過它們的公開邊界互動。

1type Client struct {
2    id   string
3    conn *websocket.Conn
4    send chan ServerMessage
5}

conn 是底層連線，send 是 server 要推給 client 的訊息佇列。其他元件不直接呼叫 conn.WriteJSON，而是把 ServerMessage 放進 send。

責任表：

元件	責任	不應做的事
read pump	讀 client message、交給 router	直接寫 WebSocket
write pump	寫 server message、送 heartbeat、送 close	處理 client action
hub	註冊、取消註冊、廣播	直接讀寫 connection
router	解析 action、呼叫 usecase 或更新訂閱	關閉底層 connection

這個分工讓連線生命週期可以被測試與替換，而不是散在多個 goroutine 裡。

【策略】Client 型別要表達連線邊界

Client 型別的核心責任是封裝單一連線的狀態與輸出佇列。它不應包含整個系統的業務狀態。

 1type Client struct {
 2    id   string
 3    conn *websocket.Conn
 4    send chan ServerMessage
 5
 6    mu            sync.RWMutex
 7    subscriptions map[string]struct{}
 8}
 9
10func NewClient(id string, conn *websocket.Conn, sendBuffer int) *Client {
11    return &Client{
12        id:            id,
13        conn:          conn,
14        send:          make(chan ServerMessage, sendBuffer),
15        subscriptions: make(map[string]struct{}),
16    }
17}

send 有固定容量，避免慢 client 無限制累積訊息。subscriptions 屬於這條連線的狀態，若會被多個 goroutine 讀寫，就需要 mutex 或集中到 hub event loop。

【執行】read pump 只處理 client 輸入

Read pump 的核心責任是從 connection 讀訊息、轉成 ClientMessage、交給 router。它不應直接操作所有業務規則。

 1type MessageRouter interface {
 2    Route(ctx context.Context, client *Client, message ClientMessage) error
 3}
 4
 5func (c *Client) readPump(ctx context.Context, hub *Hub, router MessageRouter) {
 6    defer func() {
 7        hub.unregister <- c
 8    }()
 9
10    for {
11        var message ClientMessage
12        if err := c.conn.ReadJSON(&message); err != nil {
13            return
14        }
15
16        if err := router.Route(ctx, c, message); err != nil {
17            c.TrySend(ServerMessage{
18                Type:  "error",
19                Error: err.Error(),
20            })
21        }
22    }
23}

Read pump 收到 read error 時退出，並通知 hub unregister。這裡不直接 close send，因為 send 的關閉責任交給 hub 統一處理。

【執行】write pump 是唯一寫入者

Write pump 的核心責任是把 send channel 裡的 server message 寫回 WebSocket。所有寫入都集中在這一個 goroutine，能避免 concurrent write。

 1func (c *Client) writePump() {
 2    for {
 3        message, ok := <-c.send
 4        if !ok {
 5            _ = c.conn.WriteMessage(websocket.CloseMessage, []byte{})
 6            return
 7        }
 8
 9        if err := c.conn.WriteJSON(message); err != nil {
10            return
11        }
12    }
13}

當 send 被關閉時，write pump 送出 close message 並退出。這表示 hub 或 connection manager 是 send 的 owner，write pump 是 receiver。

下一章會把 heartbeat ticker 加進 write pump。原則不變：ping 也是寫入，所以也要由 write pump 統一執行。

【策略】send channel 是推送邊界

send channel 的核心意義是把內部事件轉成 client 輸出佇列。其他元件可以嘗試送訊息，但不能直接寫 connection。

1func (c *Client) TrySend(message ServerMessage) bool {
2    select {
3    case c.send <- message:
4        return true
5    default:
6        return false
7    }
8}

TrySend 使用 non-blocking send，表示 client buffer 滿時不阻塞呼叫端。Hub 可以根據 false 決定丟棄訊息、取消註冊 client 或記錄 metric。

這個方法把 WebSocket 寫入問題轉成前一模組的 backpressure 問題：滿載時要有明確策略。

【執行】hub 統一管理 unregister

Unregister 的核心目標是讓清理流程只有一個責任中心。Read pump、write pump、heartbeat 都可能發現連線失效，但不要讓每個地方各自 close channel 和 connection。

 1type Hub struct {
 2    clients    map[*Client]struct{}
 3    register   chan *Client
 4    unregister chan *Client
 5    broadcast  chan ServerMessage
 6}
 7
 8func (h *Hub) run() {
 9    for {
10        select {
11        case client := <-h.register:
12            h.clients[client] = struct{}{}
13
14        case client := <-h.unregister:
15            if _, ok := h.clients[client]; ok {
16                delete(h.clients, client)
17                close(client.send)
18                _ = client.conn.Close()
19            }
20        }
21    }
22}

這個設計讓 client.send 只會在 hub 中被 close。其他 goroutine 只送 unregister 訊號，不直接關閉資源。

實務上要避免重複 unregister 造成 channel 重複 close。上例透過 clients map 判斷 client 是否仍註冊，讓 unregister 具備 idempotent 行為。

【判讀】read pump 結束不代表 write pump 立刻結束

Read pump 與 write pump 的核心關係是協作，不是互相任意關閉。Read pump 發現錯誤後通知 hub；hub 關閉 send；write pump 收到 send 關閉後送 close message 並退出。

流程：

 1read error
 2   │
 3   ▼
 4hub.unregister <- client
 5   │
 6   ▼
 7hub closes client.send and conn
 8   │
 9   ▼
10write pump exits

這條路徑讓 close ownership 清楚。若 read pump 同時 close send，hub 也 close send，就會有 double close panic。

【測試】router 可以用 fake 驗證 read pump 邊界

Read pump 測試的核心目標是確認 client message 會交給 router，而不是在 read pump 裡塞入業務邏輯。完整 WebSocket integration test 可以留到測試模組；這裡先用 router 的小介面讓行為可替換。

1type fakeRouter struct {
2    messages []ClientMessage
3}
4
5func (r *fakeRouter) Route(ctx context.Context, client *Client, message ClientMessage) error {
6    r.messages = append(r.messages, message)
7    return nil
8}

若測試需要真實 connection，可用 httptest.Server 建立 WebSocket。若只測 router 規則，應直接測 router，不必繞過 network。

Write pump 的測試通常放在 integration test，因為它依賴真實 connection 寫入行為。單元測試則可以集中在 TrySend、router、hub unregister 這些純邊界。

本章不處理

本章先處理單一連線的 read/write ownership；跨節點 hub 與 broker 互動，會在下列章節延伸：

Go 進階：跨節點 WebSocket、presence 與重連協定

和 Go 教材的關係

這一章承接的是 goroutine ownership、channel 與 backpressure；如果你要先回看語言教材，可以讀：

小結

Read pump / write pump 模式把一條 WebSocket 連線拆成清楚的 ownership：read pump 讀 client message，write pump 寫 server message，hub 統一註冊與清理。send channel 是推送邊界，所有 close path 應收斂到同一個 unregister 流程。這樣長連線才不會因為 concurrent write、double close 或慢 client 而失控。

2.2 heartbeat、deadline 與連線清理

Wed, 22 Apr 2026 00:00:00 +0000

Heartbeat 的核心目標是讓失效的長連線可以被發現並清理。Deadline 定義讀寫最多能停滯多久，ping/pong 在沒有業務訊息時確認連線仍然活著，unregister 流程負責釋放連線與訂閱狀態。

本章目標

學完本章後，你將能夠：

分辨 read deadline、write deadline、ping period、pong wait 的角色
在 read pump 設定 pong handler 與 read limit
在 write pump 用 ticker 統一送 ping
讓 heartbeat 失敗進入同一條 unregister 路徑
測試 timeout 設定與清理流程的邊界

【觀察】長連線可能在沒有錯誤訊息時失效

WebSocket 長連線的核心風險是失效不一定立刻表現成明確錯誤。Client 可能斷網、瀏覽器休眠、代理中斷、行動網路切換，server 的 read 或 write 可能長時間卡住。

沒有 heartbeat 的服務可能出現：

client 已離線，但 server 還保留 client。
訂閱狀態沒有清理，broadcast 仍嘗試推送。
write pump 卡在慢或失效的 connection。
goroutine、send buffer、記憶體逐步累積。

Heartbeat 的目的是讓失敗可以在合理時間內被觀測並進入清理流程。

【判讀】四個時間參數負責不同邊界

Heartbeat 設計的核心是四個時間參數的關係。這些參數是讀寫生命週期的合約。

1const (
2    writeWait  = 10 * time.Second
3    pongWait   = 60 * time.Second
4    pingPeriod = 50 * time.Second
5    maxMessage = 1 << 20
6)

參數	角色	常見關係
`writeWait`	單次寫入最多等待多久	小於 `pongWait`
`pongWait`	多久沒讀到資料就視為失效	大於 `pingPeriod`
`pingPeriod`	多久主動送一次 ping	小於 `pongWait`
`maxMessage`	單筆 client message 大小上限	依協定需求設定

pingPeriod 應小於 pongWait，讓 server 有時間送 ping 並等待 client 回 pong。writeWait 保護每次寫入，避免 write pump 無限卡住。

【執行】read pump 設定 read deadline 與 pong handler

Read deadline 的核心語意是超過指定時間沒有讀取進展，下一次 read 會失敗。Pong handler 的核心責任是每次收到 pong 時延長 read deadline。

1func (c *Client) configureRead() {
2    c.conn.SetReadLimit(maxMessage)
3    _ = c.conn.SetReadDeadline(time.Now().Add(pongWait))
4    c.conn.SetPongHandler(func(string) error {
5        return c.conn.SetReadDeadline(time.Now().Add(pongWait))
6    })
7}

Read pump 啟動時先設定：

 1func (c *Client) readPump(ctx context.Context, hub *Hub, router MessageRouter) {
 2    defer func() {
 3        hub.unregister <- c
 4    }()
 5
 6    c.configureRead()
 7
 8    for {
 9        var message ClientMessage
10        if err := c.conn.ReadJSON(&message); err != nil {
11            return
12        }
13        if err := router.Route(ctx, c, message); err != nil {
14            c.TrySend(errorMessage(err))
15        }
16    }
17}

ReadJSON 回錯時，read pump 不需要判斷每一種錯誤都如何清理；它只要退出並通知 hub。錯誤分類可以用於 log，但清理路徑應一致。

【執行】write pump 用 ticker 送 ping

Ping 的核心規則是由 write pump 送出，因為 ping 也是 WebSocket write。讓其他 goroutine 直接送 ping 會破壞「write pump 是唯一寫入者」的原則。

 1func (c *Client) writePump() {
 2    ticker := time.NewTicker(pingPeriod)
 3    defer ticker.Stop()
 4
 5    for {
 6        select {
 7        case message, ok := <-c.send:
 8            _ = c.conn.SetWriteDeadline(time.Now().Add(writeWait))
 9            if !ok {
10                _ = c.conn.WriteMessage(websocket.CloseMessage, []byte{})
11                return
12            }
13            if err := c.conn.WriteJSON(message); err != nil {
14                return
15            }
16
17        case <-ticker.C:
18            _ = c.conn.SetWriteDeadline(time.Now().Add(writeWait))
19            if err := c.conn.WriteMessage(websocket.PingMessage, nil); err != nil {
20                return
21            }
22        }
23    }
24}

每次寫入前設定 write deadline。這包含正常訊息、ping、close message；只保護部分寫入會留下卡住路徑。

【判讀】heartbeat 失敗走共用清理流程

Heartbeat 失敗的核心語意是連線不可用。它應該進入和 read error、write error、client disconnect 相同的 unregister 流程，而不是在 ping 錯誤處重寫一套清理。

推薦流程：

 1read error / write error / ping error
 2          │
 3          ▼
 4read pump exits or write pump exits
 5          │
 6          ▼
 7hub unregisters client
 8          │
 9          ▼
10close send, close conn, remove subscriptions

實作可以用 hub unregister channel、context cancellation 或 connection manager。重點是所有失效都收斂到同一個 owner。

【策略】read pump 和 write pump 都可能先失敗

連線失效的核心不確定性是 read pump 和 write pump 哪個先看到錯誤不可預測。讀不到 pong 可能讓 read pump 先退出；寫 ping 失敗可能讓 write pump 先退出。

因此 unregister 必須可重複呼叫而不出錯：

1func (h *Hub) unregisterClient(client *Client) {
2    if _, ok := h.clients[client]; !ok {
3        return
4    }
5
6    delete(h.clients, client)
7    close(client.send)
8    _ = client.conn.Close()
9}

用 clients map 判斷 client 是否仍註冊，可以避免重複 close send。這是 WebSocket cleanup 最容易漏掉的細節之一。

【策略】heartbeat 參數要符合部署環境

Heartbeat 參數的核心取捨是偵測速度與誤判風險。偵測太快會讓短暫網路抖動造成大量斷線；偵測太慢會讓失效連線保留太久。

調整時要考慮：

load balancer 或 proxy idle timeout
行動網路與瀏覽器背景分頁行為
server 可接受的失效連線保留時間
ping 對大量連線造成的週期性流量
client 是否會自動重連

若基礎設施會在 60 秒 idle 後關閉連線，server 的 ping period 就不能長於這個時間。這是部署環境合約，不是單純 Go 程式碼問題。

【測試】把時間參數和清理邊界拆開測

Heartbeat 的測試核心是不要用真實分鐘級等待。時間參數可以測設定值關係，清理流程可以測 unregister 是否 idempotent。

1func TestHeartbeatDurations(t *testing.T) {
2    if pingPeriod >= pongWait {
3        t.Fatalf("pingPeriod must be smaller than pongWait")
4    }
5    if writeWait >= pongWait {
6        t.Fatalf("writeWait should be smaller than pongWait")
7    }
8}

Unregister 測試：

 1func TestUnregisterClientIsIdempotent(t *testing.T) {
 2    hub := NewHub()
 3    client := NewClient("c1", nil, 1)
 4    hub.clients[client] = struct{}{}
 5
 6    hub.unregisterClient(client)
 7    hub.unregisterClient(client)
 8
 9    if _, ok := hub.clients[client]; ok {
10        t.Fatalf("client should be removed")
11    }
12}

真實 ping/pong 行為適合放在 integration test。單元測試先保證時間合約與 cleanup owner 不會被破壞。

本章不處理

本章先處理單一 WebSocket 連線的存活偵測與 cleanup；client 重連與 load balancer 參數，會在下列章節延伸：

Go 進階：跨節點 WebSocket、presence 與重連協定

和 Go 教材的關係

這一章承接的是 read/write pump、time control 與 shutdown；如果你要先回看語言教材，可以讀：

小結

Heartbeat/deadline 的目的是讓失效連線在可預期時間內被發現並清理。Read deadline 搭配 pong handler 保護讀取端，write deadline 保護每次寫入，ping ticker 由 write pump 統一執行，所有錯誤最後都應進入同一個 unregister 流程。

2.3 訂閱模型與訊息路由

Wed, 22 Apr 2026 00:00:00 +0000

訂閱模型的核心目標是把 client action 轉成明確的連線狀態與回應訊息。WebSocket 是長連線，單次 action 失敗通常不應直接關閉連線；router 應把錯誤轉成可理解的 server message。

本章目標

學完本章後，你將能夠：

設計穩定的 client action envelope
把 router、handler、usecase 與 client state 分開
用訂閱集合表達 client 想收到的 topic
在 broadcast 前檢查訂閱狀態
測試 action routing、payload validation 與 error response

【觀察】client message 很容易變成臨時協定

WebSocket action 的核心風險是前後端快速加功能時，訊息格式變成一堆臨時欄位。若 action 名稱依賴按鈕、畫面或短期 UI 狀態，server 很快會累積難以維護的分支。

不穩定的訊息格式：

1{
2  "button": "watch",
3  "tab": "jobs",
4  "id": "topic_1"
5}

這種訊息描述 UI 發生什麼，不是描述 client 想對服務做什麼。服務端應該接收穩定 action，例如 subscribe_topic、unsubscribe_topic、list_subscriptions。

【判讀】action 是 client intent

Client action 的核心語意是「client 想做什麼」。它不是 domain event，因為它還沒被驗證、授權或套用規則。Domain event 表示已經發生的事，action 表示請求。

 1type ClientAction string
 2
 3const (
 4    ActionSubscribeTopic   ClientAction = "subscribe_topic"
 5    ActionUnsubscribeTopic ClientAction = "unsubscribe_topic"
 6    ActionListTopics       ClientAction = "list_topics"
 7)
 8
 9type ClientMessage struct {
10    Action ClientAction    `json:"action"`
11    Data   json.RawMessage `json:"data,omitempty"`
12}

外層 envelope 穩定，內層 Data 依 action 解析。這讓 read pump 可以先解析 envelope，router 再依 action 決定 payload 型別。

【策略】router 負責分派，不擁有全部規則

Router 的核心責任是把 action 分派到對應 handler。它應該知道有哪些 action，但不應把訂閱規則、權限檢查、資料查詢全部塞在一個巨大 switch 裡。

 1type Router struct {
 2    subscriptions *SubscriptionService
 3}
 4
 5func (r Router) Route(ctx context.Context, client *Client, message ClientMessage) error {
 6    switch message.Action {
 7    case ActionSubscribeTopic:
 8        return r.handleSubscribe(ctx, client, message.Data)
 9    case ActionUnsubscribeTopic:
10        return r.handleUnsubscribe(ctx, client, message.Data)
11    case ActionListTopics:
12        return r.handleListTopics(ctx, client)
13    default:
14        return fmt.Errorf("unknown action: %s", message.Action)
15    }
16}

switch 讓支援的 action 集中可見。真正的訂閱狀態修改可以交給 SubscriptionService 或 client method，避免 router 變成所有規則的聚集地。

【執行】payload validation 在 action 邊界完成

Payload validation 的核心責任是讓內部服務只收到有效 command。訂閱 topic 至少要檢查 JSON 格式、topic 是否空白、topic 名稱是否符合規則。

 1type SubscribeTopicRequest struct {
 2    Topic string `json:"topic"`
 3}
 4
 5type SubscribeTopicCommand struct {
 6    ClientID string
 7    Topic    string
 8}
 9
10func (r Router) handleSubscribe(ctx context.Context, client *Client, raw json.RawMessage) error {
11    var req SubscribeTopicRequest
12    if err := json.Unmarshal(raw, &req); err != nil {
13        return fmt.Errorf("decode subscribe request: %w", err)
14    }
15
16    topic := strings.TrimSpace(req.Topic)
17    if topic == "" {
18        return fmt.Errorf("topic is required")
19    }
20
21    cmd := SubscribeTopicCommand{
22        ClientID: client.ID(),
23        Topic:    topic,
24    }
25
26    return r.subscriptions.Subscribe(ctx, client, cmd)
27}

Request struct 是 wire format，command 是內部意圖。兩者分開後，JSON 命名、驗證錯誤與內部服務規則不會混在同一個型別。

【執行】訂閱集合是連線狀態

訂閱集合的核心語意是「這個 client 目前想收到哪些 topic」。它可以放在 client 上，也可以由 hub 集中保存；重點是 owner 要明確。

Client owner 版本：

 1type Client struct {
 2    id string
 3
 4    mu            sync.RWMutex
 5    subscriptions map[string]struct{}
 6}
 7
 8func (c *Client) Subscribe(topic string) {
 9    c.mu.Lock()
10    defer c.mu.Unlock()
11    c.subscriptions[topic] = struct{}{}
12}
13
14func (c *Client) Unsubscribe(topic string) {
15    c.mu.Lock()
16    defer c.mu.Unlock()
17    delete(c.subscriptions, topic)
18}
19
20func (c *Client) IsSubscribed(topic string) bool {
21    c.mu.RLock()
22    defer c.mu.RUnlock()
23    _, ok := c.subscriptions[topic]
24    return ok
25}

map[string]struct{} 是 Go 常見 set 表示法。若 read pump 修改訂閱，hub broadcast 讀取訂閱，就需要 lock 或把所有訂閱操作集中到 hub event loop。

【策略】訂閱狀態也需要 copy boundary

訂閱列表的核心風險是直接回傳 map 會暴露內部狀態。若需要列出目前訂閱，應回傳 slice 或 map copy。

 1func (c *Client) Subscriptions() []string {
 2    c.mu.RLock()
 3    defer c.mu.RUnlock()
 4
 5    topics := make([]string, 0, len(c.subscriptions))
 6    for topic := range c.subscriptions {
 7        topics = append(topics, topic)
 8    }
 9    sort.Strings(topics)
10    return topics
11}

回傳 sorted slice 讓測試更穩定，也避免呼叫端修改內部 map。排序不是業務必要條件，但對 API response 與測試可讀性有幫助。

【執行】成功與失敗都應回 server message

WebSocket action 的核心互動模式是 request-like，但連線不會因單次 action 結束。成功或失敗都應回一筆 server message，讓 client 能更新 UI 或顯示錯誤。

 1type ServerMessage struct {
 2    Type  string `json:"type"`
 3    Topic string `json:"topic,omitempty"`
 4    Error string `json:"error,omitempty"`
 5}
 6
 7func (s *SubscriptionService) Subscribe(ctx context.Context, client *Client, cmd SubscribeTopicCommand) error {
 8    client.Subscribe(cmd.Topic)
 9    ok := client.TrySend(ServerMessage{
10        Type:  "topic_subscribed",
11        Topic: cmd.Topic,
12    })
13    if !ok {
14        return ErrClientQueueFull
15    }
16    return nil
17}

若 action 失敗，read pump 或 router wrapper 可以把錯誤轉成 ServerMessage{Type: "error"}。不要只寫 server log，因為 client 需要知道該 action 沒有成功。

【執行】broadcast 前檢查訂閱

Broadcast 的核心規則是 producer 只產生 topic 與 message，hub 決定哪些 client 應該收到。訂閱邏輯不應散落在每個 producer 裡。

 1func (h *Hub) Broadcast(topic string, message ServerMessage) {
 2    for client := range h.clients {
 3        if !client.IsSubscribed(topic) {
 4            continue
 5        }
 6
 7        if ok := client.TrySend(message); !ok {
 8            h.unregister <- client
 9        }
10    }
11}

這段程式先檢查訂閱，再嘗試送出。若 client 的 send buffer 滿了，hub 可以 unregister 或採用其他慢 client 策略；下一章會專門處理。

【測試】router test 不需要真實 WebSocket

Router 的測試核心是 action 到行為的對應。它不需要真實 WebSocket connection，只需要 fake client 或檢查 client state。

 1func TestSubscribeActionAddsTopic(t *testing.T) {
 2    client := NewTestClient("client_1")
 3    router := Router{subscriptions: NewSubscriptionService()}
 4
 5    data := json.RawMessage(`{"topic":"alerts"}`)
 6    err := router.Route(context.Background(), client, ClientMessage{
 7        Action: ActionSubscribeTopic,
 8        Data:   data,
 9    })
10    if err != nil {
11        t.Fatalf("route subscribe: %v", err)
12    }
13
14    if !client.IsSubscribed("alerts") {
15        t.Fatalf("client should subscribe to alerts")
16    }
17}

Payload validation 也應獨立測：

 1func TestSubscribeActionRequiresTopic(t *testing.T) {
 2    client := NewTestClient("client_1")
 3    router := Router{subscriptions: NewSubscriptionService()}
 4
 5    err := router.Route(context.Background(), client, ClientMessage{
 6        Action: ActionSubscribeTopic,
 7        Data:   json.RawMessage(`{"topic":" "}`),
 8    })
 9    if err == nil {
10        t.Fatalf("empty topic should return error")
11    }
12}

WebSocket integration test 留給「真實 client/server 互動」；router 單元測試先確保協定語意正確。

本章不處理

本章先處理 action envelope 到 subscription 的路由與 ownership；授權、presence 與跨節點同步，會在下列章節延伸：

Go 進階：跨節點 WebSocket、presence 與重連協定

和 Go 教材的關係

這一章承接的是 WebSocket action、event fusion 與 handler boundary；如果你要先回看語言教材，可以讀：

小結

訂閱模型把 client action 轉成連線狀態與 server response。Action 是 client intent，不是 domain event；router 負責分派，payload validation 在邊界完成，訂閱集合要有明確 owner，broadcast 由 hub 統一檢查訂閱。這樣新增 action 或 topic 時，修改範圍會清楚且可測。

2.4 慢客戶端與 send buffer 管理

Wed, 22 Apr 2026 00:00:00 +0000

慢客戶端管理的核心問題是單一 client 的讀取速度可能低於 server 推送速度。若 send buffer 沒有上限，慢 client 會把訊息堆在記憶體裡；若 hub 使用 blocking send，慢 client 會拖住所有 client。

本章目標

學完本章後，你將能夠：

分辨慢 client 對 hub、write pump、記憶體的影響
用 bounded send channel 限制單一 client 的排隊量
設計 queue full 時的 drop、disconnect、coalesce 策略
在必要時用 byte budget 管理大型 payload
測試 send buffer 滿載與 client unregister 行為

【觀察】慢 client 會把局部問題變成全域問題

慢 client 的核心風險是它不只影響自己。若 hub broadcast 時對每個 client 使用 blocking send，其中一個 client 的 send channel 滿了，hub 就可能卡住，其他 client 也收不到訊息。

反模式：

1func (h *Hub) Broadcast(message ServerMessage) {
2    for client := range h.clients {
3        client.send <- message
4    }
5}

這段程式看起來保證送達，但實際上把整個 hub 的可用性綁在最慢的 client 上。只要一個 client 不讀，所有 broadcast 都可能停住。

【判讀】send channel 是每個 client 的容量邊界

Send channel 的核心責任是作為單一 client 的輸出佇列。它必須有容量上限，否則 server 會替慢 client 無限制保存訊息。

 1const sendBufferSize = 64
 2
 3type Client struct {
 4    id   string
 5    send chan ServerMessage
 6}
 7
 8func NewClient(id string) *Client {
 9    return &Client{
10        id:   id,
11        send: make(chan ServerMessage, sendBufferSize),
12    }
13}

Buffer 的目的只是吸收短暫尖峰，不是讓 client 長期落後。若 client 長期消費速度低於推送速度，任何有限 buffer 都會滿。

【策略】滿載策略取決於訊息語意

慢 client 滿載的核心決策是訊息能不能遺失。不同資料類型需要不同策略。

訊息類型	常見策略	理由
即時狀態 snapshot	可丟棄舊訊息或 coalesce	最新狀態比每個中間狀態重要
action result	優先送達，滿載時可斷線	client 需要知道操作結果
診斷 log stream	可取樣或丟棄	資料量大，通常不是唯一真相
金流、訂單、稽核事件	不應只靠 WebSocket	需要可靠儲存或可重播來源

WebSocket send buffer 不應承擔資料可靠性。若訊息不能遺失，可靠性應放在資料庫、queue 或 event log，WebSocket 只負責即時通知。

【執行】non-blocking send 保護 hub

Hub 的核心保護是 broadcast 時不被單一 client 阻塞。TrySend 可以讓 hub 立即知道該 client 是否已滿載。

1func (c *Client) TrySend(message ServerMessage) bool {
2    select {
3    case c.send <- message:
4        return true
5    default:
6        return false
7    }
8}

Hub 可以把滿載 client 送進 unregister：

 1func (h *Hub) Broadcast(topic string, message ServerMessage) {
 2    for client := range h.clients {
 3        if !client.IsSubscribed(topic) {
 4            continue
 5        }
 6
 7        if ok := client.TrySend(message); !ok {
 8            h.unregister <- client
 9        }
10    }
11}

這種策略犧牲慢 client，保護整體服務。對即時通知服務來說，讓慢 client 重連並重新取得 snapshot，通常比讓所有 client 等它更合理。

【策略】drop newest、drop oldest、disconnect 是不同語意

Queue full 策略的核心差異是保留哪一筆資料，以及是否繼續維持連線。

策略	行為	適用情境
drop newest	新訊息不進 queue	舊訊息仍有價值
drop oldest	移除舊訊息，保留最新	狀態型更新
disconnect	關閉 client，要求重連	client 已明顯跟不上
coalesce	合併多筆更新成一筆	topic 最新狀態可覆蓋

Drop oldest 範例：

 1func (c *Client) TrySendLatest(message ServerMessage) bool {
 2    select {
 3    case c.send <- message:
 4        return true
 5    default:
 6    }
 7
 8    select {
 9    case <-c.send:
10    default:
11    }
12
13    select {
14    case c.send <- message:
15        return true
16    default:
17        return false
18    }
19}

這段程式表示「新狀態比舊狀態重要」。它不適合 action result 或不可遺失事件，因為它會主動丟掉尚未送出的舊訊息。

【策略】byte budget 比 message count 更接近記憶體風險

Message count 的核心限制是每筆訊息大小不同。64 筆小訊息和 64 筆大型 JSON payload 的記憶體成本差很多；當 payload 大小差異明顯時，可以加上 byte budget。

 1type Client struct {
 2    send      chan ServerMessage
 3    sendBytes int64
 4    maxBytes  int64
 5}
 6
 7func (c *Client) TrySend(message ServerMessage) bool {
 8    size := int64(message.Size())
 9    if atomic.AddInt64(&c.sendBytes, size) > c.maxBytes {
10        atomic.AddInt64(&c.sendBytes, -size)
11        return false
12    }
13
14    select {
15    case c.send <- message:
16        return true
17    default:
18        atomic.AddInt64(&c.sendBytes, -size)
19        return false
20    }
21}

Write pump 成功取出並寫出訊息後，必須扣回 byte budget：

1func (c *Client) markSent(message ServerMessage) {
2    atomic.AddInt64(&c.sendBytes, -int64(message.Size()))
3}

Byte budget 更接近記憶體風險，但也更複雜。只有在訊息大小差異大、或服務連線數高時才值得加入；小型服務先用固定 buffer 通常足夠。

【判讀】write pump 慢不一定是 client 的錯

慢寫入的核心原因可能在 client，也可能在 server。Client 網路慢、瀏覽器停住、行動裝置休眠會造成慢寫；server payload 太大、序列化太慢、單次寫入沒有 deadline 也會造成問題。

排查方向：

send buffer 長期接近滿載
write deadline 錯誤增加
單筆 message size 過大
broadcast 頻率超過 client 消費能力
某些 topic 推送量異常高

queue full 的歸因應同時檢查 client 與 server 端訊號。若所有 client 都慢，通常是 server 推送量、payload 大小或下游網路策略出問題。

【策略】滿載要有觀測欄位

慢 client 策略的核心要求是可觀測。若系統選擇 drop 或 disconnect，應記錄足夠欄位讓工程師知道原因。

 1func (h *Hub) handleFullClient(client *Client, topic string) {
 2    metrics.Inc("websocket_client_send_full")
 3    h.logger.Warn("websocket client send buffer full",
 4        "client_id", client.ID(),
 5        "topic", topic,
 6        "send_queue_len", len(client.send),
 7        "send_queue_cap", cap(client.send),
 8    )
 9    h.unregister <- client
10}

Log 用來追單次事件，metric 用來看趨勢。若滿載數量突然增加，可能是某個 topic 推送量上升，也可能是 client 版本或網路環境改變。

【測試】滿載測試要先填滿 buffer

慢 client 測試的核心是直接建立滿載條件。容量為 1 的 channel 加上預先填滿的資料，可以穩定製造 queue full；sleep 只是在等待排程運氣。

 1func TestTrySendReturnsFalseWhenBufferFull(t *testing.T) {
 2    client := &Client{
 3        id:   "client_1",
 4        send: make(chan ServerMessage, 1),
 5    }
 6    client.send <- ServerMessage{Type: "first"}
 7
 8    ok := client.TrySend(ServerMessage{Type: "second"})
 9    if ok {
10        t.Fatalf("TrySend should return false when buffer is full")
11    }
12}

Hub unregister 行為也可以測：

 1func TestBroadcastUnregistersFullClient(t *testing.T) {
 2    hub := NewHub()
 3    client := NewTestClient("client_1", 1)
 4    client.Subscribe("alerts")
 5    client.send <- ServerMessage{Type: "existing"}
 6    hub.clients[client] = struct{}{}
 7
 8    hub.Broadcast("alerts", ServerMessage{Type: "new"})
 9
10    select {
11    case got := <-hub.unregister:
12        if got != client {
13            t.Fatalf("unregister client mismatch")
14        }
15    default:
16        t.Fatalf("full client should be unregistered")
17    }
18}

這類測試直接驗證服務策略：client 滿載時，hub 不阻塞，而是走指定降級路徑。

本章不處理

本章先處理單一 server 內的慢 client 與 send buffer 邊界；跨節點 fan-out 與持久化同步，會在下列章節延伸：

Go 進階：跨節點 WebSocket、presence 與重連協定

和 Go 教材的關係

這一章承接的是 channel backpressure 、non-blocking send 與 rate limiting；如果你要先回看語言教材，可以讀：

小結

慢客戶端是 WebSocket 服務的容量控制問題。每個 client 的 send buffer 必須有上限，hub broadcast 不應被單一 client 阻塞，queue full 策略要符合訊息語意。必要時可加入 byte budget，但更重要的是明確決定 drop、disconnect、coalesce 或可靠儲存，並用 log、metric、測試讓降級行為可見。