《互联网产品的客户端架构·规模化与架构演进》12.1 绞杀者与渐进式替换

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

export type BucketKind = "user" | "endpoint" | "feature";

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

export type BucketRef = {
  kind: BucketKind;
  key: string;
};

export type BucketRule = {
  kind: BucketKind;
  keys: string[] | null;
  percent: number | null;
  force: RouteTarget | null;
};

export type MigrationPlan = {
  feature: string;
  percent: number;
  rules: BucketRule[];
  allowlist: BucketRef[];
  holdback: BucketRef[];
};

export type RouteRequest = {
  user: string;
  endpoint: string;
  feature: string;
};

export type RouteMatcher =
  | "allowlist"
  | "holdback"
  | "rule:user"
  | "rule:endpoint"
  | "rule:feature"
  | "global";

export type RouteDecision = {
  target: RouteTarget;
  matchedBy: RouteMatcher;
  percent: number;
};

export type TakeoverReport = {
  total: number;
  newCount: number;
  legacyCount: number;
  newPercent: number;
  legacyPercent: number;
  complete: boolean;
};

export type PromoteResult =
  | { ok: true; plan: MigrationPlan }
  | { ok: false; reason: "range" | "regression" };

const KINDS: BucketKind[] = ["user", "endpoint", "feature"];

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

function clonePlan(plan: MigrationPlan): MigrationPlan {
  return {
    feature: plan.feature,
    percent: plan.percent,
    rules: plan.rules.map((rule) => ({
      kind: rule.kind,
      keys: rule.keys === null ? null : [...rule.keys],
      percent: rule.percent,
      force: rule.force,
    })),
    allowlist: plan.allowlist.map((ref) => ({ kind: ref.kind, key: ref.key })),
    holdback: plan.holdback.map((ref) => ({ kind: ref.kind, key: ref.key })),
  };
}

export function bucketPercent(key: string): number {
  let hash = 0x811c9dc5;
  for (let i = 0; i < key.length; i += 1) {
    hash ^= key.charCodeAt(i);
    hash = Math.imul(hash, 0x01000193);
  }
  return (hash >>> 0) % 100;
}

export function bucketKeyOf(request: RouteRequest, kind: BucketKind): string {
  if (kind === "user") return request.user;
  if (kind === "endpoint") return request.endpoint;
  return request.feature;
}

export function sameBucket(ref: BucketRef, request: RouteRequest): boolean {
  return ref.key === bucketKeyOf(request, ref.kind);
}

export function validatePlan(plan: MigrationPlan): string[] {
  const errors: string[] = [];
  if (plan.feature.trim() === "") errors.push("feature");
  if (!Number.isInteger(plan.percent) || plan.percent < 0 || plan.percent > 100) {
    errors.push("percent");
  }
  plan.rules.forEach((rule, index) => {
    if (!KINDS.includes(rule.kind)) errors.push(`rule:${index}:kind`);
    if (rule.keys !== null && rule.keys.length === 0) {
      errors.push(`rule:${index}:keys`);
    }
    if (
      rule.percent !== null &&
      (!Number.isInteger(rule.percent) || rule.percent < 0 || rule.percent > 100)
    ) {
      errors.push(`rule:${index}:percent`);
    }
  });
  for (const held of plan.holdback) {
    const conflict = plan.allowlist.some(
      (allowed) => allowed.kind === held.kind && allowed.key === held.key,
    );
    if (conflict) {
      errors.push(`conflict:${held.kind}:${held.key}`);
    }
  }
  return errors;
}

export function decideRoute(
  plan: MigrationPlan,
  request: RouteRequest,
): RouteDecision {
  if (plan.holdback.some((ref) => sameBucket(ref, request))) {
    return { target: "legacy", matchedBy: "holdback", percent: 0 };
  }
  if (plan.allowlist.some((ref) => sameBucket(ref, request))) {
    return { target: "new", matchedBy: "allowlist", percent: 100 };
  }
  for (const rule of plan.rules) {
    const key = bucketKeyOf(request, rule.kind);
    if (rule.keys !== null && !rule.keys.includes(key)) continue;
    const matchedBy = `rule:${rule.kind}` as RouteMatcher;
    if (rule.force !== null) {
      return {
        target: rule.force,
        matchedBy,
        percent: rule.force === "new" ? 100 : 0,
      };
    }
    const percent = rule.percent ?? plan.percent;
    const hash = bucketPercent(`${rule.kind}:${key}`);
    return {
      target: hash < percent ? "new" : "legacy",
      matchedBy,
      percent,
    };
  }
  const hash = bucketPercent(`user:${request.user}`);
  return {
    target: hash < plan.percent ? "new" : "legacy",
    matchedBy: "global",
    percent: plan.percent,
  };
}

export function takeoverReport(decisions: RouteDecision[]): TakeoverReport {
  const total = decisions.length;
  const newCount = decisions.filter((item) => item.target === "new").length;
  const legacyCount = total - newCount;
  return {
    total,
    newCount,
    legacyCount,
    newPercent: total === 0 ? 0 : roundPercent((newCount * 100) / total),
    legacyPercent: total === 0 ? 0 : roundPercent((legacyCount * 100) / total),
    complete: total > 0 && legacyCount === 0,
  };
}

export function promotePlan(
  plan: MigrationPlan,
  nextPercent: number,
): PromoteResult {
  if (
    !Number.isInteger(nextPercent) ||
    nextPercent < 0 ||
    nextPercent > 100
  ) {
    return { ok: false, reason: "range" };
  }
  if (nextPercent < plan.percent) {
    return { ok: false, reason: "regression" };
  }
  const next = clonePlan(plan);
  next.percent = nextPercent;
  return { ok: true, plan: next };
}

export function rollbackPlan(plan: MigrationPlan): MigrationPlan {
  const next = clonePlan(plan);
  next.percent = 0;
  next.allowlist = [];
  next.rules = next.rules.map((rule) => ({
    kind: rule.kind,
    keys: rule.keys === null ? null : [...rule.keys],
    percent: null,
    force: rule.force === "new" ? "legacy" : rule.force,
  }));
  return next;
}