NOTE This implementation has been deprecated in favor of the official Ruby SDK. We recommend switching to that. In the future, we hope to add RBS and Tapioca DSL generation support to the official library.
OpenFeature is an open standard for vendor-agnostic feature flagging. Sorbet is a type-checker for Ruby, built by Stripe. Sorbet provides powerful runtime utilities to achieve things traditionally not possible with Ruby, such as interfaces, immutable structures and enums. This makes it a very good option when defining specifications.
If an organization is not already using Sorbet, you probably don't want to introduce a dependency on sorbet-runtime
, which this gem does. As such, this will always be a distinct implementation, separate from the official Ruby SDK.
Current OpenFeature specification target version: 0.5.2
Current supported Ruby versions: 3.1.X
, 3.2.X
Support for Evaluation Context and Hooks is not complete.
Install the gem and add to the application's Gemfile by executing:
$ bundle add openfeature-sdk-sorbet
If bundler is not being used to manage dependencies, install the gem by executing:
$ gem install openfeature-sdk-sorbet
require "open_feature_sorbet"
# Configure global API properties
OpenFeature.set_provider(OpenFeatureSorbet::NoOpProvider.new)
OpenFeature.set_evaluation_context(OpenFeatureSorbet::EvaluationContext.new(fields: { "globally" => "available" }))
OpenFeature.add_hooks([OpenFeatureSorbet::Hook.new]) # experimental, not fully supported
client = OpenFeature.create_client(evaluation_context: OpenFeatureSorbet::EvaluationContext.new(fields: { "client" => "available" }))
# Fetch boolean value
# Also methods available for String, Number, Integer, Float and Structure (Hash)
bool_value = client.fetch_boolean_value(flag_key: "my_toggle", default_value: false) # => (true or false)
# Sorbet sprinkles in type safety
bool_value = client.fetch_boolean_value(flag_key: "my_toggle", default_value: "bad!") # => raises TypeError from Sorbet, invalid default value
# Additional evaluation context can be provided during invocation
number_value = client.fetch_number_value(flag_key: "my_toggle", default_value: 1, context: OpenFeatureSorbet::EvaluationContext.new(fields: { "only_this_call_site" => 10 })) # => merges client and global context
# Fetch structure evaluation details
structure_evaluation_details = client.fetch_structure_details(flag_key: "my_structure", default_value: { "a" => "fallback" }) # => EvaluationDetails(value: Hash, flag_key: "my_structure", ...)
Structure
The OpenFeature specification defines Structure as a potential return type. This is somewhat ambiguous in Ruby, further complicated by T::Struct
that we get from Sorbet. For now, the type I've elected here is T.any(T::Array[T.untyped], T::Hash[T.untyped, T.untyped]
(loosely, either an Array of untyped members or a Hash with untyped keys and untyped values) for flexibility but with a little more structure than a YML or JSON parsable string. This decision might change in the future upon further interpretation or new versions of the specification.
We support global evaluation context (set on the OpenFeature
module), client evaluation context (set on client instances or during client initialization) and invocation evaluation context (passed in during flag evaluation). In compliance with the specification, the invocation context merges into the client context which merges into the global context. Fields in invocation context take precedence over fields in the client context which take precedence over fields in the global context.
By default, this implementation sets the provider to the OpenFeatureSorbet::NoOpProvider
which always returns the default value. It's up to the individual teams to define their own providers based on their flag source (in the future, I'll release open-source providers based on various, common vendors).
This gem also provides OpenFeatureSorbet::MultipleSourceProvider
to allow fetching flags from multiple sources. This is especially useful if your existing application has flags spread across bespoke and vendor solutions and you want to unify the evaluation sites. It can be instantiated and configured like so:
provider = OpenFeatureSorbet::MultipleSourceProvider.new(
providers: [
CustomProvider.new,
OpenFeatureSorbet::NoOpProvider.new
]
)
OpenFeature.set_provider(provider)
Thanks to Sorbet abstract classes, it's fairly straightforward to implement a new provider. Here is an example for a JSON-based flag format on disk:
class JsonFileFlagProvider < OpenFeatureSorbet::Provider
extend T::Sig
sig { void }
def initialize
super(OpenFeatureSorbet::ProviderStatus::NotReady)
end
def init(context)
@file = File.open(context.file || "flags.json")
@status = OpenFeatureSorbet::ProviderStatus::Ready
end
sig { overridable.void }
def shutdown
@file.close
end
sig { override.returns(OpenFeatureSorbet::ProviderMetadata) }
def metadata
OpenFeatureSorbet::ProviderMetadata.new(name: "Json File Flag Provider")
end
sig { override.returns(T::Array[Hook]) }
def hooks
[]
end
sig do
override
.params(
flag_key: String,
default_value: T::Boolean,
context: T.nilable(EvaluationContext)
)
.returns(OpenFeatureSorbet::ResolutionDetails[T::Boolean])
end
def resolve_boolean_value(flag_key:, default_value:, context: nil)
file_input = JSON.parse(File.read("flags.rb"))
value = file_input.fetch("flag_key", default_value)
OpenFeatureSorbet::ResolutionDetails.new(
value: value,
# ... other optional fields
)
end
# ... other resolver methods
end
By inheriting from the OpenFeatureSorbet::Provider
class, Sorbet will indicate what methods it's expecting and what their type signatures should be.
initialize
versus init
The Ruby initialize
method is the best place to do any direct construction logic for an object, such as setting configuration values. init
is called by OpenFeature when setting a provider and is the best place to make any HTTP requests, establish persistent connections, or any other connection logic that could potentially fail. By the end of this method, @status
must be set to either Ready
or Error
.
After checking out the repo, run bin/setup
to install dependencies. Then, run rake
to run Rubocop and the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
.
Bug reports and pull requests are welcome on GitHub at https://github.com/maxveldink/openfeature-sdk-sorbet. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in this project's codebase, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
I love creating in the open. If you find this or any other maxveld.ink content useful, please consider sponsoring me on GitHub.