Class CircuitBreaker

java.lang.Object

com.eqixiac.equinix.core.http.CircuitBreaker

public final class CircuitBreaker
extends Object

A simple, opt-in consecutive-failure circuit breaker for the SDK's request execution path.

Disabled by default; enable it via EquinixConfig.builder().circuitBreaker(new CircuitBreaker(5, 30_000)).build(). When enabled it is consulted for every request attempt (including retry attempts), alongside RetryPolicy:

• CLOSED (normal): requests flow through. Each service failure - a 5xx response or a transport IOException - increments a consecutive-failure counter; any completed HTTP exchange with a status below 500 resets it. Once the counter reaches failureThreshold, the breaker opens.
• OPEN: every request is rejected immediately with a CircuitOpenException (no HTTP exchange happens) until openCooldownMillis elapses. Outcomes reported by straggler requests - attempts admitted before the circuit opened that complete afterwards - are ignored: a straggler success must not snap the circuit shut (that would bypass the cooldown and the half-open probe) and a straggler failure must not extend the cooldown.
• HALF_OPEN: after the cooldown, a single probe request is admitted (further requests are rejected while the probe is pending - a probe slot expires after another cooldown, so a probe that dies without reporting cannot wedge the breaker). Only the probe's completion moves the breaker on: a successful probe closes it; a failed probe re-opens it for another cooldown.

Client-side errors (4xx) are deliberately not counted as failures - they indicate the service is up and answering. Rate limiting (429) is likewise left to RetryPolicy's backoff. Cooldowns are measured on an injectable Clock (a monotonic clock by default, see CircuitBreaker(int, long, Clock)), so tests can advance time instead of sleeping. Instances are thread-safe and may be shared by all requests of a client (which is exactly how the SDK uses them).

Author:

ianjones

See Also:

• CircuitOpenException

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	CircuitBreaker.State	The breaker's lifecycle state.

Constructor Summary

Constructors

Constructor	Description
CircuitBreaker(int failureThreshold, long openCooldownMillis)	Creates a breaker that opens after failureThreshold consecutive service failures and admits a half-open probe after openCooldownMillis of rejection.
CircuitBreaker(int failureThreshold, long openCooldownMillis, Clock clock)	Creates a breaker that measures its cooldowns on the given clock.

Method Summary

Modifier and Type	Method	Description
void	acquire()	Requests permission to execute one attempt.
CircuitBreaker.State	getState()	The current state, for diagnostics.
void	recordFailure()	Records a service failure (5xx response or transport IOException).
void	recordSuccess()	Records a healthy outcome (any completed HTTP exchange with status < 500).

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

CircuitBreaker

public CircuitBreaker(int failureThreshold,
 long openCooldownMillis)

Creates a breaker that opens after failureThreshold consecutive service failures and admits a half-open probe after openCooldownMillis of rejection.

Parameters:

failureThreshold - number of consecutive failures that opens the circuit (must be >= 1)

openCooldownMillis - how long the circuit stays open before a probe is admitted (must be >= 1)

CircuitBreaker

public CircuitBreaker(int failureThreshold,
 long openCooldownMillis,
 Clock clock)

Creates a breaker that measures its cooldowns on the given clock. Only differences between Clock.millis() readings are used, so any clock (including a fixed or manually advanced test clock) works.

Parameters:

failureThreshold - number of consecutive failures that opens the circuit (must be >= 1)

openCooldownMillis - how long the circuit stays open before a probe is admitted (must be >= 1)

clock - the time source for cooldowns (must not be null)

Method Details

acquire

public void acquire()
             throws CircuitOpenException

Requests permission to execute one attempt. Returns normally when the attempt may proceed; throws when the circuit is open (or a half-open probe is already pending).

Throws:

CircuitOpenException - if the request must not be sent

recordSuccess

public void recordSuccess()

Records a healthy outcome (any completed HTTP exchange with status < 500). In CLOSED this resets the consecutive-failure count; in HALF_OPEN it is the probe's success and closes the circuit. In OPEN it is ignored - it can only come from a straggler request admitted before the circuit opened, and closing on it would bypass the cooldown and the half-open probe.

recordFailure

public void recordFailure()

Records a service failure (5xx response or transport IOException). In CLOSED this opens the circuit once the consecutive-failure count reaches the threshold; in HALF_OPEN it is the probe's failure and re-opens the circuit for a fresh cooldown. In OPEN it is ignored - a straggler's late failure must not keep extending the cooldown.

getState

public CircuitBreaker.State getState()

The current state, for diagnostics. Note that an elapsed-cooldown OPEN circuit reports OPEN until the next acquire() transitions it to HALF_OPEN.

Returns:

the current CircuitBreaker.State