# Twirl

Wrapper for kjess that works with multiple kestrel instances intelligently.

## Installation

Add this line to your application's Gemfile:

    gem 'twirl'

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install twirl

## Usage

```ruby
clients = [
  KJess::Client.new(host: "localhost", port: 9444),
  KJess::Client.new(host: "localhost", port: 9544),
]
twirl = Twirl.new(clients) # returns a Twirl::Cluster instance.

twirl.set("events", "...data...")
twirl.get("events")

# reliable reads
item = twirl.get("events", open: true)
# or...
item = twirl.reserve("events")

# once you have an item you can close or abort it
item.value # => "...data..."
item.close # get("events", close: true) to same client
item.abort # get("events", abort: true) to same client
```

Pretty much all of the KJess::Client methods are supported. Check out [Twirl::Cluster](https://github.com/jnunemaker/twirl/blob/master/lib/twirl/cluster.rb) for more.

The few that are not are `close`, `abort`, and `connected?`. close and abort require knowing the client. Since we are rotating clients, these make less sense. Just close and abort using the [Twirl::Item](https://github.com/jnunemaker/twirl/blob/master/lib/twirl/item.rb) returned from the reliable read instead.

You can customize most anything you like as well:

```ruby
clients = [
  KJess::Client.new(host: "localhost", port: 9444),
  KJess::Client.new(host: "localhost", port: 9544),
]

# rotate every 5 commands
Twirl.new(clients, commands_per_client: 5)

# only retry commands that raise exceptions 1 time
Twirl.new(clients, retries: 1)

# only retry for network errors
Twirl.new(clients, retryable_errors: [KJess::NetworkError])

# instrument using active support notifications and statsd
require "twirl/instrumentation/statsd"
Twirl::Instrumentation::StatsdSubscriber.client = Statsd.new
Twirl.new(clients, instrumeter: ActiveSupport::Notifications)
```

## Contributing

1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request