@syncular/server 0.31.0 → 0.32.1

package/src/postgres-storage.ts

@@ -66,11 +66,18 @@ import {
   layoutsOf,
   migratePayload,
   parseLayouts,
+  quoteIdent,
   retiredTableNames,
   rewritePlan,
   rewriteRowSql,
   rewriteValues,
   SCHEMA_META_DDL_POSTGRES,
+  SYNC_COLUMN_VERSIONS_COLUMN,
+  SYNC_PARTITION_COLUMN,
+  SYNC_PAYLOAD_COLUMN,
+  SYNC_ROW_ID_COLUMN,
+  SYNC_SCOPES_COLUMN,
+  SYNC_VERSION_COLUMN,
   type StoredColumnLayout,
   scanRowBatchSql,
   scanRowPageSql,
@@ -89,8 +96,11 @@ import type {
   AuthoritativeQueryResult,
   CheckpointDeclaration,
   ClientCursorInfo,
+  ClientPushResult,
   ClientRecord,
   ClientSubscription,
+  CommitChangeSummary,
+  CommitDetail,
   CommitMetadata,
   CommitMetadataQuery,
   CommitWindowQuery,
@@ -105,6 +115,9 @@ import type {
   ReactionFailureUpdate,
   ReactionListQuery,
   ReactionPruneQuery,
+  RowChangeRecord,
+  RowChangesQuery,
+  RowListQuery,
   RowScanQuery,
   ScopeActivityQuery,
   ScopeCommitActivity,
@@ -2584,6 +2597,11 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
     partition: string,
     query: CommitMetadataQuery,
   ): Promise<CommitMetadata[]> {
+    // Newest-first window, resumed by `afterSeq` (exclusive lower bound) and
+    // ended by `beforeSeq` (exclusive upper bound) when paging older. An
+    // omitted bound is the largest safe commitSeq, so one statement serves
+    // both the bounded and unbounded read.
+    const beforeSeq = query.beforeSeq ?? Number.MAX_SAFE_INTEGER;
     const { rows } = query.table
       ? await this.#exec.query<{
           commit_seq: unknown;
@@ -2594,11 +2612,11 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
         }>(
           `SELECT c.commit_seq, c.client_id, c.client_commit_id, c.actor_id, c.created_at_ms
            FROM sync_commits c
-           WHERE c.partition=$1 AND c.commit_seq>$2
+           WHERE c.partition=$1 AND c.commit_seq>$2 AND c.commit_seq<$3
              AND EXISTS (SELECT 1 FROM sync_changes ch
-               WHERE ch.partition=c.partition AND ch.commit_seq=c.commit_seq AND ch.tbl=$3)
-           ORDER BY c.commit_seq DESC LIMIT $4`,
-          [partition, query.afterSeq, query.table, query.limit],
+               WHERE ch.partition=c.partition AND ch.commit_seq=c.commit_seq AND ch.tbl=$4)
+           ORDER BY c.commit_seq DESC LIMIT $5`,
+          [partition, query.afterSeq, beforeSeq, query.table, query.limit],
         )
       : await this.#exec.query<{
           commit_seq: unknown;
@@ -2609,10 +2627,42 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
         }>(
           `SELECT commit_seq, client_id, client_commit_id, actor_id, created_at_ms
            FROM sync_commits
-           WHERE partition=$1 AND commit_seq>$2
-           ORDER BY commit_seq DESC LIMIT $3`,
-          [partition, query.afterSeq, query.limit],
+           WHERE partition=$1 AND commit_seq>$2 AND commit_seq<$3
+           ORDER BY commit_seq DESC LIMIT $4`,
+          [partition, query.afterSeq, beforeSeq, query.limit],
         );
+    // `changeSample`: one extra statement for the whole page — the first
+    // `sample` changes (change-index order) of every listed commit.
+    const sampleCount =
+      query.changeSample !== undefined &&
+      Number.isInteger(query.changeSample) &&
+      query.changeSample > 0
+        ? query.changeSample
+        : 0;
+    const samples = new Map<number, CommitChangeSummary[]>();
+    if (sampleCount > 0 && rows.length > 0) {
+      const seqs = rows.map((row) => asNumber(row.commit_seq));
+      const { rows: changeRows } = await this.#exec.query<{
+        commit_seq: unknown;
+        tbl: string;
+        row_id: string;
+        op: unknown;
+      }>(
+        `SELECT commit_seq, tbl, row_id, op FROM sync_changes
+         WHERE partition=$1 AND commit_seq IN (${seqs.map((_, index) => `$${index + 2}`).join(',')}) AND idx<$${seqs.length + 2}
+         ORDER BY commit_seq, idx`,
+        [partition, ...seqs, sampleCount],
+      );
+      for (const change of changeRows) {
+        const sample = samples.get(asNumber(change.commit_seq)) ?? [];
+        sample.push({
+          table: change.tbl,
+          rowId: change.row_id,
+          op: asNumber(change.op) === 1 ? 'upsert' : 'delete',
+        });
+        samples.set(asNumber(change.commit_seq), sample);
+      }
+    }
     const out: CommitMetadata[] = [];
     for (const row of rows) {
       const commitSeq = asNumber(row.commit_seq);
@@ -2628,11 +2678,127 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
         createdAtMs: asNumber(row.created_at_ms),
         changeCount: changes.rows.reduce((sum, c) => sum + asNumber(c.n), 0),
         tables: changes.rows.map((c) => c.tbl),
+        ...(sampleCount > 0 ? { sample: samples.get(commitSeq) ?? [] } : {}),
       });
     }
     return out;
   }
 
+  async getCommit(
+    partition: string,
+    commitSeq: number,
+  ): Promise<CommitDetail | undefined> {
+    const { rows } = await this.#exec.query<{
+      client_id: string;
+      client_commit_id: string;
+      actor_id: string;
+      created_at_ms: unknown;
+    }>(
+      'SELECT client_id, client_commit_id, actor_id, created_at_ms FROM sync_commits WHERE partition=$1 AND commit_seq=$2',
+      [partition, commitSeq],
+    );
+    const meta = rows[0];
+    if (meta === undefined) return undefined;
+    const { rows: changeRows } = await this.#exec.query<ChangeRecord>(
+      'SELECT tbl, row_id, op, row_version, scopes, payload FROM sync_changes WHERE partition=$1 AND commit_seq=$2 ORDER BY idx',
+      [partition, commitSeq],
+    );
+    const changes = changeRows.map(toStoredChange);
+    return {
+      commitSeq,
+      clientId: meta.client_id,
+      clientCommitId: meta.client_commit_id,
+      actorId: meta.actor_id,
+      createdAtMs: asNumber(meta.created_at_ms),
+      changeCount: changes.length,
+      tables: [...new Set(changes.map((change) => change.table))].sort(),
+      changes,
+    };
+  }
+
+  async listRowChanges(
+    partition: string,
+    query: RowChangesQuery,
+  ): Promise<RowChangeRecord[]> {
+    // Retained-log read for one row: no dedicated index (the write path pays
+    // nothing for it), bounded by retention (§4.6).
+    const { rows } = await this.#exec.query<{
+      commit_seq: unknown;
+      op: unknown;
+      row_version: unknown;
+      actor_id: string;
+      client_id: string;
+      created_at_ms: unknown;
+    }>(
+      `SELECT ch.commit_seq, ch.op, ch.row_version, c.actor_id, c.client_id, c.created_at_ms
+       FROM sync_changes ch
+       JOIN sync_commits c
+         ON c.partition=ch.partition AND c.commit_seq=ch.commit_seq
+       WHERE ch.partition=$1 AND ch.tbl=$2 AND ch.row_id=$3
+       ORDER BY ch.commit_seq DESC, ch.idx DESC LIMIT $4`,
+      [partition, query.table, query.rowId, query.limit],
+    );
+    return rows.map((row) => ({
+      commitSeq: asNumber(row.commit_seq),
+      op: asNumber(row.op) === 1 ? 'upsert' : 'delete',
+      ...(row.row_version === null || row.row_version === undefined
+        ? {}
+        : { rowVersion: asNumber(row.row_version) }),
+      actorId: row.actor_id,
+      clientId: row.client_id,
+      createdAtMs: asNumber(row.created_at_ms),
+    }));
+  }
+
+  async listRows(partition: string, query: RowListQuery): Promise<StoredRow[]> {
+    // Keyset page over the row table's (partition, rowId) primary key: an
+    // index range read, no scope filter, no per-row lookup.
+    const { rows } = await this.#exec.query<RowRecord>(
+      `SELECT ${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, ${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, ${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, ${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, ${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions
+       FROM ${quoteIdent(this.table(query.table).name)}
+       WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=$1 AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}>$2
+       ORDER BY ${quoteIdent(SYNC_ROW_ID_COLUMN)} LIMIT $3`,
+      [partition, query.afterRowId ?? '', query.limit],
+    );
+    return rows.map(toStoredRow);
+  }
+
+  async countRows(partition: string, table: string): Promise<number> {
+    const { rows } = await this.#exec.query<{ n: unknown }>(
+      `SELECT count(*) AS n FROM ${quoteIdent(this.table(table).name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=$1`,
+      [partition],
+    );
+    return rows[0] === undefined ? 0 : asNumber(rows[0].n);
+  }
+
+  async listPushResults(
+    partition: string,
+    clientCommitId: string,
+  ): Promise<ClientPushResult[]> {
+    // Retained outcomes for one clientCommitId: no dedicated index, ordered
+    // by client so the read is deterministic.
+    const { rows } = await this.#exec.query<{
+      client_id: string;
+      result: unknown;
+    }>(
+      'SELECT client_id, result FROM sync_push_results WHERE partition=$1 AND client_commit_id=$2 ORDER BY client_id',
+      [partition, clientCommitId],
+    );
+    return rows.map((row) => {
+      try {
+        return {
+          clientId: row.client_id,
+          result: deserializePushResult(asJson(row.result)),
+        };
+      } catch {
+        throw syncError(
+          'sync.idempotency_cache_miss',
+          'persisted push result unreadable (§6.3)',
+        );
+      }
+    });
+  }
+
   async scopeActivity(
     partition: string,
     query: ScopeActivityQuery,
@@ -2674,27 +2840,6 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
     return out;
   }
 
-  async getRowScopes(
-    partition: string,
-    table: string,
-    rowId: string,
-  ): Promise<
-    { serverVersion: number; scopes: Record<string, string> } | undefined
-  > {
-    const { rows } = await this.#exec.query<{
-      server_version: unknown;
-      scopes: unknown;
-    }>(selectRowScopesSql(this.table(table), 'postgres'), [partition, rowId]);
-    const row = rows[0];
-    if (row === undefined) return undefined;
-    return {
-      serverVersion: asNumber(row.server_version),
-      scopes: (typeof row.scopes === 'string'
-        ? JSON.parse(row.scopes)
-        : row.scopes) as Record<string, string>,
-    };
-  }
-
   async listPartitions(): Promise<string[]> {
     return (await this.listPartitionRegistry()).map((entry) => entry.partition);
   }

package/src/push.ts

@@ -503,6 +503,7 @@ async function applyOperation(
         if (
           present[i] &&
           !crdtIndexes.has(i) &&
+          i !== table.primaryKeyIndex &&
           effectiveVersion(i) > op.baseVersion
         ) {
           marked.push(i);
@@ -978,7 +979,20 @@ async function enforceReferences(
   const operations: ValidateCommitOperation[] = [];
   const originByIndex: number[] = [];
 
+  const finalByRow = new Map<
+    string,
+    { readonly first: StagedWrite; readonly last: StagedWrite }
+  >();
   for (const write of staged) {
+    const rowKey = `${write.table.name}\u0000${write.rowId}`;
+    const existing = finalByRow.get(rowKey);
+    finalByRow.set(rowKey, {
+      first: existing?.first ?? write,
+      last: write,
+    });
+  }
+
+  for (const { last: write } of finalByRow.values()) {
     if (write.op !== 'upsert' || write.values === undefined) continue;
     for (const reference of write.table.references) {
       const value = write.values[reference.columnIndex];
@@ -1028,9 +1042,9 @@ async function enforceReferences(
     readonly rowId: string;
     readonly originOpIndex: number;
   }> = [];
-  for (const write of staged) {
-    if (write.op === 'delete' && write.stored !== undefined) {
-      schedule(write.table, write.rowId, write.opIndex, scheduled, queue);
+  for (const { first, last } of finalByRow.values()) {
+    if (last.op === 'delete' && first.stored !== undefined) {
+      schedule(last.table, last.rowId, last.opIndex, scheduled, queue);
     }
   }
 
@@ -1040,6 +1054,13 @@ async function enforceReferences(
     const key = `${item.table.name}\u0000${item.rowId}`;
     if (processed.has(key)) continue;
     processed.add(key);
+    const parentPkColumn = item.table.columns[item.table.primaryKeyIndex];
+    const parentKeyValue: RowValue =
+      parentPkColumn?.type === 'integer'
+        ? Number(item.rowId)
+        : parentPkColumn?.type === 'boolean'
+          ? item.rowId === 'true'
+          : item.rowId;
     for (const reference of item.table.referencedBy) {
       if (tx.scanRowsByIndex === undefined) {
         throw new Error(
@@ -1052,7 +1073,7 @@ async function enforceReferences(
         const page = await tx.scanRowsByIndex({
           table: reference.table,
           index: reference.index,
-          values: [item.rowId],
+          values: [parentKeyValue],
           afterRowId,
           limit: 1_000,
         });
@@ -1081,6 +1102,21 @@ async function enforceReferences(
         );
       }
       for (const childRow of children) {
+        if (reference.onDelete === 'CASCADE') {
+          if (
+            !schedule(
+              child,
+              childRow.rowId,
+              item.originOpIndex,
+              scheduled,
+              queue,
+            )
+          ) {
+            continue;
+          }
+        } else if (scheduled.has(`${child.name}\u0000${childRow.rowId}`)) {
+          continue;
+        }
         if (originByIndex.length >= cascadeLimit) {
           return {
             kind: 'terminate',
@@ -1091,11 +1127,6 @@ async function enforceReferences(
             ),
           };
         }
-        if (
-          !schedule(child, childRow.rowId, item.originOpIndex, scheduled, queue)
-        ) {
-          continue;
-        }
         const syntheticIndex = clientOpCount + originByIndex.length;
         const storedValues = decodeRow(child.columns, childRow.payload);
         if (reference.onDelete === 'CASCADE') {

package/src/realtime.ts

@@ -23,6 +23,7 @@ import {
   encodeMessage,
   encodePresenceError,
   encodePresenceFanout,
+  isSupportedProtocolWireVersion,
   MessageStreamScanner,
   PROTOCOL_WIRE_VERSION,
   type PresenceKind,
@@ -48,6 +49,7 @@ import {
   syncError,
 } from './errors';
 import { emitEvent, type SyncularServerEvents } from './events';
+import { composeEvents } from './events-ring';
 import { createSyncResponseStream } from './handler';
 import {
   type CompiledSchema,
@@ -277,6 +279,8 @@ export class RealtimeSession {
   #registrationGeneration = 0;
   /** Generation of the most recent refresh whose result was applied. */
   #registrationApplied = 0;
+  /** Highest sequence that required a catch-up wake for this session. */
+  #wakeRequiredThroughSeq: number;
 
   constructor(
     hub: RealtimeHub,
@@ -300,6 +304,7 @@ export class RealtimeSession {
     this.cursor = cursor;
     this.lastKnownSeq = latestSeq;
     this.wakePending = cursor < latestSeq;
+    this.#wakeRequiredThroughSeq = cursor < latestSeq ? latestSeq : 0;
     this.registrations = registrations;
     this.openedAtMs = clock();
     this.#send = options.send;
@@ -335,9 +340,9 @@ export class RealtimeSession {
     // proves those commits no longer need socket notifications, so the next
     // notification must be adjacent to the acknowledged cursor.
     this.lastKnownSeq = Math.max(this.lastKnownSeq, this.cursor);
-    if (this.cursor >= this.lastKnownSeq) this.wakePending = false;
+    if (this.cursor >= this.#wakeRequiredThroughSeq) this.wakePending = false;
     // §8.2: acks update the client cursor record without an HTTP pull.
-    this.#persistCursor();
+    this.#persistCursor(cursor);
   }
 
   /**
@@ -570,7 +575,7 @@ export class RealtimeSession {
     try {
       const requestedWireVersion =
         (requestBytes[4] ?? 0) | ((requestBytes[5] ?? 0) << 8);
-      if (requestedWireVersion === 1 || requestedWireVersion === 2) {
+      if (isSupportedProtocolWireVersion(requestedWireVersion)) {
         this.wireVersion = requestedWireVersion;
       }
       let stream: AsyncIterable<Uint8Array> | undefined;
@@ -720,7 +725,7 @@ export class RealtimeSession {
     this.#hub.disconnect(this);
   }
 
-  #persistCursor(): void {
+  #persistCursor(cursor: number): 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.
@@ -730,7 +735,7 @@ export class RealtimeSession {
         this.clientId,
         this.actorId,
         this.logEpoch,
-        this.cursor,
+        cursor,
         this.#clock(),
       );
     })();
@@ -766,6 +771,10 @@ export class RealtimeSession {
 
   sendWake(reason: WakeReason): void {
     this.wakePending = true;
+    this.#wakeRequiredThroughSeq = Math.max(
+      this.#wakeRequiredThroughSeq,
+      this.lastKnownSeq,
+    );
     this.#sendSafe(
       JSON.stringify({
         event: 'sync',
@@ -907,8 +916,16 @@ export class RealtimeSession {
   }
 }
 
+/** One open realtime socket. */
+export interface RealtimeConnection {
+  readonly sessionId: string;
+  readonly clientId: string;
+  readonly actorId: string;
+  readonly openedAtMs: number;
+}
+
 export class RealtimeHub {
-  readonly #config: RealtimeHubConfig;
+  #config: RealtimeHubConfig;
   readonly #schema: CompiledSchema;
   readonly #sessions = new Set<RealtimeSession>();
   /** §8.6 presence registry — ephemeral, in-memory, never persisted. */
@@ -928,10 +945,35 @@ export class RealtimeHub {
     );
   }
 
+  /**
+   * Compose `sink` into the hub's `events`, so socket rounds and sessions
+   * opened afterwards report to it as well. `createSyncularHono` uses it to
+   * feed the admin console's event ring.
+   */
+  addEventSink(sink: SyncularServerEvents): void {
+    const events = this.#config.events;
+    this.#config = {
+      ...this.#config,
+      events: events === undefined ? sink : composeEvents(events, sink),
+    };
+  }
+
   get sessionCount(): number {
     return this.#sessions.size;
   }
 
+  /** The partition's open sockets, for the admin console. */
+  connections(partition: string): RealtimeConnection[] {
+    return [...this.#sessions]
+      .filter((session) => session.partition === partition)
+      .map((session) => ({
+        sessionId: session.sessionId,
+        clientId: session.clientId,
+        actorId: session.actorId,
+        openedAtMs: session.openedAtMs,
+      }));
+  }
+
   /** §8.6.2 published-document size cap (bytes). */
   get maxPresenceBytes(): number {
     return this.#config.maxPresenceBytes ?? DEFAULT_MAX_PRESENCE_BYTES;
@@ -1087,6 +1129,12 @@ export class RealtimeHub {
       ...(this.#config.commitValidator !== undefined
         ? { commitValidator: this.#config.commitValidator }
         : {}),
+      ...(this.#config.reactionPlanner !== undefined
+        ? { reactionPlanner: this.#config.reactionPlanner }
+        : {}),
+      ...(this.#config.checkpoints !== undefined
+        ? { checkpoints: this.#config.checkpoints }
+        : {}),
       ...(this.#config.clock !== undefined
         ? { clock: this.#config.clock }
         : {}),
@@ -1114,6 +1162,9 @@ export class RealtimeHub {
       ...(this.#config.onError !== undefined
         ? { onError: this.#config.onError }
         : {}),
+      ...(this.#config.mapError !== undefined
+        ? { mapError: this.#config.mapError }
+        : {}),
       realtime: this,
     };
   }
@@ -1177,7 +1228,9 @@ export class RealtimeHub {
       this.#config.maxDeltaBytes ?? DEFAULT_MAX_DELTA_BYTES,
       storage,
       registry.logEpoch,
-      record?.wireVersion ?? PROTOCOL_WIRE_VERSION,
+      record !== undefined && isSupportedProtocolWireVersion(record.wireVersion)
+        ? record.wireVersion
+        : PROTOCOL_WIRE_VERSION,
       this.#config.events,
     );
     this.#sessions.add(session);

package/src/seed.ts

@@ -24,6 +24,7 @@ import { SyncError } from './errors';
 import type { SyncularServerEvent, SyncularServerEvents } from './events';
 import { composeEvents } from './events-ring';
 import { handleSyncRequest } from './handler';
+import { renderScopeValue } from './scopes';
 
 /** One app-shaped seed mutation — the same vocabulary as client mutations. */
 export type SeedMutation =
@@ -171,11 +172,11 @@ export async function seedMutations(
       (column) => (byColumn.get(column.name) ?? null) as RowValue,
     );
     const pkIndex = table.columns.findIndex((c) => c.name === table.primaryKey);
-    const rowId = values[pkIndex];
-    if (typeof rowId !== 'string' || rowId.length === 0) {
+    const rowId = renderScopeValue(values[pkIndex]);
+    if (rowId === undefined) {
       throw new SyncError(
         'sync.invalid_request',
-        `seedMutations: table ${table.name}: upsert requires a non-empty string primary key`,
+        `seedMutations: table ${table.name}: upsert requires a non-empty primary key`,
       );
     }
     return {