okengine 0.8.0 → 0.9.0

package/src/docker/compose.ts

@@ -5,6 +5,10 @@
  * 2. `compose.<role>.yml`     — per-role services (generated)
  * 3. `compose.prod.yml`       — prod overlays (generated when `--prod`)
  * 4. `compose.override.yml`   — user-owned; oke never writes it
+ *
+ * Also emits {@link COMPOSE_ALL} — layers 1–3 deep-merged into one file
+ * (for Swarm `stack deploy -c` and single-file preferrers). Not part of the
+ * `-f` merge order; never includes layer 4.
  */
 
 import { defaultHostPort, envPrefix, serviceNameFor, toYaml } from "./helpers.ts";
@@ -24,6 +28,12 @@ import { APP_PORT } from "../runtime/types.ts";
 /** Canonical layer-4 filename — never written by derivation. */
 export const COMPOSE_OVERRIDE = "compose.override.yml";
 
+/**
+ * Fully merged compose (layers 1–3) — additive single-file alternative.
+ * Does not replace or shadow the base {@code compose.yml} layer.
+ */
+export const COMPOSE_ALL = "compose.all.yml";
+
 /**
  * Relative path refs for compose files living under {@link DeriveOptions.composeDir}.
  *
@@ -85,6 +95,8 @@ export function emitComposeLayers(
   const includeApp = options.includeApp !== false;
   const paths = composePathRefs(options.composeDir ?? DEFAULT_DOCKER_DIR);
   const files: GeneratedFile[] = [];
+  /** Layers 1–3 as objects — same merge Compose would apply via `-f` order. */
+  const mergeLayers: Record<string, unknown>[] = [];
 
   // Layer 1 — project name + network (+ optional app for deploy / oke docker)
   const base: Record<string, unknown> = {
@@ -92,21 +104,29 @@ export function emitComposeLayers(
     networks: { oke: { driver: "bridge" } },
   };
   if (includeApp) {
+    // `image` + `build`: local compose builds and tags; Swarm stack deploy
+    // ignores `build` and pulls/uses the pre-built tag.
+    // When an opt-in `proxy` role is present, the edge publishes 80/443 —
+    // leave `app` unpublished so `docker compose up --scale app=N` works.
+    const hasProxy = specs.some((s) => s.role === "proxy");
+    const backendDeps = specs.filter((s) => s.role !== "proxy");
     base.services = {
       app: {
+        image: `oke-${app}:latest`,
         build: {
           context: paths.buildContext,
           dockerfile: paths.dockerfile,
         },
-        ports: [`${appPort}:${appPort}`],
+        ...(hasProxy ? {} : { ports: [`${appPort}:${appPort}`] }),
         env_file: [paths.envFile],
         depends_on: Object.fromEntries(
-          specs.map((s) => [s.serviceName, { condition: "service_healthy" }]),
+          backendDeps.map((s) => [s.serviceName, { condition: "service_healthy" }]),
         ),
         networks: ["oke"],
       },
     };
   }
+  mergeLayers.push(base);
   files.push({ path: "compose.yml", content: `${toYaml(base)}\n` });
 
   // Layer 2 — per-role
@@ -134,26 +154,67 @@ export function emitComposeLayers(
     if (applied.healthcheck) service.healthcheck = applied.healthcheck;
     if (applied.volumes) service.volumes = applied.volumes;
     if (applied.user) service.user = applied.user;
+    if (applied.ulimits) service.ulimits = applied.ulimits;
+    if (applied.labels) service.labels = applied.labels;
+    if (applied.dependsOn) {
+      const deps = { ...applied.dependsOn };
+      if (!includeApp) delete deps.app;
+      if (Object.keys(deps).length > 0) service.depends_on = deps;
+    }
 
-    const namedVolumes = namedVolumeDecls(applied.volumes);
+    const namedVolumes = namedVolumeDecls([
+      ...(applied.volumes ?? []),
+      ...extraServiceVolumes(applied.services),
+    ]);
     const doc: Record<string, unknown> = {
-      services: { [spec.serviceName]: service },
+      services: { [spec.serviceName]: service, ...applied.services },
       networks: { oke: { external: false } },
     };
     if (Object.keys(namedVolumes).length > 0) {
       doc.volumes = namedVolumes;
     }
+    mergeLayers.push(doc);
     const path = `compose.${spec.role}.yml`;
     files.push({ path, content: `${toYaml(doc)}\n` });
   }
 
-  // Layer 3 — prod overlay
+  // Layer 3 — prod overlay (Swarm-aware deploy + app readiness healthcheck)
   if (options.prod) {
     const prodServices: Record<string, unknown> = {};
     if (includeApp) {
       prodServices.app = {
+        // Single Docker HEALTHCHECK — Swarm has no separate readiness/liveness.
+        // Prefer kernel readiness so the routing mesh and rolling updates wait
+        // out booting / orphan_scan (see GET /_/ready). App GET /health stays
+        // for external monitors only.
+        healthcheck: {
+          test: [
+            "CMD",
+            "bun",
+            "-e",
+            `fetch("http://127.0.0.1:${appPort}/_/ready").then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))`,
+          ],
+          interval: "10s",
+          timeout: "3s",
+          retries: 3,
+          start_period: "60s",
+        },
+        // Match installGracefulShutdown lease release window (≥ Signal TTL).
+        stop_grace_period: "30s",
         deploy: {
           replicas: 1,
+          update_config: {
+            parallelism: 1,
+            delay: "10s",
+            failure_action: "rollback",
+            order: "start-first",
+          },
+          restart_policy: {
+            condition: "on-failure",
+            delay: "5s",
+            max_attempts: 3,
+            window: "120s",
+          },
           resources: {
             limits: { cpus: "1.0", memory: "512M" },
           },
@@ -171,12 +232,21 @@ export function emitComposeLayers(
         secrets: secretNames(spec),
       };
     }
+    const prodDoc = { services: prodServices };
+    mergeLayers.push(prodDoc);
     files.push({
       path: "compose.prod.yml",
-      content: `${toYaml({ services: prodServices })}\n`,
+      content: `${toYaml(prodDoc)}\n`,
     });
   }
 
+  // Additive single-file merge of layers 1–3 (not in `-f` order; no layer 4).
+  const merged = mergeLayers.reduce<Record<string, unknown>>(
+    (acc, layer) => deepMergeCompose(acc, layer),
+    {},
+  );
+  files.push({ path: COMPOSE_ALL, content: `${toYaml(merged)}\n` });
+
   // Layer 4 — never written. Document merge order only.
   const composeFiles = [
     "compose.yml",
@@ -188,6 +258,33 @@ export function emitComposeLayers(
   return { files, composeFiles };
 }
 
+/**
+ * Deep-merge compose documents the way Docker Compose merges `-f` overlays:
+ * maps recurse; sequences and scalars from the later document replace earlier.
+ *
+ * @param base - Earlier layer
+ * @param overlay - Later layer
+ */
+export function deepMergeCompose(
+  base: Record<string, unknown>,
+  overlay: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(overlay)) {
+    const prev = out[key];
+    if (isPlainObject(prev) && isPlainObject(value)) {
+      out[key] = deepMergeCompose(prev, value);
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
 /**
  * Build docker env key/value map (credentials + connection URLs).
  *
@@ -227,6 +324,19 @@ export function buildStackEnv(
       env[`${prefix}_DB`] = spec.credentials.database;
       env[`${prefix}_URL`] = url;
       env.DATABASE_URL = url;
+    } else if (spec.role === "pgdog") {
+      // URL uses store.sql credentials (same user/db the pooler proxies).
+      const sql = specs.find((s) => s.role === "store.sql");
+      const creds = sql?.credentials ?? spec.credentials;
+      const poolUrl = recipe.url(spec, {
+        host,
+        port: spec.hostPort,
+        user: creds.user,
+        password: creds.password,
+        database: creds.database,
+      });
+      env[`${prefix}_URL`] = poolUrl;
+      env.OKE_PGDOG_URL = poolUrl;
     } else if (spec.role === "store.kv") {
       env[`${prefix}_PASSWORD`] = spec.credentials.password;
       env[`${prefix}_URL`] = url;
@@ -259,6 +369,10 @@ export function buildStackEnv(
       // Ollama: standalone HTTP URL; model is a stack control (OKE_AI_MODEL).
       env[`${prefix}_URL`] = url;
       env.OKE_AI_URL = url;
+    } else if (spec.role === "proxy") {
+      // Edge TLS terminator — host is the public URL, not a driver DSN.
+      env[`${prefix}_URL`] = url;
+      env.OKE_PROXY_URL = url;
     } else {
       env[`${prefix}_USER`] = spec.credentials.user;
       env[`${prefix}_PASSWORD`] = spec.credentials.password;
@@ -266,6 +380,21 @@ export function buildStackEnv(
       env[`${prefix}_URL`] = url;
     }
   }
+  // When PgDog sits in front of Postgres, apps talk to the pooler — wire-protocol
+  // transparent; zero application changes (Bun.SQL / Drizzle / any Postgres client).
+  const sqlSpec = specs.find((s) => s.role === "store.sql");
+  const pgdogSpec = specs.find((s) => s.role === "pgdog");
+  if (sqlSpec && pgdogSpec) {
+    const poolRecipe = recipeFor(pgdogSpec.image, recipes);
+    env.DATABASE_URL = poolRecipe.url(pgdogSpec, {
+      host,
+      port: pgdogSpec.hostPort,
+      user: sqlSpec.credentials.user,
+      password: sqlSpec.credentials.password,
+      database: sqlSpec.credentials.database,
+    });
+  }
+
   for (const key of STACK_CONTROL_KEYS) {
     const value = controls[key];
     if (value !== undefined) env[key] = value;
@@ -276,6 +405,7 @@ export function buildStackEnv(
 /** Friendly section titles for known compose roles. */
 const ROLE_SECTION_TITLE: Readonly<Record<string, string>> = {
   "store.sql": "store.sql — Postgres",
+  pgdog: "pgdog — connection pooler (in front of Postgres)",
   "store.kv": "store.kv — Redis",
   "store.files": "store.files — object storage (S3)",
   "store.index": "store.index — search index",
@@ -283,11 +413,13 @@ const ROLE_SECTION_TITLE: Readonly<Record<string, string>> = {
   signal: "signal — message bus",
   vault: "vault — OpenBao",
   ai: "ai — Ollama (local models)",
+  proxy: "proxy — TLS terminator (Caddy / Traefik)",
 };
 
 /** Friendly aliases emitted beside their role block. */
 const ROLE_ALIASES: Readonly<Record<string, readonly string[]>> = {
   "store.sql": ["DATABASE_URL", "PGDATA", "POSTGRES_INITDB_ARGS"],
+  pgdog: ["OKE_PGDOG_URL"],
   "store.kv": ["REDIS_URL", "OKE_STORE_KV_MAXMEMORY", "OKE_STORE_KV_MAXMEMORY_POLICY"],
   "store.files": [
     "S3_ACCESS_KEY_ID",
@@ -311,6 +443,7 @@ const ROLE_ALIASES: Readonly<Record<string, readonly string[]>> = {
     "MP_SMTP_AUTH_ALLOW_INSECURE",
   ],
   ai: ["OKE_AI_URL", "OKE_AI_MODEL"],
+  proxy: ["OKE_PROXY_HOST", "OKE_PROXY_ACME_EMAIL"],
 };
 
 /** Optional controls documented in `.env.docker` and preserved on regeneration. */
@@ -327,6 +460,7 @@ const ROLE_CONTROL_EXAMPLES: Readonly<Record<string, readonly string[]>> = {
   ],
   // qwen3.5:9b is a balanced local-dev starting point — override freely.
   ai: ["OKE_AI_MODEL=qwen3.5:9b"],
+  proxy: ["OKE_PROXY_HOST=localhost", "OKE_PROXY_ACME_EMAIL=admin@example.com"],
 };
 
 /**
@@ -344,6 +478,9 @@ function roleFromEnvKey(key: string): string | undefined {
   if (key === "PGDATA" || key === "POSTGRES_INITDB_ARGS") return "store.sql";
   if (key.startsWith("OKE_STORE_KV_MAXMEMORY")) return "store.kv";
   if (key === "OKE_AI_URL" || key === "OKE_AI_MODEL" || key === "OLLAMA_HOST") return "ai";
+  if (key === "OKE_PROXY_URL" || key === "OKE_PROXY_HOST" || key === "OKE_PROXY_ACME_EMAIL") {
+    return "proxy";
+  }
   return undefined;
 }
 
@@ -451,6 +588,25 @@ function namedVolumeDecls(
   return out;
 }
 
+/**
+ * Volume mounts declared on companion services from {@link RecipeApplyResult.services}.
+ *
+ * @param services - Extra compose service fragments
+ */
+function extraServiceVolumes(
+  services: Readonly<Record<string, Record<string, unknown>>> | undefined,
+): string[] {
+  const out: string[] = [];
+  for (const svc of Object.values(services ?? {})) {
+    const vols = svc.volumes;
+    if (!Array.isArray(vols)) continue;
+    for (const v of vols) {
+      if (typeof v === "string") out.push(v);
+    }
+  }
+  return out;
+}
+
 function escapeEnv(value: string): string {
   if (/[\s#"'$\\]/.test(value)) {
     return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;

package/src/docker/derive.ts

@@ -11,14 +11,17 @@ import {
   formatStackEnv,
 } from "./compose.ts";
 import { emitDockerfile } from "./dockerfile.ts";
+import { buildCaddyfile } from "./recipes/caddy.ts";
+import { buildPgDogToml, buildPgDogUsersToml } from "./recipes/pgdog.ts";
 import type { DeriveOptions, DeriveResult, GeneratedFile } from "./types.ts";
 import { DEFAULT_DOCKER_DIR } from "./types.ts";
+import { APP_PORT } from "../runtime/types.ts";
 
 /**
  * Derive infrastructure files from normalised image pins.
  *
- * Credentials land only in the returned `stackEnv` (for `.env.docker`);
- * generated YAML never contains cleartext secrets. Layer 4
+ * Credentials land only in the returned `stackEnv` (for `.env.docker`) and
+ * in `users.toml` when PgDog is present — never in generated YAML. Layer 4
  * (`compose.override.yml`) is listed in `composeFiles` but never written.
  *
  * @param options - Images / app / prod flag
@@ -43,7 +46,12 @@ export function deriveInfrastructure(options: DeriveOptions): DeriveResult {
     content: emitDockerfile({ appPort: normalised.appPort }),
   };
   // Always emit Dockerfile for deploy; stack-only runs ignore it.
-  const files = [dockerfile, ...composeFilesContent];
+  const files = [
+    dockerfile,
+    ...composeFilesContent,
+    ...pgdogConfigFiles(specs),
+    ...proxyConfigFiles(specs, normalised.appPort),
+  ];
 
   for (const f of files) {
     if (f.path.endsWith(".yml") || f.path === "Dockerfile") {
@@ -65,6 +73,55 @@ export function deriveInfrastructure(options: DeriveOptions): DeriveResult {
   return { specs, files, stackEnv, composeFiles };
 }
 
+/**
+ * Emit PgDog TOML configs when both `pgdog` and `store.sql` are in the stack.
+ *
+ * `pgdog.toml` has no secrets; `users.toml` mirrors store.sql credentials
+ * (same trust boundary as `.env.docker` — do not commit).
+ *
+ * @param specs - Normalised services
+ */
+function pgdogConfigFiles(specs: DeriveResult["specs"]): GeneratedFile[] {
+  const sql = specs.find((s) => s.role === "store.sql");
+  const pooler = specs.find((s) => s.role === "pgdog");
+  if (!sql || !pooler) return [];
+  return [
+    {
+      path: "pgdog.toml",
+      content: buildPgDogToml({ database: sql.credentials.database }),
+    },
+    {
+      path: "users.toml",
+      content: buildPgDogUsersToml({
+        user: sql.credentials.user,
+        password: sql.credentials.password,
+        database: sql.credentials.database,
+      }),
+    },
+  ];
+}
+
+/**
+ * Emit proxy companion configs when `images.proxy` is pinned.
+ *
+ * Caddy gets a generated `Caddyfile`. Traefik configures via Docker labels
+ * (no companion file).
+ *
+ * @param specs - Normalised services
+ * @param appPort - App listen port (default 6530)
+ */
+function proxyConfigFiles(
+  specs: DeriveResult["specs"],
+  appPort: number | undefined,
+): GeneratedFile[] {
+  const proxy = specs.find((s) => s.role === "proxy");
+  if (!proxy) return [];
+  if (/caddy/i.test(proxy.image)) {
+    return [{ path: "Caddyfile", content: buildCaddyfile({ appPort: appPort ?? APP_PORT }) }];
+  }
+  return [];
+}
+
 /**
  * Write derived files to disk. Never writes `compose.override.yml` or
  * credential values into YAML. Optionally writes `docker/.env.docker`.