@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/ws-alignment.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  createAlignedWsQueue,
+  createProtocolControlHandler,
+  createReconnectTracker,
+} from "./ws-alignment.ts";
+
+describe("aligned websocket queue", () => {
+  it("drops oldest frame when queue is full", () => {
+    const logs: string[] = [];
+    const queue = createAlignedWsQueue({ accountId: "default", log: (msg) => logs.push(msg), maxSize: 2 });
+
+    queue.enqueue({ eventName: "typing.update", traceId: "a", chatId: "c", wire: "a" });
+    queue.enqueue({ eventName: "typing.update", traceId: "b", chatId: "c", wire: "b" });
+    queue.enqueue({ eventName: "typing.update", traceId: "c", chatId: "c", wire: "c" });
+
+    expect(queue.snapshot().map((item) => item.traceId)).toEqual(["b", "c"]);
+    expect(logs.some((line) => line.includes("event=send_queue_drop"))).toBe(true);
+  });
+
+  it("keeps failed flush frame at the head", () => {
+    const queue = createAlignedWsQueue({ accountId: "default", log: () => {}, maxSize: 128 });
+    queue.enqueue({ eventName: "message.reply", traceId: "a", chatId: "c", wire: "a" });
+    queue.enqueue({ eventName: "message.reply", traceId: "b", chatId: "c", wire: "b" });
+
+    expect(() => queue.flush(() => { throw new Error("socket closed"); })).toThrow("socket closed");
+    expect(queue.snapshot().map((item) => item.traceId)).toEqual(["a", "b"]);
+  });
+
+  it("resets reconnect_count only after ready is stable for 5000ms", () => {
+    vi.useFakeTimers();
+    const logs: string[] = [];
+    const tracker = createReconnectTracker({ accountId: "default", log: (msg) => logs.push(msg) });
+
+    expect(tracker.connectStart()).toMatchObject({ attempt: 1, reconnectCount: 0 });
+    tracker.scheduleReconnect("connection_lost");
+    expect(tracker.connectStart()).toMatchObject({ attempt: 2, reconnectCount: 1 });
+    tracker.markReady();
+    vi.advanceTimersByTime(4999);
+    expect(tracker.snapshot().reconnectCount).toBe(1);
+    vi.advanceTimersByTime(1);
+    expect(tracker.snapshot().reconnectCount).toBe(0);
+    expect(logs).toContain(
+      "clawchat.ws event=reconnect_backoff_reset account_id=default attempt=2 reconnect_count=0 state=ready action=reset stable_ms=5000",
+    );
+    vi.useRealTimers();
+  });
+
+  it("answers JSON ping and logs JSON pong as protocol control", () => {
+    const logs: string[] = [];
+    const sent: string[] = [];
+    const handler = createProtocolControlHandler({
+      accountId: "default",
+      log: (msg) => logs.push(msg),
+      send: (wire) => sent.push(wire),
+    });
+
+    expect(
+      handler.handleInbound({
+        version: "2",
+        event: "ping",
+        trace_id: "trace-ping",
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    ).toBe(true);
+    expect(JSON.parse(sent[0]!)).toMatchObject({ event: "pong", trace_id: "trace-ping" });
+    expect(logs).toContain(
+      "clawchat.ws event=protocol_ping_received account_id=default attempt=1 reconnect_count=0 state=ready action=send_pong trace_id=trace-ping",
+    );
+
+    expect(
+      handler.handleInbound({
+        version: "2",
+        event: "pong",
+        trace_id: "trace-pong",
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    ).toBe(true);
+    expect(logs).toContain(
+      "clawchat.ws event=protocol_pong_received account_id=default attempt=1 reconnect_count=0 state=ready action=ignore trace_id=trace-pong",
+    );
+  });
+
+  it("logs heartbeat timeout and schedules reconnect", () => {
+    const logs: string[] = [];
+    const reconnects: string[] = [];
+    const handler = createProtocolControlHandler({
+      accountId: "default",
+      log: (msg) => logs.push(msg),
+      send: () => {},
+      scheduleReconnect: (reason) => reconnects.push(reason),
+    });
+
+    handler.heartbeatTimeout(10000);
+
+    expect(logs).toContain(
+      "clawchat.ws event=heartbeat_timeout account_id=default attempt=1 reconnect_count=0 state=ready action=reconnect timeout_ms=10000",
+    );
+    expect(reconnects).toEqual(["heartbeat_timeout"]);
+  });
+});

package/src/ws-alignment.ts

@@ -0,0 +1,275 @@
+import { formatWsLog } from "./ws-log.ts";
+
+export const MAX_WS_QUEUE_SIZE = 128;
+
+export interface AlignedWsQueueItem {
+  eventName: string;
+  traceId: string;
+  chatId?: string;
+  wire: string;
+  onWrite?: () => void;
+  onDrop?: () => void;
+}
+
+export interface CreateAlignedWsQueueOptions {
+  accountId: string;
+  log: (msg: string) => void;
+  maxSize?: number;
+  attempt?: number;
+  reconnectCount?: number;
+  state?: string;
+  context?: () => WsLogContext;
+}
+
+export interface WsLogContext {
+  attempt: number;
+  reconnectCount: number;
+  state: string;
+}
+
+export function createAlignedWsQueue(options: CreateAlignedWsQueueOptions) {
+  const maxSize = options.maxSize ?? MAX_WS_QUEUE_SIZE;
+  const queue: AlignedWsQueueItem[] = [];
+  const context = (): WsLogContext =>
+    options.context?.() ?? {
+      attempt: options.attempt ?? 1,
+      reconnectCount: options.reconnectCount ?? 0,
+      state: options.state ?? "ready",
+    };
+
+  const logFrame = (
+    event: string,
+    action: string,
+    item: AlignedWsQueueItem,
+    fields: Array<[string, string | number | boolean | null | undefined]> = [],
+    logState?: string,
+  ) => {
+    const current = context();
+    options.log(
+      formatWsLog({
+        event,
+        accountId: options.accountId,
+        attempt: current.attempt,
+        reconnectCount: current.reconnectCount,
+        state: logState ?? current.state,
+        action,
+        fields: [
+          ["event_name", item.eventName],
+          ["trace_id", item.traceId],
+          ["chat_id", item.chatId],
+          ...fields,
+        ],
+      }),
+    );
+  };
+
+  return {
+    enqueue(item: AlignedWsQueueItem) {
+      if (queue.length >= maxSize) {
+        const dropped = queue.shift();
+        if (dropped) {
+          logFrame(
+            "send_queue_drop",
+            "drop_oldest",
+            dropped,
+            [
+              ["queue_size", queue.length],
+              ["queue_max", maxSize],
+            ],
+            context().state,
+          );
+          dropped.onDrop?.();
+        }
+      }
+      queue.push(item);
+      logFrame("send_queued", "queue", item, [["queue_size", queue.length]]);
+    },
+
+    flush(write: (wire: string) => void) {
+      while (queue.length > 0) {
+        const item = queue[0]!;
+        try {
+          write(item.wire);
+          queue.shift();
+          item.onWrite?.();
+          logFrame("send_flush", "send", item, [["remaining", queue.length]], "ready");
+        } catch (err) {
+          logFrame("send_failed", "requeue_reconnect", item, [["queue_size", queue.length]]);
+          throw err;
+        }
+      }
+    },
+
+    remove(item: AlignedWsQueueItem) {
+      const index = queue.indexOf(item);
+      if (index < 0) return false;
+      queue.splice(index, 1);
+      return true;
+    },
+
+    snapshot() {
+      return [...queue];
+    },
+  };
+}
+
+export interface CreateReconnectTrackerOptions {
+  accountId: string;
+  log: (msg: string) => void;
+  stableResetMs?: number;
+  initialDelayMs?: number;
+  maxDelayMs?: number;
+}
+
+export function createReconnectTracker(options: CreateReconnectTrackerOptions) {
+  const stableResetMs = options.stableResetMs ?? 5000;
+  let attempt = 0;
+  let reconnectCount = 0;
+  let state = "idle";
+  let stableResetTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const clearStableReset = () => {
+    if (!stableResetTimer) return;
+    clearTimeout(stableResetTimer);
+    stableResetTimer = undefined;
+  };
+
+  return {
+    connectStart() {
+      clearStableReset();
+      attempt += 1;
+      state = "connecting";
+      return { attempt, reconnectCount };
+    },
+
+    scheduleReconnect(
+      reason: string,
+      details: { delayMs?: number; maxDelayMs?: number } = {},
+    ) {
+      clearStableReset();
+      reconnectCount += 1;
+      state = "reconnecting";
+      if (details.delayMs !== undefined || details.maxDelayMs !== undefined) {
+        options.log(
+          formatWsLog({
+            event: "reconnect_scheduled",
+            accountId: options.accountId,
+            attempt,
+            reconnectCount,
+            state: "reconnecting",
+            action: "wait",
+            fields: [
+              ["delay_ms", details.delayMs],
+              ["max_delay_ms", details.maxDelayMs ?? options.maxDelayMs],
+              ["reason", reason],
+            ],
+          }),
+        );
+      }
+      return { attempt, reconnectCount };
+    },
+
+    markReady() {
+      clearStableReset();
+      state = "ready";
+      stableResetTimer = setTimeout(() => {
+        reconnectCount = 0;
+        options.log(
+          formatWsLog({
+            event: "reconnect_backoff_reset",
+            accountId: options.accountId,
+            attempt,
+            reconnectCount,
+            state: "ready",
+            action: "reset",
+            fields: [["stable_ms", stableResetMs]],
+          }),
+        );
+        stableResetTimer = undefined;
+      }, stableResetMs);
+    },
+
+    markClosed() {
+      clearStableReset();
+      state = "closed";
+    },
+
+    snapshot() {
+      return { attempt, reconnectCount, state };
+    },
+  };
+}
+
+export interface ProtocolControlEnvelope {
+  version?: string;
+  event: string;
+  trace_id?: string;
+  emitted_at?: number;
+  payload?: unknown;
+}
+
+export interface CreateProtocolControlHandlerOptions {
+  accountId: string;
+  log: (msg: string) => void;
+  send: (wire: string) => void;
+  scheduleReconnect?: (reason: string) => void;
+  attempt?: number;
+  reconnectCount?: number;
+  state?: string;
+  context?: () => WsLogContext;
+}
+
+export function createProtocolControlHandler(options: CreateProtocolControlHandlerOptions) {
+  const context = (): WsLogContext =>
+    options.context?.() ?? {
+      attempt: options.attempt ?? 1,
+      reconnectCount: options.reconnectCount ?? 0,
+      state: options.state ?? "ready",
+    };
+  const logControl = (
+    event: string,
+    action: string,
+    fields: Array<[string, string | number | boolean | null | undefined]>,
+  ) => {
+    const current = context();
+    options.log(
+      formatWsLog({
+        event,
+        accountId: options.accountId,
+        attempt: current.attempt,
+        reconnectCount: current.reconnectCount,
+        state: current.state,
+        action,
+        fields,
+      }),
+    );
+  };
+
+  return {
+    handleInbound(env: ProtocolControlEnvelope): boolean {
+      if (env.event === "ping") {
+        logControl("protocol_ping_received", "send_pong", [["trace_id", env.trace_id]]);
+        options.send(
+          JSON.stringify({
+            version: "2",
+            event: "pong",
+            trace_id: env.trace_id ?? "-",
+            emitted_at: Date.now(),
+            payload: {},
+          }),
+        );
+        return true;
+      }
+      if (env.event === "pong") {
+        logControl("protocol_pong_received", "ignore", [["trace_id", env.trace_id]]);
+        return true;
+      }
+      return false;
+    },
+
+    heartbeatTimeout(timeoutMs: number) {
+      logControl("heartbeat_timeout", "reconnect", [["timeout_ms", timeoutMs]]);
+      options.scheduleReconnect?.("heartbeat_timeout");
+    },
+  };
+}