@syncular/server 0.31.0 → 0.32.0

package/dist/realtime.d.ts

@@ -169,13 +169,28 @@ export declare class RealtimeSession {
     deliverCommit(commit: StoredCommit): void;
     close(): void;
 }
+/** One open realtime socket. */
+export interface RealtimeConnection {
+    readonly sessionId: string;
+    readonly clientId: string;
+    readonly actorId: string;
+    readonly openedAtMs: number;
+}
 export declare class RealtimeHub {
     #private;
     /** §8.6 presence registry — ephemeral, in-memory, never persisted. */
     readonly presence: PresenceRegistry;
     constructor(config: RealtimeHubConfig);
     projectPayload(registration: Registration, payload: Uint8Array): Uint8Array;
+    /**
+     * 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;
     get sessionCount(): number;
+    /** The partition's open sockets, for the admin console. */
+    connections(partition: string): RealtimeConnection[];
     /** §8.6.2 published-document size cap (bytes). */
     get maxPresenceBytes(): number;
     /** §8.6.4 presence rate cap (ms); 0 = off (reference default). */

package/dist/realtime.js

@@ -20,6 +20,7 @@ import { DecodeError, decodeMessage, encodeMessage, encodePresenceError, encodeP
 import { REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE, touchAuthenticatedPartition, } from './context.js';
 import { adapterSyncError, reportError, SyncError, syncError, } from './errors.js';
 import { emitEvent } from './events.js';
+import { composeEvents } from './events-ring.js';
 import { createSyncResponseStream } from './handler.js';
 import { compileSchema, } from './schema.js';
 import { schemaWindowOf, projectRowPayload } from './schema-window.js';
@@ -714,9 +715,32 @@ export class RealtimeHub {
     projectPayload(registration, payload) {
         return projectRowPayload(this.#schema.tables.get(registration.table), registration.codec, payload);
     }
+    /**
+     * 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) {
+        const events = this.#config.events;
+        this.#config = {
+            ...this.#config,
+            events: events === undefined ? sink : composeEvents(events, sink),
+        };
+    }
     get sessionCount() {
         return this.#sessions.size;
     }
+    /** The partition's open sockets, for the admin console. */
+    connections(partition) {
+        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() {
         return this.#config.maxPresenceBytes ?? DEFAULT_MAX_PRESENCE_BYTES;

package/dist/sqlite-storage.d.ts

@@ -2,7 +2,7 @@ import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
 import type { ScopeMap } from '@syncular/core';
 import type { CompiledSchema, CompiledTable } from './schema.js';
 import { type SqliteDatabase } from './sqlite-driver.js';
-import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, ServeGate, StorageTransaction, StoredCommit, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
+import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientPushResult, ClientRecord, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, ServeGate, StorageTransaction, StoredCommit, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
 export declare class SqliteServerStorage implements ServerStorage {
     #private;
     readonly db: SqliteDatabase;
@@ -69,10 +69,11 @@ export declare class SqliteServerStorage implements ServerStorage {
     listReferencedBlobIds(partition: string): Promise<string[]>;
     listClientRecords(partition: string): Promise<ClientRecord[]>;
     listCommitMetadata(partition: string, query: CommitMetadataQuery): Promise<CommitMetadata[]>;
+    getCommit(partition: string, 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[]>;
     scopeActivity(partition: string, query: ScopeActivityQuery): Promise<ScopeCommitActivity[]>;
-    getRowScopes(partition: string, table: string, rowId: string): Promise<{
-        serverVersion: number;
-        scopes: Record<string, string>;
-    } | undefined>;
     listPartitions(): Promise<string[]>;
 }

package/dist/sqlite-storage.js

@@ -13,9 +13,9 @@ import { serveNotReadyError } from './readiness.js';
  */
 import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
-import { assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, latestScopedChangeSeqSql, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
+import { assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, latestScopedChangeSeqSql, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, 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, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
-import { collectCommitWindowPage, deserializePushResult, placeholders, SQLITE_DDL, serializePushResult, toStoredRow, } from './sqlite-dialect.js';
+import { collectCommitWindowPage, deserializePushResult, placeholders, SQLITE_DDL, serializePushResult, toStoredChange, toStoredRow, } from './sqlite-dialect.js';
 import { SqliteAdapterRequiredError, } from './sqlite-driver.js';
 import { isSqliteConstraintError, StorageConstraintError, } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
@@ -1218,22 +1218,51 @@ END`);
         }));
     }
     async listCommitMetadata(partition, query) {
-        // 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(`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(`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();
+        if (sampleCount > 0 && rows.length > 0) {
+            const seqs = rows.map((row) => row.commit_seq);
+            const records = this.db
+                .query(`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('SELECT tbl, count(*) AS n FROM sync_changes WHERE partition=? AND commit_seq=? GROUP BY tbl')
@@ -1246,9 +1275,88 @@ 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, commitSeq) {
+        const meta = this.db
+            .query('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('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, query) {
+        // 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(`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, query) {
+        // 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(`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, table) {
+        const record = this.db
+            .query(`SELECT count(*) AS n FROM ${quoteIdent(this.table(table).name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=?`)
+            .get(partition);
+        return record?.n ?? 0;
+    }
+    async listPushResults(partition, clientCommitId) {
+        // Retained outcomes for one clientCommitId: no dedicated index, ordered
+        // by client so the read is deterministic.
+        return this.db
+            .query('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, query) {
         // Candidate commits via the change-scope index (§3.1) — never a scan.
         const rows = this.db
@@ -1276,17 +1384,6 @@ END`);
         }
         return out;
     }
-    async getRowScopes(partition, table, rowId) {
-        const record = this.db
-            .query(selectRowScopesSql(this.table(table), 'sqlite'))
-            .get(partition, rowId);
-        if (record === null)
-            return undefined;
-        return {
-            serverVersion: record.server_version,
-            scopes: JSON.parse(record.scopes),
-        };
-    }
     async listPartitions() {
         return (await this.listPartitionRegistry()).map((entry) => entry.partition);
     }

package/dist/storage.d.ts

@@ -303,13 +303,55 @@ 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. */
 export interface ScopeCommitActivity {
@@ -671,18 +713,27 @@ 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.
      */
     listClientRecords?(partition: string): Promise<ClientRecord[]>;
     listCommitMetadata?(partition: string, query: CommitMetadataQuery): Promise<CommitMetadata[]>;
     scopeActivity?(partition: string, query: ScopeActivityQuery): Promise<ScopeCommitActivity[]>;
-    getRowScopes?(partition: string, table: string, rowId: string): Promise<{
-        serverVersion: number;
-        scopes: Record<string, string>;
-    } | undefined>;
+    getCommit?(partition: string, 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[]>;
 }
 /** A row referencing a blob, with the scopes needed to authorize download. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -68,7 +68,7 @@
     "verify:node": "cd ../.. && bun build ./packages/server/test/sqlite-runtime/verify-node.mjs --target=node --conditions=bun --outfile=./packages/server/.verify-node.built.mjs && node ./packages/server/.verify-node.built.mjs"
   },
   "dependencies": {
-    "@syncular/core": "0.31.0"
+    "@syncular/core": "0.32.0"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"