@podosoft/podokit 1.4.0 → 1.4.2

package/dist/templates/fullstack/apps/web/src/error.html

@@ -0,0 +1,73 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="color-scheme" content="light dark" />
+    <title>%sveltekit.status% %sveltekit.error.message%</title>
+    <!-- SvelteKit serves this page when the root layout or a server hook fails,
+         so it cannot use the app's styles, scripts, assets, or components. It
+         fills in only the status and the HTML-escaped error message. -->
+    <style>
+      :root {
+        --background: oklch(1 0 0);
+        --foreground: oklch(0.141 0.005 285.823);
+        --muted-foreground: oklch(0.552 0.016 285.938);
+        --border: oklch(0.92 0.004 286.32);
+      }
+
+      @media (prefers-color-scheme: dark) {
+        :root {
+          --background: oklch(0.141 0.005 285.823);
+          --foreground: oklch(0.985 0 0);
+          --muted-foreground: oklch(0.705 0.015 286.067);
+          --border: oklch(1 0 0 / 15%);
+        }
+      }
+
+      body {
+        box-sizing: border-box;
+        display: grid;
+        min-height: 100vh;
+        margin: 0;
+        padding: 1.5rem;
+        place-items: center;
+        background: var(--background);
+        color: var(--foreground);
+        font-family: ui-sans-serif, system-ui, sans-serif;
+        line-height: 1.5;
+      }
+
+      main {
+        display: flex;
+        align-items: center;
+        gap: 1rem;
+        max-width: 32rem;
+      }
+
+      .status {
+        margin: 0;
+        color: var(--muted-foreground);
+        font-size: 2.25rem;
+        font-variant-numeric: tabular-nums;
+        font-weight: 600;
+        line-height: 1;
+      }
+
+      h1 {
+        margin: 0;
+        padding-left: 1rem;
+        border-left: 1px solid var(--border);
+        font-size: 1rem;
+        font-weight: 500;
+        overflow-wrap: anywhere;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <p class="status">%sveltekit.status%</p>
+      <h1>%sveltekit.error.message%</h1>
+    </main>
+  </body>
+</html>

package/dist/templates/fullstack/apps/web/src/lib/server/api.test.ts

@@ -0,0 +1,116 @@
+import { ApiError } from "@podosoft/podokit-api-client";
+import type { RequestEvent } from "@sveltejs/kit";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { BackendUnavailableError, serverApiClient } from "./api";
+import { backendReachable, checkBackend, reportBackendAnswer } from "./backend-proxy";
+
+type Fetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+function requestEvent(fetch: Fetch): RequestEvent {
+  return {
+    request: new Request("http://app.localhost/services", { headers: { cookie: "session=abc" } }),
+    getClientAddress: () => "203.0.113.9",
+    fetch,
+  } as unknown as RequestEvent;
+}
+
+// Never answers on its own, like a blackholed connection or a hung API, and
+// rejects when its signal aborts.
+const hang: Fetch = (_input, init) =>
+  new Promise((_settle, reject) => {
+    init?.signal?.addEventListener("abort", () => reject(init.signal?.reason));
+  });
+const refuse: Fetch = async () => {
+  throw new TypeError("Unable to connect. Is the computer able to access the url?");
+};
+
+// The background GET /health check uses the global fetch.
+function stubHealth(health: Fetch): ReturnType<typeof vi.fn<Fetch>> {
+  const fetch = vi.fn<Fetch>(health);
+  vi.stubGlobal("fetch", fetch);
+  return fetch;
+}
+
+describe("serverApiClient", () => {
+  afterEach(() => {
+    reportBackendAnswer();
+    vi.unstubAllGlobals();
+    vi.unstubAllEnvs();
+  });
+
+  it("forwards the cookie and client address", async () => {
+    let headers: Headers | undefined;
+    const api = serverApiClient(requestEvent(async (_input, init) => {
+      headers = new Headers(init?.headers);
+      return Response.json({ ok: true });
+    }));
+
+    await expect(api.get("/site/settings")).resolves.toEqual({ ok: true });
+    expect(headers?.get("cookie")).toBe("session=abc");
+    expect(headers?.get("x-forwarded-for")).toBe("203.0.113.9");
+  });
+
+  it("gives up on a call that outlasts BACKEND_TIMEOUT_MS", async () => {
+    vi.stubEnv("BACKEND_TIMEOUT_MS", "20");
+    stubHealth(async () => new Response("ok"));
+    const api = serverApiClient(requestEvent(hang));
+
+    const started = Date.now();
+    await expect(api.get("/reports/slow")).rejects.toMatchObject({ name: "TimeoutError" });
+    expect(Date.now() - started).toBeLessThan(5_000);
+    await checkBackend();
+    expect(backendReachable()).toBe(true);
+  });
+
+  it("marks the API unreachable when its health check fails as well", async () => {
+    vi.stubEnv("BACKEND_TIMEOUT_MS", "20");
+    stubHealth(hang);
+
+    await expect(serverApiClient(requestEvent(hang)).get("/site/settings")).rejects.toMatchObject({
+      name: "TimeoutError",
+    });
+    await checkBackend();
+    expect(backendReachable()).toBe(false);
+  });
+
+  it("fails at once without contacting the API while it is unreachable", async () => {
+    stubHealth(refuse);
+    await checkBackend();
+    const fetch = vi.fn<Fetch>(async () => Response.json({}));
+
+    await expect(serverApiClient(requestEvent(fetch)).get("/blog")).rejects.toBeInstanceOf(BackendUnavailableError);
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it("fails calls in flight once the API is found unreachable", async () => {
+    stubHealth(refuse);
+    const pending = serverApiClient(requestEvent(hang)).get("/site/settings");
+    const failed = expect(pending).rejects.toBeInstanceOf(BackendUnavailableError);
+
+    await checkBackend();
+
+    await failed;
+  });
+
+  it("treats an error status as an answer from a reachable API", async () => {
+    const health = stubHealth(refuse);
+    const api = serverApiClient(requestEvent(async () =>
+      Response.json({ success: false, error: { code: "INTERNAL", message: "boom", statusCode: 500 } }, { status: 500 })
+    ));
+
+    await expect(api.get("/blog")).rejects.toBeInstanceOf(ApiError);
+    expect(health).not.toHaveBeenCalled();
+    expect(backendReachable()).toBe(true);
+  });
+
+  it("does not report a call the caller aborted as an outage", async () => {
+    const health = stubHealth(refuse);
+    const caller = new AbortController();
+    const pending = serverApiClient(requestEvent(hang)).get("/blog", { signal: caller.signal });
+    caller.abort();
+
+    await expect(pending).rejects.toBeDefined();
+    expect(health).not.toHaveBeenCalled();
+    expect(backendReachable()).toBe(true);
+  });
+});

package/dist/templates/fullstack/apps/web/src/lib/server/api.ts

@@ -1,18 +1,48 @@
 import type { RequestEvent } from "@sveltejs/kit";
 import { createApiClient, type ApiClient } from "@podosoft/podokit-api-client";
-import { backendBaseUrl, resolveClientIp } from "./backend-proxy";
+import {
+  backendBaseUrl,
+  backendOutageSignal,
+  backendReachable,
+  backendTimeoutMs,
+  reportBackendAnswer,
+  reportBackendFailure,
+  resolveClientIp,
+} from "./backend-proxy";
+
+/** Thrown without contacting the API while it is known to be unreachable. */
+export class BackendUnavailableError extends Error {
+  constructor() {
+    super("The API is unavailable");
+    this.name = "BackendUnavailableError";
+  }
+}
 
 // Server-side client for load functions and hooks: points at the internal
-// backend URL and forwards the incoming request's cookies.
+// backend URL and forwards the incoming request's cookies. Each call is bounded
+// by BACKEND_TIMEOUT_MS, so a page renders its fallbacks instead of waiting for
+// an API that does not answer.
 export function serverApiClient(event: RequestEvent): ApiClient {
   const cookie = event.request.headers.get("cookie") ?? "";
   const clientIp = resolveClientIp(event.getClientAddress);
   const fetchWithCookies: typeof fetch = Object.assign(
-    (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+    async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]): Promise<Response> => {
+      if (!backendReachable()) throw new BackendUnavailableError();
       const headers = new Headers(init?.headers);
       if (cookie) headers.set("cookie", cookie);
       if (clientIp) headers.set("x-forwarded-for", clientIp);
-      return event.fetch(input, { ...init, headers });
+      const outage = backendOutageSignal();
+      const signals = [AbortSignal.timeout(backendTimeoutMs()), outage];
+      if (init?.signal) signals.push(init.signal);
+      try {
+        const response = await event.fetch(input, { ...init, headers, signal: AbortSignal.any(signals) });
+        reportBackendAnswer();
+        return response;
+      } catch (cause: unknown) {
+        if (outage.aborted) throw new BackendUnavailableError();
+        if (!init?.signal?.aborted) void reportBackendFailure();
+        throw cause;
+      }
     },
     { preconnect: fetch.preconnect },
   );

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

@@ -3,9 +3,13 @@ import type { AddressInfo } from "node:net";
 import { gzipSync } from "node:zlib";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
+  backendReachable,
   bodyLimitFor,
+  checkBackend,
+  envMilliseconds,
   IN_MEMORY_RESPONSE_BYTES,
   proxyRequest,
+  reportBackendAnswer,
   rawSubpath,
   resolveClientIp,
   sortedBodyLimits,
@@ -564,3 +568,174 @@ describe("backend proxy application body limits", () => {
     );
   });
 });
+
+describe("backend proxy outages", () => {
+  type Fetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+  afterEach(() => {
+    reportBackendAnswer();
+    vi.unstubAllGlobals();
+    vi.unstubAllEnvs();
+  });
+
+  // Never answers on its own, like a blackholed connection or a hung API, and
+  // rejects when its signal aborts.
+  const hang: Fetch = (_input, init) =>
+    new Promise((_settle, reject) => {
+      init?.signal?.addEventListener("abort", () => reject(init.signal?.reason));
+    });
+  const refuse: Fetch = async () => {
+    throw new TypeError("Unable to connect. Is the computer able to access the url?");
+  };
+
+  // Routes the background GET /health check and the proxied request separately.
+  function stubApi(health: Fetch, upstream: Fetch): ReturnType<typeof vi.fn<Fetch>> {
+    const fetch = vi.fn<Fetch>((input, init) =>
+      String(input).endsWith("/health") ? health(input, init) : upstream(input, init),
+    );
+    vi.stubGlobal("fetch", fetch);
+    return fetch;
+  }
+
+  async function takeApiDown(): Promise<void> {
+    stubApi(refuse, refuse);
+    await checkBackend();
+    expect(backendReachable()).toBe(false);
+  }
+
+  it("answers 503 with the error envelope when the API cannot be reached", async () => {
+    stubApi(refuse, refuse);
+
+    const response = await proxyRequest(new Request("http://app.localhost/api/blog"), "http://api:5002/blog");
+
+    expect(response.status).toBe(503);
+    expect(response.headers.get("retry-after")).toBe("2");
+    expect(response.headers.get("cache-control")).toBe("no-store");
+    expect(await response.json()).toMatchObject({
+      success: false,
+      error: { code: "BACKEND_UNAVAILABLE", statusCode: 503, path: "/api/blog" },
+    });
+    await checkBackend();
+    expect(backendReachable()).toBe(false);
+  });
+
+  it("answers 504 when the API sends no response headers before the deadline", async () => {
+    vi.stubEnv("BACKEND_PROXY_TIMEOUT_MS", "20");
+    stubApi(async () => new Response("ok"), hang);
+
+    const response = await proxyRequest(new Request("http://app.localhost/api/report"), "http://api:5002/report");
+
+    expect(response.status).toBe(504);
+    expect(response.headers.get("retry-after")).toBeNull();
+    expect(await response.json()).toMatchObject({ error: { code: "BACKEND_TIMEOUT", statusCode: 504 } });
+    await checkBackend();
+    expect(backendReachable()).toBe(true);
+  });
+
+  it("fails requests still waiting for headers once the API is found unreachable", async () => {
+    vi.stubEnv("BACKEND_TIMEOUT_MS", "20");
+    stubApi(hang, hang);
+
+    const started = Date.now();
+    const response = await proxyRequest(new Request("http://app.localhost/api/blog"), "http://api:5002/blog");
+
+    expect(Date.now() - started).toBeLessThan(5_000);
+    expect(response.status).toBe(503);
+    expect(await response.json()).toMatchObject({ error: { code: "BACKEND_UNAVAILABLE" } });
+    expect(backendReachable()).toBe(false);
+  });
+
+  it("keeps waiting for a slow endpoint while the API answers its health check", async () => {
+    vi.stubEnv("BACKEND_INTERNAL_URL", "http://api:5002");
+    vi.stubEnv("BACKEND_TIMEOUT_MS", "20");
+    const fetch = stubApi(
+      async () => new Response("ok"),
+      () => new Promise((settle) => setTimeout(() => settle(Response.json({ done: true })), 80)),
+    );
+
+    const response = await proxyRequest(new Request("http://app.localhost/api/report"), "http://api:5002/report");
+
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({ done: true });
+    expect(fetch.mock.calls.map(([input]) => String(input))).toEqual([
+      "http://api:5002/report",
+      "http://api:5002/health",
+    ]);
+    expect(backendReachable()).toBe(true);
+  });
+
+  it("answers at once without contacting the API while it is unreachable", async () => {
+    await takeApiDown();
+    const fetch = stubApi(refuse, async () => new Response(null, { status: 204 }));
+
+    const response = await proxyRequest(
+      new Request("http://app.localhost/api/blog", { method: "POST", body: "{}" }),
+      "http://api:5002/blog",
+    );
+
+    expect(response.status).toBe(503);
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it("checks the API again after the retry interval and recovers on any HTTP answer", async () => {
+    await takeApiDown();
+    const fetch = stubApi(async () => new Response("unavailable", { status: 500 }), refuse);
+
+    expect(backendReachable(Date.now() + 2_000)).toBe(false);
+    await checkBackend();
+
+    expect(fetch).toHaveBeenCalledTimes(1);
+    expect(backendReachable()).toBe(true);
+  });
+
+  it("relays an error status without checking the API", async () => {
+    const fetch = stubApi(refuse, async () => Response.json({ success: false }, { status: 500 }));
+
+    const response = await proxyRequest(new Request("http://app.localhost/api/blog"), "http://api:5002/blog");
+
+    expect(response.status).toBe(500);
+    expect(fetch).toHaveBeenCalledTimes(1);
+    expect(backendReachable()).toBe(true);
+  });
+
+  it("does not report a browser that disconnected as an outage", async () => {
+    const fetch = stubApi(refuse, hang);
+    const client = new AbortController();
+    const pending = proxyRequest(
+      new Request("http://app.localhost/api/events", { signal: client.signal }),
+      "http://api:5002/events",
+    );
+    client.abort();
+
+    await expect(pending).rejects.toBeDefined();
+    expect(fetch).toHaveBeenCalledTimes(1);
+    expect(backendReachable()).toBe(true);
+  });
+
+  it("stops the deadline once response headers arrive, so a stream keeps flowing", async () => {
+    vi.stubEnv("BACKEND_PROXY_TIMEOUT_MS", "20");
+    let upstreamSignal: AbortSignal | undefined;
+    stubApi(refuse, async (_input, init) => {
+      upstreamSignal = init?.signal ?? undefined;
+      return new Response(new ReadableStream(), { headers: { "content-type": "text/event-stream" } });
+    });
+
+    const response = await proxyRequest(new Request("http://app.localhost/api/events"), "http://api:5002/events");
+    await new Promise((settle) => setTimeout(settle, 60));
+
+    expect(response.status).toBe(200);
+    expect(upstreamSignal?.aborted).toBe(false);
+  });
+
+  it.each(["0", "-1", "1.5", "soon", "2147483648"])("rejects the invalid timeout %s", (value) => {
+    vi.stubEnv("BACKEND_TIMEOUT_MS", value);
+    expect(() => envMilliseconds("BACKEND_TIMEOUT_MS", 2_000)).toThrow("whole number of milliseconds");
+  });
+
+  it("uses the default timeout when the variable is unset or empty", () => {
+    vi.stubEnv("BACKEND_TIMEOUT_MS", "");
+    expect(envMilliseconds("BACKEND_TIMEOUT_MS", 2_000)).toBe(2_000);
+    vi.stubEnv("BACKEND_TIMEOUT_MS", "1500");
+    expect(envMilliseconds("BACKEND_TIMEOUT_MS", 2_000)).toBe(1_500);
+  });
+});

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

@@ -218,6 +218,135 @@ 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 long the proxy waits for response headers before it checks whether the
+ * API still answers at all.
+ */
+const DEFAULT_BACKEND_TIMEOUT_MS = 2_000;
+/**
+ * Milliseconds the proxy waits for the API's response headers, matching the
+ * API's default idle timeout. 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();
+
+// 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, or
+// when the proxy waits longer than that for response headers, so one slow
+// endpoint does not fail every request in the process. 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;
+}
+
+/** 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 +381,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 +400,42 @@ 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 check, 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 deadline = setTimeout(
+    () => waiting.abort(new DOMException("The API did not respond in time", "TimeoutError")),
+    backendProxyTimeoutMs(),
+  );
+  const healthCheck = setTimeout(() => void checkBackend(), 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);
+    clearTimeout(healthCheck);
+    outage.removeEventListener("abort", failOnOutage);
+  }
+  reportBackendAnswer();
 
   const responseHeaders = new Headers();
   for (const name of relayedResponseHeaders) {

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,10 @@ POSTGRES_USER=podokit
 POSTGRES_PASSWORD=podokit
 POSTGRES_DB=podokit
 BACKEND_INTERNAL_URL=http://api:5002
+# 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

@@ -35,6 +35,13 @@ 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
+# the API's apiServerOptions.idleTimeout.
+# 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