featureflip-openfeature 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f6fa5f7d072f5f820620ac950eda71f01af344681916c8fd152229a881a0f142
+  data.tar.gz: bc9efccb44950cc991d5aabf9594f245075fb205ecc3a0c48f8ba34de2198f87
+SHA512:
+  metadata.gz: 7dda6c5cf1cb568b1632b8d8d4fe4af625ccf917236cb0f3ce4cdd4040c01f6ea5ebf07d0670d6ce8170484429eeb3984176cfdab6d701f66f6c9e5a97ae9e83
+  data.tar.gz: 754d476ea0e98b5421f21b4e786ce10efaf2acf8664dfce812fdb849e8811e6e593f04d198ebe6758a19ae2ff688b3bc140fe01316988b5ffd0bf66a18576532

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 — 2026-10-10
+
+### Added
+
+- First release of the OpenFeature provider for Ruby, backed by the `featureflip` gem. Resolves boolean, string, number, integer, float and object flags through the standard `openfeature-sdk` client, maps Featureflip reasons onto OpenFeature's (an unmet prerequisite surfaces as `PREREQUISITE_FAILED`), exposes `ruleId` and `prerequisiteKey` as flag metadata, writes the targeting key under both `user_id` and `userId`, and emits `PROVIDER_CONFIGURATION_CHANGED` with the changed flag keys. Needs `featureflip` 2.10 or newer. (#3643)

data/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Canopy Labs LLC
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,66 @@
+# Featureflip OpenFeature provider for Ruby
+
+Use [Featureflip](https://featureflip.io) feature flags through the
+[OpenFeature](https://openfeature.dev) Ruby SDK.
+
+## Install
+
+```ruby
+# Gemfile
+gem "featureflip-openfeature"
+```
+
+## Use
+
+```ruby
+require "featureflip-openfeature"
+
+OpenFeature::SDK.set_provider_and_wait(
+  Featureflip::OpenFeature::Provider.new(sdk_key: ENV.fetch("FEATUREFLIP_SDK_KEY"))
+)
+
+client = OpenFeature::SDK.build_client
+enabled = client.fetch_boolean_value(
+  flag_key: "new-checkout",
+  default_value: false,
+  evaluation_context: OpenFeature::SDK::EvaluationContext.new(targeting_key: "user-42", plan: "pro")
+)
+```
+
+Use `set_provider_and_wait`. Plain `set_provider` initializes in the background
+and returns before flags load, so the next read gets your default.
+
+Already using the Featureflip client directly? Pass it in and the provider will
+share it, leaving ownership with you:
+
+```ruby
+client = Featureflip::Client.get("sdk-...")
+OpenFeature::SDK.set_provider_and_wait(Featureflip::OpenFeature::Provider.new(client: client))
+```
+
+## Behavior
+
+- `targeting_key` is written under both `user_id` and `userId`, so a targeting
+  rule on either spelling matches. An explicit attribute of either spelling wins.
+- `Time`, `Date` and `DateTime` attributes become ISO-8601 strings.
+- `fetch_integer_value` accepts whole-number floats (`3.0` returns `3`).
+  `fetch_float_value` accepts integers (`5` returns `5.0`).
+  `fetch_object_value` accepts hashes and arrays only.
+- An unmet prerequisite resolves with reason `PREREQUISITE_FAILED`. `ruleId` and
+  `prerequisiteKey` are in `flag_metadata`.
+- `PROVIDER_CONFIGURATION_CHANGED` fires with `flags_changed` whenever flag
+  configuration changes after startup. The initial load does not fire it.
+
+## Forking servers
+
+On Puma with `preload_app!`, Unicorn or Passenger, register the provider in the
+post-fork hook (`on_worker_boot` or `after_fork`). A provider built before the
+fork leaves each worker with dead polling and streaming threads, so it serves
+the boot snapshot and never emits `PROVIDER_CONFIGURATION_CHANGED`. If you pass
+your own `client:`, call `client.restart` in that hook instead.
+
+Full documentation: https://featureflip.io/docs/integrations/openfeature/#ruby
+
+## License
+
+Apache-2.0

data/lib/featureflip/open_feature/context_mapping.rb

@@ -0,0 +1,47 @@
+require "date"
+require "time"
+
+module Featureflip
+  module OpenFeature
+    # OpenFeature evaluation context -> the Featureflip SDK's context hash.
+    module ContextMapping
+      TARGETING_KEY = "targeting_key"
+      IDENTITY_KEYS = %w[user_id userId].freeze
+
+      module_function
+
+      def to_featureflip(evaluation_context)
+        return {} if evaluation_context.nil?
+
+        fields = evaluation_context.fields
+        # The reserved key is OpenFeature's, not an attribute: leaking it into
+        # the bag is a recorded .NET-provider bug.
+        context = fields.each_with_object({}) do |(key, value), out|
+          out[key] = render(value) unless key == TARGETING_KEY
+        end
+
+        targeting_key = fields[TARGETING_KEY]
+        blank = targeting_key.nil? || (targeting_key.respond_to?(:empty?) && targeting_key.empty?)
+        # BOTH spellings, because the Ruby SDK's condition evaluator reads
+        # context[attribute] exactly; the userId/user_id alias exists only on
+        # the bucketing path. A rule on either spelling must match. An explicit
+        # attribute of either spelling wins and nothing is overwritten.
+        if !blank && IDENTITY_KEYS.none? { |k| context.key?(k) }
+          IDENTITY_KEYS.each { |k| context[k] = targeting_key }
+        end
+        context
+      end
+
+      # Every SDK gates its date operators on the ISO grammar, so a Time left as
+      # an object would match no date rule at all.
+      def render(value)
+        case value
+        when Time, Date then value.iso8601 # DateTime < Date, so it lands here too
+        when Hash then value.transform_values { |v| render(v) }
+        when Array then value.map { |v| render(v) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/featureflip/open_feature/provider.rb

@@ -0,0 +1,199 @@
+module Featureflip
+  module OpenFeature
+    # OpenFeature server provider backed by the Featureflip Ruby SDK.
+    #
+    #   ::OpenFeature::SDK.set_provider_and_wait(
+    #     Featureflip::OpenFeature::Provider.new(sdk_key: "sdk-...")
+    #   )
+    #
+    # Prefer set_provider_and_wait: plain set_provider initializes on a
+    # background thread and returns before flags load.
+    class Provider
+      include ::OpenFeature::SDK::Provider::EventEmitter
+
+      NAME = "featureflip-ruby"
+
+      attr_reader :metadata
+
+      # Pass exactly one of:
+      # - sdk_key: (with an optional Featureflip::Config). The provider builds the
+      #   client in #init and closes it in #shutdown.
+      # - client: an existing Featureflip::Client. The caller keeps ownership;
+      #   #shutdown never closes it.
+      def initialize(sdk_key: nil, config: nil, client: nil)
+        raise ArgumentError, "pass exactly one of sdk_key: or client:" if sdk_key.nil? == client.nil?
+        raise ArgumentError, "config: applies only with sdk_key:" if client && config
+
+        @metadata = ::OpenFeature::SDK::Provider::ProviderMetadata.new(name: NAME).freeze
+        @sdk_key = sdk_key
+        @config = config
+        @client = client
+        @owns_client = client.nil?
+        # Held across #init's blocking Client.get, so nothing on the SDK's update
+        # thread may ever wait on it.
+        @lifecycle_mutex = Mutex.new
+        @unsubscribe = nil
+        # Guards the fields below. Held only for a few assignments and never while
+        # an app handler runs, because emit_event calls handlers inline.
+        @state_mutex = Mutex.new
+        @events_drained = ConditionVariable.new
+        @shut_down = false
+        # Bumped by #shutdown. A listener only emits for the generation it was
+        # subscribed under, so a dispatch the SDK snapshotted before an
+        # unsubscribe can never surface on a later subscription.
+        @generation = 0
+        @emitting = Hash.new(0) # thread => events it is delivering right now
+      end
+
+      # Builds the owned client here rather than in #new because Client.get blocks
+      # on the first flag fetch, and that wait belongs inside
+      # set_provider_and_wait. It is bounded by config.init_timeout and raises
+      # Featureflip::InitializationError, which OpenFeature reports as
+      # PROVIDER_ERROR. The evaluation context is unused: this is a
+      # dynamic-context (server) provider.
+      def init(_evaluation_context = nil)
+        @lifecycle_mutex.synchronize do
+          # Plain set_provider runs #init on a background thread, so replacing the
+          # provider at once can run #shutdown first. Building a client now would
+          # leave one nothing ever closes. Setting the provider again re-arms it
+          # (see #attach).
+          generation = @state_mutex.synchronize { @shut_down ? nil : @generation }
+          return nil if generation.nil?
+
+          @client ||= Featureflip::Client.get(@sdk_key, config: @config)
+          # Subscribed after the client is ready, so the initial load is never a
+          # "change" (OpenFeature signals it with PROVIDER_READY). Guarded because
+          # OpenFeature may initialize a provider more than once. The listener can
+          # fire before on_update returns; it checks the generation, not
+          # @unsubscribe, so that change is still delivered.
+          @unsubscribe ||= @client.on_update(->(keys) { on_flags_changed(keys, generation) })
+        end
+        nil
+      end
+
+      def shutdown
+        @lifecycle_mutex.synchronize do
+          @state_mutex.synchronize do
+            @shut_down = true
+            @generation += 1
+          end
+          # Always unsubscribe: the listener publishes on this provider's event
+          # channel and must not outlive it, even on a borrowed client.
+          @unsubscribe&.call
+          @unsubscribe = nil
+          # A borrowed client is a refcounted handle the caller still holds;
+          # closing it would make THEIR handle start serving defaults.
+          if @owns_client && @client
+            @client.close
+            @client = nil
+          end
+        end
+        # Outside the lifecycle mutex: a handler still running may itself call
+        # into this provider.
+        wait_for_events_in_flight
+        nil
+      end
+
+      def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve(:boolean, flag_key, default_value, evaluation_context)
+      end
+
+      def fetch_string_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve(:string, flag_key, default_value, evaluation_context)
+      end
+
+      def fetch_number_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve(:number, flag_key, default_value, evaluation_context)
+      end
+
+      def fetch_integer_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve(:integer, flag_key, default_value, evaluation_context)
+      end
+
+      def fetch_float_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve(:float, flag_key, default_value, evaluation_context)
+      end
+
+      def fetch_object_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve(:object, flag_key, default_value, evaluation_context)
+      end
+
+      # Called by openfeature-sdk 0.6.1+; 0.5 has no tracking API and never calls it.
+      def track(tracking_event_name, evaluation_context: nil, tracking_event_details: nil)
+        client = @client
+        return if client.nil?
+
+        metadata = nil
+        if tracking_event_details
+          metadata = tracking_event_details.fields.dup
+          metadata["value"] = tracking_event_details.value unless tracking_event_details.value.nil?
+        end
+        client.track(tracking_event_name, ContextMapping.to_featureflip(evaluation_context), metadata)
+      end
+
+      private
+
+      # Reads UNTYPED via variation_detail and applies the type guard here. The
+      # SDK's typed accessors report a wrong-typed value as reason "Error", the
+      # same reason a real failure carries, so TYPE_MISMATCH could not be told
+      # apart from GENERAL through them.
+      def resolve(type, flag_key, default_value, evaluation_context)
+        client = @client
+        if client.nil?
+          return ResolutionMapping.error(default_value, ::OpenFeature::SDK::Provider::ErrorCode::PROVIDER_NOT_READY,
+                                         "Featureflip provider has not been initialized")
+        end
+
+        detail = client.variation_detail(flag_key, ContextMapping.to_featureflip(evaluation_context), default_value)
+        ResolutionMapping.to_resolution(flag_key, detail, default_value, type)
+      rescue StandardError => e
+        # The SDK rescues its own evaluation errors; this only catches a mapping
+        # defect, which must still serve the caller's default.
+        ResolutionMapping.error(default_value, ::OpenFeature::SDK::Provider::ErrorCode::GENERAL, e.message)
+      end
+
+      # OpenFeature attaches a provider every time it is set, always before the
+      # #init that follows, so this is the one signal that a later #init is
+      # legitimate rather than a stale one that lost the race to #shutdown.
+      # Overrides the private EventEmitter#attach, which 0.5 and 0.6 both call.
+      def attach(configuration)
+        @state_mutex.synchronize { @shut_down = false }
+        super
+      end
+
+      # Runs on the SDK's streaming/polling thread. Needs no rescue: Client#on_update
+      # isolates and logs a raising listener.
+      #
+      # openfeature-sdk (0.5 and 0.6) never detaches a replaced provider, so an
+      # event emitted after #shutdown would still reach every API-level handler.
+      # The generation check and the in-flight count are taken together under
+      # @state_mutex, and #shutdown bumps the generation under the same lock and
+      # then waits for the count to drain: once #shutdown returns, no event from
+      # this provider is being delivered and none can start.
+      def on_flags_changed(keys, generation)
+        @state_mutex.synchronize do
+          return unless generation == @generation
+
+          @emitting[Thread.current] += 1
+        end
+        begin
+          emit_event(::OpenFeature::SDK::ProviderEvent::PROVIDER_CONFIGURATION_CHANGED, flags_changed: keys)
+        ensure
+          @state_mutex.synchronize do
+            @emitting.delete(Thread.current) if (@emitting[Thread.current] -= 1).zero?
+            @events_drained.broadcast
+          end
+        end
+      end
+
+      def wait_for_events_in_flight
+        @state_mutex.synchronize do
+          # A handler that shuts this provider down runs on the delivering thread.
+          # Waiting for its own event would never return, so only other threads'
+          # deliveries are waited out.
+          @events_drained.wait(@state_mutex) while @emitting.any? { |thread, _| !thread.equal?(Thread.current) }
+        end
+      end
+    end
+  end
+end

data/lib/featureflip/open_feature/resolution_mapping.rb

@@ -0,0 +1,103 @@
+module Featureflip
+  module OpenFeature
+    # Featureflip EvaluationDetail -> OpenFeature ResolutionDetails.
+    module ResolutionMapping
+      ResolutionDetails = ::OpenFeature::SDK::Provider::ResolutionDetails
+      Reason = ::OpenFeature::SDK::Provider::Reason
+      ErrorCode = ::OpenFeature::SDK::Provider::ErrorCode
+
+      # No standard OpenFeature reason models an unmet prerequisite, and reasons
+      # are open strings, so it is passed through rather than mislabeled DEFAULT
+      # or DISABLED. Same choice as every other Featureflip provider.
+      PREREQUISITE_FAILED = "PREREQUISITE_FAILED"
+
+      REASONS = {
+        "RuleMatch" => Reason::TARGETING_MATCH,
+        "Fallthrough" => Reason::DEFAULT,
+        "FlagDisabled" => Reason::DISABLED,
+        "PrerequisiteFailed" => PREREQUISITE_FAILED
+      }.freeze
+
+      ERROR_CODES = {
+        "FlagNotFound" => ErrorCode::FLAG_NOT_FOUND,
+        "Error" => ErrorCode::GENERAL
+      }.freeze
+
+      ERROR_MESSAGES = {
+        "FlagNotFound" => "Flag '%s' was not found",
+        "Error" => "Flag '%s' could not be evaluated"
+      }.freeze
+
+      # A double represents every integer exactly only up to 2**53. Beyond it a
+      # whole-looking float may be a rounded neighbor of the number that was
+      # meant, so it is refused rather than handed back silently rounded.
+      MAX_EXACT_INTEGER = 2**53
+
+      MISMATCH = Object.new.freeze
+      private_constant :MISMATCH
+
+      module_function
+
+      def to_resolution(flag_key, detail, default_value, type)
+        error_code = ERROR_CODES[detail.reason]
+        if error_code
+          # The caller's default, never detail.value: an error detail can carry a
+          # wrong-typed off variation (a failed prerequisite chain), which is not
+          # what the OpenFeature error contract prescribes. The type guard is
+          # skipped for the same reason; it would mislabel the error.
+          return error(default_value, error_code, format(ERROR_MESSAGES.fetch(detail.reason), flag_key))
+        end
+
+        value = coerce(detail.value, type)
+        if value.equal?(MISMATCH)
+          return error(default_value, ErrorCode::TYPE_MISMATCH,
+                       "Flag '#{flag_key}' did not resolve to #{article(type)} #{type} value")
+        end
+
+        ResolutionDetails.new(
+          value: value,
+          reason: REASONS.fetch(detail.reason, Reason::UNKNOWN),
+          variant: detail.variation_key,
+          flag_metadata: metadata(detail)
+        )
+      end
+
+      def error(default_value, error_code, message)
+        ResolutionDetails.new(value: default_value, reason: Reason::ERROR,
+                              error_code: error_code, error_message: message)
+      end
+
+      def article(type)
+        type.to_s.match?(/\A[aeiou]/i) ? "an" : "a"
+      end
+
+      def metadata(detail)
+        { "ruleId" => detail.rule_id, "prerequisiteKey" => detail.prerequisite_key }.compact
+      end
+
+      def coerce(value, type)
+        case type
+        when :boolean then value == true || value == false ? value : MISMATCH
+        when :string then value.is_a?(String) ? value : MISMATCH
+        when :number then value.is_a?(Numeric) ? value : MISMATCH
+        when :integer then to_integer(value)
+        # The OpenFeature client checks is_a?(Float) strictly, so an integral
+        # flag value must be widened here or the client reports a mismatch.
+        when :float then value.is_a?(Integer) ? value.to_f : (value.is_a?(Float) ? value : MISMATCH)
+        when :object then value.is_a?(Hash) || value.is_a?(Array) ? value : MISMATCH
+        else raise ArgumentError, "unknown OpenFeature type #{type.inspect}"
+        end
+      end
+
+      # JSON does not distinguish 1 from 1.0, and the engine renders whole floats
+      # with a decimal part, so a whole Float is an integer here and is narrowed.
+      def to_integer(value)
+        return value if value.is_a?(Integer)
+        return MISMATCH unless value.is_a?(Float) && value.finite? && value == value.truncate
+        return MISMATCH if value.abs > MAX_EXACT_INTEGER
+
+        value.to_i
+      end
+    end
+  end
+end

data/lib/featureflip/open_feature/version.rb

@@ -0,0 +1,7 @@
+module Featureflip
+  module OpenFeature
+    # Rewritten from the release tag at publish time; the committed value is
+    # convention, the tag is what ships.
+    VERSION = "0.1.0"
+  end
+end

data/lib/featureflip-openfeature.rb

@@ -0,0 +1,7 @@
+require "featureflip"
+require "open_feature/sdk"
+
+require_relative "featureflip/open_feature/version"
+require_relative "featureflip/open_feature/context_mapping"
+require_relative "featureflip/open_feature/resolution_mapping"
+require_relative "featureflip/open_feature/provider"

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: featureflip-openfeature
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Featureflip
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: featureflip
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.10'
+- !ruby/object:Gem::Dependency
+  name: openfeature-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: Use Featureflip feature flags through the OpenFeature Ruby SDK.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/featureflip-openfeature.rb
+- lib/featureflip/open_feature/context_mapping.rb
+- lib/featureflip/open_feature/provider.rb
+- lib/featureflip/open_feature/resolution_mapping.rb
+- lib/featureflip/open_feature/version.rb
+homepage: https://featureflip.io/docs/integrations/openfeature/
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://featureflip.io/docs/integrations/openfeature/
+  documentation_uri: https://featureflip.io/docs/integrations/openfeature/
+  source_code_uri: https://github.com/canopy-labs/featureflip-ruby-openfeature
+  changelog_uri: https://github.com/canopy-labs/featureflip-ruby-openfeature/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: OpenFeature provider for Featureflip
+test_files: []