@pylonsync/sync 0.3.202 → 0.3.203

package/src/transports/sse.ts

@@ -0,0 +1,140 @@
+// Server-Sent Events transport. One-way GET stream of change events
+// from a dedicated `/events` endpoint on baseUrl-port+2.
+//
+// SSE has no uplink, so `send()` is a no-op — the engine continues to
+// dispatch subscribe / presence / topic frames through this method but
+// they don't reach the wire on this transport. Apps that need
+// bidirectional should pick WebSocket; SSE is for read-only mirror
+// clients (dashboards, monitors) that don't subscribe to anything
+// individually.
+//
+// Reconnect: SSE has its own browser-level reconnect, but it can't see
+// our auth token (no header on the GET retry), so we own the reconnect
+// loop here too — close on error, jittered backoff, pull-on-reconnect.
+
+import type { ChangeEvent } from "../types";
+import { ReconnectBackoff } from "./reconnect";
+import type { Transport, TransportHost } from "./types";
+
+export class SseTransport implements Transport {
+  private readonly host: TransportHost;
+  private es: EventSource | null = null;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private readonly backoff: ReconnectBackoff;
+
+  constructor(host: TransportHost) {
+    this.host = host;
+    this.backoff = new ReconnectBackoff(host.reconnectDelayMs);
+  }
+
+  start(): void {
+    if (!this.host.isRunning()) return;
+    if (!this.host.isLeader()) return;
+    if (this.es) return;
+
+    const sseUrl = this.deriveSseUrl();
+    try {
+      const es = new EventSource(sseUrl);
+      this.es = es;
+      es.onopen = () => {
+        this.host.setStatus("connected");
+        this.backoff.reset();
+        this.host.onConnected();
+      };
+      es.onmessage = (event) => {
+        try {
+          const msg = JSON.parse(event.data) as Record<string, unknown>;
+          if (
+            typeof msg.seq === "number" &&
+            msg.seq > 0 &&
+            typeof msg.entity === "string" &&
+            typeof msg.kind === "string"
+          ) {
+            this.host.onChangeEvent(msg as unknown as ChangeEvent);
+            return;
+          }
+          // Non-change envelopes are rare on SSE (no reactive queries,
+          // no row-revoked typically) but route through anyway so
+          // future protocol additions don't get silently dropped.
+          this.host.onJsonMessage(msg);
+        } catch {
+          // Ignore malformed events.
+        }
+      };
+      es.onerror = () => {
+        try {
+          es.close();
+        } catch {
+          /* may already be closed */
+        }
+        if (this.es === es) this.es = null;
+        if (!this.host.isRunning()) return;
+        this.host.setStatus("reconnecting");
+        this.host.onDisconnected();
+        this.scheduleReconnect();
+      };
+    } catch {
+      // EventSource constructor threw at runtime — rare, but a buggy
+      // polyfill or a malformed URL can land here. The `transport: "sse"`
+      // → polling fallback for the "EventSource undefined" case lives in
+      // `createTransport`; this catch covers the narrower "exists but
+      // failed to construct" case. Schedule a reconnect so we retry
+      // rather than silently giving up.
+      this.scheduleReconnect();
+    }
+  }
+
+  stop(): void {
+    if (this.es) {
+      try {
+        this.es.close();
+      } catch {
+        /* may already be closed */
+      }
+      this.es = null;
+    }
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+
+  /** SSE is one-way. The engine still calls send() for subscribe /
+   *  presence / topic / ping, but those frames have nowhere to go.
+   *  Silent no-op rather than throw: a no-op keeps app code identical
+   *  across transports. */
+  send(_msg: unknown): void {
+    /* no uplink on SSE */
+  }
+
+  /** SSE is always "open enough" to receive once the EventSource is
+   *  attached and not in CLOSED. We expose this for the engine's
+   *  `connected` getter so UI status matches reality. */
+  isOpen(): boolean {
+    return (
+      this.es !== null && this.es.readyState !== EventSource.CLOSED
+    );
+  }
+
+  bumpReconnect(by = 1): void {
+    this.backoff.bump(by);
+  }
+
+  // ---- internals --------------------------------------------------------
+
+  private scheduleReconnect(): void {
+    if (!this.host.isRunning()) return;
+    this.backoff.bump();
+    const delay = this.backoff.nextDelayMs();
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      void this.host.performReconnectPull().then(() => this.start());
+    }, delay);
+  }
+
+  private deriveSseUrl(): string {
+    const url = new URL(this.host.baseUrl);
+    const port = parseInt(url.port || "4321", 10);
+    return `http://${url.hostname}:${port + 2}/events`;
+  }
+}

package/src/transports/types.ts

@@ -0,0 +1,116 @@
+// Common interface every real-time transport implements + the host
+// contract the engine offers each transport.
+//
+// Why this exists: WebSocket, SSE, and polling each used to live as
+// large parallel methods on the engine, sharing state through engine
+// fields (`this.ws`, `this.pingTimer`, `this.reconnectAttempts`,
+// `this.pollTimer`). That coupling made the three modes hard to
+// test, hard to swap, and a graveyard for state bugs (timer leaks on
+// promotion, stale-socket sends after reconnect, ping racing close).
+// The interface here gives each one a single owner of its own state
+// + a tight contract with the engine for dispatch and lifecycle.
+
+import type { ChangeEvent, SyncConnectionStatus } from "../types";
+
+/** Real-time transport implementations all conform to this shape. The
+ *  engine holds exactly one. The interface intentionally hides the
+ *  underlying mechanism (WebSocket vs EventSource vs setInterval) so
+ *  the engine can be told "go connect" without caring which one. */
+export interface Transport {
+  /** Connect / start the transport. Idempotent — calling twice is a
+   *  no-op for an already-running transport. */
+  start(): void;
+  /** Disconnect / stop the transport, clearing every timer and
+   *  releasing the socket. Idempotent. After stop() the transport is
+   *  re-startable. */
+  stop(): void;
+  /** Send a JSON message over the transport. No-op for non-bidirectional
+   *  transports (SSE, polling) — the engine still sends subscribe
+   *  frames + presence + topic + ping through this entry point, and
+   *  those frames simply never reach the wire when the transport
+   *  doesn't support uplink. */
+  send(msg: unknown): void;
+  /** True when the underlying connection is currently open for sending.
+   *  Used by the engine's `connected` getter and by paths that need to
+   *  short-circuit when no socket exists (e.g., avoid throwing on a
+   *  send-without-WS). */
+  isOpen(): boolean;
+  /** Bump the reconnect backoff counter by N attempts. Called by the
+   *  engine when it observes a hint that the NEXT reconnect should
+   *  wait longer — typically a 429 on pull, which would otherwise
+   *  drive a tight 429 / reconnect / 429 loop. Transports without a
+   *  backoff (polling) implement this as a no-op. */
+  bumpReconnect(by?: number): void;
+}
+
+/** Engine-side surface the transport calls into. Transport is the
+ *  thing that knows about sockets and timers; the host (engine) is the
+ *  thing that knows what to DO with inbound frames and lifecycle
+ *  events. Keeping this small + explicit makes the boundary clear:
+ *  if a transport needs a new engine capability it gets added here,
+ *  not via reaching back into the engine instance. */
+export interface TransportHost {
+  /** Base URL of the Pylon HTTP API (e.g. `https://api.example.com`).
+   *  Transports derive their own URLs from this (ws upgrade path, SSE
+   *  endpoint, poll path). */
+  readonly baseUrl: string;
+  /** Optional explicit WS URL — overrides the derived one. */
+  readonly wsUrl?: string;
+  /** WS keepalive interval. Default is implementation-defined; the
+   *  engine accepts `pingIntervalMs` from config to tune broadcast
+   *  latency on single-threaded server fallbacks. */
+  readonly pingIntervalMs?: number;
+  /** Base delay for reconnect backoff (full-jitter). */
+  readonly reconnectDelayMs?: number;
+  /** Polling cadence (polling transport only). */
+  readonly pollIntervalMs?: number;
+
+  /** Current bearer token, or undefined when anonymous. The transport
+   *  must call this fresh on each connect / reconnect so token rotation
+   *  is picked up automatically. */
+  getToken(): string | undefined;
+
+  /** Is this tab the multi-tab leader. Followers don't open their own
+   *  transport — they mirror the leader's broadcasts. Transports check
+   *  this defensively at start() to avoid wasting socket budget. */
+  isLeader(): boolean;
+  /** Is the engine currently running. Set false on stop(); transports
+   *  bail out of reconnect timers when this flips. */
+  isRunning(): boolean;
+
+  /** Inbound: a typed change event from the server's change log.
+   *  Engine routes through the apply queue so order is preserved. */
+  onChangeEvent(ev: ChangeEvent): void;
+  /** Inbound: a typed JSON envelope (not a ChangeEvent). The transport
+   *  doesn't try to interpret the envelope — engine has the dispatch
+   *  table (session-changed, reactive-result, row-revoked, presence,
+   *  pong, etc). */
+  onJsonMessage(msg: Record<string, unknown>): void;
+  /** Inbound: a binary frame. CRDT broadcast layer ships these for
+   *  every Loro-mode write; the engine routes via its binaryHandlers
+   *  + multi-tab forwarders. */
+  onBinaryFrame(bytes: Uint8Array): void;
+
+  /** Lifecycle: the transport just connected. Engine uses this to
+   *  replay active subscriptions, fire a catch-up pull + reconcile,
+   *  and flip the public connection status. */
+  onConnected(): void;
+  /** Lifecycle: the transport just disconnected. Engine flips status
+   *  to `reconnecting` while the transport's own backoff timer is
+   *  pending; or to `offline` when `isRunning()` is false. */
+  onDisconnected(): void;
+  /** Flip the engine's public `connectionStatus`. Transports drive
+   *  this so the UI sees `connecting` / `connected` / `reconnecting`
+   *  / `offline` at the right moments. */
+  setStatus(s: SyncConnectionStatus): void;
+
+  /** Polling transport only: one iteration of the push→pull cycle.
+   *  Implementations of polling do nothing else; they just call this
+   *  on a timer. */
+  performPollTick(): Promise<void>;
+  /** Reconnect-aware transports (WS, SSE) need to do a catch-up pull
+   *  before the next connect attempt so they don't open a fresh socket
+   *  and immediately discover their cursor is stale. The engine owns
+   *  the pull queue + reconcile path; the transport invokes this. */
+  performReconnectPull(): Promise<void>;
+}

package/src/transports/websocket.test.ts

@@ -0,0 +1,310 @@
+// Unit tests for the WebSocketTransport. Uses a fake WebSocket
+// implementation so the test runs without a real server. Pins:
+//  - start() opens a socket and wires onopen/onmessage/onclose/onerror
+//  - onopen flips status to "connected", replay fires via host.onConnected
+//  - binary frames route through host.onBinaryFrame
+//  - ChangeEvent JSON routes through host.onChangeEvent
+//  - Other JSON routes through host.onJsonMessage
+//  - Disconnect triggers reconnect after a backoff window
+//  - stop() suppresses the scheduled reconnect
+
+import {
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "bun:test";
+
+import type { ChangeEvent, SyncConnectionStatus } from "../types";
+import type { TransportHost } from "./types";
+import { WebSocketTransport } from "./websocket";
+
+// ---------------------------------------------------------------------------
+// Fake WebSocket. Captures every constructor call so tests can poke at the
+// returned socket's onopen/onmessage/onclose/onerror handlers. The real
+// browser API doesn't let us do that — but we control what `new WebSocket`
+// returns in test land.
+// ---------------------------------------------------------------------------
+
+interface FakeWebSocketInstance {
+  url: string;
+  protocols?: string | string[];
+  readyState: number;
+  binaryType: string;
+  sent: string[];
+  onopen: ((ev: Event) => void) | null;
+  onmessage: ((ev: MessageEvent) => void) | null;
+  onclose: ((ev: CloseEvent) => void) | null;
+  onerror: ((ev: Event) => void) | null;
+  send(data: string): void;
+  close(): void;
+  /** Test helper: simulate the server pushing a frame. */
+  simulateMessage(data: string | ArrayBuffer): void;
+  /** Test helper: simulate the open handshake completing. */
+  simulateOpen(): void;
+  /** Test helper: simulate an unexpected close. */
+  simulateClose(): void;
+}
+
+const fakeSockets: FakeWebSocketInstance[] = [];
+
+class FakeWebSocket implements FakeWebSocketInstance {
+  url: string;
+  protocols?: string | string[];
+  readyState = 0; // CONNECTING
+  binaryType = "blob";
+  sent: string[] = [];
+  onopen: ((ev: Event) => void) | null = null;
+  onmessage: ((ev: MessageEvent) => void) | null = null;
+  onclose: ((ev: CloseEvent) => void) | null = null;
+  onerror: ((ev: Event) => void) | null = null;
+
+  constructor(url: string, protocols?: string | string[]) {
+    this.url = url;
+    this.protocols = protocols;
+    fakeSockets.push(this);
+  }
+
+  send(data: string): void {
+    this.sent.push(data);
+  }
+
+  close(): void {
+    this.readyState = 3; // CLOSED
+    // Bun's tests run synchronously enough that we don't fire onclose
+    // here — the production code's stop() nulls onclose before this
+    // is called, and the test's simulateClose covers the other path.
+  }
+
+  simulateOpen(): void {
+    this.readyState = 1; // OPEN
+    this.onopen?.(new Event("open"));
+  }
+
+  simulateMessage(data: string | ArrayBuffer): void {
+    this.onmessage?.({ data } as MessageEvent);
+  }
+
+  simulateClose(): void {
+    this.readyState = 3; // CLOSED
+    this.onclose?.(new CloseEvent("close"));
+  }
+}
+
+// Patch globals once for this file. We intentionally don't restore —
+// the test runner gives each file its own module evaluation, and other
+// test files that need a real WebSocket already supply their own stub
+// (e.g., the scenario harness installs its own). Restoring after each
+// test caused us to clobber the FakeWebSocket mid-suite and break
+// subsequent tests in this file.
+beforeAll(() => {
+  Object.defineProperty(globalThis, "WebSocket", {
+    value: FakeWebSocket,
+    writable: true,
+    configurable: true,
+  });
+  // The transport checks `this.ws.readyState === WebSocket.OPEN`, so
+  // the static .OPEN constant has to exist on whatever class we
+  // install. Mirrors the browser's WebSocket.OPEN === 1.
+  Object.defineProperty(FakeWebSocket, "OPEN", {
+    value: 1,
+    writable: false,
+    configurable: true,
+  });
+});
+
+// ---------------------------------------------------------------------------
+
+interface TestState {
+  statuses: SyncConnectionStatus[];
+  changes: ChangeEvent[];
+  jsonMessages: Record<string, unknown>[];
+  binaries: Uint8Array[];
+  connectedCount: number;
+  reconnectPulls: number;
+}
+
+/** Build a TransportHost wired to a TestState recorder. Recorder is
+ *  returned via `state` so tests can read counters after the transport
+ *  has called back into the host. Spreading state into host would
+ *  copy the counter values once at construction — the recorder needs
+ *  shared mutable state. */
+function makeHost(
+  overrides: Partial<TransportHost> = {},
+): { host: TransportHost; state: TestState } {
+  const state: TestState = {
+    statuses: [],
+    changes: [],
+    jsonMessages: [],
+    binaries: [],
+    connectedCount: 0,
+    reconnectPulls: 0,
+  };
+  const host: TransportHost = {
+    baseUrl: "http://stub.invalid",
+    reconnectDelayMs: 10,
+    getToken: () => undefined,
+    isLeader: () => true,
+    isRunning: () => true,
+    onChangeEvent: (ev) => state.changes.push(ev),
+    onJsonMessage: (msg) => state.jsonMessages.push(msg),
+    onBinaryFrame: (bytes) => state.binaries.push(bytes),
+    onConnected: () => {
+      state.connectedCount += 1;
+    },
+    onDisconnected: () => {},
+    setStatus: (s) => state.statuses.push(s),
+    performPollTick: async () => {},
+    performReconnectPull: async () => {
+      state.reconnectPulls += 1;
+    },
+    ...overrides,
+  };
+  return { host, state };
+}
+
+describe("WebSocketTransport", () => {
+  let t: WebSocketTransport | null = null;
+
+  beforeEach(() => {
+    fakeSockets.length = 0;
+    t = null;
+  });
+
+  afterEach(() => {
+    t?.stop();
+    t = null;
+  });
+
+  test("start opens a socket with the derived URL", () => {
+    const { host, state } = makeHost();
+    t = new WebSocketTransport(host);
+    t.start();
+    expect(fakeSockets.length).toBe(1);
+    // baseUrl is http → ws scheme; multiplexed on /api/sync/ws.
+    expect(fakeSockets[0].url).toBe("ws://stub.invalid/api/sync/ws");
+  });
+
+  test("start passes the bearer-subprotocol when host has a token", () => {
+    const { host } = makeHost({ getToken: () => "tok_abc" });
+    t = new WebSocketTransport(host);
+    t.start();
+    expect(fakeSockets[0].protocols).toBe("bearer.tok_abc");
+  });
+
+  test("onopen flips status to connected and fires host.onConnected", () => {
+    const { host, state } = makeHost();
+    t = new WebSocketTransport(host);
+    t.start();
+    fakeSockets[0].simulateOpen();
+    expect(state.statuses).toContain("connected");
+    expect(state.connectedCount).toBe(1);
+  });
+
+  test("ChangeEvent frames route through onChangeEvent", () => {
+    const { host, state } = makeHost();
+    t = new WebSocketTransport(host);
+    t.start();
+    fakeSockets[0].simulateOpen();
+    const ev = {
+      seq: 5,
+      entity: "Todo",
+      row_id: "r1",
+      kind: "insert",
+      data: { id: "r1" },
+      timestamp: "",
+    };
+    fakeSockets[0].simulateMessage(JSON.stringify(ev));
+    expect(state.changes.length).toBe(1);
+    expect(state.changes[0].seq).toBe(5);
+  });
+
+  test("non-change JSON routes through onJsonMessage", () => {
+    const { host, state } = makeHost();
+    t = new WebSocketTransport(host);
+    t.start();
+    fakeSockets[0].simulateOpen();
+    fakeSockets[0].simulateMessage(
+      JSON.stringify({ type: "session-changed" }),
+    );
+    expect(state.jsonMessages.length).toBe(1);
+    expect(state.jsonMessages[0].type).toBe("session-changed");
+    expect(state.changes.length).toBe(0);
+  });
+
+  test("binary frames route through onBinaryFrame", () => {
+    const { host, state } = makeHost();
+    t = new WebSocketTransport(host);
+    t.start();
+    fakeSockets[0].simulateOpen();
+    const bytes = new Uint8Array([1, 2, 3, 4]).buffer;
+    fakeSockets[0].simulateMessage(bytes);
+    expect(state.binaries.length).toBe(1);
+    expect(state.binaries[0].length).toBe(4);
+  });
+
+  test("send writes a JSON string to the socket when open", () => {
+    const { host, state } = makeHost();
+    t = new WebSocketTransport(host);
+    t.start();
+    fakeSockets[0].simulateOpen();
+    t.send({ type: "presence", x: 1 });
+    expect(fakeSockets[0].sent).toContain('{"type":"presence","x":1}');
+  });
+
+  test("send is a no-op when the socket isn't open", () => {
+    const { host, state } = makeHost();
+    t = new WebSocketTransport(host);
+    t.start();
+    // Don't simulateOpen — readyState stays at CONNECTING.
+    t.send({ type: "presence" });
+    expect(fakeSockets[0].sent.length).toBe(0);
+  });
+
+  test("unexpected close triggers reconnect via performReconnectPull", async () => {
+    const { host, state } = makeHost({ reconnectDelayMs: 5 });
+    t = new WebSocketTransport(host);
+    t.start();
+    fakeSockets[0].simulateOpen();
+    fakeSockets[0].simulateClose();
+    // Wait long enough for the backoff timer + reconnect to fire.
+    await new Promise((r) => setTimeout(r, 80));
+    expect(state.reconnectPulls).toBeGreaterThanOrEqual(1);
+    // A second socket should have been opened.
+    expect(fakeSockets.length).toBeGreaterThanOrEqual(2);
+  });
+
+  test("stop suppresses the scheduled reconnect", async () => {
+    const { host, state } = makeHost({ reconnectDelayMs: 5 });
+    t = new WebSocketTransport(host);
+    t.start();
+    fakeSockets[0].simulateOpen();
+    fakeSockets[0].simulateClose();
+    t.stop();
+    await new Promise((r) => setTimeout(r, 80));
+    // No reconnect pull should have fired — stop cancelled the timer.
+    expect(state.reconnectPulls).toBe(0);
+  });
+
+  test("does not open a socket when host is not leader", () => {
+    const { host } = makeHost({ isLeader: () => false });
+    t = new WebSocketTransport(host);
+    t.start();
+    expect(fakeSockets.length).toBe(0);
+  });
+
+  test("isOpen reflects the underlying readyState", () => {
+    const { host, state } = makeHost();
+    t = new WebSocketTransport(host);
+    expect(t.isOpen()).toBe(false);
+    t.start();
+    expect(t.isOpen()).toBe(false); // CONNECTING
+    fakeSockets[0].simulateOpen();
+    expect(t.isOpen()).toBe(true); // OPEN
+    fakeSockets[0].simulateClose();
+    expect(t.isOpen()).toBe(false); // CLOSED
+  });
+});
+