《互联网产品的客户端架构·规模化与架构演进》3.3 动态配置与热更新的停止条件

// file: src/plugin/hot-update.ts
// tier: L2
// verify: node --test test/plugin/hot-update.test.ts

export type ConfigLayer = "default" | "environment" | "experiment";

export type ConfigValue = string | number | boolean;

export type ConfigPatch = Record<string, ConfigValue>;

export type LayerConfig = { layer: ConfigLayer; values: ConfigPatch };

const LAYER_RANK: Record<ConfigLayer, number> = {
  default: 0,
  environment: 1,
  experiment: 2,
};

export function resolveConfig(layers: LayerConfig[]): ConfigPatch {
  const ordered = [...layers].sort(
    (a, b) => LAYER_RANK[a.layer] - LAYER_RANK[b.layer],
  );
  const merged: ConfigPatch = {};
  for (const layer of ordered) {
    for (const [key, value] of Object.entries(layer.values)) {
      merged[key] = value;
    }
  }
  return merged;
}

export function rolloutBucket(unitId: string, key: string): number {
  let hash = 2166136261;
  const input = `${key}:${unitId}`;
  for (let index = 0; index < input.length; index += 1) {
    hash ^= input.charCodeAt(index);
    hash = Math.imul(hash, 16777619);
  }
  return (hash >>> 0) % 100;
}

export function inRollout(unitId: string, key: string, percent: number): boolean {
  const clamped = Math.max(0, Math.min(100, percent));
  if (clamped === 0) return false;
  if (clamped === 100) return true;
  return rolloutBucket(unitId, key) < clamped;
}

export type HealthSignal = {
  sampleSize: number;
  crashRate: number;
  errorRate: number;
  p95LatencyMs: number;
};

export type StopPolicy = {
  minSampleSize: number;
  maxCrashRate: number;
  maxErrorRate: number;
  maxP95LatencyMs: number;
};

export type Action = "continue" | "hold" | "rollback";

export type BatchDecision = { action: Action; reasons: string[] };

export function evaluateHealth(
  signal: HealthSignal,
  policy: StopPolicy,
): BatchDecision {
  if (
    !Number.isFinite(signal.sampleSize) ||
    signal.sampleSize < policy.minSampleSize
  ) {
    return { action: "hold", reasons: ["sample-too-small"] };
  }
  const reasons: string[] = [];
  if (signal.crashRate > policy.maxCrashRate) reasons.push("crash-rate");
  if (signal.errorRate > policy.maxErrorRate) reasons.push("error-rate");
  if (signal.p95LatencyMs > policy.maxP95LatencyMs) reasons.push("latency");
  if (reasons.length > 0) return { action: "rollback", reasons };
  return { action: "continue", reasons: ["healthy"] };
}

export type UpdateEnvelope = { version: number; patch: ConfigPatch };

export type ApplyResult =
  | { applied: true; version: number; config: ConfigPatch }
  | {
      applied: false;
      reason: "stale-version" | "same-version" | "empty-patch" | "invalid-value";
    };

export function applyUpdate(
  current: { version: number; config: ConfigPatch },
  envelope: UpdateEnvelope,
): ApplyResult {
  if (!Number.isInteger(envelope.version) || envelope.version < 0) {
    return { applied: false, reason: "invalid-value" };
  }
  if (envelope.version < current.version) {
    return { applied: false, reason: "stale-version" };
  }
  if (envelope.version === current.version) {
    return { applied: false, reason: "same-version" };
  }
  const keys = Object.keys(envelope.patch);
  if (keys.length === 0) return { applied: false, reason: "empty-patch" };
  for (const key of keys) {
    if (key.trim() === "") return { applied: false, reason: "invalid-value" };
    const value = envelope.patch[key];
    if (typeof value === "number" && !Number.isFinite(value)) {
      return { applied: false, reason: "invalid-value" };
    }
    if (typeof value === "string" && value.trim() === "") {
      return { applied: false, reason: "invalid-value" };
    }
  }
  return {
    applied: true,
    version: envelope.version,
    config: { ...current.config, ...envelope.patch },
  };
}

export type RolloutBatch = { name: string; percent: number; policy: StopPolicy };

export type RolloutStep = {
  batch: string;
  percent: number;
  action: Action;
  reasons: string[];
};

export type RolloutPlan = {
  steps: RolloutStep[];
  stopped: boolean;
  stopAt: string | undefined;
};

export function planRollout(
  batches: RolloutBatch[],
  observations: Record<string, HealthSignal>,
): RolloutPlan {
  const steps: RolloutStep[] = [];
  for (const batch of batches) {
    const signal = observations[batch.name];
    const decision = signal
      ? evaluateHealth(signal, batch.policy)
      : { action: "hold" as Action, reasons: ["no-signal"] };
    steps.push({
      batch: batch.name,
      percent: batch.percent,
      action: decision.action,
      reasons: decision.reasons,
    });
    if (decision.action !== "continue") {
      return { steps, stopped: true, stopAt: batch.name };
    }
  }
  return { steps, stopped: false, stopAt: undefined };
}

export const DEFAULT_POLICY: StopPolicy = {
  minSampleSize: 200,
  maxCrashRate: 0.005,
  maxErrorRate: 0.02,
  maxP95LatencyMs: 800,
};

export const ROLLOUT_BATCHES: RolloutBatch[] = [
  { name: "canary", percent: 1, policy: DEFAULT_POLICY },
  { name: "early", percent: 5, policy: DEFAULT_POLICY },
  { name: "broad", percent: 20, policy: DEFAULT_POLICY },
  { name: "full", percent: 100, policy: DEFAULT_POLICY },
];