@prisma/streams-server 0.1.1 → 0.1.3

package/src/app_local.ts

@@ -3,9 +3,15 @@ import { createAppCore, type App } from "./app_core";
 import type { ObjectStore } from "./objectstore/interface";
 import { NullObjectStore } from "./objectstore/null";
 import { StreamReader } from "./reader";
+import type { StreamIndexLookup } from "./index/indexer";
+import type { RoutingKeyLexiconListResult } from "./index/lexicon_indexer";
 import type { StatsCollector } from "./stats";
-import type { UploaderController } from "./uploader";
+import type { UploaderController, UploaderHooks } from "./uploader";
 import type { SegmenterController } from "./segment/segmenter_workers";
+import { readSqliteRuntimeMemoryStats } from "./sqlite/runtime_stats";
+import { Result } from "better-result";
+
+const TEXT_DECODER = new TextDecoder();
 
 class NoopUploader implements UploaderController {
   start(): void {}
@@ -13,7 +19,7 @@ class NoopUploader implements UploaderController {
   countSegmentsWaiting(): number {
     return 0;
   }
-  setHooks(_hooks: { onSegmentsUploaded?: (stream: string) => void } | undefined): void {}
+  setHooks(_hooks: UploaderHooks | undefined): void {}
   async publishManifest(_stream: string): Promise<void> {}
 }
 
@@ -22,6 +28,97 @@ const noopSegmenter: SegmenterController = {
   stop(_hard?: boolean): void {},
 };
 
+class LocalIndexLookup implements StreamIndexLookup {
+  constructor(private readonly db: App["deps"]["db"]) {}
+
+  start(): void {}
+
+  stop(): void {}
+
+  enqueue(_stream: string): void {}
+
+  async candidateSegmentsForRoutingKey(_stream: string, _keyBytes: Uint8Array): Promise<null> {
+    return null;
+  }
+
+  async candidateSegmentsForSecondaryIndex(_stream: string, _indexName: string, _keyBytes: Uint8Array): Promise<null> {
+    return null;
+  }
+
+  async getAggSegmentCompanion(_stream: string, _segmentIndex: number): Promise<null> {
+    return null;
+  }
+
+  async getColSegmentCompanion(_stream: string, _segmentIndex: number): Promise<null> {
+    return null;
+  }
+
+  async getFtsSegmentCompanion(_stream: string, _segmentIndex: number): Promise<null> {
+    return null;
+  }
+
+  async getMetricsBlockSegmentCompanion(_stream: string, _segmentIndex: number): Promise<null> {
+    return null;
+  }
+
+  async listRoutingKeysResult(
+    stream: string,
+    after: string | null,
+    limit: number
+  ): Promise<Result<RoutingKeyLexiconListResult, { kind: string; message: string }>> {
+    const srow = this.db.getStream(stream);
+    if (!srow || this.db.isDeleted(srow)) {
+      return Result.err({ kind: "invalid_lexicon_index", message: "stream not found" });
+    }
+    const safeLimit = Math.max(1, Math.min(limit, 500));
+    const keys = new Set<string>();
+    let scannedWalRows = 0;
+    for (const rec of this.db.iterWalRange(stream, 0n, srow.next_offset - 1n)) {
+      scannedWalRows += 1;
+      const rawKey = rec.routing_key == null ? null : rec.routing_key instanceof Uint8Array ? rec.routing_key : new Uint8Array(rec.routing_key);
+      if (!rawKey || rawKey.byteLength === 0) continue;
+      keys.add(TEXT_DECODER.decode(rawKey));
+    }
+    const sorted = Array.from(keys).sort();
+    const filtered = after == null ? sorted : sorted.filter((key) => key > after);
+    const page = filtered.slice(0, safeLimit);
+    const nextAfter = filtered.length > safeLimit ? page[page.length - 1] ?? null : null;
+    return Result.ok({
+      keys: page,
+      nextAfter,
+      tookMs: 0,
+      coverage: {
+        complete: true,
+        indexedSegments: 0,
+        scannedUploadedSegments: 0,
+        scannedLocalSegments: 0,
+        scannedWalRows,
+        possibleMissingUploadedSegments: 0,
+        possibleMissingLocalSegments: 0,
+      },
+        timing: {
+          lexiconRunGetMs: 0,
+          lexiconDecodeMs: 0,
+          lexiconEnumerateMs: 0,
+          lexiconMergeMs: 0,
+          fallbackScanMs: 0,
+        fallbackSegmentGetMs: 0,
+        fallbackWalScanMs: 0,
+        lexiconRunsLoaded: 0,
+      },
+    });
+  }
+
+  getLocalStorageUsage(_stream: string) {
+    return {
+      routing_index_cache_bytes: 0,
+      exact_index_cache_bytes: 0,
+      companion_cache_bytes: 0,
+      lexicon_index_cache_bytes: 0,
+    };
+  }
+}
+
 export type CreateLocalAppOptions = {
   stats?: StatsCollector;
 };
@@ -29,16 +126,59 @@ export type CreateLocalAppOptions = {
 export function createLocalApp(cfg: Config, os?: ObjectStore, opts: CreateLocalAppOptions = {}): App {
   return createAppCore(cfg, {
     stats: opts.stats,
-    createRuntime: ({ config, db }) => {
+    createRuntime: ({ config, db, registry, memorySampler, memory }) => {
       const store = os ?? new NullObjectStore();
-      const reader = new StreamReader(config, db, store);
+      const indexer = new LocalIndexLookup(db);
+      const reader = new StreamReader(config, db, store, registry, undefined, indexer, memorySampler, memory);
 
       return {
         store,
         reader,
         segmenter: noopSegmenter,
         uploader: new NoopUploader(),
+        indexer,
         uploadSchemaRegistry: async (): Promise<void> => {},
+        getRuntimeMemorySnapshot: () => {
+          const sqliteRuntime = readSqliteRuntimeMemoryStats();
+          return {
+            subsystems: {
+              heap_estimates: {
+                ingest_queue_payload_bytes: 0,
+              },
+              mapped_files: {},
+              disk_caches: {},
+              configured_budgets: {
+                sqlite_cache_budget_bytes: config.sqliteCacheBytes,
+                worker_sqlite_cache_budget_bytes: config.workerSqliteCacheBytes,
+              },
+              pipeline_buffers: {},
+              sqlite_runtime: {
+                sqlite_memory_used_bytes: sqliteRuntime.memory_used_bytes,
+                sqlite_memory_highwater_bytes: sqliteRuntime.memory_highwater_bytes,
+                sqlite_pagecache_overflow_bytes: sqliteRuntime.pagecache_overflow_bytes,
+                sqlite_pagecache_overflow_highwater_bytes: sqliteRuntime.pagecache_overflow_highwater_bytes,
+              },
+              counts: {
+                ingest_queue_requests: 0,
+                pending_upload_segments: 0,
+                sqlite_pagecache_used_slots: sqliteRuntime.pagecache_used_slots,
+                sqlite_pagecache_used_slots_highwater: sqliteRuntime.pagecache_used_slots_highwater,
+                sqlite_malloc_count: sqliteRuntime.malloc_count,
+                sqlite_malloc_count_highwater: sqliteRuntime.malloc_count_highwater,
+                sqlite_open_connections: sqliteRuntime.open_connections,
+                sqlite_prepared_statements: sqliteRuntime.prepared_statements,
+              },
+            },
+            totals: {
+              heap_estimate_bytes: 0,
+              mapped_file_bytes: 0,
+              disk_cache_bytes: 0,
+              configured_budget_bytes: config.sqliteCacheBytes + config.workerSqliteCacheBytes,
+              pipeline_buffer_bytes: 0,
+              sqlite_runtime_bytes: sqliteRuntime.memory_used_bytes + sqliteRuntime.pagecache_overflow_bytes,
+            },
+          };
+        },
         start: (): void => {},
       };
     },

package/src/auto_tune.ts

@@ -0,0 +1,62 @@
+export type AutoTuneConfig = {
+  segmentMaxMiB: number;
+  segmentTargetRows: number;
+  sqliteCacheMb: number;
+  workerSqliteCacheMb: number;
+  indexMemMb: number;
+  lexiconIndexCacheMb: number;
+  searchCompanionTocCacheMb: number;
+  searchCompanionSectionCacheMb: number;
+  ingestBatchMb: number;
+  ingestQueueMb: number;
+  ingestConcurrency: number;
+  readConcurrency: number;
+  searchConcurrency: number;
+  asyncIndexConcurrency: number;
+  indexBuildConcurrency: number;
+  indexCompactConcurrency: number;
+  segmenterWorkers: number;
+  uploadConcurrency: number;
+  searchCompanionBatchSegments: number;
+  searchCompanionYieldBlocks: number;
+};
+
+export const AUTO_TUNE_PRESETS = [256, 512, 1024, 2048, 4096, 8192] as const;
+
+export function memoryLimitForPreset(preset: number): number {
+  return preset === 256 ? 300 : preset;
+}
+
+export function tuneForPreset(p: number): AutoTuneConfig {
+  return {
+    // Segment geometry is fixed across presets. Smaller hosts still scale
+    // concurrency and cache budgets down, but they keep the same 16 MiB /
+    // 100k-row seal thresholds so upload throughput is not dominated by many
+    // tiny compressed segment objects.
+    segmentMaxMiB: 16,
+    segmentTargetRows: 100_000,
+    sqliteCacheMb: Math.max(8, Math.floor(p / 16)),
+    workerSqliteCacheMb: Math.max(8, Math.min(32, Math.floor(p / 128))),
+    indexMemMb: Math.max(4, Math.floor(p / 64)),
+    lexiconIndexCacheMb: p >= 8192 ? 256 : p >= 4096 ? 128 : p >= 2048 ? 64 : p >= 1024 ? 32 : p >= 512 ? 16 : 8,
+    searchCompanionTocCacheMb: p >= 8192 ? 4 : p >= 4096 ? 2 : 1,
+    searchCompanionSectionCacheMb: p >= 8192 ? 128 : p >= 4096 ? 64 : p >= 2048 ? 32 : p >= 1024 ? 16 : 8,
+    // Keep append working sets tighter on <=2 GiB presets because the request path
+    // still holds multiple copies of JSON batches while normalizing and queuing.
+    ingestBatchMb: p >= 8192 ? 64 : p >= 4096 ? 16 : p >= 2048 ? 8 : p >= 1024 ? 4 : 2,
+    ingestQueueMb: p >= 8192 ? 128 : p >= 4096 ? 64 : p >= 2048 ? 32 : p >= 1024 ? 16 : 8,
+    ingestConcurrency: p >= 8192 ? 8 : p >= 4096 ? 4 : p >= 1024 ? 2 : 1,
+    readConcurrency: p >= 8192 ? 16 : p >= 4096 ? 8 : p >= 1024 ? 4 : 2,
+    searchConcurrency: p >= 8192 ? 8 : p >= 4096 ? 4 : p >= 1024 ? 2 : 1,
+    asyncIndexConcurrency: p >= 8192 ? 4 : p >= 4096 ? 2 : 1,
+    // Keep <=2 GiB presets single-lane for background work. These hosts do not
+    // have enough headroom for append, segment cut, upload, and companion work
+    // to overlap aggressively under the GH Archive "all" workload.
+    indexBuildConcurrency: p >= 8192 ? 4 : p >= 4096 ? 2 : 1,
+    indexCompactConcurrency: p >= 8192 ? 4 : p >= 4096 ? 2 : 1,
+    segmenterWorkers: p >= 8192 ? 4 : p >= 4096 ? 2 : 1,
+    uploadConcurrency: p >= 8192 ? 8 : p >= 4096 ? 4 : p >= 1024 ? 2 : 1,
+    searchCompanionBatchSegments: p >= 8192 ? 4 : p >= 4096 ? 2 : 1,
+    searchCompanionYieldBlocks: p >= 8192 ? 4 : p >= 4096 ? 2 : 1,
+  };
+}

package/src/bootstrap.ts

@@ -59,8 +59,11 @@ export async function bootstrapFromR2(cfg: Config, store: ObjectStore, opts: { c
       const epoch = typeof manifest.epoch === "number" ? manifest.epoch : 0;
       const nextOffsetNum = typeof manifest.next_offset === "number" ? manifest.next_offset : 0;
       const nextOffset = BigInt(nextOffsetNum);
+      const logicalSizeBytes = parseManifestBigInt(manifest.logical_size_bytes) ?? 0n;
 
       const contentType = typeof manifest.content_type === "string" ? manifest.content_type : "application/octet-stream";
+      const profile = typeof manifest.profile === "string" && manifest.profile !== "" ? manifest.profile : "generic";
+      const profileJson = manifest.profile_json && typeof manifest.profile_json === "object" ? manifest.profile_json : null;
       const streamSeq = typeof manifest.stream_seq === "string" ? manifest.stream_seq : null;
       const closed = typeof manifest.closed === "number" ? manifest.closed : 0;
       const closedProducerId = typeof manifest.closed_producer_id === "string" ? manifest.closed_producer_id : null;
@@ -92,6 +95,7 @@ export async function bootstrapFromR2(cfg: Config, store: ObjectStore, opts: { c
         created_at_ms: createdAtMs,
         updated_at_ms: nowMs,
         content_type: contentType,
+        profile,
         stream_seq: streamSeq,
         closed,
         closed_producer_id: closedProducerId,
@@ -105,6 +109,7 @@ export async function bootstrapFromR2(cfg: Config, store: ObjectStore, opts: { c
         uploaded_segment_count: uploadedPrefix,
         pending_rows: 0n,
         pending_bytes: 0n,
+        logical_size_bytes: logicalSizeBytes,
         wal_rows: 0n,
         wal_bytes: 0n,
         last_append_ms: lastAppendMs,
@@ -113,6 +118,11 @@ export async function bootstrapFromR2(cfg: Config, store: ObjectStore, opts: { c
         expires_at_ms: expiresAtMs,
         stream_flags: streamFlags,
       });
+      if (profileJson) {
+        db.upsertStreamProfile(stream, JSON.stringify(profileJson));
+      } else {
+        db.deleteStreamProfile(stream);
+      }
 
       db.upsertSegmentMeta(stream, segmentCount, segmentOffsetsBytes, segmentBlocksBytes, segmentLastTsBytes);
 
@@ -121,7 +131,14 @@ export async function bootstrapFromR2(cfg: Config, store: ObjectStore, opts: { c
         if (!head) throw dsError(`missing manifest head ${mkey}`);
         return head;
       }, retryOpts);
-      db.upsertManifestRow(stream, Number(manifest.generation ?? 0), Number(manifest.generation ?? 0), nowMs, manifestHead?.etag ?? null);
+      db.upsertManifestRow(
+        stream,
+        Number(manifest.generation ?? 0),
+        Number(manifest.generation ?? 0),
+        nowMs,
+        manifestHead?.etag ?? null,
+        manifestHead?.size ?? null
+      );
 
       for (let i = 0; i < segmentCount; i++) {
         const startOffset = i === 0 ? 0n : segmentOffsets[i - 1];
@@ -145,6 +162,7 @@ export async function bootstrapFromR2(cfg: Config, store: ObjectStore, opts: { c
           endOffset,
           blockCount: segmentBlocks[i],
           lastAppendMs: lastTsMs,
+          payloadBytes: 0n,
           sizeBytes: head.size,
           localPath,
         });
@@ -168,6 +186,7 @@ export async function bootstrapFromR2(cfg: Config, store: ObjectStore, opts: { c
           start_segment: Number(r.start_segment),
           end_segment: Number(r.end_segment),
           object_key: String(r.object_key),
+          size_bytes: Number(r.size_bytes ?? 0),
           filter_len: Number(r.filter_len ?? 0),
           record_count: Number(r.record_count ?? 0),
         });
@@ -181,6 +200,7 @@ export async function bootstrapFromR2(cfg: Config, store: ObjectStore, opts: { c
           start_segment: Number(r.start_segment),
           end_segment: Number(r.end_segment),
           object_key: String(r.object_key),
+          size_bytes: Number(r.size_bytes ?? 0),
           filter_len: Number(r.filter_len ?? 0),
           record_count: Number(r.record_count ?? 0),
         });
@@ -189,6 +209,136 @@ export async function bootstrapFromR2(cfg: Config, store: ObjectStore, opts: { c
         db.retireIndexRuns([runId], retiredGen, BigInt(retiredAtUnix) * 1000n);
       }
 
+      const secondaryIndexes = manifest.secondary_indexes && typeof manifest.secondary_indexes === "object" ? manifest.secondary_indexes : {};
+      for (const [indexName, rawState] of Object.entries(secondaryIndexes)) {
+        if (!rawState || typeof rawState !== "object") continue;
+        const indexSecretB64 = typeof (rawState as any).index_secret === "string" ? (rawState as any).index_secret : "";
+        if (!indexSecretB64) continue;
+        const secret = new Uint8Array(Buffer.from(indexSecretB64, "base64"));
+        const configHash = typeof (rawState as any).config_hash === "string" ? (rawState as any).config_hash : "";
+        const indexedThrough =
+          typeof (rawState as any).indexed_through === "number" ? Number((rawState as any).indexed_through) : 0;
+        db.upsertSecondaryIndexState(stream, indexName, secret, configHash, indexedThrough);
+
+        const activeSecondaryRuns = Array.isArray((rawState as any).active_runs) ? (rawState as any).active_runs : [];
+        const retiredSecondaryRuns = Array.isArray((rawState as any).retired_runs) ? (rawState as any).retired_runs : [];
+        for (const run of activeSecondaryRuns) {
+          db.insertSecondaryIndexRun({
+            run_id: String(run.run_id),
+            stream,
+            index_name: indexName,
+            level: Number(run.level),
+            start_segment: Number(run.start_segment),
+            end_segment: Number(run.end_segment),
+            object_key: String(run.object_key),
+            size_bytes: Number(run.size_bytes ?? 0),
+            filter_len: Number(run.filter_len ?? 0),
+            record_count: Number(run.record_count ?? 0),
+          });
+        }
+        for (const run of retiredSecondaryRuns) {
+          const runId = String(run.run_id);
+          db.insertSecondaryIndexRun({
+            run_id: runId,
+            stream,
+            index_name: indexName,
+            level: Number(run.level),
+            start_segment: Number(run.start_segment),
+            end_segment: Number(run.end_segment),
+            object_key: String(run.object_key),
+            size_bytes: Number(run.size_bytes ?? 0),
+            filter_len: Number(run.filter_len ?? 0),
+            record_count: Number(run.record_count ?? 0),
+          });
+          const retiredGen = typeof run.retired_gen === "number" ? run.retired_gen : Number(manifest.generation ?? 0);
+          const retiredAtUnix = typeof run.retired_at_unix === "number" ? run.retired_at_unix : Math.floor(Number(nowMs) / 1000);
+          db.retireSecondaryIndexRuns([runId], retiredGen, BigInt(retiredAtUnix) * 1000n);
+        }
+      }
+
+      const lexiconIndexes = Array.isArray(manifest.lexicon_indexes) ? manifest.lexicon_indexes : [];
+      for (const rawState of lexiconIndexes) {
+        if (!rawState || typeof rawState !== "object") continue;
+        const sourceKind = typeof (rawState as any).source_kind === "string" ? (rawState as any).source_kind : "";
+        if (sourceKind === "") continue;
+        const sourceName = typeof (rawState as any).source_name === "string" ? (rawState as any).source_name : "";
+        const indexedThrough =
+          typeof (rawState as any).indexed_through === "number" ? Number((rawState as any).indexed_through) : 0;
+        db.upsertLexiconIndexState(stream, sourceKind, sourceName, indexedThrough);
+
+        const activeLexiconRuns = Array.isArray((rawState as any).active_runs) ? (rawState as any).active_runs : [];
+        const retiredLexiconRuns = Array.isArray((rawState as any).retired_runs) ? (rawState as any).retired_runs : [];
+        for (const run of activeLexiconRuns) {
+          db.insertLexiconIndexRun({
+            run_id: String(run.run_id),
+            stream,
+            source_kind: sourceKind,
+            source_name: sourceName,
+            level: Number(run.level),
+            start_segment: Number(run.start_segment),
+            end_segment: Number(run.end_segment),
+            object_key: String(run.object_key),
+            size_bytes: Number(run.size_bytes ?? 0),
+            record_count: Number(run.record_count ?? 0),
+          });
+        }
+        for (const run of retiredLexiconRuns) {
+          const runId = String(run.run_id);
+          db.insertLexiconIndexRun({
+            run_id: runId,
+            stream,
+            source_kind: sourceKind,
+            source_name: sourceName,
+            level: Number(run.level),
+            start_segment: Number(run.start_segment),
+            end_segment: Number(run.end_segment),
+            object_key: String(run.object_key),
+            size_bytes: Number(run.size_bytes ?? 0),
+            record_count: Number(run.record_count ?? 0),
+          });
+          const retiredGen = typeof run.retired_gen === "number" ? run.retired_gen : Number(manifest.generation ?? 0);
+          const retiredAtUnix = typeof run.retired_at_unix === "number" ? run.retired_at_unix : Math.floor(Number(nowMs) / 1000);
+          db.retireLexiconIndexRuns([runId], retiredGen, BigInt(retiredAtUnix) * 1000n);
+        }
+      }
+
+      const searchCompanions =
+        manifest.search_companions && typeof manifest.search_companions === "object" ? manifest.search_companions : null;
+      if (searchCompanions) {
+        const generation = typeof searchCompanions.generation === "number" ? searchCompanions.generation : 0;
+        const planHash = typeof searchCompanions.plan_hash === "string" ? searchCompanions.plan_hash : "";
+        const planJson =
+          searchCompanions.plan_json && typeof searchCompanions.plan_json === "object"
+            ? JSON.stringify(searchCompanions.plan_json)
+            : JSON.stringify({ families: {}, summary: {} });
+        if (generation > 0 && planHash) {
+          db.upsertSearchCompanionPlan(stream, generation, planHash, planJson);
+        }
+        const segments = Array.isArray(searchCompanions.segments) ? searchCompanions.segments : [];
+        for (const segment of segments) {
+          if (!segment || typeof segment !== "object") continue;
+          if (
+            typeof (segment as any).segment_index !== "number" ||
+            typeof (segment as any).object_key !== "string" ||
+            typeof (segment as any).plan_generation !== "number"
+          ) {
+            continue;
+          }
+          const sections = Array.isArray((segment as any).sections) ? (segment as any).sections : [];
+          db.upsertSearchSegmentCompanion(
+            stream,
+            Number((segment as any).segment_index),
+            String((segment as any).object_key),
+            Number((segment as any).plan_generation),
+            JSON.stringify(sections),
+            JSON.stringify((segment as any).section_sizes ?? {}),
+            Number((segment as any).size_bytes ?? 0),
+            parseManifestBigInt((segment as any).primary_timestamp_min_ms),
+            parseManifestBigInt((segment as any).primary_timestamp_max_ms)
+          );
+        }
+      }
+
       const schemaKey = schemaObjectKey(shash);
       const schemaBytes = await retry(async () => {
         const data = await store.get(schemaKey);
@@ -197,6 +347,7 @@ export async function bootstrapFromR2(cfg: Config, store: ObjectStore, opts: { c
       }, retryOpts);
       if (schemaBytes) {
         db.upsertSchemaRegistry(stream, new TextDecoder().decode(schemaBytes));
+        db.setSchemaUploadedSizeBytes(stream, schemaBytes.byteLength);
       }
     }
   } finally {
@@ -204,6 +355,13 @@ export async function bootstrapFromR2(cfg: Config, store: ObjectStore, opts: { c
   }
 }
 
+function parseManifestBigInt(value: unknown): bigint | null {
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return BigInt(Math.trunc(value));
+  if (typeof value === "string" && /^-?[0-9]+$/.test(value)) return BigInt(value);
+  return null;
+}
+
 function decodeZstdBase64(value: string): Uint8Array {
   if (!value) return new Uint8Array(0);
   const raw = Buffer.from(value, "base64");

package/src/concurrency_gate.ts

@@ -0,0 +1,108 @@
+export type GateRelease = () => void;
+
+type Waiter = {
+  resolve: (release: GateRelease) => void;
+  reject: (error: unknown) => void;
+  signal: AbortSignal | null;
+  onAbort: (() => void) | null;
+};
+
+function abortError(): Error {
+  const err = new Error("operation aborted");
+  err.name = "AbortError";
+  return err;
+}
+
+export class ConcurrencyGate {
+  private limit: number;
+  private active = 0;
+  private readonly waiters: Waiter[] = [];
+
+  constructor(limit: number) {
+    this.limit = Math.max(1, Math.floor(limit));
+  }
+
+  getLimit(): number {
+    return this.limit;
+  }
+
+  getActive(): number {
+    return this.active;
+  }
+
+  getQueued(): number {
+    return this.waiters.length;
+  }
+
+  setLimit(nextLimit: number): void {
+    this.limit = Math.max(1, Math.floor(nextLimit));
+    this.drain();
+  }
+
+  async acquire(signal?: AbortSignal | null): Promise<GateRelease> {
+    if (signal?.aborted) throw abortError();
+    if (this.active < this.limit) {
+      this.active += 1;
+      return this.releaseFactory();
+    }
+    return await new Promise<GateRelease>((resolve, reject) => {
+      const waiter: Waiter = {
+        resolve,
+        reject,
+        signal: signal ?? null,
+        onAbort: null,
+      };
+      if (signal) {
+        waiter.onAbort = () => {
+          this.removeWaiter(waiter);
+          reject(abortError());
+        };
+        signal.addEventListener("abort", waiter.onAbort, { once: true });
+      }
+      this.waiters.push(waiter);
+    });
+  }
+
+  async run<T>(fn: () => Promise<T>, signal?: AbortSignal | null): Promise<T> {
+    const release = await this.acquire(signal);
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+
+  private releaseFactory(): GateRelease {
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.active = Math.max(0, this.active - 1);
+      this.drain();
+    };
+  }
+
+  private removeWaiter(waiter: Waiter): void {
+    const idx = this.waiters.indexOf(waiter);
+    if (idx >= 0) this.waiters.splice(idx, 1);
+    if (waiter.signal && waiter.onAbort) {
+      waiter.signal.removeEventListener("abort", waiter.onAbort);
+      waiter.onAbort = null;
+    }
+  }
+
+  private drain(): void {
+    while (this.active < this.limit && this.waiters.length > 0) {
+      const waiter = this.waiters.shift()!;
+      if (waiter.signal?.aborted) {
+        if (waiter.signal && waiter.onAbort) waiter.signal.removeEventListener("abort", waiter.onAbort);
+        waiter.reject(abortError());
+        continue;
+      }
+      if (waiter.signal && waiter.onAbort) waiter.signal.removeEventListener("abort", waiter.onAbort);
+      waiter.onAbort = null;
+      this.active += 1;
+      waiter.resolve(this.releaseFactory());
+    }
+  }
+}