deepline 0.1.243 → 0.1.245

package/dist/bundling-sources/shared_libs/play-runtime/governor/coordinator-rate-state-backend.ts

@@ -1,252 +0,0 @@
-import {
-  noopPacingPermit,
-  type PacingPermit,
-  type PacingRule,
-  type RateStateBackend,
-} from './rate-state-backend';
-
-/**
- * Distributed Rate State Backend for the `esm_workers` substrate.
- *
- * On Cloudflare a single play run fans child plays and map rows across many
- * V8 isolates, so the per-`(org, provider)` request window cannot be
- * process-local — each isolate would otherwise pace against its own private
- * counter and the org could blow past a provider's real limit by the number of
- * isolates. This backend makes the window GLOBAL by RPCing the coordinator
- * Durable Object addressed per bucket (`idFromName('rate:<orgId>:<provider>')`).
- * The DO is single-threaded, so it runs the same sliding-window algorithm as
- * `InMemoryRateStateBackend` correctly for all isolates at once.
- *
- * Latency: a full DO round-trip on every outbound tool call would tax the
- * hello-world latency baseline. Instead the backend LEASES SMALL PERMIT BLOCKS:
- * one `/rate-acquire` round-trip debits up to {@link LEASE_BLOCK_SIZE} permits
- * from the global window, and subsequent acquires draw from the local block
- * until it is exhausted or its rule-scoped TTL expires. This bounds round-trips
- * to roughly `calls / LEASE_BLOCK_SIZE` while keeping over-issuance bounded by
- * one block per isolate per window.
- *
- * Fail-open: if the coordinator is unreachable the backend logs once and
- * PROCEEDS (grants the permit) rather than stalling the run, matching the
- * semantics of `src/lib/redis/customer-rate-limiter.ts` — a degraded limiter
- * must never become an availability outage. The Governor's global
- * tool-concurrency semaphore remains the unconditional backstop.
- */
-
-/** Permits leased per round-trip. Tuned to amortize the DO hop, not to batch. */
-const LEASE_BLOCK_SIZE = 16;
-/**
- * Min/max age of a leased block. A leased permit debited the global window
- * already, but if it is held well past the provider window it could let an
- * isolate run ahead of a rolled-over window. The effective TTL is derived from
- * the shortest rule window so low-RPS pure-rate providers can draw already-
- * debited permits throughout a normal window instead of burning most blocks.
- */
-const LEASE_BLOCK_MIN_TTL_MS = 250;
-const LEASE_BLOCK_MAX_TTL_MS = 5_000;
-/** Cap one coordinator-provided sleep hint; total wait is bounded by run timeout. */
-const MAX_ACQUIRE_SLEEP_MS = 5_000;
-
-export interface CoordinatorRatePort {
-  /**
-   * Lease up to `requested` request-window permits for `bucketId` under all
-   * `rules` from the coordinator DO. Returns how many were `granted` (0 when the
-   * window is saturated) and a `waitMs` hint before retrying.
-   */
-  rateAcquire(input: {
-    bucketId: string;
-    rules: PacingRule[];
-    requested: number;
-  }): Promise<{ granted: number; waitMs: number }>;
-  /** Feed a Retry-After cooldown back into the global bucket. */
-  ratePenalize(input: { bucketId: string; cooldownMs: number }): Promise<void>;
-}
-
-interface LeasedBlock {
-  remaining: number;
-  expiresAt: number;
-  /** Stable signature of the rules this block was leased under. */
-  rulesKey: string;
-}
-
-interface Options {
-  now?: () => number;
-  sleep?: (ms: number) => Promise<void>;
-  onDegraded?: (info: { bucketId: string; error: string }) => void;
-}
-
-function rulesSignature(rules: readonly PacingRule[]): string {
-  return [...rules]
-    .map(
-      (rule) =>
-        `${rule.ruleId}:${rule.requestsPerWindow}:${rule.windowMs}:${rule.maxConcurrency ?? ''}`,
-    )
-    .sort()
-    .join('|');
-}
-
-export class CoordinatorRateStateBackend implements RateStateBackend {
-  private readonly port: CoordinatorRatePort;
-  private readonly now: () => number;
-  private readonly sleep: (ms: number) => Promise<void>;
-  private readonly onDegraded: (info: {
-    bucketId: string;
-    error: string;
-  }) => void;
-  private readonly blocks = new Map<string, LeasedBlock>();
-  private degradedLogged = false;
-
-  constructor(port: CoordinatorRatePort, options: Options = {}) {
-    this.port = port;
-    this.now = options.now ?? (() => Date.now());
-    this.sleep =
-      options.sleep ??
-      ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms)));
-    this.onDegraded =
-      options.onDegraded ??
-      ((info) => {
-        if (this.degradedLogged) return;
-        this.degradedLogged = true;
-        console.warn('[coordinator-rate-state] acquire failed open', info);
-      });
-  }
-
-  async acquire(input: {
-    bucketId: string;
-    rules: readonly PacingRule[];
-    signal?: AbortSignal;
-  }): Promise<PacingPermit> {
-    const { bucketId, rules, signal } = input;
-    if (rules.length === 0) {
-      return noopPacingPermit();
-    }
-    const rulesKey = rulesSignature(rules);
-
-    // Draw from a still-valid local block first — no round-trip.
-    if (this.drawFromBlock(bucketId, rulesKey)) {
-      return noopPacingPermit();
-    }
-
-    while (true) {
-      if (signal?.aborted) {
-        throw signal.reason instanceof Error
-          ? signal.reason
-          : new Error('Rate-state acquire aborted.');
-      }
-      let response: { granted: number; waitMs: number };
-      try {
-        response = await this.port.rateAcquire({
-          bucketId,
-          rules: [...rules],
-          requested: LEASE_BLOCK_SIZE,
-        });
-      } catch (error) {
-        // Fail open: a degraded coordinator must not stall the run.
-        this.onDegraded({
-          bucketId,
-          error: error instanceof Error ? error.message : String(error),
-        });
-        return noopPacingPermit();
-      }
-      if (response.granted > 0) {
-        // Consume one for this call; cache the rest as a short-lived block.
-        const remaining = response.granted - 1;
-        if (remaining > 0) {
-          this.mergeBlock(bucketId, remaining, rulesKey, rules);
-        }
-        return noopPacingPermit();
-      }
-      // Window saturated. Park for the hint, then re-acquire. This is not a
-      // degraded coordinator: the limiter answered and said "wait", so granting
-      // here would violate the provider request-rate contract. Overall wait is
-      // bounded by the play runtime deadline / abort signal.
-      const waitMs = Math.max(
-        1,
-        Math.min(response.waitMs, MAX_ACQUIRE_SLEEP_MS),
-      );
-      await this.sleep(waitMs);
-    }
-  }
-
-  async penalize(input: {
-    bucketId: string;
-    cooldownMs: number;
-  }): Promise<void> {
-    if (input.cooldownMs <= 0) return;
-    // Drop any cached block for this bucket so the cooldown takes effect on the
-    // very next acquire instead of being masked by already-leased permits.
-    this.blocks.delete(input.bucketId);
-    try {
-      await this.port.ratePenalize({
-        bucketId: input.bucketId,
-        cooldownMs: input.cooldownMs,
-      });
-    } catch (error) {
-      this.onDegraded({
-        bucketId: input.bucketId,
-        error: error instanceof Error ? error.message : String(error),
-      });
-      throw error;
-    }
-  }
-
-  /**
-   * Add freshly-leased permits to the bucket's block instead of overwriting it.
-   * Two concurrent acquires can both miss the local block and both round-trip;
-   * each debited the global window, so the DO already issued both blocks'
-   * permits. Overwriting would drop one set — under-issuance that wastes window
-   * capacity and over-throttles. Merging preserves every debited permit:
-   *  - same rulesKey + still valid → sum remaining, keep the earlier expiry so
-   *    the merged block never outlives the older lease's sub-window bound.
-   *  - missing / stale / different rules → start fresh from this lease.
-   */
-  private mergeBlock(
-    bucketId: string,
-    remaining: number,
-    rulesKey: string,
-    rules: readonly PacingRule[],
-  ): void {
-    const freshExpiresAt = this.now() + leasedBlockTtlMs(rules);
-    const existing = this.blocks.get(bucketId);
-    if (
-      existing &&
-      existing.rulesKey === rulesKey &&
-      existing.expiresAt > this.now()
-    ) {
-      existing.remaining += remaining;
-      existing.expiresAt = Math.min(existing.expiresAt, freshExpiresAt);
-      return;
-    }
-    this.blocks.set(bucketId, {
-      remaining,
-      expiresAt: freshExpiresAt,
-      rulesKey,
-    });
-  }
-
-  private drawFromBlock(bucketId: string, rulesKey: string): boolean {
-    const block = this.blocks.get(bucketId);
-    if (!block) return false;
-    if (block.rulesKey !== rulesKey || block.expiresAt <= this.now()) {
-      this.blocks.delete(bucketId);
-      return false;
-    }
-    block.remaining -= 1;
-    if (block.remaining <= 0) {
-      this.blocks.delete(bucketId);
-    }
-    return true;
-  }
-}
-
-function leasedBlockTtlMs(rules: readonly PacingRule[]): number {
-  const shortestWindowMs = Math.min(
-    ...rules
-      .map((rule) => rule.windowMs)
-      .filter((windowMs) => Number.isFinite(windowMs) && windowMs > 0),
-  );
-  if (!Number.isFinite(shortestWindowMs)) return LEASE_BLOCK_MIN_TTL_MS;
-  return Math.max(
-    LEASE_BLOCK_MIN_TTL_MS,
-    Math.min(LEASE_BLOCK_MAX_TTL_MS, Math.floor(shortestWindowMs)),
-  );
-}

package/dist/bundling-sources/shared_libs/play-runtime/runtime-pg-driver-neon-serverless.ts

@@ -1,217 +0,0 @@
-/**
- * `@neondatabase/serverless` Pool factory. Installed at boot by the
- * workers_edge dynamic Worker harness. The serverless driver speaks the
- * same Postgres wire protocol as `pg` but uses Neon's WebSocket proxy
- * (or HTTP endpoint) so it works inside the workerd V8 isolate where raw
- * TCP is unavailable.
- *
- * ## Lazy loading (the actual implementation)
- *
- * `@neondatabase/serverless` is ~143 KB minified — a non-trivial fraction
- * of every per-graphHash play Worker bundle. The harness's
- * `installNeonServerlessRuntimePoolDriver()` fires unconditionally at
- * isolate startup, but the heavy module is loaded ON FIRST `pool.connect()`
- * via dynamic `import('@neondatabase/serverless')`. Plays that never open
- * a Postgres pool (csv-only, computation-only, tool-only plays) skip the
- * import entirely, even though the driver registration ran at boot.
- *
- * Concretely:
- *   - Bundle still contains the dynamic-import path → `@neondatabase/serverless`
- *     is still in the per-play bundle (esbuild emits it as a deferred chunk
- *     in `format: 'esm'`, but workerd inlines all chunks for a Worker —
- *     so the bytes are still in the worker's compiled code).
- *   - V8 PARSE / COMPILE for those bytes is also deferred until the first
- *     `import()` call resolves; modern V8 does parse-on-demand for ESM
- *     dynamic imports. So plays that never connect skip the parse cost.
- *   - Plays that DO connect pay the import cost once per isolate, then
- *     reuse the cached module + pool for the rest of the run.
- *
- * If you change this file, double-check by:
- *   1. Bundling a play that doesn't use `ctx.dataset` / postgres ops
- *      (e.g. tests/v2-plays/plays/03-tool-basic.play.ts).
- *   2. Confirm the resulting bundle still references
- *      `@neondatabase/serverless` (the dynamic import path is preserved
- *      as a string), but no top-level `Pool` symbol is constructed.
- *   3. Confirm that creating an actual pool via `createRuntimePool` in
- *      a test still resolves and returns a working client.
- *
- * Why we don't just `external: ['@neondatabase/serverless']` in
- * bundle-play-file.ts:
- *   The `@neondatabase/serverless` package isn't provided by the
- *   workerd runtime — marking it external would crash the Worker on
- *   first import lookup. The lazy dynamic import is the right pattern:
- *   esbuild bundles the module, but its CODE STARTUP COST (parse +
- *   compile) is paid only when the import resolves.
- */
-
-import {
-  registerRuntimePoolFactory,
-  type RuntimePool,
-  type RuntimePoolClient,
-} from './runtime-pg-driver';
-
-/**
- * Minimal local types for the Neon module's runtime surface.
- *
- * We INTENTIONALLY don't `import type { Pool, PoolClient } from
- * '@neondatabase/serverless'` here — that would force tsc to read the
- * package's full type tree on every typecheck, slowing the build, and
- * the package's overloaded `connect()` resolves through types in a way
- * that surfaces as `void` in some TS configurations.
- *
- * The minimal shape is just:
- *   - Pool ctor takes a config bag
- *   - Pool instance has connect() / end()
- *   - PoolClient instance has query() / release()
- *
- * If Neon ever changes this surface, the runtime cast will fail loudly
- * the first time a play tries to use Postgres — which is exactly when
- * we want to find out.
- */
-interface NeonPoolClient {
-  query<R = Record<string, unknown>>(
-    text: string,
-    params?: unknown[],
-  ): Promise<{ rows: R[] }>;
-  release(): void;
-}
-
-interface NeonPoolInstance {
-  connect(): Promise<NeonPoolClient>;
-  end(): Promise<void>;
-}
-
-interface NeonPoolConfig {
-  connectionString: string;
-  max?: number;
-  idleTimeoutMillis?: number;
-  connectionTimeoutMillis?: number;
-}
-
-interface NeonModule {
-  Pool: new (config: NeonPoolConfig) => NeonPoolInstance;
-}
-
-function assertBindParams(params: unknown[] | undefined): void {
-  if (params !== undefined && !Array.isArray(params)) {
-    throw new Error(
-      'Neon runtime query bind parameters must be an array. Configure Neon client options at client construction, not on query().',
-    );
-  }
-}
-
-/**
- * Cached promise of the loaded Neon module. Once the first connect()
- * resolves, every subsequent connect on the same isolate hits this
- * cache instead of re-importing.
- *
- * We cache the PROMISE rather than the resolved module so concurrent
- * first-connect calls coalesce onto a single import — V8's module
- * loader is already idempotent for the same specifier, but caching at
- * this layer makes the contract obvious to readers.
- */
-let neonModulePromise: Promise<NeonModule> | null = null;
-function loadNeonModule(): Promise<NeonModule> {
-  if (!neonModulePromise) {
-    neonModulePromise =
-      import('@neondatabase/serverless') as unknown as Promise<NeonModule>;
-  }
-  return neonModulePromise;
-}
-
-function wrapNeonClient(client: NeonPoolClient): RuntimePoolClient {
-  return {
-    query: <R extends Record<string, unknown> = Record<string, unknown>>(
-      text: string,
-      params?: unknown[],
-    ) => {
-      assertBindParams(params);
-      return (
-        client.query as unknown as (
-          t: string,
-          p?: unknown[],
-        ) => Promise<{ rows: R[] }>
-      )(text, params);
-    },
-    release: () => {
-      client.release();
-    },
-  };
-}
-
-/**
- * Wrap a Neon `Pool` instance as our internal `RuntimePool` shape.
- * `connect()` and `end()` are async on both sides, so this is a thin
- * adapter — no logic, just type marshaling.
- */
-function wrapNeonPool(pool: NeonPoolInstance): RuntimePool {
-  return {
-    connect: async () =>
-      wrapNeonClient((await pool.connect()) as unknown as NeonPoolClient),
-    end: async () => {
-      await pool.end();
-    },
-  };
-}
-
-/**
- * Install the Neon-backed pool factory. Called once at Worker isolate
- * boot — `registerRuntimePoolFactory` is idempotent and throws if a
- * different factory was already registered (build-config bug).
- *
- * The factory itself is SYNCHRONOUS (returns a `RuntimePool`) but the
- * underlying Neon Pool is created LAZILY: we capture the connection
- * config in a closure and instantiate the real `Pool` on first
- * `connect()`. Until then, no `@neondatabase/serverless` runtime code
- * runs in the isolate — V8 doesn't parse the dynamic-imported chunk
- * until the import() resolves.
- */
-export function installNeonServerlessRuntimePoolDriver(): void {
-  registerRuntimePoolFactory(
-    (input) => {
-      // Captured lazily so a Pool is only constructed if the play actually
-      // connects. Most plays that don't touch Postgres directly never even
-      // reach this branch — the factory is registered but never invoked.
-      let lazyPool: NeonPoolInstance | null = null;
-
-      /**
-       * Resolve the lazy Pool, creating it on first call.
-       *
-       * Race safety: workerd executes within a single JS event loop, so
-       * two concurrent `connect()` calls on the SAME wrapper run their
-       * "lazyPool == null" checks in turn — the first creates the Pool,
-       * the second sees it. No locking needed.
-       *
-       * If pool creation fails (e.g. DNS, bad connection string), the
-       * error propagates out of connect() to the caller. We don't cache
-       * a failed pool so retries can succeed on transient failures.
-       */
-      async function ensurePool(): Promise<NeonPoolInstance> {
-        if (lazyPool) return lazyPool;
-        const neon = await loadNeonModule();
-        const pool = new neon.Pool({
-          connectionString: input.connectionString,
-          max: input.maxConnections ?? 4,
-          idleTimeoutMillis: input.idleTimeoutMs ?? 15_000,
-          connectionTimeoutMillis: input.connectTimeoutMs ?? 10_000,
-        });
-        lazyPool = pool;
-        return pool;
-      }
-
-      return {
-        connect: async () => {
-          const pool = await ensurePool();
-          return wrapNeonClient(await pool.connect());
-        },
-        end: async () => {
-          if (lazyPool) {
-            await lazyPool.end();
-            lazyPool = null;
-          }
-        },
-      };
-    },
-    { canReuseAcrossRequests: false },
-  );
-}