《移动游戏产品的架构·网络、资源与热更新》7.2 心跳、长连接与推送的取舍

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

export const SCENES = ["battle", "lobby", "background"] as const;

export type Scene = (typeof SCENES)[number];

export interface KeepaliveProfile {
  readonly scene: Scene;
  readonly intervalMs: number;
  readonly upstreamBytes: number;
  readonly downstreamBytes: number;
  readonly missedToDetect: number;
}

export interface HeartbeatPlan {
  readonly profile: KeepaliveProfile;
  readonly beats: number;
  readonly wireBytes: number;
  readonly detectionMs: number;
}

export type LinkState = "ok" | "suspect" | "dead";

export interface SilenceReport {
  readonly state: LinkState;
  readonly missed: number;
  readonly silentMs: number;
}

export interface ProfileInput {
  readonly scene: Scene;
  readonly intervalMs: number;
  readonly upstreamBytes: number;
  readonly downstreamBytes: number;
  readonly missedToDetect?: number;
}

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 defineProfile(input: ProfileInput): KeepaliveProfile {
  if (!Number.isInteger(input.intervalMs) || input.intervalMs <= 0) {
    throw new RangeError(`heartbeat interval must be a positive integer: ${input.intervalMs}`);
  }
  if (!Number.isInteger(input.upstreamBytes) || input.upstreamBytes < 0) {
    throw new RangeError(`upstream bytes must be a non-negative integer: ${input.upstreamBytes}`);
  }
  if (!Number.isInteger(input.downstreamBytes) || input.downstreamBytes < 0) {
    throw new RangeError(`downstream bytes must be a non-negative integer: ${input.downstreamBytes}`);
  }
  const missedToDetect = input.missedToDetect ?? 2;
  if (!Number.isInteger(missedToDetect) || missedToDetect <= 0) {
    throw new RangeError(`missed-to-detect must be a positive integer: ${missedToDetect}`);
  }
  return {
    scene: input.scene,
    intervalMs: input.intervalMs,
    upstreamBytes: input.upstreamBytes,
    downstreamBytes: input.downstreamBytes,
    missedToDetect,
  };
}

export function planSession(profile: KeepaliveProfile, activeMs: number): HeartbeatPlan {
  if (!Number.isInteger(activeMs) || activeMs < 0) {
    throw new RangeError(`active milliseconds must be a non-negative integer: ${activeMs}`);
  }
  const beats = activeMs === 0 ? 0 : Math.floor(activeMs / profile.intervalMs) + 1;
  const wireBytes = beats * (profile.upstreamBytes + profile.downstreamBytes);
  return {
    profile,
    beats,
    wireBytes,
    detectionMs: profile.intervalMs * profile.missedToDetect,
  };
}

export function classifySilence(profile: KeepaliveProfile, silentMs: number): SilenceReport {
  if (!Number.isInteger(silentMs) || silentMs < 0) {
    throw new RangeError(`silent milliseconds must be a non-negative integer: ${silentMs}`);
  }
  const missed = Math.floor(silentMs / profile.intervalMs);
  let state: LinkState = "ok";
  if (missed >= profile.missedToDetect * 2) {
    state = "dead";
  } else if (missed >= profile.missedToDetect) {
    state = "suspect";
  }
  return { state, missed, silentMs };
}

export interface PlanComparison {
  readonly cheapest: HeartbeatPlan;
  readonly fastest: HeartbeatPlan;
  readonly overheadBytes: number;
}

export function comparePlans(plans: readonly HeartbeatPlan[]): PlanComparison {
  if (plans.length === 0) {
    throw new RangeError("at least one heartbeat plan is required");
  }
  let cheapest = plans[0];
  let fastest = plans[0];
  for (const plan of plans) {
    if (plan.wireBytes < cheapest.wireBytes) {
      cheapest = plan;
    }
    if (plan.detectionMs < fastest.detectionMs) {
      fastest = plan;
    }
  }
  return {
    cheapest,
    fastest,
    overheadBytes: fastest.wireBytes - cheapest.wireBytes,
  };
}

export function describePlan(plan: HeartbeatPlan): string {
  return `${plan.profile.scene}：间隔 ${plan.profile.intervalMs}ms，${plan.beats} 次心跳，流量 ${formatBytes(plan.wireBytes)}，断线判定 ${plan.detectionMs}ms`;
}