@syncular/server 0.30.16 → 0.32.0

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/pull.ts

@@ -23,7 +23,6 @@ import {
 import { scopeDigest } from './scopes';
 import type { SegmentRecord, SegmentStore } from './segment-store';
 import { issueSegmentUrl } from './signed-url';
-import type { SqliteImageBuilder } from './sqlite-image';
 import type { ServerStorage, StoredCommit, StoredRow } from './storage';
 import { projectRowPayload, projectRowValues } from './schema-window';
 
@@ -33,26 +32,6 @@ const imageBuilds = new WeakMap<
   WeakMap<SegmentStore, Map<string, Promise<SegmentRecord>>>
 >();
 
-/**
- * Resolve the §5.3 image builder: the host-injected one if present, else the
- * in-tree `buildSqliteImage` on a Bun runtime (dynamic import so `bun:sqlite`
- * is never a static dep of the neutral core), else `undefined` (rows lane).
- * Memoized so the dynamic import happens at most once per process.
- */
-let cachedDefaultBuilder: SqliteImageBuilder | null | undefined;
-async function resolveImageBuilder(
-  ctx: SyncRequestContext,
-): Promise<SqliteImageBuilder | undefined> {
-  if (ctx.sqliteImageBuilder !== undefined) return ctx.sqliteImageBuilder;
-  if (cachedDefaultBuilder === undefined) {
-    const hasBun = (globalThis as { Bun?: unknown }).Bun !== undefined;
-    cachedDefaultBuilder = hasBun
-      ? (await import('./sqlite-bun')).buildSqliteImage
-      : null;
-  }
-  return cachedDefaultBuilder ?? undefined;
-}
-
 /** §4.2 accept bitmask. */
 export const ACCEPT_INLINE_ROWS = 1 << 0;
 export const ACCEPT_EXTERNAL_ROWS = 1 << 1;
@@ -280,14 +259,9 @@ async function* sqliteImageSegment(
   // rows page — smaller tables stay on the (typically inline) rows lane.
   // The probe is the rows lane's first page, read by `prepareSections`.
   if (probe.length <= limits.limitSnapshotRows) return false;
-  // §5.3: building an image needs a SQLite engine. The host injects the
-  // builder through `sqliteImageBuilder`; when omitted we default to the
-  // in-tree `buildSqliteImage` ONLY on a Bun runtime, reached by a *dynamic*
-  // import so `bun:sqlite` is never a static dependency of the pull path
-  // (runtime neutrality is enforced by test/runtime-neutrality.test.ts). On
-  // Workers/edge (no `Bun`) this yields the rows lane for a bit-2 client — a
-  // support floor, not a fallback (§5.3: sqlite is an *accept*, not a demand).
-  const buildImage = await resolveImageBuilder(ctx);
+  // §5.3: hosts opt into image construction with a runtime-specific builder.
+  // Without one, matching stored images remain usable and cold pulls use rows.
+  const buildImage = ctx.sqliteImageBuilder;
   if (buildImage === undefined) return false;
   let stores = imageBuilds.get(storage);
   if (stores === undefined) {

package/src/realtime.ts

@@ -44,9 +44,11 @@ import {
   reportError,
   SyncError,
   type SyncularErrorHandler,
+  type SyncularErrorMapper,
   syncError,
 } from './errors';
 import { emitEvent, type SyncularServerEvents } from './events';
+import { composeEvents } from './events-ring';
 import { createSyncResponseStream } from './handler';
 import {
   type CompiledSchema,
@@ -599,7 +601,12 @@ export class RealtimeSession {
         const sync =
           error instanceof DecodeError
             ? syncError(error.code, error.message)
-            : adapterSyncError(error, this.#hub.onError, 'realtime');
+            : adapterSyncError(
+                error,
+                (error, context) => this.#hub.onError?.(error, context),
+                'realtime',
+                (error, context) => this.#hub.mapError?.(error, context),
+              );
         finishRound(); // END is in this one chunk
         await this.#sendRoundChunk(
           errorResponseBytes(sync, this.wireVersion, this.logEpoch),
@@ -625,7 +632,12 @@ export class RealtimeSession {
         const sync =
           error instanceof DecodeError
             ? syncError(error.code, error.message)
-            : adapterSyncError(error, this.#hub.onError, 'realtime');
+            : adapterSyncError(
+                error,
+                (error, context) => this.#hub.onError?.(error, context),
+                'realtime',
+                (error, context) => this.#hub.mapError?.(error, context),
+              );
         finishRound();
         await this.#sendRoundChunk(
           errorResponseBytes(sync, this.wireVersion, this.logEpoch),
@@ -641,7 +653,11 @@ export class RealtimeSession {
     } catch (error) {
       // A host failure mid-stream leaves the byte stream unfinishable —
       // fail loud, drop the connection (§8.7 / §1.4 abort rule).
-      reportError(error, this.#hub.onError, 'realtime');
+      reportError(
+        error,
+        (error, context) => this.#hub.onError?.(error, context),
+        'realtime',
+      );
       this.#violation('sync round failed mid-stream');
     } finally {
       finishRound();
@@ -892,8 +908,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. */
@@ -913,10 +937,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;
@@ -1108,6 +1157,11 @@ export class RealtimeHub {
     return this.#config.onError;
   }
 
+  /** The host's adapter error mapper (`SyncServerConfig.mapError`), if any. */
+  get mapError(): SyncularErrorMapper | undefined {
+    return this.#config.mapError;
+  }
+
   requestContext(session: RealtimeSession): SyncRequestContext {
     return this.requestContextFor(session);
   }

package/src/sqlite-image.ts

@@ -69,7 +69,7 @@ export interface SqliteImageInput {
  * a real SQLite engine, which is not available on every runtime. The core
  * takes the builder as an optional capability rather than importing a driver
  * on the pull path. A Bun or Node host passes `buildSqliteImage`; a Workers
- * host omits it and serves the rows lane.
+ * host omits it and serves matching stored images or the rows lane.
  */
 export type SqliteImageBuilder = (
   input: SqliteImageInput,