《移动游戏产品的架构·网络、资源与热更新》12.2 CDN 选型与回源策略

hit ≈ ttl / (ttl + revisit)

// file: src/cdn/cdn-plan.ts
// tier: L1
// verify: node --test test/cdn/cdn-plan.test.ts

export type ObjectKind = "bundle" | "manifest" | "hotfix" | "api";
export type CacheMode = "immutable" | "revalidate" | "no-store";

export interface CdnObject {
  readonly path: string;
  readonly kind: ObjectKind;
  readonly bytes: number;
  readonly requests: number;
}

export interface CachePolicy {
  readonly immutableTtlSeconds: number;
  readonly manifestTtlSeconds: number;
  readonly respectRange: boolean;
}

export const DEFAULT_POLICY: CachePolicy = {
  immutableTtlSeconds: 30 * 24 * 60 * 60,
  manifestTtlSeconds: 120,
  respectRange: true,
};

export interface KindSummary {
  readonly kind: ObjectKind;
  readonly objects: number;
  readonly totalBytes: number;
  readonly edgeBytes: number;
  readonly originBytes: number;
  readonly hitRatio: number;
}

export interface CachePlan {
  readonly byKind: readonly KindSummary[];
  readonly totalBytes: number;
  readonly edgeBytes: number;
  readonly originBytes: number;
  readonly hitRatio: number;
  readonly rangesSupported: boolean;
}

export interface Vendor {
  readonly id: string;
  readonly weight: number;
  readonly unitCostPerGb: number;
}

export interface VendorShare {
  readonly id: string;
  readonly share: number;
  readonly originBytes: number;
  readonly cost: number;
}

const GIB = 1024 ** 3;
const KINDS: readonly ObjectKind[] = ["bundle", "manifest", "hotfix", "api"];

export function cacheModeFor(kind: ObjectKind): CacheMode {
  switch (kind) {
    case "bundle":
      return "immutable";
    case "manifest":
    case "hotfix":
      return "revalidate";
    case "api":
      return "no-store";
    default:
      throw new Error(`unknown object kind: ${String(kind)}`);
  }
}

export function estimateHitRatio(ttlSeconds: number, revisitSeconds: number): number {
  if (!Number.isFinite(ttlSeconds) || ttlSeconds < 0) throw new Error(`invalid ttl: ${ttlSeconds}`);
  if (!Number.isFinite(revisitSeconds) || revisitSeconds <= 0) {
    throw new Error(`invalid revisit interval: ${revisitSeconds}`);
  }
  if (ttlSeconds === 0) return 0;
  return ttlSeconds / (ttlSeconds + revisitSeconds);
}

export function planCache(
  objects: readonly CdnObject[],
  policy: CachePolicy = DEFAULT_POLICY,
  revisitSeconds = 24 * 60 * 60,
): CachePlan {
  if (!Number.isInteger(policy.immutableTtlSeconds) || policy.immutableTtlSeconds < 1) {
    throw new Error(`invalid immutable ttl: ${policy.immutableTtlSeconds}`);
  }
  if (!Number.isInteger(policy.manifestTtlSeconds) || policy.manifestTtlSeconds < 0) {
    throw new Error(`invalid manifest ttl: ${policy.manifestTtlSeconds}`);
  }

  const totals = new Map<ObjectKind, { objects: number; totalBytes: number; edgeBytes: number }>();
  let totalBytes = 0;
  let edgeBytes = 0;

  for (const object of objects) {
    if (object.path.length === 0) throw new Error("object path must not be empty");
    if (!Number.isInteger(object.bytes) || object.bytes < 0) {
      throw new Error(`invalid bytes for ${object.path}: ${object.bytes}`);
    }
    if (!Number.isInteger(object.requests) || object.requests < 0) {
      throw new Error(`invalid requests for ${object.path}: ${object.requests}`);
    }

    const mode = cacheModeFor(object.kind);
    const ttl =
      mode === "immutable"
        ? policy.immutableTtlSeconds
        : mode === "revalidate"
          ? policy.manifestTtlSeconds
          : 0;
    const requested = object.bytes * object.requests;
    const hit = Math.round(requested * estimateHitRatio(ttl, revisitSeconds));

    const bucket = totals.get(object.kind) ?? { objects: 0, totalBytes: 0, edgeBytes: 0 };
    bucket.objects += 1;
    bucket.totalBytes += requested;
    bucket.edgeBytes += hit;
    totals.set(object.kind, bucket);
    totalBytes += requested;
    edgeBytes += hit;
  }

  const byKind: KindSummary[] = [];
  for (const kind of KINDS) {
    const bucket = totals.get(kind);
    if (bucket === undefined) continue;
    const originBytes = bucket.totalBytes - bucket.edgeBytes;
    byKind.push({
      kind,
      objects: bucket.objects,
      totalBytes: bucket.totalBytes,
      edgeBytes: bucket.edgeBytes,
      originBytes,
      hitRatio: bucket.totalBytes === 0 ? 0 : bucket.edgeBytes / bucket.totalBytes,
    });
  }

  return {
    byKind,
    totalBytes,
    edgeBytes,
    originBytes: totalBytes - edgeBytes,
    hitRatio: totalBytes === 0 ? 0 : edgeBytes / totalBytes,
    rangesSupported: policy.respectRange,
  };
}

export function splitAcrossVendors(
  vendors: readonly Vendor[],
  originBytes: number,
): readonly VendorShare[] {
  if (vendors.length === 0) throw new Error("at least one vendor is required");
  if (!Number.isInteger(originBytes) || originBytes < 0) {
    throw new Error(`invalid origin bytes: ${originBytes}`);
  }

  const seen = new Set<string>();
  let weightSum = 0;
  for (const vendor of vendors) {
    if (vendor.id.length === 0) throw new Error("vendor id must not be empty");
    if (seen.has(vendor.id)) throw new Error(`duplicate vendor: ${vendor.id}`);
    seen.add(vendor.id);
    if (!Number.isFinite(vendor.weight) || vendor.weight <= 0) {
      throw new Error(`invalid weight for ${vendor.id}: ${vendor.weight}`);
    }
    if (!Number.isFinite(vendor.unitCostPerGb) || vendor.unitCostPerGb < 0) {
      throw new Error(`invalid unit cost for ${vendor.id}: ${vendor.unitCostPerGb}`);
    }
    weightSum += vendor.weight;
  }

  let assigned = 0;
  return vendors.map((vendor, index) => {
    const isLast = index === vendors.length - 1;
    const bytes = isLast ? originBytes - assigned : Math.round((originBytes * vendor.weight) / weightSum);
    assigned += bytes;
    return {
      id: vendor.id,
      share: vendor.weight / weightSum,
      originBytes: bytes,
      cost: Math.round(((bytes / GIB) * vendor.unitCostPerGb + Number.EPSILON) * 100) / 100,
    };
  });
}

export function formatCdnPlan(plan: CachePlan): string {
  const lines = ["kind\tobjects\trequestedB\tedgeB\toriginB\thit"];
  for (const row of plan.byKind) {
    lines.push(
      `${row.kind}\t${row.objects}\t${row.totalBytes}\t${row.edgeBytes}\t${row.originBytes}\t${(row.hitRatio * 100).toFixed(1)}%`,
    );
  }
  lines.push(
    `total=${plan.totalBytes}B edge=${plan.edgeBytes}B origin=${plan.originBytes}B hit=${(plan.hitRatio * 100).toFixed(1)}% range=${plan.rangesSupported}`,
  );
  return lines.join("\n");
}

kind	objects	requestedB	edgeB	originB	hit
bundle	1	10000	9677	323	96.8%
manifest	1	1000	1	999	0.1%
hotfix	1	1000	1	999	0.1%
api	1	1000	0	1000	0.0%
total=13000B edge=9679B origin=3321B hit=74.5% range=true