@pylonsync/sync 0.3.202 → 0.3.203

package/src/test-harness/transport.ts

@@ -0,0 +1,256 @@
+// Fetch + WebSocket mocks that route engine traffic to a TestServer.
+//
+// We intentionally don't reimplement the wire format here — every
+// path the engine actually calls lives in `handle()` and produces
+// exactly the JSON shape the engine parses. New engine paths require
+// a new branch here (which is the point: forces the harness to stay
+// honest about what the engine sends).
+
+import type { Row } from "../types";
+import type { TestServer } from "./server";
+
+export interface TransportHandle {
+  /** Token the engine is currently sending as Authorization: Bearer */
+  currentToken: () => string | undefined;
+  /** Set / clear the active token (mirrors localStorage flips). */
+  setToken: (token: string | undefined) => void;
+  /** Number of `fetch` calls observed — assert against this in
+   *  tests that need to confirm "nothing more was requested." */
+  fetchCount: () => number;
+  /** Number of WS connections opened so far. */
+  wsConnectCount: () => number;
+  /** Tear down the global stubs. */
+  restore: () => void;
+}
+
+interface MockResponse {
+  status: number;
+  body: unknown;
+  headers?: Record<string, string>;
+}
+
+export function installTransport(server: TestServer): TransportHandle {
+  let token: string | undefined;
+  let fetchCount = 0;
+  let wsConnectCount = 0;
+
+  const originalFetch = globalThis.fetch;
+  const originalWS = (globalThis as { WebSocket?: unknown }).WebSocket;
+
+  globalThis.fetch = (async (
+    input: RequestInfo | URL,
+    init?: RequestInit,
+  ): Promise<Response> => {
+    fetchCount += 1;
+    const url = typeof input === "string" ? input : input.toString();
+    const method = (init?.method ?? "GET").toUpperCase();
+    const authHeader = readAuthHeader(init);
+    // If the request didn't include Authorization but our test rig
+    // has a "current token", forward it the way the engine actually
+    // does. The engine reads from localStorage; we shortcut here
+    // because the engine's currentToken() comes from the storage
+    // adapter we'd otherwise need to mock.
+    const effectiveToken = authHeader ?? token;
+
+    const result = await handle(server, method, url, effectiveToken, init);
+    const json = result.body == null ? "" : JSON.stringify(result.body);
+    return new Response(json, {
+      status: result.status,
+      headers: {
+        "content-type": "application/json",
+        ...(result.headers ?? {}),
+      },
+    });
+  }) as typeof fetch;
+
+  // Minimal WebSocket stub. The engine calls `new WebSocket(url)`,
+  // attaches onopen/onmessage/onclose, and posts session-changed +
+  // change events. We hand it a controllable EventTarget the
+  // TestServer subscribes to.
+  class MockWebSocket extends EventTarget {
+    static readonly CONNECTING = 0;
+    static readonly OPEN = 1;
+    static readonly CLOSING = 2;
+    static readonly CLOSED = 3;
+    readyState = 0;
+    binaryType: "blob" | "arraybuffer" = "blob";
+    url: string;
+    protocol = "";
+    onopen: ((ev: Event) => void) | null = null;
+    onclose: ((ev: Event) => void) | null = null;
+    onmessage: ((ev: MessageEvent) => void) | null = null;
+    onerror: ((ev: Event) => void) | null = null;
+    private unsubscribe: (() => void) | null = null;
+    private boundToken: string | undefined;
+
+    constructor(url: string, protocols?: string | string[]) {
+      super();
+      this.url = url;
+      wsConnectCount += 1;
+      // The engine encodes the token as `bearer.<percent-encoded>` in
+      // the WS subprotocol when one is set. Decode it so the harness
+      // can route this connection to the right subscriber bucket
+      // independently of any localStorage state.
+      const protoToken = extractBearerFromProtocols(protocols);
+      this.boundToken = protoToken ?? token;
+      const auth = server.authContextFor(this.boundToken);
+      if (auth.userId) {
+        this.unsubscribe = server.subscribe(auth.userId, (msg) => {
+          const event = new MessageEvent("message", {
+            data: JSON.stringify(msg),
+          });
+          this.dispatchEvent(event);
+          this.onmessage?.(event);
+        });
+      }
+      // Fire onopen on the next microtask so listeners attached
+      // synchronously after construction still see it.
+      queueMicrotask(() => {
+        this.readyState = 1;
+        const ev = new Event("open");
+        this.dispatchEvent(ev);
+        this.onopen?.(ev);
+      });
+    }
+
+    send(data: string): void {
+      // Capture outbound client messages so tests can assert that
+      // `reactive-subscribe`, `crdt-subscribe`, etc., were actually
+      // emitted by the engine. The real server would dispatch on
+      // these; the harness just records them.
+      try {
+        const parsed = JSON.parse(data);
+        server.recordClientWsMessage(this.boundToken, parsed);
+      } catch {
+        server.recordClientWsMessage(this.boundToken, data);
+      }
+    }
+
+    close(): void {
+      this.readyState = 3;
+      this.unsubscribe?.();
+      this.unsubscribe = null;
+      const ev = new Event("close");
+      this.dispatchEvent(ev);
+      this.onclose?.(ev);
+    }
+  }
+  (globalThis as { WebSocket?: unknown }).WebSocket = MockWebSocket;
+
+  return {
+    currentToken: () => token,
+    setToken: (t) => {
+      token = t;
+    },
+    fetchCount: () => fetchCount,
+    wsConnectCount: () => wsConnectCount,
+    restore: () => {
+      globalThis.fetch = originalFetch;
+      if (originalWS) {
+        (globalThis as { WebSocket?: unknown }).WebSocket = originalWS;
+      } else {
+        delete (globalThis as { WebSocket?: unknown }).WebSocket;
+      }
+    },
+  };
+}
+
+function readAuthHeader(init: RequestInit | undefined): string | undefined {
+  if (!init?.headers) return undefined;
+  const headersInit = init.headers;
+  let raw: string | null = null;
+  if (headersInit instanceof Headers) {
+    raw = headersInit.get("Authorization") ?? headersInit.get("authorization");
+  } else if (Array.isArray(headersInit)) {
+    for (const [k, v] of headersInit) {
+      if (k.toLowerCase() === "authorization") {
+        raw = v;
+        break;
+      }
+    }
+  } else {
+    const h = headersInit as Record<string, string>;
+    raw = h.Authorization ?? h.authorization ?? null;
+  }
+  if (!raw) return undefined;
+  return raw.startsWith("Bearer ") ? raw.slice("Bearer ".length) : raw;
+}
+
+function extractBearerFromProtocols(
+  protocols: string | string[] | undefined,
+): string | undefined {
+  if (!protocols) return undefined;
+  const list = Array.isArray(protocols) ? protocols : [protocols];
+  for (const p of list) {
+    if (typeof p !== "string") continue;
+    if (p.startsWith("bearer.")) {
+      try {
+        return decodeURIComponent(p.slice("bearer.".length));
+      } catch {
+        return p.slice("bearer.".length);
+      }
+    }
+  }
+  return undefined;
+}
+
+async function handle(
+  server: TestServer,
+  method: string,
+  url: string,
+  token: string | undefined,
+  _init: RequestInit | undefined,
+): Promise<MockResponse> {
+  // /api/auth/me — cheap auth context probe. Engine expects snake_case
+  // keys here (user_id / tenant_id / is_admin); the TestServer holds
+  // them as camelCase internally so we re-key on the way out.
+  if (url.endsWith("/api/auth/me") && method === "GET") {
+    const ctx = server.authContextFor(token);
+    return {
+      status: 200,
+      body: {
+        user_id: ctx.userId,
+        tenant_id: ctx.tenantId,
+        is_admin: ctx.isAdmin,
+        roles: ctx.roles,
+      },
+    };
+  }
+
+  // /api/sync/pull?since=N — incremental change pull.
+  if (url.includes("/api/sync/pull") && method === "GET") {
+    const primed = server.consumeNextPullStatus();
+    if (primed) {
+      return {
+        status: primed,
+        body: { error: { code: "RESYNC_REQUIRED" } },
+      };
+    }
+    const since = Number(new URL(url, "http://test").searchParams.get("since") ?? "0");
+    const resp = await server.pull(token, since);
+    return { status: 200, body: resp };
+  }
+
+  // /api/entities/<E>/cursor — policy-filtered list for reconcile.
+  const cursorMatch = url.match(/\/api\/entities\/([^/?]+)\/cursor/);
+  if (cursorMatch && method === "GET") {
+    const entity = cursorMatch[1]!;
+    const rows: Row[] = await server.listEntityRows(entity, token);
+    return {
+      status: 200,
+      body: { data: rows, next_cursor: null, has_more: false },
+    };
+  }
+
+  // /api/sync/push — accept ops from optimistic mutations.
+  if (url.endsWith("/api/sync/push") && method === "POST") {
+    return { status: 200, body: { ops: [] } };
+  }
+
+  // Anything else: 404 with a clear error so test failures point
+  // at the exact missing route rather than a generic JSON parse.
+  return {
+    status: 404,
+    body: { error: { code: "TEST_HARNESS_UNHANDLED", path: url, method } },
+  };
+}

package/src/transports/factory.test.ts

@@ -0,0 +1,87 @@
+// Tests for the createTransport factory + its sse→polling fallback.
+//
+// Regression for codex round-7 P2: pre-refactor, `transport: "sse"` in
+// an environment without a native `EventSource` (Node / jsdom /
+// unsupported browser) silently fell back to polling via the catch
+// block inside `connectSse()`. The extraction dropped that path; the
+// factory restores it by feature-checking up front so the engine
+// never holds an SseTransport that can never connect.
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  createTransport,
+  PollingTransport,
+  SseTransport,
+  WebSocketTransport,
+} from "./index";
+import type { TransportHost } from "./types";
+
+function noopHost(): TransportHost {
+  return {
+    baseUrl: "http://stub.invalid",
+    getToken: () => undefined,
+    isLeader: () => true,
+    isRunning: () => true,
+    onChangeEvent: () => {},
+    onJsonMessage: () => {},
+    onBinaryFrame: () => {},
+    onConnected: () => {},
+    onDisconnected: () => {},
+    setStatus: () => {},
+    performPollTick: async () => {},
+    performReconnectPull: async () => {},
+  };
+}
+
+describe("createTransport factory", () => {
+  test("websocket kind builds a WebSocketTransport", () => {
+    const t = createTransport("websocket", noopHost());
+    expect(t).toBeInstanceOf(WebSocketTransport);
+  });
+
+  test("poll kind builds a PollingTransport", () => {
+    const t = createTransport("poll", noopHost());
+    expect(t).toBeInstanceOf(PollingTransport);
+  });
+});
+
+describe("createTransport sse → polling fallback", () => {
+  let originalEventSource: unknown;
+
+  beforeEach(() => {
+    originalEventSource = (globalThis as { EventSource?: unknown }).EventSource;
+  });
+
+  afterEach(() => {
+    if (originalEventSource === undefined) {
+      delete (globalThis as { EventSource?: unknown }).EventSource;
+    } else {
+      (globalThis as { EventSource?: unknown }).EventSource =
+        originalEventSource;
+    }
+  });
+
+  test("sse kind WITH EventSource defined → SseTransport", () => {
+    // Provide a minimal stub so `typeof EventSource !== "undefined"`.
+    (globalThis as { EventSource: unknown }).EventSource = class {
+      // constructor is enough; we don't actually start the transport here
+      // (start would try to open a real connection). The factory check
+      // is purely a `typeof` lookup.
+    };
+    const t = createTransport("sse", noopHost());
+    expect(t).toBeInstanceOf(SseTransport);
+  });
+
+  test("sse kind WITHOUT EventSource → PollingTransport (fallback)", () => {
+    // Bun's test runtime has no global EventSource by default. Make sure
+    // it's actually undefined for this test, then assert the fallback
+    // kicks in.
+    delete (globalThis as { EventSource?: unknown }).EventSource;
+    const t = createTransport("sse", noopHost());
+    expect(t).toBeInstanceOf(PollingTransport);
+    // The pre-refactor behavior this pins: a Node consumer that calls
+    // `init({ transport: "sse" })` keeps syncing via polling instead of
+    // sitting in `connecting` forever with no socket and no timer.
+  });
+});

package/src/transports/index.ts

@@ -0,0 +1,42 @@
+// Public surface for the transport layer. The engine imports types
+// from here and constructs a transport via `createTransport(kind, host)`.
+
+import { PollingTransport } from "./polling";
+import { SseTransport } from "./sse";
+import type { Transport, TransportHost } from "./types";
+import { WebSocketTransport } from "./websocket";
+
+export type TransportKind = "websocket" | "sse" | "poll";
+export type { Transport, TransportHost } from "./types";
+export { WebSocketTransport } from "./websocket";
+export { SseTransport } from "./sse";
+export { PollingTransport } from "./polling";
+
+/** Build the right transport for a given kind. The host supplies all
+ *  config + the inbound dispatch callbacks; the transport hides the
+ *  underlying mechanism.
+ *
+ *  Fallback rule: `transport: "sse"` in an environment without a
+ *  native EventSource (Node, jsdom without a polyfill, old browsers)
+ *  silently downgrades to polling. The pre-refactor `connectSse()`
+ *  did this inside its constructor catch — we lift the decision to
+ *  the factory so the engine never sees an SseTransport that can
+ *  never connect. Clients that NEED SSE specifically can detect this
+ *  by feature-checking `typeof EventSource` themselves before calling
+ *  `init()`. */
+export function createTransport(
+  kind: TransportKind,
+  host: TransportHost,
+): Transport {
+  switch (kind) {
+    case "websocket":
+      return new WebSocketTransport(host);
+    case "sse":
+      if (typeof EventSource === "undefined") {
+        return new PollingTransport(host);
+      }
+      return new SseTransport(host);
+    case "poll":
+      return new PollingTransport(host);
+  }
+}

package/src/transports/polling.test.ts

@@ -0,0 +1,102 @@
+// Unit tests for the PollingTransport in isolation — the engine
+// integration is covered by `scenarios.test.ts` (which exercises
+// poll-mode reconcile + race fixes). These tests just pin the
+// transport's own contract:
+//  - start() begins ticking on `pollIntervalMs`
+//  - each tick calls host.performPollTick()
+//  - stop() halts the loop
+//  - send() / bumpReconnect() / onConnected are deterministic no-ops
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { PollingTransport } from "./polling";
+import type { TransportHost } from "./types";
+
+function makeHost(overrides: Partial<TransportHost> = {}): TransportHost & {
+  ticks: number;
+} {
+  const host = {
+    baseUrl: "http://stub.invalid",
+    pollIntervalMs: 20,
+    getToken: () => undefined,
+    isLeader: () => true,
+    isRunning: () => true,
+    onChangeEvent: () => {},
+    onJsonMessage: () => {},
+    onBinaryFrame: () => {},
+    onConnected: () => {},
+    onDisconnected: () => {},
+    setStatus: () => {},
+    performPollTick: async () => {
+      host.ticks += 1;
+    },
+    performReconnectPull: async () => {},
+    ticks: 0,
+    ...overrides,
+  };
+  return host as TransportHost & { ticks: number };
+}
+
+describe("PollingTransport", () => {
+  let t: PollingTransport | null = null;
+  let host: ReturnType<typeof makeHost> | null = null;
+
+  beforeEach(() => {
+    host = makeHost();
+    t = new PollingTransport(host);
+  });
+
+  afterEach(() => {
+    t?.stop();
+    t = null;
+    host = null;
+  });
+
+  test("start kicks off a tick loop on pollIntervalMs cadence", async () => {
+    t!.start();
+    expect(host!.ticks).toBe(0); // no eager tick — first tick fires AFTER the interval
+    await new Promise((r) => setTimeout(r, 70));
+    // 70ms / 20ms = ~3 ticks. Allow some slop for timer jitter.
+    expect(host!.ticks).toBeGreaterThanOrEqual(2);
+    expect(host!.ticks).toBeLessThanOrEqual(5);
+  });
+
+  test("stop halts the loop", async () => {
+    t!.start();
+    await new Promise((r) => setTimeout(r, 40));
+    const seen = host!.ticks;
+    t!.stop();
+    await new Promise((r) => setTimeout(r, 60));
+    expect(host!.ticks).toBe(seen);
+  });
+
+  test("start is idempotent", () => {
+    t!.start();
+    t!.start();
+    t!.start();
+    // No assertion beyond not throwing — the second/third call should
+    // see the existing timer and bail.
+    expect(t!.isOpen()).toBe(true);
+  });
+
+  test("send is a no-op (polling has no uplink)", () => {
+    t!.start();
+    expect(() => t!.send({ type: "ping" })).not.toThrow();
+  });
+
+  test("bumpReconnect is a no-op (polling has no backoff)", () => {
+    expect(() => t!.bumpReconnect(5)).not.toThrow();
+  });
+
+  test("does not start when host is not running", () => {
+    host!.isRunning = () => false;
+    t!.start();
+    expect(t!.isOpen()).toBe(false);
+  });
+
+  test("does not start when host is not the multi-tab leader", () => {
+    host!.isLeader = () => false;
+    t!.start();
+    expect(t!.isOpen()).toBe(false);
+  });
+});

package/src/transports/polling.ts

@@ -0,0 +1,63 @@
+// Polling transport. No persistent connection — every `pollIntervalMs`
+// the transport asks the host to do one push→pull cycle. Used by
+// environments where WS / SSE are unavailable (corporate proxies that
+// strip the Upgrade header, ancient browsers, certain serverless edge
+// runtimes).
+//
+// `send()` is a no-op — no socket exists. Subscribe / presence / topic
+// frames silently disappear. Apps that need bidirectional should not
+// use polling.
+
+import type { Transport, TransportHost } from "./types";
+
+const DEFAULT_POLL_INTERVAL_MS = 1_000;
+
+export class PollingTransport implements Transport {
+  private readonly host: TransportHost;
+  private timer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(host: TransportHost) {
+    this.host = host;
+  }
+
+  start(): void {
+    if (!this.host.isRunning()) return;
+    if (!this.host.isLeader()) return;
+    if (this.timer) return;
+    const interval = this.host.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    this.timer = setInterval(() => {
+      void this.host.performPollTick();
+    }, interval);
+    // Polling intentionally does NOT fire onConnected on start — there
+    // is no real "open" event with this transport, just a heartbeat
+    // tick every `pollIntervalMs`. Engine status stays at whatever
+    // `start()` set it to (typically "connecting"), and each
+    // successful tick implicitly proves liveness without us claiming
+    // a connection that doesn't exist. Apps that need an explicit
+    // "online" indicator under polling can derive it from the
+    // store's `notify` cadence.
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  send(_msg: unknown): void {
+    /* no uplink on polling */
+  }
+
+  isOpen(): boolean {
+    return this.timer !== null;
+  }
+
+  /** No-op — polling doesn't have a backoff counter; it just retries
+   *  every interval. A 429 on the in-flight push/pull will surface as
+   *  a thrown error on the next tick but the loop continues at the
+   *  same cadence. */
+  bumpReconnect(_by = 1): void {
+    /* polling has no backoff */
+  }
+}

package/src/transports/reconnect.test.ts

@@ -0,0 +1,57 @@
+// Unit tests for the ReconnectBackoff helper. Pins the contract the
+// WS + SSE transports rely on:
+//  - Starts at 0 attempts (delay = 0 on first nextDelayMs).
+//  - bump() increments; nextDelayMs() grows exponentially with jitter.
+//  - reset() returns to 0.
+//  - Cap at MAX_DELAY_MS.
+
+import { describe, expect, test } from "bun:test";
+
+import { ReconnectBackoff } from "./reconnect";
+
+describe("ReconnectBackoff", () => {
+  test("first delay is 0 (no jitter on no attempts)", () => {
+    const b = new ReconnectBackoff(1_000);
+    // attempts=0, but nextDelayMs uses max(1, attempts)=1 → exp=1000 →
+    // random in [0, 1000]. Just check the BOUND.
+    const d = b.nextDelayMs();
+    expect(d).toBeGreaterThanOrEqual(0);
+    expect(d).toBeLessThanOrEqual(1_000);
+  });
+
+  test("each bump doubles the exponent (until cap)", () => {
+    const b = new ReconnectBackoff(1_000);
+    b.bump(); // 1 → exp=1000
+    const d1Max = b.nextDelayMs();
+    b.bump(); // 2 → exp=2000
+    const d2Max = b.nextDelayMs();
+    b.bump(); // 3 → exp=4000
+    const d3Max = b.nextDelayMs();
+    // Bounds (not exact values — jitter is random).
+    expect(d1Max).toBeLessThanOrEqual(1_000);
+    expect(d2Max).toBeLessThanOrEqual(2_000);
+    expect(d3Max).toBeLessThanOrEqual(4_000);
+  });
+
+  test("delay caps at 30_000 ms even with many attempts", () => {
+    const b = new ReconnectBackoff(1_000);
+    // 10 doublings = 2^10 * 1_000 = ~1M ms unclamped. Cap is 30_000.
+    for (let i = 0; i < 20; i++) b.bump();
+    const d = b.nextDelayMs();
+    expect(d).toBeLessThanOrEqual(30_000);
+  });
+
+  test("reset clears the counter", () => {
+    const b = new ReconnectBackoff(1_000);
+    b.bump(5);
+    b.reset();
+    // Same bound as the fresh state.
+    expect(b.nextDelayMs()).toBeLessThanOrEqual(1_000);
+  });
+
+  test("bump(N) jumps by N — used by the 429 case in the engine", () => {
+    const b = new ReconnectBackoff(1_000);
+    b.bump(3); // attempts=3 → exp=4000
+    expect(b.nextDelayMs()).toBeLessThanOrEqual(4_000);
+  });
+});

package/src/transports/reconnect.ts

@@ -0,0 +1,50 @@
+// Shared exponential-backoff-with-full-jitter helper used by WS and
+// SSE. Polling has its own steady-cadence loop and doesn't backoff.
+//
+// Thundering-herd fix: when the server restarts, every connected
+// client fires onclose at nearly the same instant. Without jitter
+// they all reconnect at `baseDelay` and hammer the newly-booted
+// server; after a few cycles the reconnect waves align and the
+// server never recovers. Full-jitter (`delay = random(0, exp)`)
+// spreads clients evenly across the backoff window so the second-
+// wave load is flat, not spiky. Algorithm from AWS Architecture
+// Blog "Exponential Backoff and Jitter" — the "Full Jitter" variant.
+
+const DEFAULT_BASE_DELAY_MS = 1_000;
+const MAX_DELAY_MS = 30_000;
+
+/** Stateful backoff counter. Reset to 0 attempts after a successful
+ *  stable connection window. Increment on every failed connect /
+ *  unexpected close. */
+export class ReconnectBackoff {
+  private attempts = 0;
+  private baseDelayMs: number;
+
+  constructor(baseDelayMs?: number) {
+    this.baseDelayMs = baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+  }
+
+  /** Record a failed connect / unexpected close. Returns the new attempt
+   *  count so callers can use it for bookkeeping (e.g., the 429 case
+   *  bumps by 3 to push the next delay further out). */
+  bump(by = 1): number {
+    this.attempts += by;
+    return this.attempts;
+  }
+
+  /** Reset the counter — call this after the connection has been
+   *  stable long enough that subsequent reconnects shouldn't carry
+   *  the prior backoff over. */
+  reset(): void {
+    this.attempts = 0;
+  }
+
+  /** Compute the next delay in ms. Always returns at least 0; never
+   *  negative. Full-jitter over [0, exp] where exp grows
+   *  exponentially with the attempt count and caps at MAX_DELAY_MS. */
+  nextDelayMs(): number {
+    const attempt = Math.max(1, this.attempts);
+    const exp = Math.min(MAX_DELAY_MS, this.baseDelayMs * Math.pow(2, attempt - 1));
+    return Math.floor(Math.random() * exp);
+  }
+}