《移动游戏产品的架构·网络、资源与热更新》1.3 mga-lab-net 的网络实验骨架与验收口径

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

export interface NetProbe {
  readonly id: string;
  readonly rttMs: readonly number[];
  readonly packetsSent: number;
  readonly packetsDelivered: number;
  readonly switches: number;
}

export type GateMetric = "rttP95" | "lossRatio";

export interface Gate {
  readonly metric: GateMetric;
  readonly max: number;
}

export interface ProbeResult {
  readonly id: string;
  readonly rttP50: number;
  readonly rttP95: number;
  readonly lossRatio: number;
  readonly switches: number;
  readonly weak: boolean;
  readonly passed: boolean;
  readonly failures: readonly string[];
}

export interface SuiteResult {
  readonly total: number;
  readonly passed: number;
  readonly failed: number;
  readonly failures: readonly string[];
}

export const DEFAULT_GATES: readonly Gate[] = [
  { metric: "rttP95", max: 300 },
  { metric: "lossRatio", max: 0.02 },
];

export const CASE_FIXTURES = {
  casual: {
    label: "潮汐消消",
    rttP50Ms: 78,
    rttP95Ms: 310,
    lossRatio: 0.004,
    weakShare: 0.22,
    disconnectRate: 0.021,
    reconnectRate: 0.972,
    supplementShare: 0.08,
    heartbeatCombatSeconds: 25,
    heartbeatLobbySeconds: 25,
    sessionTrafficMB: 3.2,
  },
  midcore: {
    label: "潮汐方舟",
    rttP50Ms: 62,
    rttP95Ms: 240,
    lossRatio: 0.006,
    weakShare: 0.14,
    disconnectRate: 0.014,
    reconnectRate: 0.981,
    supplementShare: 0.31,
    heartbeatCombatSeconds: 5,
    heartbeatLobbySeconds: 20,
    sessionTrafficMB: 18,
  },
} as const;

export function percentile(values: readonly number[], p: number): number {
  if (!Number.isFinite(p) || p <= 0 || p > 100) {
    throw new RangeError(`percentile must be in (0, 100], got ${p}`);
  }
  if (values.length === 0) {
    throw new Error("percentile needs at least one value");
  }
  for (const value of values) {
    if (!Number.isFinite(value) || value < 0) {
      throw new RangeError(`invalid sample value: ${value}`);
    }
  }
  const sorted = [...values].sort((a, b) => a - b);
  const rank = Math.ceil((p / 100) * sorted.length);
  return sorted[Math.min(rank, sorted.length) - 1];
}

export function runProbe(probe: NetProbe, gates: readonly Gate[] = DEFAULT_GATES): ProbeResult {
  if (probe.rttMs.length === 0) {
    throw new Error(`${probe.id}: rttMs must not be empty`);
  }
  if (!Number.isInteger(probe.packetsSent) || probe.packetsSent <= 0) {
    throw new RangeError(`${probe.id}: packetsSent must be a positive integer`);
  }
  if (
    !Number.isInteger(probe.packetsDelivered) ||
    probe.packetsDelivered < 0 ||
    probe.packetsDelivered > probe.packetsSent
  ) {
    throw new RangeError(`${probe.id}: packetsDelivered out of range`);
  }
  if (!Number.isInteger(probe.switches) || probe.switches < 0) {
    throw new RangeError(`${probe.id}: switches must be a non-negative integer`);
  }
  const rttP50 = percentile(probe.rttMs, 50);
  const rttP95 = percentile(probe.rttMs, 95);
  const lossRatio = 1 - probe.packetsDelivered / probe.packetsSent;
  const metrics: Record<GateMetric, number> = {
    rttP95,
    lossRatio,
  };
  const failures: string[] = [];
  for (const gate of gates) {
    const value = metrics[gate.metric];
    if (value > gate.max) {
      failures.push(`${gate.metric}=${value.toFixed(4)}>${gate.max}`);
    }
  }
  return {
    id: probe.id,
    rttP50,
    rttP95,
    lossRatio,
    switches: probe.switches,
    weak: rttP95 > 300 || lossRatio > 0.02,
    passed: failures.length === 0,
    failures,
  };
}

export function evaluateSuite(results: readonly ProbeResult[]): SuiteResult {
  const failures = results
    .filter((result) => !result.passed)
    .map((result) => `${result.id}:${result.failures.join(",")}`);
  return {
    total: results.length,
    passed: results.length - failures.length,
    failed: failures.length,
    failures,
  };
}

export function formatReport(results: readonly ProbeResult[]): string {
  const header = "probe\trttP50\trttP95\tloss\tweak\tswitches\tpassed";
  const rows = results.map((result) =>
    [
      result.id,
      `${result.rttP50}ms`,
      `${result.rttP95}ms`,
      `${(result.lossRatio * 100).toFixed(2)}%`,
      result.weak ? "yes" : "no",
      String(result.switches),
      result.passed ? "yes" : "no",
    ].join("\t"),
  );
  return [header, ...rows].join("\n");
}

probe	rttP50	rttP95	loss	weak	switches	passed
casual-probe	78ms	120ms	0.40%	no	1	yes