freno-client/README.md

A Ruby client and throttling library for [Freno](https://github.com/github/freno): the cooperative, highly available throttler service.

## Current status

`Freno::Client`, as [Freno](https://github.com/github/freno) itself, is in active development and its API can still change.

## Installation

Add this line to your application's Gemfile:

```ruby
gem "freno-client"
```

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install freno-client

## Usage

`Freno::Client` uses [faraday](https://github.com/lostisland/faraday) to abstract the http client of your choice:

To start using the client, give it a faraday instance pointing to Freno's base URL.

```ruby
require "freno/client"

FRENO_URL = "http://freno.domain.com:8111"
faraday   = Faraday.new(FRENO_URL)
freno     = Freno::Client.new(faraday)

freno.check?(app: :my_app, store_name: :my_cluster)
# => true

freno.replication_delay(app: :my_app, store_name: :my_cluster)
# => 0.125
```

### Providing sensible defaults

If most of the times you are going to ask Freno about the same app and/or storage name, you can tell the client to use some defaults, and override them as necessary.

```ruby
freno = Freno::Client.new(faraday) do |client|
  client.default_store_name = :my_cluster
  client.default_app        = :my_app
end

freno.check?
# => true (Freno thinks that `my_app` can write to `main` storage)

freno.check?(app: :another_app, store_name: :another_storage)
# => false (Freno thinks that `another_app` should not write to `another_storage`)
```

### What can I do with the client?

#### Asking whether an app can write to a certain storage. ([`check` requests](https://github.com/github/freno/blob/master/doc/http.md#check-requests))

If we want to get a deep sense on why freno allowed or not, writing to a certain storage.

```ruby
result = freno.check(app: :my_app, store_name: :my_cluster)
# => #<Freno::Client::Requests::Result ...>

result.ok?
# => false

result.failed?
# => true

result.code
# => 429

result.meaning
# => :too_many_requests
```

Or if we only want to know if we can write:

```ruby
result = freno.check?(app: :my_app, store_name: :my_cluster)
# => true or false (a shortcut for `check.ok?`)
```

#### Asking whether replication delay is below a certain threshold. ([`check-read` requests](https://github.com/github/freno/blob/master/doc/http.md#specialized-requests))

```ruby
result = freno.check_read(threshold: 0.5, app: :my_app, store_name: :my_cluster)
# => #<Freno::Client::Requests::Result ...>

result.ok?
# => true

result.failed?
# => false

result.code
# => 200

result.meaning
# => :ok
```

Or if we only want to know if we can read:

```ruby
freno.check?(threshold: 0.5, app: :my_app, store_name: :my_cluster)
# => true or false (a shortcut for `check_read.ok?`)
```

#### Asking what's the replication delay

Freno's response to [`GET /check`](https://github.com/github/freno/blob/master/doc/http.md#get-method) includes the replication delay value in seconds. The `replication_delay` method in the client returns this information.

```ruby
freno.replication_delay(app: :my_app, store_name: :my_cluster)
# => 0.125
```

#### Cross-cutting concerns with decorators

Decorators can be used augment the client with custom features.

A decorator is anything that has a `:request` accessor and can forward the execution of `perform` to it.

The following is an example of a decorator implementing a read-trough cache.

```ruby
class Cache
  attr_accessor :request

  def initialize(cache, ttl)
    @cache = cache
    @ttl = ttl
  end

  def perform(**kwargs)
    @cache.fetch("freno:client:v1:#{args.hash}", ttl: @ttl) do
      request.perform(kwargs)
    end
  end
end
```

You can use it to decorate a single kind of request to freno:

```ruby
freno = Freno::Client.new(faraday) do |client|
  client.decorate :replication_delay, with: Cache.new(App.cache, App.config.ttl)
end
```

Or every kind of request:

```ruby
freno = Freno::Client.new(faraday) do |client|
  client.decorate :all, with: Cache.new(App.cache, App.config.ttl)
end
```

Additionally, decorators can be composed in multiple ways. The following client
applies logging and instrumentation to all the requests, and it also applies caching, **before** the previous concerns, to `replication_delay` requests.

```ruby
freno = Freno::Client.new(faraday) do |client|
  client.decorate :replication_delay, with: caching
  client.decorate :all, with: [logging, instrumentation]  
end
```

### Throttler objects

Apart from the operations above, freno-client comes with `Freno::Throttler`, a Ruby library for throttling. You can use it in the following way:

```ruby
require "freno/throttler"

client    = Freno::Client.new(faraday)
throttler = Freno::Throttler.new(client: client, app: :my_app)
context   = :my_cluster

bid_data_set.each_slice(SLICE_SIZE) do |slice|
  throttler.throttle(context) do
    update(slice)
  end
end
```

In the above example, `Freno::Throttler#throttle(context, &block)` will check freno to determine whether is OK to proceed with the given block. If so, the block will be executed immediately, otherwise the throttler will sleep and try
again.

#### Throttler configuration

```ruby
module Freno
  class Throttler

    DEFAULT_WAIT_SECONDS = 0.5
    DEFAULT_MAX_WAIT_SECONDS = 10

    def initialize(client: nil,
                    app: nil,
                    mapper: Mapper::Identity,
                    instrumenter: Instrumenter::Noop,
                    circuit_breaker: CircuitBreaker::Noop,
                    wait_seconds: DEFAULT_WAIT_SECONDS,
                    max_wait_seconds: DEFAULT_MAX_WAIT_SECONDS)


      @client           = client
      @app              = app
      @mapper           = mapper
      @instrumenter     = instrumenter
      @circuit_breaker  = circuit_breaker
      @wait_seconds     = wait_seconds
      @max_wait_seconds = max_wait_seconds

      yield self if block_given?

      validate_args
    end

    ...
  end
end
```

A Throttler instance will make calls to freno on behalf of the given `app`,
using the given `client` (an instance of `Freno::Client`).

You optionally provide the time you want the throttler to sleep in case the check to freno fails, this is `wait_seconds`.

If replication lags badly, you can control until when you want to keep sleeping
and retrying the check by setting `max_wait_seconds`. When that times out, the throttle will raise a `Freno::Throttler::WaitedTooLong` error.

#### Instrumenting the throttler

You can also configure the throttler with an `instrumenter` collaborator to subscribe to events happening during the `throttle` call.

An instrumenter is an object that responds to `instrument(event_name, payload = {})` to receive events from the throttler. One could use `ActiveSupport::Notifications` as an instrumenter and subscribe to "freno.*" events somewhere else in the application, or implement one like the following to push some metrics to a stats system.

```ruby
  class StatsInstrumenter

    attr_reader :stats

    def initialize(stats:)
      @stats = stats
    end

    def instrument(event_name, payload)
      method = event_name.sub("throttler.", "")
      send(method, payload) if respond_to?(method)
    end

    def called(payload)
      increment("throttler.called", tags: extract_tags(payload))
    end

    def waited(payload)
      stats.histogram("throttler.waited", payload[:waited], tags: extract_tags(payload))
    end

    ...

    def circuit_open(payload)
      stats.increment("throttler.circuit_open", tags: extract_tags(payload))
    end

    private

    def extract_tags(payload)
      cluster_names = payload[:store_names] || []
      cluster_tags = cluster_names.map{ |cluster_name| "cluster:#{cluster_name}" }
    end
  end
```

#### Adding resiliency

The throttler can also receive a `circuit_breaker` object to implement resiliency.

With that information it receives, the circuit breaker determines whether or not to allow the next request. A circuit is said to be open when the next request is not allowed; and it's said to be closed when the next request is allowed

If the throttler waited too long, or an unexpected error happened; the circuit breaker will receive a `failure`. If in contrast it succeeded, the circuit breaker will receive a `success` message.

Once the circuit is open, the throttler will not try to throttle calls, an instead throw a `Freno::Throttler::CircuitOpen`

The following is a simple per-process circuit breaker implementation:

```ruby
class MemoryCircuitBreaker

  DEFAULT_CIRCUIT_RETRY_INTERVAL = 10

  def initialize(circuit_retry_interval: DEFAULT_CIRCUIT_RETRY_INTERVAL)
    @circuit_closed = true
    @last_failure = nil
    @circuit_retry_interval = circuit_retry_interval
  end

  def allow_request?
    @circuit_closed || (Time.now - @last_failure) > @circuit_retry_interval
  end

  def success
    @circuit_closed = true
  end

  def failure
    @last_failure = Time.now
    @circuit_closed = false
  end
end
```

#### Flexible throttling strategies

The throttler uses a `mapper` to determine, based on the context provided to `#throttle`, the clusters which replication delay needs to be checked.

By default the throttler uses `Mapper::Identity`, which expect the context to be the store name(s) to check:

```ruby
# will check my_cluster's health
throttler.throttle(:my_cluster) { ... }
# will check the health of cluster_a and cluster_b and throttle if any of them is not OK.
throttler.throttle([:cluster_a, :cluster_b]) { ... }
```

You can create your own mapper, which is just an callable object (like a Proc, or any other object that responds to `call(context)`). The following is a mapper that knows how to throttle access to certain tables and shards.


```ruby
class ShardMapper
  def call(context = {})
    context.map do |table, shards|
      DatabaseStructure.cluster_for(table, shards)
    end
  end
end

throttler = Freno::Throttler.new(client: freno, app: :my_app, mapper: ShardMapper.new)

throttler.throttle(:users => [1,2,3], :repositories => 5) do
  perform_writes
end
```

## Development

After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

## Contributing

This repository is open to [contributions](CONTRIBUTING.md). Contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.

## Releasing

If you are the current maintainer of this gem:

1. Create a branch for the release: `git checkout -b cut-release-vx.y.z`
1. Make sure your local dependencies are up to date: `bin/setup`
1. Ensure that tests are green: `bin/test`
1. Bump gem version in `lib/freno/client/version.rb`
1. Merge a PR to github/freno-client containing the changes in the version file
1. Run `bin/release`

## License

The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).