@zackbart/connecta 0.7.8 → 0.8.0

package/dist/registry.js

@@ -1,13 +1,18 @@
 import { storedCredentialShape, } from "./credentials.js";
 import { ConnectorCallError } from "./errors.js";
 import { CredentialHealthChecker, } from "./credential-health.js";
+import { ConnectorCallAdmissionController, } from "./call-admission.js";
+import { fingerprintSerializedCatalog, snapshotCatalog, } 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 { splitAddress } 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:
  * `alignEndToCharBoundary` widens a window narrower than the codepoint at the
@@ -43,6 +48,7 @@ export function resolveMaxResultBytes(value, inherited) {
         ? value
         : inherited;
 }
+const CATALOG_CHUNK_IO_CONCURRENCY = 4;
 /**
  * Recent real-call outcomes per connector, as observed by ONE view.
  *
@@ -58,13 +64,14 @@ export class HealthLog {
     observations = new Map();
     recordSuccess(id, latencyMs) {
         const previous = this.observations.get(id);
-        this.observations.set(id, {
+        const observation = {
             ...previous,
             lastSuccessAt: new Date().toISOString(),
             lastLatencyMs: latencyMs,
             consecutiveFailures: 0,
-            lastError: undefined,
-        });
+        };
+        delete observation.lastError;
+        this.observations.set(id, observation);
     }
     recordFailure(id, latencyMs, error) {
         const previous = this.observations.get(id);
@@ -91,6 +98,35 @@ function namespaced(storage, prefix) {
 function msg(err) {
     return err instanceof Error ? err.message : String(err);
 }
+/** WHATWG TextEncoder byte length without allocating another full buffer. */
+function utf8ByteLength(value) {
+    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;
+}
 /**
  * Holds the connector set, resolves addresses, and caches per-connector tool
  * lists in memory with a TTL. Connector failures are isolated: a broken
@@ -99,12 +135,15 @@ function msg(err) {
 export class Registry {
     opts;
     connectors = new Map();
+    callAdmission = new Map();
     cache = new Map();
     invalidated = new Set();
     /** Per-connector epoch preventing a pre-invalidation refresh from publishing. */
     catalogGenerations = new Map();
     /** Serialize persisted catalog set/delete operations within this isolate. */
     catalogMutations = new Map();
+    /** Same-request cold loads share one promise without retaining the request. */
+    requestCatalogLoads = new WeakMap();
     /** Deployment-wide observations — every call, whatever view made it. */
     health = new HealthLog();
     ttlMs;
@@ -133,6 +172,9 @@ export class Registry {
                 throw new Error(`Duplicate connector id "${c.id}"`);
             }
             this.connectors.set(c.id, c);
+            if (c.callAdmission) {
+                this.callAdmission.set(c.id, new ConnectorCallAdmissionController(c.id, c.callAdmission));
+            }
         }
         this.checkConventions(opts.logger);
         this.checkResultCaps(opts.logger, opts.maxResultBytes, opts.maxBatchResultBytes);
@@ -142,7 +184,9 @@ export class Registry {
             contextFor: (id, baseUrl, requestScope) => this.contextFor(id, baseUrl, requestScope),
             storage: opts.storage,
             logger: opts.logger,
-            credentialVault: opts.credentialVault,
+            ...(opts.credentialVault !== undefined
+                ? { credentialVault: opts.credentialVault }
+                : {}),
         }, opts.credentialHealth);
     }
     /**
@@ -236,6 +280,24 @@ export class Registry {
             ...callOptions,
         };
     }
+    admitCall(id, input) {
+        const admission = this.callAdmission.get(id);
+        if (admission)
+            return admission.acquire(input);
+        return Promise.resolve({ waitMs: 0, release() { } });
+    }
+    /** Payload-free aggregate state for the open health endpoint. */
+    callAdmissionSnapshot() {
+        return Object.fromEntries([...this.callAdmission].map(([id, admission]) => [
+            id,
+            admission.snapshot(),
+        ]));
+    }
+    /** Reject queued/future downstream admission; active permits release safely. */
+    closeCallAdmission() {
+        for (const admission of this.callAdmission.values())
+            admission.close();
+    }
     /**
      * Storage namespaced to the meta-tool result store (`results:` prefix), kept
      * separate from any connector's `conn:<id>:` namespace. Backs get_result.
@@ -256,40 +318,236 @@ export class Registry {
     catalogKey(id) {
         return `catalog:${id}`;
     }
-    validCatalog(raw) {
+    catalogChunkKey(id, revision, index) {
+        return `${this.catalogKey(id)}:chunk:${revision}:${index}`;
+    }
+    validLegacyCatalog(value) {
+        if (!value || typeof value !== "object")
+            return null;
+        const catalog = value;
+        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;
+    }
+    validCatalogTools(value) {
+        return value.every((tool) => tool !== null &&
+            typeof tool === "object" &&
+            typeof tool.name === "string");
+    }
+    validCatalogManifest(value) {
+        if (!value || typeof value !== "object")
+            return null;
+        const manifest = value;
+        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;
+    }
+    parseCatalogManifest(raw) {
         if (!raw)
             return null;
         try {
-            const value = JSON.parse(raw);
-            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.name === "string")) {
+            return this.validCatalogManifest(JSON.parse(raw));
+        }
+        catch {
+            return null;
+        }
+    }
+    splitCatalogChunks(snapshot) {
+        const chunks = [];
+        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;
+    }
+    async readCatalog(id, raw, now) {
+        if (!raw)
+            return null;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        if (!parsed ||
+            typeof parsed !== "object" ||
+            parsed.version !== 2) {
+            const legacy = this.validLegacyCatalog(parsed);
+            if (!legacy || legacy.staleUntil <= now)
+                return null;
+            const snapshot = await snapshotCatalog(legacy.tools);
+            if (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 {
+                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 = [];
+        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;
             }
-            return value;
+            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;
+        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,
+        };
     }
-    async storeCatalog(id, tools) {
+    async storeCatalog(id, snapshot) {
         if (!this.persistToolCatalog)
             return;
         const fetchedAt = Date.now();
-        const catalog = {
-            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 = {
+            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,
         });
     }
+    async deleteCatalog(id) {
+        let raw = null;
+        let readError;
+        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;
+        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;
+    }
     catalogGeneration(id) {
         return this.catalogGenerations.get(id) ?? 0;
     }
@@ -319,22 +577,40 @@ export class Registry {
         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 catalogChanged = !previous || JSON.stringify(previous.tools) !== JSON.stringify(tools);
-        const shouldPersist = !connector.staticTools &&
-            (catalogChanged || previous.exp <= now || this.invalidated.has(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 || previous.fingerprint !== snapshot.fingerprint;
+        const shouldPersist = 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,
         });
@@ -344,7 +620,7 @@ export class Registry {
                 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)}`);
@@ -354,7 +630,7 @@ export class Registry {
         return tools;
     }
     /** Cached listTools with in-memory + persisted serializable catalog layers. */
-    async getTools(id, baseUrl, requestScope, callOptions = {}) {
+    async loadTools(id, baseUrl, requestScope, callOptions = {}) {
         const connector = this.connectors.get(id);
         if (!connector)
             throw new Error(`Unknown connector "${id}"`);
@@ -370,7 +646,7 @@ export class Registry {
             const generation = this.catalogGeneration(id);
             let persisted = null;
             try {
-                persisted = this.validCatalog(await this.opts.storage.get(this.catalogKey(id)));
+                persisted = await this.readCatalog(id, await this.opts.storage.get(this.catalogKey(id)), now);
             }
             catch (err) {
                 this.opts.logger.warn(`[connecta] connector "${id}" catalog read failed: ${msg(err)}`);
@@ -382,6 +658,7 @@ export class Registry {
             if (persisted && persisted.staleUntil > now) {
                 this.cache.set(id, {
                     tools: persisted.tools,
+                    fingerprint: persisted.fingerprint,
                     exp: persisted.expiresAt,
                     staleUntil: persisted.staleUntil,
                 });
@@ -403,6 +680,45 @@ export class Registry {
             throw err;
         }
     }
+    /**
+     * 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, baseUrl, requestScope, callOptions = {}) {
+        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) {
         const connector = this.connectors.get(id);
@@ -512,7 +828,7 @@ export class Registry {
         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)}`);
@@ -528,7 +844,7 @@ export class Registry {
         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)}`);
@@ -655,6 +971,11 @@ export class ScopedRegistry {
             throw this.unknownConnector(id);
         return this.base.contextFor(id, baseUrl, requestScope, callOptions);
     }
+    admitCall(id, input) {
+        if (!this.visible(id))
+            return Promise.reject(this.unknownConnector(id));
+        return this.base.admitCall(id, input);
+    }
     /**
      * Stashed oversized results are bound to the scope that produced them: a
      * scoped session cannot page a result it could not have produced, and an id