《移动游戏产品的架构·网络、资源与热更新》7.3 流量预算与弱网适配

// file: src/net/traffic-budget.ts
// tier: L1
// verify: node --test test/net/traffic-budget.test.ts

export const TIERS = ["core", "optional", "diagnostic"] as const;

export type Tier = (typeof TIERS)[number];

export type TierBytes = Readonly<Record<Tier, number>>;

export interface Budget {
  readonly dailyBytes: number;
  readonly caps: TierBytes;
  readonly spent: TierBytes;
}

export interface ChargeResult {
  readonly budget: Budget;
  readonly accepted: number;
  readonly rejected: number;
  readonly reason: "accepted" | "partial" | "capped";
}

export interface NetworkSample {
  readonly rttP95Ms: number;
  readonly lossRate: number;
}

export interface NetworkPolicy {
  readonly weakRttMs: number;
  readonly weakLossRate: number;
  readonly severeRttMs: number;
  readonly severeLossRate: number;
}

export type DegradeLevel = 0 | 1 | 2;

const DEFAULT_NETWORK_POLICY: NetworkPolicy = {
  weakRttMs: 300,
  weakLossRate: 0.02,
  severeRttMs: 600,
  severeLossRate: 0.04,
};

const DEFAULT_SHARES: TierBytes = { core: 0.7, optional: 0.25, diagnostic: 0.05 };

function formatBytes(bytes: number): string {
  if (bytes < 1024) {
    return `${bytes} B`;
  }
  if (bytes < 1024 * 1024) {
    return `${(bytes / 1024).toFixed(1)} KB`;
  }
  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
}

export function createBudget(dailyBytes: number, shares: TierBytes = DEFAULT_SHARES): Budget {
  if (!Number.isInteger(dailyBytes) || dailyBytes <= 0) {
    throw new RangeError(`daily budget must be a positive integer: ${dailyBytes}`);
  }
  const total = shares.core + shares.optional + shares.diagnostic;
  if (Math.abs(total - 1) > 1e-9) {
    throw new RangeError(`tier shares must sum to 1: ${total}`);
  }
  if (shares.core < 0 || shares.optional < 0 || shares.diagnostic < 0) {
    throw new RangeError("tier shares must be non-negative");
  }
  const core = Math.floor(dailyBytes * shares.core);
  const optional = Math.floor(dailyBytes * shares.optional);
  const diagnostic = dailyBytes - core - optional;
  return {
    dailyBytes,
    caps: { core, optional, diagnostic },
    spent: { core: 0, optional: 0, diagnostic: 0 },
  };
}

export function charge(budget: Budget, tier: Tier, bytes: number): ChargeResult {
  if (!Number.isInteger(bytes) || bytes < 0) {
    throw new RangeError(`charge bytes must be a non-negative integer: ${bytes}`);
  }
  const cap = budget.caps[tier];
  const spent = budget.spent[tier];
  const available = Math.max(0, cap - spent);
  const accepted = Math.min(bytes, available);
  const rejected = bytes - accepted;
  const reason: ChargeResult["reason"] =
    rejected === 0 ? "accepted" : accepted === 0 ? "capped" : "partial";
  return {
    budget: {
      dailyBytes: budget.dailyBytes,
      caps: budget.caps,
      spent: { ...budget.spent, [tier]: spent + accepted },
    },
    accepted,
    rejected,
    reason,
  };
}

export interface RemainingReport {
  readonly total: number;
  readonly byTier: TierBytes;
}

export function remainingBytes(budget: Budget): RemainingReport {
  const byTier: Record<Tier, number> = {
    core: budget.caps.core - budget.spent.core,
    optional: budget.caps.optional - budget.spent.optional,
    diagnostic: budget.caps.diagnostic - budget.spent.diagnostic,
  };
  return {
    total: byTier.core + byTier.optional + byTier.diagnostic,
    byTier,
  };
}

export interface NetworkPlan {
  readonly level: DegradeLevel;
  readonly allowed: readonly Tier[];
}

export function planForNetwork(
  sample: NetworkSample,
  policy: NetworkPolicy = DEFAULT_NETWORK_POLICY,
): NetworkPlan {
  if (!Number.isFinite(sample.rttP95Ms) || sample.rttP95Ms < 0) {
    throw new RangeError(`RTT P95 must be non-negative: ${sample.rttP95Ms}`);
  }
  if (!Number.isFinite(sample.lossRate) || sample.lossRate < 0 || sample.lossRate > 1) {
    throw new RangeError(`loss rate must be within 0..1: ${sample.lossRate}`);
  }
  let level: DegradeLevel = 0;
  if (sample.rttP95Ms > policy.weakRttMs || sample.lossRate > policy.weakLossRate) {
    level = 1;
  }
  if (sample.rttP95Ms > policy.severeRttMs || sample.lossRate > policy.severeLossRate) {
    level = 2;
  }
  const allowed: readonly Tier[] = level === 0 ? TIERS : level === 1 ? ["core", "optional"] : ["core"];
  return { level, allowed };
}

export function describeBudget(budget: Budget): string {
  const remaining = remainingBytes(budget);
  return `日预算 ${formatBytes(budget.dailyBytes)}，已用 ${formatBytes(budget.dailyBytes - remaining.total)}，剩余 ${formatBytes(remaining.total)}（core ${formatBytes(remaining.byTier.core)}，optional ${formatBytes(remaining.byTier.optional)}，diagnostic ${formatBytes(remaining.byTier.diagnostic)}）`;
}