This manual is a work in progress and is currently incomplete.
If you'd like to help improve it, and we hope you do, please see the README.

17 Hystrix

If your application is part of a distributed architecture like microservices, has dependencies on other distributed services or a client library that can potentially result in network requests, then it is essential that you defend your application with Hystrix. Part of the Netflix OSS Platform, Hystrix is a library that provides fault tolerance and greater control in the face of failure resulting in reduced latency, increased responsiveness and resilience for your application. See the Hystrix Wiki for common usage patterns.

Hystrix can also help you reduce the number of external network calls your application makes by de-duping (Request Caching) and batching (Request Collapsing) your requests within a request context. The ratpack-hystrix JAR provides and registers a Hystrix Concurrency Strategy with Hystrix that allows the Ratpack Registry to be used for managing the Hystrix Request Context. What all that means is that you do not need to initialise a Hystrix Request Context (HystrixRequestContext context = HystrixRequestContext.initializeContext();) before a request begins as detailed in the Hystrix wiki.

One of the best features of Hystrix is the metrics that are captured and the dashboard provided for viewing them real-time. This is achieved by streaming metrics out of your application over SSE and the ratpack-hystrix JAR provides a handler that will do this for you.

The ratpack-hystrix module as of 1.5.0 is built against (and depends on) RxJava 1.5.13.

17.1 Initialization

If you do not need to use any Hystrix request scoped features (request caching, request collapsing, request log) or the Ratpack handler for streaming metrics then you can just include Hystrix as a dependency and there is no initialization required. If you do want to use these features however, then your application should depend on the ratpack-hystrix module and simply register the Guice module, HystrixModule.

17.2 Which Command execution to use

Hystrix provides three types of Command execution, synchronous, asynchronous and reactive. Out of the three only reactive is actually non-blocking. Synchronous and asynchronous command execution will work with Ratpack, as is demonstrated in the integration tests, but for maximum performance only reactive execution is recommended. If you do not wish to use Observables however, then you can convert them to Ratpack Promises instead using RxRatpack#promise or RxRatpack#promiseSingle.

import com.netflix.hystrix.HystrixCommandGroupKey;
import com.netflix.hystrix.HystrixObservableCommand;
import ratpack.exec.Promise;
import ratpack.rx.RxRatpack;
import rx.Observable;
public class CommandFactory {

  public static Promise<String> fooCommand() {
    Observable<String> command = new HystrixObservableCommand<String>(HystrixCommandGroupKey.Factory.asKey("foo-command")) {
      @Override
      protected Observable<String> construct() {
        return Observable.just("foo");
      }
    }.toObservable();

    return RxRatpack.promiseSingle(command);
  }
}

There is a fourth command execution under construction, HystrixAsyncCommand that will also be non-blocking and hopefully available in 1.4.0 Final.

17.3 Executing blocking code in a command

When you have a command that needs to execute blocking code, e.g. for an external resource that you do not have a non blocking client for, then inject ExecControl into your command and observe ExecControl#blocking. You can see an example of how to do this in Example-Books.

17.4 Streaming metrics

TODO

17.4.1 Turbine

TODO