perf: fix storage caching layer with proper TTL, Cache-Control, and non-blocking writes

- Fix `setMeta({ ttl })` bug: TTL was only set on meta key, not data key.
  Replace all 12 occurrences with `{ ttl }` parameter on `setItem`/`setItemRaw`.
- Add Cache-Control headers to all cached routes (img, og, favicon, screenshot, fonts).
- Use `event.waitUntil` for non-blocking cache writes in hot paths.
- Fix img route cache key mismatch: data and Content-Type now stored/read
  from consistent keys using `setItemRaw` + `setMeta`/`getMeta`.
- Replace extension-guessing cache lookup with `getRouterParam` path extraction.
- Remove FS driver from production cache config (no TTL support), keep for dev.
- Extract all TTL magic numbers into `server/utils/constants.ts`.

Author: DemoMacro

nitro.config.ts

@@ -1,11 +1,8 @@
 import { defineNitroConfig } from "nitro/config";
-import { env, isBun, isDeno, isNode } from "std-env";
+import { env } from "std-env";
 
 import pkg from "./package.json";
 
-// Detect if filesystem is available (Node.js, Bun, or Deno runtime)
-const hasFilesystem = isNode || isBun || isDeno;
-
 export default defineNitroConfig({
   serverDir: "./server/",
   experimental: {
@@ -35,14 +32,11 @@ export default defineNitroConfig({
   },
   storage: {
     cache: {
-      driver: env.REDIS_URL ? "redis" : hasFilesystem ? "fs" : "memory",
+      // FS driver does not support TTL, only use redis or memory
+      driver: env.REDIS_URL ? "redis" : "memory",
       ...(env.REDIS_URL && {
         url: env.REDIS_URL,
       }),
-      ...(hasFilesystem &&
-        !env.REDIS_URL && {
-          base: "./.cache",
-        }),
     },
   },
   devStorage: {

package.json

@@ -38,16 +38,15 @@
   },
   "devDependencies": {
     "@sparticuz/chromium": "143.0.4",
-    "@types/node": "25.5.0",
+    "@types/node": "25.5.2",
     "@types/ua-parser-js": "0.7.39",
     "@vercel/og": "0.11.1",
     "cheerio": "1.2.0",
     "ioredis": "5.10.1",
     "ipx": "4.0.0-alpha.1",
     "nitro": "3.0.260311-beta",
-    "playwright": "1.58.2",
-    "prettier": "3.8.1",
+    "playwright": "1.59.1",
     "ua-parser-js": "2.0.9",
-    "vite-plus": "0.1.13"
+    "vite-plus": "0.1.15"
   }
 }

pnpm-lock.yaml

@@ -4,6 +4,8 @@ import { useStorage } from "nitro/storage";
 import { hash } from "ohash";
 import sharp from "sharp";
 
+import { FONT_FILE_TTL } from "../utils/constants";
+
 export interface FaviconQuery {
   url: string;
   size?: string;
@@ -327,17 +329,19 @@ export default defineHandler(async (event) => {
   if (cached) {
     event.res.headers.set("X-Cache", "HIT");
     event.res.headers.set("Content-Type", "image/png");
+    event.res.headers.set("Cache-Control", `public, max-age=${FONT_FILE_TTL}`);
     return Buffer.from(cached);
   }
 
   // CORS is handled by global routeRules
   const favicon = await getFavicon(url, size);
 
-  await storage.setItemRaw(cacheKey, new Uint8Array(favicon));
-  await storage.setMeta(cacheKey, { ttl: 2592000 }); // 30 days
+  // Non-blocking cache write (30 days TTL)
+  event.waitUntil(storage.setItemRaw(cacheKey, new Uint8Array(favicon), { ttl: FONT_FILE_TTL }));
 
   event.res.headers.set("X-Cache", "MISS");
   event.res.headers.set("Content-Type", "image/png");
+  event.res.headers.set("Cache-Control", `public, max-age=${FONT_FILE_TTL}`);
 
   return favicon;
 });

server/routes/favicon.ts

@@ -2,6 +2,8 @@ import { defineHandler, HTTPError, getRouterParam } from "nitro/h3";
 import { useStorage } from "nitro/storage";
 import { hash } from "ohash";
 
+import { FONT_FILE_TTL } from "../../utils/constants";
+
 export const allowedProviders = ["google", "bunny", "fontshare", "fontsource"];
 
 export const providerDomains: Record<string, string[]> = {
@@ -94,6 +96,7 @@ export default defineHandler(async (event) => {
     event.res.headers.set("X-Cache", "HIT");
     const contentType = getFontContentType(fontpath);
     event.res.headers.set("Content-Type", contentType);
+    event.res.headers.set("Cache-Control", `public, max-age=${FONT_FILE_TTL}`);
     return Buffer.from(cached);
   }
 
@@ -112,14 +115,14 @@ export default defineHandler(async (event) => {
 
   const data = Buffer.from(await response.arrayBuffer());
 
-  // Store raw binary data (30 days)
-  await storage.setItemRaw(cacheKey, new Uint8Array(data));
-  await storage.setMeta(cacheKey, { ttl: 2592000 }); // 30 days
+  // Non-blocking cache write (30 days TTL)
+  event.waitUntil(storage.setItemRaw(cacheKey, new Uint8Array(data), { ttl: FONT_FILE_TTL }));
 
   // CORS is handled by global routeRules
   const contentType = response.headers.get("content-type") || getFontContentType(fontpath);
   event.res.headers.set("X-Cache", "MISS");
   event.res.headers.set("Content-Type", contentType);
+  event.res.headers.set("Cache-Control", `public, max-age=${FONT_FILE_TTL}`);
 
   return data;
 });

server/routes/fonts/[...].ts

@@ -1,9 +1,11 @@
 import { createIPX, ipxHttpStorage, ipxFSStorage, createIPXFetchHandler } from "ipx";
-import { defineHandler } from "nitro/h3";
+import { defineHandler, getRouterParam } from "nitro/h3";
 import { useStorage } from "nitro/storage";
 import { hash } from "ohash";
 import { env } from "std-env";
 
+import { IMAGE_TTL, OG_IMAGE_TTL } from "../../utils/constants";
+
 // Parse allowed domains from environment
 export const allowedDomains = env.ALLOWED_DOMAINS
   ? env.ALLOWED_DOMAINS.split(",")
@@ -17,75 +19,54 @@ export const ipx = createIPX({
   httpStorage: ipxHttpStorage({
     domains: allowedDomains,
     allowAllDomains: allowedDomains.length === 0,
-    maxAge: 86400,
+    maxAge: IMAGE_TTL,
   }),
-  maxAge: 86400,
+  maxAge: IMAGE_TTL,
 });
 
-export function contentTypeToExtension(contentType: string): string {
-  const type = contentType.toLowerCase();
-  if (type.includes("png")) return "png";
-  if (type.includes("jpeg") || type.includes("jpg")) return "jpg";
-  if (type.includes("webp")) return "webp";
-  if (type.includes("gif")) return "gif";
-  if (type.includes("avif")) return "avif";
-  if (type.includes("heif")) return "heif";
-  if (type.includes("tiff")) return "tiff";
-  return "png";
-}
+const fetchHandler = createIPXFetchHandler(ipx);
 
 export default defineHandler(async (event) => {
+  const path = getRouterParam(event, "_") || "";
+  const ipxPath = "/" + path;
   const url = new URL(event.req.url);
-  const ipxPath = url.pathname.replace(/^\/img/, "") || "/";
   url.pathname = ipxPath;
 
-  // Generate cache key using ohash
-  const cacheKeyBase = `img:${hash({ path: ipxPath, search: url.search })}`;
+  const cacheKey = `img:${hash({ path: ipxPath, search: url.search })}`;
   const storage = useStorage("cache");
 
-  // Try common image extensions for cache lookup
-  const extensions = ["png", "jpg", "jpeg", "webp", "gif", "avif", "heif", "tiff", "tif"];
-  let cached: Uint8Array | null = null;
-  let cacheKey = "";
-
-  for (const ext of extensions) {
-    const key = `${cacheKeyBase}.${ext}`;
-    const data = await storage.getItemRaw<Uint8Array>(key);
-    if (data) {
-      cached = data;
-      cacheKey = key;
-      break;
-    }
-  }
-
+  // Cache lookup
+  const cached = await storage.getItemRaw<Uint8Array>(cacheKey);
   if (cached) {
+    const cachedMeta = await storage.getMeta(cacheKey);
+    const contentType =
+      typeof cachedMeta?.contentType === "string" ? cachedMeta.contentType : "image/png";
+    event.res.headers.set("Content-Type", contentType);
     event.res.headers.set("X-Cache", "HIT");
-    return Buffer.from(cached);
+    event.res.headers.set("Cache-Control", `public, max-age=${IMAGE_TTL}`);
+    return cached;
   }
 
-  cacheKey = cacheKeyBase;
-
-  // Use IPX to process the image
-  const fetchHandler = createIPXFetchHandler(ipx);
+  // Process with IPX
   const response = await fetchHandler(new Request(url, event.req));
-  const arrayBuffer = await response.arrayBuffer();
-  const buffer = Buffer.from(arrayBuffer);
+  const data = await response.bytes();
 
-  // Get extension from response Content-Type
-  const contentType = response.headers.get("content-type") || "image/png";
-  const extension = contentTypeToExtension(contentType);
-  cacheKey = `${cacheKey}.${extension}`;
-
-  // Store raw binary data (7 days)
-  await storage.setItemRaw(cacheKey, new Uint8Array(buffer));
-  await storage.setMeta(cacheKey, { ttl: 604800 }); // 7 days
-
-  // Copy headers from IPX response
+  // Copy IPX response headers
   response.headers.forEach((value, key) => {
     event.res.headers.set(key, value);
   });
 
   event.res.headers.set("X-Cache", "MISS");
+  event.res.headers.set("Cache-Control", `public, max-age=${IMAGE_TTL}`);
+
+  // Non-blocking cache write: data with TTL, Content-Type in metadata
+  const contentType = response.headers.get("content-type") || "image/png";
+  event.waitUntil(
+    Promise.all([
+      storage.setItemRaw(cacheKey, data, { ttl: OG_IMAGE_TTL }),
+      storage.setMeta(cacheKey, { contentType }, { ttl: OG_IMAGE_TTL }),
+    ]),
+  );
 
-  return buffer;
+  return data;
 });

server/routes/img/[...].ts

@@ -3,6 +3,8 @@ import { defineHandler, getQuery } from "nitro/h3";
 import { useStorage } from "nitro/storage";
 import { hash } from "ohash";
 
+import { OG_IMAGE_TTL } from "../utils/constants";
+
 export interface OGQuery {
   title?: string;
   description?: string;
@@ -35,6 +37,7 @@ export default defineHandler(async (event) => {
   if (cached) {
     event.res.headers.set("X-Cache", "HIT");
     event.res.headers.set("Content-Type", "image/png");
+    event.res.headers.set("Cache-Control", `public, max-age=${OG_IMAGE_TTL}`);
     return Buffer.from(cached);
   }
 
@@ -108,10 +111,11 @@ export default defineHandler(async (event) => {
   const imageResponse = new ImageResponse(element, { width, height });
   const buffer = Buffer.from(await imageResponse.arrayBuffer());
 
-  await storage.setItemRaw(cacheKey, new Uint8Array(buffer));
+  await storage.setItemRaw(cacheKey, new Uint8Array(buffer), { ttl: OG_IMAGE_TTL });
 
   event.res.headers.set("X-Cache", "MISS");
   event.res.headers.set("Content-Type", "image/png");
+  event.res.headers.set("Cache-Control", `public, max-age=${OG_IMAGE_TTL}`);
 
   return buffer;
 });

server/routes/og.ts

@@ -4,6 +4,8 @@ import { useStorage } from "nitro/storage";
 import { hash } from "ohash";
 import { chromium as playwright, type Browser, type Page, type BrowserContext } from "playwright";
 
+import { IMAGE_TTL } from "../utils/constants";
+
 export interface ScreenshotQuery {
   url: string;
   width?: string;
@@ -143,6 +145,7 @@ export default defineHandler(async (event) => {
     event.res.headers.set("X-Cache", "HIT");
     const contentType = format === "jpeg" ? "image/jpeg" : "image/png";
     event.res.headers.set("Content-Type", contentType);
+    event.res.headers.set("Cache-Control", `public, max-age=${IMAGE_TTL}`);
     return Buffer.from(cached);
   }
 
@@ -171,14 +174,14 @@ export default defineHandler(async (event) => {
       ...(format === "jpeg" && { quality }),
     });
 
-    // Store raw binary data (24 hours)
-    await storage.setItemRaw(cacheKey, new Uint8Array(screenshot));
-    await storage.setMeta(cacheKey, { ttl: 86400 }); // 24 hours
+    // Non-blocking cache write (24 hours TTL)
+    event.waitUntil(storage.setItemRaw(cacheKey, new Uint8Array(screenshot), { ttl: IMAGE_TTL }));
 
     // CORS is handled by global routeRules
     const contentType = format === "jpeg" ? "image/jpeg" : "image/png";
     event.res.headers.set("X-Cache", "MISS");
     event.res.headers.set("Content-Type", contentType);
+    event.res.headers.set("Cache-Control", `public, max-age=${IMAGE_TTL}`);
 
     return screenshot;
   } finally {

server/routes/screenshot.ts

@@ -2,6 +2,7 @@ import { defineHandler, getQuery } from "nitro/h3";
 import { useStorage } from "nitro/storage";
 import { hash } from "ohash";
 
+import { FONT_META_TTL } from "../utils/constants";
 import { getWebfontsList } from "../utils/fonts/webfonts";
 
 export interface WebfontsQuery {
@@ -32,8 +33,7 @@ export default defineHandler(async (event) => {
 
   const response = await getWebfontsList(provider, { family, subset, category }, sort);
 
-  await storage.setItem(cacheKey, response);
-  await storage.setMeta(cacheKey, { ttl: 3600 }); // 1 hour
+  await storage.setItem(cacheKey, response, { ttl: FONT_META_TTL }); // 1 hour
 
   event.res.headers.set("X-Cache", "MISS");
 

server/routes/webfonts.ts

@@ -0,0 +1,11 @@
+/** Font metadata cache: 1 hour */
+export const FONT_META_TTL = 3600;
+
+/** Image proxy and screenshot cache: 1 day */
+export const IMAGE_TTL = 86400;
+
+/** OG image cache: 7 days */
+export const OG_IMAGE_TTL = 604800;
+
+/** Favicon and font file cache: 30 days */
+export const FONT_FILE_TTL = 2592000;