《移动游戏产品的架构·网络、资源与热更新》3.2 指数退避与抖动：重连节奏怎么定

// file: src/net/backoff.ts
// tier: L1
// verify: node --test test/net/backoff.test.ts
/**
 * 指数退避与抖动模型（mga-net-lab）。
 * 所有数值都是实验参数，不是案例事实；随机源由调用方注入以便复现。
 */

export type JitterMode = "none" | "full" | "equal";

export interface BackoffOptions {
  readonly baseMs: number;
  readonly capMs: number;
  readonly maxAttempts: number;
  readonly stableResetMs: number;
}

export const DEFAULT_BACKOFF: BackoffOptions = {
  baseMs: 500,
  capMs: 20_000,
  maxAttempts: 8,
  stableResetMs: 10_000,
};

export interface BackoffStep {
  readonly attempt: number;
  readonly rawMs: number;
  readonly cappedMs: number;
  readonly delayMs: number;
  readonly mode: JitterMode;
}

export type ReconnectPhase = "idle" | "waiting" | "connecting" | "exhausted";

export interface ReconnectState {
  readonly attempt: number;
  readonly phase: ReconnectPhase;
  readonly nextDelayMs: number | null;
  readonly connectedAt: number | null;
  readonly history: readonly BackoffStep[];
}

export type ReconnectEvent = "failed" | "connected" | "stable" | "retry";

export interface AdvanceResult {
  readonly state: ReconnectState;
  readonly changed: boolean;
  readonly reason: string;
}

function sample(random: () => number): number {
  const value = random();
  if (!(value >= 0 && value < 1)) {
    throw new RangeError(`随机源必须返回 [0, 1) 区间，收到 ${value}`);
  }
  return value;
}

export function backoffStep(
  attempt: number,
  options: BackoffOptions = DEFAULT_BACKOFF,
  mode: JitterMode = "full",
  random: () => number = Math.random,
): BackoffStep {
  if (!Number.isInteger(attempt) || attempt < 1) {
    throw new RangeError(`重试序号必须是正整数，收到 ${attempt}`);
  }
  const rawMs = options.baseMs * 2 ** (attempt - 1);
  const cappedMs = Math.min(rawMs, options.capMs);
  let delayMs = cappedMs;
  if (mode === "full") {
    delayMs = Math.floor(sample(random) * cappedMs);
  } else if (mode === "equal") {
    delayMs = Math.floor(cappedMs / 2 + sample(random) * (cappedMs / 2));
  }
  return { attempt, rawMs, cappedMs, delayMs, mode };
}

export function createReconnect(): ReconnectState {
  return {
    attempt: 0,
    phase: "idle",
    nextDelayMs: null,
    connectedAt: null,
    history: [],
  };
}

export function advance(
  state: ReconnectState,
  event: ReconnectEvent,
  at: number,
  options: BackoffOptions = DEFAULT_BACKOFF,
  mode: JitterMode = "full",
  random: () => number = Math.random,
): AdvanceResult {
  if (event === "failed") {
    if (state.attempt >= options.maxAttempts) {
      return {
        state: { ...state, phase: "exhausted", nextDelayMs: null, connectedAt: null },
        changed: true,
        reason: `已达到 ${options.maxAttempts} 次上限，转人工重试`,
      };
    }
    const step = backoffStep(state.attempt + 1, options, mode, random);
    return {
      state: {
        attempt: step.attempt,
        phase: "waiting",
        nextDelayMs: step.delayMs,
        connectedAt: null,
        history: [...state.history, step],
      },
      changed: true,
      reason: `第 ${step.attempt} 次失败，等待 ${step.delayMs}ms`,
    };
  }

  if (event === "connected") {
    if (state.phase === "exhausted") {
      return { state, changed: false, reason: "已耗尽，忽略连接事件" };
    }
    return {
      state: { ...state, phase: "connecting", connectedAt: at, nextDelayMs: null },
      changed: true,
      reason: "传输层已连通，开始稳定计时",
    };
  }

  if (event === "retry") {
    if (state.phase !== "waiting") {
      return { state, changed: false, reason: `阶段 ${state.phase} 不在等待窗口` };
    }
    return {
      state: { ...state, phase: "connecting", nextDelayMs: null },
      changed: true,
      reason: "等待结束，发起下一次连接",
    };
  }

  if (state.connectedAt === null) {
    return { state, changed: false, reason: "尚未连接，无法判断稳定窗口" };
  }
  const stableMs = at - state.connectedAt;
  if (stableMs < options.stableResetMs) {
    return {
      state,
      changed: false,
      reason: `稳定窗口未满足，还需 ${options.stableResetMs - stableMs}ms`,
    };
  }
  return {
    state: createReconnect(),
    changed: true,
    reason: `连接稳定 ${stableMs}ms，退避计数清零`,
  };
}

export function formatBackoff(step: BackoffStep): string {
  const labels: Record<JitterMode, string> = {
    none: "无抖动",
    full: "full 抖动",
    equal: "equal 抖动",
  };
  return `第 ${step.attempt} 次：原始 ${step.rawMs}ms，封顶 ${step.cappedMs}ms，${labels[step.mode]}后 ${step.delayMs}ms`;
}

第 3 次：原始 2000ms，封顶 2000ms，无抖动后 2000ms

第 1 次：原始 500ms，封顶 500ms，full 抖动后 250ms