@absolutejs/sync 1.20.0 → 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';
@@ -425,6 +426,18 @@ export declare class MutationQueueOverflowError extends Error {
     readonly queueLimit: number;
     constructor(queueLimit: number);
 }
+/**
+ * Thrown by `engine.subscribe` when the calling tenant's active-subscription
+ * count is already at the configured `subscriptionLimit.max`. The caller sees
+ * this immediately — BEFORE authorize, hydrate, or any subscription state
+ * allocation — so a rejected call leaks nothing. Added in 1.20.1.
+ */
+export declare class SubscriptionLimitError extends Error {
+    readonly tenantKey: string;
+    readonly limit: number;
+    readonly active: number;
+    constructor(tenantKey: string, limit: number, active: number);
+}
 /**
  * Serializable snapshot of an engine's change log + monotonic version, returned
  * by {@link SyncEngine.exportChangeLog} and consumed by
@@ -597,6 +610,51 @@ export type SyncEngineOptions = {
      * Added in 1.20.0.
      */
     mutationQueueLimit?: number;
+    /**
+     * Per-tenant active-subscription cap. Symmetric to
+     * {@link SyncEngineOptions.mutationConcurrency} on the read side: a
+     * single tenant opening thousands of subscriptions would otherwise
+     * exhaust the engine's per-subscription bookkeeping
+     * (`active`/`tableIndex` Maps, the reactive cache, per-row diff
+     * computation cost).
+     *
+     * `key` derives a tenant identifier from `(ctx, args)`; returning
+     * `undefined` skips the cap for that call (e.g. internal/system
+     * subscriptions). When the active count for a key reaches `max`, the
+     * next `subscribe` throws {@link SubscriptionLimitError} BEFORE any
+     * authorize, hydrate, or state allocation — so a denied call leaks
+     * nothing.
+     *
+     * Active counts are surfaced through `engine.metrics().subscriptions.byTenant`
+     * for tier monitoring. Added in 1.20.1.
+     */
+    subscriptionLimit?: {
+        max: number;
+        key: (ctx: unknown, args: {
+            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) {
@@ -1161,6 +1214,19 @@ class MutationQueueOverflowError extends Error {
     this.queueLimit = queueLimit;
   }
 }
+
+class SubscriptionLimitError extends Error {
+  tenantKey;
+  limit;
+  active;
+  constructor(tenantKey, limit, active) {
+    super(`Tenant "${tenantKey}" is at the subscription cap ` + `(${active}/${limit}). Close an existing subscription before opening another.`);
+    this.name = "SubscriptionLimitError";
+    this.tenantKey = tenantKey;
+    this.limit = limit;
+    this.active = active;
+  }
+}
 var defaultKey = (row) => row.id;
 var shallowEqual3 = (a, b) => {
   if (a === b) {
@@ -1311,6 +1377,31 @@ var createSyncEngine = (options = {}) => {
     if (next !== undefined)
       next();
   };
+  const subscriptionsByTenant = new Map;
+  const acquireSubscriptionSlot = (ctx, args) => {
+    const cap = options.subscriptionLimit;
+    if (cap === undefined)
+      return;
+    const tenantKey = cap.key(ctx, args);
+    if (tenantKey === undefined)
+      return;
+    const active2 = subscriptionsByTenant.get(tenantKey) ?? 0;
+    if (active2 >= cap.max) {
+      throw new SubscriptionLimitError(tenantKey, cap.max, active2);
+    }
+    subscriptionsByTenant.set(tenantKey, active2 + 1);
+    return tenantKey;
+  };
+  const releaseSubscriptionSlot = (tenantKey) => {
+    if (tenantKey === undefined)
+      return;
+    const active2 = subscriptionsByTenant.get(tenantKey);
+    if (active2 === undefined || active2 <= 1) {
+      subscriptionsByTenant.delete(tenantKey);
+    } else {
+      subscriptionsByTenant.set(tenantKey, active2 - 1);
+    }
+  };
   const reactiveCacheMax = options.reactiveCache?.max ?? 256;
   const reactiveCacheTtlMs = options.reactiveCache?.ttlMs ?? 60000;
   const cachedReruns = new Map;
@@ -1352,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.`);
@@ -2143,89 +2235,125 @@ 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 typedOnDiff = onDiff;
-      const subscribeSet = subsFor(collection);
-      const wrapReturn = (sub) => {
-        checkAborted(signal);
-        linkAbortToUnsubscribe(signal, sub.unsubscribe);
-        return sub;
-      };
-      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 subscribeSpan = tracer.startSpan("sync.subscribe", {
+        attributes: {
+          [ABS_ATTRS.engineId]: instanceId,
+          [ABS_ATTRS.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
+      try {
+        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);
+          }
+          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
+            });
+          }
+          return wrapReturn({
+            initial: view.rows(),
+            cursor: currentCursor(),
+            version: atVersion,
+            unsubscribe
+          });
+        } catch (error) {
+          if (!slotHandedOff)
+            releaseSubscriptionSlot(tenantSlot);
+          throw error;
+        }
+      } catch (spanError) {
+        subscribeSpan.recordException(spanError);
+        subscribeSpan.setStatus({
+          code: 2,
+          message: spanError instanceof Error ? spanError.message : String(spanError)
         });
+        throw spanError;
+      } finally {
+        subscribeSpan.end();
       }
-      return wrapReturn({
-        initial: view.rows(),
-        cursor: currentCursor(),
-        version: atVersion,
-        unsubscribe
-      });
     },
     hydrate: async (collection, params, ctx, options2) => {
       const signal = options2?.signal;
@@ -2328,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) => {
@@ -2690,6 +2835,7 @@ var createSyncEngine = (options = {}) => {
         },
         subscriptions: {
           byCollection,
+          byTenant: Object.fromEntries(subscriptionsByTenant),
           total: totalSubscriptions
         },
         uptimeMs: now - engineStartedAt,
@@ -3072,5 +3218,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=9DD57DF563EB9CB564756E2164756E21
+//# debugId=06ECBF0C02EA0B8464756E2164756E21
 //# sourceMappingURL=index.js.map