@podosoft/podokit 1.1.6 → 1.3.0

package/dist/templates/modules/admin-dashboard/files/apps/api/src/site-assets/site-assets.routes.spec.ts

@@ -0,0 +1,167 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AppException } from "@podosoft/podokit-contracts";
+import { LocalObjectStore, type ObjectData } from "@podosoft/podokit-runtime";
+import { Elysia } from "elysia";
+import type { Logger } from "pino";
+import { ProfileImageService } from "../profile-image/profile-image.service";
+import type { SiteFavicon } from "../site-settings/site-settings.service";
+import { faviconCacheControl, IMMUTABLE_CACHE_CONTROL, siteAssetRoutes } from "./site-assets.routes";
+
+const PNG = Buffer.from(
+  "iVBORw0KGgoAAAANSUhEUgAAAAIAAAADAQMAAACDJEzCAAAAIGNIUk0AAHomAACAhAAA+gAAAIDoAAB1MAAA6mAAADqYAAAXcJy6UTwAAAAGUExURWYzmf///129H+IAAAABYktHRAH/Ai3eAAAAB3RJTUUH6gcVCSUTzXBDTwAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAyNi0wNy0yMVQwOTozNzoxOSswMDowMOuehLIAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMjYtMDctMjFUMDk6Mzc6MTkrMDA6MDCawzwOAAAAKHRFWHRkYXRlOnRpbWVzdGFtcAAyMDI2LTA3LTIxVDA5OjM3OjE5KzAwOjAwzdYd0QAAAAtJREFUCNdjYAABAAAGAAFm9MlsAAAAAElFTkSuQmCC",
+  "base64",
+);
+
+const directories: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(directories.splice(0).map((path) => rm(path, { recursive: true, force: true })));
+});
+
+async function localStore(): Promise<LocalObjectStore> {
+  const directory = await mkdtemp(join(tmpdir(), "podokit-site-assets-"));
+  directories.push(directory);
+  return new LocalObjectStore({ rootDirectory: directory });
+}
+
+interface TrackedObject {
+  object: ObjectData;
+  read: () => boolean;
+}
+
+function trackedObject(content: string): TrackedObject {
+  let read = false;
+  const bytes = Buffer.from(content);
+  return {
+    object: {
+      key: "site/favicon",
+      size: bytes.byteLength,
+      contentType: "application/octet-stream",
+      etag: "\"favicon-1\"",
+      lastModified: new Date("2026-01-02T03:04:05Z"),
+      body: new ReadableStream<Uint8Array>({
+        pull(controller): void {
+          read = true;
+          controller.enqueue(bytes);
+          controller.close();
+        },
+      }, { highWaterMark: 0 }),
+    },
+    read: () => read,
+  };
+}
+
+type Get = (path: string, headers?: Record<string, string>) => Promise<Response>;
+
+function app(
+  favicon: () => SiteFavicon | null,
+  profileImages: Pick<ProfileImageService, "get">,
+): Get {
+  const target = new Elysia()
+    .onError(({ error, set }) => {
+      if (!(error instanceof AppException)) return undefined;
+      set.status = error.statusCode;
+      return { code: error.code };
+    })
+    .use(siteAssetRoutes({ getFavicon: async () => favicon() }, profileImages));
+  return async (path, headers = {}) => target.handle(new Request(`http://localhost${path}`, { headers }));
+}
+
+const noProfileImages: Pick<ProfileImageService, "get"> = {
+  get: () => Promise.reject(new Error("unused")),
+};
+
+describe("GET /site/favicon", () => {
+  test("streams the favicon with the validated type and its validators", async () => {
+    const icon = trackedObject("<svg/>");
+    const get = app(() => ({ object: icon.object, contentType: "image/svg+xml", version: "1700" }), noProfileImages);
+    const response = await get("/site/favicon");
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("content-type")).toBe("image/svg+xml");
+    expect(response.headers.get("content-length")).toBe("6");
+    expect(response.headers.get("etag")).toBe("\"favicon-1\"");
+    expect(response.headers.get("last-modified")).toBe("Fri, 02 Jan 2026 03:04:05 GMT");
+    expect(await response.text()).toBe("<svg/>");
+  });
+
+  test("answers a current copy with 304 without reading storage", async () => {
+    const icon = trackedObject("<svg/>");
+    const get = app(() => ({ object: icon.object, contentType: "image/svg+xml", version: "1700" }), noProfileImages);
+    const response = await get("/site/favicon", { "if-none-match": "\"favicon-1\"" });
+
+    expect(response.status).toBe(304);
+    expect(await response.text()).toBe("");
+    expect(icon.read()).toBe(false);
+  });
+
+  test("caches the current version for good and revalidates any other URL", async () => {
+    const get = (path: string, headers: Record<string, string> = {}): Promise<Response> => {
+      const icon = trackedObject("<svg/>");
+      return app(() => ({ object: icon.object, contentType: "image/svg+xml", version: "1700" }), noProfileImages)(
+        path,
+        headers,
+      );
+    };
+
+    const current = await get("/site/favicon?v=1700");
+    expect(current.status).toBe(200);
+    expect(current.headers.get("cache-control")).toBe(IMMUTABLE_CACHE_CONTROL);
+
+    for (const path of ["/site/favicon?v=1600", "/site/favicon?v=", "/site/favicon"]) {
+      const response = await get(path);
+      expect(response.status, path).toBe(200);
+      expect(response.headers.get("cache-control"), path).toBe("no-cache");
+      expect(response.headers.get("etag"), path).toBe("\"favicon-1\"");
+    }
+
+    const revalidated = await get("/site/favicon?v=1600", { "if-none-match": "\"favicon-1\"" });
+    expect(revalidated.status).toBe(304);
+    expect(revalidated.headers.get("cache-control")).toBe("no-cache");
+    expect(faviconCacheControl(null, "")).toBe("no-cache");
+  });
+
+  test("returns 404 when no favicon is set", async () => {
+    const response = await app(() => null, noProfileImages)("/site/favicon");
+    expect(response.status).toBe(404);
+    expect(await response.json()).toEqual({ code: "FAVICON_NOT_FOUND" });
+  });
+});
+
+describe("GET /profile-images/:fileName", () => {
+  test("streams exactly the uploaded bytes as an immutable resource", async () => {
+    const store = await localStore();
+    const logger = { warn: mock(() => undefined) } as unknown as Logger;
+    const images = new ProfileImageService(store, logger, async () => undefined);
+    const { image } = await images.upload(null, { buffer: PNG, mimetype: "image/png", size: PNG.byteLength }, new Headers());
+    const path = image?.replace(/^\/api/, "") ?? "";
+    const get = app(() => null, images);
+
+    const response = await get(path);
+    expect(response.status).toBe(200);
+    expect(response.headers.get("content-type")).toBe("image/png");
+    expect(response.headers.get("cache-control")).toBe(IMMUTABLE_CACHE_CONTROL);
+    expect(response.headers.get("content-length")).toBe(String(PNG.byteLength));
+    expect(Buffer.from(await response.arrayBuffer()).equals(PNG)).toBe(true);
+
+    const revalidated = await get(path, { "if-none-match": response.headers.get("etag") ?? "" });
+    expect(revalidated.status).toBe(304);
+    expect(revalidated.headers.get("cache-control")).toBe(IMMUTABLE_CACHE_CONTROL);
+
+    await images.remove(image ?? null, new Headers());
+    expect((await get(path)).status).toBe(404);
+  });
+
+  test("returns 404 for names that are not managed images", async () => {
+    const store = await localStore();
+    const logger = { warn: mock(() => undefined) } as unknown as Logger;
+    const get = app(() => null, new ProfileImageService(store, logger, async () => undefined));
+
+    for (const name of ["missing.png", "123e4567-e89b-42d3-a456-426614174000.png", "..%2Fsite%2Ffavicon"]) {
+      expect((await get(`/profile-images/${name}`)).status).toBe(404);
+    }
+  });
+});

package/dist/templates/modules/admin-dashboard/files/apps/api/src/site-assets/site-assets.routes.ts

@@ -0,0 +1,50 @@
+import { AppException } from "@podosoft/podokit-contracts";
+import { objectResponse } from "@podosoft/podokit-runtime";
+import { Elysia, t } from "elysia";
+import type { ElysiaPlugin } from "../core/services";
+import type { ProfileImageService } from "../profile-image/profile-image.service";
+import type { SiteSettingsService } from "../site-settings/site-settings.service";
+
+export const IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
+
+/**
+ * Pages link the favicon as `?v=<version>`, and a new upload changes the
+ * version, so that URL can be cached for good. Any other URL revalidates.
+ */
+export function faviconCacheControl(current: string | null, requested: string | undefined): string {
+  return current !== null && requested === current ? IMMUTABLE_CACHE_CONTROL : "no-cache";
+}
+
+/** Public images streamed from object storage with validators for 304 replies. */
+export function siteAssetRoutes(
+  site: Pick<SiteSettingsService, "getFavicon">,
+  profileImages: Pick<ProfileImageService, "get">,
+): ElysiaPlugin {
+  return new Elysia({ name: "podokit.admin.site-assets" })
+    .get("/site/favicon", async ({ request, query }) => {
+      const icon = await site.getFavicon();
+      if (!icon) throw new AppException("FAVICON_NOT_FOUND", "No favicon set", 404);
+      return objectResponse(request, icon.object, {
+        contentType: icon.contentType,
+        cacheControl: faviconCacheControl(icon.version, query.v),
+      });
+    }, {
+      query: t.Object({ v: t.Optional(t.String()) }),
+      detail: {
+        tags: ["site"],
+        summary: "Get the site favicon",
+        description: "Cached permanently when `v` is the current `faviconVersion`; revalidated otherwise.",
+      },
+    })
+    .get("/profile-images/:fileName", async ({ request, params }) => {
+      const image = await profileImages.get(params.fileName);
+      // Every upload gets a new random file name, so a name never changes content.
+      return objectResponse(request, image.object, {
+        contentType: image.contentType,
+        cacheControl: IMMUTABLE_CACHE_CONTROL,
+      });
+    }, {
+      params: t.Object({ fileName: t.String({ minLength: 1 }) }),
+      detail: { tags: ["account"], summary: "Get a public profile image" },
+    });
+}

package/dist/templates/modules/admin-dashboard/files/apps/api/src/site-settings/site-settings.service.spec.ts

@@ -0,0 +1,158 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { SQL } from "bun";
+import type { ObjectData, ObjectStore } from "@podosoft/podokit-runtime";
+import { SiteSettingsService } from "./site-settings.service";
+
+const favicon: ObjectData = {
+  key: "site/favicon",
+  size: 1,
+  etag: "\"icon\"",
+  lastModified: new Date(0),
+  body: new ReadableStream<Uint8Array>(),
+};
+const storage = {
+  put: async (): Promise<void> => undefined,
+  get: async (key: string): Promise<ObjectData | null> => (key === "site/favicon" ? favicon : null),
+} as unknown as ObjectStore;
+
+interface Harness {
+  service: SiteSettingsService;
+  reads: () => number;
+  holdNextRead: () => () => void;
+  advance: (milliseconds: number) => void;
+  failNextWrite: () => void;
+}
+
+describe("SiteSettingsService", () => {
+  let db: SQL;
+  let harness: Harness;
+
+  beforeEach(async () => {
+    db = new SQL(":memory:");
+    await db`CREATE TABLE "app_setting" ("key" TEXT PRIMARY KEY, "value" TEXT NOT NULL, "updatedAt" TEXT)`;
+    await db`INSERT INTO "app_setting" ("key", "value") VALUES ('site.name', 'Before'), ('require2fa', 'false')`;
+
+    let reads = 0;
+    let clock = 1_000;
+    let hold: Promise<void> | null = null;
+    let failWrite = false;
+    // Counts reads and can hold a read's result to interleave it with a write.
+    const counted = async (strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown> => {
+      reads += 1;
+      const gate = hold;
+      hold = null;
+      const rows: unknown = await db(strings, ...values);
+      if (gate) await gate;
+      return rows;
+    };
+    const sql = Object.assign(counted, {
+      begin: <T>(work: (tx: SQL) => Promise<T>): Promise<T> =>
+        db.begin(async (tx) => {
+          const result = await work(tx as unknown as SQL);
+          if (failWrite) {
+            failWrite = false;
+            throw new Error("write failed");
+          }
+          return result;
+        }),
+    });
+    harness = {
+      service: new SiteSettingsService(sql as unknown as SQL, storage, () => clock),
+      reads: () => reads,
+      holdNextRead: () => {
+        let release: () => void = () => undefined;
+        hold = new Promise((resolve) => { release = resolve; });
+        return release;
+      },
+      advance: (milliseconds) => { clock += milliseconds; },
+      failNextWrite: () => { failWrite = true; },
+    };
+  });
+
+  afterEach(async () => {
+    await db.close();
+  });
+
+  test("serves concurrent and repeated reads from one query", async () => {
+    const results = await Promise.all([
+      harness.service.getAll(),
+      harness.service.getAll(),
+      harness.service.get("name"),
+      harness.service.faviconVersion(),
+    ]);
+    await harness.service.getAll();
+
+    expect(harness.reads()).toBe(1);
+    expect(results[0]).toEqual({ name: "Before" });
+    expect(results[2]).toBe("Before");
+    expect(results[3]).toBeNull();
+  });
+
+  test("reads again after the snapshot expires", async () => {
+    await harness.service.getAll();
+    harness.advance(2_999);
+    await harness.service.getAll();
+    expect(harness.reads()).toBe(1);
+
+    harness.advance(1);
+    await harness.service.getAll();
+    expect(harness.reads()).toBe(2);
+  });
+
+  test("returns a write to the next read immediately", async () => {
+    await harness.service.getAll();
+
+    const saved = await harness.service.setMany({ name: "After", locale: "ko" });
+
+    expect(saved).toEqual({ name: "After", locale: "ko" });
+    expect(await harness.service.getAll()).toEqual({ name: "After", locale: "ko" });
+  });
+
+  test("writes every key in one transaction", async () => {
+    harness.failNextWrite();
+
+    await expect(harness.service.setMany({ name: "After", locale: "ko" })).rejects.toThrow("write failed");
+
+    expect(await harness.service.getAll()).toEqual({ name: "Before" });
+  });
+
+  test("does not keep a read that raced a write", async () => {
+    const release = harness.holdNextRead();
+    const stale = harness.service.getAll();
+
+    await harness.service.setMany({ name: "After" });
+    release();
+
+    expect(await stale).toEqual({ name: "Before" });
+    expect(await harness.service.getAll()).toEqual({ name: "After" });
+  });
+
+  test("derives the favicon fields from the same snapshot", async () => {
+    await harness.service.setFavicon(new Uint8Array([1]), "image/png");
+    const reads = harness.reads();
+
+    const all = await harness.service.getAll();
+
+    expect(all.faviconContentType).toBe("image/png");
+    expect(await harness.service.faviconVersion()).toBe(all.faviconUpdatedAt ?? "missing");
+    expect(harness.reads()).toBe(reads);
+  });
+
+  test("returns the favicon unread with its type and version from the snapshot", async () => {
+    expect(await harness.service.getFavicon()).toBeNull();
+    await harness.service.setFavicon(new Uint8Array([1]), "image/png");
+    const reads = harness.reads();
+    const version = await harness.service.faviconVersion();
+
+    expect(await harness.service.getFavicon()).toEqual({ object: favicon, contentType: "image/png", version });
+    expect(version).toMatch(/^\d+$/);
+    expect(harness.reads()).toBe(reads);
+  });
+
+  test("copies the snapshot for each caller", async () => {
+    const first = await harness.service.getAll();
+    first.name = "Changed";
+
+    expect(await harness.service.getAll()).toEqual({ name: "Before" });
+  });
+});

package/dist/templates/modules/admin-dashboard/files/apps/api/src/site-settings/site-settings.service.ts

@@ -27,46 +27,63 @@ interface SiteSettingRow {
 }
 
 export interface SiteFavicon {
-  body: Buffer;
+  object: ObjectData;
+  /** The type validated on upload. */
   contentType: string;
+  /** The `faviconUpdatedAt` setting that pages put in the favicon URL. */
+  version: string | null;
 }
 
-async function objectBuffer(object: ObjectData): Promise<Buffer> {
-  const chunks: Uint8Array[] = [];
-  for await (const chunk of object.body) chunks.push(chunk);
-  return Buffer.concat(chunks);
+// Every page render reads the site settings, so one short-lived snapshot serves
+// concurrent renders. Writes on this replica clear it immediately; another
+// replica sees the change within this window.
+const SNAPSHOT_TTL_MS = 3_000;
+
+interface Snapshot {
+  values: Record<string, string>;
+  expiresAt: number;
 }
 
 export class SiteSettingsService {
+  private snapshot: Snapshot | null = null;
+  private pending: Promise<Record<string, string>> | null = null;
+  private generation = 0;
+
   constructor(
     private readonly sql: SQL,
     private readonly storage: ObjectStore,
+    private readonly now: () => number = Date.now,
   ) {}
 
+  /** Every `site.*` setting, keyed without the prefix. */
   async getAll(): Promise<Record<string, string>> {
-    const rows = await this.sql<SiteSettingRow[]>`
-      SELECT "key", "value" FROM "app_setting" WHERE "key" LIKE 'site.%'
-    `;
-    const result: Record<string, string> = {};
-    for (const row of rows) result[row.key.slice(PREFIX.length)] = row.value;
-    return result;
+    const snapshot = this.snapshot;
+    if (snapshot && snapshot.expiresAt > this.now()) return { ...snapshot.values };
+    return { ...(await this.load()) };
   }
 
   async get(key: string): Promise<string | null> {
-    const rows = await this.sql<SiteSettingRow[]>`
-      SELECT "key", "value" FROM "app_setting" WHERE "key" = ${PREFIX + key}
-    `;
-    return rows[0]?.value ?? null;
+    return (await this.getAll())[key] ?? null;
   }
 
   async setMany(update: Record<string, string>): Promise<Record<string, string>> {
-    for (const [key, value] of Object.entries(update)) {
-      await this.sql`
-        INSERT INTO "app_setting" ("key", "value", "updatedAt")
-        VALUES (${PREFIX + key}, ${value}, CURRENT_TIMESTAMP)
-        ON CONFLICT ("key") DO UPDATE
-        SET "value" = EXCLUDED."value", "updatedAt" = CURRENT_TIMESTAMP
-      `;
+    const entries = Object.entries(update);
+    if (entries.length > 0) {
+      try {
+        await this.sql.begin(async (tx) => {
+          for (const [key, value] of entries) {
+            await tx`
+              INSERT INTO "app_setting" ("key", "value", "updatedAt")
+              VALUES (${PREFIX + key}, ${value}, CURRENT_TIMESTAMP)
+              ON CONFLICT ("key") DO UPDATE
+              SET "value" = EXCLUDED."value", "updatedAt" = CURRENT_TIMESTAMP
+            `;
+          }
+        });
+      } finally {
+        // Also after a failure: the outcome of an interrupted commit is unknown.
+        this.invalidate();
+      }
     }
     return this.getAll();
   }
@@ -79,17 +96,50 @@ export class SiteSettingsService {
     });
   }
 
+  /** The favicon with its content unread, or null when none is set. */
   async getFavicon(): Promise<SiteFavicon | null> {
-    const contentType = await this.get("faviconContentType");
+    const settings = await this.getAll();
+    const contentType = settings.faviconContentType;
     if (!contentType) return null;
-    try {
-      return { body: await objectBuffer(await this.storage.get(FAVICON_KEY)), contentType };
-    } catch {
-      return null;
-    }
+    const object = await this.storage.get(FAVICON_KEY);
+    return object ? { object, contentType, version: settings.faviconUpdatedAt ?? null } : null;
   }
 
   faviconVersion(): Promise<string | null> {
     return this.get("faviconUpdatedAt");
   }
+
+  /** One query at a time; concurrent readers share it. */
+  private load(): Promise<Record<string, string>> {
+    if (this.pending) return this.pending;
+    const generation = this.generation;
+    const pending = this.query()
+      .then((values) => {
+        // A write that finished meanwhile may not be in these rows.
+        if (generation === this.generation) {
+          this.snapshot = { values, expiresAt: this.now() + SNAPSHOT_TTL_MS };
+        }
+        return values;
+      })
+      .finally(() => {
+        if (this.pending === pending) this.pending = null;
+      });
+    this.pending = pending;
+    return pending;
+  }
+
+  private invalidate(): void {
+    this.generation += 1;
+    this.snapshot = null;
+    this.pending = null;
+  }
+
+  private async query(): Promise<Record<string, string>> {
+    const rows = await this.sql<SiteSettingRow[]>`
+      SELECT "key", "value" FROM "app_setting" WHERE "key" LIKE 'site.%'
+    `;
+    const result: Record<string, string> = {};
+    for (const row of rows) result[row.key.slice(PREFIX.length)] = row.value;
+    return result;
+  }
 }

package/dist/templates/modules/admin-dashboard/files/apps/web/src/app.d.ts

@@ -1,3 +1,4 @@
+import type { Capabilities } from "@podosoft/podokit-api-client";
 import type { Locale } from "#lib/i18n/messages.js";
 import type { SiteSettings } from "#lib/site.svelte.js";
 
@@ -24,6 +25,8 @@ declare global {
       locale: Locale;
       site: SiteSettings | null;
       siteUnavailable: boolean;
+      /** Per-request memo; read it through `getCapabilities()` from `#lib/server/capabilities.js`. */
+      capabilities?: Promise<Capabilities>;
     }
   }
 }

package/dist/templates/modules/admin-dashboard/files/apps/web/src/hooks.server.test.ts

@@ -0,0 +1,124 @@
+import { ApiError } from "@podosoft/podokit-api-client";
+import type { RequestEvent } from "@sveltejs/kit";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { handle } from "./hooks.server";
+
+type SessionResult = {
+  data: { user: { id: string }; session: { id: string; impersonatedBy?: string | null } } | null;
+  error: { status: number } | null;
+};
+
+const client = vi.hoisted(() => ({
+  get: vi.fn<(path: string) => Promise<unknown>>(),
+  getSession: vi.fn<() => Promise<SessionResult>>(),
+}));
+
+vi.mock("#lib/server/api.js", () => ({
+  serverApiClient: () => ({ get: client.get, auth: { getSession: client.getSession } }),
+}));
+
+const resolve = vi.fn(async (): Promise<Response> => new Response("ok"));
+
+function requestEvent(pathname: string, cookies: Record<string, string> = {}): RequestEvent {
+  return {
+    route: { id: pathname },
+    url: new URL(`http://localhost${pathname}`),
+    cookies: { get: (name: string) => cookies[name] },
+    locals: {},
+  } as unknown as RequestEvent;
+}
+
+const signedIn: SessionResult = {
+  data: { user: { id: "user-1" }, session: { id: "session-1", impersonatedBy: "admin-1" } },
+  error: null,
+};
+
+describe("handle", () => {
+  beforeEach(() => {
+    client.get.mockReset();
+    client.getSession.mockReset();
+    resolve.mockClear();
+  });
+
+  it("requests the session without waiting for site settings", async () => {
+    let releaseSite: (value: unknown) => void = () => undefined;
+    client.get.mockReturnValue(new Promise((settle) => { releaseSite = settle; }));
+    client.getSession.mockResolvedValue(signedIn);
+    const event = requestEvent("/account");
+
+    const pending = handle({ event, resolve });
+    await vi.waitFor(() => expect(client.getSession).toHaveBeenCalledTimes(1));
+    releaseSite({ locale: "ko" });
+    await pending;
+
+    expect(client.get).toHaveBeenCalledWith("/site/settings");
+    expect(event.locals).toMatchObject({
+      site: { locale: "ko" },
+      siteUnavailable: false,
+      authUnavailable: false,
+      locale: "ko",
+      user: { id: "user-1" },
+      session: { id: "session-1", impersonatedBy: "admin-1" },
+    });
+  });
+
+  it("treats a site settings client error as a reachable backend", async () => {
+    client.get.mockRejectedValue(new ApiError("TWO_FACTOR_REQUIRED", "Two-factor enrolment is required.", 403));
+    client.getSession.mockResolvedValue(signedIn);
+    const event = requestEvent("/account", { locale: "en" });
+
+    await handle({ event, resolve });
+
+    expect(event.locals).toMatchObject({ site: null, siteUnavailable: false, locale: "en" });
+    expect(resolve).toHaveBeenCalledTimes(1);
+  });
+
+  it("fails closed on protected pages when site settings are unavailable", async () => {
+    client.get.mockRejectedValue(new TypeError("fetch failed"));
+    client.getSession.mockResolvedValue(signedIn);
+
+    await expect(handle({ event: requestEvent("/account"), resolve })).rejects.toMatchObject({ status: 503 });
+    expect(resolve).not.toHaveBeenCalled();
+  });
+
+  it("keeps public pages available with fallbacks when the backend fails", async () => {
+    client.get.mockRejectedValue(new ApiError("UNAVAILABLE", "Unavailable", 503));
+    client.getSession.mockRejectedValue(new TypeError("fetch failed"));
+    const event = requestEvent("/login");
+
+    await handle({ event, resolve });
+
+    expect(event.locals).toMatchObject({
+      site: null,
+      siteUnavailable: true,
+      authUnavailable: true,
+      user: null,
+      session: null,
+      locale: "en",
+    });
+  });
+
+  it("confirms an anonymous visitor on a 401 session response", async () => {
+    client.get.mockResolvedValue({ locale: null });
+    client.getSession.mockResolvedValue({ data: null, error: { status: 401 } });
+    const event = requestEvent("/");
+
+    await handle({ event, resolve });
+
+    expect(event.locals).toMatchObject({ authUnavailable: false, user: null, session: null });
+  });
+
+  it("fails closed on protected pages when the session cannot be checked", async () => {
+    client.get.mockResolvedValue({ locale: null });
+    client.getSession.mockResolvedValue({ data: null, error: { status: 500 } });
+
+    await expect(handle({ event: requestEvent("/account"), resolve })).rejects.toMatchObject({ status: 503 });
+  });
+
+  it("skips runtime lookups for API proxy requests", async () => {
+    await handle({ event: requestEvent("/api/site/settings"), resolve });
+
+    expect(client.get).not.toHaveBeenCalled();
+    expect(client.getSession).not.toHaveBeenCalled();
+  });
+});