Official FeatureHub Ruby SDK.
To control the feature flags from the FeatureHub Admin console, either use our demo version for evaluation or install the app using our guide here
Add the featurehub sdk gem to your Gemfile and/or gemspec if you are creating a library:
To use it in your code, use:
Options to get feature updates
There are 2 ways to request for feature updates via this SDK:
SSE (Server Sent Events) realtime updates mechanism
In this mode, you will make a connection to the FeatureHub Edge server using using Server Sent Events, any updates to any features will come through in near realtime, automatically updating the feature values in the repository. This method is recommended for server applications.
FeatureHub polling client (GET request updates)
In this mode you can set an interval (from 0 - just once) to any number of seconds between polling. This is more useful for when you have short term single threaded processes like command line tools. Batch tools that iterate over data sets and wish to control when updates happen can also benefit from this method.
This SDK uses concurrent ruby to ensure whichever option you choose stays open and continually updates your data.
Check our example Sinatra app here
Connecting to FeatureHub
There are 3 steps to connecting:
- Copy FeatureHub API Key from the FeatureHub Admin Console
- Create FeatureHub config
- Check FeatureHub Repository readiness and request feature state
1. API Key from the FeatureHub Admin Console
Find and copy your API Key from the FeatureHub Admin Console on the API Keys page -
you will use this in your code to configure feature updates for your environments.
It should look similar to this:
There are two options - a Server Evaluated API Key and a Client Evaluated API Key. More on this here
Client Side evaluation is intended for use in secure environments (such as microservices) and is intended for rapid client side evaluation, per request for example.
Server Side evaluation is more suitable when you are using an insecure client. (e.g. command line tool). This also means you evaluate one user per client.
2. Create FeatureHub config:
FeatureHubConfig. You need to provide the API Key and the URL of the FeatureHub Edge server.
config = FeatureHub::Sdk::FeatureHubConfig.new(ENV.fetch("FEATUREHUB_EDGE_URL"), [ENV.fetch("FEATUREHUB_CLIENT_API_KEY")]) config.init
Note, you only ever need to do this once, a Config consists of a Repository (which holds state) and an Edge Server (which gets the updates and passes them on to the Repository). You can have many of them if you wish, but you don't need to.
to in Rails, you might create an initializer that does this:
Rails.configuration.fh_client = FeatureHub::Sdk::FeatureHubConfig.new(ENV.fetch("FEATUREHUB_EDGE_URL"), [ENV.fetch("FEATUREHUB_CLIENT_API_KEY")]).init
in Sinatra (our example), it might do this:
class App < Sinatra::Base configure do set :fh_config, FeatureHub::Sdk::FeatureHubConfig.new(ENV.fetch("FEATUREHUB_EDGE_URL"), [ENV.fetch("FEATUREHUB_CLIENT_API_KEY")]) end end
By default, this SDK will use SSE client. If you decide to use FeatureHub polling client, after initialising the config, you can add this:
config.use_polling_edge_service(30) # OR config.use_polling_edge_service # uses environment variable FEATUREHUB_POLL_INTERVAL or default of 30
in this case it is configured for requesting an update every 30 seconds.
3. Check FeatureHub Repository readiness and request feature state
Check for FeatureHub Repository readiness:
if config.repository.ready? # do something end
If you are not intending to use rollout strategies, you can pass empty context to the SDK:
def name_arg(name) if config.new_context.build.feature("FEATURE_TITLE_TO_UPPERCASE").flag "HELLO WORLD" else "hello world" end end
If you are using rollout strategies and targeting rules they are all determined by the active user context. In this example we pass
user_key to the context :
def name_arg(name) if config.new_context.user_key(name).build.feature("FEATURE_TITLE_TO_UPPERCASE").flag "HELLO WORLD" else "hello world" end end
Well known fields have their own methods, or you can add custom
values for fields using
attribute_value(key, [values]). For
example if you wish to trigger on specific contract ids and each
user could have a different set of contract ids, you can add those
attribute_value("contract_values", [2,17,45]) and have configured
your strategy with a list of contract values which trigger the feature.
See more options to request feature states here
Using inside popular web servers
Because most of the popular webservers use a process per request distributed request distribution model, they will generally fork the process when they need more processes to handle the incoming traffic, and this will naturally kill the connection to FeatureHub. It does not however reset the cached repository. To ensure your fork is back up in running, for various frameworks you will need to ensure the Edge connection is restarted. This consists of
Resetting in Passenger
if defined?(PhusionPassenger) PhusionPassenger.on_event(:starting_worker_process) do |forked| if forked # e.g. # App.settings.fh_config.force_new_edge_service end end end
Resetting in Puma
on_worker_boot do # e.g. # App.settings.fh_config.force_new_edge_service end
Resetting in Unicorn
after_fork do |_server, _worker| # e.g. # App.settings.fh_config.force_new_edge_service end
Resetting in Spring
Spring.after_fork do # e.g. # App.settings.fh_config.force_new_edge_service end
Extracting the state
You can extract the state from a repository and store it somewhere and reload it, but it should be done so using the JSON mechanism so it parses correctly.
require 'json' state = config.repository.extract_feature_state # somehow save it save(state.to_json) # some later stage, reload it or use it as a cache config.repository.notify(:features, JSON.parse(read_state))
It is encourage that you include the ready state of the repository in your readyness check. If your server cannot connect to your FeatureHub repository and cannot sensibly operate without it, it is not ready. Once it has received initial state it will remain ready even when it temporarily loses connections.
It is only if the key is invalid, or if the repository has never received state, that the repository is marked not ready. To determine readyness: