@zackbart/connecta 0.7.5 → 0.7.7

package/src/executors/quickjs-runtime.ts

@@ -14,6 +14,10 @@ import {
   type QuickJSDeferredPromise,
 } from "quickjs-emscripten";
 import type { ExecuteResult, ExecutorProvider } from "../types.js";
+import {
+  MAX_QUICKJS_LOG_TRANSPORT_BYTES,
+  serializedBytes,
+} from "./quickjs-protocol.js";
 
 export interface QuickJsRuntimeOptions {
   timeoutMs: number;
@@ -31,11 +35,16 @@ const MAX_LOG_ENTRIES = 200;
 // Cap each entry AND the cumulative buffer at capture time so untrusted guest
 // code can't retain unbounded host memory: a single `console.log("x".repeat(N))`
 // otherwise copies the whole N-char guest string into a host array we hold for
-// the entire execution. 8k chars/entry is generous for glue-code logging (the
-// join in execute.ts trims the assembled log to 4k anyway), and 256k total
-// keeps the worst case — 200 maxed-out entries — bounded well under a MiB.
+// the entire execution. The separate transport-byte budget below accounts for
+// JSON escaping and is what keeps the result envelope below its IPC ceiling.
 const MAX_LOG_ENTRY_CHARS = 8_000;
 const MAX_LOG_TOTAL_CHARS = 256_000;
+const LOG_ENTRY_LIMIT_MARKER = `[log truncated after ${MAX_LOG_ENTRIES} entries]`;
+const LOG_SIZE_LIMIT_MARKER = "[log truncated: size budget exceeded]";
+const MAX_LOG_MARKER_TRANSPORT_BYTES = Math.max(
+  logTransportBytes(LOG_ENTRY_LIMIT_MARKER),
+  logTransportBytes(LOG_SIZE_LIMIT_MARKER),
+);
 // Keep one host result below the range where quickjs-emscripten@0.32.0 can
 // nondeterministically fail during runtime disposal under concurrent load.
 // This still lets guest code reduce data more than ten times larger than
@@ -46,6 +55,12 @@ function msg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+function logTransportBytes(entry: string): number {
+  // The log is encoded into ExecutionPayload, then that payloadJson string is
+  // encoded into ChildToParentMessage. Measure the units the IPC cap sees.
+  return serializedBytes(JSON.stringify(JSON.stringify(entry)));
+}
+
 function exceedsUtf8ByteLimit(value: string, limit: number): boolean {
   let bytes = 0;
   for (let index = 0; index < value.length; index += 1) {
@@ -175,15 +190,16 @@ function installBridge(
   };
   armWake(bridge);
 
-  // Running total of chars actually retained in `logs`; once the cumulative
-  // budget is spent we push one marker and drop the rest, so a flood of large
-  // entries can't grow the host array without bound.
+  // Keep both the in-memory character budget and the twice-JSON-encoded
+  // transport budget. Reserve enough byte budget for whichever truncation
+  // marker ends the stream.
   let logTotalChars = 0;
+  let logTotalTransportBytes = 0;
   let logBudgetSpent = false;
   const logFn = ctx.newFunction("__log", (h) => {
     if (logs.length >= MAX_LOG_ENTRIES) {
       if (logs.length === MAX_LOG_ENTRIES) {
-        logs.push(`[log truncated after ${MAX_LOG_ENTRIES} entries]`);
+        logs.push(LOG_ENTRY_LIMIT_MARKER);
       }
       return;
     }
@@ -194,13 +210,19 @@ function installBridge(
     if (entry.length > MAX_LOG_ENTRY_CHARS) {
       entry = `${entry.slice(0, MAX_LOG_ENTRY_CHARS)}…[entry truncated]`;
     }
-    if (logTotalChars + entry.length > MAX_LOG_TOTAL_CHARS) {
-      logs.push("[log truncated: size budget exceeded]");
+    const entryTransportBytes = logTransportBytes(entry);
+    if (
+      logTotalChars + entry.length > MAX_LOG_TOTAL_CHARS ||
+      logTotalTransportBytes + entryTransportBytes >
+        MAX_QUICKJS_LOG_TRANSPORT_BYTES - MAX_LOG_MARKER_TRANSPORT_BYTES
+    ) {
+      logs.push(LOG_SIZE_LIMIT_MARKER);
       logBudgetSpent = true;
       return;
     }
     logs.push(entry);
     logTotalChars += entry.length;
+    logTotalTransportBytes += entryTransportBytes;
   });
   ctx.setProp(ctx.global, "__log", logFn);
   logFn.dispose();

package/src/executors/quickjs.ts

@@ -2,7 +2,9 @@
 // child process: guest CPU, WASM aborts, and interpreter OOMs cannot block or
 // terminate the HTTP-serving process.
 
+import { Buffer } from "node:buffer";
 import { fork, type ChildProcess } from "node:child_process";
+import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import {
   AdmissionController,
@@ -10,6 +12,7 @@ import {
 } from "../executor-admission.js";
 import type {
   AdmittingExecutor,
+  AdmissionSnapshot,
   ExecuteResult,
   ExecutorLease,
   ExecutorProvider,
@@ -84,12 +87,33 @@ const DEFAULT_MAX_QUEUE_SIZE = 32;
 const DEFAULT_QUEUE_TIMEOUT_MS = 5_000;
 const CHILD_EXIT_GRACE_MS = 250;
 const CHILD_STARTUP_TIMEOUT_MS = 10_000;
+const MAX_CHILD_STDERR_BYTES = 8 * 1024;
 const MAX_ERROR_CHARS = 4_000;
 
 function msg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+function retainStderrTail(current: Buffer, chunk: Buffer | string): Buffer {
+  const incoming = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+  if (incoming.length >= MAX_CHILD_STDERR_BYTES) {
+    return Buffer.from(
+      incoming.subarray(incoming.length - MAX_CHILD_STDERR_BYTES),
+    );
+  }
+  const combined = Buffer.concat([current, incoming]);
+  if (combined.length <= MAX_CHILD_STDERR_BYTES) return combined;
+  return Buffer.from(combined.subarray(combined.length - MAX_CHILD_STDERR_BYTES));
+}
+
+function childExitError(message: string, stderrTail: Buffer): Error {
+  if (stderrTail.length === 0) return new Error(message);
+  return new Error(
+    `${message}\nRecent child stderr (last ${stderrTail.length} bytes):\n` +
+      stderrTail.toString("utf8"),
+  );
+}
+
 function positiveWhole(
   value: number | undefined,
   fallback: number,
@@ -256,6 +280,7 @@ class QuickJsChildPool implements AdmittingExecutor {
     let released = false;
     let executed = false;
     return {
+      waitMs: admission.waitMs,
       execute: async (code, providers) => {
         if (released) throw new Error("Executor lease was already released.");
         if (executed) throw new Error("Executor lease may execute only once.");
@@ -278,6 +303,10 @@ class QuickJsChildPool implements AdmittingExecutor {
     };
   }
 
+  admissionSnapshot(): AdmissionSnapshot {
+    return this.admission.snapshot();
+  }
+
   async execute(
     code: string,
     providers: ExecutorProvider[],
@@ -425,10 +454,26 @@ class QuickJsChildPool implements AdmittingExecutor {
       sourceMode ? "./quickjs-child.ts" : "./quickjs-child.js",
       import.meta.url,
     );
-    const child = fork(fileURLToPath(childUrl), [], {
+    const childPath = fileURLToPath(childUrl);
+    if (!existsSync(childPath)) {
+      throw new Error(
+        `QuickJS child entry is missing at ${childPath}. ` +
+          "The @zackbart/connecta/quickjs subpath requires the package file " +
+          "layout on disk; externalize @zackbart/connecta (or at least " +
+          "@zackbart/connecta/quickjs) when bundling the server.",
+      );
+    }
+    const child = fork(childPath, [], {
       execArgv: sourceMode ? ["--import", "tsx"] : [],
-      stdio: ["ignore", "ignore", "ignore", "ipc"],
+      stdio: ["ignore", "ignore", "pipe", "ipc"],
     });
+    let stderrTail: Buffer = Buffer.alloc(0);
+    child.stderr?.on("data", (chunk: Buffer | string) => {
+      stderrTail = retainStderrTail(stderrTail, chunk);
+    });
+    (
+      child.stderr as (NodeJS.ReadableStream & { unref?: () => void }) | null
+    )?.unref?.();
     slot.child = child;
     slot.ready = new Promise<void>((resolve, reject) => {
       slot.resolveReady = resolve;
@@ -453,26 +498,30 @@ class QuickJsChildPool implements AdmittingExecutor {
       this.rejectActive(slot, error);
       this.recycle(slot);
     });
-    child.on("exit", (code, exitSignal) => {
+    // `close`, unlike `exit`, runs after the stdio streams have closed, so the
+    // diagnostic includes stderr bytes flushed immediately before a crash.
+    child.on("close", (code, exitSignal) => {
       const expected = slot.expectedExit === child;
       if (slot.expectedExit === child) slot.expectedExit = undefined;
+      const exitDescription = `${
+        exitSignal ? `signal ${exitSignal}` : `code ${String(code)}`
+      }`;
       this.rejectChildReady(
         slot,
         child,
-        new Error(
-          `QuickJS child exited before becoming ready` +
-          ` (${exitSignal ? `signal ${exitSignal}` : `code ${String(code)}`}).`,
+        childExitError(
+          `QuickJS child exited before becoming ready (${exitDescription}).`,
+          stderrTail,
         ),
       );
       if (slot.child === child) slot.child = undefined;
       if (expected) return;
       this.recordCrash(slot);
-      this.resolveActive(slot, {
-        result: undefined,
-        error:
-          `QuickJS child exited unexpectedly` +
-          ` (${exitSignal ? `signal ${exitSignal}` : `code ${String(code)}`}).`,
-      });
+      const error = childExitError(
+        `QuickJS child exited unexpectedly (${exitDescription}).`,
+        stderrTail,
+      );
+      this.resolveActive(slot, { result: undefined, error: error.message });
     });
     child.unref();
     child.channel?.unref();

package/src/index.ts

@@ -14,6 +14,11 @@ import {
 } from "./toolkits.js";
 import { memoryStorage } from "./storage/memory.js";
 import { CONNECTA_VERSION } from "./version.js";
+import {
+  AdmissionController,
+  isAdmittingExecutor,
+  withExecutorAdmission,
+} from "./executor-admission.js";
 import type { ActivityReadGate, ActivityStore } from "./activity.js";
 import type {
   CredentialCheckResult,
@@ -108,6 +113,35 @@ export interface ConnectaCallsConfig {
   maxResultBytes?: number;
 }
 
+export interface AdmissionPoolConfig {
+  /** Simultaneous work admitted to this pool. */
+  concurrency?: number;
+  /** Callers allowed to wait behind active work. Set zero to fail fast. */
+  maxQueueSize?: number;
+  /** Maximum queue wait in milliseconds. */
+  queueTimeoutMs?: number;
+  /** Retry hint returned with overload failures, in milliseconds. */
+  retryAfterMs?: number;
+}
+
+/**
+ * Runtime-portable server-memory boundaries. `/health` and operator routes do
+ * not consume these permits, so they remain responsive during MCP saturation.
+ */
+export interface ConnectaAdmissionConfig {
+  /**
+   * The `/mcp` request boundary. Defaults to 16 active, 32 queued, and a
+   * 5-second maximum wait.
+   */
+  requests?: AdmissionPoolConfig;
+  /**
+   * Fallback pool for an `executor` that does not implement its own `acquire`.
+   * Defaults to 2 active, 8 queued, and a 5-second maximum wait. Bounded
+   * executors (including `quickJsExecutor`) keep their own tighter pool.
+   */
+  code?: AdmissionPoolConfig;
+}
+
 export interface ConnectaConfig {
   connectors: Connector[];
   /**
@@ -159,6 +193,8 @@ export interface ConnectaConfig {
   discovery?: ConnectaDiscoveryConfig;
   /** Deployment-wide call deadlines and result paging threshold. */
   calls?: ConnectaCallsConfig;
+  /** Bounded MCP and fallback code-mode admission. */
+  admission?: ConnectaAdmissionConfig;
   /** Optional browser UI and OAuth result-page labels. */
   branding?: ConnectaBranding;
   logger?: Logger;
@@ -222,6 +258,32 @@ export interface Connecta {
   close: () => Promise<void>;
 }
 
+const REQUEST_ADMISSION_DEFAULTS = {
+  concurrency: 16,
+  maxQueueSize: 32,
+  queueTimeoutMs: 5_000,
+  retryAfterMs: 1_000,
+} as const;
+
+const CODE_ADMISSION_DEFAULTS = {
+  concurrency: 2,
+  maxQueueSize: 8,
+  queueTimeoutMs: 5_000,
+  retryAfterMs: 1_000,
+} as const;
+
+function admissionController(
+  options: AdmissionPoolConfig | undefined,
+  defaults: typeof REQUEST_ADMISSION_DEFAULTS | typeof CODE_ADMISSION_DEFAULTS,
+): AdmissionController {
+  return new AdmissionController({
+    concurrency: options?.concurrency ?? defaults.concurrency,
+    maxQueueSize: options?.maxQueueSize ?? defaults.maxQueueSize,
+    queueTimeoutMs: options?.queueTimeoutMs ?? defaults.queueTimeoutMs,
+    retryAfterMs: options?.retryAfterMs ?? defaults.retryAfterMs,
+  });
+}
+
 function defaultLogger(): Logger {
   return {
     debug: (...a) => console.debug("[connecta]", ...a),
@@ -495,6 +557,26 @@ export function createConnecta(config: ConnectaConfig): Connecta {
   // with a 403 its client reports as a transport failure. Throw here instead.
   validateToolkitBindings(inboundAuth, toolkits);
   warnInsecureConfig(config, inboundAuth, toolkits, logger);
+  const requestAdmission = admissionController(
+    config.admission?.requests,
+    REQUEST_ADMISSION_DEFAULTS,
+  );
+  const configuredCodeAdmission = admissionController(
+    config.admission?.code,
+    CODE_ADMISSION_DEFAULTS,
+  );
+  let codeAdmission: AdmissionController | undefined;
+  let executor = config.executor;
+  if (executor && !isAdmittingExecutor(executor)) {
+    codeAdmission = configuredCodeAdmission;
+    executor = withExecutorAdmission(executor, codeAdmission);
+  } else if (executor && config.admission?.code) {
+    logger.warn(
+      "[connecta] admission.code is ignored because the configured executor " +
+        "implements acquire() and owns its admission pool; configure that " +
+        "executor's concurrency and queue options instead.",
+    );
+  }
   const handler = createFetchHandler({
     registry,
     auth: inboundAuth,
@@ -508,7 +590,8 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     activity: config.activity?.store,
     activityReadGate: config.activity?.readGate,
     activityDeploymentId: config.activity?.deploymentId,
-    executor: config.executor,
+    executor,
+    requestAdmission,
     defaultToolTimeoutMs: config.calls?.defaultTimeoutMs,
     probeTimeoutMs: config.discovery?.probeTimeoutMs,
     credentialVault,
@@ -555,6 +638,8 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     },
     close: async () => {
       closePromise ??= Promise.resolve().then(async () => {
+        requestAdmission.close();
+        codeAdmission?.close();
         await config.executor?.close?.();
       });
       await closePromise;
@@ -614,6 +699,7 @@ export type {
   ConnectorStatus,
   CredentialTestResult,
   AdmittingExecutor,
+  AdmissionSnapshot,
   ExecuteResult,
   Executor,
   ExecutorLease,
@@ -633,8 +719,11 @@ export type {
   ActivityCallSource,
   ActivityOutcome,
   ActivityPage,
+  ActivityReadActor,
+  ActivityReadEvent,
   ActivityReader,
   ActivityReadGate,
+  ActivityReadPage,
   ActivitySink,
   ActivityStore,
   ToolCallActivityEvent,

package/src/registry.ts

@@ -235,6 +235,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;
@@ -459,6 +463,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 +502,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 +526,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 +552,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 +569,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 +587,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 +727,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)}`,
+          );
+        }
+      });
     }
   }
 }