《移动游戏产品的架构·网络、资源与热更新》11.3 回滚与版本收敛

// file: src/hotfix/rollback.ts
// tier: L1
// verify: node --test test/hotfix/rollback.test.ts

export type ReleaseKind = "config" | "resource" | "code" | "store";

export interface ReleaseVersion {
  readonly version: string;
  readonly kind: ReleaseKind;
  readonly releasedAt: string;
  readonly rollbackable: boolean;
  readonly minClient: string;
}

export interface RollbackRequest {
  readonly currentVersion: string;
  readonly incidentAt: string;
  readonly clientVersion: string;
  readonly deadlineMinutes: number;
  readonly forwardFixAvailable: boolean;
}

export interface RollbackStep {
  readonly order: number;
  readonly action: string;
  readonly minutes: number;
}

export interface RollbackPlan {
  readonly mode: "rollback" | "forward-fix";
  readonly target: ReleaseVersion | null;
  readonly steps: readonly RollbackStep[];
  readonly totalMinutes: number;
  readonly withinDeadline: boolean;
  readonly warnings: readonly string[];
}

export interface VersionShare {
  readonly version: string;
  readonly users: number;
}

function validateVersion(version: string): void {
  if (!/^\d+(\.\d+)*$/.test(version)) {
    throw new Error(`invalid version: ${version}`);
  }
}

export function compareVersions(left: string, right: string): number {
  validateVersion(left);
  validateVersion(right);
  const a = left.split(".").map((part) => Number.parseInt(part, 10));
  const b = right.split(".").map((part) => Number.parseInt(part, 10));
  const length = Math.max(a.length, b.length);
  for (let index = 0; index < length; index += 1) {
    const x = a[index] ?? 0;
    const y = b[index] ?? 0;
    if (x !== y) return x < y ? -1 : 1;
  }
  return 0;
}

function requireRelease(
  history: readonly ReleaseVersion[],
  version: string,
): ReleaseVersion {
  const found = history.find((release) => release.version === version);
  if (found === undefined) {
    throw new Error(`unknown release: ${version}`);
  }
  return found;
}

export function selectRollbackTarget(
  history: readonly ReleaseVersion[],
  request: RollbackRequest,
): ReleaseVersion | null {
  const incident = Date.parse(request.incidentAt);
  if (Number.isNaN(incident)) {
    throw new Error(`invalid incidentAt: ${request.incidentAt}`);
  }
  const current = requireRelease(history, request.currentVersion);
  const candidates = history.filter((release) => {
    if (release.version === current.version) return false;
    if (!release.rollbackable) return false;
    const released = Date.parse(release.releasedAt);
    if (Number.isNaN(released) || released >= incident) return false;
    if (compareVersions(release.version, current.version) >= 0) return false;
    return compareVersions(release.minClient, request.clientVersion) <= 0;
  });
  candidates.sort((a, b) => {
    const byTime = Date.parse(b.releasedAt) - Date.parse(a.releasedAt);
    if (byTime !== 0) return byTime;
    return compareVersions(b.version, a.version);
  });
  return candidates[0] ?? null;
}

export function planRollback(
  history: readonly ReleaseVersion[],
  request: RollbackRequest,
): RollbackPlan {
  if (!Number.isInteger(request.deadlineMinutes) || request.deadlineMinutes <= 0) {
    throw new Error(`invalid deadline: ${request.deadlineMinutes}`);
  }
  const current = requireRelease(history, request.currentVersion);
  const warnings: string[] = [];
  const target = current.kind === "store" ? null : selectRollbackTarget(history, request);

  if (current.kind === "store") {
    warnings.push("store packages cannot be rolled back; only a new store version can replace them");
  }

  let mode: "rollback" | "forward-fix";
  const actions: { action: string; minutes: number }[] = [];

  if (target !== null) {
    mode = "rollback";
    actions.push({ action: `freeze rollout of ${current.version}`, minutes: 1 });
    actions.push({
      action: `switch active manifest ${current.version} -> ${target.version}`,
      minutes: 2,
    });
    actions.push({
      action: `restore ${target.kind} snapshot ${target.version} and verify checksum`,
      minutes: 3,
    });
    actions.push({ action: "force clients to re-sync the version index", minutes: 2 });
    actions.push({ action: "watch crash, ANR and download success", minutes: 4 });
  } else {
    mode = "forward-fix";
    if (request.forwardFixAvailable) {
      actions.push({ action: `build forward fix on top of ${current.version}`, minutes: 10 });
      actions.push({ action: "canary the forward fix on the internal group", minutes: 5 });
      actions.push({ action: "promote the forward fix and watch the gates", minutes: 5 });
    } else {
      actions.push({ action: "submit a new store package and wait for review", minutes: 60 });
      warnings.push("no forward fix is available; the store package is the only path");
    }
  }

  const steps: RollbackStep[] = actions.map((item, index) => ({
    order: index + 1,
    action: item.action,
    minutes: item.minutes,
  }));
  const totalMinutes = steps.reduce((sum, step) => sum + step.minutes, 0);
  if (totalMinutes > request.deadlineMinutes) {
    warnings.push(
      `plan needs ${totalMinutes} minutes but the deadline is ${request.deadlineMinutes} minutes`,
    );
  }

  return {
    mode,
    target,
    steps,
    totalMinutes,
    withinDeadline: totalMinutes <= request.deadlineMinutes,
    warnings,
  };
}

export function convergenceRate(
  shares: readonly VersionShare[],
  targetVersion: string,
): number {
  const seen = new Set<string>();
  let total = 0;
  let target = 0;
  for (const share of shares) {
    if (seen.has(share.version)) {
      throw new Error(`duplicate version share: ${share.version}`);
    }
    seen.add(share.version);
    if (!Number.isInteger(share.users) || share.users < 0) {
      throw new Error(`invalid users for ${share.version}: ${share.users}`);
    }
    total += share.users;
    if (share.version === targetVersion) target += share.users;
  }
  if (total === 0) return 0;
  return Number((target / total).toFixed(4));
}

export function formatRollbackPlan(plan: RollbackPlan): string {
  const lines = [
    `mode ${plan.mode}`,
    `target ${plan.target === null ? "none" : plan.target.version}`,
    `budget ${plan.totalMinutes}min within=${plan.withinDeadline ? "yes" : "no"}`,
  ];
  for (const step of plan.steps) {
    lines.push(`${step.order}\t${step.minutes}min\t${step.action}`);
  }
  for (const warning of plan.warnings) {
    lines.push(`warning\t${warning}`);
  }
  return lines.join("\n");
}

mode rollback
target 1.11.0
budget 12min within=yes
1	1min	freeze rollout of 1.13.0
2	2min	switch active manifest 1.13.0 -> 1.11.0
3	3min	restore resource snapshot 1.11.0 and verify checksum
4	2min	force clients to re-sync the version index
5	4min	watch crash, ANR and download success