@podosoft/podokit 0.16.4 → 0.17.1

package/dist/deploy-compose-render.js

@@ -0,0 +1,333 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serviceName = serviceName;
+exports.derivedRuntimeConfig = derivedRuntimeConfig;
+exports.rolloutStateDigest = rolloutStateDigest;
+exports.renderComposeDocument = renderComposeDocument;
+exports.renderMigrationDocument = renderMigrationDocument;
+exports.defaultComposeImages = defaultComposeImages;
+exports.renderComposeDeployment = renderComposeDeployment;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const deploy_schema_1 = require("./deploy-schema");
+/** The internal port every generated application service listens on. */
+const CONTAINER_PORT = 3000;
+function quote(value) {
+    return JSON.stringify(value);
+}
+function digest(parts) {
+    const hash = (0, node_crypto_1.createHash)("sha256");
+    for (const part of parts)
+        hash.update(part).update("\0");
+    return `sha256:${hash.digest("hex")}`;
+}
+function serviceName(profile, role) {
+    return `${profile.target.project}-${role}`;
+}
+/**
+ * Configuration PodoKit derives rather than accepts, so a profile cannot point the
+ * app at the wrong service or port.
+ */
+function derivedRuntimeConfig(profile) {
+    const result = {
+        PORT: String(CONTAINER_PORT),
+        BACKEND_INTERNAL_URL: `http://${serviceName(profile, "api")}:${CONTAINER_PORT}`,
+        ...profile.runtimeConfig,
+    };
+    if (profile.dependencies.postgres.mode === "managed") {
+        result.POSTGRES_HOST = serviceName(profile, "postgres");
+        result.POSTGRES_PORT = "5432";
+    }
+    if (profile.dependencies.redis.mode === "managed") {
+        result.REDIS_HOST = serviceName(profile, "redis");
+        result.REDIS_PORT = "6379";
+    }
+    if (profile.dependencies.objectStorage.mode === "managed") {
+        result.S3_ENDPOINT = `http://${serviceName(profile, "object-storage")}:9000`;
+        result.S3_BUCKET = profile.dependencies.objectStorage.bucket;
+        result.S3_FORCE_PATH_STYLE = "true";
+    }
+    return result;
+}
+function sortedEnvironment(config) {
+    return Object.entries(config).sort(([left], [right]) => left.localeCompare(right));
+}
+function environmentBlock(config, indent) {
+    const entries = sortedEnvironment(config);
+    if (!entries.length)
+        return "";
+    return `${indent}environment:\n${entries
+        .map(([key, value]) => `${indent}  ${key}: ${quote(value)}`)
+        .join("\n")}\n`;
+}
+/**
+ * Identity of everything the containers read but Compose cannot see a change in.
+ *
+ * Compose recreates a container when its definition changes; it has no idea an env
+ * file on the host was edited. Stamping this digest as a label makes an edited
+ * secret or a changed runtime config a definition change, so `up` actually rolls
+ * the containers instead of leaving stale values running.
+ */
+function rolloutStateDigest(profile, secretIdentities) {
+    return digest([
+        "compose-rollout-state",
+        JSON.stringify(sortedEnvironment(derivedRuntimeConfig(profile))),
+        JSON.stringify(Object.entries(secretIdentities).sort(([l], [r]) => l.localeCompare(r))),
+    ]);
+}
+function resourceBlock(workload, indent) {
+    return (`${indent}deploy:\n` +
+        `${indent}  replicas: ${workload.replicas}\n` +
+        `${indent}  resources:\n` +
+        `${indent}    limits:\n` +
+        `${indent}      cpus: ${quote(workload.resources.cpuLimit)}\n` +
+        `${indent}      memory: ${workload.resources.memoryLimit}\n`);
+}
+/**
+ * An HTTP readiness probe that needs nothing the runtime image does not already
+ * have. The application images are Node, and Node 22 has a global `fetch`, so this
+ * avoids making `curl` or `wget` a deployment dependency.
+ */
+function httpHealthcheck(path, indent) {
+    const probe = `fetch('http://127.0.0.1:${CONTAINER_PORT}${path}')` +
+        `.then((r) => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))`;
+    return (`${indent}healthcheck:\n` +
+        `${indent}  test: ["CMD", "node", "-e", ${quote(probe)}]\n` +
+        `${indent}  interval: 10s\n` +
+        `${indent}  timeout: 5s\n` +
+        `${indent}  retries: 6\n` +
+        `${indent}  start_period: 30s\n`);
+}
+function labelsBlock(profile, release, stateDigest, indent) {
+    return (`${indent}labels:\n` +
+        `${indent}  io.podokit.project: ${quote(profile.target.project)}\n` +
+        `${indent}  io.podokit.release: ${quote(release)}\n` +
+        `${indent}  io.podokit.rollout-state: ${quote(stateDigest)}\n`);
+}
+function dependencyService(profile, role, dependency, image, extra) {
+    return (`  ${serviceName(profile, role)}:\n` +
+        `    image: ${quote(image)}\n` +
+        `    restart: unless-stopped\n` +
+        (extra.command ? `    command: ${extra.command}\n` : "") +
+        `    env_file:\n      - ${quote(dependency.envFile)}\n` +
+        `    volumes:\n      - ${quote(`${dependency.volume}:${extra.dataPath}`)}\n` +
+        `    networks: [${profile.target.project}]\n` +
+        extra.healthcheck);
+}
+function postgresService(profile, image) {
+    return dependencyService(profile, "postgres", profile.dependencies.postgres, image, {
+        dataPath: "/var/lib/postgresql/data",
+        healthcheck: `    healthcheck:\n` +
+            `      test: ["CMD-SHELL", "pg_isready -U \\"$$POSTGRES_USER\\" -d \\"$$POSTGRES_DB\\""]\n` +
+            `      interval: 10s\n      timeout: 5s\n      retries: 10\n      start_period: 20s\n`,
+    });
+}
+function redisService(profile, image) {
+    return dependencyService(profile, "redis", profile.dependencies.redis, image, {
+        dataPath: "/data",
+        // Authenticated and durable, matching what the Kubernetes driver renders.
+        command: `["sh", "-c", ${quote('exec redis-server --appendonly yes --requirepass "$$REDIS_PASSWORD"')}]`,
+        healthcheck: `    healthcheck:\n` +
+            `      test: ["CMD-SHELL", "redis-cli -a \\"$$REDIS_PASSWORD\\" ping | grep -q PONG"]\n` +
+            `      interval: 10s\n      timeout: 5s\n      retries: 10\n      start_period: 10s\n`,
+    });
+}
+function objectStorageService(profile, image) {
+    return dependencyService(profile, "object-storage", profile.dependencies.objectStorage, image, {
+        dataPath: "/data",
+        command: `["server", "/data", "--address", ":9000", "--console-address", ":9001"]`,
+        healthcheck: `    healthcheck:\n` +
+            `      test: ["CMD", "mc", "ready", "local"]\n` +
+            `      interval: 10s\n      timeout: 5s\n      retries: 10\n      start_period: 15s\n`,
+    });
+}
+/**
+ * Creates the bucket and a least-privilege application user, then exits. Compose
+ * runs it as a normal service with `restart: "no"`, which is the closest thing it
+ * has to a Job.
+ */
+function objectStorageInitService(profile, clientImage) {
+    const storage = profile.dependencies.objectStorage;
+    const endpoint = `http://${serviceName(profile, "object-storage")}:9000`;
+    // `$$` is Compose's escape: a single `$` would be substituted at parse time,
+    // from the environment of whoever runs compose, and these values only exist in
+    // the env file the container reads.
+    // The least-privilege policy the application user gets: its own bucket, nothing
+    // else. It is written here rather than referenced, because a policy file that the
+    // job does not create is a policy that never gets attached -- the user is then
+    // created with no permissions at all and every object operation fails, which
+    // surfaces as a readiness check that is down for no visible reason.
+    const policy = JSON.stringify({
+        Version: "2012-10-17",
+        Statement: [
+            {
+                Effect: "Allow",
+                Action: ["s3:*"],
+                Resource: [`arn:aws:s3:::${storage.bucket}`, `arn:aws:s3:::${storage.bucket}/*`],
+            },
+        ],
+    });
+    const script = [
+        "set -e",
+        `mc alias set podokit ${endpoint} "$$MINIO_ROOT_USER" "$$MINIO_ROOT_PASSWORD"`,
+        `mc mb --ignore-existing podokit/${storage.bucket}`,
+        `mc admin user add podokit "$$S3_ACCESS_KEY_ID" "$$S3_SECRET_ACCESS_KEY" || true`,
+        `printf '%s' '${policy}' > /tmp/podokit-policy.json`,
+        `mc admin policy create podokit podokit-app /tmp/podokit-policy.json || true`,
+        `mc admin policy attach podokit podokit-app --user "$$S3_ACCESS_KEY_ID" || true`,
+        // Prove the attachment, or the job reports success while the user still cannot
+        // read its own bucket. Checked with shell builtins only: the mc image is
+        // minimal and has no grep, so a pipeline into one exits 127 and takes the job
+        // down for the wrong reason.
+        `attached=$$(mc admin policy entities podokit --user "$$S3_ACCESS_KEY_ID")`,
+        `case "$$attached" in *podokit-app*) ;; *) echo "policy not attached" >&2; exit 1 ;; esac`,
+    ].join("\n");
+    return (`  ${serviceName(profile, "object-storage-init")}:\n` +
+        `    image: ${quote(clientImage)}\n` +
+        `    restart: "no"\n` +
+        `    depends_on:\n      ${serviceName(profile, "object-storage")}:\n        condition: service_healthy\n` +
+        `    env_file:\n      - ${quote(storage.envFile)}\n` +
+        `    entrypoint: ["sh", "-c", ${quote(script)}]\n` +
+        `    networks: [${profile.target.project}]\n`);
+}
+function applicationService(profile, role, image, release, stateDigest, options) {
+    const workload = role === "worker" ? profile.workloads.worker : profile.workloads[role];
+    if (!workload)
+        return "";
+    const envFile = role === "web" ? profile.secrets.web : profile.secrets.api;
+    // Service name -> the condition it must reach before this one starts.
+    const dependsOn = [];
+    if (profile.dependencies.postgres.mode === "managed" && role !== "web") {
+        dependsOn.push([serviceName(profile, "postgres"), "service_healthy"]);
+    }
+    if (profile.dependencies.redis.mode === "managed" && role !== "web") {
+        dependsOn.push([serviceName(profile, "redis"), "service_healthy"]);
+    }
+    if (profile.dependencies.objectStorage.mode === "managed" && role !== "web") {
+        // Not just "storage is up": the bucket and the application user's policy are
+        // created by the init service, and an API that starts before that finishes
+        // fails every object operation and reports itself unready.
+        dependsOn.push([serviceName(profile, "object-storage-init"), "service_completed_successfully"]);
+    }
+    if (role === "web")
+        dependsOn.push([serviceName(profile, "api"), "service_healthy"]);
+    return (`  ${serviceName(profile, role)}:\n` +
+        `    image: ${quote(image)}\n` +
+        `    restart: unless-stopped\n` +
+        (options.command ? `    command: ${options.command}\n` : "") +
+        (envFile ? `    env_file:\n      - ${quote(envFile.path)}\n` : "") +
+        environmentBlock(derivedRuntimeConfig(profile), "    ") +
+        (dependsOn.length
+            ? `    depends_on:\n${dependsOn
+                .map(([name, condition]) => `      ${name}:\n        condition: ${condition}\n`)
+                .join("")}`
+            : "") +
+        (options.publish
+            ? `    ports:\n      - ${quote(`${profile.exposure.bindAddress}:${profile.exposure.port}:${CONTAINER_PORT}`)}\n`
+            : "") +
+        `    networks: [${profile.target.project}]\n` +
+        resourceBlock(workload, "    ") +
+        (options.healthcheckPath
+            ? httpHealthcheck(options.healthcheckPath, "    ")
+            : // The worker runs the API image with a different entry point, and that image
+                // declares an HTTP healthcheck. A process with no HTTP server can never pass
+                // it, so the container reports unhealthy forever unless the inherited check
+                // is switched off here.
+                "    healthcheck:\n      disable: true\n") +
+        labelsBlock(profile, release, stateDigest, "    "));
+}
+function renderComposeDocument(profile, release, images, stateDigest) {
+    const services = [];
+    if (profile.dependencies.postgres.mode === "managed" && images.postgres) {
+        services.push(postgresService(profile, images.postgres));
+    }
+    if (profile.dependencies.redis.mode === "managed" && images.redis) {
+        services.push(redisService(profile, images.redis));
+    }
+    if (profile.dependencies.objectStorage.mode === "managed" && images.objectStorage) {
+        services.push(objectStorageService(profile, images.objectStorage));
+        if (images.objectStorageClient) {
+            services.push(objectStorageInitService(profile, images.objectStorageClient));
+        }
+    }
+    services.push(applicationService(profile, "api", images.api, release, stateDigest, {
+        healthcheckPath: "/health/ready",
+    }));
+    services.push(applicationService(profile, "web", images.web, release, stateDigest, {
+        healthcheckPath: "/",
+        publish: true,
+    }));
+    if (profile.workloads.worker) {
+        // The worker runs the API image with a different entry point, exactly as the
+        // Kubernetes driver does.
+        services.push(applicationService(profile, "worker", images.api, release, stateDigest, {
+            command: `["node", "dist/main-worker"]`,
+        }));
+    }
+    const volumes = [
+        ...(profile.dependencies.postgres.mode === "managed"
+            ? [profile.dependencies.postgres.volume]
+            : []),
+        ...(profile.dependencies.redis.mode === "managed" ? [profile.dependencies.redis.volume] : []),
+        ...(profile.dependencies.objectStorage.mode === "managed"
+            ? [profile.dependencies.objectStorage.volume]
+            : []),
+    ];
+    return (`# Generated by PodoKit. Do not edit; run "podo deploy render" to regenerate.\n` +
+        `name: ${profile.target.project}\n` +
+        `services:\n${services.filter(Boolean).join("")}` +
+        (volumes.length
+            ? `volumes:\n${volumes.map((name) => `  ${name}:\n    external: true\n`).join("")}`
+            : "") +
+        `networks:\n  ${profile.target.project}:\n    name: ${profile.target.project}\n`);
+}
+/**
+ * The migration runs as its own Compose project so it can be started, waited on,
+ * and removed without touching the running application definition.
+ */
+function renderMigrationDocument(profile, release, images) {
+    const command = profile.migration?.command ?? ["npm", "run", "migrate:all"];
+    return (`# Generated by PodoKit. One-shot migration for ${release}.\n` +
+        `name: ${profile.target.project}-migrate\n` +
+        `services:\n` +
+        `  migrate:\n` +
+        `    image: ${quote(images.api)}\n` +
+        `    restart: "no"\n` +
+        `    command: [${command.map((part) => quote(part)).join(", ")}]\n` +
+        `    env_file:\n      - ${quote(profile.secrets.api.path)}\n` +
+        environmentBlock(derivedRuntimeConfig(profile), "    ") +
+        `    networks: [${profile.target.project}]\n` +
+        `networks:\n  ${profile.target.project}:\n    name: ${profile.target.project}\n    external: true\n`);
+}
+function defaultComposeImages(profile, release) {
+    return {
+        api: `${profile.release.apiRepository}:${release}`,
+        web: `${profile.release.webRepository}:${release}`,
+        postgres: profile.dependencies.postgres.mode === "managed"
+            ? profile.dependencies.postgres.image
+            : null,
+        redis: profile.dependencies.redis.mode === "managed" ? profile.dependencies.redis.image : null,
+        objectStorage: profile.dependencies.objectStorage.mode === "managed"
+            ? profile.dependencies.objectStorage.image
+            : null,
+        objectStorageClient: profile.dependencies.objectStorage.mode === "managed"
+            ? profile.dependencies.objectStorage.clientImage
+            : null,
+    };
+}
+function renderComposeDeployment(projectRoot, profileName, profile, release, resolvedImages, stateDigest) {
+    (0, deploy_schema_1.profilePath)(projectRoot, profileName);
+    const images = resolvedImages ?? defaultComposeImages(profile, release);
+    const effectiveStateDigest = stateDigest ?? rolloutStateDigest(profile, {});
+    const root = (0, node_path_1.join)((0, node_path_1.resolve)(projectRoot), ".podokit", "runtime", "deploy", profileName);
+    (0, node_fs_1.rmSync)(root, { recursive: true, force: true });
+    (0, node_fs_1.mkdirSync)(root, { recursive: true });
+    const composeDocument = renderComposeDocument(profile, release, images, effectiveStateDigest);
+    const migrationDocument = renderMigrationDocument(profile, release, images);
+    const composeFile = (0, node_path_1.join)(root, "compose.yaml");
+    const migrationFile = (0, node_path_1.join)(root, "compose.migrate.yaml");
+    (0, node_fs_1.writeFileSync)(composeFile, composeDocument);
+    (0, node_fs_1.writeFileSync)(migrationFile, migrationDocument);
+    return { root, composeFile, migrationFile, composeDocument, migrationDocument };
+}

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

@@ -0,0 +1,144 @@
+import type { CommandRunner } from "./dev";
+/**
+ * Development-time artifact sync for the docker-compose driver.
+ *
+ * `podo deploy apply` replaces containers with a new image, which is the only way a
+ * release reaches users. That round trip has to build for the target's architecture,
+ * push to a registry, and roll out -- minutes, every time, and most of it is spent
+ * rebuilding dependencies that did not change. While *developing against* a
+ * deployment, the thing that actually changed is a few megabytes of compiled output.
+ *
+ * So this copies that output into the containers that are already running and
+ * restarts them. It is deliberately NOT a release:
+ *
+ * - The image tag does not change, so the deployment now runs code its tag does not
+ *   describe. A marker file records that, and `podo deploy status` reports it.
+ * - Nothing is pushed anywhere, so nothing is reproducible from it.
+ * - The next `apply` (or any container recreate) discards it, because container
+ *   writable layers do not survive recreation. That is the property that makes this
+ *   safe rather than a parallel deployment path: the drift heals itself.
+ *
+ * It refuses rather than warns whenever the copy would produce a container that
+ * cannot be trusted -- see the guards below.
+ */
+export type ComposeSyncRole = "api" | "web" | "worker";
+export interface ComposeSyncArtifact {
+    /** Project-relative source path. */
+    source: string;
+    /** Absolute path inside the container. */
+    destination: string;
+    kind: "directory" | "file";
+    roles: ComposeSyncRole[];
+}
+export interface ComposeSyncTarget {
+    role: ComposeSyncRole;
+    service: string;
+    container: string;
+    /** The image's configured user, so copied files can be given back to it. */
+    user: string | null;
+}
+export interface ComposeSyncPlan {
+    profile: string;
+    project: string;
+    artifacts: ComposeSyncArtifact[];
+    excluded: string[];
+    targets: ComposeSyncTarget[];
+    warnings: string[];
+}
+export interface ComposeSyncMarker {
+    syncedAt: string;
+    profile: string;
+    artifacts: string[];
+    note: string;
+}
+export interface ComposeSyncDrift {
+    container: string;
+    marker: ComposeSyncMarker;
+}
+export interface ComposeSyncResult {
+    plan: ComposeSyncPlan;
+    copied: Array<{
+        container: string;
+        source: string;
+        destination: string;
+    }>;
+    restarted: string[];
+    marker: ComposeSyncMarker;
+}
+export interface ComposeSyncOptions {
+    /** Build the artifacts before copying them, in the order the images build them. */
+    build?: boolean;
+    /** Empty each destination before copying, so deleted files do not linger. */
+    clean?: boolean;
+    /** Injected for tests; the marker records when the sync happened. */
+    now?: () => Date;
+    /** How long to wait for a restarted container to report healthy. */
+    healthTimeoutMs?: number;
+}
+interface PackageManifest {
+    dependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+}
+/**
+ * What the images ship outside their dependency tree.
+ *
+ * Every entry mirrors a `COPY --from=build` line in the generated Dockerfiles, which
+ * is what makes the copy equivalent to a rebuild for code-only changes. Two entries
+ * exist for a reason worth keeping:
+ *
+ * - `apps/web/server.js` and `apps/web/src/lib/server` ship as SOURCE, outside the
+ *   bundle, because the entry point has to run before the adapter does. Syncing only
+ *   `build/` would leave a stale entry running new routes.
+ * - `packages/*` are copied as real directories rather than the symlinks npm leaves
+ *   behind, so their `dist/` is a separate destination from the apps'.
+ *
+ * `node_modules` is deliberately absent: the image installs a production-only,
+ * workspace-scoped tree for its own platform, and a developer's tree is neither.
+ */
+export declare function composeSyncArtifacts(projectRoot: string): ComposeSyncArtifact[];
+/** The excludes that fall inside one artifact, as paths relative to it. */
+export declare function excludesWithin(artifact: ComposeSyncArtifact, excludes: string[]): string[];
+/**
+ * Whether the image's dependency tree can still run this code.
+ *
+ * Only the runtime dependency sets matter: `npm ci --omit=dev` installed what these
+ * declare and nothing else, so a change to any of them means the container is
+ * missing a package the new code imports -- a failure that surfaces as a crash loop
+ * after the restart rather than as a copy error. `devDependencies` are absent from
+ * the image by design and a `version` bump changes nothing at runtime, so neither
+ * takes part.
+ */
+export declare function runtimeDependenciesOf(manifest: PackageManifest): string;
+export declare function planComposeSync(projectRoot: string, profileName: string, runner?: CommandRunner): ComposeSyncPlan;
+export declare function syncComposeDeployment(projectRoot: string, profileName: string, options?: ComposeSyncOptions, runner?: CommandRunner): Promise<ComposeSyncResult>;
+/**
+ * Which containers are running synced artifacts rather than their image's.
+ *
+ * Reporting-only, so it never throws: `podo deploy status` folds this in, and a
+ * target that cannot answer right now is a reason to report less, not a reason for
+ * status to fail. An empty result therefore means "no drift found", which is also
+ * what an unreachable target produces -- the services list beside it already shows
+ * that case for what it is.
+ */
+export declare function readComposeSyncDrift(projectRoot: string, profileName: string, runner?: CommandRunner): ComposeSyncDrift[];
+/**
+ * Put the deployment back on its image.
+ *
+ * The release to restore comes from the ledger, and the project is rendered from
+ * that entry's own release, images and rollout state -- the same way a rollback
+ * reproduces a revision.
+ *
+ * ⚠ Not from the Compose file sitting on the target, which was the first attempt.
+ * That file is written by whichever command last ran a compose mutation, and one of
+ * them renders a placeholder release to obtain a file path. The revert then tried to
+ * pull an image tag that never existed and refused to recreate anything. Measured
+ * against a live deployment; the read path was fixed at the same time so a status
+ * call can no longer overwrite the target's project.
+ */
+export declare function revertComposeSync(projectRoot: string, profileName: string, runner?: CommandRunner): Promise<{
+    services: string[];
+    project: string;
+    release: string;
+}>;
+export {};