@syncular/server 0.39.1 → 0.39.2

package/README.md

@@ -1292,15 +1292,13 @@ install no fanout at all.
 ```ts
 import { PostgresFanout, type PgNotificationConnection } from '@syncular/server';
 
-// node-postgres: a dedicated Client for LISTEN + the pool for NOTIFY.
+// Bun.sql over the direct (unpooled) URL: LISTEN needs a session-mode
+// connection, and Bun.sql reconnects a dropped listener and re-runs onListen.
+const sql = new Bun.SQL(process.env.DATABASE_URL_DIRECT!);
 const conn: PgNotificationConnection = {
-  async listen(channel, handler) {
-    const client = await pool.connect(); // long-lived, NOT released
-    client.on('notification', (m) => m.payload && handler(m.payload));
-    await client.query(`LISTEN ${channel}`);
-  },
-  notify: (channel, payload) =>
-    pool.query('SELECT pg_notify($1, $2)', [channel, payload]).then(() => {}),
+  listen: (channel, handler, onListen) =>
+    sql.listen(channel, handler, onListen).then(() => {}),
+  notify: (channel, payload) => sql.notify(channel, payload).then(() => {}),
 };
 const fanout = new PostgresFanout(conn);
 await fanout.install(hub); // start the LISTEN loop
@@ -1308,10 +1306,16 @@ await fanout.install(hub); // start the LISTEN loop
 await fanout.notifyCommit(partition, commitSeq);
 ```
 
+Notifications sent while a listener session is down are lost. Every
+`onListen` after the first therefore wakes all local sessions with
+`catchup-required` (`hub.wakeAll`). A node-postgres adapter reconnects its
+dedicated `Client` on `end` and calls `onListen` after each `LISTEN`.
+
 pglite is single-connection and cannot exercise cross-connection NOTIFY,
 so the fanout integration test is env-gated on `SYNCULAR_PG_URL` (it wires
-Bun.sql as a worked example) and skips cleanly; the payload encode/parse
-and wake wiring are unit-tested hermetically.
+Bun.sql as a worked example and terminates the listener backend to cover the
+reconnect path) and skips cleanly; the payload encode/parse and wake wiring
+are unit-tested hermetically.
 
 ### Bench lane
 

package/dist/postgres-fanout.d.ts

@@ -29,6 +29,14 @@
  * The payload carries `commitSeq` purely for observability/ordering in logs;
  * the wake itself is seq-agnostic (a session pulls whatever it is behind).
  *
+ * ## Listener gaps
+ *
+ * Postgres drops notifications for a session that is not listening, so a
+ * LISTEN connection that dies and reconnects (server restart, failover, a
+ * serverless compute suspending) misses every commit in between. The
+ * connection reports each LISTEN that takes effect through `onListen`; every
+ * report after the first wakes all local sessions with `catchup-required`.
+ *
  * pglite cannot exercise cross-connection NOTIFY, so the integration
  * (`postgres-fanout.integration.test.ts`) is env-gated on `SYNCULAR_PG_URL`
  * and skips cleanly; the payload encode/parse is unit-tested hermetically.
@@ -51,18 +59,23 @@ export declare function parseFanoutPayload(text: string): FanoutPayload | undefi
 /** The hub surface the fanout wakes (a `RealtimeHub` satisfies this). */
 export interface FanoutWakeTarget {
     wake(partition: string, reason: WakeReason): void;
+    wakeAll(reason: WakeReason): void;
 }
 /**
  * A raw notification connection. Production wires a driver's LISTEN support:
+ *   - Bun.sql and postgres.js: `sql.listen(channel, handler, onListen)`; both
+ *     reconnect a dropped listener and call `onListen` again;
  *   - node-postgres: a dedicated `Client` with `client.on('notification', …)`
- *     after `LISTEN syncular_commit`;
- *   - Bun.sql: `sql.listen(channel, handler)`.
+ *     after `LISTEN syncular_commit`, reconnected by the host.
  * The `notify` side can reuse the main pool (`SELECT pg_notify($1,$2)`), but
- * LISTEN needs its own long-lived connection.
+ * LISTEN needs its own long-lived, unpooled connection.
  */
 export interface PgNotificationConnection {
-    /** Register a payload handler for the channel and begin listening. */
-    listen(channel: string, handler: (payload: string) => void): Promise<void> | void;
+    /**
+     * Register a payload handler for the channel and begin listening. Call
+     * `onListen` every time LISTEN takes effect, including after a reconnect.
+     */
+    listen(channel: string, handler: (payload: string) => void, onListen: () => void): Promise<void> | void;
     /** Send a notification on the channel. */
     notify(channel: string, payload: string): Promise<void>;
     close?(): Promise<void>;

package/dist/postgres-fanout.js

@@ -54,11 +54,17 @@ export class PostgresFanout {
         if (this.#installed)
             throw new Error('fanout already installed');
         this.#installed = true;
+        let listening = false;
         await this.#conn.listen(FANOUT_CHANNEL, (payload) => {
             const parsed = parseFanoutPayload(payload);
             if (parsed === undefined)
                 return; // ignore malformed frames
             hub.wake(parsed.partition, FANOUT_WAKE_REASON);
+        }, () => {
+            // A repeated LISTEN follows a gap whose notifications are lost.
+            if (listening)
+                hub.wakeAll(FANOUT_WAKE_REASON);
+            listening = true;
         });
     }
     /** Fan an applied commit out to the other instances. */

package/dist/realtime.d.ts

@@ -257,6 +257,8 @@ export declare class RealtimeHub {
     refreshScopes(partition: string, actorId?: string): Promise<void>;
     /** Broadcast a wake-up (host-initiated resync, schema rollover, §8.3). */
     wake(partition: string, reason: WakeReason): void;
+    /** Wake every session on every partition (fanout listener gap, §8.3). */
+    wakeAll(reason: WakeReason): void;
 }
 export declare function createRealtimeHub(config: RealtimeHubConfig): RealtimeHub;
 export {};

package/dist/realtime.js

@@ -1012,6 +1012,11 @@ export class RealtimeHub {
             session.sendWake(reason);
         }
     }
+    /** Wake every session on every partition (fanout listener gap, §8.3). */
+    wakeAll(reason) {
+        for (const session of this.#sessions)
+            session.sendWake(reason);
+    }
 }
 export function createRealtimeHub(config) {
     return new RealtimeHub(config);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.39.1",
+  "version": "0.39.2",
   "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -68,7 +68,7 @@
     "verify:node": "cd ../.. && bun build ./packages/server/test/sqlite-runtime/verify-node.mjs --target=node --conditions=bun --outfile=./packages/server/.verify-node.built.mjs && node ./packages/server/.verify-node.built.mjs"
   },
   "dependencies": {
-    "@syncular/core": "0.39.1"
+    "@syncular/core": "0.39.2"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"

package/src/postgres-fanout.ts

@@ -29,6 +29,14 @@
  * The payload carries `commitSeq` purely for observability/ordering in logs;
  * the wake itself is seq-agnostic (a session pulls whatever it is behind).
  *
+ * ## Listener gaps
+ *
+ * Postgres drops notifications for a session that is not listening, so a
+ * LISTEN connection that dies and reconnects (server restart, failover, a
+ * serverless compute suspending) misses every commit in between. The
+ * connection reports each LISTEN that takes effect through `onListen`; every
+ * report after the first wakes all local sessions with `catchup-required`.
+ *
  * pglite cannot exercise cross-connection NOTIFY, so the integration
  * (`postgres-fanout.integration.test.ts`) is env-gated on `SYNCULAR_PG_URL`
  * and skips cleanly; the payload encode/parse is unit-tested hermetically.
@@ -84,21 +92,27 @@ export function parseFanoutPayload(text: string): FanoutPayload | undefined {
 /** The hub surface the fanout wakes (a `RealtimeHub` satisfies this). */
 export interface FanoutWakeTarget {
   wake(partition: string, reason: WakeReason): void;
+  wakeAll(reason: WakeReason): void;
 }
 
 /**
  * A raw notification connection. Production wires a driver's LISTEN support:
+ *   - Bun.sql and postgres.js: `sql.listen(channel, handler, onListen)`; both
+ *     reconnect a dropped listener and call `onListen` again;
  *   - node-postgres: a dedicated `Client` with `client.on('notification', …)`
- *     after `LISTEN syncular_commit`;
- *   - Bun.sql: `sql.listen(channel, handler)`.
+ *     after `LISTEN syncular_commit`, reconnected by the host.
  * The `notify` side can reuse the main pool (`SELECT pg_notify($1,$2)`), but
- * LISTEN needs its own long-lived connection.
+ * LISTEN needs its own long-lived, unpooled connection.
  */
 export interface PgNotificationConnection {
-  /** Register a payload handler for the channel and begin listening. */
+  /**
+   * Register a payload handler for the channel and begin listening. Call
+   * `onListen` every time LISTEN takes effect, including after a reconnect.
+   */
   listen(
     channel: string,
     handler: (payload: string) => void,
+    onListen: () => void,
   ): Promise<void> | void;
   /** Send a notification on the channel. */
   notify(channel: string, payload: string): Promise<void>;
@@ -122,11 +136,20 @@ export class PostgresFanout {
   async install(hub: FanoutWakeTarget): Promise<void> {
     if (this.#installed) throw new Error('fanout already installed');
     this.#installed = true;
-    await this.#conn.listen(FANOUT_CHANNEL, (payload) => {
-      const parsed = parseFanoutPayload(payload);
-      if (parsed === undefined) return; // ignore malformed frames
-      hub.wake(parsed.partition, FANOUT_WAKE_REASON);
-    });
+    let listening = false;
+    await this.#conn.listen(
+      FANOUT_CHANNEL,
+      (payload) => {
+        const parsed = parseFanoutPayload(payload);
+        if (parsed === undefined) return; // ignore malformed frames
+        hub.wake(parsed.partition, FANOUT_WAKE_REASON);
+      },
+      () => {
+        // A repeated LISTEN follows a gap whose notifications are lost.
+        if (listening) hub.wakeAll(FANOUT_WAKE_REASON);
+        listening = true;
+      },
+    );
   }
 
   /** Fan an applied commit out to the other instances. */

package/src/realtime.ts

@@ -1313,6 +1313,11 @@ export class RealtimeHub {
       session.sendWake(reason);
     }
   }
+
+  /** Wake every session on every partition (fanout listener gap, §8.3). */
+  wakeAll(reason: WakeReason): void {
+    for (const session of this.#sessions) session.sendWake(reason);
+  }
 }
 
 export function createRealtimeHub(config: RealtimeHubConfig): RealtimeHub {