launchdarkly-openfeature-server-sdk 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cde8b4698ae233e35dbfb0374fe5d01f86cad889a5dd7cdb5d501bf460a08e59
-  data.tar.gz: 800e91c816324cd7fdd1c00476fee09e1b70eb03cfaa7d1064e748c4584e7139
+  metadata.gz: a049cefbbcbd5e85ec11ecb64d78c6e2a0c838bf702f266dad3e0aed9895b8d0
+  data.tar.gz: a3ff14970d3b4cfcd990e0d902c6c080bfbec96965fbb306800c93a405654a32
 SHA512:
-  metadata.gz: bc87f538233fc26f07dfe75f064186d5780cf4bc75ddbc176b433ddd926da733d1d2369f9801f627370fd7c45e3427742bfe6a1fff1be5b47de6a6f13e15af95
-  data.tar.gz: b4ff462356adf44223d27c2aeabd6ccc60516390d137b87b5b9cbb726ca8790cb1ca9616db93854b715843685dcecec4c44ca9f2f4f1aa81698dd3eab4633886
+  metadata.gz: d6faf775bd94dfcf35f9b5542b793e61d59b06dd74d7217ca1eaeac06cae58f2c7acf287dd352bd344535a8b82176177b7edea7478440dcdf306211c75b1b0fd
+  data.tar.gz: 583e9d48d1ed7ac46cf22bed6f8ecb7f20d369ceedd0d2bbb3163878f2695dfc251a919218fc2e8b472a14b4b75a6819360789f0d6b69b4453d219f4f4f90ddb

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.2.0"
+  ".": "0.3.0"
 }

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.3.0](https://github.com/launchdarkly/openfeature-ruby-server/compare/0.2.0...0.3.0) (2026-08-25)
+
+
+### Features
+
+* Emit provider events from LaunchDarkly client status ([#29](https://github.com/launchdarkly/openfeature-ruby-server/issues/29)) ([1b53b0c](https://github.com/launchdarkly/openfeature-ruby-server/commit/1b53b0c08165efdc29e2504e56b0be651bd3f6e7))
+* Populate OpenFeature flag metadata from the evaluation reason ([#31](https://github.com/launchdarkly/openfeature-ruby-server/issues/31)) ([e6ef78a](https://github.com/launchdarkly/openfeature-ruby-server/commit/e6ef78aafc480de7b61b5ed00d41c6adafe532f3))
+* Report provider name and version to LaunchDarkly ([#30](https://github.com/launchdarkly/openfeature-ruby-server/issues/30)) ([c5dd94d](https://github.com/launchdarkly/openfeature-ruby-server/commit/c5dd94dd09a70f7d10f4dcd5a907f9e1db43a046))
+* Support OpenFeature tracking ([#27](https://github.com/launchdarkly/openfeature-ruby-server/issues/27)) ([709f52d](https://github.com/launchdarkly/openfeature-ruby-server/commit/709f52d73ffaf5144f45eec92101abc77f4a93f5))
+* Support provider initialization and shutdown ([#28](https://github.com/launchdarkly/openfeature-ruby-server/issues/28)) ([27df803](https://github.com/launchdarkly/openfeature-ruby-server/commit/27df80355abac7e3ed18a3549da5f178f1a47234))
+
 ## [0.2.0](https://github.com/launchdarkly/openfeature-ruby-server/compare/0.1.0...0.2.0) (2026-04-02)
 
 

data/PROVENANCE.md

@@ -9,7 +9,7 @@ To verify build provenance attestations, we recommend using the [GitHub CLI `att
 <!-- x-release-please-start-version -->
 ```
 # Set the version of the SDK to verify
-SDK_VERSION=0.2.0
+SDK_VERSION=0.3.0
 ```
 <!-- x-release-please-end -->
 

data/README.md

@@ -26,6 +26,27 @@ This provider is designed primarily for use in multi-user systems such as web se
 
 This version of the LaunchDarkly provider works with Ruby 3.4 and above.
 
+## Feature matrix
+
+This matrix mirrors the [feature matrix of the OpenFeature SDK for Ruby](https://github.com/open-feature/ruby-sdk#-features) and describes what this provider supports. Rows which are not supported state whether the limitation comes from the OpenFeature Ruby SDK or from the provider.
+
+| Status | Feature                         | Notes                                                                                                                                                                                                                    |
+|--------|---------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| ✅      | Providers                       | Evaluates boolean, string, integer, float, number, and object flags through the LaunchDarkly Ruby SDK.                                                                                                                    |
+| ✅      | Targeting                       | The `EvaluationContext` is converted to a LaunchDarkly single or multi-context. See [OpenFeature Specific Considerations](#openfeature-specific-considerations).                                                          |
+| ✅      | Hooks                           | Hooks are registered on the OpenFeature API and client; the provider requires no additional support and its results are visible to hooks, including [flag metadata](#flag-metadata).                                      |
+| ✅      | Logging                         | The provider logs through the logger of the `LaunchDarkly::Config` it is given.                                                                                                                                           |
+| ✅      | Domains                         | Domains bind clients to providers in the OpenFeature SDK; a separate provider instance may be registered per domain.                                                                                                      |
+| ✅      | Eventing                        | LaunchDarkly data source status changes are emitted as `PROVIDER_READY`, `PROVIDER_STALE`, and `PROVIDER_ERROR`. Flag changes are emitted as `PROVIDER_CONFIGURATION_CHANGED` with the changed flag key.                  |
+| ✅      | Initialization                  | `init` reports whether the LaunchDarkly client became ready within the configured wait time; a failure results in the `ERROR` state so that cached or fallback flag data is still evaluated.                              |
+| ✅      | Shutdown                        | `shutdown` closes the LaunchDarkly client. A closed client cannot be restarted, so a new provider instance is required afterward.                                                                                        |
+| ✅      | Tracking                        | `track` sends a LaunchDarkly custom event for the evaluation context, with the tracking event value and remaining details attached.                                                                                       |
+| ✅      | Transaction Context Propagation | Provided by the OpenFeature SDK, which merges the transaction context into the evaluation context before the provider is called; no provider support is required.                                                         |
+| ✅      | Extending                       | This provider is itself an extension of the OpenFeature SDK. The underlying LaunchDarkly client is available through `provider.client` for functionality with no OpenFeature equivalent.                                  |
+| ✅      | Flag metadata                   | LaunchDarkly evaluation reason details are returned as OpenFeature flag metadata. See [Flag Metadata](#flag-metadata).                                                                                                    |
+
+<sub>Supported: ✅ | Partially supported: ⚠️ | Not supported: ❌</sub>
+
 ## Getting started
 
 ### Requisites
@@ -147,6 +168,24 @@ attributes = {
 context = EvaluationContext(**attributes)
 ```
 
+### Flag Metadata
+
+Evaluations include flag metadata for the LaunchDarkly specific parts of the evaluation result which have no OpenFeature equivalent. Each entry is absent when it does not apply to the evaluation.
+
+| Key                 | Type    | Description                                                        |
+|---------------------|---------|--------------------------------------------------------------------|
+| `variationIndex`    | integer | The index of the returned variation. Absent for default values.    |
+| `inExperiment`      | boolean | Present, and `true`, when the evaluation was part of an experiment. |
+| `ruleIndex`         | integer | The index of the rule that matched.                                |
+| `ruleId`            | string  | The identifier of the rule that matched.                           |
+| `prerequisiteKey`   | string  | The key of the prerequisite flag that failed.                       |
+| `bigSegmentsStatus` | string  | The status of the Big Segments query made during the evaluation.   |
+
+```ruby
+details = client.fetch_boolean_details(flag_key: "my-flag", default_value: false)
+in_experiment = details.flag_metadata.fetch("inExperiment", false)
+```
+
 ## Learn more
 
 Check out our [documentation](http://docs.launchdarkly.com) for in-depth instructions on configuring and using LaunchDarkly. You can also head straight to the [complete reference guide for this SDK](https://docs.launchdarkly.com/sdk/server-side/ruby).

data/SECURITY.md

@@ -1,5 +1,8 @@
 # Reporting and Fixing Security Issues
 
-Please report all security issues to the LaunchDarkly security team by submitting a bug bounty report to our [HackerOne program](https://hackerone.com/launchdarkly?type=team). LaunchDarkly will triage and address all valid security issues following the response targets defined in our program policy. Valid security issues may be eligible for a bounty.
+**Do not open Issues or Pull Requests for security issues.**  
+This will make potential issues publicly visible before LaunchDarkly's Security Team can address them, which could lead to a compromise of the platform and negatively impact our customers. 
 
-Please do not open issues or pull requests for security issues. This makes the problem immediately visible to everyone, including potentially malicious actors.
+Security issues must be reported through our [Bug Bounty program](https://bugcrowd.com/engagements/launchdarkly-mbb-og), following the program policy, for triage and remediation by the LaunchDarkly Security Team. Valid security issues may be eligible for a bounty.
+
+Please do not attempt to directly contact members of LaunchDarkly staff.

data/launchdarkly-openfeature-server-sdk.gemspec

@@ -28,8 +28,8 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "launchdarkly-server-sdk", "~> 8.4"
-  spec.add_runtime_dependency "openfeature-sdk", "~> 0.6.0"
+  spec.add_runtime_dependency "launchdarkly-server-sdk", "~> 8.15"
+  spec.add_runtime_dependency "openfeature-sdk", "~> 0.6.1"
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html

data/lib/ldclient-openfeature/impl/details_converter.rb

@@ -7,6 +7,16 @@ module LaunchDarkly
   module OpenFeature
     module Impl
       class ResolutionDetailsConverter
+        VARIATION_INDEX_KEY = 'variationIndex'
+        IN_EXPERIMENT_KEY = 'inExperiment'
+        RULE_INDEX_KEY = 'ruleIndex'
+        RULE_ID_KEY = 'ruleId'
+        PREREQUISITE_KEY_KEY = 'prerequisiteKey'
+        BIG_SEGMENTS_STATUS_KEY = 'bigSegmentsStatus'
+
+        private_constant :VARIATION_INDEX_KEY, :IN_EXPERIMENT_KEY, :RULE_INDEX_KEY, :RULE_ID_KEY,
+          :PREREQUISITE_KEY_KEY, :BIG_SEGMENTS_STATUS_KEY
+
         #
         # @param detail [LaunchDarkly::EvaluationDetail]
         #
@@ -35,10 +45,30 @@ module LaunchDarkly
             error_code: openfeature_error_code,
             error_message: nil,
             reason: openfeature_reason,
-            variant: openfeature_variant
+            variant: openfeature_variant,
+            flag_metadata: flag_metadata(reason, is_default ? nil : variation_index)
           )
         end
 
+        #
+        # @param reason [LaunchDarkly::EvaluationReason]
+        # @param variation_index [Integer, nil]
+        #
+        # @return [Hash]
+        #
+        private def flag_metadata(reason, variation_index)
+          metadata = {}
+
+          metadata[VARIATION_INDEX_KEY] = variation_index unless variation_index.nil?
+          metadata[IN_EXPERIMENT_KEY] = true if reason.in_experiment
+          metadata[RULE_INDEX_KEY] = reason.rule_index unless reason.rule_index.nil?
+          metadata[RULE_ID_KEY] = reason.rule_id unless reason.rule_id.nil?
+          metadata[PREREQUISITE_KEY_KEY] = reason.prerequisite_key unless reason.prerequisite_key.nil?
+          metadata[BIG_SEGMENTS_STATUS_KEY] = reason.big_segments_status.to_s unless reason.big_segments_status.nil?
+
+          metadata
+        end
+
         #
         # @param kind [Symbol]
         #

data/lib/ldclient-openfeature/impl/event_listeners.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'ldclient-rb'
+require 'open_feature/sdk'
+
+module LaunchDarkly
+  module OpenFeature
+    module Impl
+      #
+      # Translates LaunchDarkly data source status changes into OpenFeature provider events.
+      #
+      class DataSourceStatusListener
+        #
+        # @param provider [LaunchDarkly::OpenFeature::Provider]
+        #
+        def initialize(provider)
+          @provider = provider
+        end
+
+        #
+        # @param status [LaunchDarkly::Interfaces::DataSource::Status]
+        #
+        # @return [void]
+        #
+        def update(status)
+          case status.state
+          when ::LaunchDarkly::Interfaces::DataSource::Status::VALID
+            @provider.emit_event(::OpenFeature::SDK::ProviderEvent::PROVIDER_READY)
+          when ::LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED
+            @provider.emit_event(
+              ::OpenFeature::SDK::ProviderEvent::PROVIDER_STALE,
+              message: message(status, "the data source has been interrupted")
+            )
+          when ::LaunchDarkly::Interfaces::DataSource::Status::OFF
+            @provider.emit_event(
+              ::OpenFeature::SDK::ProviderEvent::PROVIDER_ERROR,
+              error_code: ::OpenFeature::SDK::Provider::ErrorCode::GENERAL,
+              message: message(status, "the data source has been permanently shut down")
+            )
+          end
+        end
+
+        #
+        # @param status [LaunchDarkly::Interfaces::DataSource::Status]
+        # @param fallback [String]
+        #
+        # @return [String]
+        #
+        private def message(status, fallback)
+          error = status.last_error
+          return fallback if error.nil?
+
+          "#{fallback}: #{error.kind} #{error.status_code} #{error.message}".strip
+        end
+      end
+
+      #
+      # Translates LaunchDarkly flag change events into OpenFeature configuration changed events.
+      #
+      class FlagChangeListener
+        #
+        # @param provider [LaunchDarkly::OpenFeature::Provider]
+        #
+        def initialize(provider)
+          @provider = provider
+        end
+
+        #
+        # @param flag_change [LaunchDarkly::Interfaces::FlagChange]
+        #
+        # @return [void]
+        #
+        def update(flag_change)
+          @provider.emit_event(
+            ::OpenFeature::SDK::ProviderEvent::PROVIDER_CONFIGURATION_CHANGED,
+            flags_changed: [flag_change.key]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ldclient-openfeature/provider.rb

@@ -6,6 +6,8 @@ require 'open_feature/sdk'
 module LaunchDarkly
   module OpenFeature
     class Provider
+      include ::OpenFeature::SDK::Provider::EventEmitter
+
       #
       # Retrieve metadata information describing this provider.
       #
@@ -25,18 +27,50 @@ module LaunchDarkly
       NUMERIC_TYPES = %i[integer float number].freeze
       private_constant :NUMERIC_TYPES
 
+      WRAPPER_NAME = "open-feature-ruby-server"
+      private_constant :WRAPPER_NAME
+
       #
       # @param sdk_key [String]
       # @param config [LaunchDarkly::Config]
       # @param wait_for_seconds [Float]
       #
       def initialize(sdk_key, config = LaunchDarkly::Config.default, wait_for_seconds = 5)
-        @client = LaunchDarkly::LDClient.new(sdk_key, config, wait_for_seconds)
+        @client = LaunchDarkly::LDClient.new(sdk_key, config.with_wrapper_information(WRAPPER_NAME, VERSION), wait_for_seconds)
 
+        @logger = config.logger
         @context_converter = Impl::EvaluationContextConverter.new(config.logger)
         @details_converter = Impl::ResolutionDetailsConverter.new
 
         @metadata = ::OpenFeature::SDK::Provider::ProviderMetadata.new(name: "launchdarkly-openfeature-server").freeze
+
+        @client.data_source_status_provider.add_listener(Impl::DataSourceStatusListener.new(self))
+        @client.flag_tracker.add_listener(Impl::FlagChangeListener.new(self))
+      end
+
+      #
+      # Called by the OpenFeature SDK when this provider is set. The LaunchDarkly client has already been given the
+      # opportunity to initialize, so this only reports whether that succeeded.
+      #
+      # @param _evaluation_context [::OpenFeature::SDK::EvaluationContext, nil]
+      #
+      # @return [void]
+      #
+      def init(_evaluation_context = nil)
+        return if @client.initialized?
+
+        state = @client.data_source_status_provider.status.state
+        raise "the LaunchDarkly client was unable to initialize; the data source state is #{state}"
+      end
+
+      #
+      # Called by the OpenFeature SDK when this provider is replaced or the SDK is shut down. The LaunchDarkly client
+      # cannot be restarted, so a new provider instance is required afterward.
+      #
+      # @return [void]
+      #
+      def shutdown
+        @client.close
       end
 
       def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)
@@ -63,6 +97,32 @@ module LaunchDarkly
         resolve_value(:object, flag_key, default_value, evaluation_context)
       end
 
+      #
+      # Track a custom event, which can be used as a metric for an experiment.
+      #
+      # @param tracking_event_name [String]
+      # @param evaluation_context [::OpenFeature::SDK::EvaluationContext, nil]
+      # @param tracking_event_details [::OpenFeature::SDK::TrackingEventDetails, nil]
+      #
+      # @return [void]
+      #
+      def track(tracking_event_name, evaluation_context: nil, tracking_event_details: nil)
+        if evaluation_context.nil?
+          @logger.warn(
+            "The track method was called without an evaluation context. No event will be sent to LaunchDarkly, " \
+            "because a context is required to associate the event with."
+          )
+          return
+        end
+
+        ld_context = @context_converter.to_ld_context(evaluation_context)
+
+        data = tracking_event_details&.fields
+        data = nil if data.nil? || data.empty?
+
+        @client.track(tracking_event_name, ld_context, data, tracking_event_details&.value)
+      end
+
       #
       # @param flag_type [Symbol]
       # @param flag_key [String]

data/lib/ldclient-openfeature/version.rb

@@ -2,6 +2,6 @@
 
 module LaunchDarkly
   module OpenFeature
-    VERSION = "0.2.0" # x-release-please-version
+    VERSION = "0.3.0" # x-release-please-version
   end
 end

data/lib/ldclient-openfeature.rb

@@ -2,6 +2,7 @@
 
 require_relative "ldclient-openfeature/impl/context_converter"
 require_relative "ldclient-openfeature/impl/details_converter"
+require_relative "ldclient-openfeature/impl/event_listeners"
 require_relative "ldclient-openfeature/provider"
 require_relative "ldclient-openfeature/version"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: launchdarkly-openfeature-server-sdk
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - LaunchDarkly
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '8.4'
+        version: '8.15'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '8.4'
+        version: '8.15'
 - !ruby/object:Gem::Dependency
   name: openfeature-sdk
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.6.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.6.1
 description: A LaunchDarkly provider for use with the OpenFeature SDK
 email:
 - team@launchdarkly.com
@@ -63,6 +63,7 @@ files:
 - lib/ldclient-openfeature/impl.rb
 - lib/ldclient-openfeature/impl/context_converter.rb
 - lib/ldclient-openfeature/impl/details_converter.rb
+- lib/ldclient-openfeature/impl/event_listeners.rb
 - lib/ldclient-openfeature/provider.rb
 - lib/ldclient-openfeature/version.rb
 - release-please-config.json