《移动游戏产品的架构·客户端与移动运行时》6.3 资源泄漏定位与回归

// file: src/resource/cache.ts
// tier: L1
// verify: node --test test/resource/cache.test.ts

import { fail, ok, type Result } from "../core/result.ts";

export type CacheError = "invalid-size" | "missing-key" | "capacity-exhausted";

export interface CacheOptions {
  readonly pinned?: boolean;
  readonly refs?: number;
}

export interface CacheEntryView {
  readonly key: string;
  readonly sizeBytes: number;
  readonly refs: number;
  readonly pinned: boolean;
  readonly lastUsedTick: number;
}

export interface SnapshotEntry {
  readonly key: string;
  readonly sizeBytes: number;
  readonly refs: number;
  readonly pinned: boolean;
}

export interface CacheSnapshot {
  readonly totalBytes: number;
  readonly entries: readonly SnapshotEntry[];
}

export interface EvictionReport {
  readonly evictedKeys: readonly string[];
  readonly freedBytes: number;
  readonly totalBytes: number;
}

interface CacheEntry {
  sizeBytes: number;
  refs: number;
  pinned: boolean;
  lastUsedTick: number;
}

export class LruResourceCache {
  #capacityBytes: number;
  #entries = new Map<string, CacheEntry>();
  #tick = 0;

  constructor(capacityBytes: number) {
    if (!Number.isInteger(capacityBytes) || capacityBytes <= 0) {
      throw new RangeError(`capacityBytes must be a positive integer, got ${capacityBytes}`);
    }
    this.#capacityBytes = capacityBytes;
  }

  get capacityBytes(): number {
    return this.#capacityBytes;
  }

  get totalBytes(): number {
    let sum = 0;
    for (const entry of this.#entries.values()) sum += entry.sizeBytes;
    return sum;
  }

  put(key: string, sizeBytes: number, options: CacheOptions = {}): Result<CacheEntryView, CacheError> {
    if (!Number.isInteger(sizeBytes) || sizeBytes < 0) return fail("invalid-size", `${key}: ${sizeBytes}`);
    if (sizeBytes > this.#capacityBytes) {
      return fail("capacity-exhausted", `${key}: ${sizeBytes} > ${this.#capacityBytes}`);
    }
    const existing = this.#entries.get(key);
    const projected = this.totalBytes - (existing?.sizeBytes ?? 0) + sizeBytes;
    const victims = this.#pickVictims(projected, key);
    if (victims === null) return fail("capacity-exhausted", `${key}: protected entries fill the cache`);

    for (const victim of victims) this.#entries.delete(victim);
    this.#tick += 1;
    this.#entries.set(key, {
      sizeBytes,
      refs: options.refs ?? existing?.refs ?? 0,
      pinned: options.pinned ?? existing?.pinned ?? false,
      lastUsedTick: this.#tick,
    });
    return ok(this.#view(key));
  }

  get(key: string): CacheEntryView | null {
    const entry = this.#entries.get(key);
    if (entry === undefined) return null;
    this.#tick += 1;
    entry.lastUsedTick = this.#tick;
    return this.#view(key);
  }

  peek(key: string): CacheEntryView | null {
    return this.#entries.has(key) ? this.#view(key) : null;
  }

  retain(key: string): Result<CacheEntryView, CacheError> {
    const entry = this.#entries.get(key);
    if (entry === undefined) return fail("missing-key", key);
    entry.refs += 1;
    return ok(this.#view(key));
  }

  release(key: string): Result<CacheEntryView, CacheError> {
    const entry = this.#entries.get(key);
    if (entry === undefined) return fail("missing-key", key);
    entry.refs = Math.max(0, entry.refs - 1);
    return ok(this.#view(key));
  }

  setPinned(key: string, pinned: boolean): Result<CacheEntryView, CacheError> {
    const entry = this.#entries.get(key);
    if (entry === undefined) return fail("missing-key", key);
    entry.pinned = pinned;
    return ok(this.#view(key));
  }

  evict(key: string): Result<number, CacheError> {
    const entry = this.#entries.get(key);
    if (entry === undefined) return fail("missing-key", key);
    if (entry.pinned || entry.refs > 0) return fail("capacity-exhausted", `${key}: protected`);
    this.#entries.delete(key);
    return ok(entry.sizeBytes);
  }

  trim(): EvictionReport {
    const candidates = [...this.#entries.entries()]
      .filter(([, entry]) => !entry.pinned && entry.refs === 0)
      .sort((a, b) => a[1].lastUsedTick - b[1].lastUsedTick || a[0].localeCompare(b[0]));
    const victims: string[] = [];
    let remaining = this.totalBytes;
    for (const [key, entry] of candidates) {
      if (remaining <= this.#capacityBytes) break;
      victims.push(key);
      remaining -= entry.sizeBytes;
    }
    return this.#remove(victims);
  }

  dropUnreferenced(): EvictionReport {
    const keys = [...this.#entries.entries()]
      .filter(([, entry]) => !entry.pinned && entry.refs === 0)
      .map(([key]) => key)
      .sort();
    return this.#remove(keys);
  }

  snapshot(): CacheSnapshot {
    const entries = [...this.#entries.entries()]
      .map(([key, entry]) => ({ key, sizeBytes: entry.sizeBytes, refs: entry.refs, pinned: entry.pinned }))
      .sort((a, b) => a.key.localeCompare(b.key));
    return { totalBytes: this.totalBytes, entries };
  }

  #remove(keys: readonly string[]): EvictionReport {
    let freedBytes = 0;
    for (const key of keys) {
      freedBytes += this.#entries.get(key)?.sizeBytes ?? 0;
      this.#entries.delete(key);
    }
    return { evictedKeys: [...keys], freedBytes, totalBytes: this.totalBytes };
  }

  #pickVictims(projected: number, protectedKey: string | null): string[] | null {
    if (projected <= this.#capacityBytes) return [];
    const candidates = [...this.#entries.entries()]
      .filter(([key, entry]) => key !== protectedKey && !entry.pinned && entry.refs === 0)
      .sort((a, b) => a[1].lastUsedTick - b[1].lastUsedTick || a[0].localeCompare(b[0]));
    let remaining = projected;
    const victims: string[] = [];
    for (const [key, entry] of candidates) {
      victims.push(key);
      remaining -= entry.sizeBytes;
      if (remaining <= this.#capacityBytes) return victims;
    }
    return null;
  }

  #view(key: string): CacheEntryView {
    const entry = this.#entries.get(key);
    if (entry === undefined) throw new Error(`missing cache entry: ${key}`);
    return {
      key,
      sizeBytes: entry.sizeBytes,
      refs: entry.refs,
      pinned: entry.pinned,
      lastUsedTick: entry.lastUsedTick,
    };
  }
}

export interface SizeChange {
  readonly key: string;
  readonly beforeBytes: number;
  readonly afterBytes: number;
}

export interface SnapshotDiff {
  readonly added: readonly string[];
  readonly removed: readonly string[];
  readonly grew: readonly SizeChange[];
  readonly shrank: readonly SizeChange[];
  readonly byteDelta: number;
}

export function diffSnapshots(before: CacheSnapshot, after: CacheSnapshot): SnapshotDiff {
  const beforeMap = new Map(before.entries.map((entry) => [entry.key, entry.sizeBytes]));
  const afterMap = new Map(after.entries.map((entry) => [entry.key, entry.sizeBytes]));
  const added = [...afterMap.keys()].filter((key) => !beforeMap.has(key)).sort();
  const removed = [...beforeMap.keys()].filter((key) => !afterMap.has(key)).sort();
  const grew: SizeChange[] = [];
  const shrank: SizeChange[] = [];
  for (const [key, beforeBytes] of beforeMap) {
    const afterBytes = afterMap.get(key);
    if (afterBytes === undefined || afterBytes === beforeBytes) continue;
    const change = { key, beforeBytes, afterBytes };
    if (afterBytes > beforeBytes) grew.push(change);
    else shrank.push(change);
  }
  grew.sort((a, b) => a.key.localeCompare(b.key));
  shrank.sort((a, b) => a.key.localeCompare(b.key));
  return {
    added,
    removed,
    grew,
    shrank,
    byteDelta: after.totalBytes - before.totalBytes,
  };
}

export interface LeakReport {
  readonly scene: string;
  readonly ok: boolean;
  readonly byteDelta: number;
  readonly diff: SnapshotDiff;
}

export class SceneLeakGuard {
  #baselines = new Map<string, CacheSnapshot>();

  mark(scene: string, snapshot: CacheSnapshot): void {
    this.#baselines.set(scene, snapshot);
  }

  hasBaseline(scene: string): boolean {
    return this.#baselines.has(scene);
  }

  check(scene: string, snapshot: CacheSnapshot, toleranceBytes = 0): LeakReport {
    const baseline = this.#baselines.get(scene);
    if (baseline === undefined) throw new Error(`no baseline for scene: ${scene}`);
    const diff = diffSnapshots(baseline, snapshot);
    const leaked = diff.added.length > 0 || diff.grew.length > 0;
    const overTolerance = diff.byteDelta > toleranceBytes;
    return { scene, ok: !leaked && !overTolerance, byteDelta: diff.byteDelta, diff };
  }
}