lrucache.ts

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") ??
    "1073741824",
); // 1 GB max size of cache
const CACHE_MAX_ITEMS = parseInt(
  Deno.env.get("CACHE_MAX_ITEMS") ?? "4096",
); // max number of items in the LRU cache (bounds internal typed array memory)
const CACHE_TTL_AUTOPURGE = Deno.env.get("CACHE_TTL_AUTOPURGE") === "true"; // creates a cron for each element in the cache to automatically delete expired items
const CACHE_TTL_RESOLUTION = parseInt(
  Deno.env.get("CACHE_TTL_RESOLUTION") ?? "1000",
); // updates the lru cache timer every 1 second
// How long stale content remains serveable (and stays on disk) beyond its expires header.
// Default: 1 hour — long enough for low-traffic sites to keep serving cached content across
// quiet periods while background revalidation catches up.
const STALE_TTL_PERIOD = parseInt(
  Deno.env.get("STALE_TTL_PERIOD") ?? "3600000", // 1h
);

const cacheOptions = (cache: Cache) => (
  {
    max: CACHE_MAX_ITEMS,
    maxSize: CACHE_MAX_SIZE,
    ttlAutopurge: CACHE_TTL_AUTOPURGE,
    ttlResolution: CACHE_TTL_RESOLUTION,
    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 openedCachesByName = new Map<string, Promise<Cache>>();
  const caches = createBaseCacheStorage(
    cacheStorageInner,
    (_cacheName, cacheInner, requestURLSHA1) => {
      const existing = openedCachesByName.get(_cacheName);
      if (existing) return existing;
      const fileCache = new LRUCache(cacheOptions(cacheInner));
      activeCaches.set(_cacheName, fileCache);
      const cache = Promise.resolve({
        ...baseCache,
        delete: async (
          request: RequestInfo | URL,
          options?: CacheQueryOptions,
        ): Promise<boolean> => {
          const cacheKey = await requestURLSHA1(request);
          cacheInner.delete(cacheKey, options);
          return fileCache.delete(cacheKey);
        },
        match: async (
          request: RequestInfo | URL,
          options?: CacheQueryOptions,
        ): Promise<Response | undefined> => {
          assertNoOptions(options);
          const cacheKey = await requestURLSHA1(request);
          if (fileCache.has(cacheKey)) {
            return cacheInner.match(cacheKey);
          }
          return undefined;
        },
        put: async (
          request: RequestInfo | URL,
          response: Response,
        ): Promise<void> => {
          const req = new Request(request);
          assertCanBeCached(req, response);

          if (!response.body) {
            return;
          }

          const expirationTimestamp = Date.parse(
            response.headers.get("expires") ?? "",
          );

          // Calculate the time-to-live (TTL) for the cached item:
          // - If STALE_TTL_PERIOD is configured, add it to the expiration time from the response headers
          //   This allows extending the cache lifetime beyond what the server specifies and serves stale content during this extra time
          // The staleness is detect at the loader level because it checks for the expires header, that remains untouched here, the idea is to serve stale content but with expired header
          const ttl = (expirationTimestamp - Date.now()) + STALE_TTL_PERIOD;

          const cacheKey = await requestURLSHA1(request);
          const length = response.headers.get("Content-Length");
          if (!length || length == "0") {
            return;
          }
          fileCache.set(cacheKey, true, {
            size: parseInt(length),
            ttl,
          });
          return cacheInner.put(cacheKey, response);
        },
      });
      openedCachesByName.set(_cacheName, cache);
      return cache;
    },
  );
  return caches;
}

export const caches = (cache: CacheStorage) => createLruCacheStorage(cache);