《互联网产品的客户端架构·规模化与架构演进》6.2 产物治理与缓存

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

import { createHash } from "node:crypto";

export type FileDigest = {
  path: string;
  size: number;
  hash: string;
};

export type ArtifactManifest = {
  files: FileDigest[];
  totalBytes: number;
  digest: string;
};

export type CacheKeyInput = {
  task: string;
  sourceHash: string;
  toolchain: string;
  env: Record<string, string>;
  deps: Record<string, string>;
};

export type CacheEntry = {
  key: string;
  createdAt: number;
  ttlMs?: number;
  manifest: ArtifactManifest;
};

export type CacheDecision = {
  status: "hit" | "miss";
  reason: "hit" | "no-entry" | "key-changed" | "expired" | "artifact-missing";
  missing: string[];
};

export type BudgetReport = {
  totalBytes: number;
  budgetBytes: number;
  overBy: number;
  withinBudget: boolean;
  largest: FileDigest[];
};

export function hashContent(content: string | Uint8Array): string {
  return createHash("sha256").update(content).digest("hex");
}

export function canonicalJson(value: unknown): string {
  if (value === null || typeof value !== "object") {
    return JSON.stringify(value);
  }
  if (Array.isArray(value)) {
    return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
  }
  const record = value as Record<string, unknown>;
  const keys = Object.keys(record).sort();
  const body = keys
    .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
    .join(",");
  return `{${body}}`;
}

export function hashFiles(files: Record<string, string>): FileDigest[] {
  return Object.keys(files)
    .sort()
    .map((path) => {
      const content = files[path];
      return {
        path,
        size: Buffer.byteLength(content, "utf8"),
        hash: hashContent(content),
      };
    });
}

export function buildCacheKey(input: CacheKeyInput): string {
  const canonical = canonicalJson({
    task: input.task,
    sourceHash: input.sourceHash,
    toolchain: input.toolchain,
    env: input.env,
    deps: input.deps,
  });
  return `${input.task}-${hashContent(canonical).slice(0, 16)}`;
}

export function buildManifest(files: Record<string, string>): ArtifactManifest {
  const digests = hashFiles(files);
  const totalBytes = digests.reduce((sum, item) => sum + item.size, 0);
  const digest = hashContent(canonicalJson(digests));
  return { files: digests, totalBytes, digest };
}

export function evaluateCache(
  entry: CacheEntry | undefined,
  desiredKey: string,
  existingFiles: Iterable<string>,
  now: number = Date.now(),
): CacheDecision {
  if (!entry) {
    return { status: "miss", reason: "no-entry", missing: [] };
  }
  if (entry.key !== desiredKey) {
    return { status: "miss", reason: "key-changed", missing: [] };
  }
  if (
    entry.ttlMs !== undefined &&
    now - entry.createdAt > entry.ttlMs
  ) {
    return { status: "miss", reason: "expired", missing: [] };
  }
  const present = new Set(existingFiles);
  const missing = entry.manifest.files
    .map((file) => file.path)
    .filter((path) => !present.has(path))
    .sort();
  if (missing.length > 0) {
    return { status: "miss", reason: "artifact-missing", missing };
  }
  return { status: "hit", reason: "hit", missing: [] };
}

export function verifyManifest(
  manifest: ArtifactManifest,
  actual: Record<string, { size: number; hash: string }>,
): string[] {
  const problems: string[] = [];
  const listed = new Set<string>();
  for (const file of manifest.files) {
    listed.add(file.path);
    const found = actual[file.path];
    if (!found) {
      problems.push(`missing:${file.path}`);
      continue;
    }
    if (found.size !== file.size) problems.push(`size:${file.path}`);
    if (found.hash !== file.hash) problems.push(`hash:${file.path}`);
  }
  for (const path of Object.keys(actual)) {
    if (!listed.has(path)) problems.push(`extra:${path}`);
  }
  return problems.sort();
}

export function checkSizeBudget(
  entries: FileDigest[],
  budgetBytes: number,
): BudgetReport {
  const totalBytes = entries.reduce((sum, entry) => sum + entry.size, 0);
  const largest = [...entries]
    .sort((a, b) => b.size - a.size || a.path.localeCompare(b.path))
    .slice(0, 3);
  return {
    totalBytes,
    budgetBytes,
    overBy: Math.max(0, totalBytes - budgetBytes),
    withinBudget: totalBytes <= budgetBytes,
    largest,
  };
}

node --test test/build/artifact-cache.test.ts

✔ 完整清单校验没有问题 (0.075709ms)
✔ 体积在预算内时报告通过 (0.099667ms)
✔ 体积超预算时报告超出字节 (0.045042ms)
✔ 内容变化改变清单摘要 (0.054334ms)
ℹ tests 21
ℹ suites 0
ℹ pass 21
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 154.792084