@pickleball/expo-sdk 0.1.1 → 1.0.0

package/src/device-agent/mqtt-channel.ts

@@ -0,0 +1,379 @@
+import {
+  CONNACK_REASON,
+  decodePackets,
+  encodeConnect,
+  encodeDisconnect,
+  encodePingReq,
+  encodePublish,
+  encodePuback,
+  encodeSubscribe,
+  type MqttPacket,
+} from "./mqtt-codec";
+
+/**
+ * Kênh MQTT của máy camera — vòng đời kết nối trên WebSocket.
+ *
+ * Vai trò trong kiến trúc: đây là "device plane". Presence do broker phát hiện
+ * ở tầng TCP (LWT) chứ không phải do server đoán từ nhịp heartbeat, nên máy
+ * chết được biết trong ~45s, và biết TỨC THÌ khi app đóng kết nối sạch. Lệnh
+ * start/stop cũng đi đường này; Convex websocket + poll 30s vẫn giữ nguyên làm
+ * lưới an toàn (broker sập không được giết match-start).
+ *
+ * Module này KHÔNG import `@pickleball/shared`: hợp đồng topic/ngưỡng do phía
+ * app truyền vào. Lý do là gói SDK này được publish ra npm và Metro đọc thẳng
+ * `src/`, nên một import workspace ở đây sẽ vỡ khi app ngoài repo cài gói.
+ * Nguồn duy nhất của hợp đồng vẫn là `packages/shared/src/realtime.ts` — chỉ
+ * khác là chỗ nối dây nằm ở app first-party.
+ */
+
+/** Bề mặt WebSocket tối thiểu mà kênh cần — đủ để test thay bằng đồ giả. */
+export interface MqttSocket {
+  binaryType: string;
+  send(data: ArrayBufferView | ArrayBuffer): void;
+  close(): void;
+  onopen: (() => void) | null;
+  onmessage: ((event: { data: unknown }) => void) | null;
+  onerror: ((event: unknown) => void) | null;
+  onclose: ((event: { code?: number }) => void) | null;
+}
+
+export interface MqttChannelOptions {
+  /** wss://mqtt.cabinvn.com/mqtt */
+  url: string;
+  deviceId: string;
+  /** Token bền của máy — broker chuyển thẳng cho auth-hook Convex. */
+  deviceToken: string;
+  topics: { status: string; cmd: string; cfg: string; evt: string; score: string };
+  /** Payload retained lúc kết nối + payload LWT lúc rớt. */
+  statusPayload: (online: boolean) => string;
+  keepaliveS: number;
+  /** Thang backoff (ms); phần tử cuối được lặp lại mãi. */
+  reconnectDelaysMs: readonly number[];
+  onMessage?: (topic: string, payload: string) => void;
+  onConnectionChange?: (connected: boolean) => void;
+  /** Auth bị từ chối (token thu hồi / máy chưa claim) — để app log/khai báo. */
+  onAuthRejected?: (reason: string) => void;
+}
+
+export interface MqttChannelDeps {
+  createSocket?: (url: string, protocols: string[]) => MqttSocket;
+  setTimeout?: (fn: () => void, ms: number) => unknown;
+  clearTimeout?: (handle: unknown) => void;
+  now?: () => number;
+  /** Jitter ±20% chống bão reconnect đồng loạt sau khi broker restart. */
+  random?: () => number;
+}
+
+/**
+ * Sức khoẻ kênh cho quyết định giãn nhịp beat. `isConnected()` KHÔNG đủ: nối
+ * được mà chưa SUBACK thì máy không nghe được lệnh nào, còn TCP mở mà broker
+ * chết thì `connected` vẫn true tới tận keepalive kế.
+ */
+export interface MqttChannelHealth {
+  connected: boolean;
+  subscribed: boolean;
+  lastInboundAt: number;
+  healthySince: number;
+}
+
+export interface MqttChannel {
+  start(): void;
+  /** Đóng CHỦ ĐỘNG: gửi DISCONNECT nên broker KHÔNG bắn LWT. */
+  stop(): void;
+  isConnected(): boolean;
+  health(): MqttChannelHealth;
+  publish(topic: string, payload: string, opts?: { qos?: 0 | 1; retain?: boolean }): boolean;
+}
+
+/**
+ * Auth hỏng thì đừng quay số theo thang thường: token bị thu hồi hoặc máy chưa
+ * được claim là trạng thái kéo dài hàng phút tới hàng giờ, mà mỗi lần thử là
+ * một lượt gọi auth-hook Convex. 5 phút là đủ thưa để 1.000 máy hỏng cùng lúc
+ * cũng không thành bão, vẫn đủ dày để máy vừa được claim tự vào trong 5 phút.
+ */
+const AUTH_RETRY_MS = 5 * 60_000;
+
+export function createMqttChannel(
+  o: MqttChannelOptions,
+  deps: MqttChannelDeps = {},
+): MqttChannel {
+  const createSocket =
+    deps.createSocket ??
+    ((url, protocols) => new WebSocket(url, protocols) as unknown as MqttSocket);
+  const setTimer = deps.setTimeout ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = deps.clearTimeout ?? ((h) => clearTimeout(h as never));
+  const now = deps.now ?? (() => Date.now());
+  const random = deps.random ?? Math.random;
+
+  let socket: MqttSocket | null = null;
+  let buffer = new Uint8Array(0);
+  let connected = false;
+  let stopped = true;
+  let attempt = 0;
+  let packetId = 0;
+  let reconnectTimer: unknown = null;
+  let pingTimer: unknown = null;
+  let lastInboundAt = 0;
+  // Đã SUBACK đủ topic điều khiển chưa, và khoẻ liên tục từ lúc nào. Cả hai
+  // reset trong teardown: nối lại là phải chứng minh khoẻ lại từ đầu, không
+  // được thừa hưởng "đã khoẻ" của phiên kết nối trước.
+  let subscribed = false;
+  let healthySince = 0;
+
+  const nextPacketId = () => {
+    packetId = (packetId % 65_535) + 1;
+    return packetId;
+  };
+
+  const setConnected = (value: boolean) => {
+    if (connected === value) return;
+    connected = value;
+    o.onConnectionChange?.(value);
+  };
+
+  const clearTimers = () => {
+    if (reconnectTimer !== null) {
+      clearTimer(reconnectTimer);
+      reconnectTimer = null;
+    }
+    if (pingTimer !== null) {
+      clearTimer(pingTimer);
+      pingTimer = null;
+    }
+  };
+
+  const send = (bytes: Uint8Array): boolean => {
+    if (!socket) return false;
+    try {
+      socket.send(bytes);
+      return true;
+    } catch {
+      // Socket vừa chết giữa chừng — đóng để rơi vào nhánh reconnect chung,
+      // đừng ném lên trên: kênh này không được phép làm sập engine.
+      teardown(true);
+      return false;
+    }
+  };
+
+  const scheduleReconnect = (delayMs?: number) => {
+    if (stopped || reconnectTimer !== null) return;
+    const base =
+      delayMs ??
+      o.reconnectDelaysMs[Math.min(attempt, o.reconnectDelaysMs.length - 1)] ??
+      30_000;
+    const jitter = base === 0 ? 0 : base * 0.2 * (random() * 2 - 1);
+    attempt += 1;
+    reconnectTimer = setTimer(() => {
+      reconnectTimer = null;
+      open();
+    }, Math.max(0, Math.round(base + jitter)));
+  };
+
+  const teardown = (reconnect: boolean, delayMs?: number) => {
+    clearTimers();
+    setConnected(false);
+    subscribed = false;
+    healthySince = 0;
+    buffer = new Uint8Array(0);
+    const dead = socket;
+    socket = null;
+    if (dead) {
+      dead.onopen = null;
+      dead.onmessage = null;
+      dead.onerror = null;
+      dead.onclose = null;
+      try {
+        dead.close();
+      } catch {
+        // Đóng socket đã chết không phải lỗi.
+      }
+    }
+    if (reconnect) scheduleReconnect(delayMs);
+  };
+
+  /**
+   * Nhịp giữ kết nối. Gửi PINGREQ ở 3/4 keepalive, và nếu quá 1,5× keepalive mà
+   * KHÔNG nhận được byte nào thì tự coi là chết và nối lại — WiFi sân hay rơi
+   * vào cảnh socket "còn mở" trên giấy tờ nhưng không gói nào qua được nữa,
+   * lúc đó chỉ có phía mình tự nghi ngờ mới thoát ra được.
+   */
+  const armPing = () => {
+    if (pingTimer !== null) clearTimer(pingTimer);
+    pingTimer = setTimer(() => {
+      pingTimer = null;
+      if (!socket) return;
+      if (now() - lastInboundAt > o.keepaliveS * 1500) {
+        teardown(true);
+        return;
+      }
+      send(encodePingReq());
+      armPing();
+    }, Math.max(1000, Math.round(o.keepaliveS * 750)));
+  };
+
+  const handlePacket = (p: MqttPacket) => {
+    switch (p.type) {
+      case "connack": {
+        if (p.returnCode !== 0) {
+          const reason = CONNACK_REASON[p.returnCode] ?? `mã ${p.returnCode}`;
+          o.onAuthRejected?.(reason);
+          // 4/5 = sai creds hoặc bị auth-hook từ chối → nghỉ dài, xem AUTH_RETRY_MS.
+          teardown(true, p.returnCode === 4 || p.returnCode === 5 ? AUTH_RETRY_MS : undefined);
+          return;
+        }
+        attempt = 0;
+        setConnected(true);
+        // Trình tự sau CONNACK: khai "tôi sống" (retained, để dashboard thấy
+        // ngay cả khi bridge vừa khởi động lại) rồi mới nhận lệnh.
+        send(
+          encodePublish({
+            topic: o.topics.status,
+            payload: o.statusPayload(true),
+            qos: 1,
+            retain: true,
+            packetId: nextPacketId(),
+          }),
+        );
+        send(
+          encodeSubscribe(nextPacketId(), [
+            { topic: o.topics.cmd, qos: 1 },
+            { topic: o.topics.cfg, qos: 1 },
+            // Tỉ số trận đang ghi (retained) — reconnect là nhận ngay bản mới nhất.
+            { topic: o.topics.score, qos: 1 },
+          ]),
+        );
+        armPing();
+        return;
+      }
+      case "suback": {
+        // Broker xác nhận đã đăng ký topic điều khiển. Trước mốc này máy nối
+        // được nhưng KHÔNG nghe được lệnh nào — không tính là kênh khoẻ.
+        // Mã ≥ 0x80 là broker TỪ CHỐI (ACL) → giữ subscribed = false.
+        if (p.codes.every((c) => c < 0x80)) {
+          subscribed = true;
+          if (healthySince === 0) healthySince = now();
+        }
+        return;
+      }
+      case "publish": {
+        // QoS1 phải ack, không thì broker gửi lại mãi.
+        if (p.qos === 1 && p.packetId !== undefined) send(encodePuback(p.packetId));
+        o.onMessage?.(p.topic, p.payload);
+        return;
+      }
+      default:
+        return;
+    }
+  };
+
+  const open = () => {
+    if (stopped || socket) return;
+    let s: MqttSocket;
+    try {
+      s = createSocket(o.url, ["mqtt"]);
+    } catch {
+      scheduleReconnect();
+      return;
+    }
+    socket = s;
+    s.binaryType = "arraybuffer";
+    lastInboundAt = now();
+
+    s.onopen = () => {
+      if (socket !== s) return;
+      send(
+        encodeConnect({
+          clientId: o.deviceId,
+          username: o.deviceId,
+          password: o.deviceToken,
+          keepaliveS: o.keepaliveS,
+          cleanSession: true,
+          will: {
+            topic: o.topics.status,
+            payload: o.statusPayload(false),
+            qos: 1,
+            retain: true,
+          },
+        }),
+      );
+    };
+
+    s.onmessage = (event) => {
+      if (socket !== s) return;
+      const data = event.data;
+      let chunk: Uint8Array | null = null;
+      if (data instanceof ArrayBuffer) {
+        chunk = new Uint8Array(data);
+      } else if (ArrayBuffer.isView(data)) {
+        // Copy chứ không tạo view lên buffer nền: runtime có thể tái dùng
+        // buffer đó cho frame sau, mà ta còn giữ phần gói dở qua nhiều lượt.
+        chunk = Uint8Array.from(data as unknown as ArrayLike<number>);
+      }
+      // RN trả Blob nếu binaryType không được tôn trọng — bỏ qua còn hơn ném.
+      if (!chunk) return;
+      lastInboundAt = now();
+      const merged = new Uint8Array(buffer.length + chunk.length);
+      merged.set(buffer, 0);
+      merged.set(chunk, buffer.length);
+      const { packets, rest } = decodePackets(merged);
+      // Copy phần dư (thường vài byte của gói chưa trọn) thay vì giữ subarray:
+      // view trỏ vào buffer cũ sẽ ghim cả frame vừa rồi trong bộ nhớ.
+      buffer = Uint8Array.from(rest);
+      for (const p of packets) handlePacket(p);
+    };
+
+    s.onerror = () => {
+      if (socket !== s) return;
+      teardown(true);
+    };
+
+    s.onclose = () => {
+      if (socket !== s) return;
+      teardown(true);
+    };
+  };
+
+  return {
+    start() {
+      if (!stopped) return;
+      stopped = false;
+      attempt = 0;
+      open();
+    },
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      // DISCONNECT sạch KHÔNG kích LWT, nên phải TỰ khai offline trước khi
+      // đóng: thiếu bước này thì máy chủ động gỡ ghép/tắt tính năng sẽ đứng
+      // "online" vĩnh viễn trên dashboard (retained cũ nằm lại trên broker).
+      if (socket && connected) {
+        send(
+          encodePublish({
+            topic: o.topics.status,
+            payload: o.statusPayload(false),
+            qos: 1,
+            retain: true,
+            packetId: nextPacketId(),
+          }),
+        );
+        send(encodeDisconnect());
+      }
+      teardown(false);
+    },
+    isConnected: () => connected,
+    health: () => ({ connected, subscribed, lastInboundAt, healthySince }),
+    publish(topic, payload, opts) {
+      if (!connected) return false;
+      const qos = opts?.qos ?? 0;
+      return send(
+        encodePublish({
+          topic,
+          payload,
+          qos,
+          retain: opts?.retain ?? false,
+          ...(qos === 1 ? { packetId: nextPacketId() } : {}),
+        }),
+      );
+    },
+  };
+}