@absolutejs/sync 1.19.0 → 1.20.1

package/dist/engine/syncEngine.d.ts

@@ -414,6 +414,29 @@ export declare class CdcConsumerSlowError extends Error {
     readonly lastDeliveredVersion: number;
     constructor(maxBuffer: number, lastDeliveredVersion: number);
 }
+/**
+ * Thrown by `runMutation` / `runMutations` when `mutationConcurrency` is
+ * saturated AND the waiting queue is already at `mutationQueueLimit`. The
+ * caller sees this immediately (no queue time) so the host can shed load
+ * with a clean 429 instead of letting the queue grow unboundedly. Added
+ * in 1.20.0.
+ */
+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
@@ -557,6 +580,59 @@ export type SyncEngineOptions = {
      * `createSyncEngine` returns. Added in 1.19.0.
      */
     initialChangeLog?: ChangeLogSnapshot;
+    /**
+     * Maximum concurrent in-flight mutations (`runMutation` + `runMutations`).
+     * Calls beyond the limit wait in a FIFO queue and run as slots free up;
+     * `engine.metrics().mutations.queued` surfaces the queue depth.
+     *
+     * A single tenant flooding `runMutation` can otherwise drive unbounded
+     * memory growth (per-mutation `actions` buffers, retry timers, sandbox
+     * invocations queued against the isolate pool). Set this to a value
+     * appropriate for the host's tenant tier — e.g. `32` for a free tier,
+     * `256` for paid. Without this option the engine is unbounded
+     * (matching pre-1.20 behavior).
+     *
+     * Sandboxed mutations are gated by the same semaphore. If you need
+     * finer-grained control (sandbox-only throttling), see
+     * `@absolutejs/isolated-jsc`'s pool size — that's the lower layer.
+     *
+     * Added in 1.20.0.
+     */
+    mutationConcurrency?: number;
+    /**
+     * Cap on the queue of waiting mutations once `mutationConcurrency` is
+     * saturated. Calls beyond this cap throw {@link MutationQueueOverflowError}
+     * immediately instead of queueing — the host can surface a clean 429 or
+     * apply a tenant-specific shed policy. Defaults to unbounded (queue
+     * never rejects). Only meaningful when `mutationConcurrency` is set.
+     *
+     * 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;
+    };
 };
 /**
  * The Tier 3 sync engine: a registry of collections plus the view syncer. It is

package/dist/index.js

@@ -1152,6 +1152,28 @@ class CdcConsumerSlowError extends Error {
     this.lastDeliveredVersion = lastDeliveredVersion;
   }
 }
+
+class MutationQueueOverflowError extends Error {
+  queueLimit;
+  constructor(queueLimit) {
+    super(`Mutation queue overflowed (limit ${queueLimit}); the engine is at ` + `its mutationConcurrency cap and the waiting queue is full. ` + `Retry later or shed load at the gateway.`);
+    this.name = "MutationQueueOverflowError";
+    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) {
@@ -1268,6 +1290,65 @@ var createSyncEngine = (options = {}) => {
   let mutationsFailed = 0;
   let mutationsRetried = 0;
   let mutationsInFlight = 0;
+  const mutationWaiters = [];
+  let mutationsQueued = 0;
+  const acquireMutationSlot = async () => {
+    const limit = options.mutationConcurrency;
+    if (limit === undefined) {
+      mutationsInFlight += 1;
+      return;
+    }
+    if (mutationsInFlight < limit && mutationWaiters.length === 0) {
+      mutationsInFlight += 1;
+      return;
+    }
+    const queueLimit = options.mutationQueueLimit;
+    if (queueLimit !== undefined && mutationsQueued >= queueLimit) {
+      throw new MutationQueueOverflowError(queueLimit);
+    }
+    mutationsQueued += 1;
+    try {
+      await new Promise((resolve) => {
+        mutationWaiters.push(resolve);
+      });
+    } finally {
+      mutationsQueued -= 1;
+    }
+    mutationsInFlight += 1;
+  };
+  const releaseMutationSlot = () => {
+    mutationsInFlight -= 1;
+    if (options.mutationConcurrency === undefined)
+      return;
+    const next = mutationWaiters.shift();
+    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;
@@ -2105,84 +2186,103 @@ var createSyncEngine = (options = {}) => {
       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 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
-      });
     },
     hydrate: async (collection, params, ctx, options2) => {
       const signal = options2?.signal;
@@ -2295,6 +2395,7 @@ var createSyncEngine = (options = {}) => {
           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) => {
@@ -2310,7 +2411,6 @@ var createSyncEngine = (options = {}) => {
       const startedAt = Date.now();
       let lastError;
       let attemptsMade = 0;
-      mutationsInFlight += 1;
       try {
         for (let attempt = 1;attempt <= maxAttempts; attempt++) {
           attemptsMade = attempt;
@@ -2363,7 +2463,7 @@ var createSyncEngine = (options = {}) => {
         }
         throw lastError;
       } finally {
-        mutationsInFlight -= 1;
+        releaseMutationSlot();
       }
     },
     runMutations: async (specs, ctx) => {
@@ -2376,6 +2476,7 @@ var createSyncEngine = (options = {}) => {
         }
         return { args: spec.args, mutation, name: spec.name };
       });
+      await acquireMutationSlot();
       const runBatch = async (tx) => {
         const results = [];
         const accumulated = [];
@@ -2413,6 +2514,8 @@ var createSyncEngine = (options = {}) => {
           status: "error"
         });
         throw error;
+      } finally {
+        releaseMutationSlot();
       }
     },
     registerSchedule: (schedule) => {
@@ -2632,6 +2735,7 @@ var createSyncEngine = (options = {}) => {
           completed: mutationsCompleted,
           failed: mutationsFailed,
           inFlight: mutationsInFlight,
+          queued: mutationsQueued,
           retried: mutationsRetried
         },
         reactiveCache: {
@@ -2643,6 +2747,7 @@ var createSyncEngine = (options = {}) => {
         },
         subscriptions: {
           byCollection,
+          byTenant: Object.fromEntries(subscriptionsByTenant),
           total: totalSubscriptions
         },
         uptimeMs: now - engineStartedAt,
@@ -3025,5 +3130,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=EB8C381967D0311A64756E2164756E21
+//# debugId=27A5DE0DF43D569D64756E2164756E21
 //# sourceMappingURL=index.js.map