@podosoft/podokit 0.16.4 → 0.17.1

package/dist/deploy-compose-exec.d.ts

@@ -0,0 +1,93 @@
+import type { CommandRunner } from "./dev";
+import type { DockerComposeProfileV1 } from "./deploy-compose-profile";
+import type { ComposeImages, ComposeRuntime } from "./deploy-compose-render";
+/**
+ * The primitives every docker-compose driver action runs commands through.
+ *
+ * They live apart from the driver because more than one action needs them and
+ * because two of them encode a rule that is easy to get wrong: which machine a
+ * command has to run on. See `sshDestination` below.
+ */
+export declare function defaultRunner(command: string, args: string[], options: {
+    capture: boolean;
+}): ReturnType<CommandRunner>;
+export declare function checked(runner: CommandRunner, command: string, args: string[], capture?: boolean): string;
+export declare function parseJson<T>(value: string, description: string): T;
+export declare function dockerArgs(profile: DockerComposeProfileV1, args: string[]): string[];
+/**
+ * The SSH destination behind a `ssh://` Docker context, or null for a local one.
+ *
+ * This matters more than it looks. `docker compose` resolves `env_file` paths and
+ * expands `${VAR}` **where the CLI runs**, not where the daemon runs. Pointed at a
+ * remote context from a laptop, it looks for the host's secret files on the laptop,
+ * fails to find them, and interpolates every referenced variable to an empty string
+ * -- which is how a deployment silently comes up with a blank database password.
+ *
+ * So the Compose file is executed on the target instead: the whole point of keeping
+ * credentials in files on that host is that nothing else ever reads them.
+ */
+export declare function sshDestination(profile: DockerComposeProfileV1, runner: CommandRunner): string | null;
+/** Where the rendered project lives on the target when the context is remote. */
+export declare function remoteProjectDirectory(profile: DockerComposeProfileV1): string;
+/**
+ * Run `docker compose` where the Compose file's own references resolve.
+ *
+ * Local context: here. Remote context: on the target, after copying the rendered
+ * file across -- because `env_file` paths and `${...}` expansion are resolved by
+ * whoever runs compose, not by the daemon it talks to.
+ *
+ * ⚠ This OVERWRITES the project file on the target, so it is for mutations only.
+ * A read-only query must never come through here: `podo deploy status` renders with
+ * a placeholder release to get a file path, and routing its `ps` through this
+ * replaced the applied project on the target with one naming an image tag that does
+ * not exist. Nothing failed at the time -- the next `compose up` on that host did,
+ * with "artifact ...:v0.0.0 not found", long after the status call that caused it.
+ * Read-only queries use `composeProjectPs` below, which needs no file at all.
+ */
+export declare function runCompose(profile: DockerComposeProfileV1, runtime: Pick<ComposeRuntime, "composeFile" | "migrationFile">, file: "compose" | "migration", args: string[], runner: CommandRunner, capture: boolean): string;
+/**
+ * What the project is running, asked by project name rather than by file.
+ *
+ * Compose finds a project's containers from their labels, so this needs neither a
+ * rendered file nor a release tag -- and therefore cannot disturb the target. It
+ * also runs against the daemon through the context, so there is nothing here for
+ * `env_file` resolution to get wrong.
+ */
+export declare function composeProjectPs(profile: DockerComposeProfileV1, runner: CommandRunner): string;
+export declare const STATE_MOUNT = "/podokit-state";
+export declare const LOCK_PATH = "/podokit-state/deploy.lock";
+export declare const LEDGER_PATH = "/podokit-state/releases.json";
+export interface LedgerEntry {
+    revision: number;
+    release: string;
+    images: ComposeImages;
+    composeDocumentDigest: string;
+    rolloutStateDigest: string;
+}
+export interface Ledger {
+    schemaVersion: 1;
+    entries: LedgerEntry[];
+}
+export declare function currentLedgerEntry(ledger: Ledger): LedgerEntry | null;
+export declare function readLedger(profile: DockerComposeProfileV1, image: string, runner: CommandRunner): Ledger;
+export declare function stateVolumeName(profile: DockerComposeProfileV1): string;
+/**
+ * An image the target can pull, for the checks that need a shell on the host.
+ *
+ * The release image is the right one whenever a release is known -- it is the image
+ * about to run, so proving it pulls is part of the check. Without one (a bare
+ * `podo deploy doctor` before anything is published) fall back to a managed
+ * dependency image, which the profile already pins by digest and the deployment
+ * needs anyway. Fabricating a release tag would ask the registry for something that
+ * can never exist.
+ */
+export declare function probeImage(profile: DockerComposeProfileV1, release?: string): string | null;
+export declare function stateScript(profile: DockerComposeProfileV1, image: string, script: string): string[];
+/**
+ * Who holds the deployment lock, for actions that must not run during an apply.
+ *
+ * Returns null both when nothing holds it and when the lock cannot be read at all --
+ * a project with no managed dependency has no image to borrow a shell from, and
+ * refusing every other action because of that would be worse than not checking.
+ */
+export declare function composeLockHolder(profile: DockerComposeProfileV1, runner: CommandRunner): string | null;

package/dist/deploy-compose-exec.js

@@ -0,0 +1,198 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEDGER_PATH = exports.LOCK_PATH = exports.STATE_MOUNT = void 0;
+exports.defaultRunner = defaultRunner;
+exports.checked = checked;
+exports.parseJson = parseJson;
+exports.dockerArgs = dockerArgs;
+exports.sshDestination = sshDestination;
+exports.remoteProjectDirectory = remoteProjectDirectory;
+exports.runCompose = runCompose;
+exports.composeProjectPs = composeProjectPs;
+exports.currentLedgerEntry = currentLedgerEntry;
+exports.readLedger = readLedger;
+exports.stateVolumeName = stateVolumeName;
+exports.probeImage = probeImage;
+exports.stateScript = stateScript;
+exports.composeLockHolder = composeLockHolder;
+const node_child_process_1 = require("node:child_process");
+/**
+ * The primitives every docker-compose driver action runs commands through.
+ *
+ * They live apart from the driver because more than one action needs them and
+ * because two of them encode a rule that is easy to get wrong: which machine a
+ * command has to run on. See `sshDestination` below.
+ */
+function defaultRunner(command, args, options) {
+    const result = (0, node_child_process_1.spawnSync)(command, args, {
+        encoding: "utf8",
+        stdio: options.capture ? "pipe" : "inherit",
+    });
+    if (result.error)
+        throw result.error;
+    return {
+        status: result.status,
+        stdout: options.capture ? (result.stdout ?? "") : "",
+        stderr: options.capture ? (result.stderr ?? "") : "",
+    };
+}
+function checked(runner, command, args, capture = true) {
+    const result = runner(command, args, { capture });
+    if (result.status !== 0) {
+        const detail = capture ? result.stderr.trim() || result.stdout.trim() : "";
+        throw new Error(`${command} ${args.join(" ")} failed with status ${String(result.status)}${detail ? `: ${detail}` : ""}`);
+    }
+    return result.stdout;
+}
+function parseJson(value, description) {
+    if (!value.trim())
+        throw new Error(`${description} returned empty JSON.`);
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        throw new Error(`${description} returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function dockerArgs(profile, args) {
+    return ["--context", profile.target.context, ...args];
+}
+/**
+ * The SSH destination behind a `ssh://` Docker context, or null for a local one.
+ *
+ * This matters more than it looks. `docker compose` resolves `env_file` paths and
+ * expands `${VAR}` **where the CLI runs**, not where the daemon runs. Pointed at a
+ * remote context from a laptop, it looks for the host's secret files on the laptop,
+ * fails to find them, and interpolates every referenced variable to an empty string
+ * -- which is how a deployment silently comes up with a blank database password.
+ *
+ * So the Compose file is executed on the target instead: the whole point of keeping
+ * credentials in files on that host is that nothing else ever reads them.
+ */
+function sshDestination(profile, runner) {
+    const output = runner("docker", ["context", "inspect", profile.target.context, "--format", "{{.Endpoints.docker.Host}}"], { capture: true });
+    if (output.status !== 0)
+        return null;
+    const host = output.stdout.trim();
+    return host.startsWith("ssh://") ? host.slice("ssh://".length) : null;
+}
+/** Where the rendered project lives on the target when the context is remote. */
+function remoteProjectDirectory(profile) {
+    return `.local/share/podokit/${profile.target.project}`;
+}
+/**
+ * Run `docker compose` where the Compose file's own references resolve.
+ *
+ * Local context: here. Remote context: on the target, after copying the rendered
+ * file across -- because `env_file` paths and `${...}` expansion are resolved by
+ * whoever runs compose, not by the daemon it talks to.
+ *
+ * ⚠ This OVERWRITES the project file on the target, so it is for mutations only.
+ * A read-only query must never come through here: `podo deploy status` renders with
+ * a placeholder release to get a file path, and routing its `ps` through this
+ * replaced the applied project on the target with one naming an image tag that does
+ * not exist. Nothing failed at the time -- the next `compose up` on that host did,
+ * with "artifact ...:v0.0.0 not found", long after the status call that caused it.
+ * Read-only queries use `composeProjectPs` below, which needs no file at all.
+ */
+function runCompose(profile, runtime, file, args, runner, capture) {
+    const localFile = file === "compose" ? runtime.composeFile : runtime.migrationFile;
+    const destination = sshDestination(profile, runner);
+    if (!destination) {
+        return checked(runner, "docker", dockerArgs(profile, ["compose", "-f", localFile, ...args]), capture);
+    }
+    const directory = remoteProjectDirectory(profile);
+    const remoteFile = `${directory}/${file === "compose" ? "compose.yaml" : "compose.migrate.yaml"}`;
+    checked(runner, "ssh", [destination, `mkdir -p ${directory}`], true);
+    checked(runner, "scp", ["-q", localFile, `${destination}:${remoteFile}`], true);
+    return checked(runner, "ssh", [destination, ["docker", "compose", "-f", remoteFile, ...args].join(" ")], capture);
+}
+/**
+ * What the project is running, asked by project name rather than by file.
+ *
+ * Compose finds a project's containers from their labels, so this needs neither a
+ * rendered file nor a release tag -- and therefore cannot disturb the target. It
+ * also runs against the daemon through the context, so there is nothing here for
+ * `env_file` resolution to get wrong.
+ */
+function composeProjectPs(profile, runner) {
+    const result = runner("docker", dockerArgs(profile, ["compose", "-p", profile.target.project, "ps", "--format", "json"]), { capture: true });
+    return result.status === 0 ? result.stdout.trim() : "";
+}
+exports.STATE_MOUNT = "/podokit-state";
+exports.LOCK_PATH = `${exports.STATE_MOUNT}/deploy.lock`;
+exports.LEDGER_PATH = `${exports.STATE_MOUNT}/releases.json`;
+function currentLedgerEntry(ledger) {
+    return ledger.entries.length ? (ledger.entries[ledger.entries.length - 1] ?? null) : null;
+}
+function readLedger(profile, image, runner) {
+    const result = runner("docker", stateScript(profile, image, `cat ${exports.LEDGER_PATH} 2>/dev/null || echo ""`), { capture: true });
+    const body = result.status === 0 ? result.stdout.trim() : "";
+    if (!body)
+        return { schemaVersion: 1, entries: [] };
+    const parsed = parseJson(body, "Release ledger");
+    if (parsed.schemaVersion !== 1 || !Array.isArray(parsed.entries)) {
+        throw new Error("Release ledger is not a supported schema version 1 document.");
+    }
+    return parsed;
+}
+function stateVolumeName(profile) {
+    return `${profile.target.project}-podokit-state`;
+}
+/**
+ * An image the target can pull, for the checks that need a shell on the host.
+ *
+ * The release image is the right one whenever a release is known -- it is the image
+ * about to run, so proving it pulls is part of the check. Without one (a bare
+ * `podo deploy doctor` before anything is published) fall back to a managed
+ * dependency image, which the profile already pins by digest and the deployment
+ * needs anyway. Fabricating a release tag would ask the registry for something that
+ * can never exist.
+ */
+function probeImage(profile, release) {
+    if (release)
+        return `${profile.release.apiRepository}:${release}`;
+    for (const dependency of [
+        profile.dependencies.postgres,
+        profile.dependencies.redis,
+        profile.dependencies.objectStorage,
+    ]) {
+        if (dependency.mode === "managed")
+            return dependency.image;
+    }
+    return null;
+}
+function stateScript(profile, image, script) {
+    return dockerArgs(profile, [
+        "run",
+        "--rm",
+        "--network",
+        "none",
+        // The state volume is root-owned; the application images are not.
+        "--user",
+        "0:0",
+        "-v",
+        `${stateVolumeName(profile)}:${exports.STATE_MOUNT}`,
+        "--entrypoint",
+        "sh",
+        image,
+        "-c",
+        script,
+    ]);
+}
+/**
+ * Who holds the deployment lock, for actions that must not run during an apply.
+ *
+ * Returns null both when nothing holds it and when the lock cannot be read at all --
+ * a project with no managed dependency has no image to borrow a shell from, and
+ * refusing every other action because of that would be worse than not checking.
+ */
+function composeLockHolder(profile, runner) {
+    const probe = probeImage(profile);
+    if (!probe)
+        return null;
+    const result = runner("docker", stateScript(profile, probe, `cat ${exports.LOCK_PATH} 2>/dev/null || true`), { capture: true });
+    if (result.status !== 0)
+        return null;
+    return result.stdout.trim() || null;
+}

package/dist/deploy-compose-profile.d.ts

@@ -0,0 +1,107 @@
+import { MigrationProfile, ReleaseProfile, VerificationProfile } from "./deploy-schema";
+/**
+ * The Docker Compose deployment driver.
+ *
+ * Where the Kubernetes driver targets a cluster context and a namespace, this one
+ * targets a Docker context — which may be local or `ssh://` — and a Compose project.
+ * The boundary is the same in both: PodoKit operates the application, and never
+ * creates the host, the reverse proxy, the TLS certificate, or the secret values.
+ */
+export type ComposeDependencyMode = "managed" | "external" | "disabled";
+/**
+ * Compose resource ceilings, in the units the Compose spec uses rather than the
+ * Kubernetes ones: `cpus` is a decimal core count and `memory` a byte suffix.
+ */
+export interface ComposeResourceProfile {
+    cpuLimit: string;
+    memoryLimit: string;
+}
+export interface ComposeWorkloadProfile {
+    replicas: number;
+    resources: ComposeResourceProfile;
+}
+/**
+ * A dependency PodoKit runs as a Compose service. Its credentials live in an env
+ * file on the target host — the profile records only the path and the key names,
+ * exactly as the Kubernetes driver records only Secret names and key names.
+ */
+export interface ComposeDependencyProfile {
+    mode: ComposeDependencyMode;
+    image: string;
+    envFile: string;
+    requiredKeys: string[];
+    volume: string;
+}
+export interface ComposeObjectStorageProfile extends ComposeDependencyProfile {
+    bucket: string;
+    clientImage: string;
+}
+export interface ComposeEnvFileProfile {
+    path: string;
+    requiredKeys: string[];
+}
+/**
+ * Development-time artifact sync. Read only by `podo deploy sync`, never rendered
+ * into the Compose project — so adding it changes what that one command copies and
+ * nothing about what is deployed.
+ *
+ * `exclude` names project-relative paths the sync must leave alone. It exists
+ * because part of a build output can come from a toolchain the developer's machine
+ * does not have: overwriting that part with a local build replaces real artifacts
+ * with an index of artifacts that are no longer there, and the application keeps
+ * serving pages while the missing files 404.
+ */
+export interface ComposeSyncProfile {
+    exclude: string[];
+}
+export interface DockerComposeProfileV1 {
+    schemaVersion: 1;
+    driver: "docker-compose";
+    target: {
+        context: string;
+        endpointFingerprint: string;
+        project: string;
+    };
+    release: ReleaseProfile;
+    exposure: {
+        mode: "publishedPort";
+        host: string;
+        bindAddress: string;
+        port: number;
+    };
+    workloads: {
+        api: ComposeWorkloadProfile;
+        web: ComposeWorkloadProfile;
+        worker: ComposeWorkloadProfile | null;
+    };
+    dependencies: {
+        postgres: ComposeDependencyProfile;
+        redis: ComposeDependencyProfile;
+        objectStorage: ComposeObjectStorageProfile;
+    };
+    secrets: {
+        api: ComposeEnvFileProfile;
+        web: ComposeEnvFileProfile | null;
+        registryLogin: boolean;
+    };
+    migration?: MigrationProfile;
+    sync?: ComposeSyncProfile;
+    runtimeConfig: Record<string, string>;
+    verification: VerificationProfile;
+}
+export declare function parseComposeProfile(value: unknown): DockerComposeProfileV1;
+export interface InitializeComposeProfileOptions {
+    context: string;
+    endpointFingerprint: string;
+    host?: string;
+    /** Directory on the target host holding the env files the deployment reads. */
+    secretsDirectory?: string;
+}
+export declare function buildDefaultComposeProfile(projectName: string, options: InitializeComposeProfileOptions): DockerComposeProfileV1;
+export interface ComposeProfileSummary {
+    name: string;
+    path: string;
+    profile: DockerComposeProfileV1;
+}
+export declare function initializeComposeProfile(projectRoot: string, name: string, options: InitializeComposeProfileOptions): ComposeProfileSummary;
+export declare function composeProfileDigest(profile: DockerComposeProfileV1): string;