@zackbart/connecta 0.7.9 → 0.8.0

package/src/registry.ts

@@ -23,15 +23,27 @@ import {
   type CallAdmissionPermit,
   type ConnectorCallAdmissionSnapshot,
 } from "./call-admission.js";
+import {
+  fingerprintSerializedCatalog,
+  snapshotCatalog,
+  type CatalogSnapshot,
+} from "./catalog-fingerprint.js";
+import {
+  MAX_CATALOG_CHUNK_BYTES,
+  MAX_CATALOG_TOOLS,
+  MAX_SERIALIZED_CATALOG_BYTES,
+} from "./catalog-limits.js";
+import { mapSettledWithConcurrency } from "./concurrency.js";
 import type { DeferredWork } from "./connector-scope.js";
 import { splitAddress, type Toolkit } from "./toolkits.js";
 
 const ID_RE = /^[a-z0-9_-]+$/;
 const DEFAULT_TTL_SECONDS = 300;
 const DEFAULT_STALE_SECONDS = 3600;
-export const DEFAULT_MAX_RESULT_BYTES = 50_000;
+const CATALOG_CHUNK_TTL_GRACE_SECONDS = 300;
+const DEFAULT_MAX_RESULT_BYTES = 50_000;
 /** Independent final-envelope boundary for `batch_call`. */
-export const DEFAULT_MAX_BATCH_RESULT_BYTES = 100_000;
+const DEFAULT_MAX_BATCH_RESULT_BYTES = 100_000;
 
 /**
  * Smallest accepted inline-result cap. One byte is pathological but harmless:
@@ -76,17 +88,41 @@ export function resolveMaxResultBytes(
 
 interface CacheEntry {
   tools: ToolDef[];
+  fingerprint: string;
   exp: number; // epoch ms
   staleUntil: number;
 }
 
+interface LegacyPersistedCatalog {
+  tools: ToolDef[];
+  /** Optional only for catalogs written before fingerprints were introduced. */
+  fingerprint?: string;
+  fetchedAt: number;
+  expiresAt: number;
+  staleUntil: number;
+}
+
+interface PersistedCatalogManifest {
+  version: 2;
+  revision: string;
+  toolCount: number;
+  byteCount: number;
+  chunkCount: number;
+  fetchedAt: number;
+  expiresAt: number;
+  staleUntil: number;
+}
+
 interface PersistedCatalog {
   tools: ToolDef[];
+  fingerprint: string;
   fetchedAt: number;
   expiresAt: number;
   staleUntil: number;
 }
 
+const CATALOG_CHUNK_IO_CONCURRENCY = 4;
+
 export interface HealthObservation {
   lastSuccessAt?: string;
   lastFailureAt?: string;
@@ -111,13 +147,14 @@ export class HealthLog {
 
   recordSuccess(id: string, latencyMs: number): void {
     const previous = this.observations.get(id);
-    this.observations.set(id, {
+    const observation: HealthObservation = {
       ...previous,
       lastSuccessAt: new Date().toISOString(),
       lastLatencyMs: latencyMs,
       consecutiveFailures: 0,
-      lastError: undefined,
-    });
+    };
+    delete observation.lastError;
+    this.observations.set(id, observation);
   }
 
   recordFailure(id: string, latencyMs: number, error: unknown): void {
@@ -171,7 +208,35 @@ function msg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
-type ConnectorOperationOptions = Pick<
+/** WHATWG TextEncoder byte length without allocating another full buffer. */
+function utf8ByteLength(value: string): number {
+  let bytes = 0;
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index);
+    if (code <= 0x7f) {
+      bytes++;
+    } else if (code <= 0x7ff) {
+      bytes += 2;
+    } else if (
+      code >= 0xd800 &&
+      code <= 0xdbff &&
+      index + 1 < value.length
+    ) {
+      const next = value.charCodeAt(index + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        bytes += 4;
+        index++;
+      } else {
+        bytes += 3;
+      }
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+}
+
+export type ConnectorOperationOptions = Pick<
   ConnectorContext,
   "signal" | "timeoutMs"
 >;
@@ -265,6 +330,11 @@ export class Registry implements RegistryView {
   private readonly catalogGenerations = new Map<string, number>();
   /** Serialize persisted catalog set/delete operations within this isolate. */
   private readonly catalogMutations = new Map<string, Promise<void>>();
+  /** Same-request cold loads share one promise without retaining the request. */
+  private readonly requestCatalogLoads = new WeakMap<
+    object,
+    Map<string, Promise<ToolDef[]>>
+  >();
   /** Deployment-wide observations — every call, whatever view made it. */
   private readonly health = new HealthLog();
   private readonly ttlMs: number;
@@ -325,7 +395,9 @@ export class Registry implements RegistryView {
           this.contextFor(id, baseUrl, requestScope),
         storage: opts.storage,
         logger: opts.logger,
-        credentialVault: opts.credentialVault,
+        ...(opts.credentialVault !== undefined
+          ? { credentialVault: opts.credentialVault }
+          : {}),
       },
       opts.credentialHealth,
     );
@@ -500,47 +572,304 @@ export class Registry implements RegistryView {
     return `catalog:${id}`;
   }
 
-  private validCatalog(raw: string | null): PersistedCatalog | null {
+  private catalogChunkKey(id: string, revision: string, index: number): string {
+    return `${this.catalogKey(id)}:chunk:${revision}:${index}`;
+  }
+
+  private validLegacyCatalog(value: unknown): LegacyPersistedCatalog | null {
+    if (!value || typeof value !== "object") return null;
+    const catalog = value as Partial<LegacyPersistedCatalog>;
+    if (
+      !Array.isArray(catalog.tools) ||
+      typeof catalog.fetchedAt !== "number" ||
+      typeof catalog.expiresAt !== "number" ||
+      typeof catalog.staleUntil !== "number" ||
+      (catalog.fingerprint !== undefined &&
+        typeof catalog.fingerprint !== "string") ||
+      !this.validCatalogTools(catalog.tools)
+    ) {
+      return null;
+    }
+    return catalog as LegacyPersistedCatalog;
+  }
+
+  private validCatalogTools(value: unknown[]): value is ToolDef[] {
+    return value.every(
+      (tool) =>
+        tool !== null &&
+        typeof tool === "object" &&
+        typeof (tool as ToolDef).name === "string",
+    );
+  }
+
+  private validCatalogManifest(
+    value: unknown,
+  ): PersistedCatalogManifest | null {
+    if (!value || typeof value !== "object") return null;
+    const manifest = value as Partial<PersistedCatalogManifest>;
+    const maxChunks =
+      Math.ceil(MAX_SERIALIZED_CATALOG_BYTES / MAX_CATALOG_CHUNK_BYTES) + 1;
+    if (
+      manifest.version !== 2 ||
+      typeof manifest.revision !== "string" ||
+      !/^sha256:[0-9]{1,8}:[0-9a-f]{64}$/.test(manifest.revision) ||
+      !Number.isInteger(manifest.toolCount) ||
+      manifest.toolCount! < 0 ||
+      manifest.toolCount! > MAX_CATALOG_TOOLS ||
+      !Number.isInteger(manifest.byteCount) ||
+      manifest.byteCount! < 2 ||
+      manifest.byteCount! > MAX_SERIALIZED_CATALOG_BYTES ||
+      !manifest.revision.startsWith(`sha256:${manifest.byteCount}:`) ||
+      !Number.isInteger(manifest.chunkCount) ||
+      manifest.chunkCount! < 1 ||
+      manifest.chunkCount! > maxChunks ||
+      typeof manifest.fetchedAt !== "number" ||
+      typeof manifest.expiresAt !== "number" ||
+      typeof manifest.staleUntil !== "number"
+    ) {
+      return null;
+    }
+    return manifest as PersistedCatalogManifest;
+  }
+
+  private parseCatalogManifest(
+    raw: string | null,
+  ): PersistedCatalogManifest | null {
+    if (!raw) return null;
+    try {
+      return this.validCatalogManifest(JSON.parse(raw));
+    } catch {
+      return null;
+    }
+  }
+
+  private splitCatalogChunks(snapshot: CatalogSnapshot): string[] {
+    const chunks: string[] = [];
+    const decoder = new TextDecoder("utf-8", {
+      fatal: true,
+      ignoreBOM: true,
+    });
+    let offset = 0;
+    while (offset < snapshot.serializedBytes.byteLength) {
+      let end = Math.min(
+        offset + MAX_CATALOG_CHUNK_BYTES,
+        snapshot.serializedBytes.byteLength,
+      );
+      // Move a boundary that landed inside a multibyte UTF-8 sequence back to
+      // the next character start. Every stored string then remains valid UTF-8.
+      while (
+        end < snapshot.serializedBytes.byteLength &&
+        ((snapshot.serializedBytes[end] ?? 0) & 0xc0) === 0x80
+      ) {
+        end--;
+      }
+      chunks.push(
+        decoder.decode(snapshot.serializedBytes.subarray(offset, end)),
+      );
+      offset = end;
+    }
+    return chunks;
+  }
+
+  private async readCatalog(
+    id: string,
+    raw: string | null,
+    now: number,
+  ): Promise<PersistedCatalog | null> {
     if (!raw) return null;
+    let parsed: unknown;
     try {
-      const value = JSON.parse(raw) as Partial<PersistedCatalog>;
+      parsed = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+
+    if (
+      !parsed ||
+      typeof parsed !== "object" ||
+      (parsed as { version?: unknown }).version !== 2
+    ) {
+      const legacy = this.validLegacyCatalog(parsed);
+      if (!legacy || legacy.staleUntil <= now) return null;
+      const snapshot = await snapshotCatalog(legacy.tools);
       if (
-        !Array.isArray(value.tools) ||
-        typeof value.fetchedAt !== "number" ||
-        typeof value.expiresAt !== "number" ||
-        typeof value.staleUntil !== "number" ||
-        !value.tools.every(
-          (tool) =>
-            tool !== null &&
-            typeof tool === "object" &&
-            typeof (tool as ToolDef).name === "string",
-        )
+        legacy.tools.length > MAX_CATALOG_TOOLS ||
+        snapshot.serializedBytes.byteLength > MAX_SERIALIZED_CATALOG_BYTES ||
+        (legacy.fingerprint !== undefined &&
+          legacy.fingerprint !== snapshot.fingerprint)
       ) {
+        this.opts.logger.warn(
+          `[connecta] connector "${id}" legacy catalog is oversized or has a fingerprint mismatch; ignoring persisted catalog.`,
+        );
         return null;
       }
-      return value as PersistedCatalog;
+      return {
+        tools: legacy.tools,
+        fingerprint: snapshot.fingerprint,
+        fetchedAt: legacy.fetchedAt,
+        expiresAt: legacy.expiresAt,
+        staleUntil: legacy.staleUntil,
+      };
+    }
+
+    const manifest = this.validCatalogManifest(parsed);
+    if (!manifest) {
+      this.opts.logger.warn(
+        `[connecta] connector "${id}" catalog manifest is invalid; ignoring persisted catalog.`,
+      );
+      return null;
+    }
+    if (manifest.staleUntil <= now) return null;
+
+    const chunkReads = await mapSettledWithConcurrency(
+      Array.from({ length: manifest.chunkCount }, (_, index) => index),
+      CATALOG_CHUNK_IO_CONCURRENCY,
+      (index) =>
+        this.opts.storage.get(
+          this.catalogChunkKey(id, manifest.revision, index),
+        ),
+    );
+    const chunks: string[] = [];
+    let chunkBytes = 0;
+    for (const [index, result] of chunkReads.entries()) {
+      if (result.status === "rejected") throw result.reason;
+      const chunk = result.value;
+      if (chunk === null) {
+        this.opts.logger.warn(
+          `[connecta] connector "${id}" catalog chunk ${index + 1}/${manifest.chunkCount} is missing; ignoring persisted catalog.`,
+        );
+        return null;
+      }
+      const byteLength = utf8ByteLength(chunk);
+      chunkBytes += byteLength;
+      if (
+        byteLength > MAX_CATALOG_CHUNK_BYTES ||
+        chunkBytes > manifest.byteCount
+      ) {
+        this.opts.logger.warn(
+          `[connecta] connector "${id}" catalog chunk bounds do not match its manifest; ignoring persisted catalog.`,
+        );
+        return null;
+      }
+      chunks.push(chunk);
+    }
+
+    const serializedTools = chunks.join("");
+    const stored = await fingerprintSerializedCatalog(serializedTools);
+    if (
+      stored.byteLength !== manifest.byteCount ||
+      stored.fingerprint !== manifest.revision
+    ) {
+      this.opts.logger.warn(
+        `[connecta] connector "${id}" catalog fingerprint mismatch; ignoring persisted catalog.`,
+      );
+      return null;
+    }
+
+    let tools: unknown;
+    try {
+      tools = JSON.parse(serializedTools);
     } catch {
+      this.opts.logger.warn(
+        `[connecta] connector "${id}" catalog chunks are torn; ignoring persisted catalog.`,
+      );
       return null;
     }
+    if (!Array.isArray(tools) || !this.validCatalogTools(tools)) {
+      this.opts.logger.warn(
+        `[connecta] connector "${id}" catalog chunks contain invalid tools; ignoring persisted catalog.`,
+      );
+      return null;
+    }
+    if (tools.length !== manifest.toolCount) {
+      this.opts.logger.warn(
+        `[connecta] connector "${id}" catalog tool count does not match its manifest; ignoring persisted catalog.`,
+      );
+      return null;
+    }
+    return {
+      tools,
+      fingerprint: stored.fingerprint,
+      fetchedAt: manifest.fetchedAt,
+      expiresAt: manifest.expiresAt,
+      staleUntil: manifest.staleUntil,
+    };
   }
 
-  private async storeCatalog(id: string, tools: ToolDef[]): Promise<void> {
+  private async storeCatalog(
+    id: string,
+    snapshot: CatalogSnapshot,
+  ): Promise<void> {
     if (!this.persistToolCatalog) return;
     const fetchedAt = Date.now();
-    const catalog: PersistedCatalog = {
-      tools,
+    const expiresAt = fetchedAt + this.ttlMs;
+    const staleUntil = expiresAt + this.staleMs;
+    const ttlSeconds = Math.max(
+      60,
+      Math.ceil((this.ttlMs + this.staleMs) / 1000),
+    );
+    const chunks = this.splitCatalogChunks(snapshot);
+    const chunkWrites = await mapSettledWithConcurrency(
+      chunks,
+      CATALOG_CHUNK_IO_CONCURRENCY,
+      (chunk, index) =>
+        this.opts.storage.set(
+          this.catalogChunkKey(id, snapshot.fingerprint, index),
+          chunk,
+          { ttlSeconds: ttlSeconds + CATALOG_CHUNK_TTL_GRACE_SECONDS },
+        ),
+    );
+    for (const result of chunkWrites) {
+      if (result.status === "rejected") throw result.reason;
+    }
+    // The manifest is the only publication point. A failed/partial chunk write
+    // therefore leaves the previous manifest authoritative (or no catalog);
+    // unreachable chunks carry a bounded TTL and require no prefix scan.
+    const manifest: PersistedCatalogManifest = {
+      version: 2,
+      revision: snapshot.fingerprint,
+      toolCount: snapshot.tools.length,
+      byteCount: snapshot.serializedBytes.byteLength,
+      chunkCount: chunks.length,
       fetchedAt,
-      expiresAt: fetchedAt + this.ttlMs,
-      staleUntil: fetchedAt + this.ttlMs + this.staleMs,
+      expiresAt,
+      staleUntil,
     };
-    await this.opts.storage.set(this.catalogKey(id), JSON.stringify(catalog), {
-      ttlSeconds: Math.max(
-        60,
-        Math.ceil((this.ttlMs + this.staleMs) / 1000),
-      ),
+    await this.opts.storage.set(this.catalogKey(id), JSON.stringify(manifest), {
+      ttlSeconds,
     });
   }
 
+  private async deleteCatalog(id: string): Promise<void> {
+    let raw: string | null = null;
+    let readError: unknown;
+    try {
+      raw = await this.opts.storage.get(this.catalogKey(id));
+    } catch (err) {
+      readError = err;
+    }
+    const manifest = this.parseCatalogManifest(raw);
+    // The root is authoritative, so attempt its deletion even when the
+    // best-effort read needed for physical chunk cleanup failed.
+    await this.opts.storage.delete(this.catalogKey(id));
+    if (!manifest) {
+      if (readError) throw readError;
+      return;
+    }
+    let firstError: unknown;
+    for (let index = 0; index < manifest.chunkCount; index++) {
+      try {
+        await this.opts.storage.delete(
+          this.catalogChunkKey(id, manifest.revision, index),
+        );
+      } catch (err) {
+        firstError ??= err;
+      }
+    }
+    if (readError) throw readError;
+    if (firstError) throw firstError;
+  }
+
   private catalogGeneration(id: string): number {
     return this.catalogGenerations.get(id) ?? 0;
   }
@@ -580,25 +909,43 @@ export class Registry implements RegistryView {
   ): Promise<ToolDef[]> {
     const connector = this.connectors.get(id);
     if (!connector) throw new Error(`Unknown connector "${id}"`);
+    if (connector.staticTools) return connector.staticTools;
     const generation = this.catalogGeneration(id);
-    const tools = connector.staticTools
-      ? connector.staticTools
-      : await connector.listTools(
-          this.contextFor(id, baseUrl, requestScope, callOptions),
-        );
+    const tools = await connector.listTools(
+      this.contextFor(id, baseUrl, requestScope, callOptions),
+    );
     // The caller that began this refresh may still use its result, but a
     // credential/OAuth change that landed while listTools was in flight means
     // the listing must not enter either shared cache layer.
     if (generation !== this.catalogGeneration(id)) return tools;
-    const now = Date.now();
+    if (tools.length > MAX_CATALOG_TOOLS) {
+      const message =
+        `Connector "${id}" returned ${tools.length} tools, over the ` +
+        `${MAX_CATALOG_TOOLS}-tool catalog ceiling; refusing the complete catalog.`;
+      this.opts.logger.warn(`[connecta] ${message}`);
+      throw new Error(message);
+    }
     const previous = this.cache.get(id);
+    const snapshot = await snapshotCatalog(tools);
+    if (generation !== this.catalogGeneration(id)) return tools;
+    if (snapshot.serializedBytes.byteLength > MAX_SERIALIZED_CATALOG_BYTES) {
+      const message =
+        `Connector "${id}" returned a ${snapshot.serializedBytes.byteLength}-byte ` +
+        `serialized catalog, over the ${MAX_SERIALIZED_CATALOG_BYTES}-byte ceiling; ` +
+        "refusing the complete catalog.";
+      this.opts.logger.warn(`[connecta] ${message}`);
+      throw new Error(message);
+    }
+    const now = Date.now();
     const catalogChanged =
-      !previous || JSON.stringify(previous.tools) !== JSON.stringify(tools);
+      !previous || previous.fingerprint !== snapshot.fingerprint;
     const shouldPersist =
-      !connector.staticTools &&
-      (catalogChanged || previous.exp <= now || this.invalidated.has(id));
+      catalogChanged ||
+      (previous !== undefined && previous.exp <= now) ||
+      this.invalidated.has(id);
     this.cache.set(id, {
       tools,
+      fingerprint: snapshot.fingerprint,
       exp: now + this.ttlMs,
       staleUntil: now + this.ttlMs + this.staleMs,
     });
@@ -607,7 +954,7 @@ export class Registry implements RegistryView {
       await this.enqueueCatalogMutation(id, async () => {
         if (generation !== this.catalogGeneration(id)) return;
         try {
-          await this.storeCatalog(id, tools);
+          await this.storeCatalog(id, snapshot);
         } catch (err) {
           this.opts.logger.warn(
             `[connecta] connector "${id}" catalog persistence failed: ${msg(err)}`,
@@ -619,7 +966,7 @@ export class Registry implements RegistryView {
   }
 
   /** Cached listTools with in-memory + persisted serializable catalog layers. */
-  async getTools(
+  private async loadTools(
     id: string,
     baseUrl: string,
     requestScope?: object,
@@ -639,8 +986,10 @@ export class Registry implements RegistryView {
       const generation = this.catalogGeneration(id);
       let persisted: PersistedCatalog | null = null;
       try {
-        persisted = this.validCatalog(
+        persisted = await this.readCatalog(
+          id,
           await this.opts.storage.get(this.catalogKey(id)),
+          now,
         );
       } catch (err) {
         this.opts.logger.warn(
@@ -654,6 +1003,7 @@ export class Registry implements RegistryView {
       if (persisted && persisted.staleUntil > now) {
         this.cache.set(id, {
           tools: persisted.tools,
+          fingerprint: persisted.fingerprint,
           exp: persisted.expiresAt,
           staleUntil: persisted.staleUntil,
         });
@@ -679,6 +1029,46 @@ export class Registry implements RegistryView {
     }
   }
 
+  /**
+   * Coalesce one connector's cold load inside one inbound request. The WeakMap
+   * neither roots the request scope nor lets its connector context escape into
+   * another request; settled entries are also removed eagerly.
+   *
+   * The first caller's `callOptions` govern the shared load: a later caller's
+   * signal or timeout neither cancels nor extends it, and an abort by the
+   * first caller rejects every coalesced caller. Within one request that is
+   * the deal being made — one fetch, one deadline.
+   */
+  async getTools(
+    id: string,
+    baseUrl: string,
+    requestScope?: object,
+    callOptions: ConnectorOperationOptions = {},
+  ): Promise<ToolDef[]> {
+    const connector = this.connectors.get(id);
+    if (!connector) throw new Error(`Unknown connector "${id}"`);
+    if (connector.staticTools) return connector.staticTools;
+    if (!requestScope) {
+      return this.loadTools(id, baseUrl, requestScope, callOptions);
+    }
+
+    let loads = this.requestCatalogLoads.get(requestScope);
+    if (!loads) {
+      loads = new Map();
+      this.requestCatalogLoads.set(requestScope, loads);
+    }
+    const existing = loads.get(id);
+    if (existing) return existing;
+    const loading = this.loadTools(id, baseUrl, requestScope, callOptions);
+    loads.set(id, loading);
+    try {
+      return await loading;
+    } finally {
+      if (loads.get(id) === loading) loads.delete(id);
+      if (loads.size === 0) this.requestCatalogLoads.delete(requestScope);
+    }
+  }
+
   /** Return a cached catalog without performing storage or network I/O. */
   peekTools(id: string): ToolDef[] | undefined {
     const connector = this.connectors.get(id);
@@ -811,7 +1201,7 @@ export class Registry implements RegistryView {
     if (this.persistToolCatalog) {
       void this.enqueueCatalogMutation(id, async () => {
         try {
-          await this.opts.storage.delete(this.catalogKey(id));
+          await this.deleteCatalog(id);
         } catch (err) {
           this.opts.logger.warn(
             `[connecta] connector "${id}" catalog invalidation failed: ${msg(err)}`,
@@ -829,7 +1219,7 @@ export class Registry implements RegistryView {
     if (this.persistToolCatalog) {
       await this.enqueueCatalogMutation(id, async () => {
         try {
-          await this.opts.storage.delete(this.catalogKey(id));
+          await this.deleteCatalog(id);
         } catch (err) {
           this.opts.logger.warn(
             `[connecta] connector "${id}" catalog invalidation failed: ${msg(err)}`,