@syncular/server 0.15.45 → 0.15.46

package/src/realtime.ts

@@ -31,7 +31,7 @@ import {
   type WakeReason,
 } from '@syncular/core';
 import type { SyncRequestContext, SyncServerConfig } from './context';
-import { RESOLVER_OUTAGE } from './context';
+import { REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE } from './context';
 import { SyncError, syncError } from './errors';
 import { emitEvent, type SyncularServerEvents } from './events';
 import { createSyncResponseStream } from './handler';
@@ -963,6 +963,12 @@ export class RealtimeHub {
   async connect(options: RealtimeConnectOptions): Promise<RealtimeSession> {
     const { storage } = this.#config;
     const clock = this.#config.clock ?? Date.now;
+    if (options.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
+      throw syncError(
+        'sync.invalid_client_id',
+        'clientId uses a reserved server-command namespace (§1.5)',
+      );
+    }
     const record = await storage.getClientRecord(
       options.partition,
       options.clientId,

package/src/sqlite-dialect.ts

@@ -74,6 +74,26 @@ CREATE TABLE IF NOT EXISTS sync_push_results(
   client_commit_id TEXT NOT NULL, result TEXT NOT NULL,
   PRIMARY KEY(partition, client_id, client_commit_id)
 );
+CREATE TABLE IF NOT EXISTS sync_reactions(
+  partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,
+  type TEXT NOT NULL, version INTEGER NOT NULL, payload TEXT NOT NULL,
+  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,
+  source_commit_seq INTEGER NOT NULL, created_at_ms INTEGER NOT NULL,
+  available_at_ms INTEGER NOT NULL, status TEXT NOT NULL,
+  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,
+  lease_owner TEXT, lease_expires_at_ms INTEGER, completed_at_ms INTEGER,
+  last_failure TEXT,
+  PRIMARY KEY(partition, idempotency_key),
+  CHECK(status IN ('pending', 'leased', 'completed', 'dead-letter'))
+);
+CREATE INDEX IF NOT EXISTS sync_reactions_due
+  ON sync_reactions(partition, status, available_at_ms, created_at_ms, idempotency_key);
+CREATE INDEX IF NOT EXISTS sync_reactions_lease
+  ON sync_reactions(partition, status, lease_expires_at_ms);
+CREATE INDEX IF NOT EXISTS sync_reactions_completed
+  ON sync_reactions(partition, status, completed_at_ms, idempotency_key);
+CREATE INDEX IF NOT EXISTS sync_reactions_dead_letter
+  ON sync_reactions(partition, status, available_at_ms, idempotency_key);
 CREATE TABLE IF NOT EXISTS sync_clients(
   partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,
   cursor INTEGER NOT NULL, subscriptions TEXT NOT NULL,

package/src/sqlite-storage.ts

@@ -7,6 +7,10 @@
  * match against the stored scope map — never a log scan.
  */
 import { Database } from 'bun:sqlite';
+import {
+  bindAuthoritativePartition,
+  prepareAuthoritativeQuery,
+} from './authoritative-query';
 import { syncError } from './errors';
 import {
   commitWindowPageSql,
@@ -42,14 +46,25 @@ import {
   toStoredRow,
 } from './sqlite-dialect';
 import type {
+  AuthoritativeQueryRequest,
+  AuthoritativeQueryResult,
+  AuthoritativeQueryValue,
   ClientCursorInfo,
   ClientRecord,
   ClientSubscription,
   CommitMetadata,
   CommitMetadataQuery,
   CommitWindowQuery,
+  DurableJsonValue,
   IndexRowScanQuery,
   NewCommit,
+  NewReaction,
+  PrunedReactionCounts,
+  ReactionClaimQuery,
+  ReactionFailure,
+  ReactionFailureUpdate,
+  ReactionListQuery,
+  ReactionPruneQuery,
   RowScanQuery,
   ScopeActivityQuery,
   ScopeCommitActivity,
@@ -57,6 +72,7 @@ import type {
   StorageTransaction,
   StoredCommit,
   StoredPushResult,
+  StoredReaction,
   StoredRow,
 } from './storage';
 import {
@@ -65,6 +81,53 @@ import {
 } from './storage-errors';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query';
 
+interface SqliteReactionRecord {
+  partition: string;
+  idempotency_key: string;
+  type: string;
+  version: number;
+  payload: string;
+  source_client_id: string;
+  source_client_commit_id: string;
+  source_commit_seq: number;
+  created_at_ms: number;
+  available_at_ms: number;
+  status: StoredReaction['status'];
+  attempts: number;
+  max_attempts: number;
+  lease_owner: string | null;
+  lease_expires_at_ms: number | null;
+  completed_at_ms: number | null;
+  last_failure: string | null;
+}
+
+function toStoredReaction(record: SqliteReactionRecord): StoredReaction {
+  return {
+    idempotencyKey: record.idempotency_key,
+    type: record.type,
+    version: record.version,
+    payload: JSON.parse(record.payload) as DurableJsonValue,
+    sourceClientId: record.source_client_id,
+    sourceClientCommitId: record.source_client_commit_id,
+    sourceCommitSeq: record.source_commit_seq,
+    createdAtMs: record.created_at_ms,
+    maxAttempts: record.max_attempts,
+    status: record.status,
+    attempts: record.attempts,
+    availableAtMs: record.available_at_ms,
+    ...(record.lease_owner !== null ? { leaseOwner: record.lease_owner } : {}),
+    ...(record.lease_expires_at_ms !== null
+      ? { leaseExpiresAtMs: record.lease_expires_at_ms }
+      : {}),
+    ...(record.completed_at_ms !== null
+      ? { completedAtMs: record.completed_at_ms }
+      : {}),
+    ...(record.last_failure !== null
+      ? { lastFailure: JSON.parse(record.last_failure) as ReactionFailure }
+      : {}),
+  };
+}
+
 class SqliteTransaction implements StorageTransaction {
   #storage: SqliteServerStorage;
   #partition: string;
@@ -256,6 +319,32 @@ class SqliteTransaction implements StorageTransaction {
       );
   }
 
+  async enqueueReactions(reactions: readonly NewReaction[]): Promise<void> {
+    this.#assertOpen();
+    const statement = this.#storage.db.query(
+      `INSERT INTO sync_reactions(
+         partition, idempotency_key, type, version, payload,
+         source_client_id, source_client_commit_id, source_commit_seq,
+         created_at_ms, available_at_ms, status, attempts, max_attempts
+       ) VALUES (?,?,?,?,?,?,?,?,?,?,'pending',0,?)`,
+    );
+    for (const reaction of reactions) {
+      statement.run(
+        this.#partition,
+        reaction.idempotencyKey,
+        reaction.type,
+        reaction.version,
+        JSON.stringify(reaction.payload),
+        reaction.sourceClientId,
+        reaction.sourceClientCommitId,
+        reaction.sourceCommitSeq,
+        reaction.createdAtMs,
+        reaction.createdAtMs,
+        reaction.maxAttempts,
+      );
+    }
+  }
+
   async commit(): Promise<void> {
     this.#assertOpen();
     try {
@@ -297,6 +386,20 @@ export class SqliteServerStorage implements ServerStorage {
   #tables: ReadonlyMap<string, CompiledTable> | undefined;
   #schemaVersion: number | undefined;
 
+  async #serializeReactionWrite<T>(operation: () => T): Promise<T> {
+    const previous = this.#transactionTail;
+    let release!: () => void;
+    this.#transactionTail = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    await previous;
+    try {
+      return operation();
+    } finally {
+      release();
+    }
+  }
+
   constructor(db: Database | string = ':memory:') {
     this.db = typeof db === 'string' ? new Database(db) : db;
     this.db.exec(SQLITE_DDL);
@@ -496,6 +599,55 @@ export class SqliteServerStorage implements ServerStorage {
     return row?.max_commit_seq ?? 0;
   }
 
+  async queryAuthoritative(
+    partition: string,
+    query: AuthoritativeQueryRequest,
+  ): Promise<AuthoritativeQueryResult> {
+    if (this.#tables === undefined) {
+      throw new Error(
+        'ensureSchema(schema) must run before registered queries',
+      );
+    }
+    const prepared = bindAuthoritativePartition(
+      prepareAuthoritativeQuery(
+        query.sql,
+        query.params,
+        query.tables,
+        this.#tables,
+      ),
+      partition,
+    );
+    const previous = this.#transactionTail;
+    let release!: () => void;
+    this.#transactionTail = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    await previous;
+    let open = false;
+    try {
+      this.db.exec('BEGIN');
+      open = true;
+      const rows = this.db
+        .query<Readonly<Record<string, unknown>>, AuthoritativeQueryValue[]>(
+          prepared.sql,
+        )
+        .all(...prepared.params);
+      const cursor = this.db
+        .query<{ max_commit_seq: number }, [string]>(
+          'SELECT max_commit_seq FROM sync_partitions WHERE partition=?',
+        )
+        .get(partition);
+      this.db.exec('COMMIT');
+      open = false;
+      return { rows, maxCommitSeq: cursor?.max_commit_seq ?? 0 };
+    } catch (error) {
+      if (open) this.db.exec('ROLLBACK');
+      throw error;
+    } finally {
+      release();
+    }
+  }
+
   async getHorizonSeq(partition: string): Promise<number> {
     const row = this.db
       .query<{ horizon_seq: number }, [string]>(
@@ -575,6 +727,219 @@ export class SqliteServerStorage implements ServerStorage {
     }
   }
 
+  async claimReactions(
+    partition: string,
+    query: ReactionClaimQuery,
+  ): Promise<StoredReaction[]> {
+    if (query.types.length === 0 || query.limit <= 0) return [];
+    return this.#serializeReactionWrite(() => {
+      const typeParams = query.types.map(() => '?').join(',');
+      const records = this.db
+        .query<SqliteReactionRecord, (string | number)[]>(
+          `UPDATE sync_reactions
+            SET status='leased', attempts=attempts+1,
+                lease_owner=?, lease_expires_at_ms=?, completed_at_ms=NULL
+          WHERE (partition, idempotency_key) IN (
+            SELECT partition, idempotency_key
+              FROM sync_reactions
+             WHERE partition=? AND type IN (${typeParams})
+               AND ((status='pending' AND available_at_ms<=?)
+                 OR (status='leased' AND lease_expires_at_ms<=?))
+             ORDER BY CASE WHEN status='leased' THEN lease_expires_at_ms
+                           ELSE available_at_ms END,
+                      created_at_ms, idempotency_key
+             LIMIT ?
+          )
+        RETURNING *`,
+        )
+        .all(
+          query.leaseOwner,
+          Math.min(
+            Number.MAX_SAFE_INTEGER,
+            query.nowMs + query.leaseDurationMs,
+          ),
+          partition,
+          ...query.types,
+          query.nowMs,
+          query.nowMs,
+          query.limit,
+        );
+      return records
+        .map(toStoredReaction)
+        .sort(
+          (a, b) =>
+            a.createdAtMs - b.createdAtMs ||
+            a.idempotencyKey.localeCompare(b.idempotencyKey),
+        );
+    });
+  }
+
+  async completeReaction(
+    partition: string,
+    idempotencyKey: string,
+    leaseOwner: string,
+    completedAtMs: number,
+  ): Promise<boolean> {
+    return this.#serializeReactionWrite(() => {
+      const result = this.db
+        .query(
+          `UPDATE sync_reactions
+            SET status='completed', completed_at_ms=?,
+                lease_owner=NULL, lease_expires_at_ms=NULL
+          WHERE partition=? AND idempotency_key=?
+            AND status='leased' AND lease_owner=?`,
+        )
+        .run(completedAtMs, partition, idempotencyKey, leaseOwner);
+      return Number(result.changes) === 1;
+    });
+  }
+
+  async extendReactionLease(
+    partition: string,
+    idempotencyKey: string,
+    leaseOwner: string,
+    leaseExpiresAtMs: number,
+  ): Promise<boolean> {
+    return this.#serializeReactionWrite(() => {
+      const result = this.db
+        .query(
+          `UPDATE sync_reactions SET lease_expires_at_ms=?
+          WHERE partition=? AND idempotency_key=?
+            AND status='leased' AND lease_owner=?`,
+        )
+        .run(leaseExpiresAtMs, partition, idempotencyKey, leaseOwner);
+      return Number(result.changes) === 1;
+    });
+  }
+
+  async failReaction(
+    partition: string,
+    idempotencyKey: string,
+    update: ReactionFailureUpdate,
+  ): Promise<boolean> {
+    const retry = update.retryAtMs !== undefined;
+    return this.#serializeReactionWrite(() => {
+      const result = this.db
+        .query(
+          `UPDATE sync_reactions
+            SET status=?, available_at_ms=?, last_failure=?,
+                lease_owner=NULL, lease_expires_at_ms=NULL
+          WHERE partition=? AND idempotency_key=?
+            AND status='leased' AND lease_owner=?`,
+        )
+        .run(
+          retry ? 'pending' : 'dead-letter',
+          update.retryAtMs ?? update.failure.atMs,
+          JSON.stringify(update.failure),
+          partition,
+          idempotencyKey,
+          update.leaseOwner,
+        );
+      return Number(result.changes) === 1;
+    });
+  }
+
+  async retryReaction(
+    partition: string,
+    idempotencyKey: string,
+    nowMs: number,
+  ): Promise<boolean> {
+    return this.#serializeReactionWrite(() => {
+      const result = this.db
+        .query(
+          `UPDATE sync_reactions
+            SET status='pending', attempts=0, available_at_ms=?,
+                last_failure=NULL, lease_owner=NULL, lease_expires_at_ms=NULL,
+                completed_at_ms=NULL
+          WHERE partition=? AND idempotency_key=? AND status='dead-letter'`,
+        )
+        .run(nowMs, partition, idempotencyKey);
+      return Number(result.changes) === 1;
+    });
+  }
+
+  async getReaction(
+    partition: string,
+    idempotencyKey: string,
+  ): Promise<StoredReaction | undefined> {
+    const record = this.db
+      .query<SqliteReactionRecord, [string, string]>(
+        'SELECT * FROM sync_reactions WHERE partition=? AND idempotency_key=?',
+      )
+      .get(partition, idempotencyKey);
+    return record === null ? undefined : toStoredReaction(record);
+  }
+
+  async listReactions(
+    partition: string,
+    query: ReactionListQuery,
+  ): Promise<StoredReaction[]> {
+    const where = ['partition=?'];
+    const params: (string | number)[] = [partition];
+    if (query.statuses !== undefined && query.statuses.length > 0) {
+      where.push(`status IN (${query.statuses.map(() => '?').join(',')})`);
+      params.push(...query.statuses);
+    }
+    if (query.types !== undefined && query.types.length > 0) {
+      where.push(`type IN (${query.types.map(() => '?').join(',')})`);
+      params.push(...query.types);
+    }
+    params.push(query.limit);
+    const records = this.db
+      .query<SqliteReactionRecord, (string | number)[]>(
+        `SELECT * FROM sync_reactions WHERE ${where.join(' AND ')}
+          ORDER BY created_at_ms DESC, idempotency_key DESC LIMIT ?`,
+      )
+      .all(...params);
+    return records.map(toStoredReaction);
+  }
+
+  async pruneReactions(
+    partition: string,
+    query: ReactionPruneQuery,
+  ): Promise<PrunedReactionCounts> {
+    if (query.limit <= 0) return { completed: 0, deadLetter: 0 };
+    return this.#serializeReactionWrite(() => {
+      const records = this.db
+        .query<
+          { status: 'completed' | 'dead-letter' },
+          [string, string, number, number, number, number, number]
+        >(
+          `DELETE FROM sync_reactions
+            WHERE partition=? AND idempotency_key IN (
+              SELECT idempotency_key FROM sync_reactions
+               WHERE partition=?
+                 AND ((status='completed' AND completed_at_ms IS NOT NULL
+                       AND completed_at_ms<?)
+                   OR (status='dead-letter' AND available_at_ms<?))
+               ORDER BY CASE WHEN status='completed' THEN completed_at_ms
+                             ELSE available_at_ms END,
+                        idempotency_key
+               LIMIT ?
+            )
+              AND ((status='completed' AND completed_at_ms IS NOT NULL
+                    AND completed_at_ms<?)
+                OR (status='dead-letter' AND available_at_ms<?))
+          RETURNING status`,
+        )
+        .all(
+          partition,
+          partition,
+          query.completedBeforeMs,
+          query.deadLetterBeforeMs,
+          query.limit,
+          query.completedBeforeMs,
+          query.deadLetterBeforeMs,
+        );
+      return {
+        completed: records.filter((record) => record.status === 'completed')
+          .length,
+        deadLetter: records.filter((record) => record.status === 'dead-letter')
+          .length,
+      };
+    });
+  }
+
   async readCommitWindow(
     partition: string,
     query: CommitWindowQuery,

package/src/storage.ts

@@ -65,6 +65,83 @@ export interface StoredCommit {
   readonly changes: readonly StoredChange[];
 }
 
+/** JSON values accepted by the durable reaction payload/failure store. */
+export type DurableJsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly DurableJsonValue[]
+  | { readonly [key: string]: DurableJsonValue };
+
+export type ReactionStatus = 'pending' | 'leased' | 'completed' | 'dead-letter';
+
+export interface ReactionFailure {
+  /** Stable application or Syncular error identity. */
+  readonly code: string;
+  readonly atMs: number;
+  /** Bounded JSON metadata. Diagnostic exception text is never persisted. */
+  readonly details?: { readonly [key: string]: DurableJsonValue };
+}
+
+/** A validated reaction row written with its source commit. */
+export interface NewReaction {
+  readonly idempotencyKey: string;
+  readonly type: string;
+  readonly version: number;
+  readonly payload: DurableJsonValue;
+  readonly sourceClientId: string;
+  readonly sourceClientCommitId: string;
+  readonly sourceCommitSeq: number;
+  readonly createdAtMs: number;
+  readonly maxAttempts: number;
+}
+
+/** Durable reaction state returned to workers and administrative readers. */
+export interface StoredReaction extends NewReaction {
+  readonly status: ReactionStatus;
+  /** Incremented atomically when a worker claims the reaction. */
+  readonly attempts: number;
+  readonly availableAtMs: number;
+  readonly leaseOwner?: string;
+  readonly leaseExpiresAtMs?: number;
+  readonly completedAtMs?: number;
+  readonly lastFailure?: ReactionFailure;
+}
+
+export interface ReactionClaimQuery {
+  /** Opaque token unique to this claim operation. */
+  readonly leaseOwner: string;
+  readonly types: readonly string[];
+  readonly nowMs: number;
+  readonly leaseDurationMs: number;
+  readonly limit: number;
+}
+
+export interface ReactionListQuery {
+  readonly statuses?: readonly ReactionStatus[];
+  readonly types?: readonly string[];
+  readonly limit: number;
+}
+
+export interface ReactionFailureUpdate {
+  readonly leaseOwner: string;
+  readonly failure: ReactionFailure;
+  /** Present for retry; absent moves the row to the dead-letter state. */
+  readonly retryAtMs?: number;
+}
+
+export interface ReactionPruneQuery {
+  readonly completedBeforeMs: number;
+  readonly deadLetterBeforeMs: number;
+  readonly limit: number;
+}
+
+export interface PrunedReactionCounts {
+  readonly completed: number;
+  readonly deadLetter: number;
+}
+
 /** Persisted push outcome for idempotent replay (§2.3, §6.3). */
 export interface StoredPushResult {
   readonly status: 'applied' | 'rejected';
@@ -183,6 +260,29 @@ export interface ScopeActivityQuery {
   readonly limit: number;
 }
 
+/** A registered SELECT executed against the authoritative row projection. */
+export type AuthoritativeQueryValue =
+  | string
+  | number
+  | bigint
+  | boolean
+  | Uint8Array
+  | null;
+
+export interface AuthoritativeQueryRequest {
+  /** Generated, positional SQLite-family SQL. It never comes from the request. */
+  readonly sql: string;
+  readonly params: readonly AuthoritativeQueryValue[];
+  /** Generated dependency set, used to validate and partition every relation. */
+  readonly tables: readonly string[];
+}
+
+/** One transactionally consistent authoritative query snapshot. */
+export interface AuthoritativeQueryResult {
+  readonly rows: readonly Readonly<Record<string, unknown>>[];
+  readonly maxCommitSeq: number;
+}
+
 /**
  * One transaction per push commit (§6.4): all row writes, the appended
  * commit (with its scope-index entries), and the idempotency record either
@@ -248,6 +348,12 @@ export interface StorageTransaction {
   deleteRow(table: string, rowId: string): Promise<void>;
   /** Allocates the next per-partition commitSeq and appends the commit. */
   appendCommit(commit: NewCommit): Promise<number>;
+  /**
+   * Persist reaction rows in this authoritative transaction. Required when
+   * the host configures a reaction planner. Reactions survive commit-log
+   * pruning because they live outside the commit/change tables.
+   */
+  enqueueReactions?(reactions: readonly NewReaction[]): Promise<void>;
   /**
    * Persist an idempotency outcome only when the key is still absent. The
    * first writer wins; callers read the canonical value after commit.
@@ -323,6 +429,55 @@ export interface ServerStorage {
     clientCommitId: string,
   ): Promise<StoredPushResult | undefined>;
 
+  /**
+   * Atomically lease due or expired-lease reactions for one worker. Optional
+   * for compatibility with custom storages; reaction runners fail closed when
+   * any lifecycle method is absent.
+   */
+  claimReactions?(
+    partition: string,
+    query: ReactionClaimQuery,
+  ): Promise<StoredReaction[]>;
+  /** Acknowledge only while `leaseOwner` still owns the lease. */
+  completeReaction?(
+    partition: string,
+    idempotencyKey: string,
+    leaseOwner: string,
+    completedAtMs: number,
+  ): Promise<boolean>;
+  /** Extend only while `leaseOwner` still owns the active lease. */
+  extendReactionLease?(
+    partition: string,
+    idempotencyKey: string,
+    leaseOwner: string,
+    leaseExpiresAtMs: number,
+  ): Promise<boolean>;
+  /** Retry or dead-letter only while `leaseOwner` still owns the lease. */
+  failReaction?(
+    partition: string,
+    idempotencyKey: string,
+    update: ReactionFailureUpdate,
+  ): Promise<boolean>;
+  /** Reset a dead-lettered row for an explicit operator retry. */
+  retryReaction?(
+    partition: string,
+    idempotencyKey: string,
+    nowMs: number,
+  ): Promise<boolean>;
+  getReaction?(
+    partition: string,
+    idempotencyKey: string,
+  ): Promise<StoredReaction | undefined>;
+  listReactions?(
+    partition: string,
+    query: ReactionListQuery,
+  ): Promise<StoredReaction[]>;
+  /** Delete a bounded set of aged terminal rows. Never deletes active work. */
+  pruneReactions?(
+    partition: string,
+    query: ReactionPruneQuery,
+  ): Promise<PrunedReactionCounts>;
+
   /**
    * Matching commits in the window, oldest first, each carrying only its
    * matching changes for `table`. Stops once accumulated matching changes
@@ -336,6 +491,16 @@ export interface ServerStorage {
   /** Scope-filtered snapshot scan, ordered by rowId (bootstrap paging). */
   scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]>;
 
+  /**
+   * Optional registered-query capability. The implementation MUST replace
+   * every generated app-table relation with a partition-filtered relation and
+   * return rows plus maxCommitSeq from one consistent database snapshot.
+   */
+  queryAuthoritative?(
+    partition: string,
+    query: AuthoritativeQueryRequest,
+  ): Promise<AuthoritativeQueryResult>;
+
   /**
    * Optional trusted-host exact lookup through a declared relational index.
    * This capability is outside client scope/subscription authorization and

package/src/validate.ts

@@ -32,6 +32,7 @@ import {
 export const RESERVED_VALIDATION_CODE_PREFIXES: readonly string[] = [
   'sync.',
   'blob.',
+  'operation.',
   'presence.',
   'client.',
 ];