@absolutejs/sync 1.20.1 → 1.22.0

package/dist/engine/syncEngine.d.ts

@@ -1,3 +1,4 @@
+import { type TracerProvider as TelemetryTracerProvider } from '@absolutejs/telemetry';
 import type { CollectionContext, CollectionDefinition, JoinCollectionDefinition } from './collection';
 import type { GraphCollectionDefinition } from './graph';
 import type { MutationDefinition, TableWriter, TransactionRunner } from './mutation';
@@ -296,6 +297,33 @@ export type SyncEngine = {
      * Added in 1.19.0.
      */
     importChangeLog: (snapshot: ChangeLogSnapshot) => number;
+    /**
+     * Reconstruct the state of registered tables as of a target
+     * timestamp by walking the change log forward and folding each op
+     * into a per-table view. Useful for forensic incident response
+     * ("what did the tenant see at 14:32?") and the "I deleted prod
+     * — restore us to 2h ago" recovery story.
+     *
+     * The reconstruction is exact when the log spans `targetAt` (i.e.
+     * the log's oldest entry is at version 1). When the log has been
+     * trimmed (`changeLogSize` / `changeLogRetainMs` evicted older
+     * entries) AND `targetAt` falls in the gap, the result is
+     * best-effort: state walked forward from the OLDEST retained
+     * entry, with `truncated: true` so the caller knows.
+     *
+     * Added in 1.22.0.
+     *
+     * @example
+     * ```ts
+     * const twoHoursAgo = Date.now() - 2 * 60 * 60 * 1000;
+     * const result = await engine.replayTo({ at: twoHoursAgo, tables: ['orders'] });
+     * if (result.truncated) {
+     *   console.warn('Replay truncated — log retention window too short.');
+     * }
+     * console.log(result.rows.orders); // orders as of two hours ago
+     * ```
+     */
+    replayTo: (options: ReplayOptions) => Promise<ReplayResult>;
     /**
      * Subscribe to the live engine activity stream (changes, mutation outcomes,
      * subscribe/unsubscribe). Returns an unsubscribe. Powers the devtools feed.
@@ -466,6 +494,48 @@ export type ChangeLogSnapshot = {
      */
     exportedAt?: number;
 };
+/**
+ * Options for {@link SyncEngine.replayTo}. Added in 1.22.0.
+ */
+export type ReplayOptions = {
+    /**
+     * Target timestamp (`Date.now()`-shaped). The engine walks the
+     * change log forward, applying entries with `at <= targetAt`. The
+     * result is the state as-of `targetAt` (or as close as the log
+     * permits — see `truncated`).
+     */
+    at: number;
+    /**
+     * Optional table filter. When set, only entries whose `table` is
+     * in this list are folded into the result; entries for other
+     * tables are skipped. Useful for "show me what `tasks` looked
+     * like at T" without paying to reconstruct every table.
+     */
+    tables?: ReadonlyArray<string>;
+};
+/**
+ * Returned by {@link SyncEngine.replayTo}. Added in 1.22.0.
+ *
+ * - `rows` — per-table arrays of rows that existed as of `asOfAt`.
+ *   Keys are table names; values are the row objects (in last-write
+ *   order — last write wins for duplicate-keyed inserts).
+ * - `asOfVersion` / `asOfAt` — the version + wall-clock of the LAST
+ *   entry folded into the result. May be earlier than `targetAt` if
+ *   no entries existed between the last-included entry and the
+ *   target.
+ * - `truncated` — `true` when the log has been trimmed past the
+ *   target window (`changeLog[0].version > 1 && changeLog[0].at >
+ *   targetAt`). In this case, `rows` represents the state walked
+ *   forward from the OLDEST retained entry — NOT the actual state
+ *   at `targetAt`. The caller should treat the result as
+ *   "best-effort given retention window" and warn the operator.
+ */
+export type ReplayResult = {
+    asOfVersion: number;
+    asOfAt: number;
+    rows: Record<string, ReadonlyArray<unknown>>;
+    truncated: boolean;
+};
 export type SyncEngineOptions = {
     /**
      * Stable identifier for this engine instance. Defaults to a per-process
@@ -633,6 +703,27 @@ export type SyncEngineOptions = {
             collection: string;
         }) => string | undefined;
     };
+    /**
+     * Optional OpenTelemetry tracer provider. When set, the engine
+     * wraps `subscribe`, `runMutation`, `runMutations`, and cluster
+     * fan-out in spans named `sync.<op>` with `ABS_ATTRS` semantic
+     * conventions (`abs.engine.id`, `abs.collection`, `abs.mutation`,
+     * etc.). When absent, all tracing is a zero-allocation noop —
+     * existing call sites pay nothing. Added in 1.21.0.
+     *
+     * Pass any `@opentelemetry/api`-compatible `TracerProvider`. See
+     * `@absolutejs/telemetry` for the type shape — sync re-uses its
+     * helpers but doesn't peer-dep `@opentelemetry/api` directly.
+     *
+     * @example
+     * ```ts
+     * import { NodeTracerProvider } from '@opentelemetry/sdk-node';
+     * const tp = new NodeTracerProvider({ ... });
+     * tp.register();
+     * const engine = createSyncEngine({ tracerProvider: tp });
+     * ```
+     */
+    tracerProvider?: TelemetryTracerProvider;
 };
 /**
  * The Tier 3 sync engine: a registry of collections plus the view syncer. It is

package/dist/index.js

@@ -542,6 +542,59 @@ var syncSocket = ({
     }
   });
 };
+// node_modules/@absolutejs/telemetry/dist/index.js
+var NOOP_SPAN_CONTEXT = {
+  spanId: "0000000000000000",
+  traceFlags: 0,
+  traceId: "00000000000000000000000000000000"
+};
+var noopSpan = {
+  addEvent: () => noopSpan,
+  end: () => {},
+  isRecording: () => false,
+  recordException: () => {},
+  setAttribute: () => noopSpan,
+  setAttributes: () => noopSpan,
+  setStatus: () => noopSpan,
+  spanContext: () => NOOP_SPAN_CONTEXT,
+  updateName: () => noopSpan
+};
+var startActiveSpanNoop = (_name, optionsOrFn, maybeFn) => {
+  const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
+  return fn(noopSpan);
+};
+var noopTracer = {
+  startActiveSpan: startActiveSpanNoop,
+  startSpan: () => noopSpan
+};
+var tracerOrNoop = (provider, name, version) => provider !== undefined ? provider.getTracer(name, version) : noopTracer;
+var ABS_ATTRS = {
+  tenant: "abs.tenant",
+  shardId: "abs.shard.id",
+  engineId: "abs.engine.id",
+  collection: "abs.collection",
+  mutation: "abs.mutation",
+  mutationAttempt: "abs.mutation.attempt",
+  subscriptionId: "abs.subscription.id",
+  batchSize: "abs.batch.size",
+  clusterMessageOrigin: "abs.cluster.origin",
+  jobId: "abs.job.id",
+  jobKind: "abs.job.kind",
+  jobAttempt: "abs.job.attempt",
+  jobMaxAttempts: "abs.job.max_attempts",
+  workerId: "abs.worker.id",
+  runtimeKey: "abs.runtime.key",
+  runtimePid: "abs.runtime.pid",
+  runtimePort: "abs.runtime.port",
+  runtimeExitReason: "abs.runtime.exit_reason",
+  runtimeReadinessMs: "abs.runtime.readiness_ms",
+  routeShard: "abs.route.shard",
+  routeDecision: "abs.route.decision",
+  secretName: "abs.secret.name",
+  secretFingerprint: "abs.secret.fingerprint",
+  auditKind: "abs.audit.kind"
+};
+
 // src/engine/equiJoin.ts
 var shallowEqual = (a, b) => {
   if (a === b) {
@@ -1390,6 +1443,7 @@ var createSyncEngine = (options = {}) => {
   const runInTransaction = options.transaction;
   const instanceId = options.instanceId ?? globalThis.crypto?.randomUUID?.() ?? `i${Math.random()}`;
   let clusterBus;
+  const tracer = tracerOrNoop(options.tracerProvider, "@absolutejs/sync");
   const importChangeLog = (snapshot) => {
     if (version !== 0) {
       throw new Error(`[sync] importChangeLog: engine already has version ${version}; ` + `restore must happen before any local writes commit.`);
@@ -2181,107 +2235,124 @@ var createSyncEngine = (options = {}) => {
       registry.set(collection.name, collection);
     },
     subscribe: async ({ collection, params, ctx, onDiff, since, signal }) => {
-      checkAborted(signal);
-      const registered = registry.get(collection);
-      if (registered === undefined) {
-        throw new Error(`Unknown collection "${collection}"`);
-      }
-      const tenantSlot = acquireSubscriptionSlot(ctx, { collection });
-      let slotHandedOff = false;
-      try {
-        const typedOnDiff = onDiff;
-        const subscribeSet = subsFor(collection);
-        const wrapReturn = (sub) => {
-          checkAborted(signal);
-          const innerUnsubscribe = sub.unsubscribe;
-          let released = false;
-          const wrappedUnsubscribe = () => {
-            if (released)
-              return;
-            released = true;
-            releaseSubscriptionSlot(tenantSlot);
-            innerUnsubscribe();
-          };
-          const wrapped = { ...sub, unsubscribe: wrappedUnsubscribe };
-          linkAbortToUnsubscribe(signal, wrappedUnsubscribe);
-          slotHandedOff = true;
-          return wrapped;
-        };
-        const registeredKind = registered.kind;
-        if (registeredKind === "join") {
-          const joined = await subscribeJoin(collection, registered, params, ctx, typedOnDiff, subscribeSet);
-          return wrapReturn(joined);
+      const subscribeSpan = tracer.startSpan("sync.subscribe", {
+        attributes: {
+          [ABS_ATTRS.engineId]: instanceId,
+          [ABS_ATTRS.collection]: collection
         }
-        if (registeredKind === "graph") {
-          const graphed = await subscribeGraph(collection, registered, params, ctx, typedOnDiff, subscribeSet);
-          return wrapReturn(graphed);
-        }
-        if (registeredKind === "reactive") {
-          const reactived = await subscribeReactive(collection, registered, params, ctx, typedOnDiff, subscribeSet);
-          return wrapReturn(reactived);
-        }
-        if (registeredKind === "search") {
-          const searched = await subscribeSearch(collection, registered, params, ctx, typedOnDiff, subscribeSet);
-          return wrapReturn(searched);
+      });
+      try {
+        checkAborted(signal);
+        const registered = registry.get(collection);
+        if (registered === undefined) {
+          throw new Error(`Unknown collection "${collection}"`);
         }
-        const definition = registered;
-        if (definition.authorize !== undefined) {
-          const allowed = await definition.authorize(params, ctx);
-          if (!allowed) {
-            throw new UnauthorizedError(`subscribe to collection "${collection}"`);
+        const tenantSlot = acquireSubscriptionSlot(ctx, { collection });
+        let slotHandedOff = false;
+        try {
+          const typedOnDiff = onDiff;
+          const subscribeSet = subsFor(collection);
+          const wrapReturn = (sub) => {
+            checkAborted(signal);
+            const innerUnsubscribe = sub.unsubscribe;
+            let released = false;
+            const wrappedUnsubscribe = () => {
+              if (released)
+                return;
+              released = true;
+              releaseSubscriptionSlot(tenantSlot);
+              innerUnsubscribe();
+            };
+            const wrapped = { ...sub, unsubscribe: wrappedUnsubscribe };
+            linkAbortToUnsubscribe(signal, wrappedUnsubscribe);
+            slotHandedOff = true;
+            return wrapped;
+          };
+          const registeredKind = registered.kind;
+          if (registeredKind === "join") {
+            const joined = await subscribeJoin(collection, registered, params, ctx, typedOnDiff, subscribeSet);
+            return wrapReturn(joined);
+          }
+          if (registeredKind === "graph") {
+            const graphed = await subscribeGraph(collection, registered, params, ctx, typedOnDiff, subscribeSet);
+            return wrapReturn(graphed);
+          }
+          if (registeredKind === "reactive") {
+            const reactived = await subscribeReactive(collection, registered, params, ctx, typedOnDiff, subscribeSet);
+            return wrapReturn(reactived);
+          }
+          if (registeredKind === "search") {
+            const searched = await subscribeSearch(collection, registered, params, ctx, typedOnDiff, subscribeSet);
+            return wrapReturn(searched);
+          }
+          const definition = registered;
+          if (definition.authorize !== undefined) {
+            const allowed = await definition.authorize(params, ctx);
+            if (!allowed) {
+              throw new UnauthorizedError(`subscribe to collection "${collection}"`);
+            }
+          }
+          const key = definition.key ?? defaultKey;
+          const match = definition.match;
+          const tables = definition.tables ?? [collection];
+          const scopedTable = tables.length === 1 ? tables[0] : undefined;
+          const readRule = scopedTable !== undefined ? readRuleFor(scopedTable) : undefined;
+          const rehydrate = async () => {
+            const raw = [...await definition.hydrate(params, ctx)];
+            const rows = scopedTable !== undefined ? raw.map((row) => migrateRow(scopedTable, row)) : raw;
+            return readRule ? rows.filter((row) => readRule(ctx, row)) : rows;
+          };
+          const incremental = match !== undefined && tables.length === 1;
+          const boundMatch = incremental ? (row) => match(row, params, ctx) && (readRule ? readRule(ctx, row) : true) : () => true;
+          const view = createMaterializedView({
+            key,
+            match: boundMatch
+          });
+          const resuming = since !== undefined && canResume(since, incremental);
+          view.hydrate([...await rehydrate()]);
+          const atVersion = version;
+          const subscription = {
+            kind: "view",
+            collection,
+            view,
+            incremental,
+            rehydrate,
+            key,
+            onDiff: typedOnDiff
+          };
+          subscribeSet.add(subscription);
+          const unsubscribe = () => {
+            subscribeSet.delete(subscription);
+          };
+          if (resuming) {
+            return wrapReturn({
+              initial: [],
+              catchup: buildCatchup(since, tables, key, boundMatch),
+              cursor: currentCursor(),
+              version: atVersion,
+              unsubscribe
+            });
           }
-        }
-        const key = definition.key ?? defaultKey;
-        const match = definition.match;
-        const tables = definition.tables ?? [collection];
-        const scopedTable = tables.length === 1 ? tables[0] : undefined;
-        const readRule = scopedTable !== undefined ? readRuleFor(scopedTable) : undefined;
-        const rehydrate = async () => {
-          const raw = [...await definition.hydrate(params, ctx)];
-          const rows = scopedTable !== undefined ? raw.map((row) => migrateRow(scopedTable, row)) : raw;
-          return readRule ? rows.filter((row) => readRule(ctx, row)) : rows;
-        };
-        const incremental = match !== undefined && tables.length === 1;
-        const boundMatch = incremental ? (row) => match(row, params, ctx) && (readRule ? readRule(ctx, row) : true) : () => true;
-        const view = createMaterializedView({
-          key,
-          match: boundMatch
-        });
-        const resuming = since !== undefined && canResume(since, incremental);
-        view.hydrate([...await rehydrate()]);
-        const atVersion = version;
-        const subscription = {
-          kind: "view",
-          collection,
-          view,
-          incremental,
-          rehydrate,
-          key,
-          onDiff: typedOnDiff
-        };
-        subscribeSet.add(subscription);
-        const unsubscribe = () => {
-          subscribeSet.delete(subscription);
-        };
-        if (resuming) {
           return wrapReturn({
-            initial: [],
-            catchup: buildCatchup(since, tables, key, boundMatch),
+            initial: view.rows(),
             cursor: currentCursor(),
             version: atVersion,
             unsubscribe
           });
+        } catch (error) {
+          if (!slotHandedOff)
+            releaseSubscriptionSlot(tenantSlot);
+          throw error;
         }
-        return wrapReturn({
-          initial: view.rows(),
-          cursor: currentCursor(),
-          version: atVersion,
-          unsubscribe
+      } catch (spanError) {
+        subscribeSpan.recordException(spanError);
+        subscribeSpan.setStatus({
+          code: 2,
+          message: spanError instanceof Error ? spanError.message : String(spanError)
         });
-      } catch (error) {
-        if (!slotHandedOff)
-          releaseSubscriptionSlot(tenantSlot);
-        throw error;
+        throw spanError;
+      } finally {
+        subscribeSpan.end();
       }
     },
     hydrate: async (collection, params, ctx, options2) => {
@@ -2385,85 +2456,102 @@ var createSyncEngine = (options = {}) => {
     },
     migrate: (table, row) => migrateRow(table, row),
     runMutation: async (name, args, ctx) => {
-      const mutation = mutations.get(name);
-      if (mutation === undefined) {
-        throw new Error(`Unknown mutation "${name}"`);
-      }
-      if (mutation.authorize !== undefined) {
-        const allowed = await mutation.authorize(args, ctx);
-        if (!allowed) {
-          throw new UnauthorizedError(`run mutation "${name}"`);
+      const span = tracer.startSpan("sync.runMutation", {
+        attributes: {
+          [ABS_ATTRS.engineId]: instanceId,
+          [ABS_ATTRS.mutation]: name
         }
-      }
-      await acquireMutationSlot();
-      const sandboxRunner = sandboxRunners.get(name);
-      const invokeHandler = sandboxRunner !== undefined ? sandboxRunner : (a, c, actions) => Promise.resolve(mutation.handler(a, c, actions));
-      const runHandler = async (tx) => {
-        const { actions, buffered } = makeActions(tx, ctx, true);
-        const result = await invokeHandler(args, ctx, actions);
-        return { buffered, result };
-      };
-      const retry = mutation.retry;
-      const maxAttempts = retry === undefined ? 1 : retry.maxAttempts ?? 5;
-      const isRetryable = retry?.isRetryable ?? isSerializationFailure;
-      const computeDelay = retry?.backoff ?? exponentialBackoff();
-      const maxElapsedMs = retry?.maxElapsedMs ?? 30000;
-      const startedAt = Date.now();
-      let lastError;
-      let attemptsMade = 0;
+      });
       try {
-        for (let attempt = 1;attempt <= maxAttempts; attempt++) {
-          attemptsMade = attempt;
-          try {
-            const { buffered, result } = runInTransaction !== undefined ? await runInTransaction((tx) => runHandler(tx)) : await runHandler(undefined);
-            await applyChangeBatch(buffered);
-            mutationsCompleted += 1;
-            emitActivity({
-              type: "mutation",
-              at: Date.now(),
-              name,
-              status: "ok"
-            });
-            return result;
-          } catch (error) {
-            lastError = error;
-            const elapsedMs = Date.now() - startedAt;
-            const canRetry = attempt < maxAttempts && isRetryable(error) && elapsedMs < maxElapsedMs;
-            if (!canRetry)
-              break;
-            mutationsRetried += 1;
-            const rawDelay = computeDelay(attempt);
-            const remaining = maxElapsedMs - elapsedMs;
-            if (remaining <= 0)
-              break;
-            const delayMs = Math.max(0, Math.min(rawDelay, remaining));
-            emitActivity({
-              type: "mutationRetry",
-              at: Date.now(),
-              name,
-              attempt,
-              delayMs,
-              errorName: error instanceof Error ? error.name : "Error",
-              errorMessage: error instanceof Error ? error.message : String(error)
-            });
-            if (delayMs > 0) {
-              await new Promise((resolve) => setTimeout(resolve, delayMs));
+        const mutation = mutations.get(name);
+        if (mutation === undefined) {
+          throw new Error(`Unknown mutation "${name}"`);
+        }
+        if (mutation.authorize !== undefined) {
+          const allowed = await mutation.authorize(args, ctx);
+          if (!allowed) {
+            throw new UnauthorizedError(`run mutation "${name}"`);
+          }
+        }
+        await acquireMutationSlot();
+        const sandboxRunner = sandboxRunners.get(name);
+        const invokeHandler = sandboxRunner !== undefined ? sandboxRunner : (a, c, actions) => Promise.resolve(mutation.handler(a, c, actions));
+        const runHandler = async (tx) => {
+          const { actions, buffered } = makeActions(tx, ctx, true);
+          const result = await invokeHandler(args, ctx, actions);
+          return { buffered, result };
+        };
+        const retry = mutation.retry;
+        const maxAttempts = retry === undefined ? 1 : retry.maxAttempts ?? 5;
+        const isRetryable = retry?.isRetryable ?? isSerializationFailure;
+        const computeDelay = retry?.backoff ?? exponentialBackoff();
+        const maxElapsedMs = retry?.maxElapsedMs ?? 30000;
+        const startedAt = Date.now();
+        let lastError;
+        let attemptsMade = 0;
+        try {
+          for (let attempt = 1;attempt <= maxAttempts; attempt++) {
+            attemptsMade = attempt;
+            try {
+              const { buffered, result } = runInTransaction !== undefined ? await runInTransaction((tx) => runHandler(tx)) : await runHandler(undefined);
+              await applyChangeBatch(buffered);
+              mutationsCompleted += 1;
+              emitActivity({
+                type: "mutation",
+                at: Date.now(),
+                name,
+                status: "ok"
+              });
+              return result;
+            } catch (error) {
+              lastError = error;
+              const elapsedMs = Date.now() - startedAt;
+              const canRetry = attempt < maxAttempts && isRetryable(error) && elapsedMs < maxElapsedMs;
+              if (!canRetry)
+                break;
+              mutationsRetried += 1;
+              const rawDelay = computeDelay(attempt);
+              const remaining = maxElapsedMs - elapsedMs;
+              if (remaining <= 0)
+                break;
+              const delayMs = Math.max(0, Math.min(rawDelay, remaining));
+              emitActivity({
+                type: "mutationRetry",
+                at: Date.now(),
+                name,
+                attempt,
+                delayMs,
+                errorName: error instanceof Error ? error.name : "Error",
+                errorMessage: error instanceof Error ? error.message : String(error)
+              });
+              if (delayMs > 0) {
+                await new Promise((resolve) => setTimeout(resolve, delayMs));
+              }
             }
           }
+          mutationsFailed += 1;
+          emitActivity({
+            type: "mutation",
+            at: Date.now(),
+            name,
+            status: "error"
+          });
+          if (attemptsMade > 1) {
+            throw new RetriesExhaustedError(attemptsMade, Date.now() - startedAt, lastError);
+          }
+          throw lastError;
+        } finally {
+          releaseMutationSlot();
         }
-        mutationsFailed += 1;
-        emitActivity({
-          type: "mutation",
-          at: Date.now(),
-          name,
-          status: "error"
+      } catch (spanError) {
+        span.recordException(spanError);
+        span.setStatus({
+          code: 2,
+          message: spanError instanceof Error ? spanError.message : String(spanError)
         });
-        if (attemptsMade > 1) {
-          throw new RetriesExhaustedError(attemptsMade, Date.now() - startedAt, lastError);
-        }
-        throw lastError;
+        throw spanError;
       } finally {
-        releaseMutationSlot();
+        span.end();
       }
     },
     runMutations: async (specs, ctx) => {
@@ -2713,6 +2801,43 @@ var createSyncEngine = (options = {}) => {
       version
     }),
     importChangeLog,
+    replayTo: async ({ at, tables }) => {
+      const filterTables = tables !== undefined ? new Set(tables) : undefined;
+      const state = new Map;
+      let asOfVersion = 0;
+      let asOfAt = 0;
+      const oldest = changeLog[0];
+      const truncated = oldest !== undefined && oldest.version > 1 && oldest.at > at;
+      for (const entry of changeLog) {
+        if (entry.at > at)
+          break;
+        if (filterTables !== undefined && !filterTables.has(entry.table)) {
+          continue;
+        }
+        let tableState = state.get(entry.table);
+        if (tableState === undefined) {
+          tableState = new Map;
+          state.set(entry.table, tableState);
+        }
+        const reader = readers.get(entry.table);
+        const key = reader?.key?.(entry.change.row) ?? entry.change.row?.id;
+        if (key === undefined) {
+          continue;
+        }
+        if (entry.change.op === "delete") {
+          tableState.delete(key);
+        } else {
+          tableState.set(key, entry.change.row);
+        }
+        asOfVersion = entry.version;
+        asOfAt = entry.at;
+      }
+      const rows = {};
+      for (const [table, map] of state) {
+        rows[table] = [...map.values()];
+      }
+      return { asOfAt, asOfVersion, rows, truncated };
+    },
     metrics: () => {
       const now = Date.now();
       const byCollection = {};
@@ -3130,5 +3255,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=27A5DE0DF43D569D64756E2164756E21
+//# debugId=6DBA546C7A7B1DC564756E2164756E21
 //# sourceMappingURL=index.js.map