Review brief

Advanced45 min

A client library is adding a circuit breaker around an unreliable dependency. Calls overlap, some business-validation failures should not affect dependency health, and the injected clock makes cooldown transitions deterministic.

Behavioral contract

In closed state, three consecutive counted dependency failures open the breaker; any success resets the consecutive count. An error for which isCountedFailure returns false propagates without incrementing failures or changing the breaker health state.
Open calls fail fast until 30 seconds have elapsed since the most recent trip. Then exactly one caller becomes the half-open probe and all other calls fail fast while it runs. If that probe ends with an uncounted error, clear only its probe ownership, keep an idle half-open state, and let a later caller become the next sole probe.
A successful half-open probe closes the breaker with zero failures. A counted failed probe immediately reopens it and starts a fresh 30-second cooldown.
Completions from operations admitted under an older state generation must not close, trip, or increment a newer generation.

Review instructions

1Trace overlapping closed calls and multiple callers arriving at the cooldown boundary.
2Anchor each finding to the narrowest useful changed line and explain the availability impact.
3Recommend a direction rather than writing replacement code.
4Prioritize no more than five findings.

Learning objectives

• Enforce single-probe half-open behavior
• Protect breaker state from stale concurrent completions
• Maintain consecutive-failure and cooldown invariants

src/circuit-breaker-types.tsTypeScript

@@ -0,0 +1,11 @@

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

3+export interface CircuitBreakerOptions {

4+ failureThreshold: number;

5+ cooldownMs: number;

6+ now(): number;

7+ /** False means a half-open attempt is inconclusive, not a failed probe. */

8+ isCountedFailure(error: unknown): boolean;

9+}

10+

11+export class CircuitOpenError extends Error {}

Reference solution

The findings below are ordered by priority.

Findings

1. Every caller can enter during the half-open probe

Location: src/circuit-breaker.ts:14-22

The first post-cooldown caller changes state to half-open, but the admission check handles only open. Every subsequent caller falls through and invokes the dependency while the probe is unresolved, turning one cautious probe into an unbounded recovery surge.

Reserve half-open ownership atomically for one caller and fail all other half-open admissions fast until that probe settles.

2. Stale completions can overwrite a newer breaker generation

Location: src/circuit-breaker.ts:23-39

Every admitted operation mutates the current state when it eventually settles. A slow success that began before another call opened the breaker can later close it, while a slow failure from an old generation can increment or trip a breaker already recovered by a probe.

Associate admission with a state generation and apply completion transitions only when that generation still owns them.

3. Uncounted errors change breaker health state

Location: src/circuit-breaker.ts:28-39

The catch path increments for every error and never calls isCountedFailure. In closed state, expected validation or caller errors can open the dependency circuit even though they say nothing about dependency health. In half-open state, an uncounted, inconclusive rejection is incorrectly treated as a failed health probe and reopens the circuit.

Classify the error before applying a health transition. Propagate an uncounted closed-state error without changing failures or state; for an uncounted half-open result, clear probe ownership but keep an idle half-open state so one later caller can perform the next probe.

4. Success does not reset the consecutive-failure count

Location: src/circuit-breaker.ts:23-27

The success branch closes state but leaves failures unchanged. Two failures, then a success, then one failure meet a threshold of three even though the final failure is only the first in a new consecutive sequence.

Reset the count on every valid closed-state success and on a successful half-open probe.

5. A counted failed probe reuses the expired cooldown timestamp

Location: src/circuit-breaker.ts:29-37

When open transitions to half-open, openedAt still contains the original trip time. A counted failed probe sets state back to open but refreshes the timestamp only when it is null, so the next caller sees an already elapsed cooldown and probes immediately again.

On every counted half-open failure, record a new trip time and begin a full cooldown.

Reasonable non-findings

Failing open-state calls fast before invoking the operation is correct.
Injecting the clock and failure classifier makes transition tests deterministic.
Propagating the original operation error is appropriate for the single admitted probe or closed call.