@syncular/server 0.15.44 → 0.15.46

package/src/errors.ts

@@ -14,8 +14,50 @@ export interface ErrorCatalogEntry {
   readonly httpStatus: number;
 }
 
-/** The §10.2 wire catalog (21 sync.* + 4 blob.* codes), keyed by stable code. */
+/** The §10.2 wire catalog, keyed by stable code. */
 export const ERROR_CATALOG: Readonly<Record<string, ErrorCatalogEntry>> = {
+  'operation.unknown': {
+    category: 'not-found',
+    retryable: false,
+    recommendedAction: 'regenerateClient',
+    httpStatus: 404,
+  },
+  'operation.forbidden': {
+    category: 'forbidden',
+    retryable: false,
+    recommendedAction: 'checkPermissions',
+    httpStatus: 403,
+  },
+  'operation.invalid_request': {
+    category: 'invalid-request',
+    retryable: false,
+    recommendedAction: 'fixRequest',
+    httpStatus: 400,
+  },
+  'operation.result_too_large': {
+    category: 'invalid-request',
+    retryable: false,
+    recommendedAction: 'fixRequest',
+    httpStatus: 400,
+  },
+  'operation.storage_unsupported': {
+    category: 'internal',
+    retryable: false,
+    recommendedAction: 'inspectServer',
+    httpStatus: 500,
+  },
+  'operation.query_failed': {
+    category: 'internal',
+    retryable: false,
+    recommendedAction: 'inspectServer',
+    httpStatus: 500,
+  },
+  'operation.execution_failed': {
+    category: 'internal',
+    retryable: false,
+    recommendedAction: 'inspectServer',
+    httpStatus: 500,
+  },
   'sync.auth_required': {
     category: 'auth-required',
     retryable: true,

package/src/events-ring.ts

@@ -1,5 +1,5 @@
 /**
- * Event ring buffer + sink composition (TODO §2.5) — the "event stream"
+ * Event ring buffer + sink composition: the "event stream"
  * without any infrastructure dependency.
  *
  * `RingBufferEvents` is a `SyncularServerEvents` sink that retains the last

package/src/events.ts

@@ -1,6 +1,6 @@
 /**
- * Structured server events — the one operational seam (host surface, not
- * wire protocol; SPEC.md is untouched by this module).
+ * Structured server events — the one operational seam (host surface, outside
+ * the wire protocol).
  *
  * Design rules:
  * - Every event is a flat, JSON-able object with a stable `type` string:
@@ -81,6 +81,62 @@ export interface PushConflictedEvent extends PushEventBase {
   readonly cacheIdentity?: string;
 }
 
+/** A planned reaction committed atomically with its accepted source commit. */
+export interface ReactionQueuedEvent {
+  readonly type: 'reaction.queued';
+  readonly atMs: number;
+  readonly partition: string;
+  readonly actorId: string;
+  readonly clientId: string;
+  readonly clientCommitId: string;
+  readonly commitSeq: number;
+  readonly idempotencyKey: string;
+  readonly reactionType: string;
+  readonly version: number;
+}
+
+interface ReactionDeliveryEventBase {
+  readonly atMs: number;
+  readonly partition: string;
+  readonly workerId: string;
+  readonly idempotencyKey: string;
+  readonly reactionType: string;
+  readonly version: number;
+  readonly attempt: number;
+}
+
+export interface ReactionStartedEvent extends ReactionDeliveryEventBase {
+  readonly type: 'reaction.started';
+}
+
+export interface ReactionRetriedEvent extends ReactionDeliveryEventBase {
+  readonly type: 'reaction.retried';
+  readonly nextAttemptAtMs: number;
+  readonly errorCode: string;
+}
+
+export interface ReactionCompletedEvent extends ReactionDeliveryEventBase {
+  readonly type: 'reaction.completed';
+}
+
+export interface ReactionDeadLetteredEvent extends ReactionDeliveryEventBase {
+  readonly type: 'reaction.dead_lettered';
+  readonly errorCode: string;
+}
+
+/** One bounded terminal-reaction retention pass. */
+export interface ReactionPruneCompletedEvent {
+  readonly type: 'reaction.prune_completed';
+  readonly atMs: number;
+  readonly partition: string;
+  readonly completedBeforeMs: number;
+  readonly deadLetterBeforeMs: number;
+  readonly limit: number;
+  readonly removedCompleted: number;
+  readonly removedDeadLetter: number;
+  readonly mayHaveMore: boolean;
+}
+
 /** One emitted segment within a pull subscription section. */
 export interface PullSegmentSummary {
   readonly mediaType: 'rows' | 'sqlite';
@@ -248,6 +304,12 @@ export type SyncularServerEvent =
   | PushAppliedEvent
   | PushRejectedEvent
   | PushConflictedEvent
+  | ReactionQueuedEvent
+  | ReactionStartedEvent
+  | ReactionRetriedEvent
+  | ReactionCompletedEvent
+  | ReactionDeadLetteredEvent
+  | ReactionPruneCompletedEvent
   | PullServedEvent
   | SegmentDownloadedEvent
   | BlobUploadedEvent

package/src/handler.ts

@@ -1,5 +1,5 @@
 /**
- * `handleSyncRequest(bytes, ctx) → bytes` (SPEC.md §1, REVISE B2).
+ * `handleSyncRequest(bytes, ctx) → bytes` (SPEC.md §1).
  *
  * Internally streaming-friendly (§1.4): `createSyncResponseStream` returns
  * an async iterable of encoded chunks — one per frame — after performing
@@ -23,7 +23,12 @@ import {
   type SubscriptionFrame,
 } from '@syncular/core';
 import type { SyncRequestContext } from './context';
-import { clockOf, limitsOf, RESOLVER_OUTAGE } from './context';
+import {
+  clockOf,
+  limitsOf,
+  REMOTE_COMMAND_CLIENT_ID_PREFIX,
+  RESOLVER_OUTAGE,
+} from './context';
 import { SyncError, syncError } from './errors';
 import {
   emitEvent,
@@ -215,6 +220,13 @@ async function planRequest(
     };
   }
 
+  if (header.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
+    throw syncError(
+      'sync.invalid_client_id',
+      'clientId uses a reserved server-command namespace (§1.5)',
+    );
+  }
+
   // §1.5: a clientId already bound to a different actor is rejected.
   const record = await ctx.storage.getClientRecord(
     ctx.partition,
@@ -629,7 +641,7 @@ async function createStreamCore(
     throw error;
   }
   const schema = compileSchema(ctx.schema);
-  // Relational row tables (DESIGN-relational-server-storage.md): create/
+  // Relational row tables: create/
   // migrate on first contact; memoized per storage instance thereafter.
   await ctx.storage.ensureSchema(schema);
   const plan = await planRequest(request, ctx, schema);

package/src/index.ts

@@ -1,6 +1,6 @@
 /**
  * @syncular/server — framework-free embeddable SSP2 protocol library
- * (SPEC.md is normative; REVISE.md B2 is the architectural mandate).
+ * (SPEC.md is normative).
  *
  * Core surface: `handleSyncRequest(bytes, ctx) → bytes` over host-provided
  * storage / scope-resolution / segment-store interfaces, plus a
@@ -8,6 +8,7 @@
  * handler (§5.5), and signed-URL token issuance/verification (§5.4).
  */
 export * from './admin';
+export * from './authoritative-query';
 export * from './blob-handlers';
 export * from './blob-store';
 export * from './content-encoding';
@@ -20,6 +21,8 @@ export * from './events-ring';
 export * from './frame-bytes';
 export * from './handler';
 export * from './lease-store';
+export * from './operations';
+export * from './operations-realtime';
 // The `PgExecutor` seam + Postgres storage/fanout are driver-agnostic (zero
 // runtime deps). Concrete driver adapters (pglite for tests; Bun.sql /
 // node-postgres for production, documented in the README) live in separate
@@ -31,6 +34,35 @@ export * from './prune';
 export * from './pull';
 export * from './push';
 export * from './readiness';
+export {
+  DEFAULT_REACTION_INITIAL_BACKOFF_MS,
+  DEFAULT_REACTION_LEASE_MS,
+  DEFAULT_REACTION_MAX_ATTEMPTS,
+  DEFAULT_REACTION_MAX_BACKOFF_MS,
+  DEFAULT_REACTION_RETENTION,
+  MAX_REACTION_FAILURE_DETAILS_BYTES,
+  MAX_REACTION_PAYLOAD_BYTES,
+  MAX_REACTIONS_PER_COMMIT,
+  PermanentReactionError,
+  pruneReactions,
+  ReactionRunner,
+  reactionIdempotencyKey,
+  retryDeadLetterReaction,
+  RetryableReactionError,
+  type PlannedReaction,
+  type PruneReactionsOptions,
+  type ReactionHandler,
+  type ReactionHandlerInput,
+  type ReactionHandlers,
+  type ReactionPlan,
+  type ReactionPlanner,
+  type ReactionPlannerInput,
+  type ReactionPruneResult,
+  type ReactionRetentionPolicy,
+  type ReactionRunnerOptions,
+  type ReactionRunResult,
+  type ReactionTypeMap,
+} from './reactions';
 export * from './realtime';
 export * from './relational-rows';
 export * from './s3-blob-store';

package/src/operations-realtime.ts

@@ -0,0 +1,272 @@
+import {
+  decodeRemoteOperationRealtimeMessage,
+  encodeRemoteOperationRealtimeMessage,
+  type RemoteOperationRealtimeMessage,
+} from '@syncular/core';
+import type { RealtimeNotifier, SyncRequestContext } from './context';
+import { REMOTE_COMMAND_CLIENT_ID_PREFIX } from './context';
+import { SyncError, syncError } from './errors';
+import type {
+  RegisteredRemoteQuery,
+  RemoteOperationRegistry,
+} from './operations';
+import type { StoredCommit } from './storage';
+
+export interface RemoteOperationWatchSession {
+  receive(bytes: Uint8Array): Promise<void>;
+  close(): void;
+}
+
+interface WatchState {
+  readonly watchId: string;
+  readonly clientId: string;
+  readonly operation: RegisteredRemoteQuery;
+  readonly params: unknown;
+  running: boolean;
+  dirty: boolean;
+}
+
+class WatchSession implements RemoteOperationWatchSession {
+  readonly #ctx: SyncRequestContext;
+  readonly #registry: RemoteOperationRegistry;
+  readonly #send: (bytes: Uint8Array) => void;
+  readonly #closed: () => void;
+  readonly #watches = new Map<string, WatchState>();
+  #isClosed = false;
+
+  get partition(): string {
+    return this.#ctx.partition;
+  }
+
+  constructor(
+    ctx: SyncRequestContext,
+    registry: RemoteOperationRegistry,
+    send: (bytes: Uint8Array) => void,
+    closed: () => void,
+  ) {
+    this.#ctx = ctx;
+    this.#registry = registry;
+    this.#send = send;
+    this.#closed = closed;
+  }
+
+  async receive(bytes: Uint8Array): Promise<void> {
+    if (this.#isClosed) return;
+    let message: RemoteOperationRealtimeMessage;
+    try {
+      message = decodeRemoteOperationRealtimeMessage(bytes);
+      if (
+        typeof message !== 'object' ||
+        message === null ||
+        message.revision !== 1 ||
+        (message.kind !== 'watch' && message.kind !== 'unwatch') ||
+        typeof message.watchId !== 'string' ||
+        message.watchId.length === 0
+      ) {
+        throw syncError('operation.invalid_request');
+      }
+      if (message.kind === 'watch') {
+        if (
+          typeof message.clientId !== 'string' ||
+          message.clientId.length === 0 ||
+          typeof message.operationId !== 'string' ||
+          message.operationId.length === 0
+        ) {
+          throw syncError('operation.invalid_request');
+        }
+      }
+    } catch (error) {
+      if (error instanceof SyncError) throw error;
+      throw syncError('operation.invalid_request');
+    }
+    if (message.kind === 'unwatch') {
+      this.#watches.delete(message.watchId);
+      return;
+    }
+    if (this.#watches.has(message.watchId)) {
+      this.#sendError(
+        message.watchId,
+        syncError('operation.invalid_request', 'watchId is already active'),
+      );
+      return;
+    }
+    if (message.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
+      this.#sendError(
+        message.watchId,
+        syncError(
+          'sync.invalid_client_id',
+          'clientId uses a reserved server-command namespace (§1.5)',
+        ),
+      );
+      return;
+    }
+    const clientRecord = await this.#ctx.storage.getClientRecord(
+      this.#ctx.partition,
+      message.clientId,
+    );
+    if (
+      clientRecord !== undefined &&
+      clientRecord.actorId !== this.#ctx.actorId
+    ) {
+      this.#sendError(
+        message.watchId,
+        syncError(
+          'sync.invalid_client_id',
+          'clientId is bound to a different actor in this partition (§1.5)',
+        ),
+      );
+      return;
+    }
+    const operation = this.#registry.get(message.operationId);
+    if (operation === undefined || operation.kind !== 'query') {
+      this.#sendError(message.watchId, syncError('operation.unknown'));
+      return;
+    }
+    const state: WatchState = {
+      watchId: message.watchId,
+      clientId: message.clientId,
+      operation,
+      params: message.params,
+      running: false,
+      dirty: false,
+    };
+    this.#watches.set(message.watchId, state);
+    await this.#refresh(state);
+  }
+
+  notify(tables: ReadonlySet<string>): void {
+    for (const state of this.#watches.values()) {
+      if (!state.operation.tables.some((table) => tables.has(table))) continue;
+      if (state.running) state.dirty = true;
+      else void this.#refresh(state);
+    }
+  }
+
+  async #refresh(state: WatchState): Promise<void> {
+    if (this.#isClosed || this.#watches.get(state.watchId) !== state) return;
+    if (state.running) {
+      state.dirty = true;
+      return;
+    }
+    state.running = true;
+    try {
+      do {
+        state.dirty = false;
+        try {
+          const response = await state.operation.run(
+            this.#ctx,
+            state.clientId,
+            state.params,
+          );
+          if (this.#isClosed || this.#watches.get(state.watchId) !== state) {
+            return;
+          }
+          if (response.kind !== 'query') {
+            throw syncError('operation.query_failed');
+          }
+          if (
+            !this.#emit(
+              encodeRemoteOperationRealtimeMessage({
+                revision: 1,
+                kind: 'snapshot',
+                watchId: state.watchId,
+                operationId: response.operationId,
+                rows: response.rows,
+                maxCommitSeq: response.maxCommitSeq,
+              }),
+            )
+          )
+            return;
+        } catch (error) {
+          if (this.#isClosed || this.#watches.get(state.watchId) !== state) {
+            return;
+          }
+          this.#sendError(
+            state.watchId,
+            error instanceof SyncError
+              ? error
+              : syncError('operation.query_failed'),
+          );
+        }
+      } while (
+        state.dirty &&
+        !this.#isClosed &&
+        this.#watches.get(state.watchId) === state
+      );
+    } finally {
+      state.running = false;
+    }
+  }
+
+  #sendError(watchId: string, error: SyncError): void {
+    this.#emit(
+      encodeRemoteOperationRealtimeMessage({
+        revision: 1,
+        kind: 'watch_error',
+        watchId,
+        code: error.code,
+        message: error.message,
+        retryable: error.retryable,
+      }),
+    );
+  }
+
+  #emit(bytes: Uint8Array): boolean {
+    if (this.#isClosed) return false;
+    try {
+      this.#send(bytes);
+      return true;
+    } catch {
+      this.close();
+      return false;
+    }
+  }
+
+  close(): void {
+    if (this.#isClosed) return;
+    this.#isClosed = true;
+    this.#watches.clear();
+    this.#closed();
+  }
+}
+
+/** In-memory invalidation hub. Every notification reruns affected watches. */
+export class RemoteOperationWatchHub implements RealtimeNotifier {
+  readonly #registry: RemoteOperationRegistry;
+  readonly #sessions = new Set<WatchSession>();
+
+  constructor(registry: RemoteOperationRegistry) {
+    this.#registry = registry;
+  }
+
+  connect(
+    ctx: SyncRequestContext,
+    send: (bytes: Uint8Array) => void,
+  ): RemoteOperationWatchSession {
+    const session = new WatchSession(ctx, this.#registry, send, () => {
+      this.#sessions.delete(session);
+    });
+    this.#sessions.add(session);
+    return session;
+  }
+
+  notifyCommit(partition: string, commit: StoredCommit): void {
+    const tables = new Set(commit.changes.map((change) => change.table));
+    for (const session of this.#sessions) {
+      if (session.partition === partition) session.notify(tables);
+    }
+  }
+}
+
+/** Fan one applied commit into sync deltas and registered query watches. */
+export function composeRealtimeNotifiers(
+  ...notifiers: readonly RealtimeNotifier[]
+): RealtimeNotifier {
+  return {
+    notifyCommit: async (partition, commit) => {
+      await Promise.all(
+        notifiers.map((notifier) => notifier.notifyCommit(partition, commit)),
+      );
+    },
+  };
+}