@podosoft/podokit 1.4.1 → 1.5.0

package/dist/deploy-compose-profile.js

@@ -357,6 +357,8 @@ function buildDefaultComposeProfile(projectName, options) {
             CORS_ORIGIN: `https://${host}`,
             ADDRESS_HEADER: "x-forwarded-for",
             XFF_DEPTH: "1",
+            TRUSTED_PROXY_HOPS: "1",
+            TRUSTED_PROXY_HEADER: "x-forwarded-for",
         },
         verification: {
             baseUrl: `https://${host}`,
@@ -418,8 +420,6 @@ function initializeComposeProfile(projectRoot, name, options) {
                 RATE_LIMIT_AUTH_TTL: "60",
                 RATE_LIMIT_AUTH_MAX: "20",
                 RATE_LIMIT_RUNTIME_MAX: "1000",
-                RATE_LIMIT_TRUSTED_PROXY_HOPS: "1",
-                RATE_LIMIT_PROXY_HEADER: "x-forwarded-for",
                 RATE_LIMIT_STORAGE_TIMEOUT_MS: "1000",
                 RATE_LIMIT_UNAVAILABLE_RETRY_AFTER: "1",
             }

package/dist/deploy-compose-render.js

@@ -37,6 +37,7 @@ function derivedRuntimeConfig(profile) {
     const result = {
         PORT: String(CONTAINER_PORT),
         BACKEND_INTERNAL_URL: `http://${serviceName(profile, "api")}:${CONTAINER_PORT}`,
+        ...(0, deploy_schema_1.idleTimeoutConfig)(profile.runtimeConfig),
         ...profile.runtimeConfig,
     };
     if (profile.dependencies.postgres.mode === "managed") {
@@ -311,7 +312,8 @@ function renderComposeDocument(profile, release, images, stateDigest, workerComm
         healthcheckPath: "/health/ready",
     }));
     services.push(applicationService(profile, "web", images.web, release, stateDigest, {
-        healthcheckPath: "/",
+        // The web server's own route: an API outage must not mark it unhealthy.
+        healthcheckPath: "/healthz",
         publish: !hasGateway,
     }));
     if (hasGateway) {

package/dist/deploy-profile.js

@@ -397,6 +397,8 @@ function initializeDeploymentProfile(projectRoot, name, options) {
             CORS_ORIGIN: `https://${host}`,
             ADDRESS_HEADER: "x-forwarded-for",
             XFF_DEPTH: "1",
+            TRUSTED_PROXY_HOPS: "1",
+            TRUSTED_PROXY_HEADER: "x-forwarded-for",
             ...(usesAuth ? { BETTER_AUTH_URL: `https://${host}` } : {}),
             ...(modules.has("rate-limit")
                 ? {
@@ -406,8 +408,6 @@ function initializeDeploymentProfile(projectRoot, name, options) {
                     RATE_LIMIT_AUTH_TTL: "60",
                     RATE_LIMIT_AUTH_MAX: "20",
                     RATE_LIMIT_RUNTIME_MAX: "1000",
-                    RATE_LIMIT_TRUSTED_PROXY_HOPS: "1",
-                    RATE_LIMIT_PROXY_HEADER: "x-forwarded-for",
                     RATE_LIMIT_STORAGE_TIMEOUT_MS: "1000",
                     RATE_LIMIT_UNAVAILABLE_RETRY_AFTER: "1",
                 }

package/dist/deploy-render.js

@@ -6,6 +6,7 @@ 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 deploy_schema_1 = require("./deploy-schema");
 const lockfile_1 = require("./lockfile");
 const toolchain_1 = require("./toolchain");
 function quote(value) {
@@ -356,6 +357,7 @@ function derivedRuntimeConfig(profile) {
         BACKEND_INTERNAL_URL: `http://${profile.target.release}-api:3000`,
         PROTOCOL_HEADER: "x-forwarded-proto",
         HOST_HEADER: "x-forwarded-host",
+        ...(0, deploy_schema_1.idleTimeoutConfig)(profile.runtimeConfig),
         ...profile.runtimeConfig,
     };
     if (profile.dependencies.postgres.mode === "inCluster") {
@@ -386,8 +388,10 @@ metadata:
 ${entries.length ? `data:\n${entries.map(([key, value]) => `  ${key}: ${quote(value)}`).join("\n")}` : "data: {}"}
 `;
 }
-// Above the API's 800 ms per-check readiness bound; the Kubernetes default is 1 s.
-const API_PROBE_TIMEOUT_SECONDS = 2;
+// Every rendered API and web probe allows 2 s instead of the Kubernetes default
+// of 1 s: above the API's 800 ms per-check readiness bound, and enough for a busy
+// web server.
+const PROBE_TIMEOUT_SECONDS = 2;
 function deployment(profile, kind, workload, image, rolloutStateDigest, runtimeConfigDigest) {
     const name = `${profile.target.release}-${kind}`;
     const workloadSecret = kind === "api" ? profile.secrets.api : profile.secrets.web;
@@ -399,25 +403,29 @@ function deployment(profile, kind, workload, image, rolloutStateDigest, runtimeC
         ? `          readinessProbe:
             httpGet: { path: /health/ready, port: 3000 }
             periodSeconds: 5
-            timeoutSeconds: ${API_PROBE_TIMEOUT_SECONDS}
+            timeoutSeconds: ${PROBE_TIMEOUT_SECONDS}
           livenessProbe:
             httpGet: { path: /health, port: 3000 }
             initialDelaySeconds: 20
             periodSeconds: 10
-            timeoutSeconds: ${API_PROBE_TIMEOUT_SECONDS}
+            timeoutSeconds: ${PROBE_TIMEOUT_SECONDS}
           startupProbe:
             httpGet: { path: /health, port: 3000 }
             failureThreshold: 30
             periodSeconds: 2
-            timeoutSeconds: ${API_PROBE_TIMEOUT_SECONDS}
+            timeoutSeconds: ${PROBE_TIMEOUT_SECONDS}
 `
-        : `          readinessProbe:
-            httpGet: { path: /, port: 3000 }
+        : // The web server's own route: an API outage must not take the web pods
+            // out of service or restart them.
+            `          readinessProbe:
+            httpGet: { path: /healthz, port: 3000 }
             periodSeconds: 5
+            timeoutSeconds: ${PROBE_TIMEOUT_SECONDS}
           livenessProbe:
-            httpGet: { path: /, port: 3000 }
+            httpGet: { path: /healthz, port: 3000 }
             initialDelaySeconds: 20
             periodSeconds: 10
+            timeoutSeconds: ${PROBE_TIMEOUT_SECONDS}
 `;
     return `apiVersion: apps/v1
 kind: Deployment

package/dist/deploy-schema.d.ts

@@ -50,6 +50,13 @@ export declare function validateImage(value: string, field: string): void;
 export declare function validateImageRepository(value: string, field: string): void;
 export declare function parseReleaseProfile(release: Record<string, unknown>): ReleaseProfile;
 export declare function parseRuntimeConfig(runtimeConfig: Record<string, unknown>): Record<string, string>;
+/**
+ * The idle timeouts of the web server (CONNECTION_IDLE_TIMEOUT) and the API
+ * (API_IDLE_TIMEOUT), both run by Bun. Each is the profile's own value, or else
+ * the fewest seconds that keep a silent connection open past the /api proxy's
+ * BACKEND_PROXY_TIMEOUT_MS deadline: 35 for the default 30000 ms.
+ */
+export declare function idleTimeoutConfig(runtimeConfig: Record<string, string>): Record<string, string>;
 export declare function validateHttpsOrigin(value: string): void;
 export declare function parseVerification(verification: Record<string, unknown>): VerificationProfile;
 export declare function profileDirectory(projectRoot: string): string;

package/dist/deploy-schema.js

@@ -17,6 +17,7 @@ exports.validateImage = validateImage;
 exports.validateImageRepository = validateImageRepository;
 exports.parseReleaseProfile = parseReleaseProfile;
 exports.parseRuntimeConfig = parseRuntimeConfig;
+exports.idleTimeoutConfig = idleTimeoutConfig;
 exports.validateHttpsOrigin = validateHttpsOrigin;
 exports.parseVerification = parseVerification;
 exports.profileDirectory = profileDirectory;
@@ -35,6 +36,11 @@ exports.MANAGED_RUNTIME_CONFIG_KEYS = [
     "PROTOCOL_HEADER",
     "HOST_HEADER",
 ];
+/** Keys the generated API no longer reads; it refuses to start while they are set. */
+const RENAMED_RUNTIME_CONFIG_KEYS = {
+    RATE_LIMIT_TRUSTED_PROXY_HOPS: "TRUSTED_PROXY_HOPS",
+    RATE_LIMIT_PROXY_HEADER: "TRUSTED_PROXY_HEADER",
+};
 function containsUrlCredentials(value) {
     if (!value.includes("://"))
         return false;
@@ -183,6 +189,10 @@ function parseRuntimeConfig(runtimeConfig) {
         if (exports.MANAGED_RUNTIME_CONFIG_KEYS.includes(key)) {
             throw new Error(`Deployment runtimeConfig key "${key}" is managed by PodoKit.`);
         }
+        const renamed = RENAMED_RUNTIME_CONFIG_KEYS[key];
+        if (renamed) {
+            throw new Error(`Deployment runtimeConfig key "${key}" was renamed to "${renamed}".`);
+        }
         if (typeof entry !== "string") {
             throw new Error(`Deployment runtimeConfig value "${key}" must be a string.`);
         }
@@ -193,6 +203,36 @@ function parseRuntimeConfig(runtimeConfig) {
     }
     return parsed;
 }
+/** Bun closes silent connections on a 4-second tick, up to 4 seconds before their idle timeout. */
+const IDLE_TICK_SECONDS = 4;
+const MAX_IDLE_TIMEOUT_SECONDS = 255;
+const DEFAULT_BACKEND_PROXY_TIMEOUT_MS = 30_000;
+/**
+ * The idle timeouts of the web server (CONNECTION_IDLE_TIMEOUT) and the API
+ * (API_IDLE_TIMEOUT), both run by Bun. Each is the profile's own value, or else
+ * the fewest seconds that keep a silent connection open past the /api proxy's
+ * BACKEND_PROXY_TIMEOUT_MS deadline: 35 for the default 30000 ms.
+ */
+function idleTimeoutConfig(runtimeConfig) {
+    const proxyTimeout = runtimeConfig.BACKEND_PROXY_TIMEOUT_MS?.trim();
+    const proxyMs = proxyTimeout && /^\d+$/.test(proxyTimeout) ? Number(proxyTimeout) : DEFAULT_BACKEND_PROXY_TIMEOUT_MS;
+    const derived = Math.floor(proxyMs / 1000) + IDLE_TICK_SECONDS + 1;
+    const config = {};
+    for (const name of ["CONNECTION_IDLE_TIMEOUT", "API_IDLE_TIMEOUT"]) {
+        const configured = runtimeConfig[name];
+        if (configured !== undefined) {
+            config[name] = configured;
+        }
+        else if (derived > MAX_IDLE_TIMEOUT_SECONDS) {
+            throw new Error(`Deployment runtimeConfig BACKEND_PROXY_TIMEOUT_MS ${proxyMs} outlasts the longest idle timeout ` +
+                `(${MAX_IDLE_TIMEOUT_SECONDS} seconds); set ${name} to "0" to turn it off.`);
+        }
+        else {
+            config[name] = String(derived);
+        }
+    }
+    return config;
+}
 function validateHttpsOrigin(value) {
     let parsed;
     try {

package/dist/lockfile.d.ts

@@ -82,7 +82,14 @@ export declare function podokitVersion(): string;
 export declare function matchGlob(path: string, glob: string): boolean;
 /** Classify a file's ownership tier. See ADR-0010 priority order. */
 export declare function classifyTier(relPath: string, content: string | Buffer, ownedGlobs: string[], managedOverrides?: string[]): Tier;
-/** List project files as POSIX-relative paths, skipping generated/vendored dirs. */
+/**
+ * Whether a path is a local environment file such as `.env`, `.env.docker` or
+ * `apps/api/.env.local`. Git ignores these and they hold secrets, so the lock
+ * never records them; the committed `*.example` files are project files.
+ */
+export declare function isLocalEnvFile(relPath: string): boolean;
+/** List project files as POSIX-relative paths, skipping generated/vendored dirs
+ *  and local environment files. */
 export declare function walkFiles(projectRoot: string, prefix?: string): string[];
 /** Recompute the files.lock by hashing and classifying every project file. */
 export declare function computeFilesLock(projectRoot: string, ownedGlobs: string[], managedOverrides?: string[]): FilesLock;

package/dist/lockfile.js

@@ -11,6 +11,7 @@ exports.writeFilesLock = writeFilesLock;
 exports.podokitVersion = podokitVersion;
 exports.matchGlob = matchGlob;
 exports.classifyTier = classifyTier;
+exports.isLocalEnvFile = isLocalEnvFile;
 exports.walkFiles = walkFiles;
 exports.computeFilesLock = computeFilesLock;
 exports.readFilesLock = readFilesLock;
@@ -54,9 +55,11 @@ 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.
+    // Owned additions to the managed /api proxy's header lists, body limits, and
+    // response deadlines.
     "apps/web/src/lib/server/proxy-headers.ts",
     "apps/web/src/lib/server/body-limits.ts",
+    "apps/web/src/lib/server/proxy-timeouts.ts",
     // Owned fallback page SvelteKit serves when the root layout or a hook fails.
     "apps/web/src/error.html",
     // AI agent guidance — yours to customize; update never touches it.
@@ -168,7 +171,17 @@ function classifyTier(relPath, content, ownedGlobs, managedOverrides = []) {
         return "assembled";
     return "managed";
 }
-/** List project files as POSIX-relative paths, skipping generated/vendored dirs. */
+/**
+ * Whether a path is a local environment file such as `.env`, `.env.docker` or
+ * `apps/api/.env.local`. Git ignores these and they hold secrets, so the lock
+ * never records them; the committed `*.example` files are project files.
+ */
+function isLocalEnvFile(relPath) {
+    const name = relPath.slice(relPath.lastIndexOf("/") + 1);
+    return (name === ".env" || name.startsWith(".env.")) && !name.endsWith(".example");
+}
+/** List project files as POSIX-relative paths, skipping generated/vendored dirs
+ *  and local environment files. */
 function walkFiles(projectRoot, prefix = "") {
     const out = [];
     for (const entry of (0, node_fs_1.readdirSync)((0, node_path_1.join)(projectRoot, prefix))) {
@@ -178,7 +191,7 @@ function walkFiles(projectRoot, prefix = "") {
         if ((0, node_fs_1.statSync)((0, node_path_1.join)(projectRoot, rel)).isDirectory()) {
             out.push(...walkFiles(projectRoot, rel));
         }
-        else {
+        else if (!isLocalEnvFile(rel)) {
             out.push(rel);
         }
     }
@@ -198,7 +211,13 @@ function computeFilesLock(projectRoot, ownedGlobs, managedOverrides = []) {
 }
 function readFilesLock(projectRoot) {
     const file = filesLockPath(projectRoot);
-    return (0, node_fs_1.existsSync)(file) ? JSON.parse((0, node_fs_1.readFileSync)(file, "utf8")) : null;
+    if (!(0, node_fs_1.existsSync)(file))
+        return null;
+    const lock = JSON.parse((0, node_fs_1.readFileSync)(file, "utf8"));
+    // Earlier versions recorded local env files. Leaving them out here keeps
+    // update from treating them as PodoKit files, and the next write drops them.
+    const files = Object.entries(lock.files).filter(([path]) => !isLocalEnvFile(path));
+    return { ...lock, files: Object.fromEntries(files) };
 }
 /**
  * Compare the current disk against the lock: report managed/assembled files the

package/dist/provider.d.ts

@@ -18,6 +18,7 @@ export interface ApplyProviderChangeOptions {
     modulesDir?: string;
     podokitVersion?: string;
 }
+/** The managed provider source; it must render byte for byte like the template's copy. */
 export declare function providerSource(providers: ProviderSelections): string;
 export declare function listProviders(projectRoot: string): ProviderListItem[];
 export declare function planProviderChange(projectRoot: string, capabilityInput: string, provider: string, modulesDir?: string): ProviderChangePlan;

package/dist/provider.js

@@ -27,15 +27,18 @@ function assertProvider(capability, provider) {
     }
     return capability;
 }
+/** The managed provider source; it must render byte for byte like the template's copy. */
 function providerSource(providers) {
     return `import type { ProviderSelections } from "@podosoft/podokit-runtime";\n\n` +
-        `export const PROVIDERS = {\n` +
+        `// Typed with every provider name, not the selected ones: the module of a\n` +
+        `// provider that stays installed after a switch compares against its own name.\n` +
+        `export const PROVIDERS: Readonly<ProviderSelections> = {\n` +
         `  database: "${providers.database}",\n` +
         `  cache: "${providers.cache}",\n` +
         `  "object-storage": "${providers["object-storage"]}",\n` +
         `  events: "${providers.events}",\n` +
         `  jobs: "${providers.jobs}",\n` +
-        `} as const satisfies ProviderSelections;\n`;
+        `};\n`;
 }
 function listProviders(projectRoot) {
     const manifest = requireManifest(projectRoot);

package/dist/templates/fullstack/AGENTS.md

@@ -49,7 +49,32 @@ Merge added module settings from `.env.example` into an existing `.env`.
   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.
+  uploads larger than it must use a direct API path (`apiPaths`) instead. Give a
+  route a longer, shorter, or no response deadline in the app-owned
+  `apps/web/src/lib/server/proxy-timeouts.ts` (`APP_PROXY_TIMEOUTS`, `null` for
+  none); never edit the managed deadline. Both lists take path prefixes with
+  `:name` parameters, such as `/api/hosts/:hostId/file-transfers`, and the most
+  specific prefix wins.
+- Server-side API calls (`serverApiClient`) give up after `BACKEND_TIMEOUT_MS`
+  (2000), and the proxy answers 504 `BACKEND_TIMEOUT` when the API sends no
+  response headers within `BACKEND_PROXY_TIMEOUT_MS` (30000). Once the API's
+  `GET /health` stops answering too, calls throw `BackendUnavailableError` and the
+  proxy answers 503 `BACKEND_UNAVAILABLE` at once until it answers again. Handle
+  any non-`ApiError` failure in a load function as a temporary outage. The API
+  (`API_IDLE_TIMEOUT`) and the built web server (`CONNECTION_IDLE_TIMEOUT`) close
+  a connection that sends nothing for that many seconds (35 each): raise both
+  with any longer `BACKEND_PROXY_TIMEOUT_MS` or `APP_PROXY_TIMEOUTS` entry, more
+  than 4 above it, or set `0` when a route has no deadline. The proxy refuses to
+  load when `CONNECTION_IDLE_TIMEOUT` cannot cover a deadline.
+- Read a caller's address in the API with `clientAddressOf(request.headers)` from
+  `apps/api/src/core/client-address.ts`, never from `X-Forwarded-For` directly. The
+  API resolves it once per request from `TRUSTED_PROXY_HOPS` (1: the web proxy) and
+  `TRUSTED_PROXY_HEADER`; Better Auth sessions, audit entries, and rate limits use
+  the same address.
+- `GET /healthz` (`apps/web/src/routes/healthz/+server.ts`) is the web server's own
+  health route for the Kubernetes probes, the Compose healthcheck, and the image
+  `HEALTHCHECK`. Keep it free of API calls, so an API outage does not take the web
+  out of service.
 - 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
@@ -96,7 +121,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. 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.
+- **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` and `API_IDLE_TIMEOUT` apply when the export leaves them 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.
 

package/dist/templates/fullstack/README.md

@@ -131,7 +131,7 @@ Run each service in a separate terminal from the project root:
 ```
 
 - API: http://localhost:5002 — health at `/health`, docs at `/api-docs`
-- Web: http://localhost:5001
+- Web: http://localhost:5001 — its own health at `/healthz`, which never calls the API
 
 ## Database & migrations
 

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

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

package/dist/templates/fullstack/apps/api/scripts/run-migrations.mjs

@@ -16,7 +16,11 @@ if (!target) {
   process.stderr.write("Run database migrations failed: no migration entry in src or dist\n");
   process.exit(1);
 }
+// Run in the API directory wherever this was started from: Bun reads decorator
+// settings from the tsconfig.json of the working directory, and the data source
+// finds .env and the migrations relative to it.
 const subprocess = Bun.spawn([process.execPath, fileURLToPath(target)], {
+  cwd: fileURLToPath(new URL("..", import.meta.url)),
   stdin: "inherit",
   stdout: "inherit",
   stderr: "inherit",

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

@@ -12,6 +12,11 @@ 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: ... }).
+// win over API_MAX_REQUEST_BODY_SIZE and API_IDLE_TIMEOUT; a function receives
+// the validated environment instead: (env) => ({ maxRequestBodySize: ... }). A
+// longer idleTimeout also needs a longer proxy deadline on the web server, which
+// stops waiting for response headers after 30 seconds by default:
+// BACKEND_PROXY_TIMEOUT_MS, or one route's entry in APP_PROXY_TIMEOUTS
+// (apps/web/src/lib/server/proxy-timeouts.ts), and the web server's
+// CONNECTION_IDLE_TIMEOUT (35 seconds).
 export const apiServerOptions: ApiServerOptionsSource = {};

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

@@ -4,6 +4,7 @@ import { AppException, type ErrorEnvelope } from "@podosoft/podokit-contracts";
 import { Elysia } from "elysia";
 import { configureServices, extensionModules } from "./app.extensions";
 import { validateEnv, type AppEnv } from "./config/env.validation";
+import { stampClientAddress } from "./core/client-address";
 import {
   appContext,
   createCoreServices,
@@ -137,6 +138,7 @@ const buildApp = (options: CreateAppOptions = {}) => {
   services.freeze();
   const context = appContext(env, services);
   const corsOrigin = env.CORS_ORIGIN?.split(",").map((origin) => origin.trim());
+  const clientAddressConfig = { trustedProxyHops: env.TRUSTED_PROXY_HOPS, header: env.TRUSTED_PROXY_HEADER };
 
   const app = new Elysia({ name: "podokit" })
     .use(cors({ origin: corsOrigin ?? true, credentials: true }))
@@ -157,11 +159,12 @@ const buildApp = (options: CreateAppOptions = {}) => {
     .onRequest(async ({ request, server, set }) => {
       const requestId = request.headers.get("x-request-id") ?? crypto.randomUUID();
       set.headers["x-request-id"] = requestId;
+      const remoteAddress = server?.requestIP(request)?.address;
+      const clientAddress = stampClientAddress(request, remoteAddress, clientAddressConfig);
       await context.requestGuards.run({
         request,
-        ...(server?.requestIP(request)?.address
-          ? { remoteAddress: server.requestIP(request)?.address }
-          : {}),
+        ...(remoteAddress ? { remoteAddress } : {}),
+        ...(clientAddress ? { clientAddress } : {}),
         setHeader: (name, value) => { set.headers[name] = value; },
       });
     })

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

@@ -6,6 +6,22 @@ const schema = z.object({
   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),
+  // Seconds a connection may stay silent, 0 (never closed) to 255. Bun closes idle
+  // connections on a 4-second sweep, so 35 outlasts the web proxy's 30-second
+  // deadline. An empty value means unset rather than 0.
+  API_IDLE_TIMEOUT: z.preprocess(
+    (value) => (value === "" ? undefined : value),
+    z.coerce.number().int().min(0).max(255).default(35),
+  ),
+  // Reverse proxies in front of the API whose forwarded header names the client;
+  // the generated web proxy is one. 0 uses the socket peer.
+  TRUSTED_PROXY_HOPS: z.coerce.number().int().nonnegative().default(0),
+  TRUSTED_PROXY_HEADER: z
+    .string()
+    .trim()
+    .toLowerCase()
+    .regex(/^[a-z0-9!#$%&'*+.^_`|~-]+$/, "must be an HTTP header name")
+    .default("x-forwarded-for"),
   CORS_ORIGIN: z.string().optional(),
   DATABASE_URL: z.string().optional(),
   POSTGRES_HOST: z.string().default("localhost"),
@@ -24,7 +40,19 @@ const schema = z.object({
 
 export type AppEnv = z.infer<typeof schema>;
 
+// Renamed settings fail loudly: falling back to the default would count and
+// record every browser request under the web server's address.
+const RENAMED: Record<string, string> = {
+  RATE_LIMIT_TRUSTED_PROXY_HOPS: "TRUSTED_PROXY_HOPS",
+  RATE_LIMIT_PROXY_HEADER: "TRUSTED_PROXY_HEADER",
+};
+
 export function validateEnv(config: Record<string, unknown>): AppEnv {
+  for (const [previous, current] of Object.entries(RENAMED)) {
+    if (config[previous] !== undefined) {
+      throw new Error(`Invalid environment: ${previous} was renamed to ${current}.`);
+    }
+  }
   const parsed = schema.safeParse(config);
   if (!parsed.success) {
     throw new Error(`Invalid environment:\n${parsed.error.toString()}`);

package/dist/templates/fullstack/apps/api/src/config/providers.ts

@@ -1,9 +1,11 @@
 import type { ProviderSelections } from "@podosoft/podokit-runtime";
 
-export const PROVIDERS = {
+// Typed with every provider name, not the selected ones: the module of a
+// provider that stays installed after a switch compares against its own name.
+export const PROVIDERS: Readonly<ProviderSelections> = {
   database: "{{databaseProvider}}",
   cache: "{{cacheProvider}}",
   "object-storage": "{{objectStorageProvider}}",
   events: "{{eventsProvider}}",
   jobs: "{{jobsProvider}}",
-} as const satisfies ProviderSelections;
+};

package/dist/templates/fullstack/apps/api/src/config/server-options.spec.ts

@@ -4,26 +4,37 @@ import { validateEnv } from "./env.validation";
 import { apiServerOptions, DEFAULT_MAX_REQUEST_BODY_SIZE } from "./server-options";
 
 describe("apiServerOptions", () => {
-  it("defaults to Bun's request body limit and leaves the idle timeout to Elysia", () => {
+  it("defaults to Bun's request body limit and an idle timeout that outlasts the web proxy", () => {
     const env = validateEnv({});
     expect(env.API_MAX_REQUEST_BODY_SIZE).toBe(DEFAULT_MAX_REQUEST_BODY_SIZE);
-    expect(apiServerOptions(env, {})).toEqual({ maxRequestBodySize: DEFAULT_MAX_REQUEST_BODY_SIZE });
+    expect(apiServerOptions(env, {})).toEqual({ maxRequestBodySize: DEFAULT_MAX_REQUEST_BODY_SIZE, idleTimeout: 35 });
+  });
+
+  it("reads API_IDLE_TIMEOUT from 0 to 255 seconds and treats an empty value as unset", () => {
+    expect(validateEnv({ API_IDLE_TIMEOUT: "125" }).API_IDLE_TIMEOUT).toBe(125);
+    expect(validateEnv({ API_IDLE_TIMEOUT: "0" }).API_IDLE_TIMEOUT).toBe(0);
+    expect(validateEnv({ API_IDLE_TIMEOUT: "255" }).API_IDLE_TIMEOUT).toBe(255);
+    expect(validateEnv({ API_IDLE_TIMEOUT: "" }).API_IDLE_TIMEOUT).toBe(35);
+    for (const value of ["256", "-1", "1.5", "soon"]) {
+      expect(() => validateEnv({ API_IDLE_TIMEOUT: value })).toThrow("API_IDLE_TIMEOUT");
+    }
+    expect(apiServerOptions(validateEnv({ API_IDLE_TIMEOUT: "0" }), {}).idleTimeout).toBe(0);
   });
 
   it("reads API_MAX_REQUEST_BODY_SIZE and rejects values that are not byte counts", () => {
-    expect(apiServerOptions(validateEnv({ API_MAX_REQUEST_BODY_SIZE: "1073741824" }), {}))
-      .toEqual({ maxRequestBodySize: 1_073_741_824 });
+    expect(apiServerOptions(validateEnv({ API_MAX_REQUEST_BODY_SIZE: "1073741824" }), {}).maxRequestBodySize)
+      .toBe(1_073_741_824);
     for (const value of ["0", "-1", "1.5", "lots"]) {
       expect(() => validateEnv({ API_MAX_REQUEST_BODY_SIZE: value })).toThrow("API_MAX_REQUEST_BODY_SIZE");
     }
   });
 
   it("lets the application's options win over the environment", () => {
-    const env = validateEnv({ API_MAX_REQUEST_BODY_SIZE: "1024" });
+    const env = validateEnv({ API_MAX_REQUEST_BODY_SIZE: "1024", API_IDLE_TIMEOUT: "60" });
     expect(apiServerOptions(env, { maxRequestBodySize: 4096, idleTimeout: 120 }))
       .toEqual({ maxRequestBodySize: 4096, idleTimeout: 120 });
     expect(apiServerOptions(env, (current) => ({ maxRequestBodySize: current.API_MAX_REQUEST_BODY_SIZE * 2 })))
-      .toEqual({ maxRequestBodySize: 2048 });
+      .toEqual({ maxRequestBodySize: 2048, idleTimeout: 60 });
     expect(() => apiServerOptions(env, { maxRequestBodySize: 0 })).toThrow("maxRequestBodySize");
     expect(() => apiServerOptions(env, { idleTimeout: 256 })).toThrow("idleTimeout");
     expect(() => apiServerOptions(env, { idleTimeout: -1 })).toThrow("idleTimeout");

package/dist/templates/fullstack/apps/api/src/config/server-options.ts

@@ -11,7 +11,7 @@ export interface ApiServerOptions {
   maxRequestBodySize?: number;
   /**
    * Seconds a connection may stay idle before it is closed, from 0 (never) to
-   * 255. Defaults to Elysia's 30 seconds.
+   * 255. Defaults to `API_IDLE_TIMEOUT`.
    */
   idleTimeout?: number;
 }
@@ -31,18 +31,15 @@ const owned: { readonly [name: string]: unknown; readonly apiServerOptions?: Api
 export function apiServerOptions(
   env: AppEnv,
   source: ApiServerOptionsSource | undefined = owned.apiServerOptions,
-): ApiServerOptions & { maxRequestBodySize: number } {
+): Required<ApiServerOptions> {
   const options = typeof source === "function" ? source(env) : source ?? {};
   const maxRequestBodySize = options.maxRequestBodySize ?? env.API_MAX_REQUEST_BODY_SIZE;
   if (!Number.isSafeInteger(maxRequestBodySize) || maxRequestBodySize < 1) {
     throw new Error("apiServerOptions.maxRequestBodySize must be a positive integer of bytes");
   }
-  const { idleTimeout } = options;
-  if (
-    idleTimeout !== undefined &&
-    (!Number.isInteger(idleTimeout) || idleTimeout < 0 || idleTimeout > MAX_IDLE_TIMEOUT_SECONDS)
-  ) {
+  const idleTimeout = options.idleTimeout ?? env.API_IDLE_TIMEOUT;
+  if (!Number.isInteger(idleTimeout) || idleTimeout < 0 || idleTimeout > MAX_IDLE_TIMEOUT_SECONDS) {
     throw new Error(`apiServerOptions.idleTimeout must be an integer from 0 to ${MAX_IDLE_TIMEOUT_SECONDS} seconds`);
   }
-  return { maxRequestBodySize, ...(idleTimeout === undefined ? {} : { idleTimeout }) };
+  return { maxRequestBodySize, idleTimeout };
 }