@zackbart/connecta 0.7.1 → 0.7.4

package/src/index.ts

@@ -19,6 +19,7 @@ import type {
   CredentialCheckResult,
   CredentialHealthConfig,
 } from "./credential-health.js";
+import type { DeferredWork } from "./connector-scope.js";
 import type {
   Connector,
   ConnectaBranding,
@@ -82,7 +83,8 @@ export interface ConnectaDiscoveryConfig {
    * Deadline (ms) for each downstream probe/catalog call fanned out by
    * `list_connectors`, `search_tools`, and `describe_tools`. Defaults to
    * 30_000. A timed-out connector degrades independently; this does not apply
-   * to tool calls or currently abort the underlying fetch.
+   * to tool calls. Catalog walks receive the same cancellation signal, which
+   * aborts an in-flight page where supported and prevents another from starting.
    */
   probeTimeoutMs?: number;
 }
@@ -191,7 +193,10 @@ export interface Connecta {
    *
    * ```ts
    * // Cloudflare Workers (wrangler.jsonc: "triggers": { "crons": ["*\/15 * * * *"] })
-   * async scheduled(_c, env, ctx) { ctx.waitUntil(build(env).checkCredentials()); }
+   * async scheduled(_c, env, ctx) {
+   *   const defer = ctx.waitUntil.bind(ctx);
+   *   ctx.waitUntil(build(env).checkCredentials({ defer }));
+   * }
    * // Node
    * setInterval(() => void connecta.checkCredentials(), 15 * 60_000).unref();
    * ```
@@ -207,7 +212,14 @@ export interface Connecta {
     baseUrl?: string;
     force?: boolean;
     ids?: string[];
+    /**
+     * Runtime continuation for bounded teardown after the check result is ready.
+     * Workers should pass `ctx.waitUntil.bind(ctx)`.
+     */
+    defer?: DeferredWork;
   }) => Promise<CredentialCheckResult[]>;
+  /** Drain and release configured executor resources. Idempotent. */
+  close: () => Promise<void>;
 }
 
 function defaultLogger(): Logger {
@@ -504,6 +516,7 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     branding: config.branding,
     ...(toolkits ? { toolkits } : {}),
   });
+  let closePromise: Promise<void> | undefined;
   return {
     fetch: (request, _env, ctx) =>
       handler(
@@ -531,10 +544,20 @@ export function createConnecta(config: ConnectaConfig): Connecta {
           ),
         );
       }
-      return registry.checkCredentialHealth(baseUrl, {
-        ...(opts.force !== undefined ? { force: opts.force } : {}),
-        ...(opts.ids ? { ids: opts.ids } : {}),
+      return registry.checkCredentialHealth(
+        baseUrl,
+        {
+          ...(opts.force !== undefined ? { force: opts.force } : {}),
+          ...(opts.ids ? { ids: opts.ids } : {}),
+        },
+        opts.defer,
+      );
+    },
+    close: async () => {
+      closePromise ??= Promise.resolve().then(async () => {
+        await config.executor?.close?.();
       });
+      await closePromise;
     },
   };
 }
@@ -590,8 +613,10 @@ export type {
   ConnectorContext,
   ConnectorStatus,
   CredentialTestResult,
+  AdmittingExecutor,
   ExecuteResult,
   Executor,
+  ExecutorLease,
   ExecutorProvider,
   InboundAuth,
   ToolkitBinding,

package/src/meta-tools.ts

@@ -6,7 +6,10 @@ import {
   type ActivityCallSource,
   type ActivityRequestContext,
 } from "./activity.js";
-import { closeConnectorScope } from "./connector-scope.js";
+import {
+  closeConnectorScope,
+  type DeferredWork,
+} from "./connector-scope.js";
 import { unwrapMcpResult } from "./mcp-result.js";
 import {
   classifyCallError,
@@ -30,7 +33,7 @@ import {
 import {
   DEFAULT_PROBE_TIMEOUT_MS,
   normalizeTimeoutMs,
-  withTimeout,
+  withAbortableTimeout,
 } from "./timeout.js";
 import { credentialVerdictApplies } from "./credential-health.js";
 import type { ConnectorStatus, KVStorage, ToolDef } from "./types.js";
@@ -586,6 +589,8 @@ export function createMetaTools(
     /** Per-connector deadline for the list/search/describe probe fan-out. Default 30_000. */
     probeTimeoutMs?: number;
     activity?: ActivityRequestContext;
+    /** Runtime continuation for the bounded tail of probe-owned teardown. */
+    defer?: DeferredWork;
   } = {},
 ) {
   // Already normalized and warned about at registry construction.
@@ -597,6 +602,18 @@ export function createMetaTools(
   // identity lets remote connectors reuse one downstream client inside that
   // request without leaking request-bound I/O into the next one.
   const requestScope = {};
+  const withProbeDeadline = <T>(
+    label: string,
+    operation: (options: {
+      signal: AbortSignal;
+      timeoutMs: number;
+    }) => Promise<T>,
+  ) =>
+    withAbortableTimeout(
+      (signal) => operation({ signal, timeoutMs: probeTimeoutMs }),
+      probeTimeoutMs,
+      label,
+    );
 
   interface RunCallOutcome {
     toolResult: ToolResult;
@@ -907,8 +924,8 @@ export function createMetaTools(
       // call scope. Closing it cannot defeat call_tool/batch/execute_code reuse.
       const connectors = registry.listConnectors();
       const scope = probe ? {} : requestScope;
-      const out = await Promise.all(
-        connectors.map(async (c) => {
+      const pending = connectors.map(
+        async (c) => {
           const statusStarted = Date.now();
           const observed = registry.healthFor(c.id);
           const verdict = await registry.credentialHealthFor(c.id);
@@ -917,10 +934,10 @@ export function createMetaTools(
             | { state: "ok" | "error" | "unknown"; message?: string };
           if (probe) {
             try {
-              status = await withTimeout(
-                registry.statusFor(c.id, baseUrl, scope),
-                probeTimeoutMs,
+              status = await withProbeDeadline(
                 `list_connectors probe of "${c.id}"`,
+                (options) =>
+                  registry.statusFor(c.id, baseUrl, scope, options),
               );
             } catch (err) {
               // A probe that outran probeTimeoutMs (or otherwise threw)
@@ -1004,14 +1021,45 @@ export function createMetaTools(
           // the first (now stale) authorization URL.
           if (probe && status.state === "ok") {
             try {
-              tools = await withTimeout(
-                registry.refreshTools(c.id, baseUrl, scope),
-                probeTimeoutMs,
+              tools = await withProbeDeadline(
                 `list_connectors catalog refresh of "${c.id}"`,
+                (options) =>
+                  registry.refreshTools(c.id, baseUrl, scope, options),
               );
               registry.recordSuccess(c.id, Date.now() - statusStarted);
             } catch (err) {
-              status = { state: "error" as const, message: msg(err) };
+              const details = classifyCallError(err);
+              if (details.code === "auth_required") {
+                let authStatus: ConnectorStatus | undefined;
+                try {
+                  authStatus = await withProbeDeadline(
+                    `list_connectors authorization status of "${c.id}"`,
+                    (options) =>
+                      registry.statusFor(c.id, baseUrl, scope, options),
+                  );
+                } catch {
+                  // The typed auth verdict is still authoritative; this second
+                  // read exists only to recover the connector's pending URL.
+                }
+                status =
+                  authStatus?.state === "auth_required"
+                    ? authStatus
+                    : {
+                        state: "auth_required" as const,
+                        message: details.message,
+                      };
+                await registry.recordCredentialHealth(c.id, {
+                  state: "auth_required",
+                  checkedAt,
+                  ...(status.message ? { message: status.message } : {}),
+                  ...("authorizationUrl" in status &&
+                  status.authorizationUrl
+                    ? { authorizationUrl: status.authorizationUrl }
+                    : {}),
+                });
+              } else {
+                status = { state: "error" as const, message: msg(err) };
+              }
               registry.recordFailure(c.id, Date.now() - statusStarted, err);
             }
           }
@@ -1036,17 +1084,24 @@ export function createMetaTools(
               : {}),
             ...(status.message ? { message: status.message } : {}),
           };
-        }),
-      ).finally(async () => {
-        if (!probe) return;
-        await Promise.all(
-          connectors.map((connector) =>
-            closeConnectorScope(
-              connector,
-              registry.contextFor(connector.id, baseUrl, scope),
-            ),
+        },
+      );
+      if (!probe) {
+        return jsonResult({ connectors: await Promise.all(pending) });
+      }
+      const settled = await Promise.allSettled(pending);
+      await Promise.all(
+        connectors.map((connector) =>
+          closeConnectorScope(
+            connector,
+            registry.contextFor(connector.id, baseUrl, scope),
+            opts.defer,
           ),
-        );
+        ),
+      );
+      const out = settled.map((result) => {
+        if (result.status === "rejected") throw result.reason;
+        return result.value;
       });
       return jsonResult({ connectors: out });
     },
@@ -1079,10 +1134,10 @@ export function createMetaTools(
       }> = [];
       const catalogs = await Promise.allSettled(
         conns.map((c) =>
-          withTimeout(
-            registry.getTools(c.id, baseUrl, requestScope),
-            probeTimeoutMs,
+          withProbeDeadline(
             `search_tools probe of "${c.id}"`,
+            (options) =>
+              registry.getTools(c.id, baseUrl, requestScope, options),
           ),
         ),
       );
@@ -1208,10 +1263,10 @@ export function createMetaTools(
       ];
       const loaded = await Promise.allSettled(
         connectorIds.map((id) =>
-          withTimeout(
-            registry.getTools(id, baseUrl, requestScope),
-            probeTimeoutMs,
+          withProbeDeadline(
             `describe_tools probe of "${id}"`,
+            (options) =>
+              registry.getTools(id, baseUrl, requestScope, options),
           ),
         ),
       );
@@ -1538,12 +1593,14 @@ export function registerMetaTools(
     defaultToolTimeoutMs?: number;
     probeTimeoutMs?: number;
     activity?: ActivityRequestContext;
+    defer?: DeferredWork;
   },
 ): void {
   const mt = createMetaTools(registry, ctx.baseUrl, {
     defaultToolTimeoutMs: ctx.defaultToolTimeoutMs,
     probeTimeoutMs: ctx.probeTimeoutMs,
     activity: ctx.activity,
+    defer: ctx.defer,
   });
 
   server.registerTool(

package/src/node.ts

@@ -32,6 +32,7 @@ const BODY_TOO_LARGE = Symbol("body-too-large");
 async function toRequest(
   req: IncomingMessage,
   maxBodyBytes: number,
+  signal: AbortSignal,
 ): Promise<Request | typeof BODY_TOO_LARGE> {
   const host = req.headers.host ?? "localhost";
   const proto =
@@ -60,6 +61,7 @@ async function toRequest(
     method,
     headers,
     body,
+    signal,
     // Required by Node's fetch when sending a body stream.
     ...(body ? { duplex: "half" } : {}),
   } as RequestInit);
@@ -111,8 +113,27 @@ export function listen(
 
   const server = createServer((req, res) => {
     void (async () => {
+      const controller = new AbortController();
+      const abortRequest = () => {
+        if (!controller.signal.aborted) {
+          controller.abort(new Error("HTTP client disconnected."));
+        }
+      };
+      const abortIncompleteRequest = () => {
+        if (!req.complete) abortRequest();
+      };
+      const abortIncompleteResponse = () => {
+        if (!res.writableFinished) abortRequest();
+      };
+      req.once("aborted", abortRequest);
+      req.once("close", abortIncompleteRequest);
+      res.once("close", abortIncompleteResponse);
       try {
-        const request = await toRequest(req, maxBodyBytes);
+        const request = await toRequest(
+          req,
+          maxBodyBytes,
+          controller.signal,
+        );
         if (request === BODY_TOO_LARGE) {
           res.statusCode = 413;
           // The request stream was abandoned mid-body, so this connection
@@ -125,6 +146,12 @@ export function listen(
         const response = await connecta.fetch(request, undefined, ctx);
         await writeResponse(res, response);
       } catch (error) {
+        // A client that deliberately went away can make either the request
+        // handler or response pipeline reject. The request's abort signal is
+        // the authoritative classification: there is no caller left to answer,
+        // and logging an expected disconnect would turn cancellation into an
+        // error-log spam vector.
+        if (controller.signal.aborted) return;
         // A headless deployment has nothing else to go on; never swallow this.
         console.error("[connecta] request failed", error);
         if (res.headersSent) {
@@ -136,6 +163,10 @@ export function listen(
         }
         res.statusCode = 500;
         res.end("Internal Server Error");
+      } finally {
+        req.removeListener("aborted", abortRequest);
+        req.removeListener("close", abortIncompleteRequest);
+        res.removeListener("close", abortIncompleteResponse);
       }
     })();
   });
@@ -152,11 +183,14 @@ export function listen(
         process.exit(1);
       }, timeoutMs);
       forced.unref?.();
+      // Stop queued/running sandbox work now, not after server.close has
+      // waited for the very requests those children are holding open.
+      const executorClose = connecta.close();
       // close() alone waits on idle keep-alive sockets, so a single browser
       // tab would stall every shutdown until the force-exit deadline.
       server.closeIdleConnections();
       server.close(() => {
-        void Promise.allSettled([...pending]).then(() => {
+        void Promise.allSettled([...pending, executorClose]).then(() => {
           clearTimeout(forced);
           process.exit(0);
         });

package/src/registry.ts

@@ -6,7 +6,11 @@ import type {
   Logger,
   ToolDef,
 } from "./types.js";
-import type { CredentialVault } from "./credentials.js";
+import {
+  storedCredentialShape,
+  type CredentialVault,
+} from "./credentials.js";
+import { ConnectorCallError } from "./errors.js";
 import {
   CredentialHealthChecker,
   type CredentialCheckOptions,
@@ -14,6 +18,7 @@ import {
   type CredentialHealthConfig,
   type CredentialHealthRecord,
 } from "./credential-health.js";
+import type { DeferredWork } from "./connector-scope.js";
 import { splitAddress, type Toolkit } from "./toolkits.js";
 
 const ID_RE = /^[a-z0-9_-]+$/;
@@ -154,6 +159,11 @@ function msg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+type ConnectorOperationOptions = Pick<
+  ConnectorContext,
+  "signal" | "timeoutMs"
+>;
+
 /**
  * The registry surface a per-connection MCP server consumes: every meta-tool
  * (`src/meta-tools.ts`) and the `execute_code` sandbox bridge (`src/execute.ts`)
@@ -178,18 +188,20 @@ export interface RegistryView {
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions?: ConnectorOperationOptions,
   ): Promise<ToolDef[]>;
   refreshTools(
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions?: ConnectorOperationOptions,
   ): Promise<ToolDef[]>;
   peekTools(id: string): ToolDef[] | undefined;
   contextFor(
     id: string,
     baseUrl: string,
     requestScope?: object,
-    callOptions?: { signal?: AbortSignal; timeoutMs?: number },
+    callOptions?: ConnectorOperationOptions,
   ): ConnectorContext;
   resultsStorage(): KVStorage;
   recordSuccess(id: string, latencyMs: number): void;
@@ -209,6 +221,7 @@ export interface RegistryView {
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions?: ConnectorOperationOptions,
   ): Promise<ConnectorStatus>;
   invalidateStored(id: string): Promise<void>;
 }
@@ -352,21 +365,31 @@ export class Registry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope: object = {},
-    callOptions: { signal?: AbortSignal; timeoutMs?: number } = {},
+    callOptions: ConnectorOperationOptions = {},
   ): ConnectorContext {
+    const credentialConfig = this.connectors.get(id)?.credential;
+    let credentialAccess: ConnectorContext["credential"];
+    if (this.opts.credentialVault && credentialConfig) {
+      const vault = this.opts.credentialVault;
+      const readValues = async () => {
+        const values = await vault.getAll(id);
+        const shape = storedCredentialShape(credentialConfig, values);
+        if (shape.state === "mismatch") {
+          throw new ConnectorCallError("auth_required", shape.message);
+        }
+        return values;
+      };
+      credentialAccess = {
+        get: async (field = "value") =>
+          (await readValues())?.[field] ?? null,
+        getAll: readValues,
+      };
+    }
     return {
       storage: namespaced(this.opts.storage, `conn:${id}:`),
       logger: this.opts.logger,
       baseUrl,
-      ...(this.opts.credentialVault && this.connectors.get(id)?.credential
-        ? {
-            credential: {
-              get: (field?: string) =>
-                this.opts.credentialVault!.get(id, field),
-              getAll: () => this.opts.credentialVault!.getAll(id),
-            },
-          }
-        : {}),
+      ...(credentialAccess ? { credential: credentialAccess } : {}),
       requestScope,
       ...callOptions,
     };
@@ -441,13 +464,14 @@ export class Registry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions: ConnectorOperationOptions = {},
   ): Promise<ToolDef[]> {
     const connector = this.connectors.get(id);
     if (!connector) throw new Error(`Unknown connector "${id}"`);
     const tools = connector.staticTools
       ? connector.staticTools
       : await connector.listTools(
-          this.contextFor(id, baseUrl, requestScope),
+          this.contextFor(id, baseUrl, requestScope, callOptions),
         );
     const now = Date.now();
     const previous = this.cache.get(id);
@@ -479,6 +503,7 @@ export class Registry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions: ConnectorOperationOptions = {},
   ): Promise<ToolDef[]> {
     const connector = this.connectors.get(id);
     if (!connector) throw new Error(`Unknown connector "${id}"`);
@@ -512,7 +537,7 @@ export class Registry implements RegistryView {
     }
 
     try {
-      return await this.refreshTools(id, baseUrl, requestScope);
+      return await this.refreshTools(id, baseUrl, requestScope, callOptions);
     } catch (err) {
       if (stale) {
         this.opts.logger.warn(
@@ -594,8 +619,9 @@ export class Registry implements RegistryView {
   checkCredentialHealth(
     baseUrl: string,
     opts?: CredentialCheckOptions,
+    defer?: DeferredWork,
   ): Promise<CredentialCheckResult[]> {
-    return this.credentialHealth.check(baseUrl, opts);
+    return this.credentialHealth.check(baseUrl, opts, defer);
   }
 
   /**
@@ -606,8 +632,9 @@ export class Registry implements RegistryView {
    */
   sweepCredentialHealthIfDue(
     baseUrl: string,
+    defer?: DeferredWork,
   ): Promise<CredentialCheckResult[]> | undefined {
-    return this.credentialHealth.sweepIfDue(baseUrl);
+    return this.credentialHealth.sweepIfDue(baseUrl, defer);
   }
 
   /**
@@ -626,10 +653,11 @@ export class Registry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope: object = {},
+    callOptions: ConnectorOperationOptions = {},
   ): Promise<ConnectorStatus> {
     const connector = this.connectors.get(id);
     if (!connector) return { state: "error", message: "Unknown connector" };
-    const ctx = this.contextFor(id, baseUrl, requestScope);
+    const ctx = this.contextFor(id, baseUrl, requestScope, callOptions);
     if (connector.status) {
       try {
         return await connector.status(ctx);
@@ -638,7 +666,7 @@ export class Registry implements RegistryView {
       }
     }
     try {
-      await this.getTools(id, baseUrl, requestScope);
+      await this.getTools(id, baseUrl, requestScope, callOptions);
       return { state: "ok" };
     } catch (err) {
       return { state: "error", message: msg(err) };
@@ -782,11 +810,12 @@ export class ScopedRegistry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions: ConnectorOperationOptions = {},
   ): Promise<ToolDef[]> {
     if (!this.visible(id)) throw this.unknownConnector(id);
     return this.inScopeTools(
       id,
-      await this.base.getTools(id, baseUrl, requestScope),
+      await this.base.getTools(id, baseUrl, requestScope, callOptions),
     );
   }
 
@@ -794,11 +823,12 @@ export class ScopedRegistry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions: ConnectorOperationOptions = {},
   ): Promise<ToolDef[]> {
     if (!this.visible(id)) throw this.unknownConnector(id);
     return this.inScopeTools(
       id,
-      await this.base.refreshTools(id, baseUrl, requestScope),
+      await this.base.refreshTools(id, baseUrl, requestScope, callOptions),
     );
   }
 
@@ -812,7 +842,7 @@ export class ScopedRegistry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope: object = {},
-    callOptions: { signal?: AbortSignal; timeoutMs?: number } = {},
+    callOptions: ConnectorOperationOptions = {},
   ): ConnectorContext {
     // Unreachable through the meta-tools (they resolve first), so a throw here
     // is a loud backstop rather than a silent grant of connector storage and
@@ -897,12 +927,13 @@ export class ScopedRegistry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope: object = {},
+    callOptions: { signal?: AbortSignal; timeoutMs?: number } = {},
   ): Promise<ConnectorStatus> {
     // Same shape the unscoped registry returns for an unregistered id.
     if (!this.visible(id)) {
       return { state: "error", message: "Unknown connector" };
     }
-    return this.base.statusFor(id, baseUrl, requestScope);
+    return this.base.statusFor(id, baseUrl, requestScope, callOptions);
   }
 
   async invalidateStored(id: string): Promise<void> {