@podosoft/podokit 1.2.0 → 1.4.0

package/dist/add.d.ts

@@ -1,5 +1,6 @@
 import { type TemplateVars } from "@podosoft/podokit-template-engine";
-import { type ProviderCapability } from "@podosoft/podokit-runtime";
+import { type ProviderCapability, type ProviderSelections } from "@podosoft/podokit-runtime";
+import { type ApiPathResult } from "./module-api-paths";
 interface Injection {
     file: string;
     marker: string;
@@ -9,7 +10,7 @@ interface Injection {
 }
 /** Highest `module.manifest.json` schema version this CLI understands. A package
  *  module declaring a higher version is rejected rather than mis-applied. */
-export declare const SUPPORTED_MANIFEST_VERSION = 3;
+export declare const SUPPORTED_MANIFEST_VERSION = 4;
 export interface ModuleRuntimeConstraints {
     /** Maximum safe API replicas for process-local providers. */
     maxApiReplicas?: number;
@@ -79,6 +80,12 @@ export interface ModuleManifest {
     requiredProjectFiles?: string[];
     /** Stable source contracts that must be present in generated baseline files. */
     requiredProjectContents?: Record<string, string[]>;
+    /**
+     * Path prefixes under /api/ that the gateway must send straight to the API,
+     * such as routes taking bodies above the web server's BODY_SIZE_LIMIT. Merged
+     * into `.podokit/dev.json` and every deployment profile.
+     */
+    apiPaths?: string[];
 }
 export interface PackageOverlay {
     dependencies?: Record<string, string>;
@@ -111,6 +118,8 @@ export interface AddResult {
     adopted: string[];
     /** Files shipped, merged, or injected while applying the module. */
     touched: string[];
+    /** Direct API paths merged into `.podokit/dev.json` and deployment profiles. */
+    apiPaths: ApiPathResult;
 }
 export interface ResolvedModule {
     dir: string;
@@ -127,6 +136,8 @@ export declare function resolveModuleDir(name: string, modulesDir: string, proje
 /** Resolve a module and capture the package identity needed to replay external
  * modules during `podo update`. */
 export declare function resolveModule(name: string, modulesDir: string, projectRoot: string): ResolvedModule | null;
+/** Name of the module that implements the selected provider for a capability. */
+export declare function selectedProviderModule(modulesDir: string, projectRoot: string, providers: ProviderSelections, capability: ProviderCapability): string;
 /** List modules available to a project: the bundled ones under `modulesDir` plus,
  *  when `projectRoot` is given, any `@podosoft/podokit-module-*` packages installed
  *  in it. Bundled names take precedence on a clash. */

package/dist/add.js

@@ -4,6 +4,7 @@ exports.SUPPORTED_MANIFEST_VERSION = void 0;
 exports.modulePackageOverlays = modulePackageOverlays;
 exports.resolveModuleDir = resolveModuleDir;
 exports.resolveModule = resolveModule;
+exports.selectedProviderModule = selectedProviderModule;
 exports.listModules = listModules;
 exports.readModuleManifest = readModuleManifest;
 exports.addModule = addModule;
@@ -13,9 +14,11 @@ const node_module_1 = require("node:module");
 const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
 const podokit_runtime_1 = require("@podosoft/podokit-runtime");
 const lockfile_1 = require("./lockfile");
+const api_paths_1 = require("./api-paths");
+const module_api_paths_1 = require("./module-api-paths");
 /** Highest `module.manifest.json` schema version this CLI understands. A package
  *  module declaring a higher version is rejected rather than mis-applied. */
-exports.SUPPORTED_MANIFEST_VERSION = 3;
+exports.SUPPORTED_MANIFEST_VERSION = 4;
 /** Return the legacy targetApp package fields plus any additional app overlays. */
 function modulePackageOverlays(manifest) {
     const overlays = new Map();
@@ -100,17 +103,21 @@ function assertManifestVersion(name, manifest) {
             throw new Error(`Module "${name}" declares invalid provider ${capability}=${String(provider)}.`);
         }
     }
+    try {
+        (0, api_paths_1.parseApiPaths)(manifest.apiPaths ?? [], "apiPaths", []);
+    }
+    catch (error) {
+        throw new Error(`Module "${name}" declares invalid apiPaths. ${error.message}`);
+    }
     const maxApiReplicas = manifest.runtimeConstraints?.maxApiReplicas;
     if (maxApiReplicas !== undefined
         && (!Number.isSafeInteger(maxApiReplicas) || maxApiReplicas < 1)) {
         throw new Error(`Module "${name}" declares an invalid maxApiReplicas constraint.`);
     }
 }
-function providerModuleName(projectRoot, modulesDir, capability) {
-    const project = (0, lockfile_1.readManifest)(projectRoot);
-    if (!project)
-        throw new Error("Provider capabilities require a PodoKit project manifest.");
-    const selected = project.providers[capability];
+/** Name of the module that implements the selected provider for a capability. */
+function selectedProviderModule(modulesDir, projectRoot, providers, capability) {
+    const selected = providers[capability];
     for (const available of listModules(modulesDir, projectRoot)) {
         const resolved = resolveModule(available.name, modulesDir, projectRoot);
         if (!resolved)
@@ -122,6 +129,12 @@ function providerModuleName(projectRoot, modulesDir, capability) {
     throw new Error(`No module provides the selected ${capability} provider "${selected}". ` +
         `Choose another provider with podo provider set ${capability} <provider> --apply.`);
 }
+function providerModuleName(projectRoot, modulesDir, capability) {
+    const project = (0, lockfile_1.readManifest)(projectRoot);
+    if (!project)
+        throw new Error("Provider capabilities require a PodoKit project manifest.");
+    return selectedProviderModule(modulesDir, projectRoot, project.providers, capability);
+}
 function requiredModules(projectRoot, modulesDir, manifest) {
     const capabilities = (manifest.requiresCapabilities ?? []).map((capability) => providerModuleName(projectRoot, modulesDir, capability));
     return [...new Set([...(manifest.requires ?? []), ...capabilities])];
@@ -217,14 +230,24 @@ function projectName(projectRoot) {
     const pkg = readJson((0, node_path_1.join)(projectRoot, "package.json"));
     return typeof pkg.name === "string" ? pkg.name : "app";
 }
-function appendEnv(projectRoot, lines) {
+function appendEnv(projectRoot, lines, anchors = []) {
     const file = (0, node_path_1.join)(projectRoot, ".env.example");
     if (!(0, node_fs_1.existsSync)(file))
         return;
     const current = (0, node_fs_1.readFileSync)(file, "utf8");
-    const missing = lines.filter((line) => !current.split("\n").includes(line));
+    const existing = current.split("\n");
+    const missing = lines.filter((line) => !existing.includes(line));
     if (missing.length === 0)
         return;
+    // Each module appends its own blank-line separated block. Keep that shape
+    // when the block belongs in front of a displaced module's block.
+    const wanted = new Set(anchors);
+    const index = existing.findIndex((line, position) => position > 0 && existing[position - 1] === "" && wanted.has(line));
+    if (index !== -1) {
+        existing.splice(index, 0, ...missing, "");
+        (0, node_fs_1.writeFileSync)(file, existing.join("\n"));
+        return;
+    }
     const separator = current.endsWith("\n") ? "" : "\n";
     (0, node_fs_1.writeFileSync)(file, `${current}${separator}\n${missing.join("\n")}\n`);
 }
@@ -246,6 +269,91 @@ function isApplied(projectRoot, modulesDir, module) {
     }
     return false;
 }
+function injectionKey(file, marker) {
+    return `${file}\n${marker}`;
+}
+/** Modules `applyModule` would newly apply, in application order. */
+function plannedModules(projectRoot, module, modulesDir, planned = new Set(), order = []) {
+    planned.add(module);
+    const resolved = resolveModule(module, modulesDir, projectRoot);
+    if (!resolved)
+        return order;
+    for (const required of requiredModules(projectRoot, modulesDir, readModuleManifest(resolved.dir))) {
+        if (planned.has(required) || isApplied(projectRoot, modulesDir, required))
+            continue;
+        plannedModules(projectRoot, required, modulesDir, planned, order);
+    }
+    order.push(module);
+    return order;
+}
+function modulePlacement(projectRoot, module, modulesDir) {
+    const project = (0, lockfile_1.readManifest)(projectRoot);
+    if (!project)
+        return undefined;
+    const installed = [...project.modules].sort((a, b) => a.order - b.order);
+    const installedNames = new Set(installed.map((entry) => entry.name));
+    const fresh = new Set(plannedModules(projectRoot, module, modulesDir).filter((name) => !installedNames.has(name)));
+    if (!fresh.size)
+        return undefined;
+    const provided = new Set();
+    for (const name of fresh) {
+        const resolved = resolveModule(name, modulesDir, projectRoot);
+        if (!resolved)
+            continue;
+        for (const capability of Object.keys(readModuleManifest(resolved.dir).provides ?? {})) {
+            provided.add(capability);
+        }
+    }
+    const vars = {
+        projectName: projectName(projectRoot),
+        ...(0, lockfile_1.manifestTemplateVars)(project),
+    };
+    const manifests = installed.map((entry) => {
+        const resolved = resolveModule(entry.packageName ?? entry.name, modulesDir, projectRoot);
+        return resolved ? readModuleManifest(resolved.dir, vars) : undefined;
+    });
+    const first = manifests.findIndex((manifest) => manifest !== undefined && ((manifest.requires ?? []).some((name) => fresh.has(name))
+        || (manifest.requiresCapabilities ?? []).some((capability) => provided.has(capability))));
+    if (first === -1)
+        return undefined;
+    const injections = new Map();
+    const env = [];
+    for (const manifest of manifests.slice(first)) {
+        if (!manifest)
+            continue;
+        for (const injection of manifest.inject ?? []) {
+            const key = injectionKey(injection.file, injection.marker);
+            injections.set(key, [...(injections.get(key) ?? []), injection.text]);
+        }
+        env.push(...(manifest.env ?? []));
+    }
+    return { before: installed[first].name, injections, env };
+}
+/** Insert wiring at its marker, or in front of the first displaced module's wiring. */
+function injectAt(content, injection, anchors = []) {
+    if (!anchors.length || content.includes(injection.text)) {
+        return (0, podokit_template_engine_1.insertAtMarker)(content, injection.marker, injection.text);
+    }
+    const lines = content.split("\n");
+    const end = lines.findIndex((line) => line.includes(injection.marker));
+    if (end === -1)
+        throw new Error(`Marker not found: ${injection.marker}`);
+    const beginMarker = injection.marker.replace("podokit:end:", "podokit:begin:");
+    const begin = beginMarker === injection.marker
+        ? -1
+        : lines.slice(0, end).findIndex((line) => line.includes(beginMarker));
+    const wanted = new Set(anchors.map((text) => text.split("\n")[0].trim()));
+    let index = end;
+    for (let line = begin + 1; line < end; line += 1) {
+        if (wanted.has(lines[line].trim())) {
+            index = line;
+            break;
+        }
+    }
+    const indent = lines[end].match(/^\s*/)?.[0] ?? "";
+    lines.splice(index, 0, `${indent}${injection.text}`);
+    return lines.join("\n");
+}
 /**
  * Apply a module to an existing generated project: overlay files, merge the
  * target app's package.json dependencies and scripts, append env example lines,
@@ -262,16 +370,21 @@ function addModule(options) {
         })
             .map(([path]) => path)
         : [];
-    const result = applyModule(options.projectRoot, options.module, options.modulesDir, new Set(), options.adopt ?? false);
-    if (options.adopt && result.adopted.length) {
-        releaseOwnedPaths(options.projectRoot, result.adopted);
+    const placement = modulePlacement(options.projectRoot, options.module, options.modulesDir);
+    const applied = applyModule(options.projectRoot, options.module, options.modulesDir, new Set(), options.adopt ?? false, placement);
+    if (options.adopt && applied.adopted.length) {
+        releaseOwnedPaths(options.projectRoot, applied.adopted);
     }
     // Record the module (and any auto-added requirements), fold in the modules'
     // declared ownedGlobs, and refresh the lock.
-    const records = [...result.added, result.module]
+    const records = [...applied.added, applied.module]
         .map((name) => resolveModule(name, options.modulesDir, options.projectRoot))
         .filter((module) => module !== null)
         .map(moduleRecord);
+    const result = {
+        ...applied,
+        apiPaths: (0, module_api_paths_1.addApiPaths)(options.projectRoot, records.flatMap((record) => (record.appliedApiPaths ?? []).map((path) => ({ module: record.name, path })))),
+    };
     (0, lockfile_1.recordModules)(options.projectRoot, records, options.podokitVersion, result.ownedGlobs, previousLock
         ? {
             previous: previousLock,
@@ -279,10 +392,10 @@ function addModule(options) {
             modulePaths: [...new Set(result.touched)],
             adoptedPaths: result.adopted,
         }
-        : undefined, result.managedOverrides);
+        : undefined, result.managedOverrides, placement?.before);
     return result;
 }
-function applyModule(projectRoot, module, modulesDir, applied, adopt) {
+function applyModule(projectRoot, module, modulesDir, applied, adopt, placement) {
     const resolved = resolveModule(module, modulesDir, projectRoot);
     if (!resolved) {
         const available = listModules(modulesDir, projectRoot).map((m) => m.name);
@@ -318,8 +431,8 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt) {
     for (const required of requiredModules(projectRoot, modulesDir, manifest)) {
         if (applied.has(required) || isApplied(projectRoot, modulesDir, required))
             continue;
-        const result = applyModule(projectRoot, required, modulesDir, applied, adopt);
-        added.push(required, ...result.added);
+        const result = applyModule(projectRoot, required, modulesDir, applied, adopt, placement);
+        added.push(...result.added, required);
         ownedGlobs.push(...result.ownedGlobs);
         managedOverrides.push(...result.managedOverrides);
         preserved.push(...result.preserved);
@@ -356,7 +469,7 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt) {
     }
     // 3) append env example lines
     if (manifest.env?.length) {
-        appendEnv(projectRoot, manifest.env);
+        appendEnv(projectRoot, manifest.env, placement?.env);
         touched.push(".env.example");
     }
     // 4) inject wiring at markers
@@ -370,7 +483,8 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt) {
         const content = (0, node_fs_1.readFileSync)(target, "utf8");
         if (injection.optional && !content.includes(injection.marker))
             continue;
-        (0, node_fs_1.writeFileSync)(target, (0, podokit_template_engine_1.insertAtMarker)(content, injection.marker, injection.text));
+        const anchors = placement?.injections.get(injectionKey(injection.file, injection.marker));
+        (0, node_fs_1.writeFileSync)(target, injectAt(content, injection, anchors));
         touched.push(injection.file);
     }
     const instructions = (manifest.instructions ?? []).map((line) => line.replace(/<app>/g, appName));
@@ -386,12 +500,13 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt) {
     };
 }
 function moduleRecord(module) {
-    const migrations = readModuleManifest(module.dir).migrations ?? [];
+    const manifest = readModuleManifest(module.dir);
     return {
         name: module.name,
         packageName: module.packageName,
         moduleVersion: module.moduleVersion,
-        appliedMigrations: migrations.map((migration) => migration.id),
+        appliedMigrations: (manifest.migrations ?? []).map((migration) => migration.id),
+        ...(manifest.apiPaths?.length ? { appliedApiPaths: manifest.apiPaths } : {}),
     };
 }
 /** Copy a module overlay without clobbering app-owned presentation files. */

package/dist/api-paths.d.ts

@@ -0,0 +1,34 @@
+/** The prefix the gateway removes before a direct request reaches the API. */
+export declare const API_PATH_PREFIX = "/api";
+/** The path an entry names, without its optional trailing slash. */
+export declare function apiPathBase(path: string): string;
+/** The entry in `paths` that already routes `path` directly, if any. */
+export declare function coveringApiPath(paths: readonly string[], path: string): string | undefined;
+/**
+ * Validate the direct API path allowlist. Each entry covers its own path and
+ * every path below it, and must stay under /api/ outside the authentication
+ * routes, because the gateway removes /api before the request reaches the API.
+ */
+export declare function parseApiPaths(value: unknown, field: string, webSocketPaths: readonly string[]): string[];
+export interface ApiPathMerge {
+    /** The resulting list: the current entries followed by the added ones. */
+    paths: string[];
+    added: string[];
+    /** Paths left out because the list would no longer validate. */
+    rejected: {
+        path: string;
+        reason: string;
+    }[];
+}
+/**
+ * Append `additions` to `current`, skipping paths an entry already covers and
+ * paths that would make `validate` throw, such as an entry covering an existing
+ * one or a WebSocket path.
+ */
+export declare function mergeApiPaths(current: readonly string[], additions: readonly string[], validate: (paths: string[]) => void): ApiPathMerge;
+/** The direct API paths installed modules contributed, as a valid list for a new configuration. */
+export declare function installedApiPaths(modules: readonly {
+    appliedApiPaths?: string[];
+}[]): string[];
+/** Plan text naming the paths that reach the API without the web proxy. */
+export declare function directApiRoutes(apiPaths: readonly string[]): string;

package/dist/api-paths.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.API_PATH_PREFIX = void 0;
+exports.apiPathBase = apiPathBase;
+exports.coveringApiPath = coveringApiPath;
+exports.parseApiPaths = parseApiPaths;
+exports.mergeApiPaths = mergeApiPaths;
+exports.installedApiPaths = installedApiPaths;
+exports.directApiRoutes = directApiRoutes;
+const MAX_PATHS = 32;
+const MAX_PATH_LENGTH = 2_048;
+const API_PATH = /^\/api(?:\/[A-Za-z0-9._~-]+)+\/?$/;
+/** The prefix the gateway removes before a direct request reaches the API. */
+exports.API_PATH_PREFIX = "/api";
+/** The path an entry names, without its optional trailing slash. */
+function apiPathBase(path) {
+    return path.endsWith("/") ? path.slice(0, -1) : path;
+}
+/** Whether `base` covers `path`: the same path or any path below it. */
+function covers(base, path) {
+    return path === base || path.startsWith(`${base}/`);
+}
+/** The entry in `paths` that already routes `path` directly, if any. */
+function coveringApiPath(paths, path) {
+    const base = apiPathBase(path);
+    return paths.find((entry) => covers(apiPathBase(entry), base));
+}
+/**
+ * Validate the direct API path allowlist. Each entry covers its own path and
+ * every path below it, and must stay under /api/ outside the authentication
+ * routes, because the gateway removes /api before the request reaches the API.
+ */
+function parseApiPaths(value, field, webSocketPaths) {
+    if (!Array.isArray(value)) {
+        throw new Error(`Configuration field "${field}" must be an array of path prefixes under /api/.`);
+    }
+    if (value.length > MAX_PATHS) {
+        throw new Error(`Configuration field "${field}" must contain at most ${MAX_PATHS} paths.`);
+    }
+    const paths = [];
+    for (const path of value) {
+        if (typeof path !== "string" ||
+            path.length > MAX_PATH_LENGTH ||
+            !API_PATH.test(path) ||
+            path.split("/").some((segment) => segment === "." || segment === "..")) {
+            throw new Error(`Configuration field "${field}" must contain only static path prefixes under /api/, such as "/api/files/uploads/". /api/ itself, patterns, queries, fragments, encoded characters, empty segments, and traversal segments are not allowed.`);
+        }
+        const base = apiPathBase(path);
+        if (covers("/api/auth", base)) {
+            throw new Error(`Configuration field "${field}" cannot list "${path}": the API serves /api/auth/ with its prefix, so authentication routes always go through the web proxy.`);
+        }
+        const overlap = paths.find((other) => {
+            const otherBase = apiPathBase(other);
+            return covers(otherBase, base) || covers(base, otherBase);
+        });
+        if (overlap !== undefined) {
+            throw new Error(overlap === path
+                ? `Configuration field "${field}" contains duplicate path "${path}".`
+                : `Configuration field "${field}" contains overlapping paths "${overlap}" and "${path}".`);
+        }
+        const socket = webSocketPaths.find((socketPath) => covers(base, socketPath));
+        if (socket !== undefined) {
+            throw new Error(`Configuration field "${field}" entry "${path}" covers WebSocket path "${socket}", which goes to the API without removing /api.`);
+        }
+        paths.push(path);
+    }
+    return paths;
+}
+/**
+ * Append `additions` to `current`, skipping paths an entry already covers and
+ * paths that would make `validate` throw, such as an entry covering an existing
+ * one or a WebSocket path.
+ */
+function mergeApiPaths(current, additions, validate) {
+    const paths = [...current];
+    const added = [];
+    const rejected = [];
+    for (const path of additions) {
+        if (coveringApiPath(paths, path) !== undefined)
+            continue;
+        const candidate = [...paths, path];
+        try {
+            validate(candidate);
+        }
+        catch (error) {
+            rejected.push({ path, reason: error.message });
+            continue;
+        }
+        paths.push(path);
+        added.push(path);
+    }
+    return { paths, added, rejected };
+}
+/** The direct API paths installed modules contributed, as a valid list for a new configuration. */
+function installedApiPaths(modules) {
+    return mergeApiPaths([], modules.flatMap((module) => module.appliedApiPaths ?? []), (paths) => parseApiPaths(paths, "apiPaths", [])).paths;
+}
+/** Plan text naming the paths that reach the API without the web proxy. */
+function directApiRoutes(apiPaths) {
+    return apiPaths.length
+        ? ` Route ${apiPaths.join(", ")} directly to the API without /api.`
+        : "";
+}

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

@@ -69,6 +69,8 @@ export interface DockerComposeProfileV1 {
         bindAddress: string;
         port: number;
         webSocketPaths: string[];
+        /** Path prefixes under /api/ that the gateway sends to the API with /api removed. */
+        apiPaths: string[];
         trustedProxyCidrs: string[];
         gatewayImage: string;
     };
@@ -107,4 +109,6 @@ export interface ComposeProfileSummary {
     profile: DockerComposeProfileV1;
 }
 export declare function initializeComposeProfile(projectRoot: string, name: string, options: InitializeComposeProfileOptions): ComposeProfileSummary;
+/** The gateway runs only when some path must bypass the web service. */
+export declare function composeHasGateway(profile: DockerComposeProfileV1): boolean;
 export declare function composeProfileDigest(profile: DockerComposeProfileV1): string;

package/dist/deploy-compose-profile.js

@@ -3,12 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseComposeProfile = parseComposeProfile;
 exports.buildDefaultComposeProfile = buildDefaultComposeProfile;
 exports.initializeComposeProfile = initializeComposeProfile;
+exports.composeHasGateway = composeHasGateway;
 exports.composeProfileDigest = composeProfileDigest;
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_net_1 = require("node:net");
 const lockfile_1 = require("./lockfile");
 const deploy_schema_1 = require("./deploy-schema");
+const api_paths_1 = require("./api-paths");
 const websocket_paths_1 = require("./websocket-paths");
 /** 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})?)$/;
@@ -167,6 +169,7 @@ function parseComposeProfile(value) {
         "bindAddress",
         "port",
         "webSocketPaths",
+        "apiPaths",
         "trustedProxyCidrs",
         "gatewayImage",
     ], "exposure");
@@ -197,9 +200,10 @@ function parseComposeProfile(value) {
     if (port > 65535)
         throw new Error("Deployment exposure.port must be a TCP port.");
     const webSocketPaths = (0, websocket_paths_1.parseExactWebSocketPaths)(exposure.webSocketPaths ?? [], "exposure.webSocketPaths");
+    const apiPaths = (0, api_paths_1.parseApiPaths)(exposure.apiPaths ?? [], "exposure.apiPaths", webSocketPaths);
     const trustedProxyCidrs = parseTrustedProxyCidrs(exposure.trustedProxyCidrs ?? [], "exposure.trustedProxyCidrs");
-    if (trustedProxyCidrs.length > 0 && webSocketPaths.length === 0) {
-        throw new Error("Deployment exposure.trustedProxyCidrs requires at least one exposure.webSocketPaths entry.");
+    if (trustedProxyCidrs.length > 0 && webSocketPaths.length === 0 && apiPaths.length === 0) {
+        throw new Error("Deployment exposure.trustedProxyCidrs requires at least one exposure.webSocketPaths or exposure.apiPaths entry.");
     }
     const gatewayImage = exposure.gatewayImage === undefined
         ? "caddy:2.10-alpine"
@@ -238,6 +242,7 @@ function parseComposeProfile(value) {
             bindAddress,
             port,
             webSocketPaths,
+            apiPaths,
             trustedProxyCidrs,
             gatewayImage,
         },
@@ -302,6 +307,7 @@ function buildDefaultComposeProfile(projectName, options) {
             bindAddress: "127.0.0.1",
             port: 8080,
             webSocketPaths: [],
+            apiPaths: [],
             trustedProxyCidrs: [],
             gatewayImage: "caddy:2.10-alpine",
         },
@@ -385,6 +391,7 @@ function initializeComposeProfile(projectRoot, name, options) {
         || providers.events === "memory"
         || providers.jobs === "local";
     draft.workloads.api.replicas = usesEmbeddedProviders ? 1 : 2;
+    draft.exposure.apiPaths = (0, api_paths_1.installedApiPaths)(manifest.modules);
     draft.dependencies.postgres.mode = providers.database === "postgres" ? "managed" : "disabled";
     draft.dependencies.redis.mode = usesRedis ? "managed" : "disabled";
     draft.dependencies.objectStorage.mode = providers["object-storage"] === "s3"
@@ -423,6 +430,10 @@ function initializeComposeProfile(projectRoot, name, options) {
     (0, node_fs_1.writeFileSync)(path, `${JSON.stringify(validated, null, 2)}\n`, { flag: "wx" });
     return { name, path, profile: validated };
 }
+/** The gateway runs only when some path must bypass the web service. */
+function composeHasGateway(profile) {
+    return profile.exposure.webSocketPaths.length > 0 || profile.exposure.apiPaths.length > 0;
+}
 function composeProfileDigest(profile) {
     return `sha256:${(0, node_crypto_1.createHash)("sha256").update(JSON.stringify(profile)).digest("hex")}`;
 }

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

@@ -1,4 +1,4 @@
-import type { DockerComposeProfileV1 } from "./deploy-compose-profile";
+import { type DockerComposeProfileV1 } from "./deploy-compose-profile";
 /**
  * Compose project rendering.
  *

package/dist/deploy-compose-render.js

@@ -10,6 +10,8 @@ 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 api_paths_1 = require("./api-paths");
+const deploy_compose_profile_1 = require("./deploy-compose-profile");
 const deploy_schema_1 = require("./deploy-schema");
 const lockfile_1 = require("./lockfile");
 const toolchain_1 = require("./toolchain");
@@ -249,12 +251,26 @@ function gatewayService(profile, image, release, stateDigest) {
 }
 `
         : "";
+    const api = `${serviceName(profile, "api")}:${CONTAINER_PORT}`;
+    const webSocketRoutes = profile.exposure.webSocketPaths.length
+        ? `  @api_websockets path ${profile.exposure.webSocketPaths.join(" ")}\n` +
+            `  handle @api_websockets {\n` +
+            `    reverse_proxy ${api}\n` +
+            `  }\n`
+        : "";
+    const apiPathRoutes = profile.exposure.apiPaths.length
+        ? `  @api_paths path ${profile.exposure.apiPaths
+            .map((path) => `${(0, api_paths_1.apiPathBase)(path)} ${(0, api_paths_1.apiPathBase)(path)}/*`)
+            .join(" ")}\n` +
+            `  handle @api_paths {\n` +
+            `    uri strip_prefix ${api_paths_1.API_PATH_PREFIX}\n` +
+            `    reverse_proxy ${api}\n` +
+            `  }\n`
+        : "";
     const caddyfile = globalOptions +
         `:3000 {\n` +
-        `  @api_websockets path ${profile.exposure.webSocketPaths.join(" ")}\n` +
-        `  handle @api_websockets {\n` +
-        `    reverse_proxy ${serviceName(profile, "api")}:${CONTAINER_PORT}\n` +
-        `  }\n` +
+        webSocketRoutes +
+        apiPathRoutes +
         `  handle {\n` +
         `    reverse_proxy ${serviceName(profile, "web")}:${CONTAINER_PORT}\n` +
         `  }\n` +
@@ -278,7 +294,7 @@ function gatewayService(profile, image, release, stateDigest) {
 }
 function renderComposeDocument(profile, release, images, stateDigest, workerCommand = ["bun", "dist/main-worker.js"]) {
     const services = [];
-    const hasGateway = profile.exposure.webSocketPaths.length > 0;
+    const hasGateway = (0, deploy_compose_profile_1.composeHasGateway)(profile);
     if (profile.dependencies.postgres.mode === "managed" && images.postgres) {
         services.push(postgresService(profile, images.postgres));
     }
@@ -300,7 +316,7 @@ function renderComposeDocument(profile, release, images, stateDigest, workerComm
     }));
     if (hasGateway) {
         if (!images.gateway) {
-            throw new Error("A resolved gateway image is required when WebSocket paths are configured.");
+            throw new Error("A resolved gateway image is required when WebSocket or API paths are configured.");
         }
         services.push(gatewayService(profile, images.gateway, release, stateDigest));
     }
@@ -350,7 +366,7 @@ function defaultComposeImages(profile, release) {
     return {
         api: `${profile.release.apiRepository}:${release}`,
         web: `${profile.release.webRepository}:${release}`,
-        gateway: profile.exposure.webSocketPaths.length > 0 ? profile.exposure.gatewayImage : null,
+        gateway: (0, deploy_compose_profile_1.composeHasGateway)(profile) ? profile.exposure.gatewayImage : null,
         postgres: profile.dependencies.postgres.mode === "managed"
             ? profile.dependencies.postgres.image
             : null,

package/dist/deploy-compose.js

@@ -11,6 +11,7 @@ exports.rollbackComposeDeployment = rollbackComposeDeployment;
 exports.composeRuntimeRoot = composeRuntimeRoot;
 const node_crypto_1 = require("node:crypto");
 const node_path_1 = require("node:path");
+const api_paths_1 = require("./api-paths");
 const deploy_driver_1 = require("./deploy-driver");
 const deploy_compose_exec_1 = require("./deploy-compose-exec");
 const deploy_compose_sync_1 = require("./deploy-compose-sync");
@@ -373,7 +374,7 @@ function planComposeDeployment(projectRoot, profileName, release, runner = deplo
     actions.push({
         order: order++,
         kind: "application",
-        description: `Roll out api, web${profile.workloads.worker ? ", worker" : ""}${profile.exposure.webSocketPaths.length ? ", gateway" : ""} and wait for health.`,
+        description: `Roll out api, web${profile.workloads.worker ? ", worker" : ""}${(0, deploy_compose_profile_1.composeHasGateway)(profile) ? ", gateway" : ""} and wait for health.${(0, api_paths_1.directApiRoutes)(profile.exposure.apiPaths)}`,
     });
     actions.push({
         order: order++,

package/dist/deploy-profile.d.ts

@@ -50,6 +50,8 @@ export interface DeployProfileV1 {
         ingressClassName: string;
         tlsSecretName: string | null;
         webSocketPaths: string[];
+        /** Path prefixes under /api/ that the Ingress sends to the API with /api removed. */
+        apiPaths: string[];
     };
     workloads: {
         api: WorkloadProfile;
@@ -78,6 +80,7 @@ export interface DeploymentProfileSummary {
     path: string;
     profile: DeployProfileV1;
 }
+export declare function parseDeploymentProfile(value: unknown): DeployProfileV1;
 export declare function loadDeploymentProfile(projectRoot: string, name: string): DeployProfileV1;
 export declare function listDeploymentProfiles(projectRoot: string): DeploymentProfileSummary[];
 export interface InitializeDeploymentProfileOptions {