featurevisor-openfeature 1.1.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac21a86ef0432191f6a12f262dd00b524f520a0e5a1cd88bf2029b0428842c46
-  data.tar.gz: 9add287e8f085ee1b446db5ccf5c577a2f4758a78be61ca36dc0af4793b9f8ab
+  metadata.gz: 3a8495a304439dace1b52ba45bd2a7e9b4947cf482a179af80b9a3c8bb1f8e2c
+  data.tar.gz: 3473b28bac62de80fd0950c895d1a1a912919752cb99007cf04f922702bd6bb1
 SHA512:
-  metadata.gz: f0ea87c62a2cfbe51bd00c5d3d75b2fb1f26f2989d5df8cfe44f52fba840374673c439960855441783074c61e531185d11decd393838cc7da485740467e53e3e
-  data.tar.gz: d93238543cd2e2bef46ed2d2bc6c56ce4ca6bf8fc35211a837f1523d1e14c7bcbb016a7aea95d2b1057e2d09632d949c928d098495d0315a38fc868fdb640ae4
+  metadata.gz: f325bd259bd59b4e8ae6a3ef7bb6b3b48d534bbfcaaf7e2212f1bacc9b23e334bcc1e54b7bd017c8adcd4ed09340e56345ad89798a7d4c7cbcf72f521169dd23
+  data.tar.gz: 101e2d9eab3c39afea5cb634e294107606cf500db85040916ecaf0c570b66ea7c47b09773a7dfa11c09604f17ad858c99c712b48854500483a044710d7a7feec

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2025 Fahad Heylaal (https://fahad19.com)
+Copyright (c) 2026 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

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,6 +90,8 @@ 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_features`, `set_sticky_variables`, `add_module`, `remove_module`, and `close`. Module, event, and diagnostic callbacks must synchronize mutable state that they capture.
+
 ## Initialization
 
 The SDK can be initialized by passing [datafile](https://featurevisor.com/docs/building-datafiles/) content directly:
@@ -293,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
 # {
@@ -319,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
 
@@ -331,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
@@ -343,6 +364,9 @@ f = Featurevisor.create_featurevisor(
     anotherFeatureKey: {
       enabled: false
     }
+  },
+  sticky_variables: {
+    welcomeMessage: 'Welcome back'
   }
 )
 ```
@@ -354,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',
@@ -366,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
@@ -391,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
 
@@ -543,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`
@@ -581,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,6 +637,8 @@ And optionally these properties depending on whether you are evaluating a featur
 
 Modules allow you to intercept the evaluation process and customize SDK behavior.
 
+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.
+
 ### Defining a module
 
 A module is a simple hash with a unique recommended `name` and optional lifecycle functions:
@@ -637,6 +672,9 @@ my_custom_module = {
     options
   },
 
+  # unified callback for feature and global variable evaluations
+  before_evaluation: ->(options) { options },
+
   # after evaluation
   after: ->(evaluation, options) {
     reason = evaluation[:reason]
@@ -646,6 +684,9 @@ my_custom_module = {
     end
   },
 
+  # unified callback for feature and global variable evaluations
+  after_evaluation: ->(evaluation, options) { evaluation },
+
   # configure bucket key
   bucket_key: ->(options) {
     # return custom bucket key
@@ -697,6 +738,8 @@ f.remove_module('my-custom-module')
 
 ## Child instance
 
+A child snapshots the parent keys that exist when it is spawned. Child values win for those keys. Parent keys introduced later are still inherited. Calling `close` removes both child-owned listeners and subscriptions delegated to the parent.
+
 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.
@@ -716,14 +759,19 @@ 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`
 - `get_variation`
+- `evaluate_variable`
 - `get_variable`
 - `get_variable_boolean`
 - `get_variable_string`
@@ -732,7 +780,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`
 
@@ -821,7 +870,7 @@ The provider currently requires Ruby 3.4 or newer because that is the minimum ve
 Install the provider:
 
 ```ruby
-gem "featurevisor-openfeature", "~> 1.1"
+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.
@@ -845,9 +894,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:
 
@@ -901,7 +950,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 `v1.1.0`
+- Tag the release with the same version number, for example `v3.0.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: 1.1.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Fahad Heylaal
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: 3.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: openfeature-sdk
   requirement: !ruby/object:Gem::Requirement