Package com.linecorp.armeria.client.circuitbreaker

@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.

Related Packages

Package	Description
com.linecorp.armeria.client	Client core.

Class	Description
AbstractCircuitBreakerClient<I extends Request,O extends Response>	A Client decorator that handles failures of remote invocation based on circuit breaker pattern.
AbstractCircuitBreakerClientBuilder<I extends Request,O extends Response>	A skeletal builder implementation that builds a new AbstractCircuitBreakerClient or its decorator function.
AbstractCircuitBreakerMappingBuilder	An abstract builder class for building a CircuitBreakerMapping based on a combination of host, method and path.
CircuitBreaker	A circuit breaker, which tracks the number of success/failure requests and detects a remote service failure.
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.
CircuitBreakerClientHandler	A handler used by a CircuitBreakerClient to integrate with a circuit breaker.
CircuitBreakerDecision	A CircuitBreakerDecision that determines a Response as a CircuitBreakerDecision.success() or CircuitBreakerDecision.failure(), or CircuitBreakerDecision.ignore()s a Response.
CircuitBreakerFactory	A functional interface that represents a mapper factory, mapping a combination of host, method and path to a CircuitBreaker.
CircuitBreakerListener	The listener interface for receiving CircuitBreaker events.
CircuitBreakerListenerAdapter	A skeletal CircuitBreakerListener implementation in order for a user to implement only the methods what he or she really needs.
CircuitBreakerMapping	Returns a CircuitBreaker instance from remote invocation parameters.
CircuitBreakerMappingBuilder	Builder class for building a CircuitBreakerMapping based on a combination of host, method and path.
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.
CircuitBreakerRule	Determines whether a Response should be reported as a success or failure to a CircuitBreaker.
CircuitBreakerRuleBuilder	A builder for creating a new CircuitBreakerRule.
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.
CircuitBreakerRuleWithContentBuilder<T extends Response>	A builder for creating a new CircuitBreakerRuleWithContent.
CircuitState	Defines the states of circuit breaker.
ClientCircuitBreakerGenerator<T>	Returns a circuit breaker implementation from remote invocation parameters.
EventCount	An immutable object that stores the count of events.
FailFastException	An exception indicating that a request has been failed by circuit breaker.