Arrow Resilience Kit/com.sorinirmies.arrow.resiliencekit/CircuitBreaker

CircuitBreaker

Circuit breaker pattern to prevent cascading failures.

The circuit breaker prevents cascading failures by stopping calls to failing services. It has three states: Closed (normal), Open (failing), and Half-Open (testing recovery).

States:

Closed: Normal operation, calls are allowed
Open: Circuit is broken, calls fail immediately
Half-Open: Testing if service has recovered

State transitions:

Closed -> Open: When failure threshold is exceeded
Open -> Half-Open: After reset timeout expires
Half-Open -> Closed: When success threshold is reached
Half-Open -> Open: When any failure occurs

Basic usage:

val breaker = CircuitBreaker.create(config = CircuitBreakerConfig(
    failureThreshold = 5,
    resetTimeout = 30.seconds
))

val result = breaker.execute {
    callExternalService()
}

With fallback:

val result = breaker.executeOrFallback(
    fallback = { cachedValue() }
) {
    callExternalService()
}

State monitoring:

when (breaker.currentState()) {
    CircuitBreakerState.Closed -> println("Service healthy")
    CircuitBreakerState.Open -> println("Service unavailable")
    CircuitBreakerState.HalfOpen -> println("Testing service...")
}

DSL builder:

val breaker = circuitBreaker {
    failureThreshold = 5
    resetTimeout = 30.seconds
    halfOpenSuccessThreshold = 3
}

Parameters

config

Configuration for circuit breaker behavior

Types

Companion

object Companion

Factory for CircuitBreaker.

Functions

addListener

fun addListener(listener: CircuitBreakerListener)

Adds a listener for circuit breaker state changes.

currentState

suspend fun currentState(): CircuitBreakerState

Gets the current state of the circuit breaker.

execute

suspend fun <T> execute(block: suspend () -> T): T

Executes an operation through the circuit breaker.

executeOrFallback

suspend fun <T> executeOrFallback(fallback: suspend (CircuitBreakerOpenException) -> T, block: suspend () -> T): T

Executes an operation with a fallback if the circuit is open.

failures

suspend fun failures(): Int

Gets the current failure count.

reset

suspend fun reset()

Manually resets the circuit breaker to closed state.

successes

suspend fun successes(): Int

Gets the current success count (in half-open state).

trip

suspend fun trip()

Manually opens the circuit breaker.

Inherited functions

asPolicy

fun CircuitBreaker.asPolicy(): Policy

Adapts this CircuitBreaker into a Policy.