deepline 0.3.127 → 0.3.129

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/receipt-completion-coalescer.ts

@@ -0,0 +1,452 @@
+/**
+ * Gateway-side commit coalescing for runtime step receipt completions.
+ *
+ * A runner settles receipts continuously, so a Machine sees many small
+ * `complete_runtime_step_receipts` requests arrive within a few milliseconds of
+ * each other. Each one costs a heavy-admission slot, a pooled client, and its
+ * own storage statement, which is why the commit lane saturated long before
+ * Postgres did (measured: p50 1 ms / p99 66 ms per statement while the lane was
+ * the fleet-wide chokepoint).
+ *
+ * This Module holds concurrent requests for a short window and commits them as
+ * ONE storage statement under ONE slot, then hands each request exactly its own
+ * receipts' results, in its original order. It owns nothing else: the caller
+ * supplies the commit, which owns admission, the client, and the statement.
+ *
+ * Coalescing is only sound inside one commit key. The completion statement is
+ * org-scoped (`target.org_id = $6`) and schema-scoped by table name, and its
+ * response projection depends on the request's legacy wire format, so requests
+ * from different orgs, schemas, or wire formats are never merged. Run identity
+ * IS per input row in the statement, so requests from different runs of the
+ * same org share a statement safely.
+ *
+ * Windows are additionally split by payload size class. Merging is only worth
+ * doing between statements of comparable cost: folding a 9 KB batch into a
+ * window that is building a multi-megabyte statement makes the cheap batch wait
+ * for the expensive one to be built AND committed, which is the head-of-line
+ * blocking the size classes exist to remove. So a window's class is fixed when
+ * it opens, a light window a request would push over the threshold is committed
+ * before that request joins anything, and light and heavy windows of the same
+ * commit key are built and committed independently.
+ */
+
+import { BoundedBatchFunction } from '../bounded-batch-function';
+
+/** The gateway admission adapter owns how these two classes acquire capacity. */
+export type GatewayCommitSizeClass = 'light' | 'heavy';
+
+/**
+ * Window for gathering concurrent completion requests. A completion is already
+ * asynchronous relative to the row that produced it, so a short hold costs the
+ * runner nothing while turning a burst into a single statement. Keep it well
+ * below the runner's own completion window so the gateway never becomes the
+ * dominant term.
+ */
+export const RUNTIME_RECEIPT_GATEWAY_COMPLETION_COALESCE_MS = 20;
+
+/**
+ * Receipts one coalesced statement may carry.
+ *
+ * Mirrors the runner's `RUNTIME_STEP_RECEIPT_REQUEST_CHUNK_SIZE` (play-runtime
+ * `context.ts`), which already bounds a single completion request: one
+ * statement therefore never carries more than one runner request's worth of
+ * receipts, whatever the window collected. The coalescer test pins the two
+ * values together, since only the runner's constant is importable here without
+ * pulling the whole runtime into the gateway process.
+ */
+export const RUNTIME_RECEIPT_GATEWAY_COMPLETION_MAX_RECEIPTS = 1_000;
+
+/** Identity that must match for two requests to share one statement. */
+export type ReceiptCompletionCommitKey = {
+  orgId: string;
+  schema: string | null;
+  wireFormat: number;
+};
+
+export function receiptCompletionCommitKeyId(
+  key: ReceiptCompletionCommitKey,
+): string {
+  // Org ids and schema names never contain '|', so the id is unambiguous.
+  return `${key.orgId}|${key.schema ?? ''}|${key.wireFormat}`;
+}
+
+/**
+ * Identity of one open window: a commit key plus the size class of the
+ * statement it is building. Two windows of the same commit key but different
+ * size classes are legal and deliberate; each commits on its own.
+ */
+export function receiptCompletionWindowId(
+  key: ReceiptCompletionCommitKey,
+  sizeClass: GatewayCommitSizeClass,
+): string {
+  return `${receiptCompletionCommitKeyId(key)}|${sizeClass}`;
+}
+
+/** One committed statement, for the per-statement telemetry record. */
+export type ReceiptCompletionStatementRecord = {
+  key: ReceiptCompletionCommitKey;
+  /** Requests merged into this statement. */
+  requestCount: number;
+  /** Receipts across those requests. */
+  receiptCount: number;
+  /** Caller-estimated request bytes across those requests. */
+  bytes: number;
+  /**
+   * On-the-wire body bytes of the merged requests that carried these receipts.
+   *
+   * `bytes` is the DECODED size the statement is admitted and classified on;
+   * this is what the network actually moved. They are equal when the requests
+   * arrived uncompressed (the caller supplies no wire size and it defaults to
+   * `bytes`), and `wireBytes / bytes` is the compression ratio the transport
+   * achieved when they arrived gzipped. Admission never reads it: a compressed
+   * request costs the statement exactly as much decoded work as an
+   * uncompressed one, so shrinking the wire must not shrink the size class.
+   */
+  wireBytes: number;
+  /** Admission class this statement was committed under. */
+  sizeClass: GatewayCommitSizeClass;
+  /** Longest time any merged request waited before the statement started. */
+  waitMs: number;
+  /**
+   * Time the commit spent waiting for its admission slot, as reported by the
+   * commit itself. Zero when the caller's commit takes no admission.
+   */
+  admissionWaitMs: number;
+  /** Wall time of the commit itself, including admission and client acquire. */
+  statementMs: number;
+  outcome: 'committed' | 'failed';
+  errorType: string | null;
+  /**
+   * Per-run share of the statement, so a readout can attribute gateway bytes
+   * and statement time to the runs that produced them. One coalesced
+   * statement may carry several runs of one org; the list is bounded and
+   * `runCount` says how many runs the statement really carried.
+   */
+  runs: ReceiptCompletionRunShare[];
+  runCount: number;
+};
+
+export type ReceiptCompletionRunShare = {
+  runId: string;
+  /**
+   * Transport attempt ids of the requests this run contributed, so a readout
+   * can pair the gateway's statement timing with the runner's flight for
+   * the same batch.
+   */
+  transportAttemptIds: string[];
+  requestCount: number;
+  receiptCount: number;
+  bytes: number;
+  /** This run's share of the statement's on-the-wire body bytes. */
+  wireBytes: number;
+};
+
+/** Runs listed per committed statement; the rest are counted, not listed. */
+export const RUNTIME_RECEIPT_GATEWAY_COMMITTED_RUNS_MAX = 16;
+
+type PendingRequest<TReceipt> = {
+  receipts: readonly TReceipt[];
+  transportAttemptId: string | null;
+  bytes: number;
+  wireBytes: number;
+  enqueuedAt: number;
+};
+
+type ReceiptCompletionWindowKey = {
+  key: ReceiptCompletionCommitKey;
+  sizeClass: GatewayCommitSizeClass;
+};
+
+export class ReceiptCompletionResultCountError extends Error {
+  constructor(
+    readonly expected: number,
+    readonly received: number,
+  ) {
+    super(
+      `Coalesced receipt completion returned ${received} results for ${expected} receipts.`,
+    );
+    this.name = 'ReceiptCompletionResultCountError';
+  }
+}
+
+export class ReceiptCompletionCoalescer<TReceipt, TResult> {
+  readonly #commit: (input: {
+    key: ReceiptCompletionCommitKey;
+    receipts: TReceipt[];
+    sizeClass: GatewayCommitSizeClass;
+    bytes: number;
+    onAdmitted: () => void;
+  }) => Promise<TResult[]>;
+  readonly #lightMaxBytes: number;
+  readonly #onStatement:
+    | ((record: ReceiptCompletionStatementRecord) => void)
+    | null;
+  readonly #requestRunId:
+    | ((receipts: readonly TReceipt[]) => string | null)
+    | null;
+  readonly #now: () => number;
+  readonly #batches: BoundedBatchFunction<
+    PendingRequest<TReceipt>,
+    TResult[],
+    ReceiptCompletionWindowKey
+  >;
+
+  constructor(input: {
+    /**
+     * Commit these receipts as one statement. The caller owns heavy-request
+     * admission, the pooled client, and the storage call. Results MUST be
+     * index-aligned with the supplied receipts.
+     */
+    commit: (input: {
+      key: ReceiptCompletionCommitKey;
+      receipts: TReceipt[];
+      /** Admission class the caller must commit this statement under. */
+      sizeClass: GatewayCommitSizeClass;
+      /** Caller-estimated bytes of the merged statement. */
+      bytes: number;
+      /**
+       * Call once the commit holds its admission slot. Reports
+       * `admissionWaitMs` for this statement; a commit that takes no admission
+       * simply never calls it.
+       */
+      onAdmitted: () => void;
+    }) => Promise<TResult[]>;
+    /** Receipts one statement may carry; matches the runner's request chunk. */
+    maxReceipts: number;
+    /** Estimated request bytes one statement may carry. */
+    maxBytes: number;
+    /**
+     * Bytes at or above which a statement is heavy. A window stays strictly
+     * below this while it is light, so a light statement's cost stays bounded
+     * and its own admission lane keeps draining.
+     */
+    lightMaxBytes: number;
+    windowMs?: number;
+    onStatement?: (record: ReceiptCompletionStatementRecord) => void;
+    /**
+     * Run identity of one request's receipts (every request carries receipts
+     * of exactly one run). Without it statements record no run shares.
+     */
+    requestRunId?: (receipts: readonly TReceipt[]) => string | null;
+    now?: () => number;
+    /**
+     * Bounded retained requests across queued and active commit statements.
+     * Defaults keep four maximum receipt statements resident per Machine.
+     */
+    maxRetainedRequests?: number;
+    maxInFlightStatements?: number;
+  }) {
+    if (!Number.isSafeInteger(input.maxReceipts) || input.maxReceipts < 1) {
+      throw new Error(
+        'Receipt completion coalescer requires a positive maxReceipts.',
+      );
+    }
+    if (!Number.isSafeInteger(input.maxBytes) || input.maxBytes < 1) {
+      throw new Error(
+        'Receipt completion coalescer requires a positive maxBytes.',
+      );
+    }
+    if (!Number.isSafeInteger(input.lightMaxBytes) || input.lightMaxBytes < 1) {
+      throw new Error(
+        'Receipt completion coalescer requires a positive lightMaxBytes.',
+      );
+    }
+    this.#commit = input.commit;
+    this.#lightMaxBytes = input.lightMaxBytes;
+    this.#onStatement = input.onStatement ?? null;
+    this.#requestRunId = input.requestRunId ?? null;
+    this.#now = input.now ?? Date.now;
+    const maxRetainedRequests =
+      input.maxRetainedRequests ??
+      Math.max(input.maxReceipts, input.maxReceipts * 4);
+    const maxInFlightStatements = input.maxInFlightStatements ?? 4;
+    this.#batches = new BoundedBatchFunction({
+      keyId: (window) =>
+        receiptCompletionWindowId(window.key, window.sizeClass),
+      // `light` stays strictly below the heavy threshold. A request exactly at
+      // that threshold belongs to the heavy lane, matching the prior gateway
+      // coalescer contract.
+      maxBatchBytesForKey: (window) =>
+        window.sizeClass === 'light'
+          ? Math.max(1, input.lightMaxBytes - 1)
+          : input.maxBytes,
+      estimateBytes: (request) => request.bytes,
+      units: (request) => request.receipts.length,
+      maxBatchItems: input.maxReceipts,
+      maxBatchBytes: input.maxBytes,
+      maxBatchUnits: input.maxReceipts,
+      maxRetainedItems: maxRetainedRequests,
+      maxRetainedBytes: input.maxBytes * 4,
+      maxRetainedUnits: input.maxReceipts * 4,
+      maxOpenGroups: Math.min(maxRetainedRequests, 128),
+      maxInFlightBatches: maxInFlightStatements,
+      flushMs: input.windowMs ?? RUNTIME_RECEIPT_GATEWAY_COMPLETION_COALESCE_MS,
+      now: this.#now,
+      execute: async ({ key, values }) =>
+        await this.#commitRequests(key, values),
+    });
+  }
+
+  /**
+   * Submit one request's receipts. Resolves with exactly this request's
+   * results, in the order its receipts were supplied. A statement failure
+   * rejects every merged request with that same error, so each caller sees the
+   * response it would have seen alone and its own retry stays safe.
+   */
+  submit(input: {
+    key: ReceiptCompletionCommitKey;
+    receipts: readonly TReceipt[];
+    /** Caller-estimated request bytes, used only for the byte bound. */
+    bytes?: number;
+    /**
+     * On-the-wire body bytes of the request that carried these receipts.
+     * Telemetry only — it never affects the byte bound or the size class.
+     * Defaults to `bytes`, which is the truth for an uncompressed request.
+     */
+    wireBytes?: number;
+    /** Runner transport identity, used only for the bounded telemetry share. */
+    transportAttemptId?: string | null;
+  }): Promise<TResult[]> {
+    if (input.receipts.length === 0) return Promise.resolve([]);
+    const bytes = Math.max(0, Math.floor(input.bytes ?? 0));
+    const wireBytes = Math.max(0, Math.floor(input.wireBytes ?? bytes));
+    // A request that is already heavy on its own can never make a light
+    // statement, so it goes straight to a heavy window instead of closing the
+    // light one that other shapes are still filling.
+    const sizeClass: GatewayCommitSizeClass =
+      bytes >= this.#lightMaxBytes ? 'heavy' : 'light';
+    return this.#batches.submit({
+      key: { key: input.key, sizeClass },
+      value: {
+        receipts: input.receipts,
+        transportAttemptId: input.transportAttemptId ?? null,
+        bytes,
+        wireBytes,
+        enqueuedAt: this.#now(),
+      },
+    });
+  }
+
+  /** Commit every open window now and wait for all in-flight statements. */
+  async drain(): Promise<void> {
+    await this.#batches.drain();
+  }
+
+  async #commitRequests(
+    window: ReceiptCompletionWindowKey,
+    requests: readonly PendingRequest<TReceipt>[],
+  ): Promise<TResult[][]> {
+    const startedAt = this.#now();
+    const waitMs = requests.reduce(
+      (longest, request) =>
+        Math.max(longest, Math.max(0, startedAt - request.enqueuedAt)),
+      0,
+    );
+    const receipts = requests.flatMap((request) => [...request.receipts]);
+    let admissionWaitMs = 0;
+    const onAdmitted = () => {
+      admissionWaitMs = Math.max(0, this.#now() - startedAt);
+    };
+    const outcome: Pick<
+      ReceiptCompletionStatementRecord,
+      'waitMs' | 'admissionWaitMs' | 'statementMs' | 'outcome' | 'errorType'
+    > = {
+      waitMs,
+      admissionWaitMs,
+      statementMs: 0,
+      outcome: 'failed',
+      errorType: null,
+    };
+    try {
+      const results = await this.#commit({
+        key: window.key,
+        receipts,
+        sizeClass: window.sizeClass,
+        bytes: requests.reduce((total, request) => total + request.bytes, 0),
+        onAdmitted,
+      });
+      if (results.length !== receipts.length) {
+        throw new ReceiptCompletionResultCountError(
+          receipts.length,
+          results.length,
+        );
+      }
+      let offset = 0;
+      const requestResults: TResult[][] = [];
+      for (const request of requests) {
+        const slice = results.slice(offset, offset + request.receipts.length);
+        offset += request.receipts.length;
+        requestResults.push(slice);
+      }
+      outcome.admissionWaitMs = admissionWaitMs;
+      outcome.statementMs = this.#now() - startedAt;
+      outcome.outcome = 'committed';
+      this.#record(window, requests, outcome);
+      return requestResults;
+    } catch (error) {
+      outcome.admissionWaitMs = admissionWaitMs;
+      outcome.statementMs = this.#now() - startedAt;
+      outcome.errorType = error instanceof Error ? error.name : typeof error;
+      this.#record(window, requests, outcome);
+      throw error;
+    }
+  }
+
+  #record(
+    window: ReceiptCompletionWindowKey,
+    requests: readonly PendingRequest<TReceipt>[],
+    outcome: Pick<
+      ReceiptCompletionStatementRecord,
+      'waitMs' | 'admissionWaitMs' | 'statementMs' | 'outcome' | 'errorType'
+    >,
+  ): void {
+    if (!this.#onStatement) return;
+    try {
+      const shares = new Map<string, ReceiptCompletionRunShare>();
+      if (this.#requestRunId) {
+        for (const request of requests) {
+          const runId = this.#requestRunId(request.receipts);
+          if (!runId) continue;
+          const share = shares.get(runId) ?? {
+            runId,
+            transportAttemptIds: [],
+            requestCount: 0,
+            receiptCount: 0,
+            bytes: 0,
+            wireBytes: 0,
+          };
+          share.requestCount += 1;
+          if (request.transportAttemptId) {
+            share.transportAttemptIds.push(request.transportAttemptId);
+          }
+          share.receiptCount += request.receipts.length;
+          share.bytes += request.bytes;
+          share.wireBytes += request.wireBytes;
+          shares.set(runId, share);
+        }
+      }
+      this.#onStatement({
+        key: window.key,
+        requestCount: requests.length,
+        receiptCount: requests.reduce(
+          (total, request) => total + request.receipts.length,
+          0,
+        ),
+        bytes: requests.reduce((total, request) => total + request.bytes, 0),
+        wireBytes: requests.reduce(
+          (total, request) => total + request.wireBytes,
+          0,
+        ),
+        sizeClass: window.sizeClass,
+        runs: [...shares.values()].slice(
+          0,
+          RUNTIME_RECEIPT_GATEWAY_COMMITTED_RUNS_MAX,
+        ),
+        runCount: shares.size,
+        ...outcome,
+      });
+    } catch {
+      // Telemetry must never affect durable delivery.
+    }
+  }
+}