@podosoft/podokit 1.3.0 → 1.4.0

package/dist/add.d.ts

@@ -1,5 +1,6 @@
 import { type TemplateVars } from "@podosoft/podokit-template-engine";
 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;

package/dist/add.js

@@ -14,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();
@@ -101,6 +103,12 @@ 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)) {
@@ -363,16 +371,20 @@ function addModule(options) {
             .map(([path]) => path)
         : [];
     const placement = modulePlacement(options.projectRoot, options.module, options.modulesDir);
-    const result = applyModule(options.projectRoot, options.module, options.modulesDir, new Set(), options.adopt ?? false, placement);
-    if (options.adopt && result.adopted.length) {
-        releaseOwnedPaths(options.projectRoot, result.adopted);
+    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,
@@ -488,12 +500,13 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt, placement)
     };
 }
 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 {

package/dist/deploy-profile.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.profilePath = exports.profileDirectory = void 0;
+exports.parseDeploymentProfile = parseDeploymentProfile;
 exports.loadDeploymentProfile = loadDeploymentProfile;
 exports.listDeploymentProfiles = listDeploymentProfiles;
 exports.initializeDeploymentProfile = initializeDeploymentProfile;
@@ -11,6 +12,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 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");
 var deploy_schema_2 = require("./deploy-schema");
 Object.defineProperty(exports, "profileDirectory", { enumerable: true, get: function () { return deploy_schema_2.profileDirectory; } });
@@ -84,7 +86,7 @@ function parseStatefulDependency(value, field, extraKeys = []) {
 function parseRedisDependency(value, field) {
     return parseStatefulDependency(value, field);
 }
-function parseProfile(value) {
+function parseDeploymentProfile(value) {
     if (!(0, deploy_schema_1.isRecord)(value))
         throw new Error("Deployment profile must be a JSON object.");
     (0, deploy_schema_1.assertOnlyKeys)(value, [
@@ -117,7 +119,7 @@ function parseProfile(value) {
     const runtimeConfig = (0, deploy_schema_1.requiredRecord)(value, "runtimeConfig");
     (0, deploy_schema_1.assertOnlyKeys)(target, ["context", "clusterFingerprint", "namespace", "release", "createNamespace"], "target");
     (0, deploy_schema_1.assertOnlyKeys)(release, ["strategy", "tagPattern", "apiRepository", "webRepository"], "release");
-    (0, deploy_schema_1.assertOnlyKeys)(exposure, ["mode", "host", "ingressClassName", "tlsSecretName", "webSocketPaths"], "exposure");
+    (0, deploy_schema_1.assertOnlyKeys)(exposure, ["mode", "host", "ingressClassName", "tlsSecretName", "webSocketPaths", "apiPaths"], "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", "imagePull"], "secrets");
@@ -167,6 +169,10 @@ function parseProfile(value) {
     if (exposureMode === "nodePort" && webSocketPaths.length > 0) {
         throw new Error("Deployment exposure.webSocketPaths requires exposure.mode ingress.");
     }
+    const apiPaths = (0, api_paths_1.parseApiPaths)(exposure.apiPaths ?? [], "exposure.apiPaths", webSocketPaths);
+    if (exposureMode === "nodePort" && apiPaths.length > 0) {
+        throw new Error("Deployment exposure.apiPaths requires exposure.mode ingress.");
+    }
     const postgres = parseStatefulDependency((0, deploy_schema_1.requiredRecord)(dependencies, "postgres"), "dependencies.postgres");
     const redis = parseRedisDependency((0, deploy_schema_1.requiredRecord)(dependencies, "redis"), "dependencies.redis");
     const objectStorageRecord = (0, deploy_schema_1.requiredRecord)(dependencies, "objectStorage");
@@ -210,6 +216,7 @@ function parseProfile(value) {
             ingressClassName,
             tlsSecretName,
             webSocketPaths,
+            apiPaths,
         },
         workloads: {
             api: parseWorkload((0, deploy_schema_1.requiredRecord)(workloads, "api"), "workloads.api"),
@@ -246,7 +253,7 @@ function loadDeploymentProfile(projectRoot, name) {
     catch (error) {
         throw new Error(`Cannot read deployment profile "${name}": ${error.message}`);
     }
-    return parseProfile(parsed);
+    return parseDeploymentProfile(parsed);
 }
 function listDeploymentProfiles(projectRoot) {
     const directory = (0, deploy_schema_1.profileDirectory)(projectRoot);
@@ -319,6 +326,7 @@ function initializeDeploymentProfile(projectRoot, name, options) {
             ingressClassName: "traefik",
             tlsSecretName: null,
             webSocketPaths: [],
+            apiPaths: (0, api_paths_1.installedApiPaths)(manifest.modules),
         },
         workloads: {
             api: {
@@ -418,7 +426,7 @@ function initializeDeploymentProfile(projectRoot, name, options) {
             ],
         },
     };
-    const validated = parseProfile(defaultProfile);
+    const validated = parseDeploymentProfile(defaultProfile);
     (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 };

package/dist/deploy-render.js

@@ -5,6 +5,7 @@ const node_fs_1 = require("node:fs");
 const node_crypto_1 = require("node:crypto");
 const node_path_1 = require("node:path");
 const deploy_profile_1 = require("./deploy-profile");
+const api_paths_1 = require("./api-paths");
 const lockfile_1 = require("./lockfile");
 const toolchain_1 = require("./toolchain");
 function quote(value) {
@@ -525,6 +526,57 @@ spec:
       app.kubernetes.io/name: ${name}
 `;
 }
+function ingressPath(path, pathType, service) {
+    return `          - path: ${quote(path)}
+            pathType: ${pathType}
+            backend:
+              service:
+                name: ${service}
+                port: { number: 3000 }
+`;
+}
+/**
+ * Direct API paths need /api removed on the way to the API, which a standard
+ * Ingress cannot express, so they get their own Ingress with a Traefik
+ * stripPrefix middleware. ImplementationSpecific makes Traefik match the
+ * trailing-slash prefix as a plain PathPrefix, and the Exact path adds the bare
+ * path, so every controller version routes the same set of requests.
+ */
+function apiPathIngress(profile, tls) {
+    if (profile.exposure.apiPaths.length === 0)
+        return "";
+    const apiService = `${profile.target.release}-api`;
+    const middleware = `${profile.target.release}-strip-api-prefix`;
+    const paths = profile.exposure.apiPaths
+        .map((path) => {
+        const base = (0, api_paths_1.apiPathBase)(path);
+        return (ingressPath(base, "Exact", apiService) +
+            ingressPath(`${base}/`, "ImplementationSpecific", apiService));
+    })
+        .join("");
+    return `---
+apiVersion: traefik.io/v1alpha1
+kind: Middleware
+metadata:
+  name: ${middleware}
+spec:
+  stripPrefix:
+    prefixes: [${quote(api_paths_1.API_PATH_PREFIX)}]
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: ${profile.target.release}-api-paths
+  annotations:
+    traefik.ingress.kubernetes.io/router.middlewares: ${quote(`${profile.target.namespace}-${middleware}@kubernetescrd`)}
+spec:
+  ingressClassName: ${quote(profile.exposure.ingressClassName)}
+${tls}  rules:
+    - host: ${quote(profile.exposure.host)}
+      http:
+        paths:
+${paths}`;
+}
 function exposure(profile) {
     const webService = `${profile.target.release}-web`;
     const apiService = `${profile.target.release}-api`;
@@ -548,13 +600,7 @@ spec:
 `
         : "";
     const webSocketPaths = profile.exposure.webSocketPaths
-        .map((path) => `          - path: ${quote(path)}
-            pathType: Exact
-            backend:
-              service:
-                name: ${apiService}
-                port: { number: 3000 }
-`)
+        .map((path) => ingressPath(path, "Exact", apiService))
         .join("");
     return `apiVersion: networking.k8s.io/v1
 kind: Ingress
@@ -572,7 +618,7 @@ ${webSocketPaths}          - path: /
               service:
                 name: ${webService}
                 port: { number: 3000 }
-`;
+${apiPathIngress(profile, tls)}`;
 }
 function applicationManifest(profile, images, rolloutStateDigest, workerCommand) {
     const runtimeConfigDigest = derivedRuntimeConfigDigest(profile);

package/dist/deploy.js

@@ -13,6 +13,7 @@ const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
+const api_paths_1 = require("./api-paths");
 const deploy_profile_1 = require("./deploy-profile");
 const deploy_render_1 = require("./deploy-render");
 function defaultRunner(command, args, options) {
@@ -168,6 +169,25 @@ function doctorDeployment(projectRoot, profileName, runner = defaultRunner) {
                 ? `IngressClass ${profile.exposure.ingressClassName} exists.`
                 : `IngressClass ${profile.exposure.ingressClassName} is missing or inaccessible.`,
         });
+        if (profile.exposure.apiPaths.length > 0) {
+            // Direct API paths remove /api with a Traefik Middleware resource.
+            const middlewareCrd = runner("kubectl", [
+                "--context",
+                profile.target.context,
+                "get",
+                "crd",
+                "middlewares.traefik.io",
+                "-o",
+                "name",
+            ], { capture: true });
+            findings.push({
+                code: "crd:middlewares.traefik.io",
+                ok: middlewareCrd.status === 0,
+                message: middlewareCrd.status === 0
+                    ? "Traefik Middleware resources are available for exposure.apiPaths."
+                    : "exposure.apiPaths needs the Traefik Middleware CRD (middlewares.traefik.io); serve the IngressClass with Traefik or remove exposure.apiPaths.",
+            });
+        }
         if (profile.exposure.tlsSecretName) {
             const tlsType = runner("kubectl", kubectlArgs(profile, [
                 "get",
@@ -465,7 +485,7 @@ function planDeployment(projectRoot, profileName, release, runner = defaultRunne
             {
                 order: 3,
                 kind: "application",
-                description: `Roll out API, web${profile.workloads.worker ? ", and worker" : ""} workloads with zero unavailable replicas.`,
+                description: `Roll out API, web${profile.workloads.worker ? ", and worker" : ""} workloads with zero unavailable replicas.${(0, api_paths_1.directApiRoutes)(profile.exposure.apiPaths)}`,
             },
             {
                 order: 4,