@podosoft/podokit 1.4.2 → 1.6.0

package/README.md

@@ -85,11 +85,12 @@ on restart; files and the database-backed local jobs persist.
 | `podo provider list` | Show active database, cache, object storage, event, and job providers. |
 | `podo provider set <capability> <provider> [--apply]` | Preview or apply one provider change. |
 | `podo status` | Show the PodoKit version, modules, ownership tiers, and local edits. |
-| `podo diff` | List edited or deleted managed files. |
+| `podo diff [path...]` | List edited or deleted managed files, or show a file's diff against its template. |
 | `podo doctor` | Check Bun and framework versions. |
 | `podo locale <command>` | Manage JSON locales. |
 | `podo update [--apply]` | Preview or apply managed template and module updates. |
 | `podo eject <path...>` | Transfer managed files to application ownership. |
+| `podo restore <path...>` | Rewrite managed files from the template; an ejected file becomes managed again. |
 | `podo dev <action>` | Manage the generated development containers. |
 | `podo deploy <action>` | Plan, apply, verify, or roll back an immutable Kubernetes or Docker Compose release. |
 

package/dist/app-proxy-timeouts.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The application's own `/api` proxy deadlines, read for deployment.
+ *
+ * The web server loads `APP_PROXY_TIMEOUTS` from an application-owned module, and
+ * the idle timeouts a deployment renders have to outlast its longest entry. The
+ * CLI must not run application code to learn them, so it reads the array literal
+ * with a small tokenizer that accepts exactly the shape PodoKit generates and
+ * documents: object literals with a string `pathPrefix` and a `timeoutMs` that is
+ * `null` or a number, optionally a product such as `5 * 60_000`. Anything else is
+ * reported, never guessed.
+ */
+export declare const APP_PROXY_TIMEOUTS_PATH = "apps/web/src/lib/server/proxy-timeouts.ts";
+export interface AppProxyTimeout {
+    pathPrefix: string;
+    timeoutMs: number | null;
+}
+/** The entries, or why they could not be read without running the module. */
+export type AppProxyTimeouts = {
+    entries: AppProxyTimeout[];
+} | {
+    error: string;
+};
+export declare const NO_APP_PROXY_TIMEOUTS: AppProxyTimeouts;
+/** Parses the `APP_PROXY_TIMEOUTS` array literal from the module's source text. */
+export declare function parseAppProxyTimeouts(source: string): AppProxyTimeout[];
+/** Reads the application's deadlines; an app without the module has none. */
+export declare function readAppProxyTimeouts(projectRoot: string): AppProxyTimeouts;

package/dist/app-proxy-timeouts.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_APP_PROXY_TIMEOUTS = exports.APP_PROXY_TIMEOUTS_PATH = void 0;
+exports.parseAppProxyTimeouts = parseAppProxyTimeouts;
+exports.readAppProxyTimeouts = readAppProxyTimeouts;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/**
+ * The application's own `/api` proxy deadlines, read for deployment.
+ *
+ * The web server loads `APP_PROXY_TIMEOUTS` from an application-owned module, and
+ * the idle timeouts a deployment renders have to outlast its longest entry. The
+ * CLI must not run application code to learn them, so it reads the array literal
+ * with a small tokenizer that accepts exactly the shape PodoKit generates and
+ * documents: object literals with a string `pathPrefix` and a `timeoutMs` that is
+ * `null` or a number, optionally a product such as `5 * 60_000`. Anything else is
+ * reported, never guessed.
+ */
+exports.APP_PROXY_TIMEOUTS_PATH = "apps/web/src/lib/server/proxy-timeouts.ts";
+exports.NO_APP_PROXY_TIMEOUTS = { entries: [] };
+function tokenize(source) {
+    const tokens = [];
+    let line = 1;
+    let index = 0;
+    const fail = (message) => {
+        throw new Error(`${message} on line ${line}`);
+    };
+    while (index < source.length) {
+        const character = source[index];
+        if (character === "\n") {
+            line += 1;
+            index += 1;
+        }
+        else if (/\s/.test(character)) {
+            index += 1;
+        }
+        else if (source.startsWith("//", index)) {
+            const end = source.indexOf("\n", index);
+            index = end === -1 ? source.length : end;
+        }
+        else if (source.startsWith("/*", index)) {
+            const end = source.indexOf("*/", index + 2);
+            if (end === -1)
+                fail("an unterminated comment");
+            line += source.slice(index, end).split("\n").length - 1;
+            index = end + 2;
+        }
+        else if (character === '"' || character === "'" || character === "`") {
+            let value = "";
+            let cursor = index + 1;
+            for (;;) {
+                const next = source[cursor];
+                if (next === undefined || next === "\n")
+                    fail("an unterminated string");
+                if (next === character)
+                    break;
+                if (next === "\\") {
+                    const escaped = source[cursor + 1];
+                    if (escaped === undefined || !"\\'\"`/".includes(escaped))
+                        fail("an unsupported string escape");
+                    value += escaped;
+                    cursor += 2;
+                    continue;
+                }
+                if (character === "`" && next === "$" && source[cursor + 1] === "{")
+                    fail("a template literal with an expression");
+                value += next;
+                cursor += 1;
+            }
+            tokens.push({ kind: "string", value, line });
+            index = cursor + 1;
+        }
+        else if (/[0-9]/.test(character)) {
+            const match = /^[0-9][0-9_]*(?:\.[0-9][0-9_]*)?(?:[eE][+-]?[0-9]+)?/.exec(source.slice(index));
+            tokens.push({ kind: "number", value: match[0], line });
+            index += match[0].length;
+        }
+        else if (/[A-Za-z_$]/.test(character)) {
+            const match = /^[A-Za-z_$][A-Za-z0-9_$]*/.exec(source.slice(index));
+            tokens.push({ kind: "identifier", value: match[0], line });
+            index += match[0].length;
+        }
+        else if (source.startsWith("=>", index) || source.startsWith("...", index)) {
+            const value = source.startsWith("=>", index) ? "=>" : "...";
+            tokens.push({ kind: "punctuation", value, line });
+            index += value.length;
+        }
+        else {
+            tokens.push({ kind: "punctuation", value: character, line });
+            index += 1;
+        }
+    }
+    return tokens;
+}
+function numberValue(token) {
+    const value = Number(token.value.replace(/_/g, ""));
+    if (!Number.isFinite(value) || /_$|_\.|\._|__/.test(token.value)) {
+        throw new Error(`an invalid number ${token.value} on line ${token.line}`);
+    }
+    return value;
+}
+/** Parses the `APP_PROXY_TIMEOUTS` array literal from the module's source text. */
+function parseAppProxyTimeouts(source) {
+    const tokens = tokenize(source);
+    const declaration = tokens.findIndex((token, index) => token.kind === "identifier" &&
+        token.value === "APP_PROXY_TIMEOUTS" &&
+        tokens[index - 1]?.value === "const");
+    if (declaration === -1)
+        throw new Error("no `const APP_PROXY_TIMEOUTS` declaration");
+    let index = declaration + 1;
+    while (index < tokens.length && tokens[index].value !== "=")
+        index += 1;
+    index += 1;
+    /** Consumes the next token, which must satisfy `accepts`. */
+    const take = (expected, accepts) => {
+        const token = tokens[index];
+        if (!token)
+            throw new Error(`${expected} expected at the end of the file`);
+        if (!accepts(token)) {
+            throw new Error(`${expected} expected, found ${JSON.stringify(token.value)} on line ${token.line}`);
+        }
+        index += 1;
+        return token;
+    };
+    const punctuation = (...values) => (token) => token.kind === "punctuation" && values.includes(token.value);
+    take("an array literal", punctuation("["));
+    const entries = [];
+    while (take("`{` or `]`", punctuation("{", "]")).value === "{") {
+        const entry = {};
+        const property = (token) => punctuation("}")(token) || token.kind === "identifier" || token.kind === "string";
+        let key = take("pathPrefix, timeoutMs, or `}`", property);
+        while (key.kind !== "punctuation") {
+            if ((key.value !== "pathPrefix" && key.value !== "timeoutMs") || key.value in entry) {
+                throw new Error(`pathPrefix or timeoutMs expected, found ${JSON.stringify(key.value)} on line ${key.line}`);
+            }
+            take("`:`", punctuation(":"));
+            if (key.value === "pathPrefix") {
+                entry.pathPrefix = take("a string literal", (token) => token.kind === "string").value;
+            }
+            else {
+                const value = take("null or a number", (token) => token.kind === "number" || (token.kind === "identifier" && token.value === "null"));
+                let product = value.kind === "number" ? numberValue(value) : null;
+                while (product !== null && tokens[index]?.value === "*") {
+                    index += 1;
+                    product *= numberValue(take("a number", (token) => token.kind === "number"));
+                }
+                entry.timeoutMs = product;
+            }
+            if (take("`,` or `}`", punctuation(",", "}")).value === "}")
+                break;
+            key = take("pathPrefix, timeoutMs, or `}`", property);
+        }
+        if (entry.pathPrefix === undefined || entry.timeoutMs === undefined) {
+            throw new Error(`an entry without pathPrefix or timeoutMs before line ${tokens[index - 1].line}`);
+        }
+        if (entry.timeoutMs !== null && (!Number.isInteger(entry.timeoutMs) || entry.timeoutMs < 1)) {
+            throw new Error(`timeoutMs ${entry.timeoutMs} for ${entry.pathPrefix} is not a positive whole number of milliseconds`);
+        }
+        entries.push({ pathPrefix: entry.pathPrefix, timeoutMs: entry.timeoutMs });
+        if (take("`,` or `]`", punctuation(",", "]")).value === "]")
+            break;
+    }
+    return entries;
+}
+/** Reads the application's deadlines; an app without the module has none. */
+function readAppProxyTimeouts(projectRoot) {
+    const path = (0, node_path_1.join)(projectRoot, exports.APP_PROXY_TIMEOUTS_PATH);
+    if (!(0, node_fs_1.existsSync)(path))
+        return exports.NO_APP_PROXY_TIMEOUTS;
+    try {
+        return { entries: parseAppProxyTimeouts((0, node_fs_1.readFileSync)(path, "utf8")) };
+    }
+    catch (error) {
+        return {
+            error: `Cannot read APP_PROXY_TIMEOUTS from ${exports.APP_PROXY_TIMEOUTS_PATH} without running it: ` +
+                `${error.message}. Write each entry as { pathPrefix: "/api/...", timeoutMs: <milliseconds> | null } ` +
+                "with literal values, or set CONNECTION_IDLE_TIMEOUT and API_IDLE_TIMEOUT in runtimeConfig yourself.",
+        };
+    }
+}

package/dist/assemble.d.ts

@@ -15,5 +15,8 @@ export interface AssembleOptions {
 }
 /** Assemble the project tree for a template + ordered modules, in memory. */
 export declare function assembleProject(options: AssembleOptions): VfsTree;
-/** Render a Bun-native project template. */
-export declare function renderProjectTemplate(templatesDir: string, template: string, answers: TemplateVars): VfsTree;
+/**
+ * Render a Bun-native project template. Files that name the development host
+ * render it from the project's `.podokit/dev.json` when there is one.
+ */
+export declare function renderProjectTemplate(templatesDir: string, template: string, projectAnswers: TemplateVars, projectRoot?: string): VfsTree;

package/dist/assemble.js

@@ -6,6 +6,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
 const add_1 = require("./add");
+const dev_1 = require("./dev");
 function textOf(tree, path) {
     return String(tree.get(path)?.content ?? "");
 }
@@ -70,14 +71,16 @@ function preserveExternalPackageDependency(tree, projectRoot, packageName) {
             ? { ...current }
             : {};
         dependencies[packageName] = version;
-        rootPackage[section] = dependencies;
+        // Bun and npm write dependency sections sorted by name; insertion order
+        // would leave the file looking edited after `bun add` a second module.
+        rootPackage[section] = Object.fromEntries(Object.entries(dependencies).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
         setText(tree, "package.json", `${JSON.stringify(rootPackage, null, 2)}\n`);
         return;
     }
 }
 /** Assemble the project tree for a template + ordered modules, in memory. */
 function assembleProject(options) {
-    const tree = renderProjectTemplate(options.templatesDir, options.template, options.answers);
+    const tree = renderProjectTemplate(options.templatesDir, options.template, options.answers, options.projectRoot);
     for (const mod of options.modules) {
         const name = typeof mod === "string" ? mod : (mod.packageName ?? mod.name);
         const resolved = (0, add_1.resolveModule)(name, (0, node_path_1.join)(options.templatesDir, "modules"), options.projectRoot ?? options.templatesDir);
@@ -93,8 +96,15 @@ function assembleProject(options) {
     }
     return tree;
 }
-/** Render a Bun-native project template. */
-function renderProjectTemplate(templatesDir, template, answers) {
+/**
+ * Render a Bun-native project template. Files that name the development host
+ * render it from the project's `.podokit/dev.json` when there is one.
+ */
+function renderProjectTemplate(templatesDir, template, projectAnswers, projectRoot) {
+    const answers = {
+        ...projectAnswers,
+        ...(0, dev_1.devTemplateVars)(projectAnswers.projectName ?? "app", projectRoot),
+    };
     const tree = template === "todo"
         ? (0, podokit_template_engine_1.renderTemplate)((0, node_path_1.join)(templatesDir, "fullstack"), answers)
         : (0, podokit_template_engine_1.renderTemplate)((0, node_path_1.join)(templatesDir, template), answers);

package/dist/deploy-checks.d.ts

@@ -0,0 +1,44 @@
+import type { AnyDeployProfile } from "./deploy-driver";
+/**
+ * Read-only checks of a deployment profile against the application it deploys.
+ *
+ * Both drivers run them before they look at the target, because they need
+ * nothing but the project directory: a profile that misconfigures the
+ * application fails or warns the same way on a cluster and on a Docker host.
+ */
+/** One doctor result. A warning still passes, so apply runs, but the CLI flags it. */
+export interface DeployFinding {
+    code: string;
+    ok: boolean;
+    message: string;
+    warning?: true;
+}
+export declare function installedModules(projectRoot: string): Set<string>;
+/** PostgreSQL's default max_connections, which a profile can change. */
+export declare const DEFAULT_MAX_CONNECTIONS = 100;
+export interface ConnectionBudget {
+    maxConnections: number;
+    available: number;
+    /** Connections one API or worker process can hold, and what they are. */
+    perProcess: number;
+    perProcessTerms: string[];
+    steadyProcesses: number;
+    steady: number;
+    /** Processes and connections while a rollout runs old and new pods side by side. */
+    rolloutProcesses: number;
+    rollout: number;
+    migration: number;
+    peak: number;
+}
+/**
+ * The most PostgreSQL connections the deployment can open: every API and worker
+ * process with each pool full, the Kubernetes rollout's surge pod per workload
+ * (the rendered strategy allows one), and the migration that runs beside the
+ * release still serving. Compose replaces containers without a surge. Null when
+ * the deployment uses no PostgreSQL.
+ */
+export declare function connectionBudget(profile: AnyDeployProfile, modules: Set<string>): ConnectionBudget | null;
+/** The plan warning for a budget over the limit, or null. */
+export declare function connectionBudgetWarning(profile: AnyDeployProfile, modules: Set<string>): string | null;
+export declare function profileFindings(projectRoot: string, profile: AnyDeployProfile): DeployFinding[];
+export declare function formatFinding(finding: DeployFinding): string;

package/dist/deploy-checks.js

@@ -0,0 +1,267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_CONNECTIONS = void 0;
+exports.installedModules = installedModules;
+exports.connectionBudget = connectionBudget;
+exports.connectionBudgetWarning = connectionBudgetWarning;
+exports.profileFindings = profileFindings;
+exports.formatFinding = formatFinding;
+const app_proxy_timeouts_1 = require("./app-proxy-timeouts");
+const deploy_compose_profile_1 = require("./deploy-compose-profile");
+const deploy_compose_render_1 = require("./deploy-compose-render");
+const deploy_render_1 = require("./deploy-render");
+const deploy_schema_1 = require("./deploy-schema");
+const lockfile_1 = require("./lockfile");
+function installedModules(projectRoot) {
+    return new Set(((0, lockfile_1.readManifest)(projectRoot)?.modules ?? []).map((module) => module.name));
+}
+function auditLogFinding(runtimeConfig) {
+    const value = runtimeConfig.AUDIT_LOG_ENABLED;
+    if (value === "true") {
+        return {
+            code: "audit-log",
+            ok: true,
+            message: "AUDIT_LOG_ENABLED is true, so the audit log records from the first request.",
+        };
+    }
+    return {
+        code: "audit-log",
+        ok: true,
+        warning: true,
+        message: value === undefined
+            ? 'runtimeConfig does not set AUDIT_LOG_ENABLED, so until an administrator saves the audit setting the API\'s built-in default decides whether anything is recorded; set it to "true".'
+            : `AUDIT_LOG_ENABLED is ${JSON.stringify(value)}, so the audit log records nothing until an administrator turns it on in Settings; set it to "true".`,
+    };
+}
+/**
+ * Whether the rendered idle timeouts outlast the /api proxy's longest wait. A web
+ * server whose CONNECTION_IDLE_TIMEOUT cannot refuses to start, so that fails; a
+ * short API_IDLE_TIMEOUT only warns, because the API may lift its idle timeout
+ * for the long routes itself with `server.timeout(request, 0)`.
+ */
+function idleTimeoutFinding(runtimeConfig, proxyTimeouts) {
+    const code = "idle-timeouts";
+    const explicit = deploy_schema_1.IDLE_TIMEOUT_KEYS.filter((key) => runtimeConfig[key] !== undefined);
+    if ("error" in proxyTimeouts) {
+        return explicit.length === deploy_schema_1.IDLE_TIMEOUT_KEYS.length
+            ? { code, ok: true, warning: true, message: `${proxyTimeouts.error} The idle timeouts were not checked.` }
+            : { code, ok: false, message: proxyTimeouts.error };
+    }
+    let rendered;
+    try {
+        rendered = (0, deploy_schema_1.idleTimeoutConfig)(runtimeConfig, proxyTimeouts);
+    }
+    catch (error) {
+        return { code, ok: false, message: error.message };
+    }
+    const wait = (0, deploy_schema_1.longestProxyWait)(runtimeConfig, proxyTimeouts.entries);
+    const problems = [];
+    for (const key of explicit) {
+        const value = rendered[key];
+        const seconds = Number(value);
+        if (!/^\d+$/.test(value) || seconds > deploy_schema_1.MAX_IDLE_TIMEOUT_SECONDS) {
+            problems.push({ key, blocking: true, message: `${key} "${value}" is not 0 to ${deploy_schema_1.MAX_IDLE_TIMEOUT_SECONDS} seconds.` });
+        }
+        else if (!(0, deploy_schema_1.idleTimeoutCovers)(seconds, wait)) {
+            problems.push({
+                key,
+                blocking: key === "CONNECTION_IDLE_TIMEOUT",
+                message: key === "CONNECTION_IDLE_TIMEOUT"
+                    ? `CONNECTION_IDLE_TIMEOUT "${value}" closes a silent connection before the /api proxy's longest wait (${(0, deploy_schema_1.describeProxyWait)(wait)}), so the web server refuses to start; remove it from runtimeConfig to derive it.`
+                    : `API_IDLE_TIMEOUT "${value}" closes a silent connection before the /api proxy's longest wait (${(0, deploy_schema_1.describeProxyWait)(wait)}), unless the API lifts it for that route; remove it from runtimeConfig to derive it.`,
+            });
+        }
+    }
+    if (problems.length) {
+        const blocking = problems.some((problem) => problem.blocking);
+        return {
+            code,
+            ok: !blocking,
+            ...(blocking ? {} : { warning: true }),
+            message: problems.map((problem) => problem.message).join(" "),
+        };
+    }
+    return {
+        code,
+        ok: true,
+        message: `CONNECTION_IDLE_TIMEOUT ${rendered.CONNECTION_IDLE_TIMEOUT} and API_IDLE_TIMEOUT ${rendered.API_IDLE_TIMEOUT} ` +
+            `outlast the /api proxy's longest wait (${(0, deploy_schema_1.describeProxyWait)(wait)}).`,
+    };
+}
+/** PostgreSQL's default max_connections, which a profile can change. */
+exports.DEFAULT_MAX_CONNECTIONS = 100;
+/** PostgreSQL's default superuser_reserved_connections, unavailable to the application. */
+const RESERVED_CONNECTIONS = 3;
+/** The migration process: Better Auth's schema check, then the application migrations. */
+const MIGRATION_CONNECTIONS = 2;
+function poolSize(runtimeConfig, key, fallback) {
+    const value = runtimeConfig[key];
+    if (value === undefined)
+        return fallback;
+    if (!/^[1-9][0-9]*$/.test(value))
+        throw new Error(`${key} "${value}" is not a positive integer.`);
+    return Number(value);
+}
+/**
+ * The most PostgreSQL connections the deployment can open: every API and worker
+ * process with each pool full, the Kubernetes rollout's surge pod per workload
+ * (the rendered strategy allows one), and the migration that runs beside the
+ * release still serving. Compose replaces containers without a surge. Null when
+ * the deployment uses no PostgreSQL.
+ */
+function connectionBudget(profile, modules) {
+    const postgres = profile.dependencies.postgres;
+    if (postgres.mode === "disabled")
+        return null;
+    const config = profile.runtimeConfig;
+    const queryPool = poolSize(config, "DB_POOL_MAX", 20);
+    // The Bun SQL pool opens one more connection to check a server that stopped answering.
+    const perProcessTerms = [`DB_POOL_MAX ${queryPool} + 1`];
+    let perProcess = queryPool + 1;
+    if (modules.has("auth")) {
+        const authPool = poolSize(config, "DB_AUTH_POOL_MAX", 10);
+        perProcessTerms.push(`DB_AUTH_POOL_MAX ${authPool}`);
+        perProcess += authPool;
+    }
+    for (const pool of postgres.appPools ?? []) {
+        const size = poolSize(config, pool.sizeKey, 0);
+        perProcessTerms.push(`${pool.sizeKey} ${size}${pool.extraConnections ? ` + ${pool.extraConnections}` : ""}`);
+        perProcess += size + pool.extraConnections;
+    }
+    const worker = profile.workloads.worker;
+    const steadyProcesses = profile.workloads.api.replicas + (worker?.replicas ?? 0);
+    const rolloutProcesses = steadyProcesses + (profile.driver === "kubernetes-helm" ? 1 + (worker ? 1 : 0) : 0);
+    const maxConnections = postgres.maxConnections ?? exports.DEFAULT_MAX_CONNECTIONS;
+    const steady = steadyProcesses * perProcess;
+    const rollout = rolloutProcesses * perProcess;
+    return {
+        maxConnections,
+        available: maxConnections - RESERVED_CONNECTIONS,
+        perProcess,
+        perProcessTerms,
+        steadyProcesses,
+        steady,
+        rolloutProcesses,
+        rollout,
+        migration: MIGRATION_CONNECTIONS,
+        peak: Math.max(rollout, steady + MIGRATION_CONNECTIONS),
+    };
+}
+function budgetSummary(budget) {
+    return (`each API or worker process holds up to ${budget.perProcess} (${budget.perProcessTerms.join(" + ")}); ` +
+        `${budget.steadyProcesses} process(es) hold ${budget.steady}` +
+        (budget.rolloutProcesses > budget.steadyProcesses
+            ? `, ${budget.rolloutProcesses} during a rollout hold ${budget.rollout}`
+            : "") +
+        `, and the migration adds ${budget.migration} to the ${budget.steady}`);
+}
+const BUDGET_FIX = "Lower DB_POOL_MAX or DB_AUTH_POOL_MAX in runtimeConfig, run fewer replicas, or raise dependencies.postgres.maxConnections.";
+/** The plan warning for a budget over the limit, or null. */
+function connectionBudgetWarning(profile, modules) {
+    let budget;
+    try {
+        budget = connectionBudget(profile, modules);
+    }
+    catch (error) {
+        return `Cannot count PostgreSQL connections: ${error.message}`;
+    }
+    if (!budget || budget.peak <= budget.available)
+        return null;
+    return (`PostgreSQL connections can reach ${budget.peak}, above the ${budget.available} that max_connections ` +
+        `${budget.maxConnections} leaves after ${RESERVED_CONNECTIONS} reserved: ${budgetSummary(budget)}. ${BUDGET_FIX}`);
+}
+function connectionBudgetFinding(profile, modules) {
+    const code = "database-connections";
+    let budget;
+    try {
+        budget = connectionBudget(profile, modules);
+    }
+    catch (error) {
+        return { code, ok: false, message: `Cannot count PostgreSQL connections: ${error.message}` };
+    }
+    if (!budget)
+        return null;
+    const limit = `max_connections ${budget.maxConnections} leaves ${budget.available} after ${RESERVED_CONNECTIONS} reserved`;
+    if (budget.steady > budget.available) {
+        return {
+            code,
+            ok: false,
+            message: `PostgreSQL connections exceed the limit even between rollouts: ${limit}, and ${budgetSummary(budget)}. ${BUDGET_FIX}`,
+        };
+    }
+    if (budget.peak > budget.available) {
+        return {
+            code,
+            ok: true,
+            warning: true,
+            message: `PostgreSQL connections can reach ${budget.peak} during a deployment: ${limit}, and ${budgetSummary(budget)}. ${BUDGET_FIX}`,
+        };
+    }
+    return {
+        code,
+        ok: true,
+        message: `PostgreSQL connections stay within the limit, at most ${budget.peak}: ${limit}, and ${budgetSummary(budget)}.`,
+    };
+}
+/**
+ * Whether the trusted chain the profile describes matches the topology PodoKit
+ * renders, so web and API record the client rather than a proxy in front.
+ */
+function clientAddressFinding(profile) {
+    const code = "client-address";
+    const edge = profile.exposure.edgeProxies;
+    const problems = [];
+    let rendered;
+    if (profile.driver === "docker-compose") {
+        rendered = (0, deploy_compose_render_1.composeProxyTrust)(profile);
+        const cidrs = profile.exposure.trustedProxyCidrs;
+        if ((0, deploy_compose_profile_1.composeHasGateway)(profile) && edge > 0 && cidrs.length === 0) {
+            problems.push(`exposure.edgeProxies is ${edge} but exposure.trustedProxyCidrs is empty, so the gateway sends the ` +
+                "nearest edge proxy's address as every request's client; list that proxy's CIDR.");
+        }
+        else if ((0, deploy_compose_profile_1.composeHasGateway)(profile) && edge === 0 && cidrs.length > 0) {
+            problems.push("exposure.trustedProxyCidrs trusts forwarded headers from a proxy, but exposure.edgeProxies is 0; " +
+                "set it to the number of proxies in front of the published port.");
+        }
+    }
+    else {
+        rendered = (0, deploy_render_1.kubernetesProxyTrust)(profile);
+        const direct = [...profile.exposure.webSocketPaths, ...profile.exposure.apiPaths];
+        if (profile.exposure.mode === "ingress" && edge > 0 && direct.length > 0) {
+            problems.push(`With exposure.edgeProxies ${edge}, the Ingress forwards ${edge + 1} addresses on ${direct.join(", ")}, ` +
+                "where requests skip the web server, and the API, which trusts the one address the web server sends, " +
+                "records the nearest edge proxy for them. Pass the client address to the Ingress controller with " +
+                "the PROXY protocol instead, so the controller sees the client as its peer, and set edgeProxies to 0.");
+        }
+    }
+    const depth = rendered.XFF_DEPTH;
+    const defaultOrigin = "keeps its default origin, https and the Host header,";
+    const web = !depth
+        ? `trusts no forwarded header: it ${defaultOrigin} and takes the client address from the connection`
+        : `${rendered.PROTOCOL_HEADER ? "takes its origin from X-Forwarded-Proto and X-Forwarded-Host" : defaultOrigin} ` +
+            `and takes the client from the X-Forwarded-For entry ${depth === "1" ? "its peer wrote" : `${depth} hops away`} ` +
+            `(XFF_DEPTH ${depth})`;
+    const summary = `the web server ${web}, and the API trusts the one address the web server sends (TRUSTED_PROXY_HOPS 1)`;
+    if (problems.length)
+        return { code, ok: true, warning: true, message: `${problems.join(" ")} Rendered: ${summary}.` };
+    const traefik = profile.driver === "kubernetes-helm" && profile.exposure.mode === "ingress" && edge > 0
+        ? " The Ingress controller must trust the edge proxies' forwarded headers, such as Traefik's forwardedHeaders.trustedIPs."
+        : "";
+    return { code, ok: true, message: `With exposure.edgeProxies ${edge}, ${summary}.${traefik}` };
+}
+function profileFindings(projectRoot, profile) {
+    const modules = installedModules(projectRoot);
+    const findings = [
+        clientAddressFinding(profile),
+        idleTimeoutFinding(profile.runtimeConfig, (0, app_proxy_timeouts_1.readAppProxyTimeouts)(projectRoot)),
+    ];
+    const budget = connectionBudgetFinding(profile, modules);
+    if (budget)
+        findings.push(budget);
+    if (modules.has("audit-log"))
+        findings.push(auditLogFinding(profile.runtimeConfig));
+    return findings;
+}
+function formatFinding(finding) {
+    return `${finding.ok ? (finding.warning ? "warn" : "ok  ") : "FAIL"} ${finding.message}`;
+}

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

@@ -1,4 +1,4 @@
-import { MigrationProfile, ReleaseProfile, VerificationProfile } from "./deploy-schema";
+import { MigrationProfile, PostgresBudgetProfile, ReleaseProfile, VerificationProfile } from "./deploy-schema";
 /**
  * The Docker Compose deployment driver.
  *
@@ -32,6 +32,8 @@ export interface ComposeDependencyProfile {
     requiredKeys: string[];
     volume: string;
 }
+export interface ComposePostgresProfile extends ComposeDependencyProfile, PostgresBudgetProfile {
+}
 export interface ComposeObjectStorageProfile extends ComposeDependencyProfile {
     bucket: string;
     clientImage: string;
@@ -71,6 +73,8 @@ export interface DockerComposeProfileV1 {
         webSocketPaths: string[];
         /** Path prefixes under /api/ that the gateway sends to the API with /api removed. */
         apiPaths: string[];
+        /** Reverse proxies in front of the published port that append to X-Forwarded-For. */
+        edgeProxies: number;
         trustedProxyCidrs: string[];
         gatewayImage: string;
     };
@@ -80,7 +84,7 @@ export interface DockerComposeProfileV1 {
         worker: ComposeWorkloadProfile | null;
     };
     dependencies: {
-        postgres: ComposeDependencyProfile;
+        postgres: ComposePostgresProfile;
         redis: ComposeDependencyProfile;
         objectStorage: ComposeObjectStorageProfile;
     };