@absolutejs/sync 1.20.1 → 1.21.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';
@@ -633,6 +634,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);
-        }
-        if (registeredKind === "graph") {
-          const graphed = await subscribeGraph(collection, registered, params, ctx, typedOnDiff, subscribeSet);
-          return wrapReturn(graphed);
+      const subscribeSpan = tracer.startSpan("sync.subscribe", {
+        attributes: {
+          [ABS_ATTRS.engineId]: instanceId,
+          [ABS_ATTRS.collection]: collection
         }
-        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) => {
@@ -3130,5 +3218,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=27A5DE0DF43D569D64756E2164756E21
+//# debugId=06ECBF0C02EA0B8464756E2164756E21
 //# sourceMappingURL=index.js.map