deepline 0.3.128 → 0.3.129

package/dist/bundling-sources/shared_libs/play-runtime/bounded-batch-function.ts

@@ -0,0 +1,682 @@
+/**
+ * A small, host-neutral batching primitive for ordinary async code.
+ *
+ * `submit()` returns one promise per value. Compatible values share one call to
+ * `execute()`, whose result positions settle the original promises. The
+ * primitive deliberately owns only bounded grouping, timing, cancellation, and
+ * result correlation. Durable identity, admission, retries, and persistence
+ * remain with the caller's executor, where their domain-specific semantics
+ * already live.
+ *
+ * Every input is counted from acceptance until its physical batch settles,
+ * including inputs already handed to `execute()`. That makes the configured
+ * retained item/byte/unit budgets a real memory bound rather than a queue-only
+ * illusion. A full budget rejects before retaining another closure or input;
+ * there is no hidden unbounded waiter list.
+ */
+
+type PendingState = 'queued' | 'ready' | 'active' | 'settled';
+
+type Pending<Value, Result, Key> = {
+  key: Key;
+  keyId: string;
+  value: Value;
+  bytes: number;
+  units: number;
+  enqueuedAt: number;
+  deadlineAt: number | null;
+  signal: AbortSignal | null;
+  onAbort: (() => void) | null;
+  state: PendingState;
+  settled: boolean;
+  resolve: (result: Result) => void;
+  reject: (error: unknown) => void;
+};
+
+type OpenGroup<Value, Result, Key> = {
+  key: Key;
+  keyId: string;
+  items: Array<Pending<Value, Result, Key>>;
+  bytes: number;
+  units: number;
+  timer: ReturnType<typeof setTimeout> | null;
+};
+
+type ReadyBatch<Value, Result, Key> = Omit<
+  OpenGroup<Value, Result, Key>,
+  'timer'
+>;
+
+export class BoundedBatchInputTooLargeError extends Error {
+  constructor(
+    readonly bytes: number,
+    readonly units: number,
+    readonly maxBatchBytes: number,
+    readonly maxBatchUnits: number,
+  ) {
+    super(
+      `Batch input exceeds one physical batch (bytes ${bytes}/${maxBatchBytes}, units ${units}/${maxBatchUnits}).`,
+    );
+    this.name = 'BoundedBatchInputTooLargeError';
+  }
+}
+
+export class BoundedBatchCapacityError extends Error {
+  constructor(
+    readonly limit: 'items' | 'bytes' | 'units' | 'groups',
+    readonly current: number,
+    readonly maximum: number,
+  ) {
+    super(
+      `Bounded batch ${limit} capacity is full (${current}/${maximum}); retry after a physical batch settles.`,
+    );
+    this.name = 'BoundedBatchCapacityError';
+  }
+}
+
+export class BoundedBatchDeadlineError extends Error {
+  constructor(readonly waitedMs: number) {
+    super(`Bounded batch item exceeded its ${waitedMs}ms queue deadline.`);
+    this.name = 'BoundedBatchDeadlineError';
+  }
+}
+
+export class BoundedBatchResultCountError extends Error {
+  constructor(
+    readonly expected: number,
+    readonly received: number,
+  ) {
+    super(
+      `Bounded batch executor returned ${received} results for ${expected} inputs.`,
+    );
+    this.name = 'BoundedBatchResultCountError';
+  }
+}
+
+export class BoundedBatchClosedError extends Error {
+  constructor() {
+    super('Bounded batch function is closed.');
+    this.name = 'BoundedBatchClosedError';
+  }
+}
+
+export type BoundedBatchStats = {
+  openGroups: number;
+  readyBatches: number;
+  queuedItems: number;
+  activeItems: number;
+  inFlightBatches: number;
+  retainedItems: number;
+  retainedBytes: number;
+  retainedUnits: number;
+};
+
+function positiveInteger(value: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error(`Bounded batch requires ${name} to be a positive integer.`);
+  }
+  return value;
+}
+
+function nonNegativeInteger(value: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error(
+      `Bounded batch requires ${name} to be a non-negative safe integer.`,
+    );
+  }
+  return value;
+}
+
+function abortReason(signal: AbortSignal): unknown {
+  return (
+    signal.reason ??
+    new DOMException('The operation was aborted.', 'AbortError')
+  );
+}
+
+/**
+ * Batch compatible ordinary async function calls under one explicit resource
+ * budget. `keyId` must represent every fact that makes a shared execution
+ * unsafe (tenant, auth, wire format, provider policy, and so on).
+ */
+export class BoundedBatchFunction<Value, Result, Key> {
+  readonly #execute: (input: {
+    key: Key;
+    values: readonly Value[];
+    signal: AbortSignal;
+  }) => Promise<readonly Result[]>;
+  readonly #keyId: (key: Key) => string;
+  readonly #estimateBytes: (value: Value) => number;
+  readonly #units: (value: Value) => number;
+  readonly #maxBatchItems: number;
+  readonly #maxBatchBytes: number;
+  readonly #maxBatchBytesForKey: (key: Key) => number;
+  readonly #maxBatchUnits: number;
+  readonly #maxRetainedItems: number;
+  readonly #maxRetainedBytes: number;
+  readonly #maxRetainedUnits: number;
+  readonly #maxOpenGroups: number;
+  readonly #maxInFlightBatches: number;
+  readonly #flushMs: number;
+  readonly #now: () => number;
+  readonly #closedController = new AbortController();
+  readonly #groups = new Map<string, OpenGroup<Value, Result, Key>>();
+  readonly #ready: Array<ReadyBatch<Value, Result, Key>> = [];
+  readonly #inFlight = new Set<Promise<void>>();
+  #deadlineTimer: ReturnType<typeof setTimeout> | null = null;
+  #closed = false;
+  #closeReason: unknown = null;
+  #retainedItems = 0;
+  #retainedBytes = 0;
+  #retainedUnits = 0;
+  #activeItems = 0;
+
+  constructor(input: {
+    keyId: (key: Key) => string;
+    execute: (input: {
+      key: Key;
+      values: readonly Value[];
+      signal: AbortSignal;
+    }) => Promise<readonly Result[]>;
+    estimateBytes?: (value: Value) => number;
+    units?: (value: Value) => number;
+    maxBatchItems: number;
+    maxBatchBytes: number;
+    /** Optional compatibility-key-specific physical byte ceiling. */
+    maxBatchBytesForKey?: (key: Key) => number;
+    maxBatchUnits?: number;
+    maxRetainedItems: number;
+    maxRetainedBytes: number;
+    maxRetainedUnits?: number;
+    maxOpenGroups?: number;
+    maxInFlightBatches?: number;
+    flushMs?: number;
+    now?: () => number;
+  }) {
+    this.#keyId = input.keyId;
+    this.#execute = input.execute;
+    this.#estimateBytes = input.estimateBytes ?? (() => 0);
+    this.#units = input.units ?? (() => 1);
+    this.#maxBatchItems = positiveInteger(input.maxBatchItems, 'maxBatchItems');
+    this.#maxBatchBytes = positiveInteger(input.maxBatchBytes, 'maxBatchBytes');
+    this.#maxBatchBytesForKey =
+      input.maxBatchBytesForKey ?? (() => this.#maxBatchBytes);
+    this.#maxBatchUnits = positiveInteger(
+      input.maxBatchUnits ?? input.maxBatchItems,
+      'maxBatchUnits',
+    );
+    this.#maxRetainedItems = positiveInteger(
+      input.maxRetainedItems,
+      'maxRetainedItems',
+    );
+    this.#maxRetainedBytes = positiveInteger(
+      input.maxRetainedBytes,
+      'maxRetainedBytes',
+    );
+    this.#maxRetainedUnits = positiveInteger(
+      input.maxRetainedUnits ?? input.maxRetainedItems,
+      'maxRetainedUnits',
+    );
+    this.#maxOpenGroups = positiveInteger(
+      input.maxOpenGroups ?? input.maxRetainedItems,
+      'maxOpenGroups',
+    );
+    this.#maxInFlightBatches = positiveInteger(
+      input.maxInFlightBatches ?? 1,
+      'maxInFlightBatches',
+    );
+    this.#flushMs = Math.max(0, Math.floor(input.flushMs ?? 0));
+    this.#now = input.now ?? Date.now;
+  }
+
+  /**
+   * Submit one logical value. `maxWaitMs` applies only before the physical
+   * call starts; after dispatch an individual caller may abort its wait but
+   * cannot cancel shared work that can still settle sibling callers safely.
+   */
+  submit(input: {
+    key: Key;
+    value: Value;
+    signal?: AbortSignal;
+    maxWaitMs?: number;
+  }): Promise<Result> {
+    if (this.#closed) {
+      return Promise.reject(this.#closeReason ?? new BoundedBatchClosedError());
+    }
+    this.#expireQueued();
+    if (input.signal?.aborted) return Promise.reject(abortReason(input.signal));
+
+    const keyId = this.#keyId(input.key);
+    if (!keyId) {
+      return Promise.reject(
+        new Error('Bounded batch keyId must not be empty.'),
+      );
+    }
+    const bytes = nonNegativeInteger(
+      Math.ceil(this.#estimateBytes(input.value)),
+      'estimated input bytes',
+    );
+    const units = positiveInteger(this.#units(input.value), 'input units');
+    const maxBatchBytes = positiveInteger(
+      this.#maxBatchBytesForKey(input.key),
+      'maxBatchBytesForKey result',
+    );
+    if (maxBatchBytes > this.#maxBatchBytes) {
+      return Promise.reject(
+        new Error(
+          'Bounded batch key-specific byte limit exceeds maxBatchBytes.',
+        ),
+      );
+    }
+    if (bytes > maxBatchBytes || units > this.#maxBatchUnits) {
+      return Promise.reject(
+        new BoundedBatchInputTooLargeError(
+          bytes,
+          units,
+          maxBatchBytes,
+          this.#maxBatchUnits,
+        ),
+      );
+    }
+    if (this.#retainedItems >= this.#maxRetainedItems) {
+      return Promise.reject(
+        new BoundedBatchCapacityError(
+          'items',
+          this.#retainedItems,
+          this.#maxRetainedItems,
+        ),
+      );
+    }
+    if (this.#retainedBytes + bytes > this.#maxRetainedBytes) {
+      return Promise.reject(
+        new BoundedBatchCapacityError(
+          'bytes',
+          this.#retainedBytes,
+          this.#maxRetainedBytes,
+        ),
+      );
+    }
+    if (this.#retainedUnits + units > this.#maxRetainedUnits) {
+      return Promise.reject(
+        new BoundedBatchCapacityError(
+          'units',
+          this.#retainedUnits,
+          this.#maxRetainedUnits,
+        ),
+      );
+    }
+
+    const existing = this.#groups.get(keyId);
+    if (!existing && this.#groups.size >= this.#maxOpenGroups) {
+      return Promise.reject(
+        new BoundedBatchCapacityError(
+          'groups',
+          this.#groups.size,
+          this.#maxOpenGroups,
+        ),
+      );
+    }
+
+    const maxWaitMs =
+      input.maxWaitMs === undefined
+        ? null
+        : nonNegativeInteger(Math.floor(input.maxWaitMs), 'maxWaitMs');
+    const now = this.#now();
+    return new Promise<Result>((resolve, reject) => {
+      const pending: Pending<Value, Result, Key> = {
+        key: input.key,
+        keyId,
+        value: input.value,
+        bytes,
+        units,
+        enqueuedAt: now,
+        deadlineAt: maxWaitMs === null ? null : now + maxWaitMs,
+        signal: input.signal ?? null,
+        onAbort: null,
+        state: 'queued',
+        settled: false,
+        resolve,
+        reject,
+      };
+      pending.onAbort = () => this.#abortPending(pending);
+      pending.signal?.addEventListener('abort', pending.onAbort, {
+        once: true,
+      });
+
+      // Seal before accepting the new value: a batch is never allowed to grow
+      // past a physical bound while the next compatible value waits behind it.
+      const open = this.#groups.get(keyId);
+      if (
+        open &&
+        (open.items.length >= this.#maxBatchItems ||
+          open.bytes + bytes > maxBatchBytes ||
+          open.units + units > this.#maxBatchUnits)
+      ) {
+        this.#sealGroup(keyId);
+      }
+      const group = this.#groups.get(keyId) ?? {
+        key: input.key,
+        keyId,
+        items: [],
+        bytes: 0,
+        units: 0,
+        timer: null,
+      };
+      group.items.push(pending);
+      group.bytes += bytes;
+      group.units += units;
+      this.#groups.set(keyId, group);
+      this.#retain(pending);
+
+      if (
+        group.items.length >= this.#maxBatchItems ||
+        group.bytes >= maxBatchBytes ||
+        group.units >= this.#maxBatchUnits
+      ) {
+        this.#sealGroup(keyId);
+      } else {
+        this.#scheduleGroupFlush(group);
+      }
+      this.#scheduleDeadlineTimer();
+      this.#pump();
+    });
+  }
+
+  /** Seal every open window and wait until all physical calls settle. */
+  async drain(): Promise<void> {
+    for (const keyId of [...this.#groups.keys()]) this.#sealGroup(keyId);
+    this.#pump();
+    while (this.#ready.length > 0 || this.#inFlight.size > 0) {
+      if (this.#inFlight.size === 0) {
+        this.#pump();
+        continue;
+      }
+      await Promise.allSettled([...this.#inFlight]);
+      this.#pump();
+    }
+  }
+
+  /**
+   * A graceful close drains accepted work. A forced close rejects subscribers,
+   * aborts the executor signal, and still waits for it to release retained
+   * inputs before returning.
+   */
+  async close(reason?: unknown): Promise<void> {
+    if (!this.#closed) {
+      this.#closed = true;
+      this.#closeReason = reason ?? new BoundedBatchClosedError();
+      if (reason !== undefined) {
+        this.#closedController.abort(reason);
+        for (const group of this.#groups.values())
+          this.#rejectContainer(group, reason);
+        this.#groups.clear();
+        for (const batch of this.#ready) this.#rejectContainer(batch, reason);
+        this.#ready.length = 0;
+        this.#clearDeadlineTimer();
+      }
+    }
+    if (reason === undefined) {
+      await this.drain();
+      return;
+    }
+    while (this.#inFlight.size > 0) {
+      await Promise.allSettled([...this.#inFlight]);
+    }
+  }
+
+  getStats(): BoundedBatchStats {
+    const queuedItems =
+      [...this.#groups.values()].reduce(
+        (total, group) => total + group.items.length,
+        0,
+      ) + this.#ready.reduce((total, batch) => total + batch.items.length, 0);
+    return {
+      openGroups: this.#groups.size,
+      readyBatches: this.#ready.length,
+      queuedItems,
+      activeItems: this.#activeItems,
+      inFlightBatches: this.#inFlight.size,
+      retainedItems: this.#retainedItems,
+      retainedBytes: this.#retainedBytes,
+      retainedUnits: this.#retainedUnits,
+    };
+  }
+
+  #retain(pending: Pending<Value, Result, Key>): void {
+    this.#retainedItems += 1;
+    this.#retainedBytes += pending.bytes;
+    this.#retainedUnits += pending.units;
+  }
+
+  #release(pending: Pending<Value, Result, Key>): void {
+    this.#retainedItems -= 1;
+    this.#retainedBytes -= pending.bytes;
+    this.#retainedUnits -= pending.units;
+  }
+
+  #scheduleGroupFlush(group: OpenGroup<Value, Result, Key>): void {
+    if (group.timer !== null) return;
+    group.timer = setTimeout(() => {
+      group.timer = null;
+      this.#sealGroup(group.keyId);
+      this.#pump();
+    }, this.#flushMs);
+    group.timer.unref?.();
+  }
+
+  #sealGroup(keyId: string): void {
+    const group = this.#groups.get(keyId);
+    if (!group) return;
+    this.#groups.delete(keyId);
+    if (group.timer !== null) clearTimeout(group.timer);
+    group.timer = null;
+    if (group.items.length === 0) return;
+    for (const pending of group.items) pending.state = 'ready';
+    this.#ready.push({
+      key: group.key,
+      keyId: group.keyId,
+      items: group.items,
+      bytes: group.bytes,
+      units: group.units,
+    });
+    this.#scheduleDeadlineTimer();
+  }
+
+  #pump(): void {
+    this.#expireQueued();
+    while (
+      this.#ready.length > 0 &&
+      this.#inFlight.size < this.#maxInFlightBatches
+    ) {
+      const batch = this.#ready.shift()!;
+      const items = batch.items.filter((pending) => pending.state === 'ready');
+      if (items.length === 0) continue;
+      for (const pending of items) pending.state = 'active';
+      this.#activeItems += items.length;
+      const active = this.#runBatch({ ...batch, items }).finally(() => {
+        this.#inFlight.delete(active);
+        this.#pump();
+      });
+      this.#inFlight.add(active);
+    }
+    this.#scheduleDeadlineTimer();
+  }
+
+  async #runBatch(batch: ReadyBatch<Value, Result, Key>): Promise<void> {
+    try {
+      const results = await this.#execute({
+        key: batch.key,
+        values: batch.items.map((pending) => pending.value),
+        signal: this.#closedController.signal,
+      });
+      if (results.length !== batch.items.length) {
+        throw new BoundedBatchResultCountError(
+          batch.items.length,
+          results.length,
+        );
+      }
+      for (let index = 0; index < batch.items.length; index += 1) {
+        const pending = batch.items[index]!;
+        if (!pending.settled) {
+          pending.settled = true;
+          pending.resolve(results[index]!);
+        }
+      }
+    } catch (error) {
+      for (const pending of batch.items) {
+        if (!pending.settled) {
+          pending.settled = true;
+          pending.reject(error);
+        }
+      }
+    } finally {
+      for (const pending of batch.items) {
+        pending.state = 'settled';
+        pending.signal?.removeEventListener('abort', pending.onAbort!);
+        this.#release(pending);
+      }
+      this.#activeItems -= batch.items.length;
+    }
+  }
+
+  #abortPending(pending: Pending<Value, Result, Key>): void {
+    if (pending.settled) return;
+    const error = abortReason(pending.signal!);
+    if (pending.state === 'active') {
+      // The operation may own durable effects for sibling callers. Detach this
+      // subscriber only; retained input is released when the shared batch ends.
+      pending.settled = true;
+      pending.reject(error);
+      return;
+    }
+    if (pending.state === 'queued') {
+      const group = this.#groups.get(pending.keyId);
+      if (group) this.#removeQueued(group, pending, error);
+    } else if (pending.state === 'ready') {
+      const batch = this.#ready.find((candidate) =>
+        candidate.items.includes(pending),
+      );
+      if (batch) this.#removeQueued(batch, pending, error);
+    }
+    this.#scheduleDeadlineTimer();
+  }
+
+  #removeQueued(
+    container: OpenGroup<Value, Result, Key> | ReadyBatch<Value, Result, Key>,
+    pending: Pending<Value, Result, Key>,
+    error: unknown,
+  ): void {
+    const index = container.items.indexOf(pending);
+    if (index < 0 || pending.settled) return;
+    container.items.splice(index, 1);
+    container.bytes -= pending.bytes;
+    container.units -= pending.units;
+    pending.state = 'settled';
+    pending.settled = true;
+    pending.signal?.removeEventListener('abort', pending.onAbort!);
+    this.#release(pending);
+    pending.reject(error);
+    if (container.items.length === 0 && 'timer' in container) {
+      if (container.timer !== null) clearTimeout(container.timer);
+      this.#groups.delete(container.keyId);
+    } else if (container.items.length === 0) {
+      const readyIndex = this.#ready.indexOf(container);
+      if (readyIndex >= 0) this.#ready.splice(readyIndex, 1);
+    }
+  }
+
+  #rejectContainer(
+    container: OpenGroup<Value, Result, Key> | ReadyBatch<Value, Result, Key>,
+    error: unknown,
+  ): void {
+    for (const pending of [...container.items]) {
+      if (!pending.settled) {
+        pending.state = 'settled';
+        pending.settled = true;
+        pending.signal?.removeEventListener('abort', pending.onAbort!);
+        this.#release(pending);
+        pending.reject(error);
+      }
+    }
+    container.items.length = 0;
+    if ('timer' in container && container.timer !== null) {
+      clearTimeout(container.timer);
+      container.timer = null;
+    }
+  }
+
+  #expireQueued(): void {
+    const now = this.#now();
+    const expired = (pending: Pending<Value, Result, Key>) =>
+      pending.deadlineAt !== null && pending.deadlineAt <= now;
+    for (const group of this.#groups.values()) {
+      for (const pending of [...group.items]) {
+        if (expired(pending)) {
+          this.#removeQueued(
+            group,
+            pending,
+            new BoundedBatchDeadlineError(
+              Math.max(0, now - pending.enqueuedAt),
+            ),
+          );
+        }
+      }
+    }
+    for (const batch of this.#ready) {
+      for (const pending of [...batch.items]) {
+        if (expired(pending)) {
+          this.#removeQueued(
+            batch,
+            pending,
+            new BoundedBatchDeadlineError(
+              Math.max(0, now - pending.enqueuedAt),
+            ),
+          );
+        }
+      }
+    }
+    for (let index = this.#ready.length - 1; index >= 0; index -= 1) {
+      if (this.#ready[index]!.items.length === 0) this.#ready.splice(index, 1);
+    }
+  }
+
+  #scheduleDeadlineTimer(): void {
+    this.#clearDeadlineTimer();
+    let nearest: number | null = null;
+    for (const group of this.#groups.values()) {
+      for (const pending of group.items) {
+        if (pending.deadlineAt !== null) {
+          nearest =
+            nearest === null
+              ? pending.deadlineAt
+              : Math.min(nearest, pending.deadlineAt);
+        }
+      }
+    }
+    for (const batch of this.#ready) {
+      for (const pending of batch.items) {
+        if (pending.deadlineAt !== null) {
+          nearest =
+            nearest === null
+              ? pending.deadlineAt
+              : Math.min(nearest, pending.deadlineAt);
+        }
+      }
+    }
+    if (nearest === null) return;
+    this.#deadlineTimer = setTimeout(
+      () => {
+        this.#deadlineTimer = null;
+        this.#expireQueued();
+        this.#scheduleDeadlineTimer();
+      },
+      Math.max(0, nearest - this.#now()),
+    );
+    this.#deadlineTimer.unref?.();
+  }
+
+  #clearDeadlineTimer(): void {
+    if (this.#deadlineTimer !== null) clearTimeout(this.#deadlineTimer);
+    this.#deadlineTimer = null;
+  }
+}