@cat-factory/local-server 0.15.0 → 0.17.0

package/dist/LocalContainerRunnerTransport.d.ts

@@ -1,4 +1,5 @@
 import type { RunnerDispatchKind, RunnerDispatchOptions, RunnerJobRef, RunnerJobView, RunnerTransport } from '@cat-factory/kernel';
+import type { LocalSettings } from '@cat-factory/contracts';
 import { type ContainerExec, type ContainerRuntimeAdapter } from './runtimes/index.js';
 /** Injectable CLI runner — overridable in tests. Re-exported for callers/tests. */
 export type { ContainerExec } from './runtimes/index.js';
@@ -36,48 +37,135 @@ export interface LocalContainerRunnerTransportOptions {
      * best-effort rootless daemon (e.g. under rootless Podman).
      */
     privilegedTestJobs?: boolean;
+    /**
+     * Warm-pool size: the max number of idle harness containers kept ready for re-lease.
+     * `0` (default) disables pooling entirely — every run cold-starts its own container and
+     * is torn down on release, the classic behaviour. Pooling additionally requires a
+     * runtime whose `capabilities.pooling` is true (the Docker family); it is ignored on
+     * Apple `container`.
+     */
+    poolSize?: number;
+    /** Members to pre-warm at boot (clamped to `poolMax`). Default 0. */
+    poolMinWarm?: number;
+    /**
+     * Hard cap on total members (leased + idle). A lease beyond this starts a TRANSIENT
+     * member that is removed on release rather than returned to the pool. Default = poolSize.
+     */
+    poolMax?: number;
+    /** How long an idle pooled member is kept before eviction. Default 10 min. */
+    poolIdleTtlMs?: number;
 }
 export declare class LocalContainerRunnerTransport implements RunnerTransport {
     private readonly adapter;
     private readonly image;
     private readonly sharedSecret;
     private readonly network?;
-    private readonly extraEnv;
+    private extraEnv;
     private readonly exec;
     private readonly fetchImpl;
     private readonly readyTimeoutMs;
     private readonly requestTimeoutMs;
     private readonly privilegedTestJobs;
+    private poolSize;
+    private poolMax;
+    private poolMinWarm;
+    private poolIdleTtlMs;
     /** runId → resolved container handle, to spare a CLI lookup on the hot poll path. */
     private readonly cache;
+    /** Warm-pool members (only used when pooling is enabled). Leased in-process by run id. */
+    private readonly members;
+    /**
+     * Members whose container start is in flight (started but not yet pushed to `members`).
+     * Counted toward the cap so concurrent cold-starts can't all read a low `members.length`
+     * and overshoot `poolMax`.
+     */
+    private pendingStarts;
     constructor(options: LocalContainerRunnerTransportOptions);
+    /**
+     * Set the warm-pool sizing fields from (defaulting) options. Shared by the constructor
+     * and {@link applySettings} so the clamps live in one place.
+     */
+    private configurePool;
+    /**
+     * Re-read the DB-backed local-mode settings into the ALREADY-BUILT transport so an edit
+     * in the settings panel takes effect WITHOUT a restart (the serving transport is built
+     * once and cached). Warm-pool sizing is applied live — `trimIdle` reaps idle members
+     * beyond the new `poolSize` and (when pooling is enabled) `prewarmPool` tops back up to
+     * `minWarm`; the checkout env applies to containers STARTED after this call. In-flight
+     * runs are never stranded: poll/release/dispatch route a run to the backend it ALREADY
+     * holds (a leased member or a per-run container), independent of the current pool mode,
+     * so even toggling pooling on/off mid-flight is safe.
+     */
+    applySettings(settings?: LocalSettings): void;
+    /** Bring the warm set in line with the current sizing: trim excess idle, then re-warm. */
+    private reconcilePool;
     /** The runtime's capabilities (e.g. whether local Docker-in-Docker testing is possible). */
     get capabilities(): import("./runtimes/containerRuntime.js").RuntimeCapabilities;
+    /** Whether the warm pool is active (a size is configured AND the runtime supports it). */
+    private get poolingEnabled();
+    /** Whether a pool member is currently leased to this run (in-process lease state). */
+    private hasLeasedMember;
     dispatch(ref: RunnerJobRef, spec: Record<string, unknown>, kind?: RunnerDispatchKind, options?: RunnerDispatchOptions): Promise<void>;
+    private dispatchPerRun;
     poll(ref: RunnerJobRef): Promise<RunnerJobView>;
     /**
      * Reclaim the per-RUN container now rather than leaving it idle — this tears down the
      * whole run's container (and with it any step still running in it). Best-effort and
-     * idempotent: removing an already-gone container is a no-op.
+     * idempotent: removing an already-gone container is a no-op. A run that holds a pool
+     * member instead RETURNS it to the pool (or removes a transient/over-capacity one).
      */
     release(ref: RunnerJobRef): Promise<void>;
     /**
      * Reap exited per-run containers this transport manages — orphans a crash or hard
      * kill left behind (release() never ran for them). Best-effort; returns the count
-     * removed. Call once at boot, before any job is in flight.
+     * removed. Call once at boot, before any job is in flight. When pooling is enabled it
+     * ALSO drains pool members orphaned by a previous process (their in-process lease state
+     * died with it, so they can't be safely re-leased) and pre-warms the configured minimum.
      */
     reapExited(): Promise<number>;
-    private url;
+    private dispatchPooled;
+    /** POST a job body to a harness, throwing on a non-OK response. */
+    private postJob;
+    private pollPooled;
+    private releasePooled;
+    /** Lease a member for `runId`, preferring repo affinity, starting one if needed. */
+    private acquireMember;
+    /** Start a fresh pool member container and wait for it to be healthy. */
+    private startMember;
+    /**
+     * Pre-warm IDLE members up to `poolMinWarm`. The deficit counts only currently-idle
+     * members (plus in-flight starts), NOT leased ones: counting leased members would
+     * under-warm the idle floor whenever this runs while runs are in flight (e.g. a live
+     * `applySettings`/`reconcilePool` mid-run), leaving the next runs to cold-start. The
+     * missing members are started CONCURRENTLY — one at a time would stack each container's
+     * full boot+health latency, delaying pool readiness by ~deficit×. Best-effort: a member
+     * that fails to start is skipped (the pool then fills the rest on demand).
+     */
+    private prewarmPool;
+    /**
+     * Remove every pool member the runtime reports from a PREVIOUS process — their
+     * in-process lease state died with that process, so they can't be safely re-leased.
+     * Best-effort and idempotent.
+     */
+    private drainPoolOrphans;
+    /** Remove idle members beyond `poolSize` (oldest first) so the warm set stays bounded. */
+    private trimIdle;
+    private scheduleIdleEviction;
+    private clearIdleEviction;
+    /** Drop a member from the in-process pool (does NOT remove the container). */
+    private dropMember;
     /** The container handle for a run from the cache, else rediscovered via the runtime. */
     private resolve;
     private waitForEndpoint;
     private waitForHealth;
 }
 /**
- * Build a {@link LocalContainerRunnerTransport} from the process environment. The image
- * ref (`LOCAL_HARNESS_IMAGE`) is required; the runtime adapter is selected by
- * `LOCAL_CONTAINER_RUNTIME` (docker | podman | orbstack | colima | apple); everything
- * else has sane local defaults.
+ * Build a {@link LocalContainerRunnerTransport} from the process environment plus the
+ * DB-stored local-mode {@link LocalSettings} (warm-pool sizing + per-repo checkout reuse —
+ * these REPLACED the old `LOCAL_POOL_*` / `HARNESS_*` env vars; edit them in the local-mode
+ * settings panel). The image ref (`LOCAL_HARNESS_IMAGE`) is required; the runtime adapter is
+ * selected by `LOCAL_CONTAINER_RUNTIME` (docker | podman | orbstack | colima | apple).
+ * `settings` omitted ⇒ pooling off + harness defaults (e.g. an early boot-reap call).
  */
-export declare function createLocalContainerTransportFromEnv(env: NodeJS.ProcessEnv): LocalContainerRunnerTransport;
+export declare function createLocalContainerTransportFromEnv(env: NodeJS.ProcessEnv, settings?: LocalSettings): LocalContainerRunnerTransport;
 //# sourceMappingURL=LocalContainerRunnerTransport.d.ts.map

package/dist/LocalContainerRunnerTransport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LocalContainerRunnerTransport.d.ts","sourceRoot":"","sources":["../src/LocalContainerRunnerTransport.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,kBAAkB,EAClB,qBAAqB,EACrB,YAAY,EACZ,aAAa,EACb,eAAe,EAChB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,uBAAuB,EAG7B,MAAM,qBAAqB,CAAA;AA4B5B,mFAAmF;AACnF,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAExD,MAAM,WAAW,oCAAoC;IACnD,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,OAAO,CAAC,EAAE,uBAAuB,CAAA;IACjC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,mFAAmF;IACnF,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB,iDAAiD;IACjD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,0FAA0F;IAC1F,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B;AAID,qBAAa,6BAA8B,YAAW,eAAe;IACnE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;IACjD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;IACvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAE5C,qFAAqF;IACrF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiE;IAEvF,YAAY,OAAO,EAAE,oCAAoC,EAqBxD;IAED,4FAA4F;IAC5F,IAAI,YAAY,iEAEf;IAEK,QAAQ,CACZ,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,GAAE,kBAA4B,EAClC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAgDf;IAEK,IAAI,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAgCpD;IAED;;;;OAIG;IACG,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAM9C;IAED;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAElC;IAID,OAAO,CAAC,GAAG;IAIX,wFAAwF;YAC1E,OAAO;YAcP,eAAe;YAYf,aAAa;CAoB5B;AAUD;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAClD,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,6BAA6B,CAkB/B"}
+{"version":3,"file":"LocalContainerRunnerTransport.d.ts","sourceRoot":"","sources":["../src/LocalContainerRunnerTransport.ts"],"names":[],"mappings":"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"}