Bandiera::Client (Ruby)

This is a client for talking to the Bandiera feature flagging service from a Ruby application.

This client is compatible with the v2 Bandiera API.

Gem version Build status Dependencies MIT licensed

Ruby Support:

This client has been tested against the latest MRI and JRuby builds.

Usage

Add the following to your Gemfile:

gem 'bandiera-client'

Then interact with a Bandiera server like so:

require 'bandiera/client'

client = Bandiera::Client.new('http://bandiera-demo.herokuapp.com')
params = {}

if client.enabled?('pubserv', 'show-new-search', params)
  # show the new experimental search function
end

The client.enabled? command takes two main arguments - the 'feature group', and the 'feature name'. This is because in Bandiera, features are organised into groups as it is intented as a service for multiple applications to use at the same time - this organisation allows separation of feature flags that are intended for different audiences.

client.enabled? also takes an optional params hash, this is for use with some of the more advanced features in Bandiera - user group and percentage based flags. It is in this params hash you pass in your user_group and user_id, i.e.:

client.enabled?('pubserv', 'show-new-search',
  { user_id: '1234567', user_group: 'Administrators' })

For more information on these advanced features, please see the Bandiera wiki:

https://github.com/nature/bandiera/wiki/How-Feature-Flags-Work#feature-flags-in-bandiera

Caching

Bandiera::Client#enabled? has a small layer of caching built into it in order to:

  1. Reduce the amount of HTTP requests made to the Bandiera server
  2. Make things faster

Strategies

There are three request/caching strategies you can use with Bandiera::Client.

:single_feature

This strategy calls the Bandiera API for each new .enabled? request, and stores the response in it's local cache. Subsequent .enabled? requests (using the same arguments) will read from the cache until it has expired. This is the least efficient strategy in terms of reducing HTTP requests and speed.

:group

This strategy calls the Bandiera API once for each feature flag group requested, and then stores the resulting feature flag values in the cache. This means that all subsequent calls to .enabled? for the same group will not perform a HTTP request and instead read from the cache until it has expired. This is a good compromise in terms of speed and number of HTTP requests, and is the default caching strategy.

:all

This strategy calls the Bandiera API once and fetches/caches all feature flag values locally. All subsequent calls to .enabled? read from the cache until it has expired. This strategy is obviously the most efficient in terms of the number of HTTP requests if you are requesting flags from across multiple groups, but might not be the fastest if there are lots of flags in your Bandiera instance.

Changing the Cache Strategy

client = Bandiera::Client.new('http://bandiera-demo.herokuapp.com')
client.cache_strategy = :all

Cache Expiration

The default cache lifetime is 5 seconds. If you would like to alter this you can do so as follows:

client = Bandiera::Client.new('http://bandiera-demo.herokuapp.com')
client.cache_ttl = 10 # 10 seconds

Direct API Access

If you'd prefer not to use the enabled? method for featching feature flag values, the following methods are available...

Get features for all groups:

client.get_all(params)

Get features for a group:

client.get_features_for_group('pubserv', params)

Get an individual feature:

client.get_feature('pubserv', 'show-article-metrics', params)

Development

  1. Fork this repo.
  2. Run bundle install

License

© 2014 Nature Publishing Group. Bandiera::Client (Ruby) is licensed under the MIT License.