@ultimat3/cache 1.0.0

package/src/lru.ts

@@ -0,0 +1,255 @@
+// Tier 1: in-process LRU bounded by BYTES, not entry count — an entry count budget is a
+// memory leak with extra steps once payload sizes vary. Doubly-linked list + Map for O(1)
+// touch/evict, plus a tag -> keys index so `invalidateTags` never scans the whole cache.
+// Zero dependencies: this must work in the `x dev` process with nothing installed.
+
+import type { Clock } from '@ultimat3/core';
+import { systemClock } from '@ultimat3/core';
+import { CacheTooLargeError } from './errors';
+import type { CacheTag } from './tags';
+import { serializeTag } from './tags';
+import type { CacheEntry, CacheSetOptions, CacheTier, TierInvalidation } from './tiers';
+import { nowMs } from './tiers';
+
+export interface LruOptions {
+  /** Byte budget for the whole tier. Default 64 MiB. */
+  readonly maxBytes?: number;
+  /** Applied when a `set` omits `ttlMs`. Default 60s — stale-by-default is safer here. */
+  readonly defaultTtlMs?: number;
+  readonly clock?: Clock;
+}
+
+interface LruNode {
+  key: string;
+  value: unknown;
+  bytes: number;
+  /** Epoch ms, or `Number.POSITIVE_INFINITY` for no expiry. */
+  expiresAt: number;
+  tags: readonly CacheTag[];
+  prev: LruNode | undefined;
+  next: LruNode | undefined;
+}
+
+const encoder = new TextEncoder();
+
+/** Cheap, deterministic size estimate. Exact heap cost is unknowable; consistency matters. */
+export function estimateBytes(value: unknown): number {
+  if (value === undefined) return 0;
+  if (typeof value === 'string') return encoder.encode(value).byteLength;
+  if (value instanceof ArrayBuffer) return value.byteLength;
+  if (ArrayBuffer.isView(value)) return value.byteLength;
+  try {
+    return encoder.encode(JSON.stringify(value) ?? '').byteLength;
+  } catch {
+    return 1024;
+  }
+}
+
+function index(into: Map<string, Set<string>>, bucket: string, key: string): void {
+  let set = into.get(bucket);
+  if (set === undefined) {
+    set = new Set();
+    into.set(bucket, set);
+  }
+  set.add(key);
+}
+
+function deindex(from: Map<string, Set<string>>, bucket: string, key: string): void {
+  const set = from.get(bucket);
+  if (set === undefined) return;
+  set.delete(key);
+  if (set.size === 0) from.delete(bucket);
+}
+
+export interface LruStats {
+  readonly entries: number;
+  readonly bytes: number;
+  readonly maxBytes: number;
+  readonly hits: number;
+  readonly misses: number;
+  readonly evictions: number;
+}
+
+export class LruCache {
+  private readonly map = new Map<string, LruNode>();
+  private readonly tagIndex = new Map<string, Set<string>>();
+  private readonly entityIndex = new Map<string, Set<string>>();
+  private readonly maxBytes: number;
+  private readonly defaultTtlMs: number;
+  private readonly clock: Clock;
+  private head: LruNode | undefined;
+  private tail: LruNode | undefined;
+  private bytes = 0;
+  private hits = 0;
+  private misses = 0;
+  private evictions = 0;
+
+  constructor(options: LruOptions = {}) {
+    this.maxBytes = options.maxBytes ?? 64 * 1024 * 1024;
+    this.defaultTtlMs = options.defaultTtlMs ?? 60_000;
+    this.clock = options.clock ?? systemClock;
+  }
+
+  get<T>(key: string): CacheEntry<T> | undefined {
+    const node = this.map.get(key);
+    if (node === undefined) {
+      this.misses += 1;
+      return undefined;
+    }
+    if (node.expiresAt <= nowMs(this.clock)) {
+      this.unlink(node);
+      this.misses += 1;
+      return undefined;
+    }
+    this.touch(node);
+    this.hits += 1;
+    return {
+      value: node.value as T,
+      tags: node.tags,
+      ...(node.expiresAt === Number.POSITIVE_INFINITY ? {} : { expiresAt: node.expiresAt }),
+    };
+  }
+
+  set<T>(key: string, value: T, options: CacheSetOptions = {}): void {
+    const bytes = estimateBytes(value) + encoder.encode(key).byteLength;
+    if (bytes > this.maxBytes) {
+      throw new CacheTooLargeError({ key, bytes, maxBytes: this.maxBytes, tier: 'lru' });
+    }
+
+    const existing = this.map.get(key);
+    if (existing !== undefined) this.unlink(existing);
+
+    const ttl = options.ttlMs ?? this.defaultTtlMs;
+    const node: LruNode = {
+      key,
+      value,
+      bytes,
+      expiresAt: ttl <= 0 ? Number.POSITIVE_INFINITY : nowMs(this.clock) + ttl,
+      tags: options.tags ?? [],
+      prev: undefined,
+      next: undefined,
+    };
+
+    this.map.set(key, node);
+    this.bytes += bytes;
+    this.pushFront(node);
+    for (const owned of node.tags) {
+      index(this.tagIndex, serializeTag(owned), key);
+      index(this.entityIndex, owned.entity, key);
+    }
+
+    while (this.bytes > this.maxBytes && this.tail !== undefined) {
+      this.unlink(this.tail);
+      this.evictions += 1;
+    }
+  }
+
+  del(key: string): boolean {
+    const node = this.map.get(key);
+    if (node === undefined) return false;
+    this.unlink(node);
+    return true;
+  }
+
+  /** Only entries carrying a matching tag are dropped; untagged neighbours survive. */
+  invalidateTags(tags: readonly CacheTag[]): readonly string[] {
+    const candidates = new Set<string>();
+    for (const requested of tags) {
+      if (requested.id === undefined) {
+        // Collection bust: every row of that entity goes too.
+        for (const key of this.entityIndex.get(requested.entity) ?? []) candidates.add(key);
+        continue;
+      }
+      // Row bust: the row itself plus anything tagged with the bare collection.
+      for (const key of this.tagIndex.get(serializeTag(requested)) ?? []) candidates.add(key);
+      for (const key of this.tagIndex.get(requested.entity) ?? []) candidates.add(key);
+    }
+
+    const removed: string[] = [];
+    for (const key of candidates) {
+      if (this.del(key)) removed.push(key);
+    }
+    return removed;
+  }
+
+  keys(): readonly string[] {
+    const out: string[] = [];
+    for (let node = this.head; node !== undefined; node = node.next) out.push(node.key);
+    return out;
+  }
+
+  clear(): void {
+    this.map.clear();
+    this.tagIndex.clear();
+    this.entityIndex.clear();
+    this.head = undefined;
+    this.tail = undefined;
+    this.bytes = 0;
+  }
+
+  stats(): LruStats {
+    return {
+      entries: this.map.size,
+      bytes: this.bytes,
+      maxBytes: this.maxBytes,
+      hits: this.hits,
+      misses: this.misses,
+      evictions: this.evictions,
+    };
+  }
+
+  private pushFront(node: LruNode): void {
+    node.prev = undefined;
+    node.next = this.head;
+    if (this.head !== undefined) this.head.prev = node;
+    this.head = node;
+    if (this.tail === undefined) this.tail = node;
+  }
+
+  private touch(node: LruNode): void {
+    if (this.head === node) return;
+    this.detach(node);
+    this.pushFront(node);
+  }
+
+  private detach(node: LruNode): void {
+    if (node.prev !== undefined) node.prev.next = node.next;
+    else if (this.head === node) this.head = node.next;
+    if (node.next !== undefined) node.next.prev = node.prev;
+    else if (this.tail === node) this.tail = node.prev;
+    node.prev = undefined;
+    node.next = undefined;
+  }
+
+  private unlink(node: LruNode): void {
+    this.detach(node);
+    this.map.delete(node.key);
+    this.bytes -= node.bytes;
+    for (const owned of node.tags) {
+      deindex(this.tagIndex, serializeTag(owned), node.key);
+      deindex(this.entityIndex, owned.entity, node.key);
+    }
+  }
+}
+
+export function createLruTier(options: LruOptions = {}): CacheTier & { readonly cache: LruCache } {
+  const cache = new LruCache(options);
+  return {
+    name: 'lru',
+    cache,
+    get<T>(key: string) {
+      return Promise.resolve(cache.get<T>(key));
+    },
+    set<T>(key: string, value: T, setOptions?: CacheSetOptions) {
+      cache.set(key, value, setOptions ?? {});
+      return Promise.resolve();
+    },
+    del(key: string) {
+      cache.del(key);
+      return Promise.resolve();
+    },
+    invalidateTags(tags: readonly CacheTag[]): Promise<TierInvalidation> {
+      return Promise.resolve({ tier: 'lru', keys: cache.invalidateTags(tags) });
+    },
+  };
+}

package/src/memo.ts

@@ -0,0 +1,83 @@
+// Tier 0: per-request memoization. Keyed off the ALS context object itself via a WeakMap,
+// so the store dies with the request — there is no `clear()` to forget, no cross-request
+// leak, and no lifecycle for an agent to get wrong. Outside a request (worker boot, a
+// script) the tier degrades to a no-op rather than throwing: memoization is never required
+// for correctness.
+
+import type { Ctx } from '@ultimat3/core';
+import { useContext } from '@ultimat3/core';
+import type { CacheTag } from './tags';
+import { tagsIntersect } from './tags';
+import type { CacheEntry, CacheSetOptions, CacheTier, TierInvalidation } from './tiers';
+
+type MemoStore = Map<string, CacheEntry<unknown>>;
+
+const stores = new WeakMap<object, MemoStore>();
+
+function currentCtx(): object | undefined {
+  try {
+    const ctx: Ctx = useContext();
+    return typeof ctx === 'object' && ctx !== null ? (ctx as object) : undefined;
+  } catch {
+    // No ambient context: not a request. Nothing to memoize against.
+    return undefined;
+  }
+}
+
+function storeFor(create: boolean): MemoStore | undefined {
+  const ctx = currentCtx();
+  if (ctx === undefined) return undefined;
+  const existing = stores.get(ctx);
+  if (existing !== undefined) return existing;
+  if (!create) return undefined;
+  const fresh: MemoStore = new Map();
+  stores.set(ctx, fresh);
+  return fresh;
+}
+
+/** Escape hatch for `x dev`'s long-lived contexts; a normal request never calls this. */
+export function clearMemo(): void {
+  const ctx = currentCtx();
+  if (ctx !== undefined) stores.delete(ctx);
+}
+
+export function memoSize(): number {
+  return storeFor(false)?.size ?? 0;
+}
+
+export function createMemoTier(): CacheTier {
+  return {
+    name: 'request-memo',
+
+    get<T>(key: string): Promise<CacheEntry<T> | undefined> {
+      const entry = storeFor(false)?.get(key);
+      // No TTL check: a request is shorter than any meaningful TTL.
+      return Promise.resolve(entry as CacheEntry<T> | undefined);
+    },
+
+    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void> {
+      storeFor(true)?.set(key, { value, tags: options?.tags ?? [] });
+      return Promise.resolve();
+    },
+
+    del(key: string): Promise<void> {
+      storeFor(false)?.delete(key);
+      return Promise.resolve();
+    },
+
+    invalidateTags(tags: readonly CacheTag[]): Promise<TierInvalidation> {
+      const store = storeFor(false);
+      if (store === undefined) {
+        return Promise.resolve({ tier: 'request-memo', keys: [], skipped: 'no request context' });
+      }
+      const keys: string[] = [];
+      for (const [key, entry] of store) {
+        if (tagsIntersect(tags, entry.tags)) {
+          store.delete(key);
+          keys.push(key);
+        }
+      }
+      return Promise.resolve({ tier: 'request-memo', keys });
+    },
+  };
+}

package/src/purge-cloudflare.ts

@@ -0,0 +1,138 @@
+// Single responsibility: Cloudflare's cache-tag purge. One `POST /zones/<id>/purge_cache` per
+// batch of tags, the same call with `purge_everything` for the whole zone. Cloudflare's cache
+// tags ARE Ultimate's wire tags, so a `Cache-Tag` response header and an `invalidates: [tag.post]`
+// name the same string — the alternative, purging by URL, would need a route list nobody keeps.
+
+import type { PurgeDriver } from './cdn';
+import { CachePurgeFailedError } from './errors';
+import type { PurgeFetch } from './purge-http';
+import {
+  assertPurgeableKeys,
+  chunked,
+  DEFAULT_PURGE_TIMEOUT_MS,
+  defaultPurgeFetch,
+  detailFrom,
+  isRecord,
+  isRetryableStatus,
+  purgeBody,
+  purgePost,
+  requireCredential,
+} from './purge-http';
+
+export const CLOUDFLARE_API_URL = 'https://api.cloudflare.com/client/v4';
+
+/** Cloudflare takes 30 cache tags per purge call; a longer list is more requests, not a refusal. */
+export const CLOUDFLARE_MAX_TAGS_PER_REQUEST = 30;
+
+export interface CloudflarePurgeOptions {
+  /** Read from `CLOUDFLARE_API_TOKEN`; needs the zone "Cache Purge" permission. */
+  readonly apiToken: string;
+  /** Read from `CLOUDFLARE_ZONE_ID` — the zone this deployment is served from. */
+  readonly zoneId: string;
+  /** Override for a proxy or a test double. Defaults to `CLOUDFLARE_API_URL`. */
+  readonly baseUrl?: string | undefined;
+  readonly timeoutMs?: number | undefined;
+  /** Injected in tests; production uses the global. */
+  readonly fetch?: PurgeFetch | undefined;
+}
+
+// Every branch names the env key to edit, the call to narrow, or a command to run. The 429 named
+// none of them: the ceiling is per zone and not raisable from here, so the only lever is the
+// `invalidates` list that decides how many 30-tag requests one write sends. `retryable` already
+// says the same purge can land — the fix is what stops the next write hitting the wall again.
+const fixFor = (status: number): string => {
+  if (status === 401 || status === 403) {
+    return 'set CLOUDFLARE_API_TOKEN in .env.production to a token holding the zone "Cache Purge" permission';
+  }
+  if (status === 400) {
+    return 'unset CLOUDFLARE_API_TOKEN in .env.production to purge nothing — purge by cache tag needs an Enterprise zone';
+  }
+  if (status === 404) {
+    return 'set CLOUDFLARE_ZONE_ID in .env.production to the zone id on the Cloudflare dashboard overview page';
+  }
+  if (status === 429) {
+    return "narrow the action's cache.invalidates to fewer tag(...) entries — the zone allows 1000 purge calls per minute";
+  }
+  return 'curl -sS -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" https://api.cloudflare.com/client/v4/zones/$CLOUDFLARE_ZONE_ID';
+};
+
+/** Cloudflare's own errors, when it sent any: `{"errors":[{"code":1122,"message":"…"}]}`. */
+function messagesFrom(payload: unknown): string | undefined {
+  if (!isRecord(payload)) return undefined;
+  const errors = payload['errors'];
+  if (!Array.isArray(errors) || errors.length === 0) return undefined;
+  const messages = errors
+    .map((entry) =>
+      isRecord(entry) && typeof entry['message'] === 'string' ? entry['message'] : undefined,
+    )
+    .filter((message): message is string => message !== undefined);
+  return messages.length > 0 ? messages.join('; ') : undefined;
+}
+
+export function cloudflarePurgeDriver(options: CloudflarePurgeOptions): PurgeDriver {
+  const apiToken = requireCredential(options.apiToken, 'CLOUDFLARE_API_TOKEN', 'cloudflare');
+  const zoneId = requireCredential(options.zoneId, 'CLOUDFLARE_ZONE_ID', 'cloudflare');
+  const baseUrl = options.baseUrl ?? CLOUDFLARE_API_URL;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_PURGE_TIMEOUT_MS;
+  const doFetch = options.fetch ?? defaultPurgeFetch;
+  const headers = { Authorization: `Bearer ${apiToken}` };
+
+  const post = (body: unknown): Promise<Response> =>
+    purgePost({
+      driver: 'cloudflare',
+      url: `${baseUrl}/zones/${zoneId}/purge_cache`,
+      headers,
+      body,
+      fetch: doFetch,
+      timeoutMs,
+    });
+
+  /**
+   * Cloudflare answers a refusal with HTTP 200 and `"success": false`, so `response.ok` alone
+   * would read a rejected purge as a completed one and leave the edge stale with no failure
+   * anywhere. Both halves are checked, and only here.
+   */
+  const settle = async (response: Response): Promise<void> => {
+    const body = await purgeBody(response);
+    if (!response.ok) {
+      throw new CachePurgeFailedError({
+        driver: 'cloudflare',
+        detail: messagesFrom(body.json) ?? detailFrom(body),
+        status: response.status,
+        retryable: isRetryableStatus(response.status),
+        fix: fixFor(response.status),
+      });
+    }
+    if (isRecord(body.json) && body.json['success'] === false) {
+      throw new CachePurgeFailedError({
+        driver: 'cloudflare',
+        detail:
+          messagesFrom(body.json) ?? 'the api answered 200 with success: false and no message',
+        status: response.status,
+        retryable: false,
+        fix: fixFor(400),
+      });
+    }
+  };
+
+  return {
+    name: 'cloudflare',
+
+    async purge(keys: readonly string[]): Promise<readonly string[]> {
+      if (keys.length === 0) return [];
+      assertPurgeableKeys('cloudflare', keys);
+      const accepted: string[] = [];
+      // Sequential on purpose: the zone rate-limits purges, and nothing downstream reads a
+      // purge before it lands, so parallelism would buy latency the caller never waits on.
+      for (const batch of chunked('cloudflare', keys, CLOUDFLARE_MAX_TAGS_PER_REQUEST)) {
+        await settle(await post({ tags: batch }));
+        accepted.push(...batch);
+      }
+      return accepted;
+    },
+
+    async purgeAll(): Promise<void> {
+      await settle(await post({ purge_everything: true }));
+    },
+  };
+}

package/src/purge-env.ts

@@ -0,0 +1,109 @@
+// Single responsibility: environment → purge driver. The one place that decides which CDN a boot
+// purges against, so `x dev`, a worker container and any custom host resolve it identically. Keyed
+// on env rather than an `app.config.ts` field because nothing loads that file's contents at
+// runtime — a `cache.cdn` block would be a setting no boot could read.
+
+import { ConfigInvalidError } from '@ultimat3/core';
+import type { PurgeDriver } from './cdn';
+import { noopPurgeDriver } from './cdn';
+import { cloudflarePurgeDriver } from './purge-cloudflare';
+import { fastlyPurgeDriver } from './purge-fastly';
+
+/** The keys read here, and nothing else. Named once so docs and tests cannot drift from the code. */
+export const CDN_PURGE_ENV_KEYS = [
+  'FASTLY_API_TOKEN',
+  'FASTLY_SERVICE_ID',
+  'CLOUDFLARE_API_TOKEN',
+  'CLOUDFLARE_ZONE_ID',
+] as const;
+
+export type PurgeEnvironment = Readonly<Record<string, string | undefined>>;
+
+export interface PurgeSelection {
+  readonly driver: PurgeDriver;
+  /**
+   * Why this driver, in one line: the env key that selected it, or what to set to change it.
+   * A boot prints it, so "does this replica purge anything" is never a guess. The key's name
+   * only — `FASTLY_API_TOKEN` holds a credential, and this string reaches a log.
+   */
+  readonly detail: string;
+}
+
+const nonEmpty = (value: string | undefined): string | undefined =>
+  value === undefined || value.trim().length === 0 ? undefined : value.trim();
+
+/**
+ * The keys this environment actually set, in declaration order. Read rather than assumed, because
+ * the refusal below reaches a JSON diagnostic: a hardcoded token pair sends an operator who set
+ * only `FASTLY_SERVICE_ID` and `CLOUDFLARE_ZONE_ID` to look at two variables they never set.
+ * Names only — every one of these four keys may hold a credential.
+ */
+const configuredKeys = (env: PurgeEnvironment): readonly string[] =>
+  CDN_PURGE_ENV_KEYS.filter((key) => nonEmpty(env[key]) !== undefined);
+
+/** A driver that reaches no CDN, so a caller can report "purges nothing" without a name match. */
+export const isNoopPurgeDriver = (driver: PurgeDriver): boolean => driver.name === 'noop';
+
+/**
+ * Either key selects its provider, and the other is then required: a `FASTLY_SERVICE_ID` with no
+ * token is a half-finished deploy, and treating it as "no CDN" is how an environment ships
+ * believing it purges. The pair is named in the cause, so the missing half is the fix.
+ */
+function requirePair(env: PurgeEnvironment, selectedBy: string, missingKey: string): string {
+  const value = nonEmpty(env[missingKey]);
+  if (value === undefined) {
+    throw new ConfigInvalidError({
+      cause: `${selectedBy} selects a CDN purge driver, but ${missingKey} is unset — the pair is incomplete`,
+      fix: `set ${missingKey} in .env.production, or unset ${selectedBy} to purge nothing`,
+      meta: { selectedBy, missing: missingKey },
+    });
+  }
+  return value;
+}
+
+/**
+ * A credential selects its CDN; no credential purges nothing, which is the honest default for a
+ * process with no edge in front of it. Two CDNs at once is refused rather than resolved: whichever
+ * this picked would be the one an operator did not mean half the time, and the other edge would
+ * serve a stale page nobody can explain.
+ */
+export function selectPurgeDriver(env: PurgeEnvironment): PurgeSelection {
+  const fastlyKey = nonEmpty(env['FASTLY_API_TOKEN']) ?? nonEmpty(env['FASTLY_SERVICE_ID']);
+  const cloudflareKey =
+    nonEmpty(env['CLOUDFLARE_API_TOKEN']) ?? nonEmpty(env['CLOUDFLARE_ZONE_ID']);
+
+  if (fastlyKey !== undefined && cloudflareKey !== undefined) {
+    const configured = configuredKeys(env);
+    throw new ConfigInvalidError({
+      cause: `two CDNs claim the same purge: ${configured.join(', ')} are set`,
+      fix: 'unset one pair in .env.production: a process purges exactly one edge',
+      meta: { configured },
+    });
+  }
+
+  if (fastlyKey !== undefined) {
+    return {
+      driver: fastlyPurgeDriver({
+        apiToken: requirePair(env, 'FASTLY_SERVICE_ID', 'FASTLY_API_TOKEN'),
+        serviceId: requirePair(env, 'FASTLY_API_TOKEN', 'FASTLY_SERVICE_ID'),
+      }),
+      detail: 'FASTLY_API_TOKEN',
+    };
+  }
+
+  if (cloudflareKey !== undefined) {
+    return {
+      driver: cloudflarePurgeDriver({
+        apiToken: requirePair(env, 'CLOUDFLARE_ZONE_ID', 'CLOUDFLARE_API_TOKEN'),
+        zoneId: requirePair(env, 'CLOUDFLARE_API_TOKEN', 'CLOUDFLARE_ZONE_ID'),
+      }),
+      detail: 'CLOUDFLARE_API_TOKEN',
+    };
+  }
+
+  return {
+    driver: noopPurgeDriver(),
+    detail:
+      'no edge in front of this process — set FASTLY_API_TOKEN + FASTLY_SERVICE_ID, or CLOUDFLARE_API_TOKEN + CLOUDFLARE_ZONE_ID',
+  };
+}