featurevisor-openfeature 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ac21a86ef0432191f6a12f262dd00b524f520a0e5a1cd88bf2029b0428842c46
+  data.tar.gz: 9add287e8f085ee1b446db5ccf5c577a2f4758a78be61ca36dc0af4793b9f8ab
+SHA512:
+  metadata.gz: f0ea87c62a2cfbe51bd00c5d3d75b2fb1f26f2989d5df8cfe44f52fba840374673c439960855441783074c61e531185d11decd393838cc7da485740467e53e3e
+  data.tar.gz: d93238543cd2e2bef46ed2d2bc6c56ce4ca6bf8fc35211a837f1523d1e14c7bcbb016a7aea95d2b1057e2d09632d949c928d098495d0315a38fc868fdb640ae4

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Fahad Heylaal (https://fahad19.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,912 @@
+# Featurevisor Ruby SDK <!-- omit in toc -->
+
+This is a port of Featurevisor [JavaScript SDK](https://featurevisor.com/docs/sdks/javascript/) v3.x to Ruby, providing a way to evaluate feature flags, variations, and variables in your Ruby applications.
+
+This SDK is compatible with Featurevisor v3 projects and v2 datafiles.
+
+## Table of contents <!-- omit in toc -->
+
+- [Installation](#installation)
+- [Public API](#public-api)
+- [Initialization](#initialization)
+- [Evaluation types](#evaluation-types)
+- [Context](#context)
+  - [Setting initial context](#setting-initial-context)
+  - [Setting after initialization](#setting-after-initialization)
+  - [Replacing existing context](#replacing-existing-context)
+  - [Manually passing context](#manually-passing-context)
+- [Check if enabled](#check-if-enabled)
+- [Getting variation](#getting-variation)
+- [Getting variables](#getting-variables)
+  - [Type specific methods](#type-specific-methods)
+- [Getting all evaluations](#getting-all-evaluations)
+- [Sticky](#sticky)
+  - [Initialize with sticky](#initialize-with-sticky)
+  - [Set sticky afterwards](#set-sticky-afterwards)
+- [Setting datafile](#setting-datafile)
+  - [Merging by default](#merging-by-default)
+  - [Replacing](#replacing)
+  - [Loading datafiles on demand](#loading-datafiles-on-demand)
+  - [Updating datafile](#updating-datafile)
+  - [Interval-based update](#interval-based-update)
+- [Evaluation details](#evaluation-details)
+- [Diagnostics](#diagnostics)
+  - [Levels](#levels)
+  - [Handler](#handler)
+- [Events](#events)
+  - [`datafile_set`](#datafile_set)
+  - [`context_set`](#context_set)
+  - [`sticky_set`](#sticky_set)
+  - [`error`](#error)
+- [Modules](#modules)
+  - [Defining a module](#defining-a-module)
+  - [Registering modules](#registering-modules)
+- [Child instance](#child-instance)
+- [Close](#close)
+- [OpenFeature](#openfeature)
+- [CLI usage](#cli-usage)
+  - [Test](#test)
+  - [Test against local monorepo's example-1](#test-against-local-monorepos-example-1)
+  - [Benchmark](#benchmark)
+  - [Assess distribution](#assess-distribution)
+- [Development](#development)
+  - [Setting up](#setting-up)
+  - [Running tests](#running-tests)
+  - [Releasing](#releasing)
+- [License](#license)
+
+<!-- FEATUREVISOR_DOCS_BEGIN -->
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'featurevisor'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install featurevisor
+```
+
+## Public API
+
+The main runtime API is `Featurevisor.create_featurevisor`:
+
+```ruby
+f = Featurevisor.create_featurevisor(
+  datafile: datafile_content
+)
+```
+
+Most applications only need this factory and the returned `Featurevisor::Instance`. Public extension and observability APIs include modules, diagnostics, events, and the datafile structures accepted by the factory.
+
+## Initialization
+
+The SDK can be initialized by passing [datafile](https://featurevisor.com/docs/building-datafiles/) content directly:
+
+```ruby
+require 'featurevisor'
+require 'net/http'
+require 'json'
+
+# Fetch datafile from URL
+datafile_url = 'https://cdn.yoursite.com/datafile.json'
+response = Net::HTTP.get_response(URI(datafile_url))
+
+# Parse JSON with symbolized keys (required)
+datafile_content = JSON.parse(response.body, symbolize_names: true)
+
+# Create SDK instance
+f = Featurevisor.create_featurevisor(
+  datafile: datafile_content
+)
+```
+
+**Important**: When parsing JSON datafiles, you must use `symbolize_names: true` to ensure proper key handling by the SDK.
+
+Alternatively, you can pass a JSON string directly and the SDK will parse it automatically:
+
+```ruby
+# Option 1: Parse JSON yourself (recommended)
+datafile_content = JSON.parse(json_string, symbolize_names: true)
+f = Featurevisor.create_featurevisor(datafile: datafile_content)
+
+# Option 2: Pass JSON string directly (automatic parsing)
+f = Featurevisor.create_featurevisor(datafile: json_string)
+```
+
+## Evaluation types
+
+We can evaluate 3 types of values against a particular [feature](https://featurevisor.com/docs/features/):
+
+- [**Flag**](#check-if-enabled) (`boolean`): whether the feature is enabled or not
+- [**Variation**](#getting-variation) (`string`): the variation of the feature (if any)
+- [**Variables**](#getting-variables): variable values of the feature (if any)
+
+These evaluations are run against the provided context.
+
+## Context
+
+Contexts are [attribute](https://featurevisor.com/docs/attributes/) values that we pass to SDK for evaluating [features](https://featurevisor.com/docs/features/) against.
+
+Think of the conditions that you define in your [segments](https://featurevisor.com/docs/segments/), which are used in your feature's [rules](https://featurevisor.com/docs/features/#rules).
+
+They are plain hashes:
+
+```ruby
+context = {
+  userId: '123',
+  country: 'nl',
+  # ...other attributes
+}
+```
+
+Context can be passed to SDK instance in various different ways, depending on your needs:
+
+### Setting initial context
+
+You can set context at the time of initialization:
+
+```ruby
+require 'featurevisor'
+
+f = Featurevisor.create_featurevisor(
+  context: {
+    deviceId: '123',
+    country: 'nl'
+  }
+)
+```
+
+This is useful for values that don't change too frequently and available at the time of application startup.
+
+### Setting after initialization
+
+You can also set more context after the SDK has been initialized:
+
+```ruby
+f.set_context({
+  userId: '234'
+})
+```
+
+This will merge the new context with the existing one (if already set).
+
+### Replacing existing context
+
+If you wish to fully replace the existing context, you can pass `true` in second argument:
+
+```ruby
+f.set_context({
+  deviceId: '123',
+  userId: '234',
+  country: 'nl',
+  browser: 'chrome'
+}, true) # replace existing context
+```
+
+### Manually passing context
+
+You can optionally pass additional context manually for each and every evaluation separately, without needing to set it to the SDK instance affecting all evaluations:
+
+```ruby
+context = {
+  userId: '123',
+  country: 'nl'
+}
+
+is_enabled = f.is_enabled('my_feature', context)
+variation = f.get_variation('my_feature', context)
+variable_value = f.get_variable('my_feature', 'my_variable', context)
+```
+
+When manually passing context, it will merge with existing context set to the SDK instance before evaluating the specific value.
+
+Further details for each evaluation types are described below.
+
+## Check if enabled
+
+Once the SDK is initialized, you can check if a feature is enabled or not:
+
+```ruby
+feature_key = 'my_feature'
+
+is_enabled = f.is_enabled(feature_key)
+
+if is_enabled
+  # do something
+end
+```
+
+You can also pass additional context per evaluation:
+
+```ruby
+is_enabled = f.is_enabled(feature_key, {
+  # ...additional context
+})
+```
+
+## Getting variation
+
+If your feature has any [variations](https://featurevisor.com/docs/features/#variations) defined, you can evaluate them as follows:
+
+```ruby
+feature_key = 'my_feature'
+
+variation = f.get_variation(feature_key)
+
+if variation == 'treatment'
+  # do something for treatment variation
+else
+  # handle default/control variation
+end
+```
+
+Additional context per evaluation can also be passed:
+
+```ruby
+variation = f.get_variation(feature_key, {
+  # ...additional context
+})
+```
+
+## Getting variables
+
+Your features may also include [variables](https://featurevisor.com/docs/features/#variables), which can be evaluated as follows:
+
+```ruby
+variable_key = 'bgColor'
+
+bg_color_value = f.get_variable('my_feature', variable_key)
+```
+
+Additional context per evaluation can also be passed:
+
+```ruby
+bg_color_value = f.get_variable('my_feature', variable_key, {
+  # ...additional context
+})
+```
+
+### Type specific methods
+
+Next to generic `get_variable()` methods, there are also type specific methods available for convenience:
+
+```ruby
+f.get_variable_boolean(feature_key, variable_key, context = {})
+f.get_variable_string(feature_key, variable_key, context = {})
+f.get_variable_integer(feature_key, variable_key, context = {})
+f.get_variable_double(feature_key, variable_key, context = {})
+f.get_variable_array(feature_key, variable_key, context = {})
+f.get_variable_object(feature_key, variable_key, context = {})
+f.get_variable_json(feature_key, variable_key, context = {})
+```
+
+Type specific methods do not coerce values. `get_variable_integer` returns `nil` for the string `"1"`, and boolean getters return `nil` for non-boolean values.
+
+## Getting all evaluations
+
+You can get evaluations of all features available in the SDK instance:
+
+```ruby
+all_evaluations = f.get_all_evaluations({})
+
+puts all_evaluations
+# {
+#   myFeature: {
+#     enabled: true,
+#     variation: "control",
+#     variables: {
+#       myVariableKey: "myVariableValue",
+#     },
+#   },
+#
+#   anotherFeature: {
+#     enabled: true,
+#     variation: "treatment",
+#   }
+# }
+```
+
+This is handy especially when you want to pass all evaluations from a backend application to the frontend.
+
+## Sticky
+
+For the lifecycle of the SDK instance in your application, you can set some features with sticky values, meaning that they will not be evaluated against the fetched [datafile](https://featurevisor.com/docs/building-datafiles/):
+
+Sticky values belong to an SDK or child instance. Evaluation options do not accept sticky overrides; use `spawn(context, sticky: ...)` when a child needs its own sticky state.
+
+### Initialize with sticky
+
+```ruby
+require 'featurevisor'
+
+f = Featurevisor.create_featurevisor(
+  sticky: {
+    myFeatureKey: {
+      enabled: true,
+      # optional
+      variation: 'treatment',
+      variables: {
+        myVariableKey: 'myVariableValue'
+      }
+    },
+    anotherFeatureKey: {
+      enabled: false
+    }
+  }
+)
+```
+
+Once initialized with sticky features, the SDK will look for values there first before evaluating the targeting conditions and going through the bucketing process.
+
+### Set sticky afterwards
+
+You can also set sticky features after the SDK is initialized:
+
+```ruby
+f.set_sticky({
+  myFeatureKey: {
+    enabled: true,
+    variation: 'treatment',
+    variables: {
+      myVariableKey: 'myVariableValue'
+    }
+  },
+  anotherFeatureKey: {
+    enabled: false
+  }
+}, true) # replace existing sticky features (false by default)
+```
+
+## Setting datafile
+
+You may also initialize the SDK without passing `datafile`, and set it later on:
+
+```ruby
+# Parse with symbolized keys before setting
+datafile_content = JSON.parse(json_string, symbolize_names: true)
+f.set_datafile(datafile_content)
+
+# Or pass JSON string directly for automatic parsing
+f.set_datafile(json_string)
+```
+
+**Important**: When calling `set_datafile()`, ensure JSON is parsed with `symbolize_names: true` if you're parsing it yourself.
+
+### Merging by default
+
+By default, `set_datafile(datafile)` merges the incoming datafile into the SDK's current datafile:
+
+- top-level metadata such as `schemaVersion`, `revision`, and `featurevisorVersion` comes from the incoming datafile
+- `segments` are merged, with incoming entries overriding existing ones
+- `features` are merged, with incoming entries overriding existing ones
+
+This means you can call `set_datafile` more than once with different datafiles, and the SDK instance accumulates their features and segments together.
+
+### Replacing
+
+To fully replace the stored datafile, pass `true` as the second argument:
+
+```ruby
+f.set_datafile(datafile_content, true)
+```
+
+### Loading datafiles on demand
+
+Because merging is the default, a single SDK instance can start with a small datafile and load more datafiles later as your application needs them, instead of downloading every feature upfront.
+
+This pairs well with [targets](https://featurevisor.com/docs/targets/), where each target produces a smaller datafile for a specific part of your application:
+
+```ruby
+require "open-uri"
+
+f = Featurevisor.create_featurevisor({})
+
+def load_datafile(f, target)
+  url = "https://cdn.yoursite.com/production/featurevisor-#{target}.json"
+  datafile = JSON.parse(URI.open(url).read, symbolize_names: true)
+
+  # merges into whatever was loaded before
+  f.set_datafile(datafile)
+end
+
+load_datafile(f, "products")
+
+# later, when the user reaches checkout
+load_datafile(f, "checkout")
+```
+
+### Updating datafile
+
+You can set the datafile as many times as you want in your application, which will result in emitting a [`datafile_set`](#datafile_set) event that you can listen and react to accordingly.
+
+The triggers for setting the datafile again can be:
+
+- periodic updates based on an interval (like every 5 minutes), or
+- reacting to:
+  - a specific event in your application (like a user action), or
+  - an event served via websocket or server-sent events (SSE)
+
+### Interval-based update
+
+Here's an example of using interval-based update:
+
+```ruby
+require 'net/http'
+require 'json'
+
+def update_datafile(f, datafile_url)
+  loop do
+    sleep(5 * 60) # 5 minutes
+
+    begin
+      response = Net::HTTP.get_response(URI(datafile_url))
+      datafile_content = JSON.parse(response.body)
+      f.set_datafile(datafile_content)
+    rescue => e
+      # handle error
+      puts "Failed to update datafile: #{e.message}"
+    end
+  end
+end
+
+# Start the update thread
+Thread.new { update_datafile(f, datafile_url) }
+```
+
+## Diagnostics
+
+By default, Featurevisor reports diagnostics to the console for `info` level and above with a `[Featurevisor]` prefix.
+
+### Levels
+
+Available diagnostic levels are `fatal`, `error`, `warn`, `info`, and `debug`.
+
+Set the level during initialization or update it afterwards:
+
+```ruby
+f = Featurevisor.create_featurevisor(log_level: "debug")
+f.set_log_level("info")
+```
+
+### Handler
+
+Use `on_diagnostic` to send structured diagnostics to your observability system:
+
+```ruby
+f = Featurevisor.create_featurevisor(
+  log_level: "info",
+  on_diagnostic: ->(diagnostic) {
+    puts "#{diagnostic[:level]} #{diagnostic[:code]} #{diagnostic[:message]}"
+  }
+)
+```
+
+Every diagnostic has `:level`, `:code`, `:message`, and an object-shaped `:details` hash. Optional `:module`, `:moduleName`, and `:originalError` fields describe provenance. Evaluation metadata belongs in `:details`.
+
+Diagnostic handlers are isolated from SDK behavior. An exception in a handler does not stop other handlers or evaluations.
+
+
+## Events
+
+Featurevisor SDK implements a simple event emitter that allows you to listen to events that happen in the runtime.
+
+You can listen to these events that can occur at various stages in your application:
+
+### `datafile_set`
+
+```ruby
+unsubscribe = f.on('datafile_set') do |event|
+  revision = event[:revision]        # new revision
+  previous_revision = event[:previousRevision]
+  revision_changed = event[:revisionChanged] # true if revision has changed
+
+  # list of feature keys that have new updates,
+  # and you should re-evaluate them
+  features = event[:features]
+
+  # handle here
+end
+
+# stop listening to the event
+unsubscribe.call
+```
+
+The `features` array will contain keys of features that have either been:
+
+- added, or
+- updated, or
+- removed
+
+compared to the previous datafile content that existed in the SDK instance.
+
+The event also includes `replaced`, which is `true` when the datafile replaced the previous content instead of merging into it.
+
+### `context_set`
+
+```ruby
+unsubscribe = f.on('context_set') do |event|
+  replaced = event[:replaced] # true if context was replaced
+  context = event[:context]   # the new context
+
+  puts 'Context set'
+end
+```
+
+### `sticky_set`
+
+```ruby
+unsubscribe = f.on('sticky_set') do |event|
+  replaced = event[:replaced] # true if sticky features got replaced
+  features = event[:features] # list of all affected feature keys
+
+  puts 'Sticky features set'
+end
+```
+
+### `error`
+
+```ruby
+unsubscribe = f.on('error') do |event|
+  diagnostic = event[:diagnostic]
+  code = diagnostic[:code]
+  message = diagnostic[:message]
+
+  puts "Featurevisor error: #{code} #{message}"
+end
+```
+
+The `error` event is emitted for diagnostics reported with `level: "error"`.
+
+## Evaluation details
+
+Besides logging with debug level enabled, you can also get more details about how the feature variations and variables are evaluated in the runtime against given context:
+
+```ruby
+# flag
+evaluation = f.evaluate_flag(feature_key, context = {})
+
+# variation
+evaluation = f.evaluate_variation(feature_key, context = {})
+
+# variable
+evaluation = f.evaluate_variable(feature_key, variable_key, context = {})
+```
+
+The returned object will always contain the following properties:
+
+- `feature_key`: the feature key
+- `reason`: the reason how the value was evaluated
+
+And optionally these properties depending on whether you are evaluating a feature variation or a variable:
+
+- `bucket_value`: the bucket value between 0 and 100,000
+- `rule_key`: the rule key
+- `error`: the error object
+- `enabled`: if feature itself is enabled or not
+- `variation`: the variation object
+- `variation_value`: the variation value
+- `variable_key`: the variable key
+- `variable_value`: the variable value
+- `variable_schema`: the variable schema
+
+## Modules
+
+Modules allow you to intercept the evaluation process and customize SDK behavior.
+
+### Defining a module
+
+A module is a simple hash with a unique recommended `name` and optional lifecycle functions:
+
+If `setup` raises an exception, the module is not registered. Featurevisor removes subscriptions created during setup, reports `module_setup_error`, and calls `close` when present.
+
+```ruby
+require 'featurevisor'
+
+my_custom_module = {
+  # recommended, and used for duplicate detection/removal
+  name: 'my-custom-module',
+
+  # rest of the properties below are all optional per module
+
+  # setup once, when the module is registered
+  setup: ->(api) {
+    revision = api[:get_revision].call
+
+    api[:on_diagnostic].call(->(diagnostic) {
+      puts diagnostic[:message]
+    })
+  },
+
+  # before evaluation
+  before: ->(options) {
+    # update context before evaluation
+    options[:context] = options[:context].merge({
+      someAdditionalAttribute: 'value'
+    })
+    options
+  },
+
+  # after evaluation
+  after: ->(evaluation, options) {
+    reason = evaluation[:reason]
+    if reason == 'error'
+      # log error
+      return
+    end
+  },
+
+  # configure bucket key
+  bucket_key: ->(options) {
+    # return custom bucket key
+    options[:bucket_key]
+  },
+
+  # configure bucket value (between 0 and 100,000)
+  bucket_value: ->(options) {
+    # return custom bucket value
+    options[:bucket_value]
+  },
+
+  # cleanup when module is removed or SDK is closed
+  close: -> {
+    # cleanup here
+  }
+}
+```
+
+The module API passed to `setup` exposes:
+
+- `get_revision`
+- `on_diagnostic`
+- `report_diagnostic`
+
+### Registering modules
+
+You can register modules at the time of SDK initialization:
+
+```ruby
+require 'featurevisor'
+
+f = Featurevisor.create_featurevisor(
+  modules: [my_custom_module]
+)
+```
+
+Or after initialization:
+
+```ruby
+remove_module = f.add_module(my_custom_module)
+
+# remove later by calling the returned function
+remove_module.call
+
+# or remove by name
+f.remove_module('my-custom-module')
+```
+
+## Child instance
+
+When dealing with purely client-side applications, it is understandable that there is only one user involved, like in browser or mobile applications.
+
+But when using Featurevisor SDK in server-side applications, where a single server instance can handle multiple user requests simultaneously, it is important to isolate the context for each request.
+
+That's where child instances come in handy:
+
+```ruby
+child_f = f.spawn({
+  # user or request specific context
+  userId: '123'
+})
+```
+
+Now you can pass the child instance where your individual request is being handled, and you can continue to evaluate features targeting that specific user alone:
+
+```ruby
+is_enabled = child_f.is_enabled('my_feature')
+variation = child_f.get_variation('my_feature')
+variable_value = child_f.get_variable('my_feature', 'my_variable')
+```
+
+Similar to parent SDK, child instances also support several additional methods:
+
+- `set_context`
+- `set_sticky`
+- `is_enabled`
+- `get_variation`
+- `get_variable`
+- `get_variable_boolean`
+- `get_variable_string`
+- `get_variable_integer`
+- `get_variable_double`
+- `get_variable_array`
+- `get_variable_object`
+- `get_variable_json`
+- `get_all_evaluations`
+- `on`
+- `close`
+
+## Close
+
+Both primary and child instances support a `.close()` method, that removes forgotten event listeners (via `on` method) and cleans up any potential memory leaks.
+
+```ruby
+f.close()
+```
+
+## CLI usage
+
+This package also provides a CLI tool for running your Featurevisor [project](https://featurevisor.com/docs/projects/)'s test specs and benchmarking against this Ruby SDK.
+
+- Global installation: you can access it as `featurevisor`
+- Local installation: you can access it as `bundle exec featurevisor`
+- From this repository: you can access it as `bin/featurevisor`
+
+### Test
+
+Learn more about testing [here](https://featurevisor.com/docs/testing/).
+
+```bash
+$ bundle exec featurevisor test --projectDirectoryPath="/absolute/path/to/your/featurevisor/project"
+```
+
+Additional options that are available:
+
+```bash
+$ bundle exec featurevisor test \
+  --projectDirectoryPath="/absolute/path/to/your/featurevisor/project" \
+  --quiet|--verbose \
+  --onlyFailures \
+  --keyPattern="myFeatureKey" \
+  --assertionPattern="#1"
+```
+
+The Ruby test runner builds base datafiles and Target datafiles in memory via `npx featurevisor build --json`. When an assertion contains `target`, it is evaluated against the matching Target datafile.
+
+All three commands accept repeatable `--target=<target>` options. `test` builds only the selected Target datafiles and runs untargeted assertions plus assertions for those targets. `benchmark` and `assess-distribution` run independently against every selected Target datafile. Without `--target`, existing project-wide behavior is preserved. Project definitions, test specs, Target discovery, and datafile generation continue to come from the Node.js CLI.
+
+### Test against local monorepo's example-1
+
+```bash
+$ cd /absolute/path/to/featurevisor-ruby
+$ bundle exec ruby bin/featurevisor test --projectDirectoryPath=../featurevisor/examples/example-1 --onlyFailures
+$ make test-example-1
+```
+
+### Benchmark
+
+Learn more about benchmarking [here](https://featurevisor.com/docs/cli/#benchmarking).
+
+```bash
+$ bundle exec featurevisor benchmark \
+  --projectDirectoryPath="/absolute/path/to/your/featurevisor/project" \
+  --environment="production" \
+  --feature="myFeatureKey" \
+  --context='{"country": "nl"}' \
+  --n=1000
+```
+
+### Assess distribution
+
+Learn more about assessing distribution [here](https://featurevisor.com/docs/cli/#assess-distribution).
+
+```bash
+$ bundle exec featurevisor assess-distribution \
+  --projectDirectoryPath="/absolute/path/to/your/featurevisor/project" \
+  --environment=production \
+  --feature=foo \
+  --variation \
+  --context='{"country": "nl"}' \
+  --populateUuid=userId \
+  --populateUuid=deviceId \
+  --n=1000
+```
+
+## OpenFeature
+
+The OpenFeature provider is published as a separate gem. This keeps OpenFeature code and dependencies out of applications that only use the Featurevisor SDK.
+
+The provider currently requires Ruby 3.4 or newer because that is the minimum version supported by the official OpenFeature Ruby SDK.
+
+Install the provider:
+
+```ruby
+gem "featurevisor-openfeature", "~> 1.1"
+```
+
+It installs the matching `featurevisor` gem and the official `openfeature-sdk` dependency. The provider and base SDK deliberately share the same version, and the provider requires that exact Featurevisor version.
+
+```ruby
+require "featurevisor/openfeature_provider"
+
+provider = Featurevisor::OpenFeatureProvider.new(
+  datafile: datafile_content,
+)
+
+OpenFeature::SDK.configure do |config|
+  config.set_provider_and_wait(provider)
+end
+
+client = OpenFeature::SDK.build_client
+enabled = client.fetch_boolean_value(
+  flag_key: "checkout",
+  default_value: false,
+  evaluation_context: OpenFeature::SDK::EvaluationContext.new(targeting_key: "user-123"),
+)
+```
+
+Use `checkout` for a flag, `checkout:variation` for its variation, and `checkout:title` for its `title` variable. Boolean variables use the boolean resolver. Arrays, hashes, and JSON variables use the object resolver.
+
+OpenFeature's targeting key maps to `userId` by default. `targeting_key_field`, `key_separator`, and `variation_key` can customize the mapping.
+
+You can pass any Featurevisor initialization options directly to the provider. These options are used to create the Featurevisor instance owned by the provider:
+
+```ruby
+provider = Featurevisor::OpenFeatureProvider.new(
+  datafile: datafile_content,
+  targeting_key_field: "accountId",
+  key_separator: "/",
+  variation_key: "$variation",
+)
+```
+
+You can also reuse an existing Featurevisor instance:
+
+```ruby
+featurevisor = Featurevisor.create_featurevisor(datafile: datafile_content)
+provider = Featurevisor::OpenFeatureProvider.new(featurevisor: featurevisor)
+```
+
+The caller owns an instance passed this way. Provider shutdown does not close it. Call `featurevisor.close` when every consumer is finished with it. When the provider creates the instance from options, the provider owns and closes it. If both are supplied, `featurevisor` takes precedence over the options hash.
+
+See the [OpenFeature provider guide](https://featurevisor.com/docs/sdks/openfeature/) for resolution reasons, errors, metadata, tracking, lifecycle, and providers for other languages.
+
+<!-- FEATUREVISOR_DOCS_END -->
+
+## Development
+
+### Setting up
+
+After checking out the repository, run `make install` to install dependencies.
+
+### Running tests
+
+```bash
+$ bundle exec rspec
+$ make test-base
+$ make test-example-1
+```
+
+Build and verify both gems with:
+
+```bash
+$ make build
+```
+
+The build produces `featurevisor-VERSION.gem` and `featurevisor-openfeature-VERSION.gem`. The artifact verifier confirms that OpenFeature code and dependencies are absent from the base gem and present only in the provider gem.
+
+### Releasing
+
+- Update the shared version in `lib/featurevisor/version.rb`
+- Run `bundle install`
+- Push commit to `main` branch
+- Wait for CI to complete
+- Tag the release with the same version number, for example `v1.1.0`
+- The workflow verifies that the tag matches the shared version
+- The workflow publishes `featurevisor` first, followed by `featurevisor-openfeature`
+
+The gems are separate RubyGems packages built from the same repository. Publishing the base gem first ensures the provider's exact Featurevisor dependency is available when the provider is published. If the second push fails, rerun or retry the provider publication without republishing the existing base version.
+
+## License
+
+MIT © [Fahad Heylaal](https://fahad19.com)

data/lib/featurevisor/openfeature_provider.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "open_feature/sdk"
+require_relative "../featurevisor"
+
+module Featurevisor
+  class OpenFeatureProvider
+    Provider = OpenFeature::SDK::Provider
+
+    attr_reader :metadata, :featurevisor
+
+    def initialize(options = {}, featurevisor: nil, targeting_key_field: "userId", key_separator: ":", variation_key: "variation", on_track: nil, **featurevisor_options)
+      raise ArgumentError, "options must be a Hash" unless options.is_a?(Hash)
+
+      @metadata = Provider::ProviderMetadata.new(name: "Featurevisor").freeze
+      @targeting_key_field = targeting_key_field.empty? ? "userId" : targeting_key_field
+      @key_separator = key_separator.empty? ? ":" : key_separator
+      @variation_key = variation_key.empty? ? "variation" : variation_key
+      @on_track = on_track
+      @datafile_error = nil
+      @shutdown = false
+      @owns_featurevisor = featurevisor.nil?
+      if featurevisor
+        @featurevisor = featurevisor
+      else
+        resolved_options = options.merge(featurevisor_options)
+        initial_datafile = resolved_options.delete(:datafile)
+        @featurevisor = Featurevisor.create_featurevisor(resolved_options)
+      end
+      @error_unsubscribe = @featurevisor.on("error", lambda do |event|
+        diagnostic = event[:diagnostic]
+        @datafile_error = diagnostic[:message] if diagnostic&.dig(:code) == "invalid_datafile"
+      end)
+      @datafile_unsubscribe = @featurevisor.on("datafile_set", ->(*) { @datafile_error = nil })
+      @featurevisor.set_datafile(initial_datafile, true) if @owns_featurevisor && initial_datafile
+    end
+
+    def init(_evaluation_context = nil); end
+    def shutdown
+      return if @shutdown
+
+      @shutdown = true
+      @error_unsubscribe&.call
+      @datafile_unsubscribe&.call
+      featurevisor.close if @owns_featurevisor
+    end
+    def hooks = []
+
+    def track(tracking_event_name:, evaluation_context: nil, tracking_event_details: nil)
+      @on_track&.call(tracking_event_name, evaluation_context, tracking_event_details)
+    end
+
+    def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)
+      resolve(flag_key, default_value, evaluation_context, :boolean)
+    end
+
+    def fetch_string_value(flag_key:, default_value:, evaluation_context: nil)
+      resolve(flag_key, default_value, evaluation_context, :string)
+    end
+
+    def fetch_number_value(flag_key:, default_value:, evaluation_context: nil)
+      resolve(flag_key, default_value, evaluation_context, :number)
+    end
+
+    def fetch_integer_value(flag_key:, default_value:, evaluation_context: nil)
+      resolve(flag_key, default_value, evaluation_context, :integer)
+    end
+
+    def fetch_float_value(flag_key:, default_value:, evaluation_context: nil)
+      resolve(flag_key, default_value, evaluation_context, :float)
+    end
+
+    def fetch_object_value(flag_key:, default_value:, evaluation_context: nil)
+      resolve(flag_key, default_value, evaluation_context, :object)
+    end
+
+    private
+
+    def resolve(flag_key, default_value, evaluation_context, expected_type)
+      return error(default_value, Provider::ErrorCode::PARSE_ERROR, @datafile_error) if @datafile_error
+
+      feature_key, selector = split_key(flag_key)
+      context = normalize(evaluation_context&.fields || {})
+      targeting_key = evaluation_context&.targeting_key
+      context[@targeting_key_field] = targeting_key if targeting_key && !targeting_key.empty?
+
+      if selector.nil? || selector.empty?
+        return type_mismatch(flag_key, default_value, expected_type) unless expected_type == :boolean
+        evaluation = featurevisor.evaluate_flag(feature_key, context)
+        value = evaluation[:enabled]
+      elsif selector == @variation_key
+        evaluation = featurevisor.evaluate_variation(feature_key, context)
+        value = evaluation[:variation_value] || evaluation.dig(:variation, :value)
+      else
+        evaluation = featurevisor.evaluate_variable(feature_key, selector, context)
+        value = evaluation[:variable_value]
+        if evaluation.dig(:variable_schema, :type) == "json" && value.is_a?(String)
+          begin
+            value = JSON.parse(value)
+          rescue JSON::ParserError
+            # Type validation below returns TYPE_MISMATCH when object was requested.
+          end
+        end
+      end
+
+      metadata = metadata_for(evaluation)
+      code = error_code(evaluation[:reason])
+      return error(default_value, code, error_message(evaluation), metadata) if code
+      value = default_value if value.nil?
+      value = normalize(value) if expected_type == :object
+      return type_mismatch(flag_key, default_value, expected_type, metadata) unless matches?(value, expected_type)
+
+      Provider::ResolutionDetails.new(
+        value: value,
+        reason: reason(evaluation[:reason]),
+        variant: variant(evaluation),
+        flag_metadata: metadata
+      )
+    end
+
+    def split_key(key)
+      index = key.index(@key_separator)
+      index ? [key[0...index], key[(index + @key_separator.length)..]] : [key, nil]
+    end
+
+    def metadata_for(evaluation)
+      metadata = {
+        "featureKey" => evaluation[:feature_key],
+        "featurevisorReason" => evaluation[:reason],
+        "schemaVersion" => featurevisor.get_schema_version
+      }
+      metadata["revision"] = featurevisor.get_revision if featurevisor.get_revision
+      {
+        variable_key: "variableKey",
+        rule_key: "ruleKey",
+        bucket_key: "bucketKey",
+        bucket_value: "bucketValue",
+        force_index: "forceIndex",
+        variable_override_index: "variableOverrideIndex"
+      }.each do |key, metadata_key|
+        metadata[metadata_key] = evaluation[key] unless evaluation[key].nil?
+      end
+      metadata
+    end
+
+    def reason(value)
+      return Provider::Reason::ERROR if %w[feature_not_found variable_not_found no_variations error].include?(value)
+      return Provider::Reason::TARGETING_MATCH if %w[required forced sticky rule variable_override_variation variable_override_rule].include?(value)
+      return Provider::Reason::SPLIT if value == "allocated"
+      return Provider::Reason::DISABLED if %w[disabled variation_disabled variable_disabled].include?(value)
+      Provider::Reason::DEFAULT
+    end
+
+    def error_code(value)
+      return Provider::ErrorCode::FLAG_NOT_FOUND if %w[feature_not_found variable_not_found no_variations].include?(value)
+      return Provider::ErrorCode::GENERAL if value == "error"
+      nil
+    end
+
+    def error_message(evaluation)
+      return evaluation[:error].message if evaluation[:error].respond_to?(:message)
+      return %(Feature "#{evaluation[:feature_key]}" was not found) if evaluation[:reason] == "feature_not_found"
+      return %(Variable "#{evaluation[:variable_key]}" was not found for feature "#{evaluation[:feature_key]}") if evaluation[:reason] == "variable_not_found"
+      return %(Feature "#{evaluation[:feature_key]}" has no variations) if evaluation[:reason] == "no_variations"
+      "Featurevisor evaluation failed"
+    end
+
+    def variant(evaluation) = evaluation[:variation_value] || evaluation.dig(:variation, :value)
+
+    def matches?(value, type)
+      case type
+      when :boolean then value == true || value == false
+      when :string then value.is_a?(String)
+      when :number then finite_number?(value)
+      when :integer then value.is_a?(Integer)
+      when :float then value.is_a?(Float) && value.finite?
+      when :object then value.is_a?(Hash) || value.is_a?(Array)
+      else false
+      end
+    end
+
+    def finite_number?(value)
+      value.is_a?(Numeric) && !value.is_a?(Complex) && (!value.respond_to?(:finite?) || value.finite?)
+    end
+
+    def normalize(value)
+      case value
+      when Time, DateTime then value.iso8601
+      when Hash then value.to_h { |key, item| [key.to_s, normalize(item)] }
+      when Array then value.map { |item| normalize(item) }
+      else value
+      end
+    end
+
+    def error(value, code, message, metadata = {})
+      Provider::ResolutionDetails.new(value: value, reason: Provider::Reason::ERROR, error_code: code, error_message: message, flag_metadata: metadata)
+    end
+
+    def type_mismatch(key, value, expected_type, metadata = {})
+      error(value, Provider::ErrorCode::TYPE_MISMATCH, %(Flag "#{key}" did not resolve to a #{expected_type} value), metadata)
+    end
+  end
+end

data/lib/featurevisor-openfeature.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "featurevisor/openfeature_provider"

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: featurevisor-openfeature
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+platform: ruby
+authors:
+- Fahad Heylaal
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: featurevisor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+- !ruby/object:Gem::Dependency
+  name: openfeature-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.5
+description: OpenFeature provider backed by the Featurevisor Ruby SDK
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/featurevisor-openfeature.rb
+- lib/featurevisor/openfeature_provider.rb
+homepage: https://featurevisor.com/docs/sdks/openfeature/
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/featurevisor/featurevisor-ruby
+  documentation_uri: https://featurevisor.com/docs/sdks/ruby/#openfeature
+  bug_tracker_uri: https://github.com/featurevisor/featurevisor-ruby/issues
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: OpenFeature provider for Featurevisor
+test_files: []