Circuit Breaker

Stop calling a failing dependency to prevent cascading failures.

resilience

Detailed Description

Circuit breakers protect callers when dependencies are slow or failing.

They should be combined with timeouts and fallbacks so failure behavior is predictable.

Visual Diagram

[CLOSED] -- failures >= threshold --> [OPEN]
[OPEN] -- resetTimeout elapsed --> [HALF-OPEN]
[HALF-OPEN] -- probe success --> [CLOSED]
[HALF-OPEN] -- probe failure --> [OPEN]
OPEN behavior: fast-fail + fallback

Tradeoffs

Pros

Prevents cascade, enables fallback

Cons

Needs careful thresholds and monitoring

Examples: opossum, Resilience4j, Hystrix

Half-Open Walkthrough

1 / 6

CLOSED

OPEN

HALF-OPEN

CLOSED -- failures threshold reached --> OPEN

OPEN -- resetTimeout expires --> HALF-OPEN

HALF-OPEN -- probe success --> CLOSED

HALF-OPEN -- probe failure --> OPEN

Step 1: Closed and healthy

Requests flow normally while the breaker tracks failures.

In CLOSED, all traffic is allowed. The breaker only observes errors and latency; nothing is blocked yet.

state: CLOSED

failures: 0

cooldown: 0s

probe allowed: no

concurrent calls: flow normally

probe result: pending

Node.js note: with opossum, this behavior is built in. Configure resetTimeout for OPEN duration and listen to the halfOpen event for probe transitions.

Why Each Stage Exists

CLOSED

Normal operation. All requests pass through while the breaker tracks failures. If errors cross the threshold in a rolling window, it trips to OPEN.

OPEN

Protection mode. Calls are blocked immediately (fast-fail + fallback) so threads do not pile up and downstream gets time to recover. After timeout, it moves to HALF-OPEN.

HALF-OPEN

Recovery probe mode. Only a small, controlled probe is allowed through. If probe succeeds, transition to CLOSED and reset counters. If probe fails, snap back to OPEN and restart timeout.

POC Code (Node.js + opossum)

Read-only reference implementation matching your setup.

shared/resilience/circuitBreaker.js

Options Explained

timeout: 1000: max time (ms) a downstream call can run before the breaker treats it as a failure.

errorThresholdPercentage: 50: if failures cross 50% in the rolling stats window, breaker moves from CLOSED to OPEN.

resetTimeout: 10000: how long (ms) breaker stays OPEN before entering HALF-OPEN and allowing a probe request.

services/order/index.js