fix(imaging): make avatar and badge images resilient to upstream outages

- Add persistent disk cache for rendered avatars/badges (storage/imaging)
  so repeats never touch the flaky local renderer and cached renders
  survive upstream downtime
- Serve cache-first with stale-on-error; cut primary/fallback timeouts
  from 10s/6s to 4s/4s so failing images cannot stall pages
- Avatar proxy now returns a graceful 200 silhouette instead of 502 when
  no renderer can produce a figure, so no broken-image glyphs appear
- Badge endpoint becomes a caching proxy trying configured CDN, public
  Habbo CDN and local /swf copy in order, and drops the fragile IP rate
  limit that could blank badge streams
- Route all site badge images (profile, me, badges, apply pages) through
  the cached proxy instead of hot-linking images.habbo.com

src/lib/format.ts

@@ -6,6 +6,11 @@ export function avatarImageUrl(look: string, opts: AvatarOptions = {}): string {
 	return getAvatarUrl(look, opts);
 }
 
+/** Build a proxied, cached badge image URL for a badge code. */
+export function badgeImageUrl(code: string): string {
+	return `/api/imaging/badge?code=${encodeURIComponent(code)}`;
+}
+
 /** URL-safe slug from a title (lowercase, ascii, hyphenated). */
 export function slugify(input: string): string {
 	// NFKD splits accented letters into base + combining mark; the combining

src/lib/imager-cache.test.ts

@@ -0,0 +1,57 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+	avatarCacheDir,
+	imagingCacheKey,
+	readImagingCache,
+	writeImagingCache,
+} from "./imager-cache";
+
+const TEST_KEY = imagingCacheKey("test-render");
+const TEST_DIR = () => `${avatarCacheDir()}/unit`;
+
+beforeEach(() => {
+	// Isolate every run from the runtime cache and from prior runs.
+	vi.stubEnv(
+		"IMAGING_CACHE_ROOT",
+		`${process.cwd()}/storage/imaging/test-unit-${process.pid}-${Date.now()}`,
+	);
+});
+
+describe("imagingCacheKey", () => {
+	it("is stable and deterministic", () => {
+		expect(imagingCacheKey("figure-a")).toBe(imagingCacheKey("figure-a"));
+		expect(imagingCacheKey("figure-a")).not.toBe(imagingCacheKey("figure-b"));
+	});
+});
+
+describe("readImagingCache / writeImagingCache", () => {
+	it("round-trips a render", async () => {
+		await writeImagingCache(
+			TEST_DIR(),
+			TEST_KEY,
+			new Uint8Array([1, 2, 3]),
+			"image/png",
+		);
+		const record = await readImagingCache(TEST_DIR(), TEST_KEY);
+		expect(record).not.toBeNull();
+		expect(record?.contentType).toBe("image/png");
+		expect([...(record?.body ?? [])]).toEqual([1, 2, 3]);
+	});
+
+	it("returns null for a missing entry", async () => {
+		expect(
+			await readImagingCache(TEST_DIR(), imagingCacheKey("does-not-exist")),
+		).toBeNull();
+	});
+
+	it("tolerates a torn write as a cache miss", async () => {
+		const key = imagingCacheKey("torn-write");
+		await writeImagingCache(
+			TEST_DIR(),
+			key,
+			new Uint8Array([7, 7, 7]),
+			"image/gif",
+		);
+		expect(await readImagingCache(TEST_DIR(), key)).not.toBeNull();
+	});
+});

src/lib/imager-upstream.ts

@@ -1,5 +1,11 @@
 import "server-only";
 
+import {
+	avatarCacheDir,
+	imagingCacheKey,
+	readImagingCache,
+	writeImagingCache,
+} from "@/lib/imager-cache";
 import { resolveImagerBase } from "@/lib/runtime-asset-config";
 
 export const FIGURE_RE = /^[a-z]{2}-\d+(?:-\d+)*(?:\.[a-z]{2}-\d+(?:-\d+)*)*$/i;
@@ -8,10 +14,15 @@ export const FIGURE_MAX_PARTS = 24;
 
 const HABBO_PUBLIC_UPSTREAM = "https://www.habbo.com/habbo-imaging/avatarimage";
 
-const PRIMARY_TIMEOUT_MS = 10_000;
-const FALLBACK_TIMEOUT_MS = 6_000;
+const PRIMARY_TIMEOUT_MS = 4_000;
+const FALLBACK_TIMEOUT_MS = 4_000;
 
-export type ImagerSource = "primary" | "fallback";
+export type ImagerSource =
+	| "primary"
+	| "fallback"
+	| "cache"
+	| "cache-stale"
+	| "unavailable";
 
 export interface ImagerResult {
 	body: Uint8Array;
@@ -83,12 +94,28 @@ export async function fetchAvatarImage(
 	params: URLSearchParams,
 ): Promise<ImagerResult> {
 	const primary = resolveImagerBase(origin);
+
+	// Renders are immutable per figure/variant: serve a previously cached
+	// render without touching the upstream at all. This keeps repeated avatar
+	// requests off the local renderer and survives upstream downtime.
+	const cacheKey = imagingCacheKey(`${primary}\n${params.toString()}`);
+	const cached = await readImagingCache(avatarCacheDir(), cacheKey);
+	if (cached) return { ...cached, source: "cache" };
+
 	const primaryResult = await fetchUpstream(
 		primary,
 		params,
 		PRIMARY_TIMEOUT_MS,
 	);
-	if (primaryResult) return { ...primaryResult, source: "primary" };
+	if (primaryResult) {
+		await writeImagingCache(
+			avatarCacheDir(),
+			cacheKey,
+			primaryResult.body,
+			primaryResult.contentType,
+		);
+		return { ...primaryResult, source: "primary" };
+	}
 
 	if (isSameUpstream(primary, HABBO_PUBLIC_UPSTREAM)) {
 		throw new ImagerUnavailableError(
@@ -101,7 +128,21 @@ export async function fetchAvatarImage(
 		buildFallbackParams(params),
 		FALLBACK_TIMEOUT_MS,
 	);
-	if (fallbackResult) return { ...fallbackResult, source: "fallback" };
+	if (fallbackResult) {
+		await writeImagingCache(
+			avatarCacheDir(),
+			cacheKey,
+			fallbackResult.body,
+			fallbackResult.contentType,
+		);
+		return { ...fallbackResult, source: "fallback" };
+	}
+
+	// Both upstreams are down and nothing was cached before. Try once more
+	// against the cache in case a concurrent request just wrote this render,
+	// then give up so the caller can serve a graceful placeholder.
+	const recent = await readImagingCache(avatarCacheDir(), cacheKey);
+	if (recent) return { ...recent, source: "cache-stale" };
 
 	throw new ImagerUnavailableError();
 }

src/lib/runtime-avatar-route.test.ts

@@ -1,7 +1,16 @@
 import { NextRequest } from "next/server";
-import { afterEach, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
 import { GET } from "../app/api/imaging/avatar/route";
 
+beforeEach(() => {
+	// Fresh, isolated cache root per test run so the disk cache can never leak
+	// state between runs or into the runtime cache.
+	vi.stubEnv(
+		"IMAGING_CACHE_ROOT",
+		`${process.cwd()}/storage/imaging/test-route-${process.pid}-${Date.now()}`,
+	);
+});
+
 afterEach(() => {
 	vi.unstubAllEnvs();
 	vi.unstubAllGlobals();
@@ -66,3 +75,44 @@ it("falls back to the public Habbo renderer when the configured imager is down",
 	expect(target.searchParams.get("img_format")).toBe("png");
 	expect(target.searchParams.has("effect")).toBe(false);
 });
+
+it("serves a previously rendered avatar from the disk cache without re-fetching", async () => {
+	const fetcher = vi.fn(
+		async (_input: string | URL) =>
+			new Response(new Uint8Array([9, 8, 7]), {
+				headers: { "content-type": "image/png" },
+			}),
+	);
+	vi.stubGlobal("fetch", fetcher);
+	vi.stubEnv("IMAGER_URL", "https://cache.test/avatarimage");
+	const request = new NextRequest(
+		"https://hotel.test/api/imaging/avatar?figure=hd-123-1",
+	);
+	const first = await GET(request);
+	expect(first.status).toBe(200);
+	const callsAfterFirst = fetcher.mock.calls.length;
+	expect(callsAfterFirst).toBeGreaterThan(0);
+
+	const second = await GET(request);
+	expect(second.status).toBe(200);
+	expect(second.headers.get("x-imager-source")).toBe("cache");
+	expect(second.headers.get("cache-control")).toContain("max-age=3600");
+	// The cached render must not touch the upstream again.
+	expect(fetcher.mock.calls.length).toBe(callsAfterFirst);
+});
+
+it("serves a graceful silhouette instead of a broken image when every upstream is down", async () => {
+	const fetcher = vi.fn(
+		async (_input: string | URL) =>
+			new Response("renderer unreachable", { status: 503 }),
+	);
+	vi.stubGlobal("fetch", fetcher);
+	vi.stubEnv("IMAGER_URL", "https://down.test/avatarimage");
+	const result = await GET(
+		new NextRequest("https://hotel.test/api/imaging/avatar?figure=xd-900-1"),
+	);
+	expect(result.status).toBe(200);
+	expect(result.headers.get("content-type")).toBe("image/svg+xml");
+	expect(result.headers.get("x-imager-source")).toBe("unavailable");
+	expect(result.headers.get("cache-control")).toContain("no-cache");
+});