@zackbart/connecta 0.7.3 → 0.7.5

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,
@@ -192,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();
    * ```
@@ -208,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 {
@@ -505,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(
@@ -532,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;
     },
   };
 }
@@ -591,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,
@@ -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.
@@ -1090,6 +1095,7 @@ export function createMetaTools(
           closeConnectorScope(
             connector,
             registry.contextFor(connector.id, baseUrl, scope),
+            opts.defer,
           ),
         ),
       );
@@ -1587,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

@@ -18,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_-]+$/;
@@ -618,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);
   }
 
   /**
@@ -630,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);
   }
 
   /**

package/src/server.ts

@@ -897,6 +897,9 @@ async function serveMcp(
     activity,
     defaultToolTimeoutMs: opts.defaultToolTimeoutMs,
     probeTimeoutMs: opts.probeTimeoutMs,
+    ...(runtimeContext
+      ? { defer: runtimeContext.waitUntil.bind(runtimeContext) }
+      : {}),
   });
   if (opts.executor) {
     registerExecuteTool(server, registry, {
@@ -904,6 +907,7 @@ async function serveMcp(
       executor: opts.executor,
       logger: opts.logger,
       activity,
+      requestSignal: request.signal,
     });
   }
   const transport = new WebStandardStreamableHTTPServerTransport({
@@ -1045,6 +1049,9 @@ export function createFetchHandler(
     const url = new URL(request.url);
     const baseUrl = publicUrl ?? url.origin;
     const path = url.pathname;
+    const defer = runtimeContext
+      ? runtimeContext.waitUntil.bind(runtimeContext)
+      : undefined;
 
     /**
      * Piggyback a DUE credential liveness sweep on traffic that has already been
@@ -1060,7 +1067,7 @@ export function createFetchHandler(
       // throws while deciding whether anything is due. Nothing about a
       // background health check may turn a served request into a 500.
       try {
-        const sweep = registry.sweepCredentialHealthIfDue(baseUrl);
+        const sweep = registry.sweepCredentialHealthIfDue(baseUrl, defer);
         if (!sweep) return;
         const settled = sweep.then(
           () => {},
@@ -1068,7 +1075,7 @@ export function createFetchHandler(
             opts.logger.warn("[connecta] credential health sweep failed", err);
           },
         );
-        if (runtimeContext?.waitUntil) runtimeContext.waitUntil(settled);
+        if (defer) defer(settled);
         else void settled;
       } catch (err) {
         opts.logger.warn("[connecta] credential health sweep failed", err);
@@ -1256,6 +1263,7 @@ export function createFetchHandler(
           Boolean(opts.activity?.list),
           credentialManagement,
           opts.toolkits,
+          defer,
         );
         return privateJson(data);
       }

package/src/types.ts

@@ -264,6 +264,23 @@ export interface ExecutorProvider {
  */
 export interface Executor {
   execute(code: string, providers: ExecutorProvider[]): Promise<ExecuteResult>;
+  /** Release runtime resources. Node's built-in pool implements this. */
+  close?(): void | Promise<void>;
+}
+
+/**
+ * Optional admission capability used by bounded executors. The acquired lease
+ * carries execution so an already-admitted caller cannot accidentally acquire
+ * a second slot and deadlock a pool of one.
+ */
+export interface AdmittingExecutor extends Executor {
+  acquire(options?: { signal?: AbortSignal }): Promise<ExecutorLease>;
+}
+
+export interface ExecutorLease {
+  execute(code: string, providers: ExecutorProvider[]): Promise<ExecuteResult>;
+  /** Idempotent. Call from finally even when provider construction fails. */
+  release(): void;
 }
 
 /**

package/src/ui.ts

@@ -4,7 +4,10 @@ import {
   storedCredentialShape,
 } from "./credentials.js";
 import type { CredentialVault } from "./credentials.js";
-import { closeConnectorScope } from "./connector-scope.js";
+import {
+  closeConnectorScope,
+  type DeferredWork,
+} from "./connector-scope.js";
 import type { Registry } from "./registry.js";
 import type { Toolkit } from "./toolkits.js";
 import type { ConnectaBranding, UiAuthConfig } from "./types.js";
@@ -404,6 +407,7 @@ export async function buildUiData(
     ? "available"
     : "requires_clerk",
   toolkits?: ReadonlyMap<string, Toolkit>,
+  defer?: DeferredWork,
 ): Promise<UiData> {
   const requestScope = {};
   const connectorSet = registry.listConnectors();
@@ -549,6 +553,7 @@ export async function buildUiData(
       closeConnectorScope(
         connector,
         registry.contextFor(connector.id, baseUrl, requestScope),
+        defer,
       ),
     ),
   );

package/src/version.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.7.3";
+export const CONNECTA_VERSION = "0.7.5";