@podosoft/podokit 0.16.4 → 0.17.1

package/dist/deploy-compose-profile.js

@@ -0,0 +1,361 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseComposeProfile = parseComposeProfile;
+exports.buildDefaultComposeProfile = buildDefaultComposeProfile;
+exports.initializeComposeProfile = initializeComposeProfile;
+exports.composeProfileDigest = composeProfileDigest;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const lockfile_1 = require("./lockfile");
+const deploy_schema_1 = require("./deploy-schema");
+/** Decimal core count, e.g. "0.25" or "2". */
+const CPU_VALUE = /^(?:0\.[0-9]{1,3}|[1-9][0-9]{0,2}(?:\.[0-9]{1,3})?)$/;
+/** Compose byte suffix, e.g. "512m" or "2g". */
+const MEMORY_VALUE = /^[1-9][0-9]*[kmg]$/;
+/** A Compose project name: the same alphabet Compose itself accepts. */
+const PROJECT_NAME = /^[a-z0-9][a-z0-9_-]*$/;
+/** An absolute POSIX path on the target host, with no traversal or control bytes. */
+const ABSOLUTE_PATH = /^\/(?:[A-Za-z0-9._-]+\/?)+$/;
+const VOLUME_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+function validateCpu(value, field) {
+    if (!CPU_VALUE.test(value)) {
+        throw new Error(`Deployment profile field "${field}" must be a decimal CPU count.`);
+    }
+}
+function validateMemory(value, field) {
+    if (!MEMORY_VALUE.test(value)) {
+        throw new Error(`Deployment profile field "${field}" must be a Compose memory quantity.`);
+    }
+}
+function validateHostPath(value, field) {
+    if (!ABSOLUTE_PATH.test(value) || value.includes("..") || value.endsWith("/")) {
+        throw new Error(`Deployment profile field "${field}" must be an absolute path on the target host.`);
+    }
+}
+function parseComposeResources(value, field) {
+    (0, deploy_schema_1.assertOnlyKeys)(value, ["cpuLimit", "memoryLimit"], field);
+    const parsed = {
+        cpuLimit: (0, deploy_schema_1.requiredString)(value, "cpuLimit"),
+        memoryLimit: (0, deploy_schema_1.requiredString)(value, "memoryLimit"),
+    };
+    validateCpu(parsed.cpuLimit, `${field}.cpuLimit`);
+    validateMemory(parsed.memoryLimit, `${field}.memoryLimit`);
+    return parsed;
+}
+function parseComposeWorkload(value, field) {
+    (0, deploy_schema_1.assertOnlyKeys)(value, ["replicas", "resources"], field);
+    return {
+        replicas: (0, deploy_schema_1.requiredNumber)(value, "replicas"),
+        resources: parseComposeResources((0, deploy_schema_1.requiredRecord)(value, "resources"), `${field}.resources`),
+    };
+}
+function parseComposeMode(value, field) {
+    if (value !== "managed" && value !== "external" && value !== "disabled") {
+        throw new Error(`Deployment profile field "${field}" must be managed, external, or disabled.`);
+    }
+    return value;
+}
+function parseComposeDependency(value, field, extraKeys = []) {
+    (0, deploy_schema_1.assertOnlyKeys)(value, ["mode", "image", "envFile", "requiredKeys", "volume", ...extraKeys], field);
+    const parsed = {
+        mode: parseComposeMode(value.mode, `${field}.mode`),
+        image: (0, deploy_schema_1.requiredString)(value, "image"),
+        envFile: (0, deploy_schema_1.requiredString)(value, "envFile"),
+        requiredKeys: (0, deploy_schema_1.parseRequiredKeys)(value.requiredKeys, `${field}.requiredKeys`),
+        volume: (0, deploy_schema_1.requiredString)(value, "volume"),
+    };
+    (0, deploy_schema_1.validateImage)(parsed.image, `${field}.image`);
+    validateHostPath(parsed.envFile, `${field}.envFile`);
+    if (!VOLUME_NAME.test(parsed.volume)) {
+        throw new Error(`Deployment profile field "${field}.volume" must be a Docker volume name.`);
+    }
+    return parsed;
+}
+/** A project-relative POSIX path: no absolute paths, no traversal, no drift upward. */
+const PROJECT_RELATIVE_PATH = /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/;
+function parseSyncProfile(value, field) {
+    (0, deploy_schema_1.assertOnlyKeys)(value, ["exclude"], field);
+    const exclude = value.exclude;
+    if (!Array.isArray(exclude)) {
+        throw new Error(`Deployment profile field "${field}.exclude" must be a string array.`);
+    }
+    const parsed = exclude.map((entry, index) => {
+        if (typeof entry !== "string" ||
+            !PROJECT_RELATIVE_PATH.test(entry) ||
+            entry.split("/").includes("..")) {
+            throw new Error(`Deployment profile field "${field}.exclude[${index}]" must be a project-relative path.`);
+        }
+        return entry;
+    });
+    if (new Set(parsed).size !== parsed.length) {
+        throw new Error(`Deployment profile field "${field}.exclude" contains duplicate paths.`);
+    }
+    return { exclude: parsed.sort() };
+}
+function parseEnvFileProfile(value, field) {
+    if (!(0, deploy_schema_1.isRecord)(value))
+        throw new Error(`Deployment profile field "${field}" must be an object.`);
+    (0, deploy_schema_1.assertOnlyKeys)(value, ["path", "requiredKeys"], field);
+    const parsed = {
+        path: (0, deploy_schema_1.requiredString)(value, "path"),
+        requiredKeys: (0, deploy_schema_1.parseRequiredKeys)(value.requiredKeys, `${field}.requiredKeys`),
+    };
+    validateHostPath(parsed.path, `${field}.path`);
+    return parsed;
+}
+function parseComposeProfile(value) {
+    if (!(0, deploy_schema_1.isRecord)(value))
+        throw new Error("Deployment profile must be a JSON object.");
+    (0, deploy_schema_1.assertOnlyKeys)(value, [
+        "schemaVersion",
+        "driver",
+        "target",
+        "release",
+        "exposure",
+        "workloads",
+        "dependencies",
+        "secrets",
+        "migration",
+        "sync",
+        "runtimeConfig",
+        "verification",
+    ], "root");
+    if (value.schemaVersion !== 1) {
+        throw new Error(`Unsupported deployment profile schemaVersion: ${String(value.schemaVersion)}`);
+    }
+    if (value.driver !== "docker-compose") {
+        throw new Error(`Unsupported deployment driver: ${String(value.driver)}`);
+    }
+    const target = (0, deploy_schema_1.requiredRecord)(value, "target");
+    const exposure = (0, deploy_schema_1.requiredRecord)(value, "exposure");
+    const workloads = (0, deploy_schema_1.requiredRecord)(value, "workloads");
+    const dependencies = (0, deploy_schema_1.requiredRecord)(value, "dependencies");
+    const secrets = (0, deploy_schema_1.requiredRecord)(value, "secrets");
+    const migration = value.migration === undefined ? undefined : (0, deploy_schema_1.requiredRecord)(value, "migration");
+    const sync = value.sync === undefined ? undefined : (0, deploy_schema_1.requiredRecord)(value, "sync");
+    (0, deploy_schema_1.assertOnlyKeys)(target, ["context", "endpointFingerprint", "project"], "target");
+    (0, deploy_schema_1.assertOnlyKeys)(exposure, ["mode", "host", "bindAddress", "port"], "exposure");
+    (0, deploy_schema_1.assertOnlyKeys)(workloads, ["api", "web", "worker"], "workloads");
+    (0, deploy_schema_1.assertOnlyKeys)(dependencies, ["postgres", "redis", "objectStorage"], "dependencies");
+    (0, deploy_schema_1.assertOnlyKeys)(secrets, ["api", "web", "registryLogin"], "secrets");
+    if (migration)
+        (0, deploy_schema_1.assertOnlyKeys)(migration, ["command"], "migration");
+    const context = (0, deploy_schema_1.requiredString)(target, "context");
+    const endpointFingerprint = (0, deploy_schema_1.requiredString)(target, "endpointFingerprint");
+    if (!/^sha256:[a-f0-9]{64}$/.test(endpointFingerprint)) {
+        throw new Error("Deployment target.endpointFingerprint must be a sha256 fingerprint.");
+    }
+    const project = (0, deploy_schema_1.requiredString)(target, "project");
+    if (!PROJECT_NAME.test(project) || project.length > 40) {
+        throw new Error("Deployment target.project must be a Compose project name of at most 40 characters.");
+    }
+    if (exposure.mode !== "publishedPort") {
+        throw new Error("Deployment exposure.mode must be publishedPort for the docker-compose driver.");
+    }
+    const host = (0, deploy_schema_1.requiredString)(exposure, "host");
+    (0, deploy_schema_1.validateDnsSubdomain)(host, "exposure.host");
+    const bindAddress = (0, deploy_schema_1.requiredString)(exposure, "bindAddress");
+    if (!/^(?:\d{1,3}\.){3}\d{1,3}$/.test(bindAddress) || bindAddress.split(".").some((o) => Number(o) > 255)) {
+        throw new Error("Deployment exposure.bindAddress must be an IPv4 address.");
+    }
+    const port = (0, deploy_schema_1.requiredNumber)(exposure, "port");
+    if (port > 65535)
+        throw new Error("Deployment exposure.port must be a TCP port.");
+    const web = parseComposeWorkload((0, deploy_schema_1.requiredRecord)(workloads, "web"), "workloads.web");
+    // Compose has no load balancer. Two replicas of the service that publishes the
+    // host port means the second one cannot bind it, and the deployment fails half
+    // way through the rollout with "port is already allocated". Scaling the public
+    // tier is what the kubernetes-helm driver is for.
+    if (web.replicas > 1) {
+        throw new Error("Deployment workloads.web.replicas must be 1: the web service publishes a host port, and Compose cannot share one across replicas.");
+    }
+    const objectStorageRecord = (0, deploy_schema_1.requiredRecord)(dependencies, "objectStorage");
+    const objectStorage = {
+        ...parseComposeDependency(objectStorageRecord, "dependencies.objectStorage", [
+            "bucket",
+            "clientImage",
+        ]),
+        bucket: (0, deploy_schema_1.requiredString)(objectStorageRecord, "bucket"),
+        clientImage: (0, deploy_schema_1.requiredString)(objectStorageRecord, "clientImage"),
+    };
+    (0, deploy_schema_1.validateDnsLabel)(objectStorage.bucket, "dependencies.objectStorage.bucket");
+    (0, deploy_schema_1.validateImage)(objectStorage.clientImage, "dependencies.objectStorage.clientImage");
+    if (typeof secrets.registryLogin !== "boolean") {
+        throw new Error("Deployment secrets.registryLogin must be a boolean.");
+    }
+    const profile = {
+        schemaVersion: 1,
+        driver: "docker-compose",
+        target: { context, endpointFingerprint, project },
+        release: (0, deploy_schema_1.parseReleaseProfile)((0, deploy_schema_1.requiredRecord)(value, "release")),
+        exposure: { mode: "publishedPort", host, bindAddress, port },
+        workloads: {
+            api: parseComposeWorkload((0, deploy_schema_1.requiredRecord)(workloads, "api"), "workloads.api"),
+            web,
+            worker: workloads.worker === null
+                ? null
+                : parseComposeWorkload((0, deploy_schema_1.requiredRecord)(workloads, "worker"), "workloads.worker"),
+        },
+        dependencies: {
+            postgres: parseComposeDependency((0, deploy_schema_1.requiredRecord)(dependencies, "postgres"), "dependencies.postgres"),
+            redis: parseComposeDependency((0, deploy_schema_1.requiredRecord)(dependencies, "redis"), "dependencies.redis"),
+            objectStorage,
+        },
+        secrets: {
+            api: parseEnvFileProfile(secrets.api, "secrets.api"),
+            web: secrets.web === null ? null : parseEnvFileProfile(secrets.web, "secrets.web"),
+            registryLogin: secrets.registryLogin,
+        },
+        ...(migration
+            ? { migration: { command: (0, deploy_schema_1.parseCommand)(migration.command, "migration.command") } }
+            : {}),
+        ...(sync ? { sync: parseSyncProfile(sync, "sync") } : {}),
+        runtimeConfig: (0, deploy_schema_1.parseRuntimeConfig)((0, deploy_schema_1.requiredRecord)(value, "runtimeConfig")),
+        verification: (0, deploy_schema_1.parseVerification)((0, deploy_schema_1.requiredRecord)(value, "verification")),
+    };
+    return profile;
+}
+function buildDefaultComposeProfile(projectName, options) {
+    const project = projectName
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40);
+    if (!project || !deploy_schema_1.DNS_LABEL.test(project)) {
+        throw new Error("Project name cannot be converted to a Compose project name.");
+    }
+    const host = options.host ?? "app.example.com";
+    const secretsDirectory = options.secretsDirectory ?? `/etc/podokit/${project}`;
+    validateHostPath(secretsDirectory, "secretsDirectory");
+    return {
+        schemaVersion: 1,
+        driver: "docker-compose",
+        target: {
+            context: options.context,
+            endpointFingerprint: options.endpointFingerprint,
+            project,
+        },
+        release: {
+            strategy: "shared-tag",
+            tagPattern: deploy_schema_1.STABLE_SEMVER_TAG_PATTERN,
+            apiRepository: `ghcr.io/example/${project}-api`,
+            webRepository: `ghcr.io/example/${project}-web`,
+        },
+        exposure: {
+            mode: "publishedPort",
+            host,
+            // Loopback by default: a reverse proxy on the same host is the expected front
+            // door, and binding every interface would publish the app straight to the
+            // network before TLS exists.
+            bindAddress: "127.0.0.1",
+            port: 8080,
+        },
+        workloads: {
+            api: { replicas: 2, resources: { cpuLimit: "1", memoryLimit: "1g" } },
+            // One, not two: this is the service that publishes the host port.
+            web: { replicas: 1, resources: { cpuLimit: "0.5", memoryLimit: "1g" } },
+            worker: null,
+        },
+        dependencies: {
+            postgres: {
+                mode: "managed",
+                image: "postgres:16.10-alpine@sha256:029660641a0cfc575b14f336ba448fb8a75fd595d42e1fa316b9fb4378742297",
+                envFile: `${secretsDirectory}/postgres.env`,
+                requiredKeys: ["POSTGRES_DB", "POSTGRES_PASSWORD", "POSTGRES_USER"],
+                volume: `${project}-postgres`,
+            },
+            redis: {
+                mode: "disabled",
+                image: "redis:7.4.5-alpine",
+                envFile: `${secretsDirectory}/redis.env`,
+                requiredKeys: ["REDIS_PASSWORD"],
+                volume: `${project}-redis`,
+            },
+            objectStorage: {
+                mode: "disabled",
+                image: "quay.io/minio/minio:RELEASE.2025-09-07T16-13-09Z",
+                clientImage: "quay.io/minio/mc:RELEASE.2025-08-13T08-35-41Z",
+                envFile: `${secretsDirectory}/object-storage.env`,
+                requiredKeys: [
+                    "MINIO_ROOT_PASSWORD",
+                    "MINIO_ROOT_USER",
+                    "S3_ACCESS_KEY_ID",
+                    "S3_SECRET_ACCESS_KEY",
+                ],
+                volume: `${project}-object-storage`,
+                bucket: "app",
+            },
+        },
+        secrets: {
+            api: { path: `${secretsDirectory}/api.env`, requiredKeys: [] },
+            web: null,
+            registryLogin: true,
+        },
+        runtimeConfig: {
+            NODE_ENV: "production",
+            CORS_ORIGIN: `https://${host}`,
+            ADDRESS_HEADER: "x-forwarded-for",
+            XFF_DEPTH: "1",
+        },
+        verification: {
+            baseUrl: `https://${host}`,
+            checks: [
+                { path: "/", expectedStatus: 200 },
+                { path: "/api/health", expectedStatus: 200, expectedJson: { status: "ok" } },
+                { path: "/api/health/ready", expectedStatus: 200, expectedJson: { status: "ready" } },
+            ],
+        },
+    };
+}
+function initializeComposeProfile(projectRoot, name, options) {
+    const manifest = (0, lockfile_1.readManifest)(projectRoot);
+    if (!manifest)
+        throw new Error("Not a PodoKit project: .podokit/manifest.json is missing.");
+    const projectName = manifest.answers.projectName;
+    if (!projectName)
+        throw new Error("PodoKit manifest is missing answers.projectName.");
+    const path = (0, deploy_schema_1.profilePath)(projectRoot, name);
+    if ((0, node_fs_1.existsSync)(path))
+        throw new Error(`Deployment profile "${name}" already exists.`);
+    const draft = buildDefaultComposeProfile(projectName, options);
+    const modules = new Set(manifest.modules.map((module) => module.name));
+    const usesRedis = [...modules].some((module) => ["redis", "bullmq", "job-progress", "rate-limit", "sse"].includes(module));
+    draft.dependencies.redis.mode = usesRedis ? "managed" : "disabled";
+    draft.dependencies.objectStorage.mode = modules.has("object-storage-s3")
+        ? "managed"
+        : "disabled";
+    if (modules.has("bullmq")) {
+        draft.workloads.worker = { replicas: 1, resources: { cpuLimit: "0.5", memoryLimit: "512m" } };
+    }
+    const usesAuth = modules.has("auth");
+    draft.secrets.api.requiredKeys = [
+        ...(usesAuth ? ["BETTER_AUTH_SECRET"] : []),
+        ...(modules.has("api-key-auth") ? ["API_KEYS"] : []),
+    ].sort();
+    const host = draft.exposure.host;
+    draft.runtimeConfig = {
+        ...draft.runtimeConfig,
+        ...(usesAuth ? { BETTER_AUTH_URL: `https://${host}` } : {}),
+        ...(modules.has("sse") && usesRedis ? { SSE_TRANSPORT: "redis" } : {}),
+        ...(modules.has("rate-limit")
+            ? {
+                RATE_LIMIT_TTL: "60",
+                RATE_LIMIT_MAX: "300",
+                RATE_LIMIT_AUTH_TTL: "60",
+                RATE_LIMIT_AUTH_MAX: "20",
+                RATE_LIMIT_RUNTIME_MAX: "1000",
+                RATE_LIMIT_TRUSTED_PROXY_HOPS: "1",
+                RATE_LIMIT_PROXY_HEADER: "x-forwarded-for",
+                RATE_LIMIT_STORAGE_TIMEOUT_MS: "1000",
+                RATE_LIMIT_UNAVAILABLE_RETRY_AFTER: "1",
+            }
+            : {}),
+    };
+    const validated = parseComposeProfile(draft);
+    (0, node_fs_1.mkdirSync)((0, deploy_schema_1.profileDirectory)(projectRoot), { recursive: true });
+    (0, node_fs_1.writeFileSync)(path, `${JSON.stringify(validated, null, 2)}\n`, { flag: "wx" });
+    return { name, path, profile: validated };
+}
+function composeProfileDigest(profile) {
+    return `sha256:${(0, node_crypto_1.createHash)("sha256").update(JSON.stringify(profile)).digest("hex")}`;
+}

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

@@ -0,0 +1,48 @@
+import type { DockerComposeProfileV1 } from "./deploy-compose-profile";
+/**
+ * Compose project rendering.
+ *
+ * The Kubernetes driver renders Helm charts; this one renders a single Compose file
+ * plus a one-shot migration file. Both are written into `.podokit/runtime/deploy/`
+ * and both are pure functions of the profile, the release, and the resolved image
+ * digests — so the same inputs always produce the same bytes, which is what lets the
+ * plan hash mean anything.
+ */
+export interface ComposeRuntime {
+    root: string;
+    composeFile: string;
+    migrationFile: string;
+    composeDocument: string;
+    migrationDocument: string;
+}
+export interface ComposeImages {
+    api: string;
+    web: string;
+    postgres: string | null;
+    redis: string | null;
+    objectStorage: string | null;
+    objectStorageClient: string | null;
+}
+export declare function serviceName(profile: DockerComposeProfileV1, role: string): string;
+/**
+ * Configuration PodoKit derives rather than accepts, so a profile cannot point the
+ * app at the wrong service or port.
+ */
+export declare function derivedRuntimeConfig(profile: DockerComposeProfileV1): Record<string, string>;
+/**
+ * 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.
+ */
+export declare function rolloutStateDigest(profile: DockerComposeProfileV1, secretIdentities: Record<string, string>): string;
+export declare function renderComposeDocument(profile: DockerComposeProfileV1, release: string, images: ComposeImages, stateDigest: string): string;
+/**
+ * The migration runs as its own Compose project so it can be started, waited on,
+ * and removed without touching the running application definition.
+ */
+export declare function renderMigrationDocument(profile: DockerComposeProfileV1, release: string, images: ComposeImages): string;
+export declare function defaultComposeImages(profile: DockerComposeProfileV1, release: string): ComposeImages;
+export declare function renderComposeDeployment(projectRoot: string, profileName: string, profile: DockerComposeProfileV1, release: string, resolvedImages?: ComposeImages, stateDigest?: string): ComposeRuntime;