@podosoft/podokit 1.3.0 → 1.4.1

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

@@ -27,7 +27,7 @@ Provider selection does not migrate or delete existing data.
 ```bash
 {{packageManager}} install
 cp .env.example .env
-{{apiRun}} migration:run
+{{apiRun}} migrate:all
 {{rootRun}} dev        # api on http://localhost:5002, web on http://localhost:5001
 ```
 
@@ -42,10 +42,25 @@ 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.
+- When the root layout or a server hook fails, such as with 503 while the API is
+  down, SvelteKit serves the app-owned `apps/web/src/error.html`. It is plain HTML
+  with inline styles: no components, app CSS, scripts, or assets, and only the
+  `%sveltekit.status%` and `%sveltekit.error.message%` placeholders.
 - 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`.
-- When `auth` is installed, run `{{apiRun}} migrate:all` for Better Auth and application tables.
+- Set up the database and apply later migrations, including after adding a module, with
+  `{{apiRun}} migrate:all` (PostgreSQL or SQLite). With `auth` installed it applies the
+  Better Auth schema before the application migrations. `{{apiRun}} migration:run` runs
+  only the application migrations and never creates Better Auth tables;
+  `{{apiRun}} migration:revert` reverts the latest application migration.
 - e2e (Playwright, ships in `tests/`): `{{rootRun}} test:e2e`.
 - Playwright officially runs on Node, so `bunx playwright` respects its Node
   shebang. Node LTS is a test-tool dependency only; API, web, worker, migrations,
@@ -81,7 +96,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 +105,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:
 
@@ -73,14 +82,16 @@ Run lifecycle and container commands from a second terminal:
 {{packageExecutor}} @podosoft/podokit dev up -d # detached stack without source watching
 {{packageExecutor}} @podosoft/podokit dev ps
 {{packageExecutor}} @podosoft/podokit dev logs
-{{packageExecutor}} @podosoft/podokit dev exec api {{apiRun}} migration:run
+{{packageExecutor}} @podosoft/podokit dev exec api {{apiRun}} migrate:all
 {{packageExecutor}} @podosoft/podokit dev down
 ```
 
 `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.
@@ -101,7 +113,7 @@ web and API processes on the host. Prepare the project first:
 ```bash
 {{packageManager}} install
 cp .env.example .env
-{{apiRun}} migration:run
+{{apiRun}} migrate:all
 ```
 
 For PostgreSQL, start `docker compose -f infra/docker/docker-compose.yml up -d`
@@ -128,12 +140,15 @@ runs PostgreSQL migrations; SQLite uses the local migration runner. Add a
 numbered migration under `apps/api/src/migrations`, then run it:
 
 ```bash
-{{apiRun}} migration:run
+{{apiRun}} migrate:all        # set up the database and apply new migrations
+{{apiRun}} migration:revert   # roll back the last application migration
 ```
 
-When `auth` is installed, use `{{apiRun}} migrate:all` to create or update both
-Better Auth and application tables. Set the module's required environment
-values before migrating.
+`migrate:all` is the one command for setup, after adding a module, and in
+production. When `auth` is installed, it applies the Better Auth schema before
+the application migrations, so set the module's required environment values
+first. `{{apiRun}} migration:run` runs only the application migrations and
+never creates Better Auth tables.
 
 Want a worked example? Generate the `todo` template instead:
 `{{packageExecutor}} @podosoft/podokit create my-app --template todo`.
@@ -183,4 +198,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

@@ -9,7 +9,7 @@
     "lint": "bunx --bun tsc -p tsconfig.json --noEmit",
     "test": "bun test src",
     "contract": "bun scripts/verify-api-contract.ts",
-    "migrate:all": "bun dist/database/migrate.js",
+    "migrate:all": "bun scripts/run-migrations.mjs",
     "typeorm": "bunx typeorm-ts-node-commonjs -d src/database/data-source.ts",
     "migration:run": "bun src/database/migrate.ts",
     "migration:revert": "bun src/database/migrate.ts --revert",
@@ -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/run-migrations.mjs

@@ -0,0 +1,25 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+// Production images ship only the compiled output.
+function entry(name) {
+  const compiled = new URL(`../dist/${name}.js`, import.meta.url);
+  if (process.env.NODE_ENV === "production" && existsSync(compiled)) return compiled;
+  const source = new URL(`../src/${name}.ts`, import.meta.url);
+  return existsSync(source) ? source : null;
+}
+
+// The auth module adds src/migrate.ts, which applies the Better Auth schema
+// before it runs the application migrations.
+const target = entry("migrate") ?? entry("database/migrate");
+if (!target) {
+  process.stderr.write("Run database migrations failed: no migration entry in src or dist\n");
+  process.exit(1);
+}
+const subprocess = Bun.spawn([process.execPath, fileURLToPath(target)], {
+  stdin: "inherit",
+  stdout: "inherit",
+  stderr: "inherit",
+});
+
+process.exitCode = await subprocess.exited;

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);
+  });
+});

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

@@ -68,6 +68,51 @@ export function redisConnectionOptions(
   return { ...base, ...overrides };
 }
 
+export const DEFAULT_REDIS_COMMAND_TIMEOUT_MS = 1_000;
+
+/** How long the API waits for Redis to answer one command (`REDIS_COMMAND_TIMEOUT_MS`). */
+export function redisCommandTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
+  const value = env.REDIS_COMMAND_TIMEOUT_MS;
+  if (value === undefined || value === "") return DEFAULT_REDIS_COMMAND_TIMEOUT_MS;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new Error("REDIS_COMMAND_TIMEOUT_MS must be a positive integer");
+  }
+  return parsed;
+}
+
+export class RedisCommandTimeoutError extends Error {
+  constructor(timeoutMs: number) {
+    super(`Redis did not answer within ${timeoutMs} ms`);
+    this.name = "RedisCommandTimeoutError";
+  }
+}
+
+/**
+ * Rejects with `RedisCommandTimeoutError` when `reply` has not settled within
+ * `timeoutMs`, after calling `onTimeout`. Redis answers a connection's commands
+ * in order, so a missing reply holds back every later one: `onTimeout` closes
+ * the connection, which fails those too and lets its supervisor reconnect.
+ */
+export async function withReplyTimeout<T>(
+  reply: Promise<T>,
+  timeoutMs: number,
+  onTimeout: () => void,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(new RedisCommandTimeoutError(timeoutMs));
+      onTimeout();
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([reply, deadline]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 /** Resolve the same Redis configuration as BullMQ into a URL for Bun.RedisClient. */
 export function redisConnectionUrl(env: NodeJS.ProcessEnv = process.env): string {
   if (env.REDIS_URL) {