@syncular/server 0.1.3 → 0.2.0

package/src/errors.ts

@@ -1,22 +1,244 @@
-export class SyncClientSchemaUnsupportedError extends Error {
-  readonly code = 'sync.client_schema_unsupported' as const;
-  readonly schemaVersion: number | null;
-  readonly supportedSchemaVersions: readonly number[];
+/**
+ * Server-side protocol errors (SPEC.md §10).
+ *
+ * Every request-level failure raised by the server core is a `SyncError`
+ * carrying the fixed catalog metadata of §10.2 (`category`, `retryable`,
+ * `recommendedAction`) plus an HTTP status for transport adapters. The
+ * catalog is closed: creating a `SyncError` with an unknown code throws.
+ */
 
-  constructor(options: {
-    schemaVersion: number | null | undefined;
-    supportedSchemaVersions: readonly number[];
-  }) {
-    const schemaVersion = options.schemaVersion ?? null;
-    super(
-      `Client schema version ${
-        schemaVersion ?? 'unknown'
-      } is not supported. Supported client schema versions: ${options.supportedSchemaVersions.join(
-        ', '
-      )}.`
-    );
-    this.name = 'SyncClientSchemaUnsupportedError';
-    this.schemaVersion = schemaVersion;
-    this.supportedSchemaVersions = options.supportedSchemaVersions;
+export interface ErrorCatalogEntry {
+  readonly category: string;
+  readonly retryable: boolean;
+  readonly recommendedAction: string;
+  readonly httpStatus: number;
+}
+
+/** The §10.2 wire catalog (21 sync.* + 4 blob.* codes), keyed by stable code. */
+export const ERROR_CATALOG: Readonly<Record<string, ErrorCatalogEntry>> = {
+  'sync.auth_required': {
+    category: 'auth-required',
+    retryable: true,
+    recommendedAction: 'refreshAuth',
+    httpStatus: 401,
+  },
+  // §7.3.3: outage without a valid lease. §7.3.4: revoked lease.
+  'sync.auth_lease_required': {
+    category: 'auth-required',
+    retryable: true,
+    recommendedAction: 'refreshAuth',
+    httpStatus: 401,
+  },
+  'sync.auth_lease_revoked': {
+    category: 'auth-required',
+    retryable: true,
+    recommendedAction: 'refreshAuth',
+    httpStatus: 401,
+  },
+  'sync.forbidden': {
+    category: 'forbidden',
+    retryable: false,
+    recommendedAction: 'checkPermissions',
+    httpStatus: 403,
+  },
+  'sync.invalid_request': {
+    category: 'invalid-request',
+    retryable: false,
+    recommendedAction: 'fixRequest',
+    httpStatus: 400,
+  },
+  'sync.invalid_client_id': {
+    category: 'invalid-request',
+    retryable: false,
+    recommendedAction: 'resetClientId',
+    httpStatus: 400,
+  },
+  'sync.invalid_subscription': {
+    category: 'invalid-request',
+    retryable: false,
+    recommendedAction: 'fixRequest',
+    httpStatus: 400,
+  },
+  'sync.empty_commit': {
+    category: 'invalid-request',
+    retryable: false,
+    recommendedAction: 'fixRequest',
+    httpStatus: 400,
+  },
+  'sync.unknown_table': {
+    category: 'schema-mismatch',
+    retryable: false,
+    recommendedAction: 'regenerateClient',
+    httpStatus: 400,
+  },
+  'sync.row_missing': {
+    category: 'not-found',
+    retryable: false,
+    recommendedAction: 'forceResync',
+    httpStatus: 404,
+  },
+  'sync.version_conflict': {
+    category: 'conflict',
+    retryable: false,
+    recommendedAction: 'resolveConflict',
+    httpStatus: 409,
+  },
+  'sync.constraint_violation': {
+    category: 'invalid-request',
+    retryable: false,
+    recommendedAction: 'fixRequest',
+    httpStatus: 400,
+  },
+  'sync.missing_scopes': {
+    category: 'internal',
+    retryable: false,
+    recommendedAction: 'inspectServer',
+    httpStatus: 500,
+  },
+  // §5.10.6: a crdt column was pushed with no merger registered for its
+  // crdtType, or the merger threw. A push operation-result error only.
+  'sync.crdt_merge_failed': {
+    category: 'internal',
+    retryable: false,
+    recommendedAction: 'inspectServer',
+    httpStatus: 500,
+  },
+  'sync.idempotency_cache_miss': {
+    category: 'internal',
+    retryable: true,
+    recommendedAction: 'retryLater',
+    httpStatus: 500,
+  },
+  'sync.too_many_operations': {
+    category: 'invalid-request',
+    retryable: false,
+    recommendedAction: 'splitBatch',
+    httpStatus: 400,
+  },
+  'sync.not_found': {
+    category: 'not-found',
+    retryable: false,
+    recommendedAction: 'forceResync',
+    httpStatus: 404,
+  },
+  'sync.segment_expired': {
+    category: 'not-found',
+    retryable: true,
+    recommendedAction: 'retryLater',
+    httpStatus: 404,
+  },
+  'sync.cursor_expired': {
+    category: 'reset-required',
+    retryable: false,
+    recommendedAction: 'rebootstrap',
+    httpStatus: 400,
+  },
+  'sync.scope_revoked': {
+    category: 'scope-revoked',
+    retryable: false,
+    recommendedAction: 'checkPermissions',
+    httpStatus: 403,
+  },
+  'sync.rate_limited': {
+    category: 'rate-limited',
+    retryable: true,
+    recommendedAction: 'retryLater',
+    httpStatus: 429,
+  },
+  'sync.schema_mismatch': {
+    category: 'schema-mismatch',
+    retryable: false,
+    recommendedAction: 'regenerateClient',
+    httpStatus: 400,
+  },
+  'sync.client_schema_unsupported': {
+    category: 'schema-mismatch',
+    retryable: false,
+    recommendedAction: 'upgradeClient',
+    httpStatus: 400,
+  },
+  'sync.websocket_connection_limit': {
+    category: 'rate-limited',
+    retryable: true,
+    recommendedAction: 'retryLater',
+    httpStatus: 429,
+  },
+  // §5.9 blobs — the closed blob.* set (§10.2).
+  'blob.not_found': {
+    category: 'not-found',
+    retryable: false,
+    recommendedAction: 'fixRequest',
+    httpStatus: 404,
+  },
+  'blob.forbidden': {
+    category: 'forbidden',
+    retryable: false,
+    recommendedAction: 'checkPermissions',
+    httpStatus: 403,
+  },
+  'blob.hash_mismatch': {
+    category: 'invalid-request',
+    retryable: false,
+    recommendedAction: 'fixRequest',
+    httpStatus: 400,
+  },
+  'blob.too_large': {
+    category: 'invalid-request',
+    retryable: false,
+    recommendedAction: 'fixRequest',
+    httpStatus: 413,
+  },
+};
+
+export class SyncError extends Error {
+  override readonly name = 'SyncError';
+  readonly code: string;
+  readonly category: string;
+  readonly retryable: boolean;
+  readonly recommendedAction: string;
+  readonly httpStatus: number;
+  readonly details?: string;
+
+  constructor(code: string, message?: string, details?: string) {
+    const entry = ERROR_CATALOG[code];
+    if (entry === undefined) {
+      throw new Error(`unknown error code ${code} (not in the §10.2 catalog)`);
+    }
+    super(message ?? code);
+    this.code = code;
+    this.category = entry.category;
+    this.retryable = entry.retryable;
+    this.recommendedAction = entry.recommendedAction;
+    this.httpStatus = entry.httpStatus;
+    if (details !== undefined) this.details = details;
   }
 }
+
+export function syncError(
+  code: string,
+  message?: string,
+  details?: string,
+): SyncError {
+  return new SyncError(code, message, details);
+}
+
+/** The §10.1 JSON error shape, for HTTP-level error bodies (§1.1). */
+export function errorBody(error: SyncError): {
+  code: string;
+  category: string;
+  retryable: boolean;
+  recommendedAction: string;
+  message: string;
+  details?: unknown;
+} {
+  return {
+    code: error.code,
+    category: error.category,
+    retryable: error.retryable,
+    recommendedAction: error.recommendedAction,
+    message: error.message,
+    ...(error.details !== undefined
+      ? { details: JSON.parse(error.details) as unknown }
+      : {}),
+  };
+}

package/src/events-ring.ts

@@ -0,0 +1,116 @@
+/**
+ * Event ring buffer + sink composition (TODO §2.5) — the "event stream"
+ * without any infrastructure dependency.
+ *
+ * `RingBufferEvents` is a `SyncularServerEvents` sink that retains the last
+ * N events in memory and exposes a `query({type?, sinceMs?, limit})`. It
+ * composes with any other sink through `composeEvents(...sinks)`, so a host
+ * can keep `consoleJsonEvents()` (or a Sentry adapter) AND feed the console
+ * event tail from the same emissions. Fire-and-forget discipline is
+ * preserved: a throwing member sink never affects the others (each emit is
+ * guarded), and the ring itself never throws through.
+ */
+import {
+  emitEvent,
+  type SyncularServerEvent,
+  type SyncularServerEvents,
+} from './events';
+
+export interface RingEventQuery {
+  /** Restrict to one event `type` (e.g. `push.applied`). */
+  readonly type?: SyncularServerEvent['type'];
+  /** Only events with `atMs >= sinceMs`. */
+  readonly sinceMs?: number;
+  /** Newest-first cap (default: the whole retained buffer). */
+  readonly limit?: number;
+}
+
+export const DEFAULT_RING_CAPACITY = 1000;
+
+/**
+ * In-memory ring of the most recent events. When full, the oldest event is
+ * dropped as a new one arrives (bounded memory — the §1.4 anti-goal
+ * discipline applied to observability). Events are stored by reference;
+ * they are already frozen-shape JSON-able objects by the events contract,
+ * so no copy is made on emit.
+ */
+export class RingBufferEvents implements SyncularServerEvents {
+  readonly #capacity: number;
+  #buffer: SyncularServerEvent[] = [];
+  /** Index of the oldest element in the circular buffer. */
+  #head = 0;
+  #size = 0;
+
+  constructor(options?: { readonly capacity?: number }) {
+    const capacity = options?.capacity ?? DEFAULT_RING_CAPACITY;
+    if (!Number.isInteger(capacity) || capacity <= 0) {
+      throw new Error('RingBufferEvents capacity must be a positive integer');
+    }
+    this.#capacity = capacity;
+  }
+
+  emit(event: SyncularServerEvent): void {
+    if (this.#size < this.#capacity) {
+      this.#buffer[(this.#head + this.#size) % this.#capacity] = event;
+      this.#size += 1;
+    } else {
+      // Full: overwrite the oldest and advance the head.
+      this.#buffer[this.#head] = event;
+      this.#head = (this.#head + 1) % this.#capacity;
+    }
+  }
+
+  /** The configured maximum number of retained events. */
+  get capacity(): number {
+    return this.#capacity;
+  }
+
+  /** The number of events currently retained. */
+  get size(): number {
+    return this.#size;
+  }
+
+  /**
+   * Newest-first slice of the retained events. Filters by `type` and
+   * `sinceMs`, then caps to `limit`. Returns a fresh array — the caller may
+   * mutate it freely.
+   */
+  query(query: RingEventQuery = {}): SyncularServerEvent[] {
+    const limit = query.limit ?? this.#size;
+    const out: SyncularServerEvent[] = [];
+    // Walk newest → oldest.
+    for (let i = this.#size - 1; i >= 0 && out.length < limit; i -= 1) {
+      const event = this.#buffer[(this.#head + i) % this.#capacity];
+      if (event === undefined) continue;
+      if (query.type !== undefined && event.type !== query.type) continue;
+      if (query.sinceMs !== undefined && event.atMs < query.sinceMs) continue;
+      out.push(event);
+    }
+    return out;
+  }
+
+  /** Drop all retained events. */
+  clear(): void {
+    this.#buffer = [];
+    this.#head = 0;
+    this.#size = 0;
+  }
+}
+
+/**
+ * Fan one emission out to several sinks. Each member emit is guarded, so a
+ * throwing sink never affects the others or the request path (the same
+ * fire-and-forget contract as `emitEvent`). Composing zero sinks yields a
+ * silent no-op sink.
+ */
+export function composeEvents(
+  ...sinks: readonly SyncularServerEvents[]
+): SyncularServerEvents {
+  return {
+    emit(event) {
+      for (const sink of sinks) {
+        emitEvent(sink, event);
+      }
+    },
+  };
+}

package/src/events.ts

@@ -0,0 +1,291 @@
+/**
+ * Structured server events — the one operational seam (host surface, not
+ * wire protocol; SPEC.md is untouched by this module).
+ *
+ * Design rules:
+ * - Every event is a flat, JSON-able object with a stable `type` string:
+ *   the same shapes feed one-line JSON logs, metrics pipelines, and error
+ *   trackers alike. No logger dependency, no formatting — emission only.
+ * - Emission is fire-and-forget: a throwing handler MUST NOT affect
+ *   request processing (`emitEvent` swallows), and when no sink is
+ *   configured the hot path pays only an `undefined` check — call sites
+ *   never build event objects behind a disabled check.
+ * - Timestamps and durations come from the ctx clock where one exists, so
+ *   the conformance virtual-clock discipline stays intact.
+ */
+import type { WakeReason } from '@syncular/core';
+
+/** One `POST /sync` request, emitted once per request after the response
+ * bytes are fully produced (or the request was rejected up front). */
+export interface RequestHandledEvent {
+  readonly type: 'request.handled';
+  readonly kind: 'sync';
+  readonly atMs: number;
+  readonly partition: string;
+  readonly actorId: string;
+  readonly durationMs: number;
+  readonly bytesIn: number;
+  readonly bytesOut: number;
+  /**
+   * `ok` — response streamed to END;
+   * `schema_floor` — §2.4 required-schema answer;
+   * `rejected` — request validation failed before any bytes (§1.7);
+   * `error` — in-band ERROR frame (§1.6) or a thrown host failure.
+   */
+  readonly outcome: 'ok' | 'schema_floor' | 'rejected' | 'error';
+  /** §10.2 code for `rejected`/`error`; `"internal"` for non-SyncErrors. */
+  readonly errorCode?: string;
+  readonly pushCommits: number;
+  readonly pulled: boolean;
+  readonly subscriptions: number;
+}
+
+interface PushEventBase {
+  readonly atMs: number;
+  readonly partition: string;
+  readonly actorId: string;
+  readonly clientId: string;
+  readonly clientCommitId: string;
+  /** Operations carried by the PUSH_COMMIT frame. */
+  readonly operations: number;
+}
+
+/** A push commit applied (or replayed from the idempotency cache, §2.3). */
+export interface PushAppliedEvent extends PushEventBase {
+  readonly type: 'push.applied';
+  readonly commitSeq?: number;
+  /** True when the result came from the idempotency cache (`cached`). */
+  readonly replay: boolean;
+}
+
+/** A push commit rejected (§6.3) — the terminating operation's code. */
+export interface PushRejectedEvent extends PushEventBase {
+  readonly type: 'push.rejected';
+  readonly code: string;
+  readonly opIndex: number;
+}
+
+/** A push commit terminated by a version conflict (§6.2). */
+export interface PushConflictedEvent extends PushEventBase {
+  readonly type: 'push.conflicted';
+  readonly opIndex: number;
+}
+
+/** One emitted segment within a pull subscription section. */
+export interface PullSegmentSummary {
+  readonly mediaType: 'rows' | 'sqlite';
+  readonly delivery: 'inline' | 'ref';
+  /** `reused` — served from the §5.3 reuse key without rebuilding. */
+  readonly origin: 'built' | 'reused';
+  readonly bytes: number;
+  readonly rows: number;
+}
+
+/** One subscription section of a served pull (§1.6). */
+export interface PullSubscriptionSummary {
+  readonly id: string;
+  readonly table: string;
+  readonly status: 'active' | 'revoked' | 'reset';
+  /** `none` for revoked/reset sections (no data half was produced). */
+  readonly mode: 'bootstrap' | 'incremental' | 'none';
+  readonly fromCursor: number;
+  readonly nextCursor: number;
+  readonly commits: number;
+  readonly changes: number;
+  readonly segments: readonly PullSegmentSummary[];
+}
+
+/** The pull half of a request, emitted once after all sections streamed. */
+export interface PullServedEvent {
+  readonly type: 'pull.served';
+  readonly atMs: number;
+  readonly partition: string;
+  readonly actorId: string;
+  readonly clientId: string;
+  readonly subscriptions: readonly PullSubscriptionSummary[];
+}
+
+/** A direct segment download (§5.5), success or failure. */
+export interface SegmentDownloadedEvent {
+  readonly type: 'segment.downloaded';
+  readonly atMs: number;
+  readonly partition: string;
+  readonly actorId: string;
+  readonly segmentId: string;
+  readonly outcome: 'ok' | 'error';
+  readonly errorCode?: string;
+  readonly mediaType?: 'rows' | 'sqlite';
+  readonly bytes?: number;
+  readonly durationMs: number;
+}
+
+/** A blob upload accepted (§5.9.3, content address verified). */
+export interface BlobUploadedEvent {
+  readonly type: 'blob.uploaded';
+  readonly atMs: number;
+  readonly partition: string;
+  readonly actorId: string;
+  readonly blobId: string;
+  readonly bytes: number;
+}
+
+/** A blob download (§5.9.5), success or failure. */
+export interface BlobDownloadedEvent {
+  readonly type: 'blob.downloaded';
+  readonly atMs: number;
+  readonly partition: string;
+  readonly actorId: string;
+  readonly blobId: string;
+  readonly outcome: 'ok' | 'error';
+  readonly errorCode?: string;
+  readonly bytes?: number;
+  readonly durationMs: number;
+}
+
+/** A §5.9.2 orphan-blob sweep pass finished (host-scheduled GC). */
+export interface BlobSweptEvent {
+  readonly type: 'blob.swept';
+  readonly atMs: number;
+  readonly partition: string;
+  /** Blobs deleted this pass (unreferenced and older than the grace period). */
+  readonly swept: number;
+  /** Size of the live keep-set consulted (§5.9.4 reference index). */
+  readonly referenced: number;
+  /** The grace period applied (ms) — the upload→push race protection. */
+  readonly graceMs: number;
+}
+
+interface RealtimeEventBase {
+  readonly atMs: number;
+  readonly partition: string;
+  readonly actorId: string;
+  readonly clientId: string;
+  readonly sessionId: string;
+}
+
+/** A realtime session registered and greeted (§8.1). */
+export interface RealtimeOpenedEvent extends RealtimeEventBase {
+  readonly type: 'realtime.opened';
+  readonly registrations: number;
+  readonly cursor: number;
+  readonly latestSeq: number;
+}
+
+/** A realtime session left the hub. */
+export interface RealtimeClosedEvent extends RealtimeEventBase {
+  readonly type: 'realtime.closed';
+  readonly durationMs: number;
+}
+
+/** A delta message pushed over the socket (§8.2). */
+export interface RealtimeDeltaEvent extends RealtimeEventBase {
+  readonly type: 'realtime.delta';
+  readonly commitSeq: number;
+  readonly bytes: number;
+  readonly changes: number;
+}
+
+/** A `sync` wake-up sent instead of (or in addition to) deltas (§8.3). */
+export interface RealtimeWakeEvent extends RealtimeEventBase {
+  readonly type: 'realtime.wake';
+  readonly reason: WakeReason;
+}
+
+/** A §4.6 prune pass finished (whether or not the horizon moved). */
+export interface PruneCompletedEvent {
+  readonly type: 'prune.completed';
+  readonly atMs: number;
+  readonly partition: string;
+  readonly previousHorizonSeq: number;
+  readonly horizonSeq: number;
+  readonly advanced: boolean;
+  readonly removedCommits: number;
+}
+
+/** The host `resolveScopes` callback threw — the §3.2/§3.4 fail-loud
+ * path (subscriptions revoke, writes reject, downloads deny). */
+export interface ScopesResolveFailedEvent {
+  readonly type: 'scopes.resolve_failed';
+  readonly atMs: number;
+  readonly partition: string;
+  readonly actorId: string;
+  readonly phase: 'request' | 'realtime' | 'segment-download' | 'blob-download';
+  readonly message: string;
+}
+
+/** §7.3.3: a lease was issued or refreshed (sliding window) on an
+ * authorized round and a `LEASE` frame emitted. */
+export interface LeaseIssuedEvent {
+  readonly type: 'lease.issued';
+  readonly atMs: number;
+  readonly partition: string;
+  readonly actorId: string;
+  readonly clientId: string;
+  readonly leaseId: string;
+  readonly expiresAtMs: number;
+}
+
+/** §7.3.4: a lease was revoked by the host (out-of-band control call). */
+export interface LeaseRevokedEvent {
+  readonly type: 'lease.revoked';
+  readonly atMs: number;
+  readonly partition: string;
+  readonly leaseId: string;
+}
+
+export type SyncularServerEvent =
+  | RequestHandledEvent
+  | PushAppliedEvent
+  | PushRejectedEvent
+  | PushConflictedEvent
+  | PullServedEvent
+  | SegmentDownloadedEvent
+  | BlobUploadedEvent
+  | BlobDownloadedEvent
+  | BlobSweptEvent
+  | RealtimeOpenedEvent
+  | RealtimeClosedEvent
+  | RealtimeDeltaEvent
+  | RealtimeWakeEvent
+  | PruneCompletedEvent
+  | ScopesResolveFailedEvent
+  | LeaseIssuedEvent
+  | LeaseRevokedEvent;
+
+/**
+ * The seam. Optional on the server config — when absent, no event object
+ * is ever built. Implementations receive every event synchronously and
+ * MUST NOT rely on throwing to influence processing: exceptions are
+ * swallowed at the emission point.
+ */
+export interface SyncularServerEvents {
+  emit(event: SyncularServerEvent): void;
+}
+
+/** Guarded emission: a throwing sink never affects request processing. */
+export function emitEvent(
+  sink: SyncularServerEvents,
+  event: SyncularServerEvent,
+): void {
+  try {
+    sink.emit(event);
+  } catch {
+    // fire-and-forget by contract
+  }
+}
+
+/**
+ * Reference sink: one line of JSON per event (stdout by default).
+ * Suitable for piping into any log collector.
+ */
+export function consoleJsonEvents(
+  write: (line: string) => void = (line) => {
+    console.log(line);
+  },
+): SyncularServerEvents {
+  return {
+    emit(event) {
+      write(JSON.stringify(event));
+    },
+  };
+}