Ruby OpenFeature provider

The Unleash OpenFeature Ruby provider lets Ruby applications evaluate Unleash feature flags through the OpenFeature API.

The provider wraps the Unleash Ruby SDK and uses the same backend SDK behavior for polling, local evaluation, caching, metrics, and shutdown.

Requirements

• Ruby 3.4 or later

Installation

Add the provider to your application’s Gemfile. The provider declares the OpenFeature SDK and the Unleash Ruby SDK as dependencies, so you don’t need to add them separately.

1
gem 'unleash-openfeature-provider'

Then install your dependencies:

$
bundle install

Configuration

Create an Unleash::OpenFeature::Provider::UnleashFlagProvider with the same options you would pass to the Unleash Ruby SDK client, then register it with OpenFeature.

1
require 'open_feature/sdk'
2
require 'unleash-openfeature-provider'
3
4
provider = Unleash::OpenFeature::Provider::UnleashFlagProvider.new(
5
  app_name: 'my-ruby-app',
6
  url: '<YOUR_UNLEASH_URL>/api',
7
  custom_http_headers: {
8
    Authorization: '<YOUR_API_TOKEN>'
9
  }
10
)
11
12
OpenFeature::SDK.configure do |config|
13
  config.set_provider(provider)
14
end

Evaluate a flag

Build an OpenFeature client and evaluate flags through the OpenFeature API:

1
client = OpenFeature::SDK.build_client
2
3
context = OpenFeature::SDK::EvaluationContext.new(
4
  targeting_key: 'user-123'
5
)
6
7
enabled = client.fetch_boolean_value(
8
  flag_key: 'my-feature',
9
  default_value: false,
10
  evaluation_context: context
11
)

The provider supports all OpenFeature evaluation methods. Boolean evaluation uses the flag’s enabled state. All other types resolve from the payload of the flag’s variant:

• String values accept string and csv payloads.
• Number, integer, and float values accept number payloads.
• Object values accept json payloads.

If the flag is disabled, or the variant payload is missing or has a different type, the evaluation returns the default value.

Context mapping

The provider maps the OpenFeature evaluation context to an Unleash context before each evaluation.

The following OpenFeature fields map directly to top-level Unleash context fields:

• currentTime
• userId
• sessionId
• remoteAddress
• environment
• appName

If you set targeting_key, the provider maps it to userId. The targeting_key takes precedence over a userId field set on the evaluation context.

The provider adds all other scalar fields, such as strings, numbers, booleans, and time values, to the Unleash context properties. It discards nested values, such as arrays and hashes.

Shutdown

Shut down the provider when your application exits. This also shuts down the underlying Unleash client.

1
provider.shutdown

Example

To try the provider against your Unleash instance, clone the provider repository and run the boolean flag example with your Unleash URL and API token:

$
bundle exec ruby examples/boolean_flag.rb \
>
  --url '<YOUR_UNLEASH_URL>/api' \
>
  --api-key "$UNLEASH_API_KEY" \
>
  --flag-key my-feature \
>
  --targeting-key user-123