@zackbart/connecta 0.7.4 → 0.7.6

package/src/executor-admission.ts

@@ -1,6 +1,8 @@
 import type {
   AdmittingExecutor,
+  AdmissionSnapshot,
   Executor,
+  ExecutorLease,
 } from "./types.js";
 
 export type ExecutorAdmissionErrorCode =
@@ -35,10 +37,13 @@ export class ExecutorAdmissionError extends Error {
 }
 
 export interface AdmissionLease {
+  /** Time spent waiting behind active work. Zero for immediate admission. */
+  readonly waitMs: number;
   release(): void;
 }
 
 interface Waiter {
+  queuedAt: number;
   resolve: (lease: AdmissionLease) => void;
   reject: (error: ExecutorAdmissionError) => void;
   signal?: AbortSignal;
@@ -82,6 +87,14 @@ export class AdmissionController {
   private active = 0;
   private closed = false;
   private readonly waiters: Waiter[] = [];
+  private admittedTotal = 0;
+  private queuedTotal = 0;
+  private rejectedTotal = 0;
+  private cancelledTotal = 0;
+  private closedTotal = 0;
+  private queueWaitCount = 0;
+  private queueWaitTotalMs = 0;
+  private queueWaitMaxMs = 0;
 
   constructor(options: AdmissionControllerOptions) {
     this.concurrency = positiveWhole(options.concurrency, "concurrency");
@@ -107,8 +120,33 @@ export class AdmissionController {
     return this.waiters.length;
   }
 
+  snapshot(): AdmissionSnapshot {
+    return {
+      concurrency: this.concurrency,
+      maxQueueSize: this.maxQueueSize,
+      queueTimeoutMs: this.queueTimeoutMs,
+      retryAfterMs: this.retryAfterMs,
+      active: this.active,
+      queued: this.waiters.length,
+      closed: this.closed,
+      totals: {
+        admitted: this.admittedTotal,
+        queued: this.queuedTotal,
+        rejected: this.rejectedTotal,
+        cancelled: this.cancelledTotal,
+        closed: this.closedTotal,
+      },
+      queueWaitMs: {
+        count: this.queueWaitCount,
+        total: this.queueWaitTotalMs,
+        max: this.queueWaitMaxMs,
+      },
+    };
+  }
+
   acquire(options: { signal?: AbortSignal } = {}): Promise<AdmissionLease> {
     if (this.closed) {
+      this.closedTotal++;
       return Promise.reject(
         new ExecutorAdmissionError(
           "executor_closed",
@@ -117,6 +155,7 @@ export class AdmissionController {
       );
     }
     if (options.signal?.aborted) {
+      this.cancelledTotal++;
       return Promise.reject(
         new ExecutorAdmissionError(
           "executor_cancelled",
@@ -126,14 +165,17 @@ export class AdmissionController {
     }
     if (this.active < this.concurrency) {
       this.active++;
-      return Promise.resolve(this.makeLease());
+      this.admittedTotal++;
+      return Promise.resolve(this.makeLease(0));
     }
     if (this.waiters.length >= this.maxQueueSize) {
+      this.rejectedTotal++;
       return Promise.reject(this.overloaded("Executor queue is full."));
     }
 
     return new Promise<AdmissionLease>((resolve, reject) => {
       const waiter: Waiter = {
+        queuedAt: Date.now(),
         resolve,
         reject,
         ...(options.signal ? { signal: options.signal } : {}),
@@ -141,6 +183,7 @@ export class AdmissionController {
       waiter.onAbort = () => {
         if (!this.remove(waiter)) return;
         this.cleanup(waiter);
+        this.cancelledTotal++;
         reject(
           new ExecutorAdmissionError(
             "executor_cancelled",
@@ -152,6 +195,7 @@ export class AdmissionController {
       waiter.timer = setTimeout(() => {
         if (!this.remove(waiter)) return;
         this.cleanup(waiter);
+        this.rejectedTotal++;
         reject(
           this.overloaded(
             `Executor admission timed out after ${this.queueTimeoutMs}ms.`,
@@ -159,6 +203,7 @@ export class AdmissionController {
         );
       }, this.queueTimeoutMs);
       this.waiters.push(waiter);
+      this.queuedTotal++;
     });
   }
 
@@ -167,6 +212,7 @@ export class AdmissionController {
     this.closed = true;
     for (const waiter of this.waiters.splice(0)) {
       this.cleanup(waiter);
+      this.closedTotal++;
       waiter.reject(
         new ExecutorAdmissionError(
           "executor_closed",
@@ -182,9 +228,10 @@ export class AdmissionController {
     });
   }
 
-  private makeLease(): AdmissionLease {
+  private makeLease(waitMs: number): AdmissionLease {
     let released = false;
     return {
+      waitMs,
       release: () => {
         if (released) return;
         released = true;
@@ -199,8 +246,13 @@ export class AdmissionController {
     const waiter = this.waiters.shift();
     if (!waiter) return;
     this.cleanup(waiter);
+    const waitMs = Math.max(0, Date.now() - waiter.queuedAt);
+    this.admittedTotal++;
+    this.queueWaitCount++;
+    this.queueWaitTotalMs += waitMs;
+    this.queueWaitMaxMs = Math.max(this.queueWaitMaxMs, waitMs);
     this.active++;
-    waiter.resolve(this.makeLease());
+    waiter.resolve(this.makeLease(waitMs));
   }
 
   private remove(waiter: Waiter): boolean {
@@ -227,3 +279,38 @@ export function isAdmittingExecutor(
     typeof (executor as { acquire?: unknown }).acquire === "function"
   );
 }
+
+/**
+ * Give a structurally-compatible but otherwise unbounded executor the same
+ * admission contract as the built-in Node executor. The wrapper owns only the
+ * queue; closing the underlying runtime remains the Connecta lifecycle's job.
+ */
+export function withExecutorAdmission(
+  executor: Executor,
+  admission: AdmissionController,
+): AdmittingExecutor {
+  return {
+    async acquire(options = {}): Promise<ExecutorLease> {
+      const token = await admission.acquire(options);
+      let released = false;
+      return {
+        waitMs: token.waitMs,
+        execute: (code, providers) => executor.execute(code, providers),
+        release: () => {
+          if (released) return;
+          released = true;
+          token.release();
+        },
+      };
+    },
+    async execute(code, providers) {
+      const lease = await this.acquire();
+      try {
+        return await lease.execute(code, providers);
+      } finally {
+        lease.release();
+      }
+    },
+    admissionSnapshot: () => admission.snapshot(),
+  };
+}

package/src/executors/quickjs-protocol.ts

@@ -1,11 +1,14 @@
 import type { ExecuteResult } from "../types.js";
 import type { QuickJsRuntimeOptions } from "./quickjs-runtime.js";
 
-// The guest result is shaped to 24k characters before transport and QuickJS
-// capture already bounds logs to 256k characters. Every complete message is
-// measured against this ceiling before process.send; one MiB leaves room for
-// multibyte log text and envelope escaping while remaining a hard IPC bound.
+// An execution result is serialized once into payloadJson and again as that
+// string is embedded in ChildToParentMessage. Captured logs therefore get a
+// separate 512 KiB budget measured after both JSON encodings. The final result
+// is shaped to 24k characters; even if every character takes its worst-case
+// seven transport bytes, that leaves ample structural overhead below this hard
+// process.send ceiling.
 export const MAX_QUICKJS_IPC_BYTES = 1024 * 1024;
+export const MAX_QUICKJS_LOG_TRANSPORT_BYTES = 512 * 1024;
 /** Preserve #84's stopgap before a host value enters the child/WASM process. */
 export const MAX_QUICKJS_HOST_RPC_BYTES = 256 * 1024;
 

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,