@pylonsync/sync 0.4.22 → 0.4.24

package/dist/index.d.ts

@@ -19,6 +19,14 @@ export interface SyncEngineConfig {
     transport?: TransportType;
     /** WebSocket URL. Default: derived from baseUrl (ws://). */
     wsUrl?: string;
+    /** Connect the live-event socket through the Durable Object sync
+     *  relay instead of the machine's own WS. The engine fetches a
+     *  signed connect target from `GET /api/sync/relay-token` before
+     *  each connect (fresh token every reconnect), so revoked sessions
+     *  converge on the token TTL. Pull/push/mutations still go to
+     *  `baseUrl` — the relay carries change events only; room, CRDT,
+     *  and reactive subscriptions require the direct machine WS. */
+    relay?: boolean;
     /** Poll interval in ms (only used when transport is "poll"). Default 1000. */
     pollInterval?: number;
     /** Reconnect delay in ms. Default 1000. */
@@ -798,6 +806,13 @@ export declare class SyncEngine {
      * subsequent sign-in as the same user is instant.
      */
     signOut(): Promise<void>;
+    /** Relay mode: fetch a fresh signed connect target from the machine
+     *  before each socket attempt. The machine authenticates + enriches
+     *  this caller and mints the blob the relay's policy filter runs
+     *  against — fetching per-connect is what bounds revoked-role
+     *  staleness to the token TTL. Returns null on any failure; the
+     *  transport treats that as a failed connect and backs off. */
+    private fetchRelayTarget;
     /** Shared transport for the auth helpers above. Same bearer/cookie
      *  policy as `request()` — keeps the auth flows on the same
      *  authentication footing as data sync. */

package/dist/transports/types.d.ts

@@ -54,6 +54,19 @@ export interface TransportHost {
      *  must call this fresh on each connect / reconnect so token rotation
      *  is picked up automatically. */
     getToken(): string | undefined;
+    /** Sync-relay mode (engine sets this only when `config.relay` is
+     *  on): resolve the relay socket target freshly for THIS connect
+     *  attempt — the ws `url` (with the `since` cursor) plus the signed
+     *  auth `blob`. The transport sends the blob in the `bearer.<blob>`
+     *  subprotocol, exactly like the machine token, so the credential
+     *  stays out of the URL (and out of proxy logs). `null` = the token
+     *  fetch failed; the transport backs off and retries like any failed
+     *  connect. When present, this replaces `wsUrl`/derivation and the
+     *  machine bearer token. */
+    getRelayTarget?(): Promise<{
+        url: string;
+        blob: string;
+    } | null>;
     /** 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. */

package/dist/transports/websocket.d.ts

@@ -5,9 +5,11 @@ export declare class WebSocketTransport implements Transport {
     private reconnectTimer;
     private stableTimer;
     private pingTimer;
+    private resolvingRelay;
     private readonly backoff;
     constructor(host: TransportHost);
     start(): void;
+    private connectTo;
     stop(): void;
     send(msg: unknown): void;
     isOpen(): boolean;

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.4.22",
+  "version": "0.4.24",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",

package/src/index.ts

@@ -110,6 +110,14 @@ export interface SyncEngineConfig {
   transport?: TransportType;
   /** WebSocket URL. Default: derived from baseUrl (ws://). */
   wsUrl?: string;
+  /** Connect the live-event socket through the Durable Object sync
+   *  relay instead of the machine's own WS. The engine fetches a
+   *  signed connect target from `GET /api/sync/relay-token` before
+   *  each connect (fresh token every reconnect), so revoked sessions
+   *  converge on the token TTL. Pull/push/mutations still go to
+   *  `baseUrl` — the relay carries change events only; room, CRDT,
+   *  and reactive subscriptions require the direct machine WS. */
+  relay?: boolean;
   /** Poll interval in ms (only used when transport is "poll"). Default 1000. */
   pollInterval?: number;
   /** Reconnect delay in ms. Default 1000. */
@@ -2566,6 +2574,39 @@ export class SyncEngine {
     await this.refreshResolvedSession();
   }
 
+  /** Relay mode: fetch a fresh signed connect target from the machine
+   *  before each socket attempt. The machine authenticates + enriches
+   *  this caller and mints the blob the relay's policy filter runs
+   *  against — fetching per-connect is what bounds revoked-role
+   *  staleness to the token TTL. Returns null on any failure; the
+   *  transport treats that as a failed connect and backs off. */
+  private async fetchRelayTarget(): Promise<{ url: string; blob: string } | null> {
+    try {
+      const headers: Record<string, string> = {};
+      const token =
+        this.config.token ??
+        this.storage.get(this.tokenStorageKey()) ??
+        undefined;
+      if (token) headers["Authorization"] = `Bearer ${token}`;
+      const res = await fetch(`${this.config.baseUrl}/api/sync/relay-token`, {
+        headers,
+        credentials: "include",
+      });
+      if (!res.ok) return null;
+      const body = (await res.json()) as { token?: string; url?: string };
+      if (!body.token || !body.url) return null;
+      const sep = body.url.includes("?") ? "&" : "?";
+      // `since` lets the relay replay its ring tail ahead of live
+      // frames; the engine's reconnect pull against the machine is
+      // still the correctness backstop for anything older. The token
+      // stays OUT of the URL — the transport sends it as a subprotocol.
+      const since = this.cursor.last_seq ?? 0;
+      return { url: `${body.url}${sep}since=${since}`, blob: body.token };
+    } catch {
+      return null;
+    }
+  }
+
   /** Shared transport for the auth helpers above. Same bearer/cookie
    *  policy as `request()` — keeps the auth flows on the same
    *  authentication footing as data sync. */
@@ -3277,6 +3318,7 @@ export class SyncEngine {
     return {
       baseUrl: this.config.baseUrl,
       wsUrl: this.config.wsUrl,
+      ...(this.config.relay ? { getRelayTarget: () => this.fetchRelayTarget() } : {}),
       pingIntervalMs: this.config.pingIntervalMs,
       reconnectDelayMs: this.config.reconnectDelay,
       pollIntervalMs: this.config.pollInterval,

package/src/transports/types.ts

@@ -70,6 +70,17 @@ export interface TransportHost {
    *  is picked up automatically. */
   getToken(): string | undefined;
 
+  /** Sync-relay mode (engine sets this only when `config.relay` is
+   *  on): resolve the relay socket target freshly for THIS connect
+   *  attempt — the ws `url` (with the `since` cursor) plus the signed
+   *  auth `blob`. The transport sends the blob in the `bearer.<blob>`
+   *  subprotocol, exactly like the machine token, so the credential
+   *  stays out of the URL (and out of proxy logs). `null` = the token
+   *  fetch failed; the transport backs off and retries like any failed
+   *  connect. When present, this replaces `wsUrl`/derivation and the
+   *  machine bearer token. */
+  getRelayTarget?(): Promise<{ url: string; blob: string } | null>;
+
   /** 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. */

package/src/transports/websocket.test.ts

@@ -194,6 +194,47 @@ describe("WebSocketTransport", () => {
     expect(fakeSockets[0].protocols).toBe("bearer.tok_abc");
   });
 
+  test("relay mode dials the minted URL with the blob as a subprotocol", async () => {
+    let mints = 0;
+    const { host } = makeHost({
+      getToken: () => "tok_abc", // machine token must NOT reach the wire
+      getRelayTarget: async () => {
+        mints += 1;
+        return {
+          url: `wss://relay.invalid/sync/ws?app=demo&since=42`,
+          blob: `blob${mints}`,
+        };
+      },
+    });
+    t = new WebSocketTransport(host);
+    t.start();
+    // Resolution is async; nothing dialed synchronously, and a second
+    // start() during resolution must not stack a second mint.
+    expect(fakeSockets.length).toBe(0);
+    t.start();
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(mints).toBe(1);
+    expect(fakeSockets.length).toBe(1);
+    // The blob is NOT in the URL (stays out of proxy logs) …
+    expect(fakeSockets[0].url).toBe("wss://relay.invalid/sync/ws?app=demo&since=42");
+    // … it rides the bearer subprotocol, and the machine token doesn't.
+    expect(fakeSockets[0].protocols).toBe("bearer.blob1");
+  });
+
+  test("relay mint failure backs off instead of dialing", async () => {
+    const { host } = makeHost({ getRelayTarget: async () => null });
+    t = new WebSocketTransport(host);
+    t.start();
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(fakeSockets.length).toBe(0);
+    // Backoff timer armed: a later fire re-attempts via reconnect pull.
+    await new Promise((r) => setTimeout(r, 30));
+    // Each retry re-mints (and fails) — no socket ever opens.
+    expect(fakeSockets.length).toBe(0);
+  });
+
   test("onopen flips status to connected and fires host.onConnected", () => {
     const { host, state } = makeHost();
     t = new WebSocketTransport(host);

package/src/transports/websocket.ts

@@ -24,6 +24,7 @@ export class WebSocketTransport implements Transport {
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
   private stableTimer: ReturnType<typeof setTimeout> | null = null;
   private pingTimer: ReturnType<typeof setInterval> | null = null;
+  private resolvingRelay = false;
   private readonly backoff: ReconnectBackoff;
 
   constructor(host: TransportHost) {
@@ -37,10 +38,39 @@ export class WebSocketTransport implements Transport {
     // the BroadcastChannel.
     if (!this.host.isLeader()) return;
     // Already connected / connecting? Don't stack a second socket.
-    if (this.ws) return;
+    if (this.ws || this.resolvingRelay) return;
+
+    // Relay mode: the connect target is minted per-attempt (signed
+    // blob + since cursor). The blob travels in the `bearer.<blob>`
+    // subprotocol via connectTo, NOT the URL — keeping the live
+    // credential out of proxy/CDN access logs.
+    if (this.host.getRelayTarget) {
+      this.resolvingRelay = true;
+      this.host
+        .getRelayTarget()
+        .then((target) => {
+          this.resolvingRelay = false;
+          if (!this.host.isRunning() || this.ws) return;
+          if (!target) {
+            this.scheduleReconnect();
+            return;
+          }
+          this.connectTo(target.url, target.blob);
+        })
+        .catch(() => {
+          // getRelayTarget shouldn't reject (the engine's impl catches
+          // to null), but a custom host might — never wedge on a stuck
+          // resolvingRelay flag.
+          this.resolvingRelay = false;
+          this.scheduleReconnect();
+        });
+      return;
+    }
+
+    this.connectTo(this.host.wsUrl ?? this.deriveWsUrl(), this.host.getToken());
+  }
 
-    const wsUrl = this.host.wsUrl ?? this.deriveWsUrl();
-    const token = this.host.getToken();
+  private connectTo(wsUrl: string, token: string | undefined): void {
     try {
       if (token) {
         const proto = `bearer.${encodeURIComponent(token)}`;
@@ -158,6 +188,8 @@ export class WebSocketTransport implements Transport {
       }
       this.ws = null;
     }
+    // A relay-target resolution in flight must not re-open after stop.
+    this.resolvingRelay = false;
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;