openfeature-sdk 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c91c19e8a0f7ef628c048224287a276713d704914142d4a2771bd74bf01ea68e
-  data.tar.gz: 565d980320e40d5a573c4710d6313f038c0a58350f6d5eb1564dcd5c85148853
+  metadata.gz: 36540a362c2f482ce84d2aa8ba3a6efd9b5d68fe7881ed4037f1422ad85f5525
+  data.tar.gz: 4f7e6a764074d50467949e056b0d50be794df0a67323bb80c5e34a724236314b
 SHA512:
-  metadata.gz: 7d5dd24ccd3b4e61de24d7a46d02169ad7373d74776664fc0686db4d51dde98c8851c81e392043130f08a4dfd6cdb877a31c3a5ecb2d42c7bd2f5c92b1008fef
-  data.tar.gz: f8ed5ee65b6bee9dd1e36e1373248b12f3729a5ce5a22857c4212957246f7c3b150d48d5cea6e59a7e164d06e69bb53a5d90fc883924c85aaa4f6d64b15e4764
+  metadata.gz: b77f6731c17b537069bbf72cf4760e88293bc59c9ae147079ff3b24ac6ac7f1b18b42b49e29fd1a04a85a6054d0a43834289561c06d6b342ba579ec23d510ef8
+  data.tar.gz: 077d8a3f20c396c82413dad70b9a93cff0cd27a76ff8034f67c50bfa0d08235e3424755a4cd33b81c39fed962d7a62e40d1f257d3bbc4e87bac787d0e315b3fb

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.5.0"
+  ".": "0.5.1"
 }

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.5.1](https://github.com/open-feature/ruby-sdk/compare/v0.5.0...v0.5.1) (2026-03-04)
+
+
+### Features
+
+* implement hooks lifecycle (spec section 4) ([#214](https://github.com/open-feature/ruby-sdk/issues/214)) ([41c3b9e](https://github.com/open-feature/ruby-sdk/commit/41c3b9e2b73b34f50d8135122fb4592f8ec44e49))
+
 ## [0.5.0](https://github.com/open-feature/ruby-sdk/compare/v0.4.1...v0.5.0) (2026-01-16)
 
 

data/CLAUDE.md

@@ -0,0 +1,72 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+OpenFeature Ruby SDK — implements the [OpenFeature specification](https://openfeature.dev) (v0.8.0) for vendor-agnostic feature flag management. Published as the `openfeature-sdk` gem. Pure Ruby, no runtime dependencies. Requires Ruby >= 3.1.
+
+## Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run full test suite + linting (default rake task)
+bundle exec rake
+
+# Run tests only
+bundle exec rspec
+
+# Run a single test file
+bundle exec rspec spec/open_feature/sdk/client_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/open_feature/sdk/client_spec.rb:40
+
+# Lint (StandardRB with performance plugin)
+bundle exec rake standard
+
+# Auto-fix lint issues
+bundle exec standardrb --fix
+```
+
+## Architecture
+
+Entry point: `require 'open_feature/sdk'` — the `OpenFeature::SDK` module delegates all method calls to `API.instance` (Singleton) via `method_missing`.
+
+### Core Components
+
+- **API** (`lib/open_feature/sdk/api.rb`) — Singleton orchestrator. Manages providers (global or domain-scoped), builds clients, stores API-level evaluation context, and registers event handlers.
+- **Configuration** (`lib/open_feature/sdk/configuration.rb`) — Thread-safe provider storage. Handles provider lifecycle (init/shutdown), domain-scoped provider mapping, and event dispatching. Uses Mutex for all shared state.
+- **Client** (`lib/open_feature/sdk/client.rb`) — Flag evaluation interface. Uses `class_eval` metaprogramming to generate 12 typed methods: `fetch_{boolean,string,number,integer,float,object}_value` and `fetch_*_details` variants. Merges evaluation contexts (API + client + invocation).
+- **EvaluationContext** (`lib/open_feature/sdk/evaluation_context.rb`) — Key-value targeting data with a special `targeting_key`. Supports merging with precedence: invocation > client > API.
+
+### Provider System
+
+- **Provider interface** — Must implement 6 `fetch_*_value` methods, optional `init(evaluation_context)` and `shutdown`. Returns `ResolutionDetails`.
+- **EventEmitter** (`lib/open_feature/sdk/provider/event_emitter.rb`) — Mixin that providers include to emit lifecycle events.
+- **Built-in providers**: `NoOpProvider` (default), `InMemoryProvider` (testing/examples).
+- **Provider states**: `NOT_READY → READY`, with `ERROR`, `FATAL`, `STALE` transitions. Tracked per-instance via `ProviderStateRegistry` using `object_id`.
+- **Initialization modes**: `set_provider` (async, background thread) or `set_provider_and_wait` (sync, raises `ProviderInitializationError` on failure).
+
+### Event System
+
+- **EventDispatcher** (`lib/open_feature/sdk/event_dispatcher.rb`) — Thread-safe pub-sub. Handlers called outside mutex to prevent deadlocks. Supports API-level and client-level handlers.
+- **ProviderEvent** constants: `PROVIDER_READY`, `PROVIDER_ERROR`, `PROVIDER_STALE`, `PROVIDER_CONFIGURATION_CHANGED`.
+
+## Test Structure
+
+Tests in `spec/` split into two categories:
+- `spec/specification/` — OpenFeature spec compliance tests, organized by requirement number (e.g., "Requirement 1.1.1")
+- `spec/open_feature/` — Unit tests for individual components
+
+Uses Timecop for time-sensitive tests (auto-reset after each test), SimpleCov for coverage.
+
+## Conventions
+
+- **Linter**: StandardRB (Ruby Standard Style) with `standard-performance` plugin, targeting Ruby 3.1
+- **Commits**: Conventional Commits required for PR titles (enforced by CI)
+- **Releases**: Automated via release-please; changelog auto-generated
+- **Threading**: All shared mutable state must be Mutex-protected. Provider storage uses immutable reassignment (`@providers = @providers.dup.merge(...)`)
+- **Structs for DTOs**: `EvaluationDetails`, `ResolutionDetails`, `ClientMetadata`, `ProviderMetadata` are `Struct`-based

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    openfeature-sdk (0.5.0)
+    openfeature-sdk (0.5.1)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -17,8 +17,8 @@
   </a>
   <!-- x-release-please-start-version -->
 
-  <a href="https://github.com/open-feature/ruby-sdk/releases/tag/v0.5.0">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.5.0&color=blue&style=for-the-badge" />
+  <a href="https://github.com/open-feature/ruby-sdk/releases/tag/v0.5.1">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.5.1&color=blue&style=for-the-badge" />
   </a>
 
   <!-- x-release-please-end -->

data/lib/open_feature/sdk/api.rb

@@ -8,6 +8,7 @@ require_relative "evaluation_context"
 require_relative "evaluation_context_builder"
 require_relative "evaluation_details"
 require_relative "client_metadata"
+require_relative "hooks"
 require_relative "client"
 require_relative "provider"
 

data/lib/open_feature/sdk/client.rb

@@ -15,6 +15,7 @@ module OpenFeature
       }.freeze
       RESULT_TYPE = TYPE_CLASS_MAP.keys.freeze
       SUFFIXES = %i[value details].freeze
+      EMPTY_HINTS = Hooks::Hints.new.freeze
 
       attr_reader :metadata, :evaluation_context
 
@@ -40,11 +41,8 @@ module OpenFeature
       RESULT_TYPE.each do |result_type|
         SUFFIXES.each do |suffix|
           class_eval <<-RUBY, __FILE__, __LINE__ + 1
-            # def fetch_boolean_details(flag_key:, default_value:, evaluation_context: nil)
-            #   result = @provider.fetch_boolean_value(flag_key: flag_key, default_value: default_value, evaluation_context: evaluation_context)
-            # end
-            def fetch_#{result_type}_#{suffix}(flag_key:, default_value:, evaluation_context: nil)
-              evaluation_details = fetch_details(type: :#{result_type}, flag_key:, default_value:, evaluation_context:)
+            def fetch_#{result_type}_#{suffix}(flag_key:, default_value:, evaluation_context: nil, hooks: [], hook_hints: nil)
+              evaluation_details = fetch_details(type: :#{result_type}, flag_key:, default_value:, evaluation_context:, invocation_hooks: hooks, hook_hints: hook_hints)
               #{"evaluation_details.value" if suffix == :value}
             end
           RUBY
@@ -53,12 +51,54 @@ module OpenFeature
 
       private
 
-      def fetch_details(type:, flag_key:, default_value:, evaluation_context: nil)
+      def fetch_details(type:, flag_key:, default_value:, evaluation_context: nil, invocation_hooks: [], hook_hints: nil)
         validate_default_value_type(type, default_value)
 
-        built_context = EvaluationContextBuilder.new.call(api_context: OpenFeature::SDK.evaluation_context, client_context: self.evaluation_context, invocation_context: evaluation_context)
+        built_context = EvaluationContextBuilder.new.call(
+          api_context: OpenFeature::SDK.evaluation_context,
+          client_context: self.evaluation_context,
+          invocation_context: evaluation_context
+        )
 
-        resolution_details = @provider.send(:"fetch_#{type}_value", flag_key:, default_value:, evaluation_context: built_context)
+        # Assemble ordered hooks: API → Client → Invocation → Provider (spec 4.4.2)
+        provider_hooks = @provider.respond_to?(:hooks) ? Array(@provider.hooks) : []
+        ordered_hooks = [*OpenFeature::SDK.hooks, *@hooks, *invocation_hooks, *provider_hooks]
+
+        # Fast path: skip hook ceremony when no hooks are registered
+        if ordered_hooks.empty?
+          return evaluate_flag(type: type, flag_key: flag_key, default_value: default_value, evaluation_context: built_context)
+        end
+
+        hook_context = Hooks::HookContext.new(
+          flag_key: flag_key,
+          flag_value_type: type,
+          default_value: default_value,
+          evaluation_context: built_context,
+          client_metadata: @metadata,
+          provider_metadata: @provider.respond_to?(:metadata) ? @provider.metadata : nil
+        )
+
+        hints = if hook_hints.is_a?(Hooks::Hints)
+          hook_hints
+        elsif hook_hints
+          Hooks::Hints.new(hook_hints)
+        else
+          EMPTY_HINTS
+        end
+
+        executor = Hooks::HookExecutor.new(logger: OpenFeature::SDK.configuration.logger)
+        executor.execute(ordered_hooks: ordered_hooks, hook_context: hook_context, hints: hints) do |hctx|
+          evaluate_flag(type: type, flag_key: flag_key, default_value: default_value, evaluation_context: hctx.evaluation_context)
+        end
+      end
+
+      def evaluate_flag(type:, flag_key:, default_value:, evaluation_context:)
+        resolution_details = @provider.send(
+          :"fetch_#{type}_value",
+          flag_key: flag_key,
+          default_value: default_value,
+          evaluation_context: evaluation_context
+        )
 
         if TYPE_CLASS_MAP[type].none? { |klass| resolution_details.value.is_a?(klass) }
           resolution_details.value = default_value
@@ -66,7 +106,7 @@ module OpenFeature
           resolution_details.reason = Provider::Reason::ERROR
         end
 
-        EvaluationDetails.new(flag_key:, resolution_details:)
+        EvaluationDetails.new(flag_key: flag_key, resolution_details: resolution_details)
       end
 
       def validate_default_value_type(type, default_value)

data/lib/open_feature/sdk/hooks/hints.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "delegate"
+
 module OpenFeature
   module SDK
     module Hooks

data/lib/open_feature/sdk/hooks/hook.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module OpenFeature
+  module SDK
+    module Hooks
+      # Module that hooks include. Provides default no-op implementations
+      # for all four lifecycle stages. A hook overrides the stages it cares about.
+      #
+      # Spec 4.3.1: Hooks MUST specify at least one stage.
+      module Hook
+        # Called before flag evaluation. May return an EvaluationContext
+        # that gets merged into the existing context (spec 4.3.2.1, 4.3.4, 4.3.5).
+        def before(hook_context:, hints:)
+          nil
+        end
+
+        # Called after successful flag evaluation (spec 4.3.3).
+        def after(hook_context:, evaluation_details:, hints:)
+          nil
+        end
+
+        # Called when an error occurs during flag evaluation (spec 4.3.6).
+        def error(hook_context:, exception:, hints:)
+          nil
+        end
+
+        # Called unconditionally after flag evaluation (spec 4.3.7).
+        def finally(hook_context:, evaluation_details:, hints:)
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/open_feature/sdk/hooks/hook_context.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module OpenFeature
+  module SDK
+    module Hooks
+      # Provides context to hook stages during flag evaluation.
+      #
+      # Per spec 4.1.1-4.1.5:
+      # - flag_key, flag_value_type, default_value are immutable (4.1.3)
+      # - client_metadata, provider_metadata are optional (4.1.2)
+      # - evaluation_context is mutable (for before hooks to modify, 4.1.4.1)
+      class HookContext
+        attr_reader :flag_key, :flag_value_type, :default_value,
+          :client_metadata, :provider_metadata
+        attr_accessor :evaluation_context
+
+        def initialize(flag_key:, flag_value_type:, default_value:, evaluation_context:,
+          client_metadata: nil, provider_metadata: nil)
+          @flag_key = flag_key.freeze
+          @flag_value_type = flag_value_type.freeze
+          @default_value = default_value.freeze
+          @evaluation_context = evaluation_context
+          @client_metadata = client_metadata
+          @provider_metadata = provider_metadata
+        end
+      end
+    end
+  end
+end

data/lib/open_feature/sdk/hooks/hook_executor.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module OpenFeature
+  module SDK
+    module Hooks
+      # Orchestrates the full hook lifecycle for flag evaluation.
+      #
+      # Hook execution order (spec 4.4.2):
+      #   Before: API → Client → Invocation → Provider
+      #   After/Error/Finally: Provider → Invocation → Client → API (reverse)
+      #
+      # Error handling (spec 4.4.3-4.4.7):
+      #   - Before/after hook error → stop remaining hooks, run error hooks, return default
+      #   - Error hook error → log, continue remaining error hooks
+      #   - Finally hook error → log, continue remaining finally hooks
+      class HookExecutor
+        def initialize(logger: nil)
+          @logger = logger
+        end
+
+        # Executes the full hook lifecycle around the flag evaluation block.
+        #
+        # @param ordered_hooks [Array] hooks in before-order (API, Client, Invocation, Provider)
+        # @param hook_context [HookContext] the hook context
+        # @param hints [Hints] hook hints
+        # @param evaluate_block [Proc] the flag evaluation to wrap
+        # @return [EvaluationDetails] the evaluation result
+        def execute(ordered_hooks:, hook_context:, hints:, &evaluate_block)
+          evaluation_details = nil
+
+          begin
+            run_before_hooks(ordered_hooks, hook_context, hints)
+            evaluation_details = evaluate_block.call(hook_context)
+            run_after_hooks(ordered_hooks, hook_context, evaluation_details, hints)
+          rescue => e
+            run_error_hooks(ordered_hooks, hook_context, e, hints)
+
+            evaluation_details = EvaluationDetails.new(
+              flag_key: hook_context.flag_key,
+              resolution_details: Provider::ResolutionDetails.new(
+                value: hook_context.default_value,
+                error_code: Provider::ErrorCode::GENERAL,
+                reason: Provider::Reason::ERROR,
+                error_message: e.message
+              )
+            )
+          ensure
+            run_finally_hooks(ordered_hooks, hook_context, evaluation_details, hints)
+          end
+
+          evaluation_details
+        end
+
+        private
+
+        # Spec 4.4.2: Before hooks run in order: API → Client → Invocation → Provider
+        # Spec 4.3.4/4.3.5: If a before hook returns an EvaluationContext, it is merged
+        # into the existing context for subsequent hooks and evaluation.
+        def run_before_hooks(hooks, hook_context, hints)
+          hooks.each do |hook|
+            next unless hook.respond_to?(:before)
+            result = hook.before(hook_context: hook_context, hints: hints)
+            if result.is_a?(EvaluationContext)
+              existing = hook_context.evaluation_context
+              hook_context.evaluation_context = existing ? existing.merge(result) : result
+            end
+          end
+        end
+
+        # Spec 4.4.2: After hooks run in reverse order: Provider → Invocation → Client → API
+        def run_after_hooks(hooks, hook_context, evaluation_details, hints)
+          hooks.reverse_each do |hook|
+            next unless hook.respond_to?(:after)
+            hook.after(hook_context: hook_context, evaluation_details: evaluation_details, hints: hints)
+          end
+        end
+
+        # Spec 4.4.4: Error hooks run in reverse order.
+        # If an error hook itself errors, log and continue remaining error hooks.
+        def run_error_hooks(hooks, hook_context, exception, hints)
+          hooks.reverse_each do |hook|
+            next unless hook.respond_to?(:error)
+            hook.error(hook_context: hook_context, exception: exception, hints: hints)
+          rescue => e
+            @logger&.error("Error hook #{hook.class.name} failed: #{e.message}")
+          end
+        end
+
+        # Spec 4.4.3: Finally hooks run in reverse order unconditionally.
+        # If a finally hook errors, log and continue remaining finally hooks.
+        def run_finally_hooks(hooks, hook_context, evaluation_details, hints)
+          hooks.reverse_each do |hook|
+            next unless hook.respond_to?(:finally)
+            hook.finally(hook_context: hook_context, evaluation_details: evaluation_details, hints: hints)
+          rescue => e
+            @logger&.error("Finally hook #{hook.class.name} failed: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/open_feature/sdk/hooks.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "hooks/hints"
+require_relative "hooks/hook"
+require_relative "hooks/hook_context"
+require_relative "hooks/hook_executor"

data/lib/open_feature/sdk/version.rb

@@ -2,6 +2,6 @@
 
 module OpenFeature
   module SDK
-    VERSION = "0.5.0"
+    VERSION = "0.5.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openfeature-sdk
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - OpenFeature Authors
@@ -150,6 +150,7 @@ files:
 - ".standard.yml"
 - ".tool-versions"
 - CHANGELOG.md
+- CLAUDE.md
 - CODEOWNERS
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
@@ -167,7 +168,11 @@ files:
 - lib/open_feature/sdk/evaluation_context_builder.rb
 - lib/open_feature/sdk/evaluation_details.rb
 - lib/open_feature/sdk/event_dispatcher.rb
+- lib/open_feature/sdk/hooks.rb
 - lib/open_feature/sdk/hooks/hints.rb
+- lib/open_feature/sdk/hooks/hook.rb
+- lib/open_feature/sdk/hooks/hook_context.rb
+- lib/open_feature/sdk/hooks/hook_executor.rb
 - lib/open_feature/sdk/provider.rb
 - lib/open_feature/sdk/provider/error_code.rb
 - lib/open_feature/sdk/provider/event_emitter.rb