@syncular/server 0.31.0 → 0.32.1

package/src/sqlite-storage.ts

@@ -30,11 +30,18 @@ import {
   layoutsOf,
   migratePayload,
   parseLayouts,
+  quoteIdent,
   retiredTableNames,
   rewritePlan,
   rewriteRowSql,
   rewriteValues,
   SCHEMA_META_DDL_SQLITE,
+  SYNC_COLUMN_VERSIONS_COLUMN,
+  SYNC_PARTITION_COLUMN,
+  SYNC_PAYLOAD_COLUMN,
+  SYNC_ROW_ID_COLUMN,
+  SYNC_SCOPES_COLUMN,
+  SYNC_VERSION_COLUMN,
   type StoredColumnLayout,
   scanRowPageSql,
   schemaDdl,
@@ -51,9 +58,11 @@ import {
   deserializePushResult,
   placeholders,
   SQLITE_DDL,
+  type SqliteChangeRecord,
   type SqliteCommitWindowRecord,
   type SqliteRowRecord,
   serializePushResult,
+  toStoredChange,
   toStoredRow,
 } from './sqlite-dialect';
 import {
@@ -66,8 +75,11 @@ import type {
   AuthoritativeQueryValue,
   CheckpointDeclaration,
   ClientCursorInfo,
+  ClientPushResult,
   ClientRecord,
   ClientSubscription,
+  CommitChangeSummary,
+  CommitDetail,
   CommitMetadata,
   CommitMetadataQuery,
   CommitWindowQuery,
@@ -82,6 +94,9 @@ import type {
   ReactionFailureUpdate,
   ReactionListQuery,
   ReactionPruneQuery,
+  RowChangeRecord,
+  RowChangesQuery,
+  RowListQuery,
   RowScanQuery,
   ScopeActivityQuery,
   ScopeCommitActivity,
@@ -1949,7 +1964,11 @@ END`);
     partition: string,
     query: CommitMetadataQuery,
   ): Promise<CommitMetadata[]> {
-    // Newest-first window, resumed by `afterSeq` (exclusive lower bound).
+    // 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
       ? this.db
           .query<
@@ -1960,16 +1979,16 @@ END`);
               actor_id: string;
               created_at_ms: number;
             },
-            [string, number, string, number]
+            [string, number, number, string, number]
           >(
             `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=? AND c.commit_seq>?
+             WHERE c.partition=? AND c.commit_seq>? AND c.commit_seq<?
                AND EXISTS (SELECT 1 FROM sync_changes ch
                  WHERE ch.partition=c.partition AND ch.commit_seq=c.commit_seq AND ch.tbl=?)
              ORDER BY c.commit_seq DESC LIMIT ?`,
           )
-          .all(partition, query.afterSeq, query.table, query.limit)
+          .all(partition, query.afterSeq, beforeSeq, query.table, query.limit)
       : this.db
           .query<
             {
@@ -1979,14 +1998,45 @@ END`);
               actor_id: string;
               created_at_ms: number;
             },
-            [string, number, number]
+            [string, number, number, number]
           >(
             `SELECT commit_seq, client_id, client_commit_id, actor_id, created_at_ms
              FROM sync_commits
-             WHERE partition=? AND commit_seq>?
+             WHERE partition=? AND commit_seq>? AND commit_seq<?
              ORDER BY commit_seq DESC LIMIT ?`,
           )
-          .all(partition, query.afterSeq, query.limit);
+          .all(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) => row.commit_seq);
+      const records = this.db
+        .query<
+          { commit_seq: number; tbl: string; row_id: string; op: number },
+          (string | number)[]
+        >(
+          `SELECT commit_seq, tbl, row_id, op FROM sync_changes
+           WHERE partition=? AND commit_seq IN (${placeholders(seqs.length)}) AND idx<?
+           ORDER BY commit_seq, idx`,
+        )
+        .all(partition, ...seqs, sampleCount);
+      for (const record of records) {
+        const sample = samples.get(record.commit_seq) ?? [];
+        sample.push({
+          table: record.tbl,
+          rowId: record.row_id,
+          op: record.op === 1 ? 'upsert' : 'delete',
+        });
+        samples.set(record.commit_seq, sample);
+      }
+    }
     return rows.map((row) => {
       const changes = this.db
         .query<{ tbl: string; n: number }, [string, number]>(
@@ -2001,10 +2051,134 @@ END`);
         createdAtMs: row.created_at_ms,
         changeCount: changes.reduce((sum, c) => sum + c.n, 0),
         tables: changes.map((c) => c.tbl),
+        ...(sampleCount > 0
+          ? { sample: samples.get(row.commit_seq) ?? [] }
+          : {}),
       };
     });
   }
 
+  async getCommit(
+    partition: string,
+    commitSeq: number,
+  ): Promise<CommitDetail | undefined> {
+    const meta = this.db
+      .query<
+        {
+          client_id: string;
+          client_commit_id: string;
+          actor_id: string;
+          created_at_ms: number;
+        },
+        [string, number]
+      >(
+        'SELECT client_id, client_commit_id, actor_id, created_at_ms FROM sync_commits WHERE partition=? AND commit_seq=?',
+      )
+      .get(partition, commitSeq);
+    if (meta === null) return undefined;
+    const changes = this.db
+      .query<SqliteChangeRecord, [string, number]>(
+        'SELECT tbl, row_id, op, row_version, scopes, payload FROM sync_changes WHERE partition=? AND commit_seq=? ORDER BY idx',
+      )
+      .all(partition, commitSeq)
+      .map(toStoredChange);
+    return {
+      commitSeq,
+      clientId: meta.client_id,
+      clientCommitId: meta.client_commit_id,
+      actorId: meta.actor_id,
+      createdAtMs: 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).
+    return this.db
+      .query<
+        {
+          commit_seq: number;
+          op: number;
+          row_version: number | null;
+          actor_id: string;
+          client_id: string;
+          created_at_ms: number;
+        },
+        [string, string, string, number]
+      >(
+        `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=? AND ch.tbl=? AND ch.row_id=?
+         ORDER BY ch.commit_seq DESC, ch.idx DESC LIMIT ?`,
+      )
+      .all(partition, query.table, query.rowId, query.limit)
+      .map((row) => ({
+        commitSeq: row.commit_seq,
+        op: row.op === 1 ? 'upsert' : 'delete',
+        ...(row.row_version !== null ? { rowVersion: row.row_version } : {}),
+        actorId: row.actor_id,
+        clientId: row.client_id,
+        createdAtMs: 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.
+    return this.db
+      .query<SqliteRowRecord, [string, string, number]>(
+        `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)}=? AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}>?
+         ORDER BY ${quoteIdent(SYNC_ROW_ID_COLUMN)} LIMIT ?`,
+      )
+      .all(partition, query.afterRowId ?? '', query.limit)
+      .map(toStoredRow);
+  }
+
+  async countRows(partition: string, table: string): Promise<number> {
+    const record = this.db
+      .query<{ n: number }, [string]>(
+        `SELECT count(*) AS n FROM ${quoteIdent(this.table(table).name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=?`,
+      )
+      .get(partition);
+    return record?.n ?? 0;
+  }
+
+  async listPushResults(
+    partition: string,
+    clientCommitId: string,
+  ): Promise<ClientPushResult[]> {
+    // Retained outcomes for one clientCommitId: no dedicated index, ordered
+    // by client so the read is deterministic.
+    return this.db
+      .query<{ client_id: string; result: string }, [string, string]>(
+        'SELECT client_id, result FROM sync_push_results WHERE partition=? AND client_commit_id=? ORDER BY client_id',
+      )
+      .all(partition, clientCommitId)
+      .map((record) => {
+        try {
+          return {
+            clientId: record.client_id,
+            result: deserializePushResult(record.result),
+          };
+        } catch {
+          throw syncError(
+            'sync.idempotency_cache_miss',
+            'persisted push result unreadable (§6.3)',
+          );
+        }
+      });
+  }
+
   async scopeActivity(
     partition: string,
     query: ScopeActivityQuery,
@@ -2044,25 +2218,6 @@ END`);
     return out;
   }
 
-  async getRowScopes(
-    partition: string,
-    table: string,
-    rowId: string,
-  ): Promise<
-    { serverVersion: number; scopes: Record<string, string> } | undefined
-  > {
-    const record = this.db
-      .query<{ server_version: number; scopes: string }, [string, string]>(
-        selectRowScopesSql(this.table(table), 'sqlite'),
-      )
-      .get(partition, rowId);
-    if (record === null) return undefined;
-    return {
-      serverVersion: record.server_version,
-      scopes: JSON.parse(record.scopes) as Record<string, string>,
-    };
-  }
-
   async listPartitions(): Promise<string[]> {
     return (await this.listPartitionRegistry()).map((entry) => entry.partition);
   }

package/src/storage.ts

@@ -379,14 +379,62 @@ export interface CommitMetadata {
   readonly createdAtMs: number;
   readonly changeCount: number;
   readonly tables: readonly string[];
+  /** The first `changeSample` changes in commit order, when requested. */
+  readonly sample?: readonly CommitChangeSummary[];
+}
+
+/** One change without its payload, for commit lists. */
+export interface CommitChangeSummary {
+  readonly table: string;
+  readonly rowId: string;
+  readonly op: 'upsert' | 'delete';
 }
 
 export interface CommitMetadataQuery {
-  /** Window `afterSeq < commitSeq`, oldest first. */
+  /** Window lower bound, exclusive: `afterSeq < commitSeq`. */
   readonly afterSeq: number;
+  /** Window upper bound, exclusive: `commitSeq < beforeSeq` (older pages). */
+  readonly beforeSeq?: number;
+  /** Newest first, at most `limit` commits. */
   readonly limit: number;
   /** Restrict to commits that touched this table (via the change index). */
   readonly table?: string;
+  /** Attach the first N changes of each commit as `sample`. */
+  readonly changeSample?: number;
+}
+
+export interface RowListQuery {
+  readonly table: string;
+  /** Resume after this rowId (exclusive); `null` = start of table. */
+  readonly afterRowId: string | null;
+  readonly limit: number;
+}
+
+/** A stored push outcome with the client that sent it. */
+export interface ClientPushResult {
+  readonly clientId: string;
+  readonly result: StoredPushResult;
+}
+
+/** One retained commit with its changes, for the admin commit drill-down. */
+export interface CommitDetail extends CommitMetadata {
+  readonly changes: readonly StoredChange[];
+}
+
+/** One retained change to a single row, for the admin row history. */
+export interface RowChangeRecord {
+  readonly commitSeq: number;
+  readonly op: 'upsert' | 'delete';
+  readonly rowVersion?: number;
+  readonly actorId: string;
+  readonly clientId: string;
+  readonly createdAtMs: number;
+}
+
+export interface RowChangesQuery {
+  readonly table: string;
+  readonly rowId: string;
+  readonly limit: number;
 }
 
 /** One recent commit touching a scope key, for the admin scope activity view. */
@@ -921,8 +969,16 @@ export interface ServerStorage {
    * touched tables), the newest-oriented window an operator inspects.
    * `scopeActivity`: the recent commits touching one scope key, via the
    * change scope index (never a log scan).
-   * `getRowScopes`: the (table, rowId) row's current server_version and
-   * stored scopes without decoding its payload — the row inspector.
+   * `getCommit`: one retained commit with its changes and payloads;
+   * `undefined` when the commit does not exist or was pruned.
+   * `listRowChanges`: the retained changes to one row, newest first. It
+   * reads the partition's retained log without a dedicated index, so the
+   * write path pays nothing for it and its cost is bounded by retention.
+   * `listRows`: one table's rows ordered by rowId, without a scope filter.
+   * `countRows`: one table's row count.
+   * `listPushResults`: every stored idempotency outcome for one
+   * clientCommitId across the partition's clients, scanning the retained
+   * outcomes without a dedicated index.
    * `listPartitions`: the partition-only compatibility view of
    * `listPartitionRegistry`, sorted.
    */
@@ -935,13 +991,20 @@ export interface ServerStorage {
     partition: string,
     query: ScopeActivityQuery,
   ): Promise<ScopeCommitActivity[]>;
-  getRowScopes?(
+  getCommit?(
     partition: string,
-    table: string,
-    rowId: string,
-  ): Promise<
-    { serverVersion: number; scopes: Record<string, string> } | undefined
-  >;
+    commitSeq: number,
+  ): Promise<CommitDetail | undefined>;
+  listRowChanges?(
+    partition: string,
+    query: RowChangesQuery,
+  ): Promise<RowChangeRecord[]>;
+  listRows?(partition: string, query: RowListQuery): Promise<StoredRow[]>;
+  countRows?(partition: string, table: string): Promise<number>;
+  listPushResults?(
+    partition: string,
+    clientCommitId: string,
+  ): Promise<ClientPushResult[]>;
   listPartitions(): Promise<string[]>;
 }