@podosoft/podokit 1.4.1 → 1.5.0

package/dist/templates/fullstack/apps/web/src/lib/server/backend-proxy.ts

@@ -1,5 +1,6 @@
 import { APP_BODY_LIMITS } from "./body-limits";
 import { APP_FORWARDED_REQUEST_HEADERS, APP_RELAYED_RESPONSE_HEADERS } from "./proxy-headers";
+import { APP_PROXY_TIMEOUTS } from "./proxy-timeouts";
 
 // Server-side proxy boundary. The browser never talks to the API directly:
 // requests go through SvelteKit server routes, which forward an allowlist of
@@ -118,46 +119,115 @@ export interface BodyLimit {
   maxBytes: number;
 }
 
-const BODY_LIMIT_PREFIX = /^\/api(?:\/[A-Za-z0-9._~!$&'()+,;=:@-]+)*\/?$/;
-
-/** Validate application body limits and order them so the longest prefix
- *  matches first. Prefixes are stored without a trailing slash. */
-export function sortedBodyLimits(limits: ReadonlyArray<BodyLimit>): BodyLimit[] {
-  const seen = new Set<string>();
-  const sorted = limits.map(({ pathPrefix, maxBytes }) => {
-    if (
-      !BODY_LIMIT_PREFIX.test(pathPrefix) ||
-      pathPrefix.split("/").some((segment) => segment === "." || segment === "..")
-    ) {
+/** A literal path segment, or null for a `:name` parameter. */
+type PathSegment = string | null;
+
+/** An application path rule with its prefix split into segments. */
+export type PathRule<T extends { pathPrefix: string }> = T & { readonly segments: readonly PathSegment[] };
+
+const LITERAL_SEGMENT = /^[A-Za-z0-9._~!$&'()+,;=:@-]+$/;
+const PARAMETER_SEGMENT = /^:[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** The segments of a prefix under /api/, or undefined when it is not one. */
+function parsePathPrefix(pathPrefix: string): PathSegment[] | undefined {
+  const base = pathPrefix.endsWith("/") ? pathPrefix.slice(0, -1) : pathPrefix;
+  const [root, ...segments] = base.split("/");
+  if (root !== "" || segments[0] !== "api") return undefined;
+  const parsed: PathSegment[] = [];
+  for (const segment of segments) {
+    if (PARAMETER_SEGMENT.test(segment)) {
+      parsed.push(null);
+    } else if (LITERAL_SEGMENT.test(segment) && !segment.startsWith(":") && segment !== "." && segment !== "..") {
+      parsed.push(segment);
+    } else {
+      return undefined;
+    }
+  }
+  return parsed;
+}
+
+/**
+ * Below zero when `a` is more specific: more segments, then, from the left, a
+ * literal segment before a parameter.
+ */
+function compareSpecificity(a: readonly PathSegment[], b: readonly PathSegment[]): number {
+  if (a.length !== b.length) return b.length - a.length;
+  for (let index = 0; index < a.length; index += 1) {
+    const literal = a[index] !== null;
+    if (literal !== (b[index] !== null)) return literal ? -1 : 1;
+  }
+  return 0;
+}
+
+/** Validate an application list of /api path prefixes and order it so the
+ *  most specific prefix matches first. Prefixes are stored without a trailing
+ *  slash. */
+function sortedByPrefix<T extends { pathPrefix: string }>(
+  entries: ReadonlyArray<T>,
+  listName: string,
+  example: string,
+  check: (entry: T) => void,
+): PathRule<T>[] {
+  const seen = new Map<string, string>();
+  const rules = entries.map((entry) => {
+    const { pathPrefix } = entry;
+    const segments = parsePathPrefix(pathPrefix);
+    if (!segments) {
       throw new Error(
-        `APP_BODY_LIMITS pathPrefix must be a static path under /api/, such as "/api/feedback/": ${JSON.stringify(pathPrefix)}`,
+        `${listName} pathPrefix must be a path under /api/ made of literal segments and ":name" parameters, ` +
+          `such as "${example}": ${JSON.stringify(pathPrefix)}`,
       );
     }
-    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
-      throw new Error(`APP_BODY_LIMITS maxBytes for ${pathPrefix} must be a positive whole number of bytes.`);
+    check(entry);
+    // Parameter names do not change which paths a prefix covers.
+    const key = segments.map((segment) => segment ?? ":").join("/");
+    const listed = seen.get(key);
+    if (listed !== undefined) {
+      throw new Error(
+        `${listName} lists the same paths twice: ${JSON.stringify(listed)} and ${JSON.stringify(pathPrefix)}.`,
+      );
     }
-    const base = pathPrefix.endsWith("/") ? pathPrefix.slice(0, -1) : pathPrefix;
-    if (seen.has(base)) throw new Error(`APP_BODY_LIMITS lists ${pathPrefix} more than once.`);
-    seen.add(base);
-    return { pathPrefix: base, maxBytes };
+    seen.set(key, pathPrefix);
+    return { ...entry, pathPrefix: pathPrefix.endsWith("/") ? pathPrefix.slice(0, -1) : pathPrefix, segments };
   });
-  return sorted.sort((left, right) => right.pathPrefix.length - left.pathPrefix.length);
+  return rules.sort((left, right) => compareSpecificity(left.segments, right.segments));
 }
 
-const bodyLimits = sortedBodyLimits(APP_BODY_LIMITS);
-
-/** The body limit for a request path, matched on the decoded path so an encoded
- *  segment cannot step around a prefix. */
-export function bodyLimitFor(pathname: string, limits: readonly BodyLimit[] = bodyLimits): number | undefined {
+/** The most specific rule for a request path. Prefixes match whole segments of
+ *  the decoded path, so an encoded segment cannot step around them, and a
+ *  parameter matches exactly one non-empty segment. */
+function entryFor<T extends { pathPrefix: string }>(
+  pathname: string,
+  rules: readonly PathRule<T>[],
+): PathRule<T> | undefined {
   let path = pathname;
   try {
     path = decodeURIComponent(pathname);
   } catch {
     // Keep the raw path when it holds a malformed escape.
   }
-  return limits.find(
-    ({ pathPrefix }) => path === pathPrefix || path.startsWith(`${pathPrefix}/`),
-  )?.maxBytes;
+  const segments = path.split("/").slice(1);
+  return rules.find(
+    (rule) =>
+      rule.segments.length <= segments.length &&
+      rule.segments.every((segment, index) =>
+        segment === null ? segments[index] !== "" : segment === segments[index],
+      ),
+  );
+}
+
+export function sortedBodyLimits(limits: ReadonlyArray<BodyLimit>): PathRule<BodyLimit>[] {
+  return sortedByPrefix(limits, "APP_BODY_LIMITS", "/api/feedback/", ({ pathPrefix, maxBytes }) => {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+      throw new Error(`APP_BODY_LIMITS maxBytes for ${pathPrefix} must be a positive whole number of bytes.`);
+    }
+  });
+}
+
+const bodyLimits = sortedBodyLimits(APP_BODY_LIMITS);
+
+export function bodyLimitFor(pathname: string, limits: readonly PathRule<BodyLimit>[] = bodyLimits): number | undefined {
+  return entryFor(pathname, limits)?.maxBytes;
 }
 
 /** Read a request body, or return null as soon as it exceeds maxBytes. The rest
@@ -218,6 +288,216 @@ export function backendBaseUrl(): string {
   return process.env.BACKEND_INTERNAL_URL ?? "http://localhost:5002";
 }
 
+/**
+ * Milliseconds one server-side API call may take, response body included, and
+ * how often the proxy checks whether the API still answers at all while it waits
+ * for response headers.
+ */
+const DEFAULT_BACKEND_TIMEOUT_MS = 2_000;
+/**
+ * Milliseconds the proxy waits for the API's response headers, unless
+ * APP_PROXY_TIMEOUTS lists the path. The API's default idle timeout of 35
+ * seconds outlasts it.
+ * Streamed bodies are not cut off once they start.
+ */
+const DEFAULT_BACKEND_PROXY_TIMEOUT_MS = 30_000;
+/** Seconds between checks while the API is unreachable, also sent as Retry-After. */
+const BACKEND_RETRY_AFTER_SECONDS = 2;
+const MAX_TIMER_MS = 2_147_483_647;
+
+/** A whole number of milliseconds from the environment, or the default when unset or empty. */
+export function envMilliseconds(name: string, fallback: number): number {
+  const raw = process.env[name]?.trim();
+  if (!raw) return fallback;
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < 1 || value > MAX_TIMER_MS) {
+    throw new Error(
+      `${name} must be a whole number of milliseconds from 1 to ${MAX_TIMER_MS}: ${JSON.stringify(raw)}`,
+    );
+  }
+  return value;
+}
+
+export function backendTimeoutMs(): number {
+  return envMilliseconds("BACKEND_TIMEOUT_MS", DEFAULT_BACKEND_TIMEOUT_MS);
+}
+
+function backendProxyTimeoutMs(): number {
+  return envMilliseconds("BACKEND_PROXY_TIMEOUT_MS", DEFAULT_BACKEND_PROXY_TIMEOUT_MS);
+}
+
+// An invalid value stops the server when this module loads instead of failing
+// every request that reads it.
+backendTimeoutMs();
+backendProxyTimeoutMs();
+
+export interface ProxyTimeout {
+  pathPrefix: string;
+  /** Milliseconds to wait for response headers, or null for no deadline. */
+  timeoutMs: number | null;
+}
+
+export function sortedProxyTimeouts(timeouts: ReadonlyArray<ProxyTimeout>): PathRule<ProxyTimeout>[] {
+  return sortedByPrefix(timeouts, "APP_PROXY_TIMEOUTS", "/api/exports/", ({ pathPrefix, timeoutMs }) => {
+    if (timeoutMs !== null && (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_TIMER_MS)) {
+      throw new Error(
+        `APP_PROXY_TIMEOUTS timeoutMs for ${pathPrefix} must be null or a whole number of milliseconds from 1 to ${MAX_TIMER_MS}.`,
+      );
+    }
+  });
+}
+
+const proxyTimeouts = sortedProxyTimeouts(APP_PROXY_TIMEOUTS);
+
+/** How long the proxy waits for response headers on a request path, or null for no deadline. */
+export function proxyTimeoutFor(
+  pathname: string,
+  timeouts: readonly PathRule<ProxyTimeout>[] = proxyTimeouts,
+): number | null {
+  const entry = entryFor(pathname, timeouts);
+  return entry ? entry.timeoutMs : backendProxyTimeoutMs();
+}
+
+/** Bun closes silent connections on a 4-second tick, up to 4 seconds before their idle timeout. */
+const IDLE_TICK_SECONDS = 4;
+/** The longest idle timeout Bun accepts; 0 turns it off. */
+const MAX_IDLE_TIMEOUT_SECONDS = 255;
+
+/**
+ * Throw unless the web server keeps a silent connection open longer than the
+ * proxy waits for response headers. adapter-bun takes its idle timeout from
+ * CONNECTION_IDLE_TIMEOUT (Bun's 10 seconds when unset) and closes a connection
+ * that sends nothing for that long without a response, so neither the API's late
+ * answer nor the proxy's 504 would reach the browser.
+ */
+export function checkIdleTimeout(
+  idleTimeout: string | undefined,
+  defaultTimeoutMs: number,
+  timeouts: readonly ProxyTimeout[],
+): void {
+  // adapter-bun rejects a malformed value itself when it starts.
+  if (idleTimeout === undefined || !/^\d+$/.test(idleTimeout) || Number(idleTimeout) === 0) return;
+  let longest: { timeoutMs: number | null; source: string } = {
+    timeoutMs: defaultTimeoutMs,
+    source: "BACKEND_PROXY_TIMEOUT_MS",
+  };
+  for (const { pathPrefix, timeoutMs } of timeouts) {
+    if (longest.timeoutMs !== null && (timeoutMs === null || timeoutMs > longest.timeoutMs)) {
+      longest = { timeoutMs, source: `APP_PROXY_TIMEOUTS for ${pathPrefix}` };
+    }
+  }
+  const seconds = Number(idleTimeout);
+  if (longest.timeoutMs !== null && (seconds - IDLE_TICK_SECONDS) * 1000 > longest.timeoutMs) return;
+  const minimum =
+    longest.timeoutMs === null ? Infinity : Math.floor(longest.timeoutMs / 1000) + IDLE_TICK_SECONDS + 1;
+  const wait = longest.timeoutMs === null ? "no deadline" : `${longest.timeoutMs} ms`;
+  const fix =
+    minimum <= MAX_IDLE_TIMEOUT_SECONDS
+      ? `at least ${minimum}, or to 0 to turn the idle timeout off`
+      : `0 to turn the idle timeout off, since Bun allows at most ${MAX_IDLE_TIMEOUT_SECONDS} seconds`;
+  throw new Error(
+    `CONNECTION_IDLE_TIMEOUT=${seconds} lets the web server close a silent connection before the /api proxy ` +
+      `stops waiting for response headers (${wait}, ${longest.source}); Bun closes idle connections up to ` +
+      `${IDLE_TICK_SECONDS} seconds early. Set CONNECTION_IDLE_TIMEOUT to ${fix}.`,
+  );
+}
+
+checkIdleTimeout(process.env.CONNECTION_IDLE_TIMEOUT, backendProxyTimeoutMs(), proxyTimeouts);
+
+// The API counts as unreachable only when GET /health gets no HTTP answer
+// within BACKEND_TIMEOUT_MS. It is checked when a request gets no answer, and
+// every BACKEND_TIMEOUT_MS while the proxy waits for response headers, so one
+// slow endpoint does not fail every request in the process, while an API that
+// stops answering still ends a long or unbounded wait. Once the API is found
+// unreachable, requests still waiting for it fail, new ones fail at once instead
+// of each waiting for a refused connection, a DNS lookup, or a hung server, and
+// a background check runs at most every BACKEND_RETRY_AFTER_SECONDS. Any HTTP
+// answer, including an error status, means the API is reachable.
+let unreachable = false;
+let answers = 0;
+let lastCheckEnded = 0;
+let pendingCheck: Promise<void> | undefined;
+let outage = new AbortController();
+
+/** Aborts when the API is found unreachable, failing the requests that still wait for it. */
+export function backendOutageSignal(): AbortSignal {
+  return outage.signal;
+}
+
+/** Check whether the API answers at all. Concurrent callers share one check. */
+export function checkBackend(): Promise<void> {
+  if (!pendingCheck) {
+    const answersBefore = answers;
+    pendingCheck = fetch(`${backendBaseUrl()}/health`, { signal: AbortSignal.timeout(backendTimeoutMs()) })
+      .then(
+        (response) => {
+          reportBackendAnswer();
+          return response.body?.cancel().catch(() => undefined);
+        },
+        () => {
+          if (answers !== answersBefore) return;
+          unreachable = true;
+          outage.abort(new DOMException("The API is unavailable", "AbortError"));
+          outage = new AbortController();
+        },
+      )
+      .finally(() => {
+        lastCheckEnded = Date.now();
+        pendingCheck = undefined;
+      });
+  }
+  return pendingCheck;
+}
+
+/** Check the API unless a check is running or one ended within BACKEND_TIMEOUT_MS. */
+function recheckBackend(now = Date.now()): void {
+  if (!pendingCheck && now - lastCheckEnded >= backendTimeoutMs()) void checkBackend();
+}
+
+/** Record an HTTP answer from the API, whatever its status. */
+export function reportBackendAnswer(): void {
+  answers += 1;
+  unreachable = false;
+}
+
+/** Record a request that got no HTTP answer, and check the API unless it is already known to be down. */
+export function reportBackendFailure(): Promise<void> {
+  return unreachable ? Promise.resolve() : checkBackend();
+}
+
+/**
+ * False while the API is known to be unreachable. Such a call also starts a
+ * background check when none ran in the last BACKEND_RETRY_AFTER_SECONDS.
+ */
+export function backendReachable(now = Date.now()): boolean {
+  if (!unreachable) return true;
+  if (!pendingCheck && now - lastCheckEnded >= BACKEND_RETRY_AFTER_SECONDS * 1000) void checkBackend();
+  return false;
+}
+
+function backendFailure(path: string, statusCode: 503 | 504): Response {
+  const timedOut = statusCode === 504;
+  return Response.json(
+    {
+      success: false,
+      error: {
+        code: timedOut ? "BACKEND_TIMEOUT" : "BACKEND_UNAVAILABLE",
+        message: timedOut ? "The API did not respond in time" : "The API is unavailable",
+        statusCode,
+        path,
+        timestamp: new Date().toISOString(),
+      },
+    },
+    {
+      status: statusCode,
+      headers: {
+        "cache-control": "no-store",
+        ...(timedOut ? {} : { "retry-after": String(BACKEND_RETRY_AFTER_SECONDS) }),
+      },
+    },
+  );
+}
+
 // Normalize the resolved client IP for the forwarded header. better-auth stores
 // IPv4 as-is but anonymizes IPv6 (masks the host bits), so an IPv6 loopback would
 // be recorded as "::" — map loopback to 127.0.0.1 for a clean local value, and
@@ -252,12 +532,16 @@ export async function proxyRequest(
   const forwardedIp = normalizeClientIp(clientAddress);
   if (forwardedIp) headers.set("x-forwarded-for", forwardedIp);
 
+  const { pathname } = new URL(request.url);
+  if (!backendReachable()) {
+    request.body?.cancel().catch(() => undefined);
+    return backendFailure(pathname, 503);
+  }
   const hasBody = request.method !== "GET" && request.method !== "HEAD";
   let body: ArrayBuffer | undefined;
   if (hasBody) {
     // Preserve multipart uploads and other binary bodies byte-for-byte. Reading
     // them as text corrupts bytes that are not valid UTF-8 before forwarding.
-    const { pathname } = new URL(request.url);
     const maxBytes = bodyLimitFor(pathname);
     if (maxBytes === undefined) {
       body = await request.arrayBuffer();
@@ -267,16 +551,46 @@ export async function proxyRequest(
       body = limited;
     }
   }
-  const upstream = await fetch(targetUrl, {
-    method: request.method,
-    headers,
-    body,
-    redirect: "manual",
-    // Abort the upstream request when the browser disconnects. Without this, every
-    // closed EventSource or aborted request keeps its API socket open until Bun's
-    // fetch pool is exhausted and the web process stops serving requests.
-    signal: request.signal,
-  });
+  // The deadline, the health checks, and the outage signal cover only the wait
+  // for response headers, so streamed bodies such as server-sent events are not
+  // cut off.
+  const waiting = new AbortController();
+  const timeoutMs = proxyTimeoutFor(pathname);
+  const deadline =
+    timeoutMs === null
+      ? undefined
+      : setTimeout(
+          () => waiting.abort(new DOMException("The API did not respond in time", "TimeoutError")),
+          timeoutMs,
+        );
+  const healthChecks = setInterval(() => recheckBackend(), backendTimeoutMs());
+  const outage = backendOutageSignal();
+  const failOnOutage = (): void => waiting.abort(outage.reason);
+  outage.addEventListener("abort", failOnOutage);
+  let upstream: Response;
+  try {
+    upstream = await fetch(targetUrl, {
+      method: request.method,
+      headers,
+      body,
+      redirect: "manual",
+      // Abort the upstream request when the browser disconnects. Without this, every
+      // closed EventSource or aborted request keeps its API socket open until Bun's
+      // fetch pool is exhausted and the web process stops serving requests.
+      signal: AbortSignal.any([request.signal, waiting.signal]),
+    });
+  } catch (cause: unknown) {
+    // Nobody waits for an answer to a request the browser abandoned.
+    if (request.signal.aborted) throw cause;
+    if (outage.aborted) return backendFailure(pathname, 503);
+    void reportBackendFailure();
+    return backendFailure(pathname, waiting.signal.aborted ? 504 : 503);
+  } finally {
+    clearTimeout(deadline);
+    clearInterval(healthChecks);
+    outage.removeEventListener("abort", failOnOutage);
+  }
+  reportBackendAnswer();
 
   const responseHeaders = new Headers();
   for (const name of relayedResponseHeaders) {

package/dist/templates/fullstack/apps/web/src/lib/server/body-limits.ts

@@ -3,8 +3,11 @@
  * proxies to the API. An entry caps the body of every request whose path is
  * pathPrefix or below it, for example
  *   { pathPrefix: "/api/feedback/", maxBytes: 64 * 1024 }
- * and the longest matching prefix wins. Above the limit the proxy stops reading
- * and answers 413 PAYLOAD_TOO_LARGE without contacting the API.
+ *   { pathPrefix: "/api/hosts/:hostId/uploads", maxBytes: 1024 * 1024 }
+ * where a :name segment matches exactly one non-empty path segment. The most
+ * specific entry wins: more segments, then a literal segment over a parameter
+ * from the left. Above the limit the proxy stops reading and answers 413
+ * PAYLOAD_TOO_LARGE without contacting the API.
  *
  * BODY_SIZE_LIMIT remains the ceiling for every web route: Bun rejects a larger
  * body before this code runs, so a maxBytes above it has no effect. Routes that

package/dist/templates/fullstack/apps/web/src/lib/server/proxy-timeouts.ts

@@ -0,0 +1,22 @@
+/**
+ * Application-owned deadlines for /api requests that the web server proxies to
+ * the API. An entry replaces BACKEND_PROXY_TIMEOUT_MS for every request whose
+ * path is pathPrefix or below it, for example
+ *   { pathPrefix: "/api/exports/", timeoutMs: 120_000 }
+ *   { pathPrefix: "/api/hosts/:hostId/file-transfers", timeoutMs: null }
+ * where a :name segment matches exactly one non-empty path segment. The most
+ * specific entry wins: more segments, then a literal segment over a parameter
+ * from the left. timeoutMs is how long the proxy waits for the API's response
+ * headers before it answers 504 BACKEND_TIMEOUT; null waits as long as the API
+ * takes. Either way the proxy answers 503 BACKEND_UNAVAILABLE once the API's
+ * GET /health stops answering, and the deadline ends when the response headers
+ * arrive.
+ *
+ * Bun closes a silent connection up to 4 seconds before its idle timeout, so a
+ * longer wait also needs the API's API_IDLE_TIMEOUT and the web server's
+ * CONNECTION_IDLE_TIMEOUT (35 seconds each by default) more than 4 seconds above
+ * the deadline, or 0 for null or anything above 250 seconds. The proxy refuses
+ * to load when CONNECTION_IDLE_TIMEOUT cannot cover an entry here.
+ * PodoKit creates this file once and never overwrites it.
+ */
+export const APP_PROXY_TIMEOUTS: ReadonlyArray<{ pathPrefix: string; timeoutMs: number | null }> = [];

package/dist/templates/fullstack/apps/web/src/routes/healthz/+server.ts

@@ -0,0 +1,13 @@
+import type { RequestHandler } from "@sveltejs/kit";
+
+// Liveness and readiness of the web server itself, for the Kubernetes probes,
+// the Compose healthcheck, and the image HEALTHCHECK. It never calls the API, so
+// an API outage does not take the web server out of service.
+export const GET: RequestHandler = () =>
+  new Response("ok\n", {
+    headers: {
+      "content-type": "text/plain; charset=utf-8",
+      "cache-control": "no-store",
+      "x-robots-tag": "noindex, nofollow",
+    },
+  });

package/dist/templates/fullstack/dot-env.docker.example

@@ -12,6 +12,12 @@ POSTGRES_USER=podokit
 POSTGRES_PASSWORD=podokit
 POSTGRES_DB=podokit
 BACKEND_INTERNAL_URL=http://api:5002
+# API: the web container and the gateway are the one proxy in front of it.
+TRUSTED_PROXY_HOPS=1
+# Web: milliseconds per server-side API call, and the /api proxy's wait for
+# response headers.
+# BACKEND_TIMEOUT_MS=2000
+# BACKEND_PROXY_TIMEOUT_MS=30000
 CORS_ORIGIN=http://{{projectName}}.localhost,http://localhost
 REDIS_HOST=redis
 REDIS_PORT=6379

package/dist/templates/fullstack/dot-env.example

@@ -27,6 +27,18 @@ POSTGRES_DB=podokit
 # Largest API request body in bytes (Bun's default is 128 MiB). Requests through
 # the web app's /api proxy are also bounded by BODY_SIZE_LIMIT below.
 # API_MAX_REQUEST_BODY_SIZE=134217728
+# Seconds the API keeps a silent connection open (0 to 255, 0 turns it off). Keep
+# it, like CONNECTION_IDLE_TIMEOUT below, more than 4 above the longest /api proxy
+# deadline in seconds.
+# API_IDLE_TIMEOUT=35
+
+# Reverse proxies in front of the API whose X-Forwarded-For names the caller. The
+# web app's /api proxy is one, so 1 records the browser's address for sessions,
+# audit entries, and rate limits; 0 uses the socket peer. Count only proxies that
+# every request passes: with 1, a caller that reaches the API directly chooses
+# its own recorded address.
+TRUSTED_PROXY_HOPS=1
+# TRUSTED_PROXY_HEADER=x-forwarded-for
 
 # Readiness (GET /health/ready): the longest one dependency check may run, and how
 # long a result is reused across probes (0 checks on every request).
@@ -35,10 +47,21 @@ POSTGRES_DB=podokit
 
 # Web -> API boundary (server-side only; not exposed to the browser)
 BACKEND_INTERNAL_URL=http://localhost:5002
+# Milliseconds one server-side API call may take, and how long the /api proxy
+# waits for response headers (504 BACKEND_TIMEOUT after the second value). When
+# the API's GET /health does not answer within BACKEND_TIMEOUT_MS either, API
+# calls fail at once until it does. Raise BACKEND_PROXY_TIMEOUT_MS together with
+# API_IDLE_TIMEOUT above and CONNECTION_IDLE_TIMEOUT below.
+# BACKEND_TIMEOUT_MS=2000
+# BACKEND_PROXY_TIMEOUT_MS=30000
 
 CORS_ORIGIN=http://localhost:5001
 # Web request limit; leave room for a 2 MiB multipart upload
 BODY_SIZE_LIMIT=3M
+# Seconds the built web server keeps a silent connection open (0 to 255, 0 turns
+# it off). Keep it more than 4 above the longest /api proxy deadline in seconds,
+# BACKEND_PROXY_TIMEOUT_MS or APP_PROXY_TIMEOUTS; the proxy refuses to load otherwise.
+CONNECTION_IDLE_TIMEOUT=35
 
 # ── Optional / development ───────────────────────────────────────────
 # Redis — only needed by cache/queue modules (redis, bullmq, rate-limit,

package/dist/templates/fullstack/infra/k3s/configmap.yaml

@@ -9,6 +9,9 @@ data:
   CORS_ORIGIN: "https://example.com"
   BACKEND_INTERNAL_URL: "http://api:3000"
   BODY_SIZE_LIMIT: "3M"
+  CONNECTION_IDLE_TIMEOUT: "35"
+  API_IDLE_TIMEOUT: "35"
+  TRUSTED_PROXY_HOPS: "1"
   PROTOCOL_HEADER: "x-forwarded-proto"
   HOST_HEADER: "x-forwarded-host"
   ADDRESS_HEADER: "x-forwarded-for"

package/dist/templates/fullstack/infra/k3s/web-deployment.yaml

@@ -21,10 +21,13 @@ spec:
           envFrom:
             - configMapRef: { name: app-config }
           # Without these a rolling update sends traffic to a process that has not
-          # bound its port yet.
+          # bound its port yet. /healthz never calls the API, so an API outage does
+          # not take the web pods out of service.
           readinessProbe:
-            httpGet: { path: /, port: 3000 }
+            httpGet: { path: /healthz, port: 3000 }
             initialDelaySeconds: 5
+            timeoutSeconds: 2
           livenessProbe:
-            httpGet: { path: /, port: 3000 }
+            httpGet: { path: /healthz, port: 3000 }
             initialDelaySeconds: 15
+            timeoutSeconds: 2

package/dist/templates/fullstack/tests/api/health.api.spec.ts

@@ -12,3 +12,11 @@ test("GET /health/ready reports the database", async ({ request }) => {
   expect(res.status()).toBe(200);
   expect((await res.json()).status).toBe("ready");
 });
+
+test("GET /healthz answers from the web server without caching or indexing @smoke", async ({ request }) => {
+  const res = await request.get("/healthz");
+  expect(res.status()).toBe(200);
+  expect(await res.text()).toBe("ok\n");
+  expect(res.headers()["cache-control"]).toBe("no-store");
+  expect(res.headers()["x-robots-tag"]).toBe("noindex, nofollow");
+});