@wardby/cli 0.2.0 → 0.3.0

package/dist/providers/jobs/docker-services.d.ts

@@ -0,0 +1,35 @@
+import { type ResolvedCodingService } from "../../coding/services/catalog.js";
+import { type DockerContainerInspection } from "./docker-isolation.js";
+import type { JobSpec } from "./types.js";
+/** Every Docker run container is PID-bounded; the catalog has no PID field. */
+export declare const SERVICE_PIDS_LIMIT = 512;
+/** /dev/shm for a service (PostgreSQL's dynamic shared memory): the Kubernetes default size. */
+export declare const SERVICE_SHM_MIB = 64;
+export interface DockerServiceContainer {
+    service: ResolvedCodingService;
+    container: string;
+    createArgs: string[];
+}
+export declare function dockerServiceContainerName(runId: string, serviceName: string): string;
+/** The container names of a spec's services, for stop and cleanup: names only, never launch input. */
+export declare function dockerServiceContainerNames(spec: JobSpec): string[];
+/**
+ * Re-validated here, not trusted from dispatch, as the Kubernetes launcher does. Returns the
+ * schema's parsed output (defaults such as `serviceEnv`/`writablePaths` filled in), never the raw
+ * spec, so a caller never has to guard against a missing default field, and any shape the schema
+ * rejects throws the isolation error rather than surfacing as a TypeError further down.
+ */
+export declare function validateDockerServices(spec: JobSpec): ResolvedCodingService[];
+/** Its data path at its disk size, then SERVICE_SCRATCH_MIB for each writable path: the Kubernetes sizes. */
+export declare function serviceTmpfsOptions(service: ResolvedCodingService): Record<string, string>;
+/** tmpfs pages count against the container's memory cgroup: catalog memory, its disk, and /dev/shm. */
+export declare function serviceMemoryMib(service: ResolvedCodingService): number;
+export declare function buildServiceCreateArgs(spec: JobSpec, service: ResolvedCodingService): string[];
+export declare function buildDockerServicePlan(spec: JobSpec): DockerServiceContainer[];
+/**
+ * Before a service starts: exactly the controls buildServiceCreateArgs asked for. No mounts at all,
+ * so an image VOLUME outside the entry's dataPath/writablePaths (an anonymous, unbounded host
+ * volume) fails here rather than run. Re-validates the spec and requires `service` to be one of its
+ * validated entries (by name and version), rather than trusting the caller's pairing of the two.
+ */
+export declare function assertServiceContainerInspection(container: DockerContainerInspection, spec: JobSpec, service: ResolvedCodingService, networkKeeperId?: string): void;

package/dist/providers/jobs/docker-services.js

@@ -0,0 +1,191 @@
+/**
+ * Coding-run services on the Docker launcher (docs/coding-services.md): one hardened container per
+ * resolved catalog entry, in the run's network keeper's namespace, so it answers on 127.0.0.1
+ * exactly like a Kubernetes sidecar. Pure builders and attestation only: DockerJobLauncher runs
+ * and checks them. The image and environment come from the admin-managed catalog snapshot on the
+ * spec, never from repository content, and are re-validated here rather than trusted from dispatch.
+ */
+import { CODING_SERVICE_NAME } from "../../coding/protocol.js";
+import { StoredCodingServicesSchema } from "../../coding/services/catalog.js";
+import { CODING_WORKER_GID, CODING_WORKER_UID, DOCKER_ISOLATION_ERROR, hasIsolationLabels, isolationLabelArgs, isolationNames, isolationToken, } from "./docker-isolation.js";
+import { SERVICE_SCRATCH_MIB, serviceEphemeralStorageMib } from "./kubernetes-isolation.js";
+/** Every Docker run container is PID-bounded; the catalog has no PID field. */
+export const SERVICE_PIDS_LIMIT = 512;
+/** /dev/shm for a service (PostgreSQL's dynamic shared memory): the Kubernetes default size. */
+export const SERVICE_SHM_MIB = 64;
+function isolationError() {
+    return new Error(DOCKER_ISOLATION_ERROR);
+}
+export function dockerServiceContainerName(runId, serviceName) {
+    if (!CODING_SERVICE_NAME.test(serviceName))
+        throw isolationError();
+    return `wardby-svc-${isolationToken(runId)}-${serviceName}`;
+}
+/** The container names of a spec's services, for stop and cleanup: names only, never launch input. */
+export function dockerServiceContainerNames(spec) {
+    return (spec.services ?? [])
+        .filter((service) => CODING_SERVICE_NAME.test(service.name))
+        .map((service) => dockerServiceContainerName(spec.runId, service.name));
+}
+/**
+ * Re-validated here, not trusted from dispatch, as the Kubernetes launcher does. Returns the
+ * schema's parsed output (defaults such as `serviceEnv`/`writablePaths` filled in), never the raw
+ * spec, so a caller never has to guard against a missing default field, and any shape the schema
+ * rejects throws the isolation error rather than surfacing as a TypeError further down.
+ */
+export function validateDockerServices(spec) {
+    if (spec.services === undefined)
+        return [];
+    const names = spec.services.map((service) => service.name);
+    if (spec.services.length === 0 || new Set(names).size !== names.length) {
+        throw isolationError();
+    }
+    const parsed = StoredCodingServicesSchema.safeParse(spec.services);
+    if (!parsed.success)
+        throw isolationError();
+    return parsed.data;
+}
+/** Its data path at its disk size, then SERVICE_SCRATCH_MIB for each writable path: the Kubernetes sizes. */
+export function serviceTmpfsOptions(service) {
+    const mounts = [
+        { path: service.dataPath, sizeMib: service.resources.diskMib },
+        ...service.writablePaths.map((path) => ({ path, sizeMib: SERVICE_SCRATCH_MIB })),
+    ];
+    return Object.fromEntries(mounts.map(({ path, sizeMib }) => [
+        path,
+        `rw,nosuid,nodev,size=${sizeMib}m,uid=${CODING_WORKER_UID},gid=${CODING_WORKER_GID},mode=0700`,
+    ]));
+}
+/** tmpfs pages count against the container's memory cgroup: catalog memory, its disk, and /dev/shm. */
+export function serviceMemoryMib(service) {
+    return service.resources.memoryMib + serviceEphemeralStorageMib(service) + SERVICE_SHM_MIB;
+}
+export function buildServiceCreateArgs(spec, service) {
+    const names = isolationNames(spec.runId);
+    const memoryMib = serviceMemoryMib(service);
+    const env = Object.entries(service.serviceEnv)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .flatMap(([name, value]) => ["--env", `${name}=${value}`]);
+    return [
+        "container",
+        "create",
+        "--name",
+        dockerServiceContainerName(spec.runId, service.name),
+        "--pull",
+        "never",
+        "--user",
+        `${CODING_WORKER_UID}:${CODING_WORKER_GID}`,
+        "--network",
+        `container:${names.networkKeeperContainer}`,
+        "--read-only",
+        "--cap-drop",
+        "ALL",
+        "--security-opt",
+        "no-new-privileges=true",
+        "--security-opt",
+        "seccomp=builtin",
+        "--cgroupns",
+        "private",
+        "--ipc",
+        "private",
+        "--shm-size",
+        `${SERVICE_SHM_MIB}m`,
+        "--cpus",
+        String(service.resources.cpuMillicores / 1000),
+        "--memory",
+        `${memoryMib}m`,
+        "--memory-swap",
+        `${memoryMib}m`,
+        "--memory-swappiness",
+        "0",
+        "--pids-limit",
+        String(SERVICE_PIDS_LIMIT),
+        ...Object.entries(serviceTmpfsOptions(service)).flatMap(([path, options]) => ["--tmpfs", `${path}:${options}`]),
+        ...env,
+        "--restart",
+        "no",
+        "--log-driver",
+        "local",
+        "--log-opt",
+        "max-size=1m",
+        "--log-opt",
+        "max-file=2",
+        ...isolationLabelArgs(spec.runId),
+        service.image,
+    ];
+}
+export function buildDockerServicePlan(spec) {
+    return validateDockerServices(spec).map((service) => ({
+        service,
+        container: dockerServiceContainerName(spec.runId, service.name),
+        createArgs: buildServiceCreateArgs(spec, service),
+    }));
+}
+/**
+ * Before a service starts: exactly the controls buildServiceCreateArgs asked for. No mounts at all,
+ * so an image VOLUME outside the entry's dataPath/writablePaths (an anonymous, unbounded host
+ * volume) fails here rather than run. Re-validates the spec and requires `service` to be one of its
+ * validated entries (by name and version), rather than trusting the caller's pairing of the two.
+ */
+export function assertServiceContainerInspection(container, spec, service, networkKeeperId) {
+    const validated = validateDockerServices(spec);
+    if (!validated.some((entry) => entry.name === service.name && entry.version === service.version)) {
+        throw isolationError();
+    }
+    const names = isolationNames(spec.runId);
+    const host = container.HostConfig;
+    const security = host?.SecurityOpt ?? [];
+    const env = container.Config?.Env ?? [];
+    const memory = serviceMemoryMib(service) * 1024 * 1024;
+    const networkModes = [
+        `container:${names.networkKeeperContainer}`,
+        ...(networkKeeperId ? [`container:${networkKeeperId}`] : []),
+    ];
+    const expectedTmpfs = serviceTmpfsOptions(service);
+    const actualTmpfs = host?.Tmpfs ?? {};
+    if (container.Config?.User !== `${CODING_WORKER_UID}:${CODING_WORKER_GID}` ||
+        container.Config.Image !== service.image ||
+        !hasIsolationLabels(container.Config.Labels, spec.runId) ||
+        host?.ReadonlyRootfs !== true ||
+        host.Privileged !== false ||
+        (host.Binds?.length ?? 0) !== 0 ||
+        (host.CapAdd?.length ?? 0) !== 0 ||
+        !host.CapDrop?.includes("ALL") ||
+        host.CgroupnsMode !== "private" ||
+        host.IpcMode !== "private" ||
+        host.ShmSize !== SERVICE_SHM_MIB * 1024 * 1024 ||
+        host.Memory !== memory ||
+        host.MemorySwap !== memory ||
+        // cgroup v2 hosts may report this as null after accepting the explicit
+        // no-swappiness request; MemorySwap still attests that swap is disabled.
+        (host.MemorySwappiness !== 0 && host.MemorySwappiness !== null) ||
+        host.PidsLimit !== SERVICE_PIDS_LIMIT ||
+        host.NanoCpus !== service.resources.cpuMillicores * 1_000_000 ||
+        !networkModes.includes(host.NetworkMode ?? "") ||
+        host.PidMode !== "" ||
+        host.RestartPolicy?.Name !== "no" ||
+        host.LogConfig?.Type !== "local" ||
+        host.LogConfig.Config?.["max-size"] !== "1m" ||
+        host.LogConfig.Config?.["max-file"] !== "2" ||
+        !security.includes("no-new-privileges=true") ||
+        !security.includes("seccomp=builtin") ||
+        (host.Devices?.length ?? 0) !== 0 ||
+        (host.DeviceRequests?.length ?? 0) !== 0 ||
+        (host.Dns?.length ?? 0) !== 0 ||
+        (host.DnsOptions?.length ?? 0) !== 0 ||
+        (host.DnsSearch?.length ?? 0) !== 0 ||
+        (host.ExtraHosts?.length ?? 0) !== 0 ||
+        (host.GroupAdd?.length ?? 0) !== 0 ||
+        Object.keys(host.PortBindings ?? {}).length !== 0 ||
+        host.PublishAllPorts !== false ||
+        (host.Mounts?.length ?? 0) !== 0 ||
+        (container.Mounts?.length ?? 0) !== 0 ||
+        Object.keys(container.NetworkSettings?.Networks ?? {}).length !== 0 ||
+        Object.keys(container.NetworkSettings?.Ports ?? {}).length !== 0 ||
+        Object.keys(actualTmpfs).length !== Object.keys(expectedTmpfs).length ||
+        Object.entries(expectedTmpfs).some(([path, options]) => actualTmpfs[path] !== options) ||
+        env.some((value) => value.startsWith("WARDBY_")) ||
+        Object.entries(service.serviceEnv).some(([name, value]) => !env.includes(`${name}=${value}`))) {
+        throw isolationError();
+    }
+}

package/dist/providers/jobs/docker.d.ts

@@ -1,8 +1,30 @@
+import { type CollectExclusions } from "../../coding/collect-exclude.js";
+import type { CodingProvider } from "../../coding/provider.js";
 import type { JobHandle, JobResult, JobSpec, JobStatus, WorkspaceJobLauncher } from "./types.js";
+/** How long one service image pull may take before the run fails as service_unready. */
+export declare const SERVICE_IMAGE_PULL_TIMEOUT_MS = 300000;
+/**
+ * The default bound on a run's whole service start-up (every service's create, start, inspection and
+ * readiness probing; image pulls excluded), matching the Kubernetes launcher's pod-start bound.
+ */
+export declare const DEFAULT_SERVICE_READY_TIMEOUT_MS = 120000;
 export declare const SAFE_WORKER_DIAGNOSTIC: RegExp;
+export interface WorkerDiagnostic {
+    diagnostic: string;
+    diagnosticIssues?: string[];
+}
+/**
+ * Worker output is untrusted: recognizes only the fixed `{"error": code}` line,
+ * plus an optional `issues` list whose every entry must pass the shared pattern.
+ * A list with any entry that does not is dropped whole rather than filtered, so
+ * a malformed worker cannot smuggle a partial value through.
+ */
+export declare function parseWorkerDiagnosticLine(line: string): WorkerDiagnostic | undefined;
 export interface DockerCommandOptions {
     env?: Record<string, string>;
     maxOutputBytes?: number;
+    /** Kill the Docker client and fail after this long (service readiness probes and image pulls). */
+    timeoutMs?: number;
 }
 export interface DockerCommandResult {
     stdout: string;
@@ -47,7 +69,7 @@ export declare class NodeDockerCommandRunner implements DockerCommandRunner {
 export interface DockerArtifactTransfer {
     seedDirectory(sourceDirectory: string, container: string, destination: string): Promise<void>;
     seedInput(sourceFile: string, container: string): Promise<void>;
-    materializeDirectory(container: string, source: string, destination: string, maxBytes: number): Promise<void>;
+    materializeDirectory(container: string, source: string, destination: string, maxBytes: number, exclusions: CollectExclusions): Promise<void>;
 }
 export declare function dockerTransferEnvironment(path: string): NodeJS.ProcessEnv;
 /** Streams tar archives into the unprivileged keeper; no host bind mounts are used. */
@@ -57,7 +79,7 @@ export declare class NodeDockerArtifactTransfer implements DockerArtifactTransfe
     constructor(dockerBinary?: string, path?: string);
     seedDirectory(sourceDirectory: string, container: string, destination: string): Promise<void>;
     seedInput(sourceFile: string, container: string): Promise<void>;
-    materializeDirectory(container: string, source: string, destination: string, maxBytes: number): Promise<void>;
+    materializeDirectory(container: string, source: string, destination: string, maxBytes: number, exclusions: CollectExclusions): Promise<void>;
 }
 export declare function validateMaterializedWorkspace(root: string, maxBytes: number): Promise<void>;
 export interface DockerJobLauncherOptions {
@@ -70,6 +92,13 @@ export interface DockerJobLauncherOptions {
     docker?: DockerCommandRunner;
     transfer?: DockerArtifactTransfer;
     now?: () => number;
+    /** Waits between service readiness probes; tests replace it. */
+    sleep?: (milliseconds: number) => Promise<void>;
+    /**
+     * The bound on a run's whole service start-up, image pulls excluded (default
+     * DEFAULT_SERVICE_READY_TIMEOUT_MS). Start-up never runs past the run's own deadline either.
+     */
+    serviceReadyTimeoutMs?: number;
     /** Optional observer invoked after provisioning fails but before resources are cleaned up. */
     onProvisionFailure?: (context: {
         runId: string;
@@ -83,10 +112,14 @@ export declare class DockerJobLauncher implements WorkspaceJobLauncher {
     private readonly docker;
     private readonly transfer;
     private readonly now;
+    private readonly sleep;
+    private readonly serviceReadyTimeoutMs;
     private readonly locks;
     private readonly timers;
     private readonly ready;
     constructor(options: DockerJobLauncherOptions);
+    /** Starts JobSpec.services (a network keeper plus one hardened container per service) for Codex and Claude Code runs. */
+    supportsServicesFor(provider: CodingProvider): boolean;
     launch(spec: JobSpec): Promise<JobHandle>;
     status(handle: JobHandle): Promise<JobStatus>;
     collect(handle: JobHandle): Promise<JobResult>;
@@ -96,8 +129,31 @@ export declare class DockerJobLauncher implements WorkspaceJobLauncher {
     private initialize;
     private launchLocked;
     private provision;
+    /**
+     * A run with services (docs/coding-services.md). The network keeper joins the run's internal
+     * network and owns the namespace; each service joins it and must pass its catalog readiness
+     * command before the next one starts, as Kubernetes starts native sidecars. The whole start-up is
+     * bounded (ServiceStartBudget): running out fails as coding_service_unready for the service being
+     * waited on. Returns the keeper's container ID, which Docker may report as the services' and
+     * worker's network mode.
+     */
+    private startServices;
+    /**
+     * A local copy of the digest-pinned image is used as is; otherwise it is pulled, bounded by its
+     * own limit and the run's deadline. Pull time does not count toward the start-up budget.
+     */
+    private ensureServiceImage;
+    /**
+     * The catalog readiness command, like a Kubernetes startup probe: every periodSeconds, each
+     * attempt bounded by timeoutSeconds, failing after failureThreshold consecutive failures. A
+     * service that exited or vanished fails at once, and so does one still unready when the start-up
+     * budget runs out (each probe and wait is clipped to what is left of it). Probe output is never
+     * logged or kept, so these errors carry no cause.
+     */
+    private waitForServiceReady;
     private refresh;
     private stopRecord;
+    private stopContainer;
     private sweepExpired;
     private cleanupResources;
     private removeContainerIfAttested;
@@ -107,6 +163,8 @@ export declare class DockerJobLauncher implements WorkspaceJobLauncher {
     private readResultArtifact;
     private readWorkerFailureDiagnostic;
     private keeperName;
+    /** For a run with services: the attested network keeper's ID, which the worker's network mode may name. */
+    private attestedNetworkKeeperId;
     private assertHost;
     private createAndAssert;
     private waitForStorage;