@podosoft/podokit 1.4.1 → 1.4.2

package/dist/deploy-compose-render.js

@@ -311,7 +311,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-render.js

@@ -386,8 +386,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 +401,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/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;
@@ -168,7 +169,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 +189,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 +209,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/templates/fullstack/AGENTS.md

@@ -50,6 +50,18 @@ Merge added module settings from `.env.example` into an existing `.env`.
   `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.
+- 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. Raising
+  the API's `apiServerOptions.idleTimeout` needs a matching
+  `BACKEND_PROXY_TIMEOUT_MS`.
+- `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

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/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

@@ -13,5 +13,7 @@ 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: ... }).
+// environment instead: (env) => ({ maxRequestBodySize: ... }). A longer
+// idleTimeout also needs BACKEND_PROXY_TIMEOUT_MS on the web server, which stops
+// waiting for response headers after 30 seconds by default.
 export const apiServerOptions: ApiServerOptionsSource = {};

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

@@ -1,8 +1,10 @@
 import { SQL } from "bun";
 import { describe, expect, it } from "bun:test";
 import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { connect, createServer, type AddressInfo } from "node:net";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import { QueryFailedError } from "typeorm";
 import { validateEnv } from "../config/env.validation";
 import { PROVIDERS } from "../config/providers";
 import {
@@ -199,6 +201,45 @@ describe("isDatabaseUnavailable", () => {
     expect(isDatabaseUnavailable(new Error("Failed to save", { cause: socket("ECONNREFUSED") }))).toBe(true);
   });
 
+  it("recognizes host lookup failures from Bun and Node", () => {
+    // Bun reports an unknown host as ENOTFOUND and a lookup timeout as ETIMEOUT;
+    // Node reports a lookup it could not complete as EAI_AGAIN.
+    for (const code of ["ENOTFOUND", "ETIMEOUT", "EAI_AGAIN"]) {
+      expect(isDatabaseUnavailable(Object.assign(new Error(`getaddrinfo ${code} db`), { code }))).toBe(true);
+    }
+  });
+
+  it("recognizes a pg client that was ended or broke while a query waited", () => {
+    for (const message of [
+      "Connection terminated",
+      "Client was closed and is not queryable",
+      "Client has encountered a connection error and is not queryable",
+    ]) {
+      expect(isDatabaseUnavailable(new Error(message))).toBe(true);
+    }
+  });
+
+  it("follows the per-address errors of a connection that tried several addresses", () => {
+    const refused = (address: string): Error =>
+      Object.assign(new Error(`connect ECONNREFUSED ${address}:5432`), { code: "ECONNREFUSED" });
+    expect(isDatabaseUnavailable(new AggregateError([refused("::1"), refused("127.0.0.1")]))).toBe(true);
+    expect(isDatabaseUnavailable(new AggregateError([new Error("first"), new Error("second")]))).toBe(false);
+  });
+
+  it("follows the driver error that TypeORM wraps", () => {
+    const failed = (driverError: Error): QueryFailedError => new QueryFailedError("SELECT 1", [], driverError);
+    expect(isDatabaseUnavailable(failed(new Error("Connection terminated")))).toBe(true);
+    const refused = Object.assign(new Error("connect ECONNREFUSED 127.0.0.1:5432"), { code: "ECONNREFUSED" });
+    expect(isDatabaseUnavailable(failed(new AggregateError([refused])))).toBe(true);
+    expect(isDatabaseUnavailable(failed(Object.assign(new Error("duplicate key"), { code: "23505" })))).toBe(false);
+  });
+
+  it("stops at an error that wraps itself", () => {
+    const loop = new Error("outer");
+    loop.cause = new Error("inner", { cause: loop });
+    expect(isDatabaseUnavailable(loop)).toBe(false);
+  });
+
   it("leaves query and application errors alone", () => {
     expect(isDatabaseUnavailable(new SQL.PostgresError("syntax error", { code: "ERR_POSTGRES_SYNTAX_ERROR" })))
       .toBe(false);
@@ -212,6 +253,31 @@ describe("isDatabaseUnavailable", () => {
     expect(isDatabaseUnavailable(undefined)).toBe(false);
   });
 
+  it("recognizes a real lookup of a host that does not exist", async () => {
+    // .invalid never resolves (RFC 2606). A resolver that does not answer at all
+    // fails with ETIMEOUT after about 16 seconds, which is recognized too.
+    const error: unknown = await fetch("http://database.invalid/").then(() => undefined, (reason: unknown) => reason);
+    expect(isDatabaseUnavailable(error)).toBe(true);
+  }, 30_000);
+
+  it("recognizes a real refused connection to localhost", async () => {
+    const server = createServer();
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const { port } = server.address() as AddressInfo;
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    // localhost may resolve to ::1 and 127.0.0.1; a client that tries both fails
+    // with an AggregateError of the two refusals.
+    const error = await new Promise<unknown>((resolve) => {
+      const socket = connect({ host: "localhost", port });
+      socket.once("connect", () => {
+        socket.destroy();
+        resolve(undefined);
+      });
+      socket.once("error", resolve);
+    });
+    expect(isDatabaseUnavailable(error)).toBe(true);
+  });
+
   it("recognizes a real Bun SQL connection timeout", async () => {
     // Accepts the TCP connection and never answers, like an overloaded server.
     const server = Bun.listen({ hostname: "127.0.0.1", port: 0, socket: { data() {} } });

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

@@ -76,9 +76,14 @@ const UNAVAILABLE_PG_MESSAGES = new Set([
   "timeout exceeded when trying to connect",
   "Connection terminated due to connection timeout",
   "Connection terminated unexpectedly",
+  // The client was ended, for example by a pool replacement, while a query waited.
+  "Connection terminated",
+  "Client was closed and is not queryable",
+  "Client has encountered a connection error and is not queryable",
   "Query read timeout",
 ]);
-// Socket errors from a pg client whose server is gone or unreachable.
+// Socket and host lookup errors from a pg client whose server is gone or
+// unreachable. Bun reports a lookup timeout as ETIMEOUT, Node as EAI_AGAIN.
 const UNAVAILABLE_SOCKET_CODES = new Set([
   "ECONNREFUSED",
   "ECONNRESET",
@@ -86,6 +91,9 @@ const UNAVAILABLE_SOCKET_CODES = new Set([
   "EHOSTUNREACH",
   "ENETUNREACH",
   "EPIPE",
+  "ENOTFOUND",
+  "ETIMEOUT",
+  "EAI_AGAIN",
 ]);
 // SQLSTATEs for a server shutting down or refusing connections (class 57P) and
 // for broken connections (class 08); pg reports them as `code`, Bun SQL as `errno`.
@@ -95,18 +103,33 @@ function unavailableSqlState(value: unknown): boolean {
   return typeof value === "string" && (UNAVAILABLE_SQLSTATES.has(value) || /^08[0-9A-Z]{3}$/.test(value));
 }
 
+function signalsUnavailable(error: Error): boolean {
+  if (error instanceof SQL.PostgresError) {
+    if (UNAVAILABLE_SQL_CODES.has(error.code) || unavailableSqlState(error.errno)) return true;
+  } else {
+    const code = (error as { code?: unknown }).code;
+    if (typeof code === "string" && (UNAVAILABLE_SOCKET_CODES.has(code) || unavailableSqlState(code))) return true;
+  }
+  return UNAVAILABLE_PG_MESSAGES.has(error.message);
+}
+
+// Bounds the walk over wrapped errors, which may form a cycle.
+const MAX_WRAPPED_ERRORS = 16;
+
 /** Whether an error, or one it wraps, means the database is unavailable rather than the request being wrong. */
 export function isDatabaseUnavailable(error: unknown): boolean {
-  let current: unknown = error;
-  for (let depth = 0; depth < 5 && current instanceof Error; depth += 1) {
-    if (current instanceof SQL.PostgresError) {
-      if (UNAVAILABLE_SQL_CODES.has(current.code) || unavailableSqlState(current.errno)) return true;
-    } else {
-      const code = (current as { code?: unknown }).code;
-      if (typeof code === "string" && (UNAVAILABLE_SOCKET_CODES.has(code) || unavailableSqlState(code))) return true;
-    }
-    if (UNAVAILABLE_PG_MESSAGES.has(current.message)) return true;
-    current = current.cause;
+  const pending: unknown[] = [error];
+  const seen = new Set<Error>();
+  while (pending.length > 0 && seen.size < MAX_WRAPPED_ERRORS) {
+    const current = pending.shift();
+    if (!(current instanceof Error) || seen.has(current)) continue;
+    seen.add(current);
+    if (signalsUnavailable(current)) return true;
+    // TypeORM's QueryFailedError keeps the driver's error as `driverError`, and
+    // a connection that tried several addresses, such as IPv6 and IPv4 for
+    // localhost, fails with an AggregateError of the per-address errors.
+    pending.push(current.cause, (current as { driverError?: unknown }).driverError);
+    if (current instanceof AggregateError) pending.push(...current.errors);
   }
   return false;
 }

package/dist/templates/fullstack/apps/api/src/database/run-migrations.spec.ts

@@ -11,18 +11,29 @@ interface Launch {
   stderr: string;
 }
 
+interface LaunchOptions {
+  /** Starts the launcher from the directory above the API, like a repository root. */
+  fromParent?: boolean;
+  files?: Record<string, string>;
+}
+
 /** Runs the migrate:all launcher in an API layout whose entries print their own path. */
-async function launch(entries: string[], nodeEnv: string, body = ""): Promise<Launch> {
-  const root = mkdtempSync(join(tmpdir(), "run-migrations-"));
+async function launch(entries: string[], nodeEnv: string, body = "", options: LaunchOptions = {}): Promise<Launch> {
+  const parent = mkdtempSync(join(tmpdir(), "run-migrations-"));
+  const root = join(parent, "api");
   try {
-    mkdirSync(join(root, "scripts"));
+    mkdirSync(join(root, "scripts"), { recursive: true });
     cpSync(LAUNCHER, join(root, "scripts/run-migrations.mjs"));
     for (const entry of entries) {
       mkdirSync(dirname(join(root, entry)), { recursive: true });
       writeFileSync(join(root, entry), `console.log(${JSON.stringify(entry)});\n${body}`);
     }
-    const child = Bun.spawn([process.execPath, "scripts/run-migrations.mjs"], {
-      cwd: root,
+    for (const [path, content] of Object.entries(options.files ?? {})) {
+      mkdirSync(dirname(join(root, path)), { recursive: true });
+      writeFileSync(join(root, path), content);
+    }
+    const child = Bun.spawn([process.execPath, options.fromParent ? "api/scripts/run-migrations.mjs" : "scripts/run-migrations.mjs"], {
+      cwd: options.fromParent ? parent : root,
       env: { ...process.env, NODE_ENV: nodeEnv },
       stdout: "pipe",
       stderr: "pipe",
@@ -34,7 +45,7 @@ async function launch(entries: string[], nodeEnv: string, body = ""): Promise<La
     ]);
     return { code, stdout: stdout.trim(), stderr };
   } finally {
-    rmSync(root, { recursive: true, force: true });
+    rmSync(parent, { recursive: true, force: true });
   }
 }
 
@@ -62,6 +73,43 @@ describe("migrate:all launcher", () => {
     expect(result.code).toBe(3);
   });
 
+  it("runs the migration in the API directory when started from elsewhere", async () => {
+    const apiRoot = 'realpathSync(join(import.meta.dir, "../.."))';
+    const result = await launch(
+      ["src/database/migrate.ts"],
+      "development",
+      `import { realpathSync } from "node:fs";\nimport { join } from "node:path";\n` +
+        `console.log(realpathSync(process.cwd()) === ${apiRoot});\n`,
+      { fromParent: true },
+    );
+    expect(result).toMatchObject({ code: 0, stdout: "src/database/migrate.ts\ntrue" });
+  });
+
+  it("applies the API's decorator settings when started from elsewhere", async () => {
+    // TypeORM entities need legacy decorators, which Bun takes from the
+    // tsconfig.json of the working directory rather than of the source file.
+    const result = await launch(
+      ["src/database/migrate.ts"],
+      "development",
+      'await import("../entity.ts");\n',
+      {
+        fromParent: true,
+        files: {
+          "tsconfig.json": JSON.stringify({ compilerOptions: { experimentalDecorators: true, emitDecoratorMetadata: true } }),
+          "src/entity.ts": [
+            "const Column = (): PropertyDecorator => (target) => console.log(typeof target);",
+            "export class Item {",
+            "  @Column()",
+            "  name!: string;",
+            "}",
+            "",
+          ].join("\n"),
+        },
+      },
+    );
+    expect(result).toMatchObject({ code: 0, stdout: "src/database/migrate.ts\nobject" });
+  });
+
   it("fails when no migration entry exists", async () => {
     const result = await launch([], "development");
     expect(result.code).toBe(1);

package/dist/templates/fullstack/apps/web/Dockerfile

@@ -37,5 +37,5 @@ WORKDIR /app/apps/web
 USER bun
 EXPOSE 3000
 HEALTHCHECK --interval=10s --timeout=5s --start-period=30s --retries=6 \
-  CMD bun -e "fetch('http://127.0.0.1:' + (process.env.PORT ?? '3000') + '/').then((r) => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
+  CMD bun -e "fetch('http://127.0.0.1:' + (process.env.PORT ?? '3000') + '/healthz').then((r) => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
 CMD ["bun", "./build"]

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