feat(cache): filesystem hardening with hex sharding, size limits, and warnings

vibegui · claude · vibegui · commit c23675125c81 · 2026-03-18T11:28:05.000-03:00
- Add hex directory sharding ({key[0:2]}/{key[2:4]}/{key}) to avoid flat dirs with 10k+ files
- Enforce CACHE_MAX_ENTRY_SIZE (2MB default) at filesystem and worker layers
- Evict existing stale entries when oversized writes are rejected
- Add write rate warning (CACHE_WRITE_RATE_WARN, default 500/min)
- Add disk fill warning when LRU tracked bytes exceed LRU_DISK_WARN_RATIO (90%)
- Add LRU eviction counter with reason dimension
- Add observable gauges for LRU keys and bytes per cache

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/runtime/caches/cacheWriteWorker.ts b/runtime/caches/cacheWriteWorker.ts
@@ -1,6 +1,10 @@
 // Worker thread for cache write operations.
 // Offloads SHA1 hashing, buffer combining, and FS writes from the main event loop.
 
+const CACHE_MAX_ENTRY_SIZE = parseInt(
+  Deno.env.get("CACHE_MAX_ENTRY_SIZE") ?? "2097152", // 2 MB
+) || 2097152;
+
 const textEncoder = new TextEncoder();
 
 const initializedDirs = new Set<string>();
@@ -57,6 +61,12 @@ function generateCombinedBuffer(
   return buf;
 }
 
+function shardedPath(cacheDir: string, key: string): string {
+  const l1 = key.substring(0, 2);
+  const l2 = key.substring(2, 4);
+  return `${cacheDir}/${l1}/${l2}/${key}`;
+}
+
 // --- Message handler ---
 
 export interface CacheWriteMessage {
@@ -85,8 +95,12 @@ self.onmessage = async (e: MessageEvent<CacheWriteMessage>) => {
     // Combine into single buffer
     const buffer = generateCombinedBuffer(body, headersBytes);
 
-    // Write to filesystem
-    const filePath = `${cacheDir}/${cacheKey}`;
+    if (buffer.length > CACHE_MAX_ENTRY_SIZE) return;
+
+    // Write to filesystem (with hex sharding for directory distribution)
+    const filePath = shardedPath(cacheDir, cacheKey);
+    const dir = filePath.substring(0, filePath.lastIndexOf("/"));
+    ensureCacheDir(dir);
     await Deno.writeFile(filePath, buffer);
   } catch (err) {
     console.error("[cache-write-worker] error:", err);
diff --git a/runtime/caches/fileSystem.ts b/runtime/caches/fileSystem.ts
@@ -11,6 +11,45 @@ import {
 const FILE_SYSTEM_CACHE_DIRECTORY =
   Deno.env.get("FILE_SYSTEM_CACHE_DIRECTORY") ?? "/tmp/deco_cache";
 
+const CACHE_MAX_ENTRY_SIZE = parseInt(
+  Deno.env.get("CACHE_MAX_ENTRY_SIZE") ?? "2097152", // 2 MB
+) || 2097152;
+
+// Warn when write rate exceeds this many writes per minute.
+// High write rates usually indicate bots, missing cache keys, or very short TTLs.
+const CACHE_WRITE_RATE_WARN = parseInt(
+  Deno.env.get("CACHE_WRITE_RATE_WARN") ?? "500",
+) || 500;
+
+// --- Write rate tracking ---
+let writeCount = 0;
+let writeWindowStart = Date.now();
+
+function trackWriteRate(key: string) {
+  const now = Date.now();
+  if (now - writeWindowStart > 60_000) {
+    writeWindowStart = now;
+    writeCount = 0;
+  }
+  writeCount++;
+  if (writeCount === CACHE_WRITE_RATE_WARN) {
+    logger.warn(
+      `fs_cache: high write rate — ${writeCount} writes in the last minute. ` +
+        `Latest key: ${key}. ` +
+        `Consider increasing CACHE_MAX_AGE_S or reviewing loader cacheKey functions. ` +
+        `Adjust threshold with CACHE_WRITE_RATE_WARN (current: ${CACHE_WRITE_RATE_WARN}/min).`,
+    );
+  }
+}
+
+const initializedShardDirs = new Set<string>();
+
+function shardedPath(cacheDir: string, key: string): string {
+  const l1 = key.substring(0, 2);
+  const l2 = key.substring(2, 4);
+  return `${cacheDir}/${l1}/${l2}/${key}`;
+}
+
 // Reuse TextEncoder instance to avoid repeated instantiation
 const textEncoder = new TextEncoder();
 
@@ -106,7 +145,7 @@ function createFileSystemCache(): CacheStorage {
       if (
         FILE_SYSTEM_CACHE_DIRECTORY && !existsSync(FILE_SYSTEM_CACHE_DIRECTORY)
       ) {
-        await Deno.mkdirSync(FILE_SYSTEM_CACHE_DIRECTORY, { recursive: true });
+        await Deno.mkdir(FILE_SYSTEM_CACHE_DIRECTORY, { recursive: true });
       }
       isCacheInitialized = true;
     } catch (err) {
@@ -118,11 +157,25 @@ function createFileSystemCache(): CacheStorage {
     key: string,
     responseArray: Uint8Array,
   ) {
+    if (responseArray.length > CACHE_MAX_ENTRY_SIZE) {
+      // Evict any existing entry so stale data doesn't stay pinned on disk.
+      deleteFile(key).catch(() => {});
+      return;
+    }
     if (!isCacheInitialized) {
       await assertCacheDirectory();
     }
-    const filePath = `${FILE_SYSTEM_CACHE_DIRECTORY}/${key}`;
-
+    trackWriteRate(key);
+    const filePath = shardedPath(FILE_SYSTEM_CACHE_DIRECTORY, key);
+    const dir = filePath.substring(0, filePath.lastIndexOf("/"));
+    if (!initializedShardDirs.has(dir)) {
+      try {
+        await Deno.mkdir(dir, { recursive: true });
+        initializedShardDirs.add(dir);
+      } catch {
+        // transient failure — don't mark initialized so next write retries mkdir
+      }
+    }
     await Deno.writeFile(filePath, responseArray);
     return;
   }
@@ -132,8 +185,12 @@ function createFileSystemCache(): CacheStorage {
       await assertCacheDirectory();
     }
     try {
-      const filePath = `${FILE_SYSTEM_CACHE_DIRECTORY}/${key}`;
+      const filePath = shardedPath(FILE_SYSTEM_CACHE_DIRECTORY, key);
       const fileContent = await Deno.readFile(filePath);
+      if (fileContent.length > CACHE_MAX_ENTRY_SIZE) {
+        Deno.remove(filePath).catch(() => {});
+        return null;
+      }
       return fileContent;
     } catch (_err) {
       const err = _err as { code?: string };
@@ -151,7 +208,7 @@ function createFileSystemCache(): CacheStorage {
       await assertCacheDirectory();
     }
     try {
-      const filePath = `${FILE_SYSTEM_CACHE_DIRECTORY}/${key}`;
+      const filePath = shardedPath(FILE_SYSTEM_CACHE_DIRECTORY, key);
       await Deno.remove(filePath);
       return true;
     } catch (err) {
diff --git a/runtime/caches/lrucache.ts b/runtime/caches/lrucache.ts
@@ -1,11 +1,19 @@
 import { LRUCache } from "npm:lru-cache@10.2.0";
+import { ValueType } from "../../deps.ts";
+import { logger } from "../../observability/otel/config.ts";
+import { meter } from "../../observability/otel/metrics.ts";
 import {
   assertCanBeCached,
   assertNoOptions,
   baseCache,
   createBaseCacheStorage,
 } from "./utils.ts";
 
+const lruEvictionCounter = meter.createCounter("lru_cache_eviction", {
+  unit: "1",
+  valueType: ValueType.DOUBLE,
+});
+
 // keep compatible with old variable name
 const CACHE_MAX_SIZE = parseInt(
   Deno.env.get("CACHE_MAX_SIZE") ?? Deno.env.get("MAX_CACHE_SIZE") ??
@@ -30,17 +38,61 @@ const cacheOptions = (cache: Cache) => (
     maxSize: CACHE_MAX_SIZE,
     ttlAutopurge: CACHE_TTL_AUTOPURGE,
     ttlResolution: CACHE_TTL_RESOLUTION,
-    dispose: async (_value: boolean, key: string) => {
+    dispose: async (_value: boolean, key: string, reason: string) => {
+      lruEvictionCounter.add(1, { reason });
       await cache.delete(key);
     },
   }
 );
 
+const lruSizeGauge = meter.createObservableGauge("lru_cache_keys", {
+  description: "number of keys in the LRU cache",
+  unit: "1",
+  valueType: ValueType.DOUBLE,
+});
+
+const lruBytesGauge = meter.createObservableGauge("lru_cache_bytes", {
+  description: "total bytes tracked by the LRU cache",
+  unit: "bytes",
+  valueType: ValueType.DOUBLE,
+});
+
+// deno-lint-ignore no-explicit-any
+const activeCaches = new Map<string, LRUCache<string, any>>();
+
+lruSizeGauge.addCallback((observer) => {
+  for (const [name, lru] of activeCaches) {
+    observer.observe(lru.size, { cache: name });
+  }
+});
+
+// Warn when LRU disk usage exceeds this fraction of CACHE_MAX_SIZE.
+// At this point the LRU is evicting aggressively and disk is nearly full.
+const LRU_DISK_WARN_RATIO = parseFloat(
+  Deno.env.get("LRU_DISK_WARN_RATIO") ?? "0.9",
+);
+
+lruBytesGauge.addCallback((observer) => {
+  for (const [name, lru] of activeCaches) {
+    observer.observe(lru.calculatedSize, { cache: name });
+    const ratio = lru.calculatedSize / CACHE_MAX_SIZE;
+    if (ratio >= LRU_DISK_WARN_RATIO) {
+      logger.warn(
+        `lru_cache: disk usage for cache "${name}" is at ` +
+          `${Math.round(lru.calculatedSize / 1024 / 1024)}MB / ` +
+          `${Math.round(CACHE_MAX_SIZE / 1024 / 1024)}MB (${Math.round(ratio * 100)}%). ` +
+          `LRU is evicting aggressively. Consider increasing CACHE_MAX_SIZE or reducing CACHE_MAX_AGE_S.`,
+      );
+    }
+  }
+});
+
 function createLruCacheStorage(cacheStorageInner: CacheStorage): CacheStorage {
   const caches = createBaseCacheStorage(
     cacheStorageInner,
     (_cacheName, cacheInner, requestURLSHA1) => {
       const fileCache = new LRUCache(cacheOptions(cacheInner));
+      activeCaches.set(_cacheName, fileCache);
       return Promise.resolve({
         ...baseCache,
         delete: async (
