@podosoft/podokit 1.2.0 → 1.4.0

package/dist/lockfile.js

@@ -54,6 +54,9 @@ exports.DEFAULT_OWNED_GLOBS = [
     "apps/web/src/lib/i18n/catalogs/app/**",
     // Owned Elysia extension slot — register application services and plugins here.
     "apps/api/src/app.extensions.ts",
+    // Owned additions to the managed /api proxy's header lists and body limits.
+    "apps/web/src/lib/server/proxy-headers.ts",
+    "apps/web/src/lib/server/body-limits.ts",
     // AI agent guidance — yours to customize; update never touches it.
     "AGENTS.md",
     "CLAUDE.md",
@@ -257,29 +260,46 @@ function mergeOwnedGlobs(existing, add) {
  * `ownedGlobs` a module declares are merged into the manifest so its owned paths
  * survive every future recompute. No-op on projects without a manifest.
  */
-function recordModules(projectRoot, moduleInputs, version, ownedGlobs, lockSnapshot, managedOverrides) {
+function recordModules(projectRoot, moduleInputs, version, ownedGlobs, lockSnapshot, managedOverrides, 
+/** Installed module that newly recorded modules must configure before. */
+insertBefore) {
     const manifest = readManifest(projectRoot);
     if (!manifest)
         return;
     const stampedWith = version ?? podokitVersion();
-    const known = new Set(manifest.modules.map((m) => m.name));
+    const fresh = [];
     for (const input of moduleInputs) {
         const module = typeof input === "string" ? { name: input } : input;
-        const existing = manifest.modules.find((entry) => entry.name === module.name);
+        const existing = manifest.modules.find((entry) => entry.name === module.name)
+            ?? fresh.find((entry) => entry.name === module.name);
         if (existing) {
             existing.packageName = module.packageName ?? existing.packageName;
             existing.moduleVersion = module.moduleVersion ?? existing.moduleVersion;
+            const apiPaths = [
+                ...new Set([...(existing.appliedApiPaths ?? []), ...(module.appliedApiPaths ?? [])]),
+            ];
+            if (apiPaths.length)
+                existing.appliedApiPaths = apiPaths;
             continue;
         }
-        manifest.modules.push({
+        fresh.push({
             name: module.name,
-            order: manifest.modules.length,
+            order: manifest.modules.length + fresh.length,
             addedWith: stampedWith,
             packageName: module.packageName,
             moduleVersion: module.moduleVersion,
             appliedMigrations: module.appliedMigrations,
+            ...(module.appliedApiPaths?.length ? { appliedApiPaths: module.appliedApiPaths } : {}),
         });
-        known.add(module.name);
+    }
+    const ordered = [...manifest.modules].sort((a, b) => a.order - b.order);
+    const position = insertBefore ? ordered.findIndex((entry) => entry.name === insertBefore) : -1;
+    if (position === -1) {
+        manifest.modules.push(...fresh);
+    }
+    else {
+        ordered.splice(position, 0, ...fresh);
+        manifest.modules = ordered.map((entry, order) => ({ ...entry, order }));
     }
     if (ownedGlobs?.length)
         manifest.ownedGlobs = mergeOwnedGlobs(manifest.ownedGlobs, ownedGlobs);

package/dist/module-api-paths.d.ts

@@ -0,0 +1,52 @@
+import type { ManifestModule } from "./lockfile";
+/**
+ * Modules declare the direct API paths their routes need (`apiPaths` in
+ * `module.manifest.json`). The development gateway configuration and the
+ * deployment profiles belong to the application, so PodoKit edits only their
+ * `apiPaths` lists, keeps every other key in place, and never writes a file
+ * that would stop validating.
+ */
+export declare const DEV_CONFIG_FILE = ".podokit/dev.json";
+/** A path that a module declares. */
+export interface ModuleApiPath {
+    module: string;
+    path: string;
+}
+/** A path written to, or removed from, one configuration file. */
+export interface ApiPathChange extends ModuleApiPath {
+    file: string;
+}
+/** A path left as it was in one configuration file, and why. */
+export interface ApiPathSkip extends ApiPathChange {
+    reason: string;
+}
+export interface ApiPathResult {
+    changed: ApiPathChange[];
+    skipped: ApiPathSkip[];
+}
+export interface ApiPathOptions {
+    /** Report the changes without writing them. */
+    dryRun?: boolean;
+    /**
+     * Text of a configuration file, or null when it does not exist. Defaults to
+     * the file on disk; an update plan passes the file it would create.
+     */
+    read?: (file: string) => string | null;
+}
+/**
+ * Add module paths to `.podokit/dev.json` and every deployment profile. A path
+ * that an entry already covers is left alone; a path that would make the file
+ * invalid, for example by covering a WebSocket path or another entry, is
+ * reported instead of written.
+ */
+export declare function addApiPaths(projectRoot: string, paths: readonly ModuleApiPath[], options?: ApiPathOptions): ApiPathResult;
+/**
+ * Remove exactly these paths from `.podokit/dev.json` and every deployment
+ * profile. A file that would stop validating without them, such as a Compose
+ * profile whose `trustedProxyCidrs` needs a direct path, is left unchanged.
+ */
+export declare function removeApiPaths(projectRoot: string, paths: readonly ModuleApiPath[]): ApiPathResult;
+/** Paths a module declares that the project has not merged yet. */
+export declare function pendingApiPaths(module: Pick<ManifestModule, "name" | "appliedApiPaths">, declared: readonly string[]): ModuleApiPath[];
+/** Indented report lines, one per changed or skipped path. */
+export declare function describeApiPaths(result: ApiPathResult, verb: "add" | "remove"): string[];

package/dist/module-api-paths.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEV_CONFIG_FILE = void 0;
+exports.addApiPaths = addApiPaths;
+exports.removeApiPaths = removeApiPaths;
+exports.pendingApiPaths = pendingApiPaths;
+exports.describeApiPaths = describeApiPaths;
+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_profile_1 = require("./deploy-profile");
+const deploy_schema_1 = require("./deploy-schema");
+const websocket_paths_1 = require("./websocket-paths");
+/**
+ * Modules declare the direct API paths their routes need (`apiPaths` in
+ * `module.manifest.json`). The development gateway configuration and the
+ * deployment profiles belong to the application, so PodoKit edits only their
+ * `apiPaths` lists, keeps every other key in place, and never writes a file
+ * that would stop validating.
+ */
+exports.DEV_CONFIG_FILE = ".podokit/dev.json";
+const DEPLOY_DIRECTORY = ".podokit/deploy";
+/** `.podokit/dev.json` followed by every deployment profile, project-relative. */
+function configFiles(projectRoot) {
+    const directory = (0, node_path_1.join)(projectRoot, DEPLOY_DIRECTORY);
+    const profiles = (0, node_fs_1.existsSync)(directory)
+        ? (0, node_fs_1.readdirSync)(directory)
+            .filter((entry) => entry.endsWith(".json"))
+            .sort()
+            .map((entry) => `${DEPLOY_DIRECTORY}/${entry}`)
+        : [];
+    return [exports.DEV_CONFIG_FILE, ...profiles];
+}
+function readDisk(projectRoot, file) {
+    const path = (0, node_path_1.join)(projectRoot, file);
+    return (0, node_fs_1.existsSync)(path) ? (0, node_fs_1.readFileSync)(path, "utf8") : null;
+}
+function parseDocument(file, text) {
+    let root;
+    try {
+        root = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`Cannot read ${file}: ${error.message}`);
+    }
+    if (!(0, deploy_schema_1.isRecord)(root))
+        throw new Error(`${file} must contain a JSON object.`);
+    const style = {
+        indent: /^[ \t]+(?=")/m.exec(text)?.[0] ?? "  ",
+        newline: text.endsWith("\n") ? "\n" : "",
+    };
+    if (file === exports.DEV_CONFIG_FILE) {
+        return {
+            root,
+            holder: root,
+            current: currentPaths(file, root),
+            validate: (apiPaths) => {
+                const webSocketPaths = (0, websocket_paths_1.parseExactWebSocketPaths)(root.webSocketPaths ?? [], `${exports.DEV_CONFIG_FILE}.webSocketPaths`);
+                (0, api_paths_1.parseApiPaths)(apiPaths, `${exports.DEV_CONFIG_FILE}.apiPaths`, webSocketPaths);
+            },
+            ...style,
+        };
+    }
+    const exposure = root.exposure;
+    if (!(0, deploy_schema_1.isRecord)(exposure))
+        throw new Error(`${file} has no exposure object.`);
+    const parse = root.driver === "docker-compose" ? deploy_compose_profile_1.parseComposeProfile : deploy_profile_1.parseDeploymentProfile;
+    return {
+        root,
+        holder: exposure,
+        current: currentPaths(file, exposure),
+        // The whole profile is checked, so driver rules such as Kubernetes
+        // requiring ingress exposure for apiPaths apply too.
+        validate: (apiPaths) => {
+            parse({ ...root, exposure: { ...exposure, apiPaths } });
+        },
+        ...style,
+    };
+}
+function currentPaths(file, holder) {
+    const value = holder.apiPaths ?? [];
+    if (!Array.isArray(value) || value.some((path) => typeof path !== "string")) {
+        throw new Error(`apiPaths in ${file} must be an array of paths.`);
+    }
+    return value;
+}
+function writeDocument(projectRoot, file, document) {
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(projectRoot, file), `${JSON.stringify(document.root, null, document.indent)}${document.newline}`);
+}
+/**
+ * Add module paths to `.podokit/dev.json` and every deployment profile. A path
+ * that an entry already covers is left alone; a path that would make the file
+ * invalid, for example by covering a WebSocket path or another entry, is
+ * reported instead of written.
+ */
+function addApiPaths(projectRoot, paths, options = {}) {
+    const result = { changed: [], skipped: [] };
+    if (paths.length === 0)
+        return result;
+    const read = options.read ?? ((file) => readDisk(projectRoot, file));
+    for (const file of configFiles(projectRoot)) {
+        const text = read(file);
+        if (text === null) {
+            for (const entry of paths) {
+                result.skipped.push({ ...entry, file, reason: "the file does not exist" });
+            }
+            continue;
+        }
+        let document;
+        try {
+            document = parseDocument(file, text);
+        }
+        catch (error) {
+            for (const entry of paths) {
+                result.skipped.push({ ...entry, file, reason: error.message });
+            }
+            continue;
+        }
+        const merge = (0, api_paths_1.mergeApiPaths)(document.current, paths.map((entry) => entry.path), document.validate);
+        for (const entry of paths) {
+            const rejected = merge.rejected.find((item) => item.path === entry.path);
+            if (rejected)
+                result.skipped.push({ ...entry, file, reason: rejected.reason });
+            else if (merge.added.includes(entry.path))
+                result.changed.push({ ...entry, file });
+        }
+        if (merge.added.length === 0 || options.dryRun)
+            continue;
+        document.holder.apiPaths = merge.paths;
+        writeDocument(projectRoot, file, document);
+    }
+    return result;
+}
+/**
+ * Remove exactly these paths from `.podokit/dev.json` and every deployment
+ * profile. A file that would stop validating without them, such as a Compose
+ * profile whose `trustedProxyCidrs` needs a direct path, is left unchanged.
+ */
+function removeApiPaths(projectRoot, paths) {
+    const result = { changed: [], skipped: [] };
+    if (paths.length === 0)
+        return result;
+    for (const file of configFiles(projectRoot)) {
+        const text = readDisk(projectRoot, file);
+        if (text === null)
+            continue;
+        let document;
+        try {
+            document = parseDocument(file, text);
+        }
+        catch {
+            continue;
+        }
+        const removed = paths.filter((entry) => document.current.includes(entry.path));
+        if (removed.length === 0)
+            continue;
+        const next = document.current.filter((path) => !removed.some((entry) => entry.path === path));
+        try {
+            document.validate(next);
+        }
+        catch (error) {
+            for (const entry of removed) {
+                result.skipped.push({ ...entry, file, reason: error.message });
+            }
+            continue;
+        }
+        document.holder.apiPaths = next;
+        writeDocument(projectRoot, file, document);
+        for (const entry of removed)
+            result.changed.push({ ...entry, file });
+    }
+    return result;
+}
+/** Paths a module declares that the project has not merged yet. */
+function pendingApiPaths(module, declared) {
+    const applied = new Set(module.appliedApiPaths ?? []);
+    return declared
+        .filter((path) => !applied.has(path))
+        .map((path) => ({ module: module.name, path }));
+}
+/** Indented report lines, one per changed or skipped path. */
+function describeApiPaths(result, verb) {
+    const sign = verb === "add" ? "+" : "-";
+    return [
+        ...result.changed.map((entry) => `  ${sign} ${entry.path}  ${entry.file}  (${entry.module})`),
+        ...result.skipped.map((entry) => `  ! ${entry.path}  ${entry.file}  (${entry.module}): not ${verb === "add" ? "added" : "removed"}; ${entry.reason}`),
+    ];
+}

package/dist/remove.d.ts

@@ -1,3 +1,4 @@
+import { type ApiPathResult } from "./module-api-paths";
 export interface RemoveOptions {
     projectRoot: string;
     module: string;
@@ -15,6 +16,8 @@ export interface RemoveResult {
     keptShared: string[];
     /** Injection targets whose wiring was removed. */
     unwired: string[];
+    /** Direct API paths removed from `.podokit/dev.json` and deployment profiles. */
+    apiPaths: ApiPathResult;
 }
 /**
  * Remove a previously-added module from a generated project: the inverse of

package/dist/remove.js

@@ -6,6 +6,7 @@ const node_path_1 = require("node:path");
 const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
 const add_1 = require("./add");
 const lockfile_1 = require("./lockfile");
+const module_api_paths_1 = require("./module-api-paths");
 function readModuleManifest(moduleDir, vars) {
     const source = (0, node_fs_1.readFileSync)((0, node_path_1.join)(moduleDir, "module.manifest.json"), "utf8");
     return JSON.parse(vars ? (0, podokit_template_engine_1.renderTokens)(source, vars) : source);
@@ -59,7 +60,7 @@ function removeModule(options) {
         .filter((m) => m.name !== module)
         .map((m) => {
         const dir = (0, add_1.resolveModuleDir)(m.packageName ?? m.name, modulesDir, projectRoot);
-        return dir ? { name: m.name, dir, manifest: readModuleManifest(dir, vars) } : null;
+        return dir ? { name: m.name, dir, manifest: readModuleManifest(dir, vars), record: m } : null;
     })
         .filter((m) => m !== null);
     // Guard: refuse if another installed module requires this one.
@@ -111,7 +112,15 @@ function removeModule(options) {
     pruneAppPackage(projectRoot, targetManifest, others);
     // 4) prune .env.example lines this module added that no other needs.
     pruneEnvExample(projectRoot, targetManifest, others);
-    // 5) drop from the manifest (re-number order) and recompute the lock.
+    // 5) remove the direct API paths this module contributed that no other declares.
+    const sharedApiPaths = new Set(others.flatMap((other) => [
+        ...(other.manifest.apiPaths ?? []),
+        ...(other.record.appliedApiPaths ?? []),
+    ]));
+    const apiPaths = (0, module_api_paths_1.removeApiPaths)(projectRoot, [...new Set([...(installedModule?.appliedApiPaths ?? []), ...(targetManifest.apiPaths ?? [])])]
+        .filter((path) => !sharedApiPaths.has(path))
+        .map((path) => ({ module, path })));
+    // 6) drop from the manifest (re-number order) and recompute the lock.
     manifest.modules = manifest.modules
         .filter((m) => m.name !== module)
         .map((m, i) => ({ ...m, order: i }));
@@ -127,7 +136,7 @@ function removeModule(options) {
         keptEdited.some((path) => (0, lockfile_1.matchGlob)(path, glob)));
     (0, lockfile_1.writeManifest)(projectRoot, manifest);
     (0, lockfile_1.writeFilesLock)(projectRoot, (0, lockfile_1.computeFilesLock)(projectRoot, manifest.ownedGlobs, manifest.managedOverrides));
-    return { module, removed, keptEdited, keptShared, unwired };
+    return { module, removed, keptEdited, keptShared, unwired, apiPaths };
 }
 /** Remove now-empty directories left behind by a deleted file, up to the root. */
 function pruneEmptyDirs(projectRoot, relDir) {

package/dist/templates/fullstack/AGENTS.md

@@ -42,6 +42,14 @@ Merge added module settings from `.env.example` into an existing `.env`.
 
 - **Ports: web = 5001, api = 5002.** The web app reaches the API only through its
   SvelteKit server proxy (`/api/*`), never with a direct browser `fetch`.
+- The proxy (`apps/web/src/lib/server/backend-proxy.ts`) is managed and passes only
+  allowlisted headers. List extra request and response header names in the
+  app-owned `apps/web/src/lib/server/proxy-headers.ts`
+  (`APP_FORWARDED_REQUEST_HEADERS`, `APP_RELAYED_RESPONSE_HEADERS`); never edit the
+  managed lists. Cap a route's request body in the app-owned
+  `apps/web/src/lib/server/body-limits.ts` (`APP_BODY_LIMITS`, 413
+  `PAYLOAD_TOO_LARGE`). `BODY_SIZE_LIMIT` is the ceiling for every web route, so
+  uploads larger than it must use a direct API path (`apiPaths`) instead.
 - Build: `{{rootRun}} build`  ·  Type-check/lint: `{{rootRun}} lint`  ·  Unit tests: `{{rootRun}} test`
 - Per workspace: `{{apiRun}} build` / `{{webRun}} build`.
 - Application migrations (PostgreSQL or SQLite): `{{apiRun}} migration:run`.
@@ -81,7 +89,7 @@ changes need an e2e/unit test.
 This project is managed by the `podo` CLI. Files have an ownership tier recorded
 in `.podokit/files.lock` — respect it:
 
-- **owned** (your code: `apps/web/src/routes/**`, your components/services, `apps/api/src/app.extensions.ts`, and this `AGENTS.md`) — edit freely. Add application-owned services or module descriptors through `app.extensions.ts` instead of changing toolkit registrations.
+- **owned** (your code: `apps/web/src/routes/**`, your components/services, `apps/api/src/app.extensions.ts`, and this `AGENTS.md`) — edit freely. Add application-owned services or module descriptors through `app.extensions.ts` instead of changing toolkit registrations. Set Bun server options (`maxRequestBodySize`, `idleTimeout`) with its `apiServerOptions` export rather than editing `main.ts`; `API_MAX_REQUEST_BODY_SIZE` sets the body limit when the export leaves it out.
 - **assembled** (e.g. `apps/api/src/app.ts`, `auth.ts`) — contain `// podokit:begin:… / …:end` fenced regions that the toolkit recomputes. Edit outside the fences only; **never hand-edit inside the fences**.
 - **managed** (bootstrap/config like `main.ts`) — the toolkit may update these; avoid gratuitous edits.
 
@@ -90,12 +98,19 @@ Useful commands:
 - `podo dev watch|up|ps|logs|exec|down` — run container development through the
   shared loopback gateway. `.podokit/dev.json` owns the local/public hosts and the
   exact API WebSocket allowlist; never use a prefix or wildcard for that allowlist.
+  `podo dev up` rebuilds the images from the current source so a recreated
+  container never runs code older than the files Compose Watch synced.
+  `podo dev down` also stops this project's running `podo dev watch`; do not
+  kill Compose processes by hand.
+  The containers read the untracked `.env.docker`; `podo dev` creates it from the
+  committed `.env.docker.example` with generated secrets when it is missing. Never
+  commit `.env.docker` or put secrets in the example.
 - `podo add <module>` — add a feature (auth, admin-dashboard, redis, bullmq, …). It wires itself into the app; run `podo add` with no argument to list modules.
 - `podo remove <module>` — un-apply a module (inverse of add; refuses if another module needs it, keeps files you edited).
 - `podo provider list` / `podo provider set <capability> <provider> [--apply]` — inspect or switch database, cache, object storage, events, and jobs. Set is dry-run by default and never migrates or deletes provider data. Local providers require one API process.
 - `podo status` / `podo diff` — see your local edits vs. what PodoKit generated.
 - `podo update` — pull in template/module improvements (3-way merges your edits; never touches owned files).
-- `podo deploy` — plan, apply, verify, or roll back an immutable release on Kubernetes or one Docker host. Production API WebSocket paths belong in the deployment profile's exact `exposure.webSocketPaths` allowlist; Compose trusts forwarding headers only from `exposure.trustedProxyCidrs`. Tag `vX.Y.Z` to build and push the images (`.github/workflows/release.yml`; check its runner — GitHub-hosted minutes are free for public repositories only). Use `.agents/skills/podokit-deploy`.
+- `podo deploy` — plan, apply, verify, or roll back an immutable release on Kubernetes or one Docker host. Production API WebSocket paths belong in the deployment profile's exact `exposure.webSocketPaths` allowlist, and API routes that take bodies above the web server's `BODY_SIZE_LIMIT` (file uploads) in `exposure.apiPaths` (and `.podokit/dev.json` `apiPaths` for `podo dev`; `podo add` and `podo deploy init` fill in the paths modules declare), which reach the API without the web proxy, so the API must check their size, session, and `Origin` itself; Compose trusts forwarding headers only from `exposure.trustedProxyCidrs`. Tag `vX.Y.Z` to build and push the images (`.github/workflows/release.yml`; check its runner — GitHub-hosted minutes are free for public repositories only). Use `.agents/skills/podokit-deploy`.
 - `podo deploy sync` — copy local build output into a running Compose deployment and restart it, for iterating without a release. Not a release: no image is published and the next `apply` discards it. Use `.agents/skills/podokit-deploy-fast`.
 
 ## Commit conventions

package/dist/templates/fullstack/README.md

@@ -63,8 +63,17 @@ the same topology, with one route and no project-specific host port.
 
 When the API exposes WebSocket endpoints, add their exact paths to
 `.podokit/dev.json` under `webSocketPaths`. The shared gateway sends only those paths
-directly to the API and leaves every other path on the web app. Add `publicUrl` to the
-same file when an HTTPS tunnel preserves its public `Host` header.
+directly to the API and leaves every other path on the web app. Routes that accept
+bodies larger than the web server's `BODY_SIZE_LIMIT`, such as file uploads, go under
+`apiPaths` as prefixes like `/api/files/uploads/`; the gateway removes `/api` and
+sends them to the API without the web proxy. `podo add` adds the paths a module
+declares, such as `file-upload`'s, to this file and to every deployment profile. Add `publicUrl` to the same file when
+an HTTPS tunnel preserves its public `Host` header.
+
+The containers read `.env.docker`, which Git ignores. `dev` commands create it from
+the committed `.env.docker.example` when it is missing, as in a fresh clone, and fill
+each empty `*_SECRET` value with a random one; `dev env` does only that. Keep shared
+defaults in the example and credentials only in `.env.docker`.
 
 Run lifecycle and container commands from a second terminal:
 
@@ -80,7 +89,9 @@ Run lifecycle and container commands from a second terminal:
 `dev watch` reads `.podokit/manifest.json` and automatically activates `cache`,
 `storage`, and `queue` when installed modules require Redis, Silo, or a worker.
 `dev up` uses the same shared gateway and module profiles without keeping Compose
-Watch attached.
+Watch attached. It rebuilds the images from the current source first, because Compose
+Watch syncs edits into running containers only: a container recreated from an older
+image would lose them. Pass `--no-build` to start from the existing images.
 You can still activate an additional Compose profile explicitly:
 
 ```bash
@@ -88,7 +99,8 @@ You can still activate an additional Compose profile explicitly:
 ```
 
 Explicit profile flags are preserved for other lifecycle commands. `dev down`
-activates all profiles while removing this project's stack and route. If it is
+first stops this project's running `dev watch`, so the next `dev watch` starts
+cleanly, then activates all profiles while removing this project's stack and route. If it is
 the final registered
 project, it also removes the shared gateway and network. Source changes are synced
 through Compose Watch, including Vite HMR on the same portless browser origin.
@@ -183,4 +195,6 @@ If the production API exposes WebSocket endpoints, list their exact paths under
 `exposure.webSocketPaths` in the deployment profile. The Compose driver then keeps a
 single published port, sends only those paths to API, and sends all other traffic to
 web. The external TLS proxy continues to use the same single upstream. Keep
-`trustedProxyCidrs` empty unless that upstream is a known reverse proxy.
+`trustedProxyCidrs` empty unless that upstream is a known reverse proxy. Large-upload
+routes listed under `exposure.apiPaths` reach the API the same way, with `/api`
+removed; the API then enforces their body limit and origin checks itself.

package/dist/templates/fullstack/apps/api/package.json

@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@podosoft/podokit-contracts": "^0.5.0",
-    "@podosoft/podokit-runtime": "^0.3.0",
+    "@podosoft/podokit-runtime": "^0.4.0",
     "@elysia/cors": "^1.4.2",
     "@elysia/openapi": "^1.4.15",
     "dotenv": "^16.4.5",

package/dist/templates/fullstack/apps/api/scripts/build.mjs

@@ -5,6 +5,7 @@ const targets = [
   { entrypoint: "src/database/migrate.ts", outdir: "dist/database" },
   { entrypoint: "src/migrate.ts", outdir: "dist" },
   { entrypoint: "src/main-worker.ts", outdir: "dist" },
+  { entrypoint: "src/bootstrap-admin-runtime.ts", outdir: "dist" },
 ].filter((target) => existsSync(target.entrypoint));
 
 for (const target of targets) {

package/dist/templates/fullstack/apps/api/src/app.extensions.ts

@@ -1,3 +1,4 @@
+import type { ApiServerOptionsSource } from "./config/server-options";
 import type { PodokitModule, ServiceRegistry } from "./core/services";
 
 // This owned extension slot is never overwritten by `podo update`. Register
@@ -8,3 +9,9 @@ import type { PodokitModule, ServiceRegistry } from "./core/services";
 export function configureServices(_services: ServiceRegistry): void {}
 
 export const extensionModules: PodokitModule[] = [];
+
+// Bun server options such as a larger request body limit for uploads, for
+// example { maxRequestBodySize: 1024 ** 3, idleTimeout: 120 }. Values set here
+// win over API_MAX_REQUEST_BODY_SIZE; a function receives the validated
+// environment instead: (env) => ({ maxRequestBodySize: ... }).
+export const apiServerOptions: ApiServerOptionsSource = {};

package/dist/templates/fullstack/apps/api/src/app.spec.ts

@@ -1,5 +1,10 @@
 import { describe, expect, it, mock, type Mock } from "bun:test";
-import { cachedOpenApiDocument, type OpenApiDocumentLoader } from "./app";
+import {
+  cachedOpenApiDocument,
+  setRetryAfter,
+  UNAVAILABLE_RETRY_AFTER_SECONDS,
+  type OpenApiDocumentLoader,
+} from "./app";
 import type { OpenApiContribution } from "./core/services";
 
 function baseSpec(): Response {
@@ -79,3 +84,17 @@ describe("cachedOpenApiDocument", () => {
     expect(base).toHaveBeenCalledTimes(2);
   });
 });
+
+describe("setRetryAfter", () => {
+  it("tells clients when to retry", () => {
+    const headers: Record<string, string | number> = {};
+    setRetryAfter(headers);
+    expect(headers).toEqual({ "retry-after": String(UNAVAILABLE_RETRY_AFTER_SECONDS) });
+  });
+
+  it("keeps a value the failing code already set, in any letter case", () => {
+    const headers: Record<string, string | number> = { "Retry-After": "7" };
+    setRetryAfter(headers);
+    expect(headers).toEqual({ "Retry-After": "7" });
+  });
+});

package/dist/templates/fullstack/apps/api/src/app.ts

@@ -95,6 +95,15 @@ export function cachedOpenApiDocument(source: OpenApiDocumentSource): OpenApiDoc
   };
 }
 
+/** Seconds a client should wait before retrying a request that failed with 503. */
+export const UNAVAILABLE_RETRY_AFTER_SECONDS = 1;
+
+/** Adds `Retry-After` to a 503 unless the code that failed the request already chose one. */
+export function setRetryAfter(headers: Record<string, string | number>): void {
+  if (Object.keys(headers).some((name) => name.toLowerCase() === "retry-after")) return;
+  headers["retry-after"] = String(UNAVAILABLE_RETRY_AFTER_SECONDS);
+}
+
 function errorEnvelope(
   code: string,
   message: string,
@@ -165,10 +174,12 @@ const buildApp = (options: CreateAppOptions = {}) => {
     .onError(({ code, error, path, set }) => {
       if (error instanceof AppException) {
         set.status = error.statusCode;
+        if (error.statusCode === 503) setRetryAfter(set.headers);
         return errorEnvelope(error.code, error.message, error.statusCode, path);
       }
       if (isDatabaseUnavailable(error)) {
         set.status = 503;
+        setRetryAfter(set.headers);
         return errorEnvelope("DATABASE_UNAVAILABLE", "The database is temporarily unavailable", 503, path);
       }
       const statusCode = code === "NOT_FOUND" ? 404 : code === "VALIDATION" ? 400 : 500;

package/dist/templates/fullstack/apps/api/src/config/env.validation.ts

@@ -4,6 +4,8 @@ import { z } from "zod";
 const schema = z.object({
   NODE_ENV: z.string().default("development"),
   PORT: z.coerce.number().default(5002),
+  // Bytes one request body may hold; 128 MiB is Bun's default.
+  API_MAX_REQUEST_BODY_SIZE: z.coerce.number().int().positive().default(128 * 1024 * 1024),
   CORS_ORIGIN: z.string().optional(),
   DATABASE_URL: z.string().optional(),
   POSTGRES_HOST: z.string().default("localhost"),
@@ -14,6 +16,7 @@ const schema = z.object({
   DB_POOL_MAX: z.coerce.number().int().positive().default(20),
   DB_CONNECT_TIMEOUT_MS: z.coerce.number().int().positive().default(10000),
   DB_IDLE_TIMEOUT_MS: z.coerce.number().int().nonnegative().default(30000),
+  DB_QUERY_TIMEOUT_MS: z.coerce.number().int().positive().default(10000),
   DB_AUTH_POOL_MAX: z.coerce.number().int().positive().default(10),
   READINESS_CHECK_TIMEOUT_MS: z.coerce.number().int().positive().default(800),
   READINESS_CACHE_MS: z.coerce.number().int().nonnegative().default(2000),

package/dist/templates/fullstack/apps/api/src/config/redis.connection.spec.ts

@@ -1,5 +1,12 @@
-import { describe, expect, it } from "bun:test";
-import { redisConnectionOptions, redisConnectionUrl } from "./redis.connection";
+import { describe, expect, it, mock } from "bun:test";
+import {
+  DEFAULT_REDIS_COMMAND_TIMEOUT_MS,
+  RedisCommandTimeoutError,
+  redisCommandTimeoutMs,
+  redisConnectionOptions,
+  redisConnectionUrl,
+  withReplyTimeout,
+} from "./redis.connection";
 
 describe("redisConnectionOptions", () => {
   it("prefers an authenticated URL over individual settings", () => {
@@ -69,3 +76,42 @@ describe("redisConnectionUrl", () => {
     })).toBe("rediss://podokit:p%40ss@cache.example.com:6381/4");
   });
 });
+
+describe("redisCommandTimeoutMs", () => {
+  it("defaults to one second and reads REDIS_COMMAND_TIMEOUT_MS", () => {
+    expect(redisCommandTimeoutMs({})).toBe(DEFAULT_REDIS_COMMAND_TIMEOUT_MS);
+    expect(redisCommandTimeoutMs({ REDIS_COMMAND_TIMEOUT_MS: "" })).toBe(1_000);
+    expect(redisCommandTimeoutMs({ REDIS_COMMAND_TIMEOUT_MS: "250" })).toBe(250);
+  });
+
+  it("rejects a value that is not a positive integer", () => {
+    for (const value of ["0", "-1", "1.5", "soon"]) {
+      expect(() => redisCommandTimeoutMs({ REDIS_COMMAND_TIMEOUT_MS: value }))
+        .toThrow("REDIS_COMMAND_TIMEOUT_MS must be a positive integer");
+    }
+  });
+});
+
+describe("withReplyTimeout", () => {
+  it("passes a reply or its error through and leaves the connection alone", async () => {
+    const onTimeout = mock(() => undefined);
+    const failure = new Error("WRONGTYPE");
+
+    await expect(withReplyTimeout(Promise.resolve("value"), 50, onTimeout)).resolves.toBe("value");
+    await expect(withReplyTimeout(Promise.reject(failure), 50, onTimeout)).rejects.toBe(failure);
+    await Bun.sleep(80);
+    expect(onTimeout).not.toHaveBeenCalled();
+  });
+
+  it("fails a missing reply after the timeout and closes the connection once", async () => {
+    const onTimeout = mock(() => undefined);
+    const started = Date.now();
+
+    const error = await withReplyTimeout(new Promise(() => undefined), 50, onTimeout)
+      .then(() => undefined, (reason: unknown) => reason);
+
+    expect(error).toBeInstanceOf(RedisCommandTimeoutError);
+    expect(Date.now() - started).toBeLessThan(1_000);
+    expect(onTimeout).toHaveBeenCalledTimes(1);
+  });
+});