clj-http-hystrix

A Clojure library to wrap clj-http requests as hystrix commands whenever a request options map includes :hystrix/... keys.

Usage

When you start your app, add:

(clj-http-hystrix.core/add-hook)

Whenever you make an http request, add one or more of the hystrix-clj options to your options map, e.g.:

(http/get "http://www.google.com" {:hystrix/command-key             :default
                                   :hystrix/fallback-fn             default-fallback
                                   :hystrix/group-key               :default
                                   :hystrix/threads                 10
                                   :hystrix/queue-size              5
                                   :hystrix/timeout-ms              1000
                                   :hystrix/breaker-request-volume  20
                                   :hystrix/breaker-error-percent   50
                                   :hystrix/breaker-sleep-window-ms 5000
                                   :hystrix/bad-request-pred        client-error?})

Requests without any :hystrix/... keys won't use Hystrix. If you include at least one :hystrix/... key then any keys not specified will take the above (default) values.

Custom default values can be specified when registering with add-hook. Any keys you supply will override the defaults shown above:

(clj-http-hystrix.core/add-hook {:hystrix/timeout-ms 2500
                                 :hystrix/queue-size 12})

Bad requests

Hystrix allows some failures to be marked as bad requests, that is, requests that have failed because of a badly formed request rather than an error in the downstream service¹. clj-http-hystrix allows a predicate to be supplied under the :hystrix/bad-request-pred key, and if this predicate returns true for a given request & response, then the failure will be considered a 'bad request' (and not counted towards the failure metrics for a command).

By default, all client errors (4xx family of response codes) are considered Hystrix bad requests and are not counted towards the failure metrics for a command. There are some useful predicates and predicate generators provided².

Cached vs dynamic configuration

Hystrix caches configuration for a command and hence there are limits to how this library can react to configuration options that vary dynamically. For a given command-key, the :hystrix/timeout-ms will be fixed on first use. This means it's a bad idea to reuse the :hystrix/command-key value in many parts of your app. When you want a new configuration, you should use a new :hystrix/command-key value.

The same is true for thread pools - configuration is cached per :hystrix/group-key, so if you need to use a different value for :hystrix/queue-size or :hystrix/threads then you should use a new :hystrix/group-key value.

License

Copyright © 2014 Joe Littlejohn, Mark Tinsley

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.