spawnfile 0.1.14 → 0.1.18

package/dist/release/postDeploy.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A caller-declared step that must succeed on the new container before the
+ * release counts as done (for example installing a credential the image
+ * cannot carry). Executed without a shell; it must be idempotent, because a
+ * failure leaves the release unrecorded and the next run deploys and runs it
+ * again.
+ */
+export interface PostDeployHook {
+    args: string[];
+    command: string;
+    timeoutMs: number;
+}
+export interface PostDeployContext {
+    containerName: string;
+    deployment: string;
+    identity: string;
+    imageId: string;
+    imageTag: string;
+}
+export interface PostDeployResult {
+    /** Null when the process ended by signal (including the timeout). */
+    exitCode: number | null;
+    output: string;
+    timedOut: boolean;
+}
+export declare const resolvePostDeployHook: (options: {
+    postDeployArg?: string[];
+    postDeployCommand?: string;
+    timeoutMs: number;
+}) => PostDeployHook | null;
+export declare const postDeployEnvironment: (context: PostDeployContext, env?: NodeJS.ProcessEnv) => NodeJS.ProcessEnv;
+export declare const runPostDeployCommand: (hook: PostDeployHook, context: PostDeployContext, signal?: AbortSignal) => Promise<PostDeployResult>;

package/dist/release/postDeploy.js

@@ -0,0 +1,62 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+const MAX_OUTPUT_CHARS = 4_000;
+const MAX_TIMEOUT_MS = 24 * 3_600_000;
+export const resolvePostDeployHook = (options) => {
+    if (options.postDeployCommand === undefined) {
+        if (options.postDeployArg?.length)
+            throw new Error("--post-deploy-arg needs --post-deploy-command");
+        return null;
+    }
+    if (!path.isAbsolute(options.postDeployCommand))
+        throw new Error("--post-deploy-command must be an absolute path to an executable");
+    if (options.timeoutMs > MAX_TIMEOUT_MS)
+        throw new Error("--post-deploy-timeout must be at most 24h");
+    return { args: options.postDeployArg ?? [], command: options.postDeployCommand, timeoutMs: options.timeoutMs };
+};
+export const postDeployEnvironment = (context, env = process.env) => ({
+    ...env,
+    SPAWNFILE_RELEASE_CONTAINER: context.containerName,
+    SPAWNFILE_RELEASE_DEPLOYMENT: context.deployment,
+    SPAWNFILE_RELEASE_IDENTITY: context.identity,
+    SPAWNFILE_RELEASE_IMAGE: context.imageTag,
+    SPAWNFILE_RELEASE_IMAGE_ID: context.imageId
+});
+/** Keeps the tail: the end of a failing script's output is where it says why. */
+const appendBounded = (current, chunk) => {
+    const next = current + chunk;
+    return next.length > MAX_OUTPUT_CHARS ? next.slice(next.length - MAX_OUTPUT_CHARS) : next;
+};
+/** Kills the hook's whole process group: a descendant holding its pipes must not outlive it. */
+const killGroup = (pid) => {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch { /* already gone */ }
+};
+export const runPostDeployCommand = (hook, context, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(new Error("aborted before the post-deploy command started"));
+        return;
+    }
+    let output = "";
+    let timedOut = false;
+    // Its own process group, so a timeout or abort reaches every descendant.
+    const child = spawn(hook.command, hook.args, { detached: true, env: postDeployEnvironment(context), stdio: ["ignore", "pipe", "pipe"] });
+    const kill = () => { killGroup(child.pid); };
+    const timer = setTimeout(() => { timedOut = true; kill(); }, hook.timeoutMs);
+    signal?.addEventListener("abort", kill, { once: true });
+    const done = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", kill);
+    };
+    const collect = (chunk) => { output = appendBounded(output, chunk.toString("utf8")); };
+    child.stdout.on("data", collect);
+    child.stderr.on("data", collect);
+    child.once("error", (error) => { done(); reject(error); });
+    // Leftover descendants would hold the pipes open and delay `close` forever.
+    child.once("exit", () => { killGroup(child.pid); });
+    child.once("close", (code) => { done(); resolve({ exitCode: code, output, timedOut }); });
+});

package/dist/release/releaseDefaults.d.ts

@@ -0,0 +1,9 @@
+import type { ReleaseDependencies } from "./releaseTypes.js";
+/**
+ * The production effects. The identity is the Docker build-context digest the
+ * build cache already keys on: a function of everything the image is built
+ * from (compiled workspaces, bundles, runtime installs, target architecture),
+ * so a change that does not reach the image does not release, and one that
+ * does always does.
+ */
+export declare const createDefaultReleaseDependencies: () => ReleaseDependencies;

package/dist/release/releaseDefaults.js

@@ -0,0 +1,115 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { performance } from "node:perf_hooks";
+import { promisify } from "node:util";
+import { buildCompiledProject, createDefaultImageTag, resolveDockerBuildArchitecture, resolveImageTagRoot } from "../compiler/buildProject.js";
+import { compileProject } from "../compiler/compileProject.js";
+import { createDockerBuildContextDigest } from "../compiler/dockerBuildContext.js";
+import { inspectDockerImage } from "../compiler/dockerBuildSkip.js";
+import { requireAuthProfile } from "../auth/index.js";
+import { readRunEnvFile } from "../compiler/runProjectAuth.js";
+import { acquireHomeDeploymentLock, resolveDockerDeploymentTarget, verifyDockerDeploymentTarget } from "../deployment/index.js";
+import { consumeImageUp, createConsumerDockerRunner, extractImageReport, resolveDockerBaseArgs } from "../distribution/index.js";
+import { helperControlCall, requestDrain, requestResume, waitForDrained } from "./drainControl.js";
+import { sendNotification } from "./notify.js";
+import { runPostDeployCommand } from "./postDeploy.js";
+import { inspectUnit, pruneReleaseImages, settleUnit } from "./releaseDocker.js";
+const execFile = promisify(execFileCallback);
+const dockerFor = (request) => createConsumerDockerRunner(request.dockerCommand, resolveDockerBaseArgs({
+    ...(request.dockerContext ? { dockerContext: request.dockerContext } : {}),
+    ...(request.dockerHost ? { dockerHost: request.dockerHost } : {})
+}));
+/**
+ * The production effects. The identity is the Docker build-context digest the
+ * build cache already keys on: a function of everything the image is built
+ * from (compiled workspaces, bundles, runtime installs, target architecture),
+ * so a change that does not reach the image does not release, and one that
+ * does always does.
+ */
+export const createDefaultReleaseDependencies = () => ({
+    async build(request, compiled, imageTag) {
+        const result = await buildCompiledProject(request.inputPath, compiled.compileResult, {
+            contextDigest: compiled.identity,
+            dockerCommand: request.dockerCommand,
+            ...(request.dockerContext ? { dockerContext: request.dockerContext } : {}),
+            imageTag
+        });
+        const image = await inspectDockerImage({ dockerCommand: request.dockerCommand, dockerContext: request.dockerContext ?? null, imageTag });
+        if (image === null)
+            throw new Error(`built image ${imageTag} cannot be inspected`);
+        return { buildMs: result.imageBuild?.buildMs ?? null, imageId: image.id, imageTag, skipped: result.imageBuild?.skipped ?? false };
+    },
+    async compile(request) {
+        const started = performance.now();
+        const containerArchitecture = await resolveDockerBuildArchitecture({
+            dockerCommand: request.dockerCommand,
+            ...(request.dockerContext ? { dockerContext: request.dockerContext } : {})
+        });
+        const compileResult = await compileProject(request.inputPath, {
+            bundleIdentity: request.bundleIdentity,
+            ...(containerArchitecture ? { containerArchitecture } : {}),
+            ...(request.outputDirectory ? { outputDirectory: request.outputDirectory } : {})
+        });
+        const identity = await createDockerBuildContextDigest(compileResult.outputDirectory);
+        return {
+            compileMs: performance.now() - started,
+            compileResult,
+            identity,
+            repository: request.imageRepository ?? createDefaultImageTag(resolveImageTagRoot(request.inputPath))
+        };
+    },
+    async deploy(request, imageTag) {
+        const started = performance.now();
+        const result = await consumeImageUp(imageTag, {
+            authProfile: request.authProfile ?? null,
+            authProfileName: request.authProfileName ?? null,
+            authValues: request.authProfile?.env ?? {},
+            deploymentLockHeld: true,
+            deploymentName: request.deployment,
+            dockerCommand: request.dockerCommand,
+            ...(request.dockerContext ? { dockerContext: request.dockerContext } : {}),
+            ...(request.dockerHost ? { dockerHost: request.dockerHost } : {}),
+            envFileEnv: request.envFileEnv,
+            envFilePath: request.envFilePath ?? null,
+            now: request.now
+        });
+        return { containerName: result.containerName, deployMs: performance.now() - started };
+    },
+    inspectUnit: (request, containerRef) => inspectUnit(dockerFor(request), containerRef),
+    notify: (config, notification) => sendNotification(config, notification),
+    prune: (request, repository, keep) => pruneReleaseImages(dockerFor(request), repository, keep),
+    lockDeployment: (deployment) => acquireHomeDeploymentLock(deployment),
+    async prepare(request) {
+        return {
+            authProfile: request.authProfileName ? await requireAuthProfile(request.authProfileName) : null,
+            envFileEnv: await readRunEnvFile(request.envFilePath)
+        };
+    },
+    async runtimesOf(request, imageId) {
+        const inspection = await extractImageReport(imageId, {
+            dockerCommand: request.dockerCommand,
+            ...(request.dockerContext ? { dockerContext: request.dockerContext } : {}),
+            ...(request.dockerHost ? { dockerHost: request.dockerHost } : {})
+        });
+        return inspection.report.runtime_instances.map((instance) => instance.runtime);
+    },
+    requestDrain: (target) => requestDrain(target, helperControlCall),
+    async pinTarget(request) {
+        // Not the deployment record's target: image-mode `up` runs Docker against
+        // the explicit context or the CLI's own default and only records a target,
+        // so the record can name a daemon the deployment does not live on.
+        if (request.dockerContext)
+            return resolveDockerDeploymentTarget({ context: request.dockerContext, dockerCommand: request.dockerCommand });
+        if (process.env.DOCKER_HOST?.trim())
+            return resolveDockerDeploymentTarget({ dockerCommand: request.dockerCommand });
+        // What a bare `docker` command would use: DOCKER_CONTEXT, else the selected context.
+        const { stdout } = await execFile(request.dockerCommand, ["context", "show"], { timeout: 10_000 });
+        return resolveDockerDeploymentTarget({ context: stdout.trim() || "default", dockerCommand: request.dockerCommand });
+    },
+    async verifyTarget(request, target) {
+        await verifyDockerDeploymentTarget(target, { dockerCommand: request.dockerCommand });
+    },
+    requestResume: (target) => requestResume(target, helperControlCall),
+    runPostDeploy: (request, hook, context) => runPostDeployCommand(hook, context, request.signal),
+    settle: (request, containerRef) => settleUnit(dockerFor(request), containerRef, request.settle),
+    waitForDrained: (target, options) => waitForDrained(target, { call: helperControlCall, ...options })
+});

package/dist/release/releaseDocker.d.ts

@@ -0,0 +1,38 @@
+import type { DockerCommandRunner } from "../distribution/dockerRunner.js";
+/** Release images are `<repository>:r-<first 12 hex of the identity>`. */
+export declare const RELEASE_TAG_PREFIX = "r-";
+export declare const releaseImageTag: (repository: string, identity: string) => string;
+export interface RunningUnit {
+    health: string;
+    id: string;
+    imageId: string;
+    restartCount: number;
+    running: boolean;
+}
+/** Null when the container does not exist; a container that exists but cannot be parsed is an error. */
+export declare const inspectUnit: (runDocker: DockerCommandRunner, containerRef: string) => Promise<RunningUnit | null>;
+export interface SettleOptions {
+    pollMs: number;
+    polls: number;
+    sleep?: (ms: number) => Promise<void>;
+    stablePolls: number;
+}
+/**
+ * Started is not working. A container that is "running (health: starting)"
+ * has proved nothing, and a crash-looping one reports `running` between
+ * restarts, so this waits until the same healthy observation, restart count
+ * included, holds for `stablePolls` consecutive polls.
+ */
+export declare const settleUnit: (runDocker: DockerCommandRunner, containerRef: string, options: SettleOptions) => Promise<RunningUnit>;
+export interface PruneResult {
+    kept: string[];
+    removed: string[];
+    skipped: string[];
+}
+/**
+ * Bounded disk: keeps the running image and one rollback, removes every other
+ * release tag of this repository. Only ever touches `<repository>:r-*` tags a
+ * release created, never an image any container (running or stopped, any
+ * deployment) still uses, never a volume, never build cache, never `prune`.
+ */
+export declare const pruneReleaseImages: (runDocker: DockerCommandRunner, repository: string, keepTags: readonly (string | null | undefined)[]) => Promise<PruneResult>;

package/dist/release/releaseDocker.js

@@ -0,0 +1,94 @@
+import { ReleaseError } from "./types.js";
+/** Release images are `<repository>:r-<first 12 hex of the identity>`. */
+export const RELEASE_TAG_PREFIX = "r-";
+export const releaseImageTag = (repository, identity) => `${repository}:${RELEASE_TAG_PREFIX}${identity.replace(/^sha256:/u, "").slice(0, 12)}`;
+// `.State.Health` is absent (not null) without a healthcheck, and Go templates
+// fail on a missing map key, so the whole State object is read and parsed here.
+const INSPECT_FORMAT = "{{json .Id}}\t{{json .Image}}\t{{json .State}}\t{{json .RestartCount}}";
+/** Null when the container does not exist; a container that exists but cannot be parsed is an error. */
+export const inspectUnit = async (runDocker, containerRef) => {
+    let raw;
+    try {
+        raw = (await runDocker(["container", "inspect", "--format", INSPECT_FORMAT, containerRef], { timeoutMs: 15_000 })).toString("utf8").trim();
+    }
+    catch (error) {
+        if (/no such (container|object)/iu.test(error.message))
+            return null;
+        throw new ReleaseError("blocked", `cannot inspect container ${containerRef}: ${error.message.slice(0, 200)}`);
+    }
+    try {
+        const [id, imageId, state, restarts] = raw.split("\t").map((field) => JSON.parse(field));
+        const { Health: health, Running: running } = (state ?? {});
+        const status = health === undefined || health === null ? "none" : health.Status;
+        if (typeof id !== "string" || typeof imageId !== "string" || typeof running !== "boolean" || typeof status !== "string" || typeof restarts !== "number")
+            throw new Error();
+        return { health: status, id, imageId, restartCount: restarts, running };
+    }
+    catch {
+        throw new ReleaseError("blocked", `container ${containerRef} returned an unreadable inspection`);
+    }
+};
+/**
+ * Started is not working. A container that is "running (health: starting)"
+ * has proved nothing, and a crash-looping one reports `running` between
+ * restarts, so this waits until the same healthy observation, restart count
+ * included, holds for `stablePolls` consecutive polls.
+ */
+export const settleUnit = async (runDocker, containerRef, options) => {
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    let last = null;
+    let stable = 0;
+    let observed = null;
+    for (let poll = 0; poll < options.polls; poll += 1) {
+        let failure = null;
+        observed = await inspectUnit(runDocker, containerRef).catch((error) => { failure = error.message.slice(0, 160); return null; });
+        const healthy = observed !== null && observed.running && (observed.health === "healthy" || observed.health === "none");
+        const key = observed ? `${observed.id} ${observed.running} ${observed.health} ${observed.restartCount}` : failure ?? "missing";
+        stable = healthy && key === last ? stable + 1 : healthy ? 1 : 0;
+        last = key;
+        if (stable >= options.stablePolls)
+            return observed;
+        if (poll + 1 < options.polls)
+            await sleep(options.pollMs);
+    }
+    throw new ReleaseError("health-failed", `the deployed container never settled healthy; last observed: ${last ?? "nothing"}`);
+};
+const inUseImageIds = async (runDocker) => {
+    const ids = (await runDocker(["ps", "-a", "-q", "--no-trunc"])).toString("utf8").split("\n").map((line) => line.trim()).filter(Boolean);
+    if (ids.length === 0)
+        return new Set();
+    const images = (await runDocker(["container", "inspect", "--format", "{{.Image}}", ...ids])).toString("utf8");
+    return new Set(images.split("\n").map((line) => line.trim()).filter(Boolean));
+};
+/**
+ * Bounded disk: keeps the running image and one rollback, removes every other
+ * release tag of this repository. Only ever touches `<repository>:r-*` tags a
+ * release created, never an image any container (running or stopped, any
+ * deployment) still uses, never a volume, never build cache, never `prune`.
+ */
+export const pruneReleaseImages = async (runDocker, repository, keepTags) => {
+    const keep = new Set(keepTags.filter((tag) => typeof tag === "string"));
+    const listed = (await runDocker(["image", "ls", repository, "--no-trunc", "--format", "{{.Tag}}\t{{.ID}}"])).toString("utf8")
+        .split("\n").map((line) => line.trim().split("\t")).filter((row) => row.length === 2 && row[0].startsWith(RELEASE_TAG_PREFIX));
+    const used = await inUseImageIds(runDocker);
+    const result = { kept: [], removed: [], skipped: [] };
+    for (const [tag, id] of listed) {
+        const ref = `${repository}:${tag}`;
+        if (keep.has(ref)) {
+            result.kept.push(ref);
+            continue;
+        }
+        if (used.has(id)) {
+            result.skipped.push(ref);
+            continue;
+        }
+        try {
+            await runDocker(["image", "rm", ref]);
+            result.removed.push(ref);
+        }
+        catch {
+            result.skipped.push(ref);
+        }
+    }
+    return result;
+};

package/dist/release/releaseTypes.d.ts

@@ -0,0 +1,94 @@
+import type { ResolvedAuthProfile } from "../auth/index.js";
+import type { CompileProjectResult } from "../compiler/compileProject.js";
+import type { DockerDeploymentTarget } from "../deployment/index.js";
+import type { Availability, DrainWait, RuntimeControlTarget, WaitForDrainedOptions } from "./drainControl.js";
+import type { NotifierConfig, NotifyResult, ReleaseNotification } from "./notify.js";
+import type { PostDeployContext, PostDeployHook, PostDeployResult } from "./postDeploy.js";
+import type { PruneResult, RunningUnit, SettleOptions } from "./releaseDocker.js";
+export declare const DAIMON_CONTROL_TOKEN_ENV = "SPAWNFILE_DAIMON_CONTROL_TOKEN";
+export interface ReleaseRequest {
+    authProfile?: ResolvedAuthProfile | null;
+    authProfileName?: string | null;
+    /** `release` (default) builds workspace bundles only from clean committed inputs. */
+    bundleIdentity: "dev" | "release";
+    deployment: string;
+    dockerCommand: string;
+    dockerContext?: string;
+    /** Set from the pinned target when it is a `DOCKER_HOST` daemon. */
+    dockerHost?: string;
+    /** False only when the operator explicitly accepts killing in-flight turns. */
+    drain: boolean;
+    drainPollMs: number;
+    drainTimeoutMs: number;
+    envFileEnv: Record<string, string>;
+    envFilePath?: string;
+    force: boolean;
+    imageRepository?: string;
+    inputPath: string;
+    log: (line: string) => void;
+    notifier: NotifierConfig;
+    notifyDeferredAfterMs: number;
+    now?: () => Date;
+    outputDirectory?: string;
+    /** Runs once the new container settled and admits; must exit 0 before the release is recorded. */
+    postDeploy?: PostDeployHook | null;
+    /** Overrides `<SPAWNFILE_HOME>/releases`. */
+    releaseRoot?: string;
+    settle: SettleOptions;
+    signal?: AbortSignal;
+    /** The Docker daemon every step of this release talks to, pinned once at the start. */
+    target?: DockerDeploymentTarget;
+}
+export interface CompiledRelease {
+    compileMs: number;
+    compileResult: CompileProjectResult;
+    identity: string;
+    repository: string;
+}
+export interface BuiltRelease {
+    buildMs: number | null;
+    imageId: string;
+    imageTag: string;
+    skipped: boolean;
+}
+export interface DeployedRelease {
+    containerName: string;
+    deployMs: number;
+}
+export interface PreparedInputs {
+    authProfile: ResolvedAuthProfile | null;
+    envFileEnv: Record<string, string>;
+}
+/**
+ * Every effect a release has, injectable so the ORDER (drain before deploy,
+ * resume on abort, never deploy on a drain timeout) is asserted by tests
+ * rather than by a comment.
+ */
+export interface ReleaseDependencies {
+    build(request: ReleaseRequest, compiled: CompiledRelease, imageTag: string): Promise<BuiltRelease>;
+    compile(request: ReleaseRequest): Promise<CompiledRelease>;
+    /** Deploys while the caller holds the deployment lock (see `lockDeployment`). */
+    deploy(request: ReleaseRequest, imageTag: string): Promise<DeployedRelease>;
+    inspectUnit(request: ReleaseRequest, containerRef: string): Promise<RunningUnit | null>;
+    /** The same home lock `up` takes, held from the drain through the swap. */
+    lockDeployment(deployment: string): Promise<() => Promise<void>>;
+    notify(config: NotifierConfig, notification: ReleaseNotification): Promise<NotifyResult>;
+    /** Reads the env file and auth profile inside the release, so their failures are reported like any other. */
+    prepare(request: ReleaseRequest): Promise<PreparedInputs>;
+    prune(request: ReleaseRequest, repository: string, keep: readonly (string | null)[]): Promise<PruneResult>;
+    /** Runtime kinds inside the running image, from its embedded distribution report. */
+    runtimesOf(request: ReleaseRequest, imageId: string): Promise<string[]>;
+    requestDrain(target: RuntimeControlTarget): Promise<Availability>;
+    /**
+     * The Docker daemon this release talks to, with its endpoint fingerprint:
+     * an explicit `--context`, else what the Docker CLI would use
+     * (`DOCKER_HOST`, `DOCKER_CONTEXT` or the selected context).
+     */
+    pinTarget(request: ReleaseRequest): Promise<DockerDeploymentTarget>;
+    /** Throws when a recorded target's endpoint is no longer the one its name resolves to. */
+    verifyTarget(request: ReleaseRequest, target: DockerDeploymentTarget): Promise<void>;
+    requestResume(target: RuntimeControlTarget): Promise<Availability>;
+    runPostDeploy(request: ReleaseRequest, hook: PostDeployHook, context: PostDeployContext): Promise<PostDeployResult>;
+    settle(request: ReleaseRequest, containerRef: string): Promise<RunningUnit>;
+    waitForDrained(target: RuntimeControlTarget, options: WaitForDrainedOptions): Promise<DrainWait>;
+}

package/dist/release/releaseTypes.js

@@ -0,0 +1 @@
+export const DAIMON_CONTROL_TOKEN_ENV = "SPAWNFILE_DAIMON_CONTROL_TOKEN";

package/dist/release/runRelease.d.ts

@@ -0,0 +1,9 @@
+import { type ReleaseDependencies, type ReleaseRequest } from "./releaseTypes.js";
+import { type ReleaseOutcome } from "./types.js";
+/**
+ * compile → identity → (unchanged? stop) → build → drain → deploy → settle →
+ * resume → post-deploy → record → prune. The ledger is written last because it claims
+ * "this identity is RUNNING"; written earlier it would claim a container that
+ * never came up, and the next run would see nothing to do.
+ */
+export declare const runRelease: (request: ReleaseRequest, deps: ReleaseDependencies) => Promise<ReleaseOutcome>;