@podosoft/podokit 1.4.1 → 1.5.0

package/dist/templates/fullstack/apps/api/src/core/client-address.spec.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "bun:test";
+import { validateEnv } from "../config/env.validation";
+import {
+  CLIENT_ADDRESS_HEADER,
+  clientAddressOf,
+  resolveClientAddress,
+  stampClientAddress,
+} from "./client-address";
+
+const forwarded = (value: string): Headers => new Headers({ "x-forwarded-for": value });
+const config = (trustedProxyHops: number) => ({ trustedProxyHops, header: "x-forwarded-for" });
+
+describe("resolveClientAddress", () => {
+  it("uses the socket peer and ignores a caller's header without trusted proxies", () => {
+    expect(resolveClientAddress(forwarded("198.51.100.66"), "10.0.0.9", config(0))).toBe("10.0.0.9");
+    expect(resolveClientAddress(forwarded("198.51.100.66"), "::ffff:10.0.0.9", config(0))).toBe("10.0.0.9");
+    expect(resolveClientAddress(new Headers(), undefined, config(0))).toBeUndefined();
+  });
+
+  it("takes the entry the trusted proxies appended, never one further left", () => {
+    // A caller sent "198.51.100.66"; the one trusted proxy appended the real client.
+    const chain = forwarded("198.51.100.66, 203.0.113.7");
+    expect(resolveClientAddress(chain, "10.0.0.9", config(1))).toBe("203.0.113.7");
+    expect(resolveClientAddress(chain, "10.0.0.9", config(2))).toBe("198.51.100.66");
+    expect(resolveClientAddress(forwarded("203.0.113.7"), "10.0.0.9", config(1))).toBe("203.0.113.7");
+    expect(
+      resolveClientAddress(new Headers({ "x-real-ip": "203.0.113.8" }), "10.0.0.9", {
+        trustedProxyHops: 1,
+        header: "x-real-ip",
+      }),
+    ).toBe("203.0.113.8");
+  });
+
+  it("falls back to the peer for a short or malformed chain", () => {
+    expect(resolveClientAddress(new Headers(), "10.0.0.9", config(1))).toBe("10.0.0.9");
+    expect(resolveClientAddress(forwarded("203.0.113.7"), "10.0.0.9", config(2))).toBe("10.0.0.9");
+    expect(resolveClientAddress(forwarded("attacker-controlled"), "10.0.0.9", config(1))).toBe("10.0.0.9");
+    expect(resolveClientAddress(forwarded("203.0.113.7, not-an-ip"), "10.0.0.9", config(1))).toBe("10.0.0.9");
+  });
+
+  it("reads the address the API set", () => {
+    expect(clientAddressOf(new Headers({ [CLIENT_ADDRESS_HEADER]: "203.0.113.7" }))).toBe("203.0.113.7");
+    expect(clientAddressOf(new Headers())).toBeUndefined();
+    expect(clientAddressOf(undefined)).toBeUndefined();
+  });
+});
+
+describe("client address settings", () => {
+  it("validates the trusted proxy settings and refuses the rate limiter's former names", () => {
+    expect(validateEnv({})).toMatchObject({ TRUSTED_PROXY_HOPS: 0, TRUSTED_PROXY_HEADER: "x-forwarded-for" });
+    expect(validateEnv({ TRUSTED_PROXY_HOPS: "1", TRUSTED_PROXY_HEADER: "X-Real-IP" }))
+      .toMatchObject({ TRUSTED_PROXY_HOPS: 1, TRUSTED_PROXY_HEADER: "x-real-ip" });
+    expect(() => validateEnv({ TRUSTED_PROXY_HOPS: "-1" })).toThrow("TRUSTED_PROXY_HOPS");
+    expect(() => validateEnv({ TRUSTED_PROXY_HEADER: "bad header" })).toThrow("TRUSTED_PROXY_HEADER");
+    expect(() => validateEnv({ RATE_LIMIT_TRUSTED_PROXY_HOPS: "1" }))
+      .toThrow("RATE_LIMIT_TRUSTED_PROXY_HOPS was renamed to TRUSTED_PROXY_HOPS");
+    expect(() => validateEnv({ RATE_LIMIT_PROXY_HEADER: "x-forwarded-for" }))
+      .toThrow("RATE_LIMIT_PROXY_HEADER was renamed to TRUSTED_PROXY_HEADER");
+  });
+});
+
+describe("stampClientAddress", () => {
+  const request = (headers: Record<string, string>): Request => new Request("http://localhost/x", { headers });
+
+  it("replaces a caller's own address header and ignores its forwarded header without trusted proxies", () => {
+    const spoofed = request({ "x-forwarded-for": "198.51.100.66", [CLIENT_ADDRESS_HEADER]: "198.51.100.67" });
+    expect(stampClientAddress(spoofed, "::ffff:127.0.0.1", config(0))).toBe("127.0.0.1");
+    expect(clientAddressOf(spoofed.headers)).toBe("127.0.0.1");
+  });
+
+  it("records the rightmost forwarded entry behind one trusted proxy", () => {
+    const proxied = request({ "x-forwarded-for": "198.51.100.66, 203.0.113.7" });
+    expect(stampClientAddress(proxied, "10.0.0.9", config(1))).toBe("203.0.113.7");
+    expect(clientAddressOf(proxied.headers)).toBe("203.0.113.7");
+  });
+
+  it("removes a caller's value when no address can be resolved", () => {
+    const unknown = request({ [CLIENT_ADDRESS_HEADER]: "198.51.100.67" });
+    expect(stampClientAddress(unknown, undefined, config(0))).toBeUndefined();
+    expect(clientAddressOf(unknown.headers)).toBeUndefined();
+  });
+});

package/dist/templates/fullstack/apps/api/src/core/client-address.ts

@@ -0,0 +1,68 @@
+import { isIP } from "node:net";
+
+/**
+ * The request header that carries the client address the API resolved. The API
+ * sets it on every request before any handler runs, replacing whatever a caller
+ * sent, so Better Auth, audit entries, and application code read one address
+ * that a caller cannot choose.
+ */
+export const CLIENT_ADDRESS_HEADER = "x-podokit-client-address";
+
+export interface ClientAddressConfig {
+  /** Reverse proxies in front of the API whose forwarded header is trusted; 0 trusts none. */
+  trustedProxyHops: number;
+  /** The lowercase header those proxies append the client address to. */
+  header: string;
+}
+
+/** An IP address without its IPv4-mapped IPv6 prefix, or undefined when the value is not one. */
+export function normalizeIp(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  const normalized = trimmed.startsWith("::ffff:") ? trimmed.slice("::ffff:".length) : trimmed;
+  return isIP(normalized) === 0 ? undefined : normalized;
+}
+
+/**
+ * The caller's address. With no trusted proxy it is the socket peer. Otherwise
+ * each trusted proxy appended one entry to the header, so the client is the
+ * entry that many places left of the peer; entries further left were written
+ * by the caller and are ignored. A chain shorter than the trusted hops, or a
+ * malformed entry, falls back to the peer instead of trusting caller input.
+ */
+export function resolveClientAddress(
+  headers: Headers,
+  remoteAddress: string | undefined,
+  config: ClientAddressConfig,
+): string | undefined {
+  const direct = normalizeIp(remoteAddress);
+  if (config.trustedProxyHops === 0) return direct;
+  const forwarded = headers.get(config.header)
+    ?.split(",")
+    .map((value) => value.trim())
+    .filter(Boolean) ?? [];
+  const chain = [...forwarded, direct ?? ""];
+  if (chain.length <= config.trustedProxyHops) return direct;
+  return normalizeIp(chain[chain.length - config.trustedProxyHops - 1]) ?? direct;
+}
+
+/**
+ * Resolves a request's client address and records it in CLIENT_ADDRESS_HEADER,
+ * replacing any value the caller sent. The API does this for every request
+ * before a guard, Better Auth, or a handler reads the request.
+ */
+export function stampClientAddress(
+  request: Request,
+  remoteAddress: string | undefined,
+  config: ClientAddressConfig,
+): string | undefined {
+  const address = resolveClientAddress(request.headers, remoteAddress, config);
+  if (address) request.headers.set(CLIENT_ADDRESS_HEADER, address);
+  else request.headers.delete(CLIENT_ADDRESS_HEADER);
+  return address;
+}
+
+/** The address the API resolved for a request, as set in CLIENT_ADDRESS_HEADER. */
+export function clientAddressOf(headers: Headers | undefined): string | undefined {
+  return headers?.get(CLIENT_ADDRESS_HEADER) ?? undefined;
+}

package/dist/templates/fullstack/apps/api/src/core/services.ts

@@ -280,7 +280,10 @@ export class AccessPolicy {
 
 export interface RequestGuardContext {
   request: Request;
+  /** The socket peer. */
   remoteAddress?: string;
+  /** The caller's address behind the trusted proxies; see core/client-address.ts. */
+  clientAddress?: string;
   setHeader: (name: string, value: string) => void;
 }
 
@@ -305,6 +308,31 @@ export interface RequestIdentity {
   activeOrganizationId(request: Request): Promise<string | undefined>;
 }
 
+/** A session the API resolved while handling a request. */
+export interface ResolvedSession {
+  /** The session token without its cookie signature. */
+  token: string;
+  userId: string;
+  expiresAt: Date;
+}
+
+/**
+ * Passes each session the API resolves for a request to the modules that listen,
+ * so they can use it without a session lookup of their own. The auth module
+ * reports; the rate limiter listens to count a signed-in caller per user.
+ */
+export class ResolvedSessions {
+  private readonly listeners: Array<(session: ResolvedSession) => void> = [];
+
+  listen(listener: (session: ResolvedSession) => void): void {
+    this.listeners.push(listener);
+  }
+
+  report(session: ResolvedSession): void {
+    for (const listener of this.listeners) listener(session);
+  }
+}
+
 export interface OpenApiContribution {
   document: Record<string, unknown>;
   pathPrefix?: string;
@@ -331,6 +359,7 @@ export const LOGGER = Symbol("logger") as ServiceKey<Logger>;
 export const ACCESS_POLICY = Symbol("access-policy") as ServiceKey<AccessPolicy>;
 export const REQUEST_GUARDS = Symbol("request-guards") as ServiceKey<RequestGuardRegistry>;
 export const REQUEST_IDENTITY = Symbol("request-identity") as ServiceKey<RequestIdentity>;
+export const RESOLVED_SESSIONS = Symbol("resolved-sessions") as ServiceKey<ResolvedSessions>;
 export const OPENAPI = Symbol("openapi") as ServiceKey<OpenApiRegistry>;
 
 export interface AppContext {
@@ -390,6 +419,7 @@ export function createCoreServices(env: AppEnv): ServiceRegistry {
     roles: async () => [],
     activeOrganizationId: async () => undefined,
   });
+  services.register(RESOLVED_SESSIONS, new ResolvedSessions());
   services.register(OPENAPI, openapiRegistry);
   return services;
 }

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

@@ -32,10 +32,14 @@ FROM oven/bun:1.4.0-alpine AS runtime
 WORKDIR /app
 ENV NODE_ENV=production
 ENV BODY_SIZE_LIMIT=3M
+# Seconds a connection may stay silent, such as while the /api proxy waits for the
+# API: more than 4 above BACKEND_PROXY_TIMEOUT_MS (30 s), since Bun closes idle
+# connections on a 4-second tick.
+ENV CONNECTION_IDLE_TIMEOUT=35
 COPY --from=build /app/apps/web/build ./apps/web/build
 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 },
   );