shared/com.santimattius.resilient.circuitbreaker/CircuitBreakerConfig

CircuitBreakerConfig

Configuration for a CircuitBreaker.

This class provides a flexible way to configure the behavior of a CircuitBreaker instance using a builder-style pattern.

Example:

val config = CircuitBreakerConfig().apply {
    failureThreshold = 10
    timeout = 30.seconds
    onStateChange = { newState -> println("Circuit state changed to $newState") }
}
val circuitBreaker = CircuitBreaker.create(config)

Constructors

CircuitBreakerConfig

constructor()

Properties

failureRateThreshold

var failureRateThreshold: Double?

When non-null, enables failure-rate mode using a count-based sliding window. The circuit opens when the failure rate (as a percentage, 0.0–100.0) computed over the last minimumNumberOfCalls outcomes meets or exceeds this value. The rate is not evaluated until minimumNumberOfCalls have been recorded. Cannot be combined with slidingWindow; setting both throws IllegalArgumentException. Defaults to null (disabled).

failureThreshold

var failureThreshold: Int

Number of failures required to open the circuit from CLOSED.

halfOpenMaxCalls

var halfOpenMaxCalls: Int

The maximum number of concurrent calls allowed when the circuit is in the HALF_OPEN state. This is to test if the downstream service has recovered. Additional calls beyond this limit will be rejected. Defaults to 3.

minimumNumberOfCalls

var minimumNumberOfCalls: Int

Minimum number of calls that must be recorded before failureRateThreshold is evaluated. Acts as both the minimum-calls guard and the ring-buffer size. Defaults to 10. Only meaningful when failureRateThreshold is non-null.

onStateChange

var onStateChange: (CircuitState) -> Unit

Invoked when the circuit state changes. Receives the new state only. When the policy is built via com.santimattius.resilient.composition.resilient, telemetry events (ResilientEvent.CircuitStateChanged) receive both the previous and new state.

shouldRecordFailure

var shouldRecordFailure: (Throwable) -> Boolean

shouldRecordResult

var shouldRecordResult: (Any?) -> Boolean?

Optional predicate evaluated after the block returns without throwing.

slidingWindow

var slidingWindow: Duration?

When null (default), failureThreshold counts consecutive failures in CLOSED. When set to a positive duration, failures in CLOSED are recorded with a timestamp; entries older than this window are discarded. The circuit opens when at least failureThreshold failures fall inside the window. Success in CLOSED only prunes expired failures (it does not clear recent failures). HALF_OPEN and OPEN behavior is unchanged.

successThreshold

var successThreshold: Int

The number of consecutive successes required to close the circuit when it is in the HALF_OPEN state. If a call succeeds, the circuit transitions back to CLOSED. Defaults to 2.

timeout

var timeout: Duration

The duration the circuit will remain in the OPEN state before transitioning to HALF_OPEN. During this time, all calls will fail immediately with a CircuitBreakerOpenException. Defaults to 60.seconds.