featurevisor-openfeature 2.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82c9c9135ecbcd5961523a67d92b068f019eaff3db7d8685f050c074766ef9de
-  data.tar.gz: ac09d5e0b55134b4184c599b430d4db35c1740aa70a5afdf59673aed98cd7620
+  metadata.gz: 9b95462003a714b5ba431826e55cfbdacaa79353bd3a2ef94b0362783563ff9e
+  data.tar.gz: 1f369ffa08695ab9eeef87253ef78f8f0891712d597c831d689543d9e16b8f9a
 SHA512:
-  metadata.gz: 30b5381e7d8dcd6e5d789bda4923690b69fcc4902dbeee29b81537383d79d583e6ea3138f2600e475e79ffaeb11732c65c9ddc88befcf08ad07cf185cc82f178
-  data.tar.gz: 4dbbdd99168585f1f714cef6a476122e263f354d1cb379594ecdd7440ae9155a2f02ed6f659e08cb9c4206bcf7c6c97ea503a8968e55fd0f6eefcd11772599d9
+  metadata.gz: dadb82981756de2034d404cff611a78971e89f42cf5a1e50d43af13686d46bb2384a4fab9feb6b08a9fd8e6ca9f38d00e4a78839b36fba97844bdb23e56a592b
+  data.tar.gz: 562954bcdf0b0173c947c87f0f6c47aa4ada512f2c0213f8c536e049b8f43086d93c8fb306f923f1830977a9659598b69ef9dd290f5190d5fa63ed5e26b2ba11

data/README.md

@@ -19,8 +19,9 @@ This SDK is compatible with Featurevisor v3 projects and v2 datafiles.
 - [Getting variation](#getting-variation)
 - [Getting variables](#getting-variables)
   - [Type specific methods](#type-specific-methods)
-- [Getting all evaluations](#getting-all-evaluations)
-- [Sticky](#sticky)
+- [Getting global variables](#getting-global-variables)
+- [Getting aggregate evaluations](#getting-aggregate-evaluations)
+- [Sticky features and variables](#sticky-features-and-variables)
   - [Initialize with sticky](#initialize-with-sticky)
   - [Set sticky afterwards](#set-sticky-afterwards)
 - [Setting datafile](#setting-datafile)
@@ -36,7 +37,7 @@ This SDK is compatible with Featurevisor v3 projects and v2 datafiles.
 - [Events](#events)
   - [`datafile_set`](#datafile_set)
   - [`context_set`](#context_set)
-  - [`sticky_set`](#sticky_set)
+  - [`sticky_features_set` and `sticky_variables_set`](#sticky_features_set-and-sticky_variables_set)
   - [`error`](#error)
 - [Modules](#modules)
   - [Defining a module](#defining-a-module)
@@ -89,7 +90,7 @@ f = Featurevisor.create_featurevisor(
 
 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.
 
-Concurrent evaluations are safe after an instance is configured. Do not mutate or close the same instance concurrently with evaluations. Serialize calls to `set_datafile`, `set_context`, `set_sticky`, `add_module`, `remove_module`, and `close`. Module, event, and diagnostic callbacks must synchronize mutable state that they capture.
+Concurrent evaluations are safe after an instance is configured. Do not mutate or close the same instance concurrently with evaluations. Serialize calls to `set_datafile`, `set_context`, `set_sticky_features`, `set_sticky_variables`, `add_module`, `remove_module`, and `close`. Module, event, and diagnostic callbacks must synchronize mutable state that they capture.
 
 ## Initialization
 
@@ -295,12 +296,24 @@ 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
+## Getting global variables
+
+Global variables use the same methods with a single variable key:
+
+```ruby
+message = f.get_variable_string('welcomeMessage', context)
+value = f.get_variable('checkoutSettings', context)
+evaluation = f.evaluate_variable('checkoutSettings', context)
+```
+
+Global variables resolve sticky values first, then required features, then the first matching override, and finally their default value.
+
+## Getting aggregate evaluations
 
 You can get evaluations of all features available in the SDK instance:
 
 ```ruby
-all_evaluations = f.get_all_evaluations({})
+all_evaluations = f.get_feature_evaluations({})
 
 puts all_evaluations
 # {
@@ -321,11 +334,17 @@ puts all_evaluations
 
 This is handy especially when you want to pass all evaluations from a backend application to the frontend.
 
-## Sticky
+Global variable values are available separately:
+
+```ruby
+global_variables = f.get_variable_evaluations({})
+```
+
+## Sticky features and variables
 
 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.
+Sticky values belong to an SDK or child instance. Feature and global variable sticky values are independent.
 
 ### Initialize with sticky
 
@@ -333,7 +352,7 @@ Sticky values belong to an SDK or child instance. Evaluation options do not acce
 require 'featurevisor'
 
 f = Featurevisor.create_featurevisor(
-  sticky: {
+  sticky_features: {
     myFeatureKey: {
       enabled: true,
       # optional
@@ -345,6 +364,9 @@ f = Featurevisor.create_featurevisor(
     anotherFeatureKey: {
       enabled: false
     }
+  },
+  sticky_variables: {
+    welcomeMessage: 'Welcome back'
   }
 )
 ```
@@ -356,7 +378,7 @@ Once initialized with sticky features, the SDK will look for values there first
 You can also set sticky features after the SDK is initialized:
 
 ```ruby
-f.set_sticky({
+f.set_sticky_features({
   myFeatureKey: {
     enabled: true,
     variation: 'treatment',
@@ -368,6 +390,8 @@ f.set_sticky({
     enabled: false
   }
 }, true) # replace existing sticky features (false by default)
+
+f.set_sticky_variables({ welcomeMessage: 'Welcome back' }, true)
 ```
 
 ## Setting datafile
@@ -393,7 +417,7 @@ By default, `set_datafile(datafile)` merges the incoming datafile into the SDK's
 - `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.
+This means you can call `set_datafile` more than once with different datafiles, and the SDK instance accumulates their features, segments, and global variables together.
 
 ### Replacing
 
@@ -430,7 +454,7 @@ 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.
+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:
 
@@ -496,7 +520,7 @@ f = Featurevisor.create_featurevisor(
 
 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.
+Diagnostic handlers are isolated from SDK behaviour. An exception in a handler does not stop other handlers or evaluations.
 
 
 ## Events
@@ -545,15 +569,19 @@ unsubscribe = f.on('context_set') do |event|
 end
 ```
 
-### `sticky_set`
+### `sticky_features_set` and `sticky_variables_set`
 
 ```ruby
-unsubscribe = f.on('sticky_set') do |event|
+feature_unsubscribe = f.on('sticky_features_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
+
+variable_unsubscribe = f.on('sticky_variables_set') do |event|
+  variables = event[:variables]
+end
 ```
 
 ### `error`
@@ -583,11 +611,14 @@ evaluation = f.evaluate_variation(feature_key, context = {})
 
 # variable
 evaluation = f.evaluate_variable(feature_key, variable_key, context = {})
+
+# global variable
+global_evaluation = f.evaluate_variable(variable_key, context = {})
 ```
 
 The returned object will always contain the following properties:
 
-- `feature_key`: the feature key
+- `feature_key`: the feature key when evaluating a feature
 - `reason`: the reason how the value was evaluated
 
 And optionally these properties depending on whether you are evaluating a feature variation or a variable:
@@ -604,7 +635,11 @@ And optionally these properties depending on whether you are evaluating a featur
 
 ## Modules
 
-Modules allow you to intercept the evaluation process and customize SDK behavior.
+Modules allow you to intercept the evaluation process and customize SDK behaviour.
+
+For feature evaluations, all `before` callbacks run in registration order, followed by all `before_evaluation` callbacks. After evaluation and caller defaults, all `after_evaluation` callbacks run, followed by all `after` callbacks. Global variable evaluations use only `before_evaluation` and `after_evaluation`. Required feature checks run through the complete module pipeline, and transformed defaults are preserved.
+
+`before` and `after` remain available as deprecated feature-only compatibility callbacks. Use `before_evaluation` and `after_evaluation` for new modules so the same callbacks can handle feature and global variable evaluations.
 
 ### Defining a module
 
@@ -630,8 +665,8 @@ my_custom_module = {
     })
   },
 
-  # before evaluation
-  before: ->(options) {
+  # before feature or global variable evaluation
+  before_evaluation: ->(options) {
     # update context before evaluation
     options[:context] = options[:context].merge({
       someAdditionalAttribute: 'value'
@@ -639,13 +674,13 @@ my_custom_module = {
     options
   },
 
-  # after evaluation
-  after: ->(evaluation, options) {
+  # after feature or global variable evaluation
+  after_evaluation: ->(evaluation, options) {
     reason = evaluation[:reason]
     if reason == 'error'
       # log error
-      return
     end
+    evaluation
   },
 
   # configure bucket key
@@ -720,12 +755,14 @@ Now you can pass the child instance where your individual request is being handl
 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')
+global_value = child_f.get_variable('welcomeMessage')
 ```
 
 Similar to parent SDK, child instances also support several additional methods:
 
 - `set_context`
-- `set_sticky`
+- `set_sticky_features`
+- `set_sticky_variables`
 - `evaluate_flag`
 - `is_enabled`
 - `evaluate_variation`
@@ -739,7 +776,8 @@ Similar to parent SDK, child instances also support several additional methods:
 - `get_variable_array`
 - `get_variable_object`
 - `get_variable_json`
-- `get_all_evaluations`
+- `get_feature_evaluations`
+- `get_variable_evaluations`
 - `on`
 - `close`
 
@@ -780,7 +818,7 @@ $ bundle exec featurevisor test \
 
 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.
+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 behaviour 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
 
@@ -828,7 +866,7 @@ The provider currently requires Ruby 3.4 or newer because that is the minimum ve
 Install the provider:
 
 ```ruby
-gem "featurevisor-openfeature", "~> 2.0"
+gem "featurevisor-openfeature", "~> 3.0"
 ```
 
 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.
@@ -852,9 +890,9 @@ enabled = client.fetch_boolean_value(
 )
 ```
 
-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.
+Use `checkout` for a flag, `checkout:variation` for its variation, `checkout:title` for its `title` variable, and `variable:welcomeMessage` for a global 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.
+OpenFeature's targeting key maps to `userId` by default. `targeting_key_field`, `key_separator`, `variation_key`, and `global_variable_prefix` can customize the mapping. The global variable prefix defaults to `variable` and cannot contain the separator.
 
 You can pass any Featurevisor initialization options directly to the provider. These options are used to create the Featurevisor instance owned by the provider:
 
@@ -908,7 +946,7 @@ The build produces `featurevisor-VERSION.gem` and `featurevisor-openfeature-VERS
 - Run `bundle install`
 - Push commit to `main` branch
 - Wait for CI to complete
-- Tag the release with the same version number, for example `v2.0.0`
+- Tag the release with the same version number, for example `v3.1.0`
 - The workflow verifies that the tag matches the shared version
 - The workflow publishes `featurevisor` first, followed by `featurevisor-openfeature`
 

data/lib/featurevisor/openfeature_provider.rb

@@ -11,13 +11,15 @@ module Featurevisor
 
     attr_reader :metadata, :featurevisor
 
-    def initialize(options = {}, featurevisor: nil, targeting_key_field: "userId", key_separator: ":", variation_key: "variation", on_track: nil, **featurevisor_options)
+    def initialize(options = {}, featurevisor: nil, targeting_key_field: "userId", key_separator: ":", variation_key: "variation", global_variable_prefix: "variable", 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
+      @global_variable_prefix = global_variable_prefix.empty? ? "variable" : global_variable_prefix
+      raise ArgumentError, "global_variable_prefix cannot contain key_separator" if @global_variable_prefix.include?(@key_separator)
       @on_track = on_track
       @datafile_error = nil
       @shutdown = false
@@ -86,7 +88,10 @@ module Featurevisor
       targeting_key = evaluation_context&.targeting_key
       context[@targeting_key_field] = targeting_key if targeting_key && !targeting_key.empty?
 
-      if selector.nil? || selector.empty?
+      if feature_key == @global_variable_prefix && selector && !selector.empty?
+        evaluation = featurevisor.evaluate_variable(selector, context)
+        value = evaluation[:variable_value]
+      elsif 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]
@@ -96,7 +101,8 @@ module Featurevisor
       else
         evaluation = featurevisor.evaluate_variable(feature_key, selector, context)
         value = evaluation[:variable_value]
-        if evaluation.dig(:variable_schema, :type) == "json" && value.is_a?(String)
+        variable_type = evaluation.dig(:variable_schema, :type) || evaluation.dig(:variable, :type)
+        if variable_type == "json" && value.is_a?(String)
           begin
             value = JSON.parse(value)
           rescue JSON::ParserError
@@ -127,10 +133,10 @@ module Featurevisor
 
     def metadata_for(evaluation)
       metadata = {
-        "featureKey" => evaluation[:feature_key],
         "featurevisorReason" => evaluation[:reason],
         "schemaVersion" => featurevisor.get_schema_version
       }
+      metadata["featureKey"] = evaluation[:feature_key] unless evaluation[:feature_key].nil?
       metadata["revision"] = featurevisor.get_revision if featurevisor.get_revision
       {
         variable_key: "variableKey",
@@ -138,7 +144,9 @@ module Featurevisor
         bucket_key: "bucketKey",
         bucket_value: "bucketValue",
         force_index: "forceIndex",
-        variable_override_index: "variableOverrideIndex"
+        variable_override_index: "variableOverrideIndex",
+        variable_override_key: "variableOverrideKey",
+        variable_override_path: "variableOverridePath"
       }.each do |key, metadata_key|
         metadata[metadata_key] = evaluation[key] unless evaluation[key].nil?
       end
@@ -149,7 +157,7 @@ module Featurevisor
       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)
+      return Provider::Reason::DISABLED if %w[disabled variation_disabled variable_disabled required_features_unmet].include?(value)
       Provider::Reason::DEFAULT
     end
 
@@ -162,7 +170,10 @@ module Featurevisor
     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"
+      if evaluation[:reason] == "variable_not_found"
+        return %(Variable "#{evaluation[:variable_key]}" was not found) unless evaluation[:feature_key]
+        return %(Variable "#{evaluation[:variable_key]}" was not found for feature "#{evaluation[:feature_key]}")
+      end
       return %(Feature "#{evaluation[:feature_key]}" has no variations) if evaluation[:reason] == "no_variations"
       "Featurevisor evaluation failed"
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: featurevisor-openfeature
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Fahad Heylaal
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 3.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 3.1.0
 - !ruby/object:Gem::Dependency
   name: openfeature-sdk
   requirement: !ruby/object:Gem::Requirement