@syncular/server 0.21.1 → 0.23.0

package/dist/realtime.d.ts

@@ -3,7 +3,10 @@
  *
  * A `RealtimeSession` wraps a connected socket's send/receive callbacks:
  * the host feeds inbound text frames to `handleMessage`, binary frames to
- * `handleBinary`, and wires `session.close()` to socket close. Initial
+ * `handleBinary`, and wires `session.close()` to socket close. `handleMessage`
+ * queues the ack's cursor write without awaiting it, so `drain()` is the
+ * awaitable boundary a host uses before closing its storage or ending a
+ * hibernatable event (§8.2). Initial
  * subscription registration comes from the client's most recent pull
  * (§8.1, loaded from the client record); a sync round completed on the
  * connection replaces it at round end (§8.7). Deltas are complete SSP2
@@ -112,6 +115,13 @@ export declare class RealtimeSession {
     /** Feed an inbound text frame (client → server control message, §8.2
      * ack, §8.6.2 presence). */
     handleMessage(text: string): void;
+    /**
+     * Resolve once every queued control-plane write has settled (§8.2). A host
+     * awaits this before it closes its storage or ends a hibernatable event, so
+     * an ack's cursor write is not abandoned mid-flight. A persistence failure
+     * surfaces here instead of vanishing.
+     */
+    drain(): Promise<void>;
     /** Deliver a fanout event to this session (called by the hub for peers,
      * §8.6.3 receive authorization checked by the caller). */
     receivePresence(scopeKey: string, kind: PresenceKind, actorId: string, clientId: string, doc: PresenceDoc | null): void;
@@ -135,6 +145,21 @@ export declare class RealtimeSession {
      * coordinated hosts await it to retain their partition FIFO through commit.
      */
     handleBinary(bytes: Uint8Array): Promise<void> | undefined;
+    /**
+     * Reload this connection's registrations and reconcile presence (§8.7).
+     * The round-end refresh and the host-initiated `RealtimeHub.refreshScopes`
+     * both route through here under one per-session generation, so a load that
+     * resolves late can never overwrite a newer result: a slow resolver may
+     * return scopes a later refresh already revoked, and the later refresh
+     * keeps the connection's current grants.
+     *
+     * `failClosed` selects the failure semantics. The round-end refresh keeps
+     * the previous registrations so a failed round changes nothing. The host
+     * refresh empties them so a revoked or unreadable grant stops receiving
+     * deltas immediately; it also survives a newer round-end refresh that
+     * failed, because that round applied nothing.
+     */
+    refreshRegistrations(failClosed: boolean): Promise<void>;
     sendHeartbeat(): void;
     sendWake(reason: WakeReason): void;
     /** Called by the hub for every applied commit notification. */
@@ -182,6 +207,20 @@ export declare class RealtimeHub {
     disconnect(session: RealtimeSession): void;
     /** RealtimeNotifier: fan an applied commit out to matching sessions. */
     notifyCommit(partition: string, commit: StoredCommit): Promise<void>;
+    /**
+     * Host-initiated, fail-closed registration refresh (§8.7). A host calls this
+     * after it changes an actor's membership or connection state, so the
+     * partition's connected sessions stop using grants the host already revoked
+     * without waiting for the client to happen to run a round.
+     *
+     * This differs deliberately from the round-end refresh
+     * (`RealtimeSession.refreshRegistrations`), which keeps the previous
+     * registrations when the client record or resolver cannot be read so a
+     * failed round changes nothing. Here an unresolvable session is emptied:
+     * a revoked or unreadable grant must stop receiving deltas rather than live
+     * on until the next round. Presence is reconciled exactly as at round end.
+     */
+    refreshScopes(partition: string, actorId?: string): Promise<void>;
     /** Broadcast a wake-up (host-initiated resync, schema rollover, §8.3). */
     wake(partition: string, reason: WakeReason): void;
 }

package/dist/realtime.js

@@ -3,7 +3,10 @@
  *
  * A `RealtimeSession` wraps a connected socket's send/receive callbacks:
  * the host feeds inbound text frames to `handleMessage`, binary frames to
- * `handleBinary`, and wires `session.close()` to socket close. Initial
+ * `handleBinary`, and wires `session.close()` to socket close. `handleMessage`
+ * queues the ack's cursor write without awaiting it, so `drain()` is the
+ * awaitable boundary a host uses before closing its storage or ending a
+ * hibernatable event (§8.2). Initial
  * subscription registration comes from the client's most recent pull
  * (§8.1, loaded from the client record); a sync round completed on the
  * connection replaces it at round end (§8.7). Deltas are complete SSP2
@@ -147,6 +150,14 @@ export class RealtimeSession {
     /** §8.6.4 rate cap: per-scope-key last-fanout time + a pending latest
      * document coalesced while over the cap. */
     #presenceRate = new Map();
+    /** Queued control-plane writes (ack cursor persistence, §8.2). */
+    #controlTail = Promise.resolve();
+    /** First control-plane failure not yet surfaced by `drain()`. */
+    #controlFailure = undefined;
+    /** Issue counter for registration refreshes (§8.7). */
+    #registrationGeneration = 0;
+    /** Generation of the most recent refresh whose result was applied. */
+    #registrationApplied = 0;
     constructor(hub, options, registrations, cursor, latestSeq, clock, maxDeltaBytes, storage, logEpoch, wireVersion, events) {
         this.sessionId = crypto.randomUUID();
         this.partition = options.partition;
@@ -198,7 +209,21 @@ export class RealtimeSession {
         if (this.cursor >= this.lastKnownSeq)
             this.wakePending = false;
         // §8.2: acks update the client cursor record without an HTTP pull.
-        void this.#persistCursor();
+        this.#persistCursor();
+    }
+    /**
+     * Resolve once every queued control-plane write has settled (§8.2). A host
+     * awaits this before it closes its storage or ends a hibernatable event, so
+     * an ack's cursor write is not abandoned mid-flight. A persistence failure
+     * surfaces here instead of vanishing.
+     */
+    drain() {
+        return this.#controlTail.then(() => {
+            const failure = this.#controlFailure;
+            this.#controlFailure = undefined;
+            if (failure !== undefined)
+                throw failure;
+        });
     }
     /** §8.6.2 inbound presence publish/leave from the client. */
     #handlePresence(text) {
@@ -421,7 +446,26 @@ export class RealtimeSession {
             // begin its next round as soon as END *arrives* (§8.7 rule 3), so
             // in-flight must end with the send, not with generator cleanup.
             const iterator = stream[Symbol.asyncIterator]();
-            let step = await iterator.next();
+            let step;
+            try {
+                step = await iterator.next();
+            }
+            catch (error) {
+                // The buffered read-verify refusal is thrown on the generator's first
+                // `next()`, before any chunk is yielded (the generator builds the whole
+                // response, then verifies). Nothing has escaped, so it is delivered as
+                // the same §8.4 ERROR frame HTTP returns rather than a silent close. A
+                // throw after the first chunk still takes the §8.7 violation path.
+                if (error instanceof DecodeError || error instanceof SyncError) {
+                    const sync = error instanceof SyncError
+                        ? error
+                        : syncError(error.code, error.message);
+                    finishRound();
+                    await this.#sendRoundChunk(errorResponseBytes(sync, this.wireVersion, this.logEpoch));
+                    return;
+                }
+                throw error;
+            }
             while (!step.done) {
                 const chunk = step.value;
                 step = await iterator.next();
@@ -439,7 +483,7 @@ export class RealtimeSession {
             finishRound();
             // §8.7 registration at round end: reload the persisted list — it
             // only advances on success, so failed rounds change nothing.
-            await this.#refreshRegistrations();
+            await this.refreshRegistrations(false);
         }
     }
     async #sendRoundChunk(chunk) {
@@ -448,19 +492,41 @@ export class RealtimeSession {
         tagged.set(chunk, 1);
         await this.#send(tagged);
     }
-    async #refreshRegistrations() {
-        // §8.6.3: a registration change re-derives the presence grant — capture
-        // the keys before, reconcile after (leaves on lost keys, snapshots on
-        // gained keys).
-        const previousKeys = this.#currentScopeKeys();
+    /**
+     * Reload this connection's registrations and reconcile presence (§8.7).
+     * The round-end refresh and the host-initiated `RealtimeHub.refreshScopes`
+     * both route through here under one per-session generation, so a load that
+     * resolves late can never overwrite a newer result: a slow resolver may
+     * return scopes a later refresh already revoked, and the later refresh
+     * keeps the connection's current grants.
+     *
+     * `failClosed` selects the failure semantics. The round-end refresh keeps
+     * the previous registrations so a failed round changes nothing. The host
+     * refresh empties them so a revoked or unreadable grant stops receiving
+     * deltas immediately; it also survives a newer round-end refresh that
+     * failed, because that round applied nothing.
+     */
+    async refreshRegistrations(failClosed) {
+        const generation = ++this.#registrationGeneration;
+        let registrations;
         try {
-            this.registrations = await this.#hub.loadRegistrations(this.partition, this.actorId, this.clientId);
+            registrations = await this.#hub.loadRegistrations(this.partition, this.actorId, this.clientId);
         }
         catch {
-            // Fail closed: an unreadable record or resolver failure leaves the
-            // previous registrations in place; the next round repairs it.
-            return;
+            if (!failClosed)
+                return;
+            // Fail closed (host refresh): drop every grant on the connection.
+            registrations = [];
         }
+        // A newer refresh already applied its result; this late one is stale.
+        if (generation < this.#registrationApplied)
+            return;
+        this.#registrationApplied = generation;
+        // §8.6.3: a registration change re-derives the presence grant — capture
+        // the keys before, reconcile after (leaves on lost keys, snapshots on
+        // gained keys).
+        const previousKeys = this.#currentScopeKeys();
+        this.registrations = registrations;
         this.reconcilePresence(previousKeys);
     }
     /** §8.7 protocol violation: drop the connection, fail loud. The
@@ -470,13 +536,19 @@ export class RealtimeSession {
         this.#closeSocket?.();
         this.#hub.disconnect(this);
     }
-    async #persistCursor() {
-        try {
+    #persistCursor() {
+        // §8.2: start the write now and keep it on the control tail so `drain()`
+        // can await it. Two acks may write concurrently: storage folds them with
+        // `MAX(cursor, ?)`, so neither order loses the later cursor.
+        const write = (async () => {
             await this.#storage.advanceClientCursor(this.partition, this.clientId, this.actorId, this.logEpoch, this.cursor, this.#clock());
-        }
-        catch {
-            // Cursor persistence is best-effort; the next pull repairs it.
-        }
+        })();
+        write.catch((error) => {
+            // Best-effort for the connection (the next pull repairs the cursor);
+            // `drain()` carries the first failure to the host.
+            this.#controlFailure ??= error;
+        });
+        this.#controlTail = Promise.allSettled([this.#controlTail, write]).then(() => undefined);
     }
     /** Fire-and-forget send for control text and deltas; a host send
      * failure surfaces on the socket, not here. */
@@ -872,6 +944,31 @@ export class RealtimeHub {
             session.deliverCommit(commit);
         }
     }
+    /**
+     * Host-initiated, fail-closed registration refresh (§8.7). A host calls this
+     * after it changes an actor's membership or connection state, so the
+     * partition's connected sessions stop using grants the host already revoked
+     * without waiting for the client to happen to run a round.
+     *
+     * This differs deliberately from the round-end refresh
+     * (`RealtimeSession.refreshRegistrations`), which keeps the previous
+     * registrations when the client record or resolver cannot be read so a
+     * failed round changes nothing. Here an unresolvable session is emptied:
+     * a revoked or unreadable grant must stop receiving deltas rather than live
+     * on until the next round. Presence is reconciled exactly as at round end.
+     */
+    async refreshScopes(partition, actorId) {
+        for (const session of [...this.#sessions]) {
+            if (session.partition !== partition)
+                continue;
+            if (actorId !== undefined && session.actorId !== actorId)
+                continue;
+            // Fail closed (see the doc above): an unreadable client record drops
+            // every grant on the connection. The session's generation guard keeps
+            // this revocation from being overwritten by a slower round-end reload.
+            await session.refreshRegistrations(true);
+        }
+    }
     /** Broadcast a wake-up (host-initiated resync, schema rollover, §8.3). */
     wake(partition, reason) {
         for (const session of this.#sessions) {

package/dist/relational-rows.d.ts

@@ -75,6 +75,26 @@ export declare function columnSqlType(column: RowColumn, dialect: RelationalDial
  * materialized), version, scopes, payload.
  */
 export declare function tableColumnNames(table: CompiledTable): string[];
+/**
+ * The physical column set the row codec and the scope index read for one
+ * configured table. The persisted marker's layouts describe the codec's app
+ * columns only and its version number is the schema's, not the database's, so
+ * a same-version database that is missing a storage-internal meta column (a
+ * version-only bump whose ALTER never ran) still has to be refused: compare
+ * the physical table and fail closed without writing a migration.
+ *
+ * `existingColumns` must be resolved the way the unqualified row queries
+ * resolve the table — on PostgreSQL, through the session `search_path`, not
+ * `current_schema()`. A search path whose first schema is not where the
+ * configured tables live is outside the supported contract: DDL is created in
+ * that first schema, so `ensureSchema` already writes shadow tables there.
+ *
+ * Scope: this checks that the columns EXIST. Stored types, nullability, and
+ * non-column storage internals (the tombstone bookkeeping) stay outside it,
+ * because a wrong type or nullability is a codec-compatibility question the
+ * persisted layouts answer for app columns.
+ */
+export declare function assertPhysicalColumns(table: CompiledTable, existingColumns: ReadonlySet<string>): void;
 /** CREATE TABLE IF NOT EXISTS for one app table. */
 export declare function createTableDdl(table: CompiledTable, dialect: RelationalDialect): string;
 /**

package/dist/relational-rows.js

@@ -169,6 +169,35 @@ export function tableColumnNames(table) {
         SYNC_COLUMN_VERSIONS_COLUMN,
     ];
 }
+/**
+ * The physical column set the row codec and the scope index read for one
+ * configured table. The persisted marker's layouts describe the codec's app
+ * columns only and its version number is the schema's, not the database's, so
+ * a same-version database that is missing a storage-internal meta column (a
+ * version-only bump whose ALTER never ran) still has to be refused: compare
+ * the physical table and fail closed without writing a migration.
+ *
+ * `existingColumns` must be resolved the way the unqualified row queries
+ * resolve the table — on PostgreSQL, through the session `search_path`, not
+ * `current_schema()`. A search path whose first schema is not where the
+ * configured tables live is outside the supported contract: DDL is created in
+ * that first schema, so `ensureSchema` already writes shadow tables there.
+ *
+ * Scope: this checks that the columns EXIST. Stored types, nullability, and
+ * non-column storage internals (the tombstone bookkeeping) stay outside it,
+ * because a wrong type or nullability is a codec-compatibility question the
+ * persisted layouts answer for app columns.
+ */
+export function assertPhysicalColumns(table, existingColumns) {
+    if (existingColumns.size === 0) {
+        throw new Error(`table ${JSON.stringify(table.name)} is missing from the database at the stored schema version — refusing to serve a database whose rows the running code cannot read`);
+    }
+    for (const name of tableColumnNames(table)) {
+        if (existingColumns.has(name))
+            continue;
+        throw new Error(`table ${JSON.stringify(table.name)} is missing column ${JSON.stringify(name)} at the stored schema version — refusing to serve a database whose rows the running code cannot read`);
+    }
+}
 /** CREATE TABLE IF NOT EXISTS for one app table. */
 export function createTableDdl(table, dialect) {
     const versionType = dialect === 'postgres' ? 'BIGINT' : 'INTEGER';

package/dist/s3-segment-store.d.ts

@@ -6,12 +6,19 @@
  * Key layout (deterministic — every lookup is a GET/HEAD, never a LIST):
  *
  *   {keyPrefix}seg/sha256/{hex}
- *     The segment bytes, verbatim (the object body MUST be exactly the
- *     content-addressed bytes so presigned GETs serve them directly and
- *     the client's §5.1 hash check passes). The full `SegmentRecord`
- *     (minus bytes) rides along as object user metadata
- *     `x-amz-meta-syncular-record` = base64url(JSON), so `get` is a
- *     single GET.
+ *     The segment bytes, verbatim and immutable (the object body MUST be
+ *     exactly the content-addressed bytes so presigned GETs serve them
+ *     directly and the client's §5.1 hash check passes).
+ *
+ *   {keyPrefix}rec/sha256/{hex}.json
+ *     The `SegmentRecord` (§5.1). It is the one MUTABLE object of the two:
+ *     the scope-digest set is a union that every publication extends, so
+ *     the merge is a read-modify-write. Keeping the record in the body (not
+ *     in the bytes object's user metadata) is what makes that write
+ *     conditional — a body ETag changes when the union changes, while the
+ *     bytes ETag is a content hash and is identical for identical bytes. A
+ *     `412` re-reads and merges again, so no concurrent publication can drop
+ *     another one's digest. `get` therefore reads two objects.
  *
  *   {keyPrefix}find/{sha256Hex(canonical reuse key)}.json
  *     Whole-table reuse pointer (§5.3): written only when
@@ -21,9 +28,14 @@
  *     confirm the segment object itself still exists — lifecycle GC may
  *     remove objects independently of pointers).
  *
+ * Records written before the split kept the record in the bytes object's
+ * user metadata `x-amz-meta-syncular-record`; `get` still reads that shape
+ * and the next `put` materializes the record object from it, so an upgrade
+ * loses no cache entry.
+ *
  * TTL mapping: expiry is **store-side and authoritative** — `expiresAtMs`
- * (put-time + `ttlMs`, default 24 h) is recorded in the object metadata
- * and the pointer; `get` returns expired records so §5.5 can answer
+ * (put-time + `ttlMs`, default 24 h) is recorded in the record and the
+ * pointer; `get` returns expired records so §5.5 can answer
  * `sync.segment_expired`, and `find` filters them out itself. S3 lifecycle
  * expiration is garbage collection only: configure it comfortably ABOVE
  * `ttlMs` (e.g. 2 days for the 24 h default) so clients normally see the