featurevisor 0.3.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42c8ec3e5bf6293eeae189365b0383588a8cf7fdd5a5ee249a6fd44a2676403c
-  data.tar.gz: ce5794865b3dd5a057b9e0841814dab1c276b52237f230e23da6317f8dea3f70
+  metadata.gz: 202758e9fe9a2c81f67c3ea7456be5d068c1d9aa8ccf35f721a4ca447a94196a
+  data.tar.gz: bf2cae186ce5b6d3b483f4eab14768553cc5d2e09148c16ebbaf3ac60af7d7a0
 SHA512:
-  metadata.gz: 41aefa056806a97bc1f5bf13d847007fd4b38fb176f97d1a09868434644fda2ed8cd58698ad9f5002a6ef5d30f7fc105accf7d505eb41fb71abe28a5bda6e47c
-  data.tar.gz: e4376d46699b8fe730d4dc4f73890fd43c6e879c446bc484dc6a47cc6b2c31f715af41b83b5f6189f9b8eeed3fd61b48213ec589855d909fe7ebccb702c04303
+  metadata.gz: aa565646ae2e3b54d018044a79e92d9172e0ac8478dbb2dbee1699605a9457fbea6b694dc42c9027b40d4d2a3358c3146be946cfe307319119ab6ba2d03657ed
+  data.tar.gz: e8e689efcc96ac4ca3bd0ec7469895fbb1c9b4e70737d0f56f87fa9f0733395c0e0de6938a7b6c7c4c6bd7daef9f9818daa9163e508b0242836b750aa83e82f4

data/README.md

@@ -1,12 +1,13 @@
 # Featurevisor Ruby SDK <!-- omit in toc -->
 
-This is a port of Featurevisor [JavaScript SDK](https://featurevisor.com/docs/sdks/javascript/) v2.x to Ruby, providing a way to evaluate feature flags, variations, and variables in your Ruby applications.
+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](https://featurevisor.com/) v2.0 projects and above.
+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)
@@ -23,22 +24,26 @@ This SDK is compatible with [Featurevisor](https://featurevisor.com/) v2.0 proje
   - [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)
-- [Logging](#logging)
+- [Evaluation details](#evaluation-details)
+- [Diagnostics](#diagnostics)
   - [Levels](#levels)
-  - [Customizing levels](#customizing-levels)
   - [Handler](#handler)
 - [Events](#events)
   - [`datafile_set`](#datafile_set)
   - [`context_set`](#context_set)
   - [`sticky_set`](#sticky_set)
-- [Evaluation details](#evaluation-details)
-- [Hooks](#hooks)
-  - [Defining a hook](#defining-a-hook)
-  - [Registering hooks](#registering-hooks)
+  - [`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)
@@ -72,6 +77,18 @@ Or install it yourself as:
 $ 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:
@@ -89,7 +106,7 @@ response = Net::HTTP.get_response(URI(datafile_url))
 datafile_content = JSON.parse(response.body, symbolize_names: true)
 
 # Create SDK instance
-f = Featurevisor.create_instance(
+f = Featurevisor.create_featurevisor(
   datafile: datafile_content
 )
 ```
@@ -101,10 +118,10 @@ Alternatively, you can pass a JSON string directly and the SDK will parse it aut
 ```ruby
 # Option 1: Parse JSON yourself (recommended)
 datafile_content = JSON.parse(json_string, symbolize_names: true)
-f = Featurevisor.create_instance(datafile: datafile_content)
+f = Featurevisor.create_featurevisor(datafile: datafile_content)
 
 # Option 2: Pass JSON string directly (automatic parsing)
-f = Featurevisor.create_instance(datafile: json_string)
+f = Featurevisor.create_featurevisor(datafile: json_string)
 ```
 
 ## Evaluation types
@@ -142,7 +159,7 @@ You can set context at the time of initialization:
 ```ruby
 require 'featurevisor'
 
-f = Featurevisor.create_instance(
+f = Featurevisor.create_featurevisor(
   context: {
     deviceId: '123',
     country: 'nl'
@@ -274,6 +291,8 @@ 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:
@@ -304,12 +323,14 @@ This is handy especially when you want to pass all evaluations from a backend ap
 
 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_instance(
+f = Featurevisor.create_featurevisor(
   sticky: {
     myFeatureKey: {
       enabled: true,
@@ -362,6 +383,49 @@ 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.
@@ -400,65 +464,38 @@ end
 Thread.new { update_datafile(f, datafile_url) }
 ```
 
-## Logging
+## Diagnostics
 
-By default, Featurevisor SDKs will print out logs to the console for `info` level and above.
+By default, Featurevisor reports diagnostics to the console for `info` level and above with a `[Featurevisor]` prefix.
 
 ### Levels
 
-These are all the available log levels:
-
-- `error`
-- `warn`
-- `info`
-- `debug`
-
-### Customizing levels
+Available diagnostic levels are `fatal`, `error`, `warn`, `info`, and `debug`.
 
-If you choose `debug` level to make the logs more verbose, you can set it at the time of SDK initialization.
-
-Setting `debug` level will print out all logs, including `info`, `warn`, and `error` levels.
+Set the level during initialization or update it afterwards:
 
 ```ruby
-require 'featurevisor'
-
-f = Featurevisor.create_instance(
-  logger: Featurevisor.create_logger(level: 'debug')
-)
-```
-
-Alternatively, you can also set `log_level` directly:
-
-```ruby
-f = Featurevisor.create_instance(
-  log_level: 'debug'
-)
-```
-
-You can also set log level from SDK instance afterwards:
-
-```ruby
-f.set_log_level('debug')
+f = Featurevisor.create_featurevisor(log_level: "debug")
+f.set_log_level("info")
 ```
 
 ### Handler
 
-You can also pass your own log handler, if you do not wish to print the logs to the console:
+Use `on_diagnostic` to send structured diagnostics to your observability system:
 
 ```ruby
-require 'featurevisor'
-
-f = Featurevisor.create_instance(
-  logger: Featurevisor.create_logger(
-    level: 'info',
-    handler: ->(level, message, details) {
-      # do something with the log
-    }
-  )
+f = Featurevisor.create_featurevisor(
+  log_level: "info",
+  on_diagnostic: ->(diagnostic) {
+    puts "#{diagnostic[:level]} #{diagnostic[:code]} #{diagnostic[:message]}"
+  }
 )
 ```
 
-Further log levels like `info` and `debug` will help you understand how the feature variations and variables are evaluated in the runtime against given context.
+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
 
@@ -471,8 +508,8 @@ You can listen to these events that can occur at various stages in your applicat
 ```ruby
 unsubscribe = f.on('datafile_set') do |event|
   revision = event[:revision]        # new revision
-  previous_revision = event[:previous_revision]
-  revision_changed = event[:revision_changed] # true if revision has changed
+  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
@@ -493,6 +530,8 @@ The `features` array will contain keys of features that have either been:
 
 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
@@ -515,6 +554,20 @@ unsubscribe = f.on('sticky_set') do |event|
 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:
@@ -547,22 +600,33 @@ And optionally these properties depending on whether you are evaluating a featur
 - `variable_value`: the variable value
 - `variable_schema`: the variable schema
 
-## Hooks
+## Modules
 
-Hooks allow you to intercept the evaluation process and customize it further as per your needs.
+Modules allow you to intercept the evaluation process and customize SDK behavior.
 
-### Defining a hook
+### Defining a module
 
-A hook is a simple hash with a unique required `name` and optional functions:
+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_hook = {
-  # only required property
-  name: 'my-custom-hook',
+my_custom_module = {
+  # recommended, and used for duplicate detection/removal
+  name: 'my-custom-module',
+
+  # rest of the properties below are all optional per module
 
-  # rest of the properties below are all optional per hook
+  # 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) {
@@ -592,26 +656,43 @@ my_custom_hook = {
   bucket_value: ->(options) {
     # return custom bucket value
     options[:bucket_value]
+  },
+
+  # cleanup when module is removed or SDK is closed
+  close: -> {
+    # cleanup here
   }
 }
 ```
 
-### Registering hooks
+The module API passed to `setup` exposes:
 
-You can register hooks at the time of SDK initialization:
+- `get_revision`
+- `on_diagnostic`
+- `report_diagnostic`
+
+### Registering modules
+
+You can register modules at the time of SDK initialization:
 
 ```ruby
 require 'featurevisor'
 
-f = Featurevisor.create_instance(
-  hooks: [my_custom_hook]
+f = Featurevisor.create_featurevisor(
+  modules: [my_custom_module]
 )
 ```
 
 Or after initialization:
 
 ```ruby
-f.add_hook(my_custom_hook)
+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
@@ -687,29 +768,24 @@ $ bundle exec featurevisor test \
   --quiet|--verbose \
   --onlyFailures \
   --keyPattern="myFeatureKey" \
-  --assertionPattern="#1" \
-  --with-scopes \
-  --with-tags
+  --assertionPattern="#1"
 ```
 
-`--with-scopes` and `--with-tags` make the Ruby test runner build scoped/tagged datafiles in memory (via `npx featurevisor build --json`) and evaluate matching assertions against those exact datafiles.
+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.
 
-If an assertion references `scope` and `--with-scopes` is not provided, the runner still evaluates the assertion by merging that scope's configured context into the assertion context (without building scoped datafiles).
-
-For compatibility, camelCase aliases are also supported: `--withScopes` and `--withTags`.
+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 featurevisor test --projectDirectoryPath=./monorepo/examples/example-1
-$ bundle exec featurevisor test --projectDirectoryPath=./monorepo/examples/example-1 --with-scopes
-$ bundle exec featurevisor test --projectDirectoryPath=./monorepo/examples/example-1 --with-tags
+$ 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/cmd/#benchmarking).
+Learn more about benchmarking [here](https://featurevisor.com/docs/cli/#benchmarking).
 
 ```bash
 $ bundle exec featurevisor benchmark \
@@ -722,7 +798,7 @@ $ bundle exec featurevisor benchmark \
 
 ### Assess distribution
 
-Learn more about assessing distribution [here](https://featurevisor.com/docs/cmd/#assess-distribution).
+Learn more about assessing distribution [here](https://featurevisor.com/docs/cli/#assess-distribution).
 
 ```bash
 $ bundle exec featurevisor assess-distribution \
@@ -736,30 +812,100 @@ $ bundle exec featurevisor assess-distribution \
   --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 repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+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
 ```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+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 version in `lib/featurevisor/version.rb`
+- 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 version number
-- This will trigger a new release to [RubyGems](https://rubygems.org/gems/featurevisor)
+- 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
 

data/bin/cli.rb

@@ -7,12 +7,13 @@ module FeaturevisorCLI
     attr_accessor :command, :assertion_pattern, :context, :environment, :feature,
                  :key_pattern, :n, :only_failures, :quiet, :variable, :variation,
                  :verbose, :inflate, :show_datafile, :schema_version, :project_directory_path,
-                 :populate_uuid, :with_scopes, :with_tags
+                 :populate_uuid, :with_scopes, :with_tags, :targets
 
     def initialize
       @n = 1000
       @project_directory_path = Dir.pwd
       @populate_uuid = []
+      @targets = []
     end
   end
 
@@ -82,15 +83,15 @@ module FeaturevisorCLI
           options.show_datafile = true
         end
 
-        opts.on("--schemaVersion=VERSION", "Schema version") do |v|
+        opts.on("--schemaVersion=VERSION", "--schema-version=VERSION", "Legacy schema version option accepted and ignored") do |v|
           options.schema_version = v
         end
 
-        opts.on("--with-scopes", "--withScopes", "Test scoped assertions against scoped datafiles") do
+        opts.on("--with-scopes", "--withScopes", "Legacy scope option accepted and ignored") do
           options.with_scopes = true
         end
 
-        opts.on("--with-tags", "--withTags", "Test tagged assertions against tagged datafiles") do
+        opts.on("--with-tags", "--withTags", "Legacy tag option accepted and ignored") do
           options.with_tags = true
         end
 
@@ -102,6 +103,10 @@ module FeaturevisorCLI
           options.populate_uuid << v
         end
 
+        opts.on("--target=TARGET", "Target datafile; repeat for multiple targets") do |v|
+          options.targets << v unless options.targets.include?(v)
+        end
+
         opts.on("-h", "--help", "Show this help message") do
           puts opts
           exit