// 客户端发起（new WebSocket 的瞬间）：
GET /sensor-feed HTTP/1.1
Host: factory.example.com
Upgrade: websocket            ⭐ 请求协议升级
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==     ⭐ 随机 base64（服务器用来生成校验值）
Sec-WebSocket-Version: 13

// 服务器同意（101 切换协议）：
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=  ⭐ Key 的 SHA-1 + 固定盐（防普通 HTTP 服务器误响应）

// —— 从这个字节之后，这条连接说的不再是 HTTP ——

帧结构（示意）：
┌─────────┬─────────┬────────────┬──────────────┐
│ FIN/opcode│  Mask  │ Payload Len │   Payload    │
│  ~2 字节  │ 4 字节  │  0~8 字节   │   实际数据    │
└─────────┴─────────┴────────────┴──────────────┘

对比：
HTTP 每请求头：几百字节起
WebSocket 帧头：2~14 字节

/**
 * WebSocket 最小可用示例：连接本地测试服务器
 */
function connect(): WebSocket {
  const ws = new WebSocket("ws://localhost:8080/sensor-feed");

  // ⭐ 必须在 connect 前（即构造后立即）设置，否则二进制帧会被当 Blob
  ws.binaryType = "arraybuffer";

  // 四个事件 = WS 生命周期的全部
  ws.onopen = () => {
    console.log("连接建立");
    ws.send(JSON.stringify({ type: "subscribe", channels: ["furnace-1"] }));
  };
  ws.onmessage = (ev: MessageEvent) => {
    if (typeof ev.data === "string") {
      const msg = JSON.parse(ev.data);
      console.log("文本消息", msg);
    } else {
      console.log("二进制帧", new Uint8Array(ev.data));   // Day 59 的主战场
    }
  };
  ws.onerror = () => console.error("连接错误（通常跟着一个 close）");
  ws.onclose = (ev: CloseEvent) => {
    console.log(`连接关闭 code=${ev.code} reason=${ev.reason} clean=${ev.wasClean}`);
  };
  return ws;
}

CONNECTING(0) ──open──▶ OPEN(1) ──close──▶ CLOSING(2) ──▶ CLOSED(3)
     │                    │
     └── 握手失败 ─────────┘→ CLOSED

// 发送前必须检查状态（CONNECTING 状态 send 会直接抛异常！）
if (ws.readyState === WebSocket.OPEN) {
  ws.send(data);
}

HTTP：无状态 → 一个请求失败，下一个请求全新开始，无损
WS：  有状态 → 断连后：
      1. 服务器推的消息全部丢失（客户端根本不知道错过了什么）
      2. 订阅状态、会话上下文全部清零
      3. 重连后一切要从头建立（重新 subscribe）

/**
 * WebSocket 连接管理器：类型化消息 + 事件订阅
 * Day 58 将扩展心跳与重连，Day 61 将扩展缓冲与补传
 */
export type WsMessage =
  | { type: "snapshot"; payload: PanelSnapshot }
  | { type: "subscribe"; channels: string[] }
  | { type: "ack"; code: number };

export interface PanelSnapshot {
  ts: number;
  devices: { id: string; temperature: number }[];
}

export class WsConnection {
  private ws: WebSocket | null = null;
  private msgListeners = new Set<(msg: WsMessage) => void>();
  private stateListeners = new Set<(open: boolean) => void>();

  constructor(private url: string) {}

  /** 建立连接（幂等：已连接则跳过） */
  connect(): void {
    if (this.ws && this.ws.readyState <= WebSocket.OPEN) return;

    const ws = new WebSocket(this.url);
    ws.binaryType = "arraybuffer";

    ws.onopen = () => this.stateListeners.forEach((l) => l(true));
    ws.onmessage = (ev) => this.dispatch(ev.data);
    ws.onclose = () => {
      this.stateListeners.forEach((l) => l(false));
      this.ws = null;    // 置空：下次 connect 可以重建
    };
    // onerror 不单独处理：浏览器保证 error 之后必有 close，统一在 close 处理
    this.ws = ws;
  }

  /** 发送消息（只有 OPEN 状态才允许） */
  send(msg: WsMessage): boolean {
    if (this.ws?.readyState !== WebSocket.OPEN) return false;
    this.ws.send(JSON.stringify(msg));
    return true;
  }

  /** 订阅消息（返回退订函数——第 1 周的发布订阅模式复用） */
  onMessage(listener: (msg: WsMessage) => void): () => void {
    this.msgListeners.add(listener);
    return () => this.msgListeners.delete(listener);
  }

  /** 订阅连接状态变化 */
  onState(listener: (open: boolean) => void): () => void {
    this.stateListeners.add(listener);
    return () => this.stateListeners.delete(listener);
  }

  /** 主动关闭 */
  close(): void {
    this.ws?.close(1000, "client-shutdown");
    this.ws = null;
  }

  /** 消息分发：文本解析 JSON，二进制留给 Day 59 */
  private dispatch(data: string | ArrayBuffer): void {
    if (typeof data === "string") {
      try {
        this.msgListeners.forEach((l) => l(JSON.parse(data)));
      } catch {
        console.warn("无法解析的消息", data);
      }
    }
  }
}

/**
 * 按环境返回 WS 地址
 * 开发：本地测试服务器；生产：走 wss + 网关域名
 */
export function wsUrl(env: "dev" | "prod" = "dev"): string {
  if (env === "prod") return "wss://api.factory.example.com/sensor-feed";
  return `ws://${location.hostname}:8080/sensor-feed`;
}

npm install ws @types/ws

/**
 * 本地 WebSocket 测试服务器（Node + ws）
 * 功能：接受连接、按订阅推送模拟传感器数据、支持手动踢连接（测试重连）
 */
import { WebSocketServer, WebSocket } from "ws";

const wss = new WebSocketServer({ port: 8080, path: "/sensor-feed" });

console.log("WS 服务器已启动 ws://localhost:8080/sensor-feed");

wss.on("connection", (ws: WebSocket) => {
  console.log("客户端接入");

  // 每秒推送一帧模拟数据
  const timer = setInterval(() => {
    if (ws.readyState !== WebSocket.OPEN) return;
    const payload = {
      type: "snapshot",
      payload: {
        ts: Date.now(),
        devices: [
          { id: "f1", temperature: 80 + Math.random() * 10 },
          { id: "f2", temperature: 78 + Math.random() * 10 },
        ],
      },
    };
    ws.send(JSON.stringify(payload));
  }, 1000);

  ws.on("message", (raw) => {
    const msg = JSON.parse(raw.toString());
    if (msg.type === "subscribe") {
      ws.send(JSON.stringify({ type: "ack", code: 200 }));
    }
  });

  ws.on("close", () => {
    clearInterval(timer);
    console.log("客户端断开");
  });

  // 测试用：10 秒后主动踢掉连接（模拟服务器重启，验证客户端 close code 1006 处理）
  // setTimeout(() => ws.terminate(), 10_000);
});

npx tsx server.ts        # 或编译后 node dist/server.js