OpenFeature Ruby Provider
Introduction
The OpenFeature Ruby Provider is intended to be used in combination with the OpenFeature Ruby SDK. The provider wraps the ConfigDirector Ruby SDK.
The provider is thread safe. Register one per process the first time the process reads a flag, and shut OpenFeature down when the process exits. Evaluations read config state the provider already holds in memory, so they make no network calls on the request path.
Installation
The provider can be installed with Bundler. Its gem page is on RubyGems: https://rubygems.org/gems/configdirector-openfeature-server-provider
The minimum Ruby version supported is 3.4, because the OpenFeature Ruby SDK requires it.
The OpenFeature Ruby SDK (openfeature-sdk) and the ConfigDirector Ruby SDK are included as dependencies.
bundle add configdirector-openfeature-server-provider
Configure and initialize the client
- Create an instance of the provider using your server SDK key. You can retrieve a server SDK key for each environment under
SDK keysin the dashboard's navigation panel. Creating the provider makes no network call. - Set the OpenFeature provider and wait for it to connect.
- Get a client instance from OpenFeature.
The example registers the provider the first time a process reads a flag, and returns the same OpenFeature client to every later read in the process:
require "configdirector/openfeature"
# Registers the provider the first time a process reads a flag, and returns the same client afterwards.
module OpenFeatureClientPerProcess
@lock = Mutex.new
@client = nil
def self.client
@lock.synchronize { @client ||= client_after_registering_the_provider }
end
def self.client_after_registering_the_provider
# IMPORTANT: Do not commit the server SDK key to your source code, it is a secret value.
provider = ConfigDirector::OpenFeature::ConfigDirectorProvider.new(ENV.fetch("CONFIGDIRECTOR_SERVER_KEY"))
begin
OpenFeature::SDK.set_provider_and_wait(provider)
rescue OpenFeature::SDK::ProviderInitializationError => e
warn("Starting on in-code default values until ConfigDirector sends config: #{e.message}")
end
at_exit { OpenFeature::SDK.shutdown }
OpenFeature::SDK.build_client
end
private_class_method :client_after_registering_the_provider
end
Each Ruby process holds its own provider and its own connection to ConfigDirector. Registering the provider on first use, rather than while the application boots, keeps the processes that never read a flag from connecting, such as the master process of Puma in cluster mode, a console session or an image build that has no server SDK key. A provider registered before the process forked keeps working in the forked process, with nothing to call. The Ruby SDK's page explains both in Servers that fork their workers.
When no config arrives in time
set_provider_and_wait raises OpenFeature::SDK::ProviderInitializationError with the PROVIDER_NOT_READY error code when no config arrives from ConfigDirector within the connection timeout, which is 3 seconds unless you set the connection's timeout, or when ConfigDirector rejects the server SDK key. The provider then reports the ERROR status, with a PROVIDER_ERROR event, and after a timeout it keeps connecting in the background. Until config arrives, flags resolve to their in-code default values with the PROVIDER_NOT_READY error code. Once it arrives, the provider reports READY, with one PROVIDER_READY event.
The example above rescues the error, prints it and starts on in-code default values. To start without waiting for ConfigDirector at all, set the provider with set_provider instead, which initializes it in the background:
OpenFeature::SDK.set_provider(ConfigDirector::OpenFeature::ConfigDirectorProvider.new(ENV.fetch("CONFIGDIRECTOR_SERVER_KEY")))
A provider whose connection drops later stays READY and serves the values it has, so the provider never reports the STALE or FATAL status.
Additional configuration options
Additional configuration options can be passed into the provider as keyword arguments of ConfigDirectorProvider.new.
For example, the metadata can be provided like this:
provider = ConfigDirector::OpenFeature::ConfigDirectorProvider.new(
ENV.fetch("CONFIGDIRECTOR_SERVER_KEY"),
metadata: ConfigDirector::Metadata.new(app_name: "YOUR-APP-NAME", app_version: "1.0.2")
)
The provider accepts the same metadata, connection, logger, log_level and telemetry options as the Ruby SDK client, refer to the additional configuration options section of the Ruby SDK for a full list. It does not take the client's hooks option: listen to the OpenFeature events instead.
That includes running without a connection: created with connection: ConfigDirector::ConnectionOptions.new(mode: "offline", ...) and no server SDK key, the provider serves the values you give it without connecting to ConfigDirector, and set_provider_and_wait raises OpenFeature::SDK::ProviderInitializationError with the GENERAL error code if those values cannot be loaded.
Shut down
Shutting OpenFeature down closes the provider, which closes its connection and reports any pending telemetry. The example above does it when the process exits:
at_exit { OpenFeature::SDK.shutdown }
Retrieve config values
To retrieve config values, use the OpenFeature client:
Every getter takes the flag key and the in-code default value and, optionally, the evaluation context, as keyword arguments:
client = OpenFeatureClientPerProcess.client
boolean_value = client.fetch_boolean_value(flag_key: "my-config-key", default_value: false)
string_value = client.fetch_string_value(flag_key: "my-string-config-key", default_value: "Default")
Each OpenFeature getter maps to a ConfigDirector config type:
| OpenFeature getter | ConfigDirector config value |
|---|---|
fetch_boolean_value | Boolean |
fetch_string_value | String or enum |
fetch_number_value, fetch_integer_value, fetch_float_value | Number |
fetch_object_value | JSON object or JSON array |
fetch_number_value reads any finite number, whatever the class of the in-code default value: a whole number comes back as an Integer and any other number as a Float. fetch_integer_value reads whole numbers only, and fetch_float_value returns a Float.
fetch_object_value returns the parsed JSON: with a Hash as the in-code default value it reads a JSON object, as a Hash with String keys, and with an Array it reads a JSON array. A JSON array read with a Hash, or a JSON object read with an Array, returns the in-code default value with TYPE_MISMATCH:
settings = client.fetch_object_value(flag_key: "my-json-config-key", default_value: {})
theme = settings["theme"]
For additional information regarding the OpenFeature client refer to the OpenFeature Ruby SDK documentation.
Evaluation details
The detailed getters of the OpenFeature client, such as fetch_boolean_details, report why an evaluation produced the value that it did:
| Outcome | Reason | Error code | Variant |
|---|---|---|---|
| A value was found | TARGETING_MATCH | The variation name, or the value ID | |
| A percentage rollout was skipped for a context without a targeting key | DEFAULT | The variation name, or the value ID | |
| The config carries no value | DEFAULT | ||
| The config key is unknown | ERROR | FLAG_NOT_FOUND | |
| No config state has arrived yet | ERROR | PROVIDER_NOT_READY | |
| The value does not match the requested type | ERROR | TYPE_MISMATCH |
The variant is the name of the variation served, such as treatment, when the config has variations and that variation has a name. Otherwise it is ConfigDirector's ID for the value served, a stable hash you can send to analytics in place of the value itself; values served in offline mode have none. In the cases without a variant, the in-code default value is returned. The details carry no flag metadata.
details = client.fetch_boolean_details(flag_key: "new-checkout", default_value: false, evaluation_context: user)
warn("new-checkout fell back to its in-code default value: #{details.error_code}") if details.error_code
To report an experiment to an analytics tool, follow the page for Amplitude, Mixpanel, Google Analytics 4, Segment or PostHog, which names the event that tool reads.
Context
The context is the evaluation_context argument of every getter of the OpenFeature client. The OpenFeature Ruby provider evaluates targeting rules locally without additional network calls for different contexts.
user = OpenFeature::SDK::EvaluationContext.new(
targeting_key: "12345", # In OpenFeature, the targeting key represents the context's identifier
name: "Example User",
traits: { "region" => "North America" } # Any arbitrary traits which can be referenced in targeting rules
)
boolean_value = client.fetch_boolean_value(flag_key: "my-config-key", default_value: false, evaluation_context: user)
To evaluate flags for an entity other than a user, such as a tenant, set the context kind with a top-level kind attribute:
tenant = OpenFeature::SDK::EvaluationContext.new(
targeting_key: "acme",
kind: "tenant",
name: "Acme Inc.",
traits: { "plan" => "enterprise" }
)
boolean_value = client.fetch_boolean_value(flag_key: "my-config-key", default_value: false, evaluation_context: tenant)
Leaving kind out means user. A kind inside traits is an ordinary trait, not the context kind. A context kind is 1 to 64 lowercase letters, digits, dashes, or underscores. A context with an invalid context kind is ignored: the SDK logs an error, and flags still resolve successfully, as if no context had been given.
The evaluation context maps onto the ConfigDirector context as follows:
| OpenFeature evaluation context | ConfigDirector context |
|---|---|
The targeting key, or otherwise an id attribute | id |
The top-level kind attribute | kind |
The name attribute | name |
The traits attribute, a Hash | traits |
The anonymous attribute, when it is true | anonymous |
An id or a name given as a Symbol, true or false, an Integer, a Float or a date is read as text, and any other id or name is left out. A date, given as a Time, a DateTime or a Date, is written as UTC text such as 2026-11-17T10:00:00.000Z, or as 2026-11-17 for a Date, inside the traits too, so date conditions can compare it.
An evaluation context with neither a targeting key nor an id attribute skips percentage rollouts: a rollout does not apply to it, and the targeting rules after the rollout are tried, as they are after a conditional rule the context does not match. When none of them applies, the flag resolves to the default targeting rule value with the reason DEFAULT; a later rule that applies resolves with TARGETING_MATCH. A rule that serves a single value still applies to it. To keep an anonymous visitor in a rollout, give the context a stable targeting key, such as a session ID.
For additional information regarding the OpenFeature client refer to the OpenFeature Ruby SDK documentation.
Events
The provider emits PROVIDER_CONFIGURATION_CHANGED whenever configs are updated on the dashboard or via the admin API, carrying the keys of the configs in the update followed by the keys of the configs it removed:
OpenFeature::SDK.add_handler(
OpenFeature::SDK::ProviderEvent::PROVIDER_CONFIGURATION_CHANGED,
->(event_details) { puts "Configs updated: #{event_details[:flags_changed].join(", ")}" }
)
When no config arrived in time at startup, the provider emits PROVIDER_READY once config arrives, as described in When no config arrives in time.
Track events
The provider implements OpenFeature's tracking API. client.track reports to ConfigDirector that something happened in your application, such as a completed checkout, and ConfigDirector shows it on the Live feed and counts it for each variation of a running experiment; see Tracked events.
client.track(
"checkout-completed",
evaluation_context: OpenFeature::SDK::EvaluationContext.new(targeting_key: "user-123"),
tracking_event_details: OpenFeature::SDK::TrackingEventDetails.new(value: 49.9, plan: "pro", seats: 3)
)
The value of the tracking event details is sent as the event's value, and their other fields as the event's details. The context the event happened for is the merged evaluation context: its targeting key, or otherwise its id attribute, and its kind.
An event counts for an experiment only when its evaluation context has the targeting key the experiment's flag was evaluated with, so track with the context you evaluate with. Without one, the event is still reported and counts for no experiment. For a context marked anonymous, the event is reported without the targeting key, so it counts for no experiment either.
track never raises: an event the provider cannot pass on, for example because its evaluation context cannot be read, is logged as a warning and not reported. It does nothing in offline mode. The provider sends tracked events as the Ruby SDK does, with the same limits.
Test your code
Code that reads flags through OpenFeature is tested by swapping the provider, so it never has to change for a test and nothing from ConfigDirector is involved. The OpenFeature Ruby SDK ships an in-memory provider for that, OpenFeature::SDK::Provider::InMemoryProvider, which serves the values your test sets:
RSpec.describe "the checkout" do
after { OpenFeature::SDK.shutdown }
it "shows the new checkout" do
provider = OpenFeature::SDK::Provider::InMemoryProvider.new("new-checkout" => true, "max-items" => 20)
OpenFeature::SDK.set_provider_and_wait(provider)
client = OpenFeature::SDK.build_client
expect(client.fetch_boolean_value(flag_key: "new-checkout", default_value: false)).to be(true)
expect(client.fetch_integer_value(flag_key: "max-items", default_value: 0)).to eq(20)
provider.add_flag(flag_key: "new-checkout", value: false)
expect(client.fetch_boolean_value(flag_key: "new-checkout", default_value: true)).to be(false)
end
end
add_flag changes a value in the middle of a test and emits PROVIDER_CONFIGURATION_CHANGED with the flag's key. The OpenFeature API is one global, so shut it down after each test with OpenFeature::SDK.shutdown, as the after block above does, which lets the next test register its own provider.
When the provider is registered the first time a process reads a flag, as in Configure and initialize the client, make ConfigDirectorProvider.new return the in-memory provider, so your application's own registration runs as it does in production, and forget the module's client after each example:
RSpec.shared_context "with an in-memory provider in place of the ConfigDirector provider" do
let(:in_memory_provider) { OpenFeature::SDK::Provider::InMemoryProvider.new("new-checkout" => true) }
before { allow(ConfigDirector::OpenFeature::ConfigDirectorProvider).to receive(:new).and_return(in_memory_provider) }
after do
OpenFeature::SDK.shutdown
OpenFeatureClientPerProcess.instance_variable_set(:@client, nil)
end
end