《移动游戏产品的架构·网络、资源与热更新》1.1 弱网、切换与丢包：客户端要面对的三种网络

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

export interface NetSample {
  readonly rttMs: number;
  readonly sent: number;
  readonly delivered: number;
  readonly switched: boolean;
}

export type QualityVerdict = "normal" | "weak";

export interface SessionProfile {
  readonly samples: number;
  readonly rttP50: number;
  readonly rttP95: number;
  readonly lossRatio: number;
  readonly switches: number;
  readonly weak: boolean;
  readonly reasons: readonly string[];
}

export const WEAK_NETWORK_THRESHOLDS = {
  rttP95Ms: 300,
  lossRatio: 0.02,
} 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 profileSession(samples: readonly NetSample[]): SessionProfile {
  if (samples.length === 0) {
    throw new Error("profileSession needs at least one sample");
  }
  const rtts: number[] = [];
  let sent = 0;
  let delivered = 0;
  let switches = 0;
  for (const sample of samples) {
    if (!Number.isFinite(sample.rttMs) || sample.rttMs < 0) {
      throw new RangeError(`invalid rtt: ${sample.rttMs}`);
    }
    if (!Number.isInteger(sample.sent) || sample.sent <= 0) {
      throw new RangeError(`sent must be a positive integer, got ${sample.sent}`);
    }
    if (!Number.isInteger(sample.delivered) || sample.delivered < 0 || sample.delivered > sample.sent) {
      throw new RangeError(`delivered out of range: ${sample.delivered}/${sample.sent}`);
    }
    rtts.push(sample.rttMs);
    sent += sample.sent;
    delivered += sample.delivered;
    if (sample.switched) {
      switches += 1;
    }
  }
  const lossRatio = sent === 0 ? 0 : 1 - delivered / sent;
  const rttP50 = percentile(rtts, 50);
  const rttP95 = percentile(rtts, 95);
  const reasons: string[] = [];
  if (rttP95 > WEAK_NETWORK_THRESHOLDS.rttP95Ms) {
    reasons.push("rtt_p95>300ms");
  }
  if (lossRatio > WEAK_NETWORK_THRESHOLDS.lossRatio) {
    reasons.push("loss>2%");
  }
  return {
    samples: samples.length,
    rttP50,
    rttP95,
    lossRatio,
    switches,
    weak: reasons.length > 0,
    reasons,
  };
}

export function classifyQuality(profile: SessionProfile): QualityVerdict {
  return profile.weak ? "weak" : "normal";
}

export function describeProfile(profile: SessionProfile): string {
  const lossPct = (profile.lossRatio * 100).toFixed(2);
  const verdict = classifyQuality(profile);
  const reason = profile.reasons.length === 0 ? "within-threshold" : profile.reasons.join("+");
  return `rtt p50=${profile.rttP50}ms p95=${profile.rttP95}ms loss=${lossPct}% switches=${profile.switches} verdict=${verdict} reason=${reason}`;
}

export function weakSessionShare(profiles: readonly SessionProfile[]): number {
  if (profiles.length === 0) {
    throw new Error("weakSessionShare needs at least one profile");
  }
  const weak = profiles.filter((profile) => profile.weak).length;
  return weak / profiles.length;
}

rtt p50=78ms p95=310ms loss=0.40% switches=1 verdict=weak reason=rtt_p95>300ms