@syncular/server 0.21.1 → 0.23.0

package/src/pull.ts

@@ -180,6 +180,7 @@ async function signedUrlFields(
 
 function segmentRefFrame(
   record: SegmentRecord,
+  scopeDigest: string,
   extra: { url?: string; urlExpiresAtMs?: number },
 ): ResponseFrame {
   return {
@@ -190,7 +191,11 @@ function segmentRefFrame(
     byteLength: record.byteLength,
     rowCount: record.rowCount,
     asOfCommitSeq: record.asOfCommitSeq,
-    scopeDigest: record.scopeDigest,
+    // The frame reports the digest THIS subscription is authorized under. A
+    // stored entry can carry several digests when identical content was
+    // published under different scopes (§5.1), and the record's primary
+    // digest is not necessarily the caller's (§5.5).
+    scopeDigest,
     ...(record.rowCursor !== null ? { rowCursor: record.rowCursor } : {}),
     ...(record.nextRowCursor !== null
       ? { nextRowCursor: record.nextRowCursor }
@@ -244,6 +249,7 @@ async function* sqliteImageSegment(
     });
     yield segmentRefFrame(
       existing,
+      digest,
       await signedUrlFields(ctx, limits, existing.segmentId, digest, now),
     );
     return true;
@@ -342,6 +348,7 @@ async function* sqliteImageSegment(
   });
   yield segmentRefFrame(
     record,
+    digest,
     await signedUrlFields(
       ctx,
       limits,
@@ -458,6 +465,7 @@ async function* bootstrapSegments(
       });
       yield segmentRefFrame(
         record,
+        digest,
         await signedUrlFields(ctx, limits, record.segmentId, digest, now),
       );
     }

package/src/push.ts

@@ -52,7 +52,9 @@ import type {
   StoredPushResult,
   StoredRow,
 } from './storage';
+import { serveGateRefusal } from './storage';
 import { StorageConstraintError } from './storage-errors';
+import { serveNotReadyError } from './readiness';
 import type {
   CommitValidationReader,
   CommitValidator,
@@ -1356,6 +1358,15 @@ export async function processPushOperationsWithTrace(
       );
     }
     await lockPartitionForPush();
+    // RFC 0007: evaluate the gate on this transaction's own connection while
+    // the partition lock is held, so the migration check and the write share
+    // one transaction and no migration can interleave in between.
+    const gate = await tx.readServeGate(schema.version);
+    const refusal = serveGateRefusal(gate, schema.version, ctx.checkpoints);
+    if (refusal !== undefined) {
+      await tx.rollback();
+      throw serveNotReadyError(refusal);
+    }
     // The optimistic lookup above may have raced another delivery. Re-check
     // only after acquiring partition serialization and before any operation
     // read, validation, merge, or staged write. The re-check runs on the
@@ -1551,6 +1562,13 @@ export async function processPushOperationsWithTrace(
       }
     }
     if (ctx.realtime !== undefined && changes.length > 0) {
+      // RFC 0007 fanout decision: the notification carries the durable commit
+      // entry itself (this commit's `changes`), not a projection read or a pull
+      // window, so fanning it out before the request's buffered read-verify can
+      // never serve a mixed result. Each peer's next pull is gated at the
+      // storage seam; a refused mixed push+pull is safe because the push is
+      // durable and replayable under its commit id. This is commit-entry
+      // durability, not gate inheritance.
       await ctx.realtime.notifyCommit(partition, {
         commitSeq,
         createdAtMs,

package/src/readiness.ts

@@ -7,12 +7,17 @@
  * a structured failure that cannot be confused with request authentication.
  */
 import type { SyncServerConfig } from './context';
+import { type SyncError, syncError } from './errors';
 import { type CompiledSchema, compileSchema } from './schema';
+import type { ServeGateRefusal } from './storage';
 
 export const SYNC_SERVER_READINESS_ERROR_CODE =
   'sync.schema_not_ready' as const;
 
-export type SyncServerReadinessPhase = 'schema_compile' | 'storage_migration';
+export type SyncServerReadinessPhase =
+  | 'schema_compile'
+  | 'storage_migration'
+  | 'backfill_checkpoint';
 
 export class SyncServerReadinessError extends Error {
   override readonly name = 'SyncServerReadinessError';
@@ -42,7 +47,7 @@ export class SyncServerReadinessError extends Error {
  * `cause` locally for the table/column or storage diagnostic.
  */
 export async function ensureSyncServerReady(
-  config: Pick<SyncServerConfig, 'schema' | 'storage'>,
+  config: Pick<SyncServerConfig, 'schema' | 'storage' | 'checkpoints'>,
 ): Promise<void> {
   let compiled: CompiledSchema;
   try {
@@ -55,12 +60,42 @@ export async function ensureSyncServerReady(
     });
   }
   try {
-    await config.storage.ensureSchema(compiled);
+    await config.storage.ensureSchema(compiled, config.checkpoints);
   } catch (cause) {
+    // RFC 0007: a declared-but-incomplete checkpoint is a barrier refusal, not
+    // an ordinary migration failure — hosts distinguish it by `phase` while the
+    // client-visible identity stays `sync.schema_not_ready`.
+    const phase: SyncServerReadinessPhase =
+      (cause as { code?: unknown } | null | undefined)?.code ===
+      'sync.storage.checkpoint_incomplete'
+        ? 'backfill_checkpoint'
+        : 'storage_migration';
     throw new SyncServerReadinessError({
-      phase: 'storage_migration',
+      phase,
       schemaVersion: config.schema.version,
       cause,
     });
   }
 }
+
+/**
+ * RFC 0007: refuse a serve path that observed a closed gate. The projection
+ * name travels in structured details, never in the message.
+ */
+export function serveNotReadyError(refusal: ServeGateRefusal): SyncError {
+  return syncError(
+    SYNC_SERVER_READINESS_ERROR_CODE,
+    'server schema is not ready for this request',
+    refusal.kind === 'checkpoint'
+      ? JSON.stringify({
+          partition: refusal.partition,
+          projection: refusal.name,
+        })
+      : refusal.kind === 'epoch'
+        ? JSON.stringify({ logEpochChanged: true })
+        : JSON.stringify({
+            storedSchemaVersion: refusal.stored,
+            runningSchemaVersion: refusal.running,
+          }),
+  );
+}

package/src/realtime.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
@@ -253,6 +256,14 @@ export class RealtimeSession {
       timer?: ReturnType<typeof setTimeout>;
     }
   >();
+  /** Queued control-plane writes (ack cursor persistence, §8.2). */
+  #controlTail: Promise<void> = Promise.resolve();
+  /** First control-plane failure not yet surfaced by `drain()`. */
+  #controlFailure: unknown = undefined;
+  /** Issue counter for registration refreshes (§8.7). */
+  #registrationGeneration = 0;
+  /** Generation of the most recent refresh whose result was applied. */
+  #registrationApplied = 0;
 
   constructor(
     hub: RealtimeHub,
@@ -313,7 +324,21 @@ export class RealtimeSession {
     this.lastKnownSeq = Math.max(this.lastKnownSeq, this.cursor);
     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(): Promise<void> {
+    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. */
@@ -575,7 +600,28 @@ 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: IteratorResult<Uint8Array>;
+      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();
@@ -590,7 +636,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);
     }
   }
 
@@ -601,22 +647,42 @@ export class RealtimeSession {
     await this.#send(tagged);
   }
 
-  async #refreshRegistrations(): Promise<void> {
-    // §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: boolean): Promise<void> {
+    const generation = ++this.#registrationGeneration;
+    let registrations: Registration[];
     try {
-      this.registrations = await this.#hub.loadRegistrations(
+      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);
   }
 
@@ -628,8 +694,11 @@ export class RealtimeSession {
     this.#hub.disconnect(this);
   }
 
-  async #persistCursor(): Promise<void> {
-    try {
+  #persistCursor(): void {
+    // §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,
@@ -638,9 +707,15 @@ export class RealtimeSession {
         this.cursor,
         this.#clock(),
       );
-    } catch {
-      // Cursor persistence is best-effort; the next pull repairs it.
-    }
+    })();
+    write.catch((error: unknown) => {
+      // 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
@@ -1106,6 +1181,30 @@ export class RealtimeHub {
     }
   }
 
+  /**
+   * 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: string, actorId?: string): Promise<void> {
+    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: string, reason: WakeReason): void {
     for (const session of this.#sessions) {

package/src/relational-rows.ts

@@ -191,6 +191,42 @@ export 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 function assertPhysicalColumns(
+  table: CompiledTable,
+  existingColumns: ReadonlySet<string>,
+): void {
+  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: CompiledTable,