觀察

app_tunnel Flutter app 連接 ttyd WebSocket 終端機。ConnectionManager.sendData() 接收 Uint8List 型別的鍵盤輸入，直接傳給 _channel!.sink.add(data)。Dart 的 IOWebSocketChannel 對 Uint8List 發送 binary frame（opcode 0x2），ttyd 期望 text frame（opcode 0x1），收到 binary frame 靜默忽略。

判讀

1. Mock 模擬的是 Dart API 契約，不是 WebSocket 協議契約。FakeWebSocketChannel 忠實實作了 WebSocketChannel 的 Dart interface — sink.add(dynamic) 接受任何型別。但 IOWebSocketChannel 的 sink.add 實際行為是：String → text frame，List<int> / Uint8List → binary frame。Mock 沒有也不應該模擬這個協議層行為。

2. ttyd 的靜默忽略放大了問題。如果 ttyd 對 binary frame 回傳錯誤碼或斷線，app 至少會進入 error 狀態讓開發者察覺。靜默忽略讓問題從「連線失敗」變成「連線成功但無回應」，debug 方向完全錯誤。

3. 型別系統幫不上忙。Dart 的 WebSocketSink.add 簽名是 void add(dynamic event) — dynamic 吃掉了型別資訊。即使用強型別語言，如果 API 設計成 dynamic，型別檢查無法區分協議語意。

策略

1. Protocol integration test：對真實 ttyd 發送 Uint8List 和 String，斷言兩者行為差異。一個 5 行 test 就能抓到這個問題。
2. 在 sendData 層做型別轉換：不依賴下游 channel 的行為，在自己的 API 邊界確保型別正確。
3. Log 送出的 frame type：developer.log('WS send: type=${data.runtimeType}') 讓 debug 時立即可見。

下一步路由

• 想寫 protocol integration test → 模組三：協議整合測試
• 想理解 mock 遮蔽的系統性機制 → Mock 遮蔽機制分析
• 類似案例（auth handshake） → T.C2 Auth handshake 缺失

本章目標

學完本章後，你將能夠：

1. 分辨 read pump、write pump、hub 的責任
2. 避免多 goroutine 同時寫同一條 WebSocket connection
3. 用 send channel 作為 server-to-client 推送邊界
4. 設計 client unregister 與 close path
5. 用 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。

責任表：

這個分工讓連線生命週期可以被測試與替換，而不是散在多個 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；如果你要先回看語言教材，可以讀：

• Go：goroutine：輕量並發工作
• Go：channel：資料傳遞與 backpressure
• Go：channel ownership 與關閉責任
• Go：如何新增一個即時訊息 action
• Backend：訊息佇列與事件傳遞

小結

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 而失控。

本章目標

學完本章後，你將能夠：

1. 用 action type 表達 client intent
2. 用 request struct 定義 JSON payload 邊界
3. 把 WebSocket message 轉成 application command
4. 設計穩定的 response 與 error 格式
5. 把 router、usecase 與 WebSocket integration test 分層測試

【觀察】action 表達 client intent

action 的核心語意是 client 想要系統做什麼。它是 client 和 server 之間的訊息合約，命名應描述行為意圖，而不是 UI 按鈕或 handler 函式名稱。

例如即時通知服務可能有三種 action：

用字串常數定義 action，可以避免 handler 到處散落 magic string：

1const (
2    ActionSubscribeTopic   = "subscribe_topic"
3    ActionUnsubscribeTopic = "unsubscribe_topic"
4    ActionGetSnapshot      = "get_snapshot"
5)

action 名稱應該描述行為意圖。subscribe_topic 比 ws_subscribe 更穩定，因為未來同一個 usecase 也可能被 HTTP endpoint 或 background job 呼叫。

【判讀】外部訊息先進入 envelope

WebSocket message 的核心邊界是 envelope。client 傳來的 JSON 應該先被解析成一個共同外殼，再根據 action 解析 payload。

1type ClientMessage struct {
2    ID      string          `json:"id"`
3    Action  string          `json:"action"`
4    Payload json.RawMessage `json:"payload"`
5}

ID 是 client message ID，可用來讓 response 對應原始 request。Action 決定路由方向。Payload 使用 json.RawMessage，讓 router 可以先看 action，再把 payload 解成對應 struct。

例如 client 可以送出：

1{
2  "id": "msg_1001",
3  "action": "subscribe_topic",
4  "payload": {
5    "topic": "deployments",
6    "includeHistory": true
7  }
8}

這種 envelope 設計讓新 action 可以共用同一套外層格式。新增 action 時，不需要改整個 WebSocket 讀取流程，只要新增 payload struct 與路由分支。

【策略】payload struct 要表達資料語意

payload struct 的核心責任是把外部 JSON 轉成明確的 Go 型別。必填欄位、可選欄位與相容性都應該在 struct 與驗證函式中清楚表達。

1type SubscribeTopicRequest struct {
2    Topic          string `json:"topic"`
3    IncludeHistory bool   `json:"includeHistory,omitempty"`
4}

Topic 是必填欄位，因為沒有 topic 就無法訂閱。IncludeHistory 是可選欄位，零值 false 可以代表「不要求歷史資料」。這裡使用 omitempty 是在表達：輸出 response 或轉送資料時，這個欄位可以省略；它不是必填資料。

驗證規則應該靠明確函式完成，讓 router 分支只負責呼叫驗證與轉換：

1func (r SubscribeTopicRequest) Validate() error {
2    if strings.TrimSpace(r.Topic) == "" {
3        return fmt.Errorf("topic is required")
4    }
5    return nil
6}

外部資料進入系統後，要先完成解碼與驗證，才轉成 application command。這可以避免 usecase 同時處理 JSON 格式、欄位缺漏與業務規則。

【執行】router 只做解析、驗證與轉換

message router 的核心責任是把 client message 轉成 application command。router 只處理傳輸邊界，狀態修改與訂閱規則交給 usecase。

先定義 usecase 需要的 command：

1type SubscribeTopicCommand struct {
2    ClientID       string
3    Topic          string
4    IncludeHistory bool
5}

command 是 application layer 的輸入模型，只描述 usecase 需要的資料。它不需要 JSON tag，因為外部傳輸格式已經停在 request struct。

接著定義 usecase 介面：

1type SubscriptionUsecase interface {
2    SubscribeTopic(ctx context.Context, cmd SubscribeTopicCommand) error
3}

這個介面小而明確，只描述 router 目前需要的能力。不要一開始就建立大型 Service 介面，把所有 action 都塞進去。

router 可以這樣組裝：

1type MessageRouter struct {
2    subscriptions SubscriptionUsecase
3}
4
5func NewMessageRouter(subscriptions SubscriptionUsecase) *MessageRouter {
6    return &MessageRouter{subscriptions: subscriptions}
7}

處理入口接收原始 JSON bytes，回傳可序列化的 response：

 1func (r *MessageRouter) Handle(ctx context.Context, clientID string, data []byte) ServerMessage {
 2    var msg ClientMessage
 3    if err := json.Unmarshal(data, &msg); err != nil {
 4        return ErrorMessage("", "invalid_json", "message must be valid JSON")
 5    }
 6
 7    switch msg.Action {
 8    case ActionSubscribeTopic:
 9        return r.handleSubscribeTopic(ctx, clientID, msg)
10    default:
11        return ErrorMessage(msg.ID, "unknown_action", "action is not supported")
12    }
13}

Handle 不知道 WebSocket connection 怎麼讀寫，也不處理網路錯誤。這讓 router 可以被普通單元測試覆蓋。

subscribe_topic 的分支負責 payload 解碼、驗證與 command 建立：

 1func (r *MessageRouter) handleSubscribeTopic(ctx context.Context, clientID string, msg ClientMessage) ServerMessage {
 2    var req SubscribeTopicRequest
 3    if err := json.Unmarshal(msg.Payload, &req); err != nil {
 4        return ErrorMessage(msg.ID, "invalid_payload", "payload must match subscribe_topic schema")
 5    }
 6
 7    if err := req.Validate(); err != nil {
 8        return ErrorMessage(msg.ID, "invalid_payload", err.Error())
 9    }
10
11    cmd := SubscribeTopicCommand{
12        ClientID:       clientID,
13        Topic:          req.Topic,
14        IncludeHistory: req.IncludeHistory,
15    }
16
17    if err := r.subscriptions.SubscribeTopic(ctx, cmd); err != nil {
18        return ErrorMessage(msg.ID, "subscribe_failed", "topic subscription failed")
19    }
20
21    return OKMessage(msg.ID, map[string]string{
22        "topic": req.Topic,
23    })
24}

這段程式保留了清楚的轉換路徑：JSON message -> request struct -> command -> usecase。每一層只處理自己的責任。

【判讀】response 也需要穩定格式

response 格式的核心目標是讓 client 能穩定判斷一個 action 的結果。成功、輸入錯誤與不支援 action 都應該使用同一個外層格式。

1type ServerMessage struct {
2    ReplyTo string `json:"replyTo,omitempty"`
3    OK      bool   `json:"ok"`
4    Code    string `json:"code,omitempty"`
5    Message string `json:"message,omitempty"`
6    Data    any    `json:"data,omitempty"`
7}

成功 response 可以用 helper 建立：

1func OKMessage(replyTo string, data any) ServerMessage {
2    return ServerMessage{
3        ReplyTo: replyTo,
4        OK:      true,
5        Data:    data,
6    }
7}

錯誤 response 也應該用 helper 建立：

1func ErrorMessage(replyTo string, code string, message string) ServerMessage {
2    return ServerMessage{
3        ReplyTo: replyTo,
4        OK:      false,
5        Code:    code,
6        Message: message,
7    }
8}

WebSocket action 失敗不一定要關閉連線。JSON 格式錯誤、未知 action 或 payload 驗證失敗，通常可以回一筆 error message，讓 client 修正下一次請求；只有協定嚴重錯誤、授權失效或連線狀態不可恢復時，才考慮關閉連線。

【策略】WebSocket handler 聚焦 connection I/O

WebSocket handler 的核心責任是 connection I/O。它可以讀 message、呼叫 router、寫 response；每種 action 的業務規則交給 router 後方的 usecase。

簡化後的連線處理可以像這樣：

 1func handleClientMessage(ctx context.Context, router *MessageRouter, clientID string, data []byte) []byte {
 2    resp := router.Handle(ctx, clientID, data)
 3
 4    encoded, err := json.Marshal(resp)
 5    if err != nil {
 6        fallback := ErrorMessage("", "encode_failed", "response could not be encoded")
 7        encoded, _ = json.Marshal(fallback)
 8    }
 9
10    return encoded
11}

真實 WebSocket server 會有 read loop、write loop、heartbeat 與 slow client 處理。這些都屬於連線生命週期，應和 action routing 分開維護。

【執行】router 測試先覆蓋協定行為

router 測試的核心目標是確認 message 進入後會產生正確 command 與 response。這類測試不需要啟動真實 WebSocket server。

先建立 fake usecase：

 1type fakeSubscriptionUsecase struct {
 2    got SubscribeTopicCommand
 3    err error
 4}
 5
 6func (f *fakeSubscriptionUsecase) SubscribeTopic(ctx context.Context, cmd SubscribeTopicCommand) error {
 7    if f.err != nil {
 8        return f.err
 9    }
10    f.got = cmd
11    return nil
12}

成功案例測試可以檢查 command 是否正確：

 1func TestMessageRouterSubscribeTopic(t *testing.T) {
 2    fake := &fakeSubscriptionUsecase{}
 3    router := NewMessageRouter(fake)
 4
 5    data := []byte(`{
 6        "id": "msg_1",
 7        "action": "subscribe_topic",
 8        "payload": {
 9            "topic": "deployments",
10            "includeHistory": true
11        }
12    }`)
13
14    resp := router.Handle(context.Background(), "client_1", data)
15
16    if !resp.OK {
17        t.Fatalf("response OK = false, want true")
18    }
19    if fake.got.ClientID != "client_1" {
20        t.Fatalf("client ID = %q, want %q", fake.got.ClientID, "client_1")
21    }
22    if fake.got.Topic != "deployments" {
23        t.Fatalf("topic = %q, want %q", fake.got.Topic, "deployments")
24    }
25    if !fake.got.IncludeHistory {
26        t.Fatalf("include history = false, want true")
27    }
28}

輸入錯誤案例應該測 response code。錯誤文案可以調整，code 才是較穩定的協定欄位：

 1func TestMessageRouterUnknownAction(t *testing.T) {
 2    router := NewMessageRouter(&fakeSubscriptionUsecase{})
 3
 4    resp := router.Handle(context.Background(), "client_1", []byte(`{
 5        "id": "msg_1",
 6        "action": "missing_action",
 7        "payload": {}
 8    }`))
 9
10    if resp.OK {
11        t.Fatalf("response OK = true, want false")
12    }
13    if resp.Code != "unknown_action" {
14        t.Fatalf("code = %q, want %q", resp.Code, "unknown_action")
15    }
16}

這些測試保護的是 action 協定。未來 WebSocket library、connection manager 或 repository 改變時，router 行為仍然能被快速驗證。

【判讀】usecase 測試要離開傳輸格式

usecase 測試的核心目標是驗證行為規則，而不是 JSON 格式。當 router 已經把 message 轉成 command，usecase 測試就應該直接餵 command。

 1func TestSubscriptionServiceSubscribeTopic(t *testing.T) {
 2    repo := NewInMemorySubscriptionRepository()
 3    service := NewSubscriptionService(repo)
 4
 5    cmd := SubscribeTopicCommand{
 6        ClientID:       "client_1",
 7        Topic:          "deployments",
 8        IncludeHistory: true,
 9    }
10
11    if err := service.SubscribeTopic(context.Background(), cmd); err != nil {
12        t.Fatalf("subscribe topic: %v", err)
13    }
14
15    if !repo.IsSubscribed("client_1", "deployments") {
16        t.Fatalf("client should be subscribed")
17    }
18}

這裡不需要出現 JSON、WebSocket 或 ClientMessage。usecase 只關心訂閱規則與 repository 狀態。

實作檢查清單

新增 action 時，可以依序檢查：

1. action 名稱是否描述 client intent
2. 是否有獨立 request struct
3. 必填欄位是否有驗證
4. router 是否只做解析、驗證與 command 轉換
5. usecase 是否不依賴 WebSocket 型別
6. response 是否有穩定 ok、code、message 格式
7. 錯誤 action 是否回 error message，而不是直接關閉連線
8. router 測試是否覆蓋成功、未知 action、invalid JSON、invalid payload
9. usecase 測試是否直接使用 command

設計檢查

檢查一：handler 只處理傳輸邊界

handler 只處理讀寫、編碼與連線狀態，可以讓 HTTP API、CLI 或背景工作共用同一個 usecase。handler 直接改 map、slice 或 repository 時，傳輸協定和業務規則會綁在一起。

檢查二：payload 轉成明確 command

map[string]any 適合短暫承接未知 JSON，不適合傳進 usecase。usecase 應該接收明確 command，讓欄位、型別與驗證規則可讀可測。

檢查三：action 失敗和連線失敗分開處理

單一 action payload 錯誤不代表 WebSocket 連線壞掉。多數 client input error 應該用 error response 表達，避免 client 因小錯誤被斷線。

檢查四：router interface 跟著 usecase 成長

router 依賴的 interface 應該由當下需要的 usecase 定義。過早建立大型 service interface，會讓每個測試都被迫實作不相關方法。

本章不處理

本章先處理單一 server 內的 action routing 與 response contract；完整 WebSocket lifecycle 與跨節點推送，會在下列章節再往外延伸：

• Go 進階：WebSocket 服務架構
• Go 進階：跨節點 WebSocket、presence 與重連協定

和 Go 教材的關係

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

• Go：用 interface 隔離外部依賴
• Go：把 handler 邏輯拆成可測單元
• Go：如何新增背景工作流程
• Go：如何新增一種 domain event

觀察

ttyd WebSocket 協議要求連線建立後發送一個 JSON frame 包含 base64 編碼的帳密（{"AuthToken":"base64(user:pass)"}），ttyd 驗證通過後才開始推送 terminal output。app_tunnel 的 ConnectionManager 建立 WS 連線後直接開始監聽 stream，沒有發送 auth token。

判讀

1. Mock 的 happy path 比真實服務寬鬆。FakeWebSocketChannel 的 ready 是 Future.value()（立即完成），stream 是開發者手動控制的 StreamController。真實 ttyd 的行為是：ready 完成代表 TCP+WS 握手成功，但 stream 要等 auth token 驗證後才有資料。Mock 把兩步合成一步。

2. Integration test 名為整合實為 fake。connection_flow_test.dart 標題是「端對端整合測試」，但內部使用 FakeWebSocketChannel + FakeBiometricService + InMemoryCredentialRepository — 三個核心依賴全是 fake。這個 test 驗證的是「假設所有外部服務都正常，內部狀態機是否正確」，不是「真實服務互動是否正確」。

3. 功能缺失比功能錯誤更難被 test 抓到。功能錯誤（T.C1 text vs binary）至少有一個實作可以斷言；功能缺失意味著沒有程式碼可以 test。只有 protocol integration test（對真實服務跑）才能暴露「應該有但沒有」的行為。

策略

1. Protocol integration test 必須涵蓋 auth handshake：連線 → 發送正確 auth token → 斷言收到 output；連線 → 不發送 auth token → 斷言 timeout 或斷線。
2. 在企劃階段列出協議握手步驟：ttyd WS 協議的 auth handshake 應該在 spec 文件中明確列出，不依賴開發者記得實作。
3. 區分「名義 integration」和「真實 integration」：test 名稱含 integration 但全用 fake，應標明 fake-integration 或改名 connection-state-machine-test。

下一步路由

• 想區分 mock 層級 → 模組一：測試策略分層
• 想建 protocol integration test → 模組三：協議整合測試
• 想設計 auth 機制的 UX fallback → U.C2 biometricOnly 無 fallback

要驗證什麼

從 T.C1 和 T.C2 的案例推導出 WebSocket protocol test 至少需要覆蓋的場景：

Frame type 驗證

IOWebSocketChannel 對 String 和 Uint8List 產生不同的 frame type（text vs binary）。ttyd 只接受 text frame，收到 binary frame 靜默忽略（T.C1）。

Protocol test 需要驗證：

• 發送 String → ttyd 回應（text frame 被處理）
• 發送 Uint8List → ttyd 不回應（binary frame 被忽略）
• 確認 sendData() 函式實際發送的是 text frame

Auth handshake 驗證

ttyd 連線後需要發送 auth token JSON frame 完成認證，認證通過後才推送 terminal output（T.C2）。

Protocol test 需要驗證：

• 連線後發送正確的 auth token → 收到 terminal output
• 連線後不發送 auth token → 逾時無 output
• 連線後發送錯誤的 auth token → 連線被斷開或無 output

連線生命週期驗證

WebSocket 連線的建立、維持、斷開在 mock 環境中都是瞬間完成的。真實環境中有延遲、可能失敗、可能逾時。

Protocol test 需要驗證：

• 連線建立的成功路徑（TCP → WS 升級 → ready）
• 連線逾時的行為（server 不可達時 client 的回應）
• 連線斷開後的狀態（stream 是否正確關閉）

Test 結構

 1setUp: 啟動本機 ttyd（Process.start('ttyd', ['bash'])）
 2tearDown: 停止 ttyd（process.kill()）
 3
 4test('text frame is accepted by ttyd'):
 5  channel = IOWebSocketChannel.connect('ws://localhost:7681/ws')
 6  await channel.ready
 7  channel.sink.add('{"AuthToken":"base64(user:pass)"}')
 8  channel.sink.add('echo hello')  // String → text frame
 9  output = await channel.stream.first.timeout(5s)
10  expect(output, contains('hello'))
11
12test('binary frame is silently ignored by ttyd'):
13  channel = IOWebSocketChannel.connect(...)
14  await channel.ready
15  channel.sink.add('{"AuthToken":"..."}')
16  channel.sink.add(Uint8List.fromList(utf8.encode('echo hello')))
17  expect(channel.stream.first.timeout(2s), throwsTimeoutException)
18
19test('auth token required before output'):
20  channel = IOWebSocketChannel.connect(...)
21  await channel.ready
22  // 不發 auth token，直接發指令
23  channel.sink.add('echo hello')
24  expect(channel.stream.first.timeout(2s), throwsTimeoutException)

執行成本

app_tunnel 的 server（ttyd）和 client 在同一台機器上。啟動 ttyd 是一行指令（ttyd bash），不需要 Docker、不需要雲端服務、不需要網路。整個 test suite 的執行時間主要是連線建立和逾時等待，每個 test case 約 2-5 秒。

這個低成本是自用工具的結構優勢 — server 可以在 test 的 setUp 中啟動、tearDown 中停止，不需要共享的 test 環境（本章合成，TF-8 Derive）。

下一步路由

• HTTP 的 contract test 設計 → HTTP contract test 設計
• CI 中的服務管理 → CI 中的服務 fixture 管理
• 什麼時候值得寫 protocol integration test → 成本判斷表

本章目標

學完本章後，你將能夠：

1. 分辨 read deadline、write deadline、ping period、pong wait 的角色
2. 在 read pump 設定 pong handler 與 read limit
3. 在 write pump 用 ticker 統一送 ping
4. 讓 heartbeat 失敗進入同一條 unregister 路徑
5. 測試 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)

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；如果你要先回看語言教材，可以讀：

• Go：select：同時等待多種事件
• Go：defer 與資源清理
• Go 進階：time control
• Go 進階：graceful shutdown 與 signal handling
• Backend：部署平台與網路入口

小結

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

本章目標

學完本章後，你將能夠：

1. 用 httptest.Server 建立真實 WebSocket 測試入口
2. 將 http:// 測試 URL 轉成 ws://
3. 用 deadline 避免 read/write 永久卡住
4. 驗證 subscribe、push、error response 與 cleanup
5. 分辨 integration test 與 unit test 的責任邊界

【觀察】WebSocket 的錯誤常出現在元件交界

WebSocket 測試的核心困難是很多錯誤不在單一函式裡。Router 單元測試可能通過，但真實連線仍可能因為 upgrade path、read pump、write pump、send buffer 或 unregister 流程出錯。

Integration test 適合驗證這些交界：

• client 能否成功 dial 到 /ws
• server 是否接受 client action
• subscribe 後是否收到 acknowledgement
• server broadcast 是否能推到 client
• client 關閉後 hub 是否清理連線
• 錯誤 action 是否回 error message 而不是斷線

這些不是每個單元測試都該覆蓋的內容。Integration test 的價值在於證明多個元件能透過真實協定協作。

【判讀】integration test 補的是協作信心

Integration test 的核心責任是覆蓋協定流程，不是取代所有規則測試。Router validation、topic normalization、dedup key、state transition 應主要用單元測試；WebSocket integration test 只挑關鍵端到端流程。

建議分工：

如果每個 validation case 都啟動 WebSocket server，測試會變慢且失敗定位不清楚。Integration test 應少量、關鍵、穩定。

【執行】用 httptest.Server 建立真實入口

WebSocket integration test 的核心起點是 httptest.Server。它提供真實 HTTP server，不需要手動管理 port。

 1func TestWebSocketSubscribe(t *testing.T) {
 2    server := httptest.NewServer(newRouter())
 3    t.Cleanup(server.Close)
 4
 5    wsURL := "ws" + strings.TrimPrefix(server.URL, "http") + "/ws"
 6
 7    conn, _, err := websocket.DefaultDialer.Dial(wsURL, nil)
 8    if err != nil {
 9        t.Fatalf("dial websocket: %v", err)
10    }
11    t.Cleanup(func() {
12        _ = conn.Close()
13    })
14}

httptest.NewServer 產生的是 http://127.0.0.1:port，WebSocket client 需要 ws://127.0.0.1:port/ws，所以常用字串轉換。

若 handler 需要 hub、router、fake repository，應在測試中明確組裝。這讓 integration test 的依賴可控。

【策略】測試 helper 應封裝連線樣板

Integration test 的核心樣板很多：建立 server、轉 URL、dial、設定 cleanup。可以用 helper 降低重複，但不要把協定斷言藏起來。

 1func newTestWebSocket(t *testing.T, handler http.Handler) (*websocket.Conn, *httptest.Server) {
 2    t.Helper()
 3
 4    server := httptest.NewServer(handler)
 5    t.Cleanup(server.Close)
 6
 7    wsURL := "ws" + strings.TrimPrefix(server.URL, "http") + "/ws"
 8    conn, _, err := websocket.DefaultDialer.Dial(wsURL, nil)
 9    if err != nil {
10        t.Fatalf("dial websocket: %v", err)
11    }
12    t.Cleanup(func() {
13        _ = conn.Close()
14    })
15
16    return conn, server
17}

Helper 負責重複 setup。測試本文仍應清楚寫出「送什麼 message、期待什麼 response」。

【執行】action 測試要檢查協定語意

Action 測試的核心流程是送 client message、讀 server message、檢查協定欄位。

 1func TestSubscribeActionReturnsAcknowledgement(t *testing.T) {
 2    conn, _ := newTestWebSocket(t, newRouter())
 3
 4    request := ClientMessage{
 5        Action: ActionSubscribeTopic,
 6        Data: mustJSON(t, SubscribeTopicRequest{
 7            Topic: "alerts",
 8        }),
 9    }
10
11    if err := conn.WriteJSON(request); err != nil {
12        t.Fatalf("write subscribe: %v", err)
13    }
14
15    response := readServerMessage(t, conn)
16    if response.Type != "topic_subscribed" {
17        t.Fatalf("response type = %q, want topic_subscribed", response.Type)
18    }
19    if response.Topic != "alerts" {
20        t.Fatalf("response topic = %q, want alerts", response.Topic)
21    }
22}

這個測試檢查的是協定語意，不只是連線沒有斷。Subscribe 的成功條件是 server 明確回覆訂閱成功。

【執行】每次讀取前設定 deadline

WebSocket integration test 的核心風險是永久卡住。每次等待 server message 前，都應設定 read deadline。

 1func readServerMessage(t *testing.T, conn *websocket.Conn) ServerMessage {
 2    t.Helper()
 3
 4    if err := conn.SetReadDeadline(time.Now().Add(2 * time.Second)); err != nil {
 5        t.Fatalf("set read deadline: %v", err)
 6    }
 7
 8    var response ServerMessage
 9    if err := conn.ReadJSON(&response); err != nil {
10        t.Fatalf("read server message: %v", err)
11    }
12    return response
13}

Deadline 是測試保護。若 server 沒有送出預期訊息，測試會在合理時間內失敗，而不是卡住整個測試套件。

Timeout 不應過短。CI 可能比本機慢，測試應給足合理緩衝，但仍要能快速暴露失敗。

【執行】推送測試要先建立可觀察觸發點

Server push 的核心測試流程是先讓 client 訂閱 topic，再從 server 端觸發 broadcast，最後讀取 client 收到的 message。

 1func TestSubscribedClientReceivesBroadcast(t *testing.T) {
 2    hub := NewHub()
 3    go hub.Run()
 4
 5    conn, _ := newTestWebSocket(t, newRouterWithHub(hub))
 6
 7    writeClientMessage(t, conn, ClientMessage{
 8        Action: ActionSubscribeTopic,
 9        Data:   mustJSON(t, SubscribeTopicRequest{Topic: "alerts"}),
10    })
11    _ = readServerMessage(t, conn)
12
13    hub.Broadcast("alerts", ServerMessage{
14        Type:  "notification",
15        Topic: "alerts",
16    })
17
18    pushed := readServerMessage(t, conn)
19    if pushed.Type != "notification" {
20        t.Fatalf("pushed type = %q, want notification", pushed.Type)
21    }
22}

這個測試證明 subscribe state、hub broadcast、write pump 能透過真實 connection 協作。若只想測 Broadcast 是否檢查 topic，應寫 hub unit test，不必走 WebSocket。

【策略】非同步清理用 eventually，不用固定 sleep

連線清理測試的核心問題是 cleanup 通常非同步發生。測試應等待可觀察條件，而不是固定 sleep。

 1func eventually(t *testing.T, timeout time.Duration, condition func() bool) {
 2    t.Helper()
 3
 4    deadline := time.Now().Add(timeout)
 5    for time.Now().Before(deadline) {
 6        if condition() {
 7            return
 8        }
 9        time.Sleep(10 * time.Millisecond)
10    }
11
12    t.Fatalf("condition was not met within %s", timeout)
13}

使用方式：

 1func TestClientIsRemovedAfterClose(t *testing.T) {
 2    hub := NewHub()
 3    conn, _ := newTestWebSocket(t, newRouterWithHub(hub))
 4
 5    eventually(t, time.Second, func() bool {
 6        return hub.ClientCount() == 1
 7    })
 8
 9    _ = conn.Close()
10
11    eventually(t, time.Second, func() bool {
12        return hub.ClientCount() == 0
13    })
14}

eventually 不是任意等待；它等待具體條件。失敗時，測試會指出 cleanup 沒發生，而不是把時間耗掉後仍然不清楚原因。

【判讀】error action 應測協定，不只測 log

WebSocket action 失敗的核心語意是單次 action 失敗，不一定代表連線失敗。Integration test 應確認 server 回 error message，並且連線仍可繼續使用。

 1func TestUnknownActionReturnsErrorMessage(t *testing.T) {
 2    conn, _ := newTestWebSocket(t, newRouter())
 3
 4    writeClientMessage(t, conn, ClientMessage{
 5        Action: "unknown_action",
 6    })
 7
 8    response := readServerMessage(t, conn)
 9    if response.Type != "error" {
10        t.Fatalf("response type = %q, want error", response.Type)
11    }
12}

若設計上 unknown action 應直接關閉連線，也應明確測出 close 行為。重點是協定行為要可驗證，不要只依賴 server log。

本章不處理

本章先處理單一 Go server 內的 WebSocket 協定協作；跨節點 fan-out 與壓力測試，會在下列章節再往外延伸：

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

和 Go 教材的關係

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

• Go：如何新增一個即時訊息 action
• Go：read/write pump 模式
• Go：heartbeat、deadline 與連線清理
• Go：graceful shutdown 與 signal handling
• Go 進階：CI、fuzz、load test 與 chaos testing
• Backend：可靠性驗證流程

小結

WebSocket integration test 應少量覆蓋關鍵端到端協定：dial、送 action、收 response、server push、錯誤回應與 cleanup。測試要使用真實 httptest.Server，每次 read 前設定 deadline，等待非同步清理時使用 eventually。單元測試負責大量規則，integration test 負責證明真實連線能把規則串起來。

本模組承接模組一的並發主題：read pump / write pump 對應 goroutine ownership，heartbeat 對應 select loop 與 ticker，send buffer 對應 backpressure，訂閱集合對應共享狀態與 copy boundary。

章節列表

本模組使用的範例主題

本模組使用虛構的即時通知服務作為範例。Client 可以訂閱 topic，server 會依 topic 推送 notification、status update 或 error message。

範例只用來展示 Go WebSocket 服務設計，不假設讀者正在維護任何特定專案。

本模組的 Go 核心概念

• 用一個 read pump 負責 client 輸入。
• 用一個 write pump 負責所有 WebSocket 寫入。
• 用 channel 作為 client send queue。
• 用 context、done channel 或 hub unregister 管理連線生命週期。
• 用 ticker 實作 heartbeat，但由 write pump 統一寫 ping。
• 用 mutex 或 hub event loop 保護訂閱狀態。
• 用 non-blocking send 保護 hub 不被慢 client 卡住。

學習重點

學完本模組後，你應該能判斷：

1. 哪個 goroutine 可以讀 WebSocket，哪個 goroutine 可以寫 WebSocket
2. read pump、write pump、hub unregister 之間如何協作
3. heartbeat 失敗後應該走哪一條清理路徑
4. client action 應該在 router、usecase 還是 hub 裡處理
5. send buffer 滿載時應該丟棄、斷線、回錯或改用可靠儲存

章節粒度說明

WebSocket 章節依照連線生命週期拆分。Read/write pump、heartbeat、subscription routing、slow client 是四個不同責任；它們常在同一個 hub 或 client type 中互相呼叫，但教學上應分開建立模型。

如果只想處理單一問題，可以這樣查：

本模組不處理

本模組不討論 WebSocket 壓縮、水平擴展、跨節點廣播或完整身份驗證。這些都是實務重要主題，但必須先建立單一 Go process 內的連線生命週期與容量邊界；後續可接 跨節點 WebSocket、presence 與重連協定。

先備知識

• 模組一：進階並發模式
• Go 入門：標準庫 HTTP
• 知道 goroutine、channel、select、context 的基本用法

學習時間

預計 3-4 小時

對應 findings

待寫章節

• Protocol integration test 定義（跟 unit test / E2E 的邊界）
• WebSocket 協議測試實作（對真實 ttyd 驗證 frame type + auth handshake）
• HTTP contract test 設計
• CI 中的服務 fixture 管理（啟動/停止真實服務的 test harness）
• 成本判斷表：什麼時候值得、什麼時候用 contract test 替代

跨分類引用

• → monitoring 模組三 SDK 設計：SDK 的 transport 行為也需要 protocol test
• ← ux-design 模組三 輸入機制：輸入設計（整行 vs 逐字元）影響 protocol test 的斷言

本章目標

學完本章後，你將能夠：

1. 設計穩定的 client action envelope
2. 把 router、handler、usecase 與 client state 分開
3. 用訂閱集合表達 client 想收到的 topic
4. 在 broadcast 前檢查訂閱狀態
5. 測試 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；如果你要先回看語言教材，可以讀：

• Go：如何新增一個即時訊息 action
• Go：如何新增一種 domain event
• Go：事件融合
• Go：把 handler 邏輯拆成可測單元
• Backend：快取與 Redis
• Backend：訊息佇列與事件傳遞

小結

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

本章目標

學完本章後，你將能夠：

1. 理解單節點 hub 為什麼不夠
2. 看懂 presence store 與 broker 在系統中的角色
3. 設計 reconnect 後的補資料流程
4. 分辨訂閱路由、連線管理與授權邊界
5. 讓多台 server 在語意上看起來像同一個訊息系統

前置章節

• Go 進階：read pump / write pump 模式
• Go 進階：heartbeat、deadline 與連線清理
• Go 進階：訂閱模型與訊息路由
• Go 進階：慢客戶端與 send buffer 管理

後續撰寫方向

1. 多台 server 如何知道某個 topic 的訂閱者在哪些節點。
2. Presence store 如何記錄 client online、offline 與最後活動時間。
3. Broker fan-out 如何和每個節點本地 send buffer 策略銜接。
4. Client reconnect 如何使用 cursor、last event ID 或 snapshot 補資料。
5. Topic ACL 與 subscription authorization 應放在 router、usecase 還是 gateway。

【觀察】跨節點 WebSocket 的核心問題是狀態協調

WebSocket 協定解決的是單一連線的雙向通訊，但跨節點之後，真正麻煩的是狀態分散在多台 server。某個 client 可能連到 A 節點，但它關注的 topic 事件卻從 B 節點產生，這時就需要能夠路由、轉送與補資料。

所以跨節點 WebSocket 的問題不只是「能不能推送」，而是：

• 這個 client 現在在哪台 server
• 它訂閱了哪些 topic
• 推送失敗後要不要重送
• 重新連線後要從哪裡補回遺漏事件

【判讀】presence store 是操作查詢

presence store 的用途是讓系統知道某個 client 或節點目前大概在線上還是離線。它通常是操作性資料，不一定是業務真相。

常見欄位包括：

• client ID
• node ID
• connected at
• last seen
• subscription keys

這類資料要允許過期與清理，因為斷線、網路抖動與 crash 都可能讓狀態暫時不準。

【策略】reconnect 一定要有補資料設計

只靠重新連上 WebSocket 並不能保證使用者不漏訊息。當連線中斷時，常見的補資料方式有：

• last event ID
• cursor / offset
• snapshot + delta

選哪一種，取決於你的事件是否可排序、是否可回放，以及業務能容忍多大的缺口。

【執行】推送路徑通常要分三層

跨節點場景下，推送路徑常見會分成：

1. 事件產生端把訊息交給 broker 或 routing layer。
2. 節點收到後，交給本機 hub / connection manager。
3. write pump 再把訊息送到單一 client。

這樣可以維持單一寫入者原則，避免多個 goroutine 同時寫 WebSocket。

【延伸】授權應該在進入路由前就處理

Topic ACL 要在訂閱建立時就確認這個 client 是否有資格加入。這能減少不必要的 fan-out 與敏感資料外流。

本章不處理

本章不會選定特定 broker 或 presence database。重點是先讓跨節點責任可見，再依服務需求選擇 Redis、NATS、Kafka、PostgreSQL 或其他基礎設施。

和 Go 教材的關係

這一章承接的是 WebSocket 連線架構與事件路由；如果你要先回看語言教材，可以讀：

• Go 進階：read/write pump 模式
• Go 進階：heartbeat、deadline 與連線清理
• Go 進階：訂閱模型與訊息路由
• Go 進階：慢客戶端與 send buffer 管理

本章目標

學完本章後，你將能夠：

1. 分辨慢 client 對 hub、write pump、記憶體的影響
2. 用 bounded send channel 限制單一 client 的排隊量
3. 設計 queue full 時的 drop、disconnect、coalesce 策略
4. 在必要時用 byte budget 管理大型 payload
5. 測試 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 滿載的核心決策是訊息能不能遺失。不同資料類型需要不同策略。

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 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；如果你要先回看語言教材，可以讀：

• Go：channel：資料傳遞與 backpressure
• Go：非阻塞送出與事件丟棄策略
• Go：rate limiting 與 backpressure
• Go：bounded worker pool
• Backend：訊息佇列與事件傳遞
• Backend：快取與 Redis

小結

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

你應該看什麼

• Twitch - Go’s march to low latency GC

這個案例告訴我們什麼

1. Go 很適合低延遲、高事件量的即時系統。
2. 直播與聊天室會大量依賴長連線與狀態協調。
3. 可讀性在高壓力服務中仍然重要，因為維護者需要快速定位問題。

可對照的公開原始碼

• Go case studies page

Twitch 的核心系統原始碼不是公開教學重點，所以這一章更適合把官方案例本身當成第一手材料，再回到你的 WebSocket、channel 與 backpressure 章節對照。

目標讀者

• 已完成 Go 入門實戰指南 的工程師
• 想深入理解 Go 並發模型與 runtime 行為的開發者
• 需要維護長時間運行服務的人
• 想把 Go 服務從「能跑」提升到「可觀測、可測、可演進」的人

學習目標

1. 掌握 goroutine、channel、mutex 的進階使用邊界
2. 理解 WebSocket client lifecycle、heartbeat、buffer 與慢客戶端問題
3. 使用 pprof、runtime 記憶體限制與結構化日誌診斷服務
4. 設計 event-driven service 的資料邊界與去重策略
5. 建立並發測試、整合測試與可重現的時間控制
6. 能評估 Go 服務在生產環境的風險與操作策略
7. 知道單一 Go 服務延伸到跨節點與平台整合時，哪些責任會轉移到資料庫、queue、broker、observability pipeline 與部署平台

共用術語

進階篇延續入門篇的 action、command、domain event、repository、port、adapter、projection 等詞彙。若你需要確認這些詞在這套教材中的責任邊界，可以先回到 Go 教材核心術語。

與 Backend 教材的分工

Go 進階篇處理單一 Go 服務內部的高階能力：goroutine lifecycle、WebSocket pump、runtime 診斷、event boundary、race test、graceful shutdown 與 diagnostics endpoint。當內容開始碰到資料庫、Redis、RabbitMQ、Kafka、OpenTelemetry、Kubernetes 或 CI 平台操作時，就應該轉到跨語言的 Backend 服務實務指南。

模組七保留在進階篇裡，因為它要回答「Go 服務在跨出去以前，還需要先把哪些 port、訊號與測試合約準備好」。外部系統本身的選型與部署細節，則放在 Backend，讓不同語言都能共用同一套實作知識。

教學模組

模組一：進階並發模式

從服務實例理解 fan-in、fan-out、取消傳播與 backpressure ，先把並發語意說清楚。

• channel ownership 與關閉責任
• select loop 的生命週期設計
• 非阻塞送出與事件丟棄策略
• 共享狀態與複製邊界
• bounded worker pool
• rate limiting 與 backpressure

模組二：WebSocket 服務架構

把 WebSocket server 的連線、訂閱、推送與錯誤處理拆成可維護的邊界。

• read pump / write pump 模式
• heartbeat、deadline 與連線清理
• 訂閱模型與訊息路由
• 慢客戶端與 send buffer 管理

模組三：Runtime 與效能診斷

理解 Go runtime 如何在長時間運行服務中影響記憶體與排程行為。

• GC 與 memory limit
• pprof 基礎診斷流程
• goroutine leak 偵測
• 資料結構與 allocation 壓力

模組四：架構邊界與事件系統

用事件驅動架構拆解服務責任，讓來源、處理與狀態不再混在一起。

• 事件來源、處理流程與狀態邊界
• 事件去重與語義鍵設計
• Source of Truth：狀態邊界
• 多來源 event 融合

模組五：測試與可靠性

針對並發服務建立能真正揭露風險的測試，而不是只追求覆蓋率。

• 時間注入與狀態轉移測試
• WebSocket integration test
• race condition 檢查
• table-driven test 的設計邊界

模組六：生產操作

把本地服務推向可維護、可診斷、可部署的操作狀態。

• graceful shutdown 與 signal handling
• 健康檢查與診斷 endpoint
• 結構化日誌欄位設計
• 版本偵測與 feature gate

模組七：跨節點與平台整合

承接各章「本章不處理」的延伸邊界，把單一服務往外擴張時必須補上的責任整理成一條清楚路線。

• 資料庫 transaction 與 schema migration
• Durable queue、outbox 與 idempotency
• 跨節點 WebSocket、presence 與重連協定
• Observability pipeline、metrics 與 tracing
• Kubernetes、systemd 與 load balancer 合約
• CI、fuzz、load test 與 chaos testing

學習路徑

路徑 A：並發服務維護者

1模組一 → 模組四 → 模組五

重點：事件流、共享狀態、並發測試。

路徑 B：WebSocket/API 開發者

1模組二 → 模組六 → 模組五

重點：連線生命週期、訊息路由、操作診斷。

路徑 C：效能與可靠性工程師

1模組三 → 模組五 → 模組六

重點：pprof、goroutine leak、race check、服務操作。

路徑 D：完整學習

1模組一 → 模組二 → 模組三 → 模組四 → 模組五 → 模組六 → 模組七

按順序學習，建立完整的 Go 長時間運行服務模型。

主題延伸地圖

進階篇的章節會反覆碰到 log、time、state、event、WebSocket 與 testing。這些主題會在不同服務壓力下承擔不同責任；主題延伸地圖用來幫讀者辨識每一層的分工。

先備知識

本系列假設你已經完成 Go 入門實戰指南 的基礎部分，因為下面這些章節會直接沿用那些概念：

• 模組三：標準庫實戰
• 模組四：並發模型
• 模組五：錯誤處理與測試

每章結構

每章都採用「由淺到深」的結構，先說明問題，再切到設計與實作：

1. 原理層：這個機制解決什麼問題
2. 設計層：在服務架構中如何切責任
3. 實作層：用簡化範例程式碼看具體做法
4. 實戰檢查：維護時要確認哪些風險

文件版本：v0.1.0 最後更新：2026-04-22 系列狀態：核心初稿完成，延伸模組規劃中

192 個 unit test 全綠、實機部署後全部功能壞掉。

這不是測試寫得差 — 每個 test 都有明確斷言、覆蓋了正常和錯誤路徑。問題出在測試策略的結構：所有 test 都用 FakeWebSocketChannel 替代真實 WebSocket，永遠不會觸碰真實協議行為。結果是 mock 和真實服務之間的差異，在整個測試套件中完全不可見。

本文拆解三個被 mock 遮蔽的真實問題、分析 mock 遮蔽的機制、提出三層測試策略作為防護。

三個被 Mock 遮蔽的真實問題

問題 1：text frame vs binary frame

ttyd 的 WebSocket 協議期望 text frame，Flutter 的 WebSocketChannel.sink.add(Uint8List) 預設發送 binary frame。兩者在 WebSocket 協議層是不同的 opcode（0x1 text vs 0x2 binary），ttyd 收到 binary frame 會靜默忽略。

 1// 原始寫法 — Uint8List 走 binary frame，ttyd 靜默忽略
 2void sendData(dynamic data) {
 3  _channel!.sink.add(data); // data 是 Uint8List → binary frame
 4}
 5
 6// 修正 — 轉成 String 走 text frame
 7void sendData(dynamic data) {
 8  if (data is Uint8List) {
 9    _channel!.sink.add(String.fromCharCodes(data)); // text frame
10  } else {
11    _channel!.sink.add(data);
12  }
13}