confidence-openfeature-provider 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b46228f63cda87c4039d870081cc365282e6818dc0c0322e77b18b18d1c4090
-  data.tar.gz: f18bdde4e4edbb3bae92511c240f4ae814913c118bf95330a7303a32c0e6730a
+  metadata.gz: 375cd3b343a316624712b6c7415665754bd356618435d9d7f455f42ac8bd797b
+  data.tar.gz: 3de4965a6f56a01da59102593b5f1bf88a71fb2e2da887391bdc39366a67c497
 SHA512:
-  metadata.gz: 951566d958ebe7c8064f725663e1df91db83923afe23669ea6c5d3220e17158c49d47dabc9b8a6929700265eaa7519ef3674a2138e665c99600f449ecb5b060e
-  data.tar.gz: f75e880c2fe2c0d36337de730879ef67f0490bf66ec89c270144c1a690bf52d515cffe286fd2c50955515fedbda9c359380446f3d407132aeafb16efe3ebe655
+  metadata.gz: fb95289e73c34bbce61de2e8c88ea61e688001bcddbcadc3bffec3d22daba866e22a3a2e21eecd9c26d04e28a1bc13037c80ec704a5a427144d11e733c4f3047
+  data.tar.gz: 03d0d7e9d6cdb1121ec77254d915a4215bc198f79283eb73ef74176a065d8ea7ea72d51884fb0b8b0b97d657a7171a4f39aac68579a437e68a2ed0295a925f0f

data/lib/confidence/openfeature/api_client.rb

@@ -6,6 +6,8 @@ require "json"
 require "uri"
 require "net/http"
 require "net/https"
+# Time.iso8601, used to coerce a String event_time.
+require "time"
 
 module Confidence
   module OpenFeature
@@ -20,12 +22,15 @@ module Confidence
       US = new("https://resolver.us.confidence.dev/v1")
     end
 
+    # The events API is a single global endpoint, unlike the regional
+    # resolver hosts above.
+    EVENTS_URI = "https://events.confidence.dev/v1"
+
     class APIClient
-      def initialize(client_secret:, region: Region::EU)
-        uri = URI.parse(region.uri)
+      def initialize(client_secret:, region: Region::EU, events_uri: EVENTS_URI)
         @client_secret = client_secret
-        @agent = Net::HTTP.new(uri.host, uri.port)
-        @agent.use_ssl = uri.scheme == "https"
+        @uri = URI.parse(region.uri)
+        @events_uri = URI.parse(events_uri)
       end
 
       def resolve_one(flag:, context: {}, apply: true)
@@ -40,6 +45,41 @@ module Confidence
         result
       end
 
+      # Publishes a single event to the Confidence events API.
+      #
+      # +event_name+ is the event definition id, sent as
+      # "eventDefinitions/#{event_name}". +payload+ is an arbitrary hash.
+      # +event_time+ defaults to now; pass it to backdate an event.
+      #
+      # Returns nil on success. Raises APIError if the request itself fails
+      # and EventPublishError if the batch is accepted but the event is
+      # refused, so rejections are never silently discarded.
+      def track(event_name:, payload: {}, event_time: nil)
+        now = Time.now
+        result = post_json("/v1/events:publish", {
+          clientSecret: @client_secret,
+          sendTime: rfc3339(now),
+          sdk: {id: "SDK_ID_RUBY_PROVIDER", version: VERSION},
+          events: [{
+            eventDefinition: "eventDefinitions/#{event_name}",
+            eventTime: rfc3339(event_time || now),
+            payload: payload || {}
+          }]
+        }, uri: @events_uri, label: "events:publish")
+
+        rejections = (result["errors"] || []).map do |error|
+          Rejection.new(error["index"], error["reason"], error["message"])
+        end
+        unless rejections.empty?
+          raise EventPublishError.new(
+            "events:publish refused #{rejections.length} event(s): " +
+              rejections.map { |r| "[#{r.index}] #{r.reason} #{r.message}".strip }.join(", "),
+            rejections
+          )
+        end
+        nil
+      end
+
       def resolve(flags: [], context: {}, apply: true)
         result = post_json("/v1/flags:resolve", {
           clientSecret: @client_secret,
@@ -47,7 +87,7 @@ module Confidence
           apply: apply,
           flags: flags,
           sdk: {id: "SDK_ID_RUBY_PROVIDER", version: VERSION}
-        })
+        }, uri: @uri, label: "flags:resolve")
 
         resolved_flags = result["resolvedFlags"] || []
         resolved_flags.map do |flag|
@@ -61,21 +101,79 @@ module Confidence
 
       private
 
-      def post_json(path, body)
+      # A fresh Net::HTTP per request, because one instance cannot be shared
+      # across threads. Net::HTTP#request auto-starts the connection when the
+      # receiver is not already started, mutating its @started and @socket:
+      #
+      #   unless started?
+      #     start { req['connection'] ||= 'close'; return request(req, ...) }
+      #   end
+      #
+      # Two threads entering that on the same object both open a connection and
+      # both assign @socket, so one clobbers the other and the loser reads or
+      # writes a socket the winner may already have closed.
+      #
+      # Per-request instantiation costs nothing here: the instance was never
+      # explicitly started, so every request already opened a connection, sent
+      # "Connection: close" and closed it again. There was no reuse to lose.
+      # Takes a URI so an additional endpoint can share it.
+      def build_agent(uri)
+        agent = Net::HTTP.new(uri.host, uri.port)
+        agent.use_ssl = uri.scheme == "https"
+        agent
+      end
+
+      # getutc rather than utc: the latter mutates its receiver, which would
+      # convert a caller-supplied event_time to UTC in place.
+      #
+      # Accepts a String as well as a Time. Spec 6.2.2 permits string custom
+      # fields, and an "event_time" entry in tracking event details is the only
+      # route to set the event time through the spec-conformant +track+, so a
+      # caller passing an ISO-8601 string is expected rather than exceptional.
+      # An unparseable value raises TypeMismatchError rather than falling back
+      # to "now": a silently wrong timestamp is harder to diagnose than a
+      # logged failure, and +track+ turns the raise into a warning.
+      def rfc3339(time)
+        coerce_time(time).getutc.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+      end
+
+      def coerce_time(time)
+        return time if time.is_a?(Time)
+
+        if time.is_a?(String)
+          begin
+            return Time.iso8601(time)
+          rescue ArgumentError => ex
+            raise TypeMismatchError.new(
+              "event_time #{time.inspect} is not a valid ISO-8601 timestamp: #{ex.message}"
+            )
+          end
+        end
+
+        raise TypeMismatchError.new(
+          "event_time must be a Time or an ISO-8601 String, got #{time.class}"
+        )
+      end
+
+      # Takes the target URI rather than a prepared agent so that every request
+      # still builds its own, per build_agent above. +label+ names the endpoint
+      # in errors; both callers pass it explicitly, which keeps "which host does
+      # this go to" a decision at the call site.
+      def post_json(path, body, uri:, label:)
         headers = {"Content-Type" => "application/json"}
         request = Net::HTTP::Post.new(path, headers)
         request.body = JSON.dump(body)
-        response = @agent.request(request)
+        response = build_agent(uri).request(request)
 
         code = response.code.to_i
         if code != 200
-          raise APIError.new("flags:resolve HTTP #{response.code} #{response.message}")
+          raise APIError.new("#{label} HTTP #{response.code} #{response.message}")
         end
 
         begin
           JSON.parse(response.body)
         rescue JSON::ParserError => ex
-          raise APIError.new("flags:resolve malformed JSON: #{ex}")
+          raise APIError.new("#{label} malformed JSON: #{ex}")
         end
       end
 
@@ -89,6 +187,9 @@ module Confidence
         variant.nil? || value.nil?
       end
     end
+
+    # A single event the events API refused within an accepted batch.
+    Rejection = Struct.new(:index, :reason, :message)
   end
 end
 

data/lib/confidence/openfeature/errors.rb

@@ -13,5 +13,31 @@ module Confidence
 
     class TypeMismatchError < BaseError
     end
+
+    # Raised when tracking event details already carry a "context" key.
+    #
+    # The evaluation context is merged into the event payload under the
+    # reserved "context" key, so a details key of the same name would be
+    # ambiguous. Rejecting it matches the other Confidence SDKs, which raise
+    # rather than silently overwrite one with the other.
+    class InvalidContextInPayloadError < BaseError
+    end
+
+    # Raised when the events API accepts the batch but refuses individual
+    # events. The batch call still returns HTTP 200 in that case, so without
+    # this the rejections would be silently dropped.
+    #
+    # +rejections+ holds one Rejection per refused event, each carrying the
+    # index of the event in the published batch, the reason (for example
+    # EVENT_DEFINITION_NOT_FOUND or EVENT_SCHEMA_VALIDATION_FAILED) and an
+    # optional message.
+    class EventPublishError < BaseError
+      attr_reader :rejections
+
+      def initialize(message, rejections = [])
+        super(message)
+        @rejections = rejections
+      end
+    end
   end
 end

data/lib/confidence/openfeature/provider.rb

@@ -11,9 +11,27 @@ module Confidence
 
       # Error_code and error_message seemingly not used by OpenFeature SDK.
       # Including here for compatibility.
+      #
+      # flag_metadata became part of the contract in openfeature-sdk 0.6.1:
+      # EvaluationDetails delegates it to whatever the provider returns, so
+      # omitting the member raises NoMethodError on the fetch_*_details path.
+      # Defaulting and immutability mirror Provider::ResolutionDetails.
+      EMPTY_FLAG_METADATA = {}.freeze
+
       ResolutionDetails = Struct.new(
-        :value, :reason, :variant, :error_code, :error_message
-      )
+        :value, :reason, :variant, :error_code, :error_message, :flag_metadata
+      ) do
+        def flag_metadata
+          raw = self[:flag_metadata]
+          if raw.nil?
+            EMPTY_FLAG_METADATA
+          elsif raw.frozen?
+            raw
+          else
+            raw.dup.freeze
+          end
+        end
+      end
 
       def initialize(api_client:, apply_on_resolve: true)
         @api_client = api_client
@@ -56,8 +74,96 @@ module Confidence
         )
       end
 
+      # Publishes an event to Confidence.
+      #
+      # Signature matches OpenFeature requirement 6.1.1.1 and the shape the
+      # OpenFeature Ruby SDK client invokes providers with:
+      #
+      #   @provider.track(name, evaluation_context:, tracking_event_details:)
+      #
+      # Returns nothing, and never raises: the SDK client does not rescue, so
+      # an exception here would surface in application code from a
+      # fire-and-forget tracking call. Failures are written to stderr. Use
+      # +track!+ when you want them raised instead.
+      def track(tracking_event_name, evaluation_context: nil, tracking_event_details: nil)
+        track!(
+          tracking_event_name,
+          evaluation_context: evaluation_context,
+          tracking_event_details: tracking_event_details
+        )
+        nil
+      rescue => ex
+        # Bare rescue is StandardError; anything narrower would let a caller
+        # mistake (a non-Hash, say) escape a call that must not raise.
+        warn("Confidence: track(#{tracking_event_name.inspect}) failed: #{ex.message}")
+        nil
+      end
+
+      # Same as +track+ but raises on failure.
+      #
+      # Raises APIError if the request fails, EventPublishError if the batch is
+      # accepted but the event is refused, InvalidContextInPayloadError on a
+      # reserved-key collision and TypeMismatchError if +value+ is not numeric
+      # or +event_time+ is not a valid timestamp.
+      #
+      # +event_time+ backdates the event and accepts a Time or an ISO-8601
+      # String. It can also be supplied as an "event_time" entry in
+      # +tracking_event_details+, which is the only route available through the
+      # spec-conformant +track+; it is removed from the payload rather than
+      # published as a custom field.
+      #
+      # "event_time" is therefore reserved in +tracking_event_details+. A value
+      # that is neither a Time nor a parseable ISO-8601 String raises
+      # TypeMismatchError rather than being published as an ordinary string
+      # field. Failing loudly is deliberate: publishing the event stamped
+      # "now" instead of the intended time, or dropping it silently, is far
+      # harder to diagnose than a logged failure.
+      def track!(tracking_event_name, evaluation_context: nil, tracking_event_details: nil, event_time: nil)
+        details = normalize_details(tracking_event_details)
+        at = details.delete("event_time") || event_time
+
+        @api_client.track(
+          event_name: tracking_event_name,
+          payload: event_payload(details, evaluation_context),
+          event_time: at
+        )
+      end
+
       private
 
+      # Mirrors PayloadMerger in the other Confidence SDKs: the tracking event
+      # details sit at the top level of the payload and the evaluation context
+      # is nested under the reserved "context" key.
+      def event_payload(details, evaluation_context)
+        if details.key?("context")
+          raise InvalidContextInPayloadError.new(
+            'tracking event details may not contain a "context" key; it is ' \
+            "reserved for the evaluation context"
+          )
+        end
+        details.merge("context" => context_hash(evaluation_context))
+      end
+
+      # Requirement 6.2.1: tracking event details define an optional numeric
+      # +value+. Requirement 6.2.2: custom fields keyed by string.
+      def normalize_details(tracking_event_details)
+        return {} if tracking_event_details.nil?
+        unless tracking_event_details.is_a?(Hash)
+          raise TypeMismatchError.new(
+            "tracking event details must be a Hash, got #{tracking_event_details.class}"
+          )
+        end
+
+        details = tracking_event_details.transform_keys(&:to_s)
+        value = details["value"]
+        if !value.nil? && !value.is_a?(Numeric)
+          raise TypeMismatchError.new(
+            "tracking event details 'value' must be numeric, got #{value.class}"
+          )
+        end
+        details
+      end
+
       def evaluate(flag_key:, default_value:, evaluation_context: nil, validator: nil)
         parts = flag_key.split(".")
         flag_id = parts.shift
@@ -104,10 +210,15 @@ module Confidence
 
       def context_hash(evaluation_context)
         return {} if evaluation_context.nil?
+        # Direct callers may pass a plain Hash; the SDK client always passes an
+        # EvaluationContext.
+        return evaluation_context.dup if evaluation_context.is_a?(Hash)
 
         # In SDK 0.4+, EvaluationContext stores all fields in a hash
         # targeting_key is a special field that can be accessed via .targeting_key
-        evaluation_context.fields.dup
+        return evaluation_context.fields.dup if evaluation_context.respond_to?(:fields)
+
+        {}
       end
     end
 

data/lib/confidence/openfeature/version.rb

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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: confidence-openfeature-provider
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
 - Confidence Team
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-18 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: openfeature-sdk
@@ -16,28 +15,34 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.4.1
+        version: 0.6.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.4.1
+        version: 0.6.1
 - !ruby/object:Gem::Dependency
   name: openssl
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -58,14 +63,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.12.0
+        version: 3.13.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.12.0
+        version: 3.13.2
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
@@ -114,15 +119,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.1.0
+        version: 3.2.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.1.0
-description:
+        version: 3.2.0
 email:
 - TBD@TBD.com
 executables: []
@@ -143,7 +147,6 @@ metadata:
   changelog_uri: https://github.com/spotify/confidence-resolver/blob/main/openfeature-provider/ruby/CHANGELOG.md
   bug_tracker_uri: https://github.com/spotify/confidence-resolver/issues
   documentation_uri: https://github.com/spotify/confidence-resolver/blob/main/openfeature-provider/ruby/README.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -151,15 +154,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Confidence provider for the OpenFeature SDK
 test_files: []