@NonNullByDefault

Package com.linecorp.armeria.client.circuitbreaker

Failure detection and fallback mechanism based on circuit breaker pattern.

Setup Client with Circuit Breaker

Example

 Iface helloClient =
     Clients.builder("tbinary+http://127.0.0.1:8080/hello")
            .decorator(CircuitBreakerClient.newDecorator(
                    CircuitBreaker.builder("hello").build()))
            .build(Iface.class);
 

A Unit of Failure Detection

You can specify a unit of failure detection from the following:

• per remote service (as shown in the example above)
• per method
• per remote host
• per remote host and method

Example

 // Setup with per-method failure detection
 AsyncIface helloClient =
     Clients.builder("tbinary+http://127.0.0.1:8080/hello")
            .decorator(CircuitBreakerClient.newPerMethodDecorator(
                    method -> CircuitBreaker.builder(method).build()))
            .build(AsyncIface.class);
 

Fallback

Once a failure is detected, A FailFastException is thrown from the client. You can write a fallback code by catching the exception.

Example

 try {
     helloClient.hello("line");
 } catch (TException e) {
     // error handling
 } catch (FailFastException e) {
    // fallback code
 }
 

Example in Async Client

 helloClient.hello("line", new AsyncMethodCallback() {
     public void onComplete(Object response) {
         // response handling
     }
     public void onError(Exception e) {
         if (e instanceof TException) {
             // error handling
         } else if (e instanceof FailFastException) {
             // fallback code
         }
     }
 });
 

Circuit States and Transitions

The circuit breaker provided by this package is implemented as a finite state machine consisting of the following states and transitions.

CLOSED

The initial state. All requests are sent to the remote service. If the failure rate exceeds the specified threshold, the state turns into OPEN.

OPEN

All requests fail immediately without calling the remote service. After the specified time, the state turns into HALF_OPEN.

HALF_OPEN

Only one trial request is sent at a time.

• If it succeeds, the state turns into CLOSED.
• If it fails, the state returns to OPEN.
• If it doesn't complete within a certain time, another trial request will be sent again.

Circuit Breaker Configurations

The behavior of a circuit breaker can be modified via CircuitBreakerBuilder.

failureRateThreshold

The threshold of failure rate(= failure/total) to detect a remote service fault.

minimumRequestThreshold

The minimum number of requests within the time window necessary to detect a remote service fault.

circuitOpenWindow

The duration of OPEN state.

trialRequestInterval

The interval of trial request in HALF_OPEN state.

counterSlidingWindow

The time length of sliding window to accumulate the count of events.

counterUpdateInterval

The interval that a circuit breaker can see the latest count of events.

exceptionFilter

A filter that decides whether a circuit breaker should deal with a given error.

Interface Summary

Interface	Description
CircuitBreaker	A circuit breaker, which tracks the number of success/failure requests and detects a remote service failure.
CircuitBreakerListener	The listener interface for receiving CircuitBreaker events.
CircuitBreakerMapping	Returns a CircuitBreaker instance from remote invocation parameters.
CircuitBreakerRule	Determines whether a Response should be reported as a success or failure to a CircuitBreaker.
CircuitBreakerRuleWithContent<T extends Response>	Determines whether a Response should be reported as a success or failure to a CircuitBreaker using the content of the Response.

Class Summary

Class	Description
AbstractCircuitBreakerClient<I extends Request,O extends Response>	A Client decorator that handles failures of remote invocation based on circuit breaker pattern.
AbstractCircuitBreakerClientBuilder<O extends Response>	A skeletal builder implementation that builds a new AbstractCircuitBreakerClient or its decorator function.
CircuitBreakerBuilder	Builds a CircuitBreaker instance using builder pattern.
CircuitBreakerClient	An HttpClient decorator that handles failures of HTTP requests based on circuit breaker pattern.
CircuitBreakerClientBuilder	Builds a new CircuitBreakerClient or its decorator function.
CircuitBreakerDecision	A CircuitBreakerDecision that determines a Response as a CircuitBreakerDecision.success() or CircuitBreakerDecision.failure(), or CircuitBreakerDecision.ignore()s a Response.
CircuitBreakerListenerAdapter	A skeletal CircuitBreakerListener implementation in order for a user to implement only the methods what he or she really needs.
CircuitBreakerRpcClient	An RpcClient decorator that handles failures of RPC remote invocation based on circuit breaker pattern.
CircuitBreakerRpcClientBuilder	Builds a new CircuitBreakerRpcClient or its decorator function.
CircuitBreakerRuleBuilder	A builder for creating a new CircuitBreakerRule.
CircuitBreakerRuleWithContentBuilder<T extends Response>	A builder for creating a new CircuitBreakerRuleWithContent.
EventCount	An immutable object that stores the count of events.

Enum Summary

Enum	Description
CircuitState	Defines the states of circuit breaker.

Exception Summary

Exception	Description
FailFastException	An exception indicating that a request has been failed by circuit breaker.