《互联网产品的客户端架构·规模化与架构演进》12.2 双写双读与兼容窗口

// file: src/migration/dual-write.ts
// tier: L1
// verify: node --test test/migration/dual-write.test.ts

export type WriteTarget = "legacy" | "new";

export type WriteOrder = "legacy-first" | "new-first";

export type WriteAttempt = {
  target: WriteTarget;
  ok: boolean;
  error?: string;
};

export type DualWriteStatus = "consistent" | "degraded" | "primary-failed";

export type DualWriteReport = {
  status: DualWriteStatus;
  order: WriteOrder;
  primary: WriteTarget;
  attempts: WriteAttempt[];
  failed: WriteTarget[];
  userVisibleFailure: boolean;
  repairNeeded: boolean;
};

export type ReadValue = string | null;

export type ReadOutcome = {
  ok: boolean;
  value: ReadValue;
};

export type ReadVerdict =
  | "match"
  | "mismatch"
  | "legacy-only"
  | "new-only"
  | "both-missing";

export type DiffSample = {
  key: string;
  legacy: ReadValue;
  next: ReadValue;
};

export type DiffReport = {
  total: number;
  matched: number;
  mismatched: number;
  diffRate: number;
  mismatchKeys: string[];
};

export type CompatibilityWindow = {
  startsAt: number;
  endsAt: number;
  closedAt: number | null;
};

export type WindowState = "not-started" | "open" | "expired" | "closed";

export type ExpiryAction = "none" | "keep-open" | "extend" | "remove-legacy";

export type ExpiryReason =
  | "closed"
  | "not-expired"
  | "above-threshold"
  | "unstable"
  | "ready";

export type ExpiryDecision = {
  action: ExpiryAction;
  reason: ExpiryReason;
};

function roundRate(value: number): number {
  return Math.round(value * 100) / 100;
}

export function primaryTarget(order: WriteOrder): WriteTarget {
  return order === "legacy-first" ? "legacy" : "new";
}

export function secondaryTarget(order: WriteOrder): WriteTarget {
  return order === "legacy-first" ? "new" : "legacy";
}

export function runDualWrite(
  order: WriteOrder,
  write: (target: WriteTarget) => { ok: boolean; error?: string },
): DualWriteReport {
  const primary = primaryTarget(order);
  const secondary = secondaryTarget(order);
  const attempts: WriteAttempt[] = [];

  const first = write(primary);
  attempts.push({ target: primary, ok: first.ok, error: first.error });
  if (!first.ok) {
    return {
      status: "primary-failed",
      order,
      primary,
      attempts,
      failed: [primary],
      userVisibleFailure: true,
      repairNeeded: true,
    };
  }

  const second = write(secondary);
  attempts.push({ target: secondary, ok: second.ok, error: second.error });
  if (!second.ok) {
    return {
      status: "degraded",
      order,
      primary,
      attempts,
      failed: [secondary],
      userVisibleFailure: false,
      repairNeeded: true,
    };
  }

  return {
    status: "consistent",
    order,
    primary,
    attempts,
    failed: [],
    userVisibleFailure: false,
    repairNeeded: false,
  };
}

export function compareReads(
  legacy: ReadOutcome,
  next: ReadOutcome,
): ReadVerdict {
  if (!legacy.ok && !next.ok) return "both-missing";
  if (!legacy.ok) return "new-only";
  if (!next.ok) return "legacy-only";
  return legacy.value === next.value ? "match" : "mismatch";
}

export function diffReport(samples: DiffSample[]): DiffReport {
  const mismatchKeys: string[] = [];
  for (const sample of samples) {
    if (sample.legacy !== sample.next) mismatchKeys.push(sample.key);
  }
  const total = samples.length;
  const mismatched = mismatchKeys.length;
  return {
    total,
    matched: total - mismatched,
    mismatched,
    diffRate: total === 0 ? 0 : roundRate((mismatched * 100) / total),
    mismatchKeys,
  };
}

export function consistencyRate(report: DiffReport): number {
  if (report.total === 0) return 0;
  return roundRate((report.matched * 100) / report.total);
}

export function windowState(
  window: CompatibilityWindow,
  now: number,
): WindowState {
  if (window.closedAt !== null) return "closed";
  if (now < window.startsAt) return "not-started";
  if (now <= window.endsAt) return "open";
  return "expired";
}

export function writesAllowed(
  window: CompatibilityWindow,
  now: number,
): boolean {
  return windowState(window, now) === "open";
}

export function closeWindow(
  window: CompatibilityWindow,
  now: number,
): CompatibilityWindow {
  if (window.closedAt !== null) return { ...window };
  return { ...window, closedAt: now };
}

export function extendWindow(
  window: CompatibilityWindow,
  extraMs: number,
): CompatibilityWindow {
  if (!Number.isFinite(extraMs) || extraMs <= 0) return { ...window };
  return { ...window, endsAt: window.endsAt + extraMs };
}

export function decideExpiry(input: {
  window: CompatibilityWindow;
  now: number;
  diffRate: number;
  maxDiffRate?: number;
  lastMismatchAt?: number | null;
  quietMs?: number;
}): ExpiryDecision {
  const state = windowState(input.window, input.now);
  if (state === "closed") return { action: "none", reason: "closed" };
  if (state !== "expired") {
    return { action: "keep-open", reason: "not-expired" };
  }
  const maxDiffRate = input.maxDiffRate ?? 0.1;
  if (input.diffRate > maxDiffRate) {
    return { action: "extend", reason: "above-threshold" };
  }
  const quietMs = input.quietMs ?? 24 * 60 * 60 * 1000;
  const lastMismatchAt = input.lastMismatchAt ?? null;
  if (
    lastMismatchAt !== null &&
    input.now - lastMismatchAt < quietMs
  ) {
    return { action: "extend", reason: "unstable" };
  }
  return { action: "remove-legacy", reason: "ready" };
}