@zackbart/connecta 0.7.6 → 0.7.8

package/src/registry.ts

@@ -25,6 +25,8 @@ const ID_RE = /^[a-z0-9_-]+$/;
 const DEFAULT_TTL_SECONDS = 300;
 const DEFAULT_STALE_SECONDS = 3600;
 export const DEFAULT_MAX_RESULT_BYTES = 50_000;
+/** Independent final-envelope boundary for `batch_call`. */
+export const DEFAULT_MAX_BATCH_RESULT_BYTES = 100_000;
 
 /**
  * Smallest accepted inline-result cap. One byte is pathological but harmless:
@@ -143,6 +145,11 @@ export interface RegistryOptions {
    * to the default 50_000.
    */
   maxResultBytes?: number;
+  /**
+   * Cap on the complete serialized batch_call envelope. Must be a whole number
+   * of bytes >= 1; anything else warns and falls back to 100_000.
+   */
+  maxBatchResultBytes?: number;
   /** Tuning for the credential liveness checks (issue #24). */
   credentialHealth?: CredentialHealthConfig;
 }
@@ -179,6 +186,8 @@ type ConnectorOperationOptions = Pick<
 export interface RegistryView {
   /** Deployment-wide result-size cap threaded to the meta-tools. */
   readonly maxResultBytes: number;
+  /** Independent cap for the complete serialized batch_call envelope. */
+  readonly maxBatchResultBytes: number;
   listConnectors(): Connector[];
   getConnector(id: string): Connector | undefined;
   resolveAddress(
@@ -235,6 +244,10 @@ export class Registry implements RegistryView {
   private readonly connectors = new Map<string, Connector>();
   private readonly cache = new Map<string, CacheEntry>();
   private readonly invalidated = new Set<string>();
+  /** Per-connector epoch preventing a pre-invalidation refresh from publishing. */
+  private readonly catalogGenerations = new Map<string, number>();
+  /** Serialize persisted catalog set/delete operations within this isolate. */
+  private readonly catalogMutations = new Map<string, Promise<void>>();
   /** Deployment-wide observations — every call, whatever view made it. */
   private readonly health = new HealthLog();
   private readonly ttlMs: number;
@@ -242,6 +255,8 @@ export class Registry implements RegistryView {
   private readonly persistToolCatalog: boolean;
   /** Result-size guard cap threaded to the meta-tools. */
   readonly maxResultBytes: number;
+  /** Final batch envelope cap threaded to the meta-tools. */
+  readonly maxBatchResultBytes: number;
   /** Proactive liveness checks over stored downstream credentials (issue #24). */
   private readonly credentialHealth: CredentialHealthChecker;
 
@@ -258,6 +273,10 @@ export class Registry implements RegistryView {
       opts.maxResultBytes,
       DEFAULT_MAX_RESULT_BYTES,
     );
+    this.maxBatchResultBytes = resolveMaxResultBytes(
+      opts.maxBatchResultBytes,
+      DEFAULT_MAX_BATCH_RESULT_BYTES,
+    );
     for (const c of connectors) {
       if (!ID_RE.test(c.id)) {
         throw new Error(
@@ -270,7 +289,11 @@ export class Registry implements RegistryView {
       this.connectors.set(c.id, c);
     }
     this.checkConventions(opts.logger);
-    this.checkResultCaps(opts.logger, opts.maxResultBytes);
+    this.checkResultCaps(
+      opts.logger,
+      opts.maxResultBytes,
+      opts.maxBatchResultBytes,
+    );
     this.credentialHealth = new CredentialHealthChecker(
       {
         listConnectors: () => this.listConnectors(),
@@ -296,6 +319,7 @@ export class Registry implements RegistryView {
   private checkResultCaps(
     logger: Logger,
     configured: number | undefined,
+    configuredBatch: number | undefined,
   ): void {
     if (configured !== undefined && !isValidMaxResultBytes(configured)) {
       logger.warn(
@@ -305,6 +329,17 @@ export class Registry implements RegistryView {
           `default ${DEFAULT_MAX_RESULT_BYTES} instead.`,
       );
     }
+    if (
+      configuredBatch !== undefined &&
+      !isValidMaxResultBytes(configuredBatch)
+    ) {
+      logger.warn(
+        `[connecta] calls.maxBatchResultBytes ${configuredBatch} is not a whole ` +
+          `number of bytes >= ${MIN_MAX_RESULT_BYTES}: it would leave the final ` +
+          "batch envelope unbounded or serve an unusable page. Using the " +
+          `default ${DEFAULT_MAX_BATCH_RESULT_BYTES} instead.`,
+      );
+    }
     for (const c of this.connectors.values()) {
       if (
         c.maxResultBytes !== undefined &&
@@ -459,6 +494,36 @@ export class Registry implements RegistryView {
     });
   }
 
+  private catalogGeneration(id: string): number {
+    return this.catalogGenerations.get(id) ?? 0;
+  }
+
+  private advanceCatalogGeneration(id: string): void {
+    this.catalogGenerations.set(id, this.catalogGeneration(id) + 1);
+  }
+
+  /**
+   * Keep this isolate's writes and invalidations ordered. Without the queue, an
+   * old refresh can finish its storage.set after a credential change deletes
+   * the catalog and resurrect the pre-change listing.
+   */
+  private enqueueCatalogMutation(
+    id: string,
+    operation: () => Promise<void>,
+  ): Promise<void> {
+    const previous = this.catalogMutations.get(id) ?? Promise.resolve();
+    const next = previous.catch(() => {}).then(operation);
+    this.catalogMutations.set(id, next);
+    void next
+      .finally(() => {
+        if (this.catalogMutations.get(id) === next) {
+          this.catalogMutations.delete(id);
+        }
+      })
+      .catch(() => {});
+    return next;
+  }
+
   /** Force a live listTools refresh and replace both catalog cache layers. */
   async refreshTools(
     id: string,
@@ -468,11 +533,16 @@ export class Registry implements RegistryView {
   ): Promise<ToolDef[]> {
     const connector = this.connectors.get(id);
     if (!connector) throw new Error(`Unknown connector "${id}"`);
+    const generation = this.catalogGeneration(id);
     const tools = connector.staticTools
       ? connector.staticTools
       : 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();
     const previous = this.cache.get(id);
     const catalogChanged =
@@ -487,13 +557,16 @@ export class Registry implements RegistryView {
     });
     this.invalidated.delete(id);
     if (shouldPersist) {
-      try {
-        await this.storeCatalog(id, tools);
-      } catch (err) {
-        this.opts.logger.warn(
-          `[connecta] connector "${id}" catalog persistence failed: ${msg(err)}`,
-        );
-      }
+      await this.enqueueCatalogMutation(id, async () => {
+        if (generation !== this.catalogGeneration(id)) return;
+        try {
+          await this.storeCatalog(id, tools);
+        } catch (err) {
+          this.opts.logger.warn(
+            `[connecta] connector "${id}" catalog persistence failed: ${msg(err)}`,
+          );
+        }
+      });
     }
     return tools;
   }
@@ -510,11 +583,13 @@ export class Registry implements RegistryView {
     if (connector.staticTools) return connector.staticTools;
 
     const now = Date.now();
+    const requestGeneration = this.catalogGeneration(id);
     const hit = this.cache.get(id);
     if (hit && hit.exp > now) return hit.tools;
 
     let stale = hit && hit.staleUntil > now ? hit.tools : undefined;
     if (this.persistToolCatalog && !this.invalidated.has(id)) {
+      const generation = this.catalogGeneration(id);
       let persisted: PersistedCatalog | null = null;
       try {
         persisted = this.validCatalog(
@@ -525,6 +600,10 @@ export class Registry implements RegistryView {
           `[connecta] connector "${id}" catalog read failed: ${msg(err)}`,
         );
       }
+      if (generation !== this.catalogGeneration(id)) {
+        persisted = null;
+        stale = undefined;
+      }
       if (persisted && persisted.staleUntil > now) {
         this.cache.set(id, {
           tools: persisted.tools,
@@ -539,7 +618,11 @@ export class Registry implements RegistryView {
     try {
       return await this.refreshTools(id, baseUrl, requestScope, callOptions);
     } catch (err) {
-      if (stale) {
+      if (
+        stale &&
+        requestGeneration === this.catalogGeneration(id) &&
+        !this.invalidated.has(id)
+      ) {
         this.opts.logger.warn(
           `[connecta] connector "${id}" catalog refresh failed; serving stale catalog: ${msg(err)}`,
         );
@@ -675,29 +758,37 @@ export class Registry implements RegistryView {
 
   /** Drop a connector's cached tool list (e.g. after auth completes). */
   invalidate(id: string): void {
+    this.advanceCatalogGeneration(id);
     this.cache.delete(id);
     this.invalidated.add(id);
     if (this.persistToolCatalog) {
-      void this.opts.storage.delete(this.catalogKey(id)).catch((err) => {
-        this.opts.logger.warn(
-          `[connecta] connector "${id}" catalog invalidation failed: ${msg(err)}`,
-        );
+      void this.enqueueCatalogMutation(id, async () => {
+        try {
+          await this.opts.storage.delete(this.catalogKey(id));
+        } catch (err) {
+          this.opts.logger.warn(
+            `[connecta] connector "${id}" catalog invalidation failed: ${msg(err)}`,
+          );
+        }
       });
     }
   }
 
   /** Drop both in-memory and persisted tool catalogs. */
   async invalidateStored(id: string): Promise<void> {
+    this.advanceCatalogGeneration(id);
     this.cache.delete(id);
     this.invalidated.add(id);
     if (this.persistToolCatalog) {
-      try {
-        await this.opts.storage.delete(this.catalogKey(id));
-      } catch (err) {
-        this.opts.logger.warn(
-          `[connecta] connector "${id}" catalog invalidation failed: ${msg(err)}`,
-        );
-      }
+      await this.enqueueCatalogMutation(id, async () => {
+        try {
+          await this.opts.storage.delete(this.catalogKey(id));
+        } catch (err) {
+          this.opts.logger.warn(
+            `[connecta] connector "${id}" catalog invalidation failed: ${msg(err)}`,
+          );
+        }
+      });
     }
   }
 }
@@ -771,6 +862,10 @@ export class ScopedRegistry implements RegistryView {
     return this.base.maxResultBytes;
   }
 
+  get maxBatchResultBytes(): number {
+    return this.base.maxBatchResultBytes;
+  }
+
   /** In scope AND actually registered. */
   private visible(id: string): boolean {
     return (