外部依存が落ちても落ちないシステム設計：リトライ・指数バックオフ＋ジッター・サーキットブレーカー実装ガイド

// クライアント側：操作ごとに「決定的な」冪等性キーを発行する。
// リトライ間で同じキーを使い回すのが肝（毎回新規発行するとキーの意味がない）。
import { randomUUID } from "node:crypto";

type ChargeRequest = {
  amount: number;
  currency: "JPY";
  customerId: string;
};

async function chargeWithIdempotency(req: ChargeRequest): Promise<void> {
  // 1回の「課金しようという意図」に対して1つのキー。リトライしても同じキー。
  const idempotencyKey = randomUUID();

  // この呼び出しは §7 の resilientFetch で包む（タイムアウト+リトライ+ブレーカー）
  await resilientFetch("https://api.example.com/charges", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey, // 同じキーなら二重課金しない契約
    },
    body: JSON.stringify(req),
  });
}

// 失敗を「分類された値」として扱う。any や生の throw に逃げない。
export type Transient =
  | { kind: "network"; cause: unknown }
  | { kind: "timeout" }
  | { kind: "server"; status: 502 | 503 | 504 }
  | { kind: "throttled"; retryAfterMs?: number }; // 429

export type Permanent =
  | { kind: "client"; status: number } // 4xx（429除く）
  | { kind: "business"; code: string }; // ドメイン上の失敗

export type Result<T> =
  | { ok: true; value: T }
  | { ok: false; error: Transient | Permanent };

// 「この失敗はリトライしてよいか」をただ1箇所で判定する（DRY）
export function isRetryable(e: Transient | Permanent): e is Transient {
  return (
    e.kind === "network" ||
    e.kind === "timeout" ||
    e.kind === "server" ||
    e.kind === "throttled"
  );
}

1. 素の指数バックオフ（ジッターなし — 悪い）
   sleep = min(cap, base * 2^attempt)

2. Full Jitter（フルジッター — 推奨）
   sleep = random_between(0, min(cap, base * 2^attempt))

3. Equal Jitter（イコールジッター）
   temp  = min(cap, base * 2^attempt)
   sleep = temp/2 + random_between(0, temp/2)

4. Decorrelated Jitter（デコリレーテッドジッター）
   sleep = min(cap, random_between(base, prev_sleep * 3))

// アンチパターン：固定間隔・ジッターなし・冪等性チェックなし・上限なし
async function badRetry<T>(fn: () => Promise<T>): Promise<T> {
  while (true) {                 // ❌ 無制限（unbounded）— 一生回り続ける
    try {
      return await fn();
    } catch {
      await sleep(1000);         // ❌ 固定1秒 — 全クライアントが同時に殺到する
      // ❌ 何の失敗かを区別していない（4xxもビジネス失敗もリトライしてしまう）
    }
  }
}

export type RetryOptions = {
  maxAttempts: number; // 上限は必須。無制限は禁止
  baseMs: number;      // 基準待ち（例: 100）
  capMs: number;       // 上限待ち（例: 20_000）capped backoff
  signal?: AbortSignal; // 全体デッドライン（§3）と連動
};

// Full Jitter: sleep = random(0, min(cap, base * 2^attempt))
function fullJitterDelay(attempt: number, baseMs: number, capMs: number): number {
  const exp = Math.min(capMs, baseMs * 2 ** attempt);
  return Math.random() * exp; // 0〜exp の一様乱数。これがストームを砕く
}

export async function retry<T>(
  op: () => Promise<Result<T>>,
  opts: RetryOptions,
): Promise<Result<T>> {
  let lastError: Transient | Permanent = { kind: "timeout" };

  for (let attempt = 0; attempt < opts.maxAttempts; attempt++) {
    const res = await op();
    if (res.ok) return res;

    lastError = res.error;
    // 恒久的失敗は即座に諦める（4xx/ビジネス失敗をリトライしない）
    if (!isRetryable(res.error)) return res;

    // 最終試行ならもう待たない
    if (attempt === opts.maxAttempts - 1) break;

    // 429 は相手が指定した Retry-After を尊重しつつ、最低限ジッターを足す
    const jittered = fullJitterDelay(attempt, opts.baseMs, opts.capMs);
    const delay =
      lastError.kind === "throttled" && lastError.retryAfterMs
        ? Math.max(lastError.retryAfterMs, jittered)
        : jittered;

    await sleepAbortable(delay, opts.signal); // 全体デッドラインで中断可能に
    // 観測性：リトライ回数はメトリクスとして必ず出す（§8）
    emitMetric("retry.attempt", { attempt: attempt + 1, kind: lastError.kind });
  }
  return { ok: false, error: lastError };
}

function sleep(ms: number): Promise<void> {
  return new Promise((r) => setTimeout(r, ms));
}

function sleepAbortable(ms: number, signal?: AbortSignal): Promise<void> {
  return new Promise((resolve, reject) => {
    if (signal?.aborted) return reject(new Error("aborted"));
    const t = setTimeout(resolve, ms);
    signal?.addEventListener(
      "abort",
      () => {
        clearTimeout(t);
        reject(new Error("aborted")); // デッドライン超過なら待たずに抜ける
      },
      { once: true },
    );
  });
}

// リトライ「予算」を管理する。成功でトークン回復、リトライで消費。
// 障害が長引いてもリトライ総量に上限がかかる（自己DDoS防止）。
export class RetryBudget {
  private tokens: number;
  constructor(
    private readonly capacity: number,
    private readonly refillPerSuccess: number = 1,
  ) {
    this.tokens = capacity;
  }
  tryAcquire(): boolean {
    if (this.tokens <= 0) return false; // 予算切れ→リトライせず即失敗
    this.tokens -= 1;
    return true;
  }
  onSuccess(): void {
    this.tokens = Math.min(this.capacity, this.tokens + this.refillPerSuccess);
  }
}

// 試行ごとのタイムアウト。AbortController で確実に下層をキャンセルする。
async function withTimeout<T>(
  fn: (signal: AbortSignal) => Promise<T>,
  ms: number,
  parentSignal?: AbortSignal, // 全体デッドラインを伝播
): Promise<T> {
  const ctrl = new AbortController();
  const onParentAbort = () => ctrl.abort();
  parentSignal?.addEventListener("abort", onParentAbort, { once: true });

  const timer = setTimeout(() => ctrl.abort(), ms);
  try {
    return await fn(ctrl.signal);
  } finally {
    clearTimeout(timer);
    parentSignal?.removeEventListener("abort", onParentAbort);
  }
}

// 全体デッドライン：リトライ総時間に蓋をする
function deadline(totalMs: number): AbortSignal {
  return AbortSignal.timeout(totalMs); // Node 18+/モダンブラウザ
}

type BreakerState = "closed" | "open" | "half-open";

export type BreakerConfig = {
  failureThreshold: number;   // Closed中、この回数失敗でOpenへ
  successThreshold: number;   // Half-Open中、この連続成功でClosedへ
  openDurationMs: number;     // Open維持時間（満了でHalf-Openへ）
  rollingWindowMs: number;    // 失敗カウンタの時間窓（古い失敗は忘れる）
};

export class CircuitBreaker {
  private state: BreakerState = "closed";
  private failures: number[] = []; // 失敗タイムスタンプ（rolling window）
  private successesInHalfOpen = 0;
  private openedAt = 0;

  constructor(
    private readonly cfg: BreakerConfig,
    private readonly now: () => number = Date.now, // テスト容易性のため注入
    private readonly onStateChange?: (s: BreakerState) => void, // 観測性
  ) {}

  /** 呼び出し前に「通してよいか」を判定する */
  private canPass(): boolean {
    if (this.state === "open") {
      // Open維持時間が過ぎたらHalf-Openへ（試しに通してみる）
      if (this.now() - this.openedAt >= this.cfg.openDurationMs) {
        this.transition("half-open");
        this.successesInHalfOpen = 0;
        return true;
      }
      return false; // まだOpen → fail fast
    }
    return true; // closed / half-open は通す
  }

  async execute<T>(op: () => Promise<Result<T>>): Promise<Result<T>> {
    if (!this.canPass()) {
      // Open中は即座に失敗。下流を一切叩かない（これが本質）
      return { ok: false, error: { kind: "server", status: 503 } };
    }
    const res = await op();
    if (res.ok) this.onSuccess();
    else if (isRetryable(res.error)) this.onFailure(); // 一時的失敗のみ計上
    // 恒久的失敗（4xx等）はブレーカーの故障判定に含めない（下流の健康とは無関係）
    return res;
  }

  private onSuccess(): void {
    if (this.state === "half-open") {
      this.successesInHalfOpen++;
      if (this.successesInHalfOpen >= this.cfg.successThreshold) {
        this.failures = [];
        this.transition("closed"); // 回復確認 → 通常運転へ
      }
    } else {
      this.failures = []; // Closedでの成功はカウンタをきれいに
    }
  }

  private onFailure(): void {
    if (this.state === "half-open") {
      this.trip(); // 試験中の失敗は即Openへ戻す
      return;
    }
    const t = this.now();
    // rolling window 外の古い失敗は捨てる（たまの失敗で開かないように）
    this.failures = this.failures.filter((ts) => t - ts < this.cfg.rollingWindowMs);
    this.failures.push(t);
    if (this.failures.length >= this.cfg.failureThreshold) this.trip();
  }

  private trip(): void {
    this.openedAt = this.now();
    this.transition("open");
  }

  private transition(next: BreakerState): void {
    if (this.state !== next) {
      this.state = next;
      this.onStateChange?.(next); // 状態遷移は必ずメトリクス/アラートに出す
    }
  }
}

// 依存先ごとに「同時実行枠」を切る。Aが詰まってもB/Cの枠は無事。
export class Semaphore {
  private active = 0;
  private queue: Array<() => void> = [];
  constructor(private readonly max: number) {}

  async run<T>(fn: () => Promise<T>): Promise<T> {
    if (this.active >= this.max) {
      await new Promise<void>((resolve) => this.queue.push(resolve));
    }
    this.active++;
    try {
      return await fn();
    } finally {
      this.active--;
      this.queue.shift()?.(); // 次の待機者を起こす
    }
  }
}

// 依存先ごとにバルクヘッドを分離。AとBは互いのリソースを侵さない。
const bulkheads = {
  paymentApi: new Semaphore(10), // 決済は重要：10枠確保
  emailApi: new Semaphore(3),    // メールは詰まっても本筋を止めない：3枠だけ
} as const;

// メールAPIが全部詰まっても、消費するのは最大3枠。決済の10枠は無傷。
await bulkheads.emailApi.run(() => sendReceiptEmail(order));

// 依存先ごとに1インスタンス。状態（ブレーカー/予算/枠）を共有する。
export class ResilientClient {
  constructor(
    private readonly breaker: CircuitBreaker,
    private readonly budget: RetryBudget,
    private readonly bulkhead: Semaphore,
    private readonly retryOpts: RetryOptions,
    private readonly perAttemptTimeoutMs: number,
  ) {}

  async call<T>(
    fn: (signal: AbortSignal) => Promise<T>,
    parse: (raw: unknown) => Result<T>, // 境界で型を絞る（信頼しない）
    overallDeadline: AbortSignal,
  ): Promise<Result<T>> {
    // 最外層：ブレーカー。Open中はここで即fail（下流を一切叩かない）
    return this.breaker.execute(() =>
      // 次層：リトライ（冪等な操作前提・Full Jitter）
      retry<T>(async () => {
        if (!this.budget.tryAcquire()) {
          return { ok: false, error: { kind: "throttled" } }; // 予算切れ
        }
        // 次層：バルクヘッド（同時実行枠の隔離）
        return this.bulkhead.run(async () => {
          try {
            // 最内層：試行ごとタイムアウト（全体デッドラインも伝播）
            const raw = await withTimeout(fn, this.perAttemptTimeoutMs, overallDeadline);
            const res = parse(raw);
            if (res.ok) this.budget.onSuccess(); // 成功で予算回復
            return res;
          } catch (e) {
            // タイムアウト/ネットワーク例外を型付き Transient に正規化
            const err: Transient =
              e instanceof Error && e.name === "AbortError"
                ? { kind: "timeout" }
                : { kind: "network", cause: e };
            return { ok: false, error: err };
          }
        });
      }, { ...this.retryOpts, signal: overallDeadline }),
    );
  }
}

// 依存先ごとに設定。決済は重要なので枠もリトライも厚めに。
const paymentClient = new ResilientClient(
  new CircuitBreaker(
    { failureThreshold: 5, successThreshold: 2, openDurationMs: 30_000, rollingWindowMs: 10_000 },
    Date.now,
    (s) => emitMetric("breaker.state", { dependency: "payment", state: s }),
  ),
  new RetryBudget(100),
  new Semaphore(10),
  { maxAttempts: 4, baseMs: 100, capMs: 20_000 },
  5_000, // per-attempt 5s
);

async function chargeOrder(order: Order): Promise<Result<Charge>> {
  const overall = AbortSignal.timeout(15_000); // 全体15秒デッドライン
  const idempotencyKey = order.id; // 注文IDを決定的キーに（リトライで不変）

  return paymentClient.call<Charge>(
    (signal) =>
      fetch("https://api.example.com/charges", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "Idempotency-Key": idempotencyKey, // 二重課金を構造的に防ぐ
        },
        body: JSON.stringify({ amount: order.total, currency: "JPY" }),
        signal, // タイムアウト/デッドラインで確実にキャンセル
      }).then(async (r) => {
        // HTTPステータスを型付き Result に正規化（境界で分類）
        if (r.ok) return await r.json();
        if (r.status === 429) {
          const ra = r.headers.get("Retry-After");
          throw Object.assign(new Error("throttled"), {
            transient: { kind: "throttled", retryAfterMs: ra ? Number(ra) * 1000 : undefined },
          });
        }
        if (r.status >= 500) throw new Error(`server ${r.status}`);
        throw new Error(`client ${r.status}`); // 4xx → リトライされない
      }),
    (raw) => ({ ok: true, value: raw as Charge }), // 実際はzod等で検証
    overall,
  );
}