1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

// 便（配送物）と受領証。delivered:false = 間に合わせ（Fallback）の応答。
export interface Parcel {
  region: string;
  id: string;
}

export interface Receipt {
  region: string;
  delivered: boolean;
}

// 配送所（外部依存）。send は Promise。倒れた配送所は応答を握ったままハングする。
export interface Branch {
  send(parcel: Parcel): Promise<Receipt>;
}

// 中央局の使い魔（並行スロット）。有限。空くまで次の便は待つ。
export class CourierPool {
  private available: number;
  private readonly queue: Array<() => void> = [];
  private running = 0; // 稼働中の使い魔数

  constructor(capacity: number) {
    this.available = capacity;
  }

  async run<T>(task: () => Promise<T>): Promise<T> {
    if (this.available > 0) {
      this.available--;
    } else {
      await new Promise<void>((res) => this.queue.push(res)); // 空くのを待つ
    }
    this.running++;
    try {
      return await task();
    } finally {
      this.running--;
      const next = this.queue.shift();
      if (next) next(); // 次の待ち手にスロットを手渡し
      else this.available++;
    }
  }

  get inFlight(): number {
    return this.running;
  }
}

1
2
3
4
5
6
7
8
9

// Before: 中央局は使い魔を1つ確保し、配送所へ直接送る。倒れていても送り、
//   応答（or タイムアウト）まで使い魔を保持する。
export async function dispatchDirect(
  pool: CourierPool,
  branch: Branch,
  parcel: Parcel,
): Promise<Receipt> {
  return pool.run(() => branch.send(parcel));
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// Deferred: Promise の解決権を外から握るユーティリティ。
export function deferred<T>(): {
  promise: Promise<T>;
  resolve: (v: T) => void;
  reject: (e: unknown) => void;
} {
  let resolve!: (v: T) => void;
  let reject!: (e: unknown) => void;
  const promise = new Promise<T>((res, rej) => {
    resolve = res;
    reject = rej;
  });
  return { promise, resolve, reject };
}

// 倒れた配送所: send を呼ぶたびに新しい Deferred を返してハングする。
// テストは任意の刻に reject（タイムアウト相当）/ resolve（回復相当）できる。
export class DownedBranch implements Branch {
  callCount = 0;
  readonly pending: Array<{
    promise: Promise<Receipt>;
    resolve: (v: Receipt) => void;
    reject: (e: unknown) => void;
  }> = [];

  send(_parcel: Parcel): Promise<Receipt> {
    this.callCount++;
    const d = deferred<Receipt>();
    this.pending.push(d);
    return d.promise;
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

const pool = new CourierPool(2); // 使い魔は二人（容量2）
const downed = new DownedBranch();
const healthy = new HealthyBranch();

// 倒れた配送所へ2便→両方とも使い魔を確保し、応答を待ってハングする。
const p1 = dispatchDirect(pool, downed, { region: "downed", id: "p1" });
const p2 = dispatchDirect(pool, downed, { region: "downed", id: "p2" });

await Promise.resolve();
await Promise.resolve();
assert.equal(pool.inFlight, 2); // 使い魔は二人とも、応答のない相手の前で塞がっている

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// 健全な地方への便→空き使い魔が無く、まだ送られないまま待たされる。
let healthyDone = false;
const healthyPromise = dispatchDirect(pool, healthy, {
  region: "healthy",
  id: "h1",
}).then((receipt) => {
  healthyDone = true;
  return receipt;
});

// マイクロタスクを数回まわしても、健全便はまだ通らない。
await Promise.resolve();
await Promise.resolve();
await Promise.resolve();
assert.equal(healthyDone, false); // 健全な便が、倒れた相手に巻き込まれて凍っている
assert.equal(healthy.callCount, 0); // healthy.send 自体がまだ呼ばれていない（使い魔が無い）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// タイムアウト相当：倒れた配送所への2便を reject して使い魔を解放する。
const [d1, d2] = downed.pending;
d1!.reject(new Error("timeout"));
d2!.reject(new Error("timeout"));

await assert.rejects(p1);
await assert.rejects(p2);

// 使い魔が空き、健全便が初めて通る。
const healthyReceipt = await healthyPromise;
assert.equal(healthyDone, true);
assert.deepEqual(healthyReceipt, { region: "healthy", delivered: true });

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

// 却下案の反証専用：dispatchDirect を retries 回までリトライでくるむ使い捨て。
async function dispatchWithRetry(
  pool: CourierPool,
  branch: Branch,
  parcel: Parcel,
  retries: number,
): Promise<void> {
  let lastError: unknown;
  for (let attempt = 0; attempt < retries; attempt++) {
    try {
      await pool.run(() => branch.send(parcel));
      return;
    } catch (e) {
      lastError = e;
    }
  }
  throw lastError;
}

1
2
3
4
5
6
7

// 送り直しなし（1回）：倒れた配送所への到達は1回だけ。
// …reject まで進めて…
assert.equal(downedNoRetry.callCount, 1); // 到達は1回のみ

// 送り直し3回：倒れた配送所への到達が3回に増える＝群がる狼が3倍。
// …1回目 reject → 2回目 → 3回目…
assert.equal(downedRetry3.callCount, 3); // 到達は3回＝送り直しなしの3倍

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

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

export interface BreakerOptions {
  failureThreshold: number; // closed→open：連続失敗がこの数に達したら断つ
  openDuration: number; // open→half-open：この論理時間が経過したら試験へ
  now: () => number; // 論理時計（テストが手で進める）
  fallback: (parcel: Parcel) => Receipt; // 軽量・安全な既定値
}

// 封印の自動結界＝失敗が続く送りを一時的に遮断し、連鎖障害を防ぐ仕組み。
export class CircuitBreaker {
  private state: BreakerState = "closed";
  private failures = 0;
  private openedAt = 0; // 断った論理時刻
  private probing = false; // half-open：プローブが1本だけ飛行中か

  private readonly opts: BreakerOptions;

  constructor(opts: BreakerOptions) {
    this.opts = opts;
  }

  async call(
    parcel: Parcel,
    send: (p: Parcel) => Promise<Receipt>,
  ): Promise<Receipt> {
    // Open：刻が満ちていれば Half-Open へ（※遅延遷移＝刻が満ちても"次の便"が来て
    //   初めて移る。背景タイマーを使わない＝模擬戦で決定的）。満ちていなければ即 Fallback。
    if (this.state === "open") {
      if (this.opts.now() - this.openedAt >= this.opts.openDuration) {
        this.state = "half-open";
        this.probing = false;
      } else {
        return this.opts.fallback(parcel); // 鎖は断たれている：send を呼ばない
      }
    }
    // Half-Open：プローブは一筋だけ。既に飛んでいれば他は即 Fallback（群がりで再沈させない）
    if (this.state === "half-open") {
      if (this.probing) return this.opts.fallback(parcel);
      this.probing = true; // この便がプローブになる
    }
    // Closed、または Half-Open のプローブ：実際に送る
    try {
      const receipt = await send(parcel);
      this.onSuccess();
      return receipt;
    } catch {
      this.onFailure();
      return this.opts.fallback(parcel); // 失敗も握り潰して間に合わせを返す＝応答性を保つ
    }
  }

  private onSuccess(): void {
    if (this.state === "half-open") this.state = "closed"; // プローブ成功＝繋ぎ直す
    this.failures = 0;
    this.probing = false;
  }

  private onFailure(): void {
    if (this.state === "half-open") {
      this.trip(); // プローブ失敗＝再び断つ
      return;
    }
    this.failures++;
    if (this.failures >= this.opts.failureThreshold) this.trip();
  }

  private trip(): void {
    this.state = "open";
    this.openedAt = this.opts.now();
    this.probing = false;
  }

  peek(): BreakerState {
    return this.state;
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// After の送り：結界を「プールの外側」に置く。Open のとき結界は send を呼ばず
//   pool.run にすら入らない＝「断てば使い魔を出さない」が文字通り真になる。
export async function dispatchGuarded(
  pool: CourierPool,
  breaker: CircuitBreaker,
  branch: Branch,
  parcel: Parcel,
): Promise<Receipt> {
  return breaker.call(parcel, () => pool.run(() => branch.send(parcel)));
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

const pool = new CourierPool(2); // 使い魔は二人（Beforeと同一）
const downed = new DownedBranch();
let clock = 0;
const downedBreaker = new CircuitBreaker({
  failureThreshold: 2,
  openDuration: 1000,
  now: () => clock,
  fallback,
});

// 学習期：最初の2便はまだ結界が倒れを知らないので、実際に送って待つ
//   （Before と同じく使い魔を確保する）。
const p1 = dispatchGuarded(pool, downedBreaker, downed, { region: "downed", id: "p1" });
const p2 = dispatchGuarded(pool, downedBreaker, downed, { region: "downed", id: "p2" });
await Promise.resolve();
await Promise.resolve();
assert.equal(pool.inFlight, 2); // 学習期は Before と同じく使い魔が塞がる
assert.equal(downedBreaker.peek(), "closed");

// 1便目が失敗→失敗1。まだ Closed。
downed.pending[0]!.reject(new Error("timeout"));
await p1;
assert.equal(downedBreaker.peek(), "closed");

// 2便目も失敗→失敗2＝閾値到達→Open（断つ）。
downed.pending[1]!.reject(new Error("timeout"));
await p2;
assert.equal(downedBreaker.peek(), "open");

1
2
3
4
5
6

// 断った後：倒れた配送所への便は結界がプール外で即 Fallback（pool.run に入らない＝
//   使い魔を確保しない）。
const before3Calls = downed.callCount;
const p3 = await dispatchGuarded(pool, downedBreaker, downed, { region: "downed", id: "p3" });
assert.deepEqual(p3, { region: "downed", delivered: false }); // 間に合わせが返る
assert.equal(downed.callCount, before3Calls); // send は呼ばれていない＝使い魔を出していない

1
2
3
4
5
6
7

// 健全な相手には、倒れた相手とは別の結界（healthyBreaker）を立ててある（結界は配送所ごとに分ける・後述）。
// 健全な地方への便は、空いた使い魔ですぐ出ていく（Before と違い凍らない）。
const healthyReceipt = await dispatchGuarded(pool, healthyBreaker, healthy, {
  region: "healthy",
  id: "h1",
});
assert.deepEqual(healthyReceipt, { region: "healthy", delivered: true });

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// 刻を満たし Half-Open へ。便Aがプローブとして実際に飛ぶ（Deferred のまま未解決）。
clock = openDuration;
const callsBeforeProbe = downed.callCount;
const probeA = dispatchGuarded(pool, breaker, downed, { region: "downed", id: "A" });
await Promise.resolve();
assert.equal(breaker.peek(), "half-open");
assert.equal(downed.callCount, callsBeforeProbe + 1); // Aが唯一のプローブとして飛んだ

// Aが飛行中（未解決）のまま、同時に便Bを送る→プローブは既に飛んでいるので即 Fallback。
const receiptB = await dispatchGuarded(pool, breaker, downed, { region: "downed", id: "B" });
assert.deepEqual(receiptB, { region: "downed", delivered: false });

// 倒れた配送所への send 呼び出しは、Aの1回だけ（Bは2本目を送らせない）。
assert.equal(downed.callCount, callsBeforeProbe + 1);

1
2
3
4
5

// プローブ成功（resolve）→ Closed に繋ぎ直す。
downed.pending[downed.pending.length - 1]!.resolve({ region: "downed", delivered: true });
const probeReceipt = await probe;
assert.deepEqual(probeReceipt, { region: "downed", delivered: true });
assert.equal(breaker.peek(), "closed");

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// プローブ失敗（reject）→ 再び Open。openedAt が更新される。
downed.pending[downed.pending.length - 1]!.reject(new Error("still down"));
const probeReceipt = await probe;
assert.deepEqual(probeReceipt, { region: "downed", delivered: false });
assert.equal(breaker.peek(), "open");

// 以降は即 Fallback、刻が再び満ちるまで試験しない。
const callsBeforeRetry = downed.callCount;
const r1 = await dispatchGuarded(pool, breaker, downed, { region: "downed", id: "retry-too-soon" });
assert.deepEqual(r1, { region: "downed", delivered: false });
assert.equal(downed.callCount, callsBeforeRetry); // send は呼ばれていない＝まだ断たれたまま

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

$ node --test
▶ Before: dispatchDirect（自動結界なし・直接送り）
  ✔ 1【連鎖】倒れた相手を待つ使い魔が塞がり、健全な便が凍る
  ✔ 2【誤診反証・使い捨て】早馬（リトライ）を増やすと、倒れた相手への到達がN倍に増えるだけ
▶ After: CircuitBreaker / dispatchGuarded（自動結界で送りを包む）
  ✔ 3【局所化】結界が断たれた後、健全な便は倒れた相手に巻き込まれない（Beforeと同じ災害）
  ✔ 4【Closed→Open】失敗が閾値に達すると断つ（境界＝閾値ちょうど）
  ✔ 5【Open→Half-Open】刻が満ちると次の便で試験へ（境界＝刻ちょうど・遅延遷移）
  ✔ 6【Half-Open単一プローブ・ゲート】回復中は一筋だけ通す（並行・群がり軸）
  ✔ 7【Half-Open→Closed】プローブ成功で繋ぎ直す（以降は普通に送れる・失敗カウントもリセット）
  ✔ 8【Half-Open→Open】プローブ失敗で再び断つ（刻が再び満ちるまで試験しない）
ℹ tests 8
ℹ pass 8
ℹ fail 0