@absolutejs/sync 1.19.0 → 1.20.1

package/dist/engine/devtools.d.ts

@@ -82,6 +82,14 @@ export type EngineMetrics = {
         total: number;
         /** Per-collection breakdown — the values sum to `total`. */
         byCollection: Record<string, number>;
+        /**
+         * Per-tenant tally — populated only when
+         * `SyncEngineOptions.subscriptionLimit` is set; otherwise `{}`. The
+         * key is whatever `subscriptionLimit.key(ctx, args)` returns; the
+         * value is the count of active subscriptions for that key. Added
+         * in 1.20.1.
+         */
+        byTenant: Record<string, number>;
     };
     reactiveCache: {
         entries: number;
@@ -96,6 +104,11 @@ export type EngineMetrics = {
         retried: number;
         /** Currently running, not yet committed or failed. */
         inFlight: number;
+        /**
+         * Waiting in the `mutationConcurrency` queue. Always `0` when
+         * `mutationConcurrency` is unset (no semaphore). Added in 1.20.0.
+         */
+        queued: number;
     };
     schedules: {
         registered: number;

package/dist/engine/index.d.ts

@@ -47,8 +47,8 @@ export type { MutationActions, MutationDefinition, MutationHandler, TableWriter,
 export type { BridgeFetchConfig, BridgeFetchEndpoint, BridgeFetchResponse, HandlerMetricsHook, HandlerMetricsRecord, SandboxConfig } from './sandbox';
 export { exponentialBackoff, isSerializationFailure, RetriesExhaustedError } from './retry';
 export type { ExponentialBackoffOptions, RetryPolicy } from './retry';
-export { CdcConsumerSlowError, createSyncEngine, MissedChangesError, SchemaError, UnauthorizedError } from './syncEngine';
-export type { CrdtFields, LoggedChange, StreamChangesOptions, SubscribeArgs, Subscription, SyncEngine } from './syncEngine';
+export { CdcConsumerSlowError, createSyncEngine, MissedChangesError, MutationQueueOverflowError, SchemaError, SubscriptionLimitError, UnauthorizedError } from './syncEngine';
+export type { ChangeLogSnapshot, CrdtFields, LoggedChange, StreamChangesOptions, SubscribeArgs, Subscription, SyncEngine, SyncEngineOptions } from './syncEngine';
 export { syncCdc } from './cdc';
 export type { SyncCdcOptions } from './cdc';
 export type { CrdtMergeable } from '../crdt';

package/dist/engine/index.js

@@ -1410,6 +1410,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 shallowEqual4 = (a, b) => {
   if (a === b) {
@@ -1526,6 +1548,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;
@@ -2363,84 +2444,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;
@@ -2553,6 +2653,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) => {
@@ -2568,7 +2669,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;
@@ -2621,7 +2721,7 @@ var createSyncEngine = (options = {}) => {
         }
         throw lastError;
       } finally {
-        mutationsInFlight -= 1;
+        releaseMutationSlot();
       }
     },
     runMutations: async (specs, ctx) => {
@@ -2634,6 +2734,7 @@ var createSyncEngine = (options = {}) => {
         }
         return { args: spec.args, mutation, name: spec.name };
       });
+      await acquireMutationSlot();
       const runBatch = async (tx) => {
         const results = [];
         const accumulated = [];
@@ -2671,6 +2772,8 @@ var createSyncEngine = (options = {}) => {
           status: "error"
         });
         throw error;
+      } finally {
+        releaseMutationSlot();
       }
     },
     registerSchedule: (schedule) => {
@@ -2890,6 +2993,7 @@ var createSyncEngine = (options = {}) => {
           completed: mutationsCompleted,
           failed: mutationsFailed,
           inFlight: mutationsInFlight,
+          queued: mutationsQueued,
           retried: mutationsRetried
         },
         reactiveCache: {
@@ -2901,6 +3005,7 @@ var createSyncEngine = (options = {}) => {
         },
         subscriptions: {
           byCollection,
+          byTenant: Object.fromEntries(subscriptionsByTenant),
           total: totalSubscriptions
         },
         uptimeMs: now - engineStartedAt,
@@ -3429,14 +3534,16 @@ export {
   chain,
   aggregateOp,
   UnauthorizedError,
+  SubscriptionLimitError,
   SchemaError,
   SEARCH_SCORE_FIELD,
   RetriesExhaustedError,
   PackTableConflictError,
   PackMissingDependencyError,
+  MutationQueueOverflowError,
   MissedChangesError,
   CdcConsumerSlowError
 };
 
-//# debugId=079CCC84C9743C1064756E2164756E21
+//# debugId=251EC576E67A0CAF64756E2164756E21
 //# sourceMappingURL=index.js.map