OpenFeature Providers

OpenFeature Ruby Provider

ConfigDirector Provider for the OpenFeature Ruby SDK

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

  1. Create an instance of the provider using your server SDK key. You can retrieve a server SDK key for each environment under SDK keys in the dashboard's navigation panel. Creating the provider makes no network call.
  2. Set the OpenFeature provider and wait for it to connect.
  3. 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:

lib/open_feature_client_per_process.rb
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
Server SDK keys are secret values. Do not commit them to your source code repository. Provide them at runtime via environment variables instead.

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:

lib/open_feature_client_per_process.rb
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:

lib/open_feature_client_per_process.rb
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:

lib/open_feature_client_per_process.rb
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:

main.rb
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 getterConfigDirector config value
fetch_boolean_valueBoolean
fetch_string_valueString or enum
fetch_number_value, fetch_integer_value, fetch_float_valueNumber
fetch_object_valueJSON 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:

main.rb
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:

OutcomeReasonError codeVariant
A value was foundTARGETING_MATCHThe variation name, or the value ID
A percentage rollout was skipped for a context without a targeting keyDEFAULTThe variation name, or the value ID
The config carries no valueDEFAULT
The config key is unknownERRORFLAG_NOT_FOUND
No config state has arrived yetERRORPROVIDER_NOT_READY
The value does not match the requested typeERRORTYPE_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.

main.rb
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.

main.rb
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:

main.rb
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 contextConfigDirector context
The targeting key, or otherwise an id attributeid
The top-level kind attributekind
The name attributename
The traits attribute, a Hashtraits
The anonymous attribute, when it is trueanonymous

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:

main.rb
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.

main.rb
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:

spec/checkout_spec.rb
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:

spec/support/in_memory_provider_in_place_of_the_configdirector_provider.rb
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