togul 3.0.1 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b2551b63847f7928914d173351b85f54aa78f64a67552701273b9ef334ea0e2
-  data.tar.gz: cb63352498c0f05520963a92fb0f8ea17759b91823a7538d9051134ffd91120b
+  metadata.gz: 5d53ead06f1bd25ad67767277f7f31cda93a4178a9e29129e5bc267da925ece6
+  data.tar.gz: 27a85c6db8f140b334c78c50bbc39809b524d99be02dc3513717dfa1787fd2b5
 SHA512:
-  metadata.gz: 7272d609f48bd5100c6e9f6bf78b00d0df4bd0a517f1e96a2c097335d6319b66d81f0f7c8485ea3a9307c7868c5ce2c74cc59bee5e8971f4884fc4247a36e843
-  data.tar.gz: 359137fd534f9dac13572955a506852ab9baa1d8c6e5a07289312075bb4d12656f3fd1e5c65dbb6df439342e18d41647e040e95a9e43ec5c20769b2010f787c3
+  metadata.gz: '04798172f985b9d886c146387de2548223040b382d7ccebbe332e3f55858061379ef3b86a8b024b421ba5749a7e73f6532dea5d55e3e7cce9bc0549431b0a692'
+  data.tar.gz: f5d508679f70eb795a576b8ffd7438ca6343dde309a7f138cd476880df2677adc0bfe9a688ce7182c3d8d1f580610efe63b73c5d7b2de6d8f4ca60b64a8474f2

data/lib/togul/client.rb

@@ -11,6 +11,7 @@ module Togul
       @config = config
       @cache = Cache.new(ttl: config.cache_ttl)
       @stream_client = nil
+      @listeners = []
     end
 
     # Evaluate a feature flag and return the result mirroring the API response.
@@ -32,26 +33,34 @@ module Togul
     # Clear all cached flag values.
     def invalidate_cache
       @cache.flush
+      notify_listeners('')
     end
 
     # Clear a specific flag from cache.
     def invalidate_flag(key)
       @cache.invalidate_flag(key)
+      notify_listeners(key)
     end
 
     # Start the SSE stream in a background thread for real-time cache invalidation.
     # Subsequent calls are no-ops; the thread runs until the process exits.
     def start_stream
-      @stream_client ||= StreamClient.new(@config, @cache)
+      unless @stream_client
+        @stream_client = StreamClient.new(@config, @cache)
+        # The stream invalidates the cache itself; forward so listeners fire
+        # for stream events exactly as for manual invalidation.
+        @stream_client.on_cache_invalidated { |flag_key| notify_listeners(flag_key) }
+      end
       @stream_thread ||= Thread.new { @stream_client.connect }
       nil
     end
 
-    # Register a listener for cache invalidation events.
-    # Call start_stream separately to begin receiving events.
+    # Register a listener for cache invalidation, called with the flag key (or
+    # "" when the whole cache was cleared) for both manual invalidation and
+    # stream events. Call start_stream separately to receive stream events.
     def on_cache_invalidated(&block)
-      @stream_client ||= StreamClient.new(@config, @cache)
-      @stream_client.on_cache_invalidated(&block)
+      @listeners << block
+      nil
     end
 
     private
@@ -108,6 +117,10 @@ module Togul
       raise Error.new("all retries failed: #{last_error}")
     end
 
+    def notify_listeners(flag_key)
+      @listeners.each { |listener| listener.call(flag_key) }
+    end
+
     def build_cache_key(key, context)
       serialized_context = context.sort.map { |context_key, value| "#{context_key}=#{value}" }
       ([key, @config.environment] + serialized_context).join(':')

data/lib/togul/open_feature.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+require 'open_feature/sdk'
+require_relative '../togul'
+
+module Togul
+  module OpenFeature
+    # OpenFeature provider backed by Togul::Client.
+    #
+    # Requires the optional "openfeature-sdk" gem and an explicit
+    # `require "togul/open_feature"`. Caching, retries and SSE invalidation all
+    # stay in Togul::Client; this class only adapts the single evaluate call to
+    # OpenFeature's typed resolvers and never raises. Cache invalidations are
+    # re-emitted as PROVIDER_CONFIGURATION_CHANGED. Mirrors the PHP provider
+    # (togul-php/src/OpenFeature/TogulProvider.php).
+    class Provider
+      include ::OpenFeature::SDK::Provider::EventEmitter
+
+      Reason = ::OpenFeature::SDK::Provider::Reason
+      ErrorCode = ::OpenFeature::SDK::Provider::ErrorCode
+      ResolutionDetails = ::OpenFeature::SDK::Provider::ResolutionDetails
+
+      attr_reader :metadata, :client
+
+      # @param client [Togul::Client]
+      # @param targeting_key_attribute [String] Context attribute the targeting
+      #   key is sent as. Matches the default rule "bucket_by".
+      def initialize(client, targeting_key_attribute: 'user_id')
+        @client = client
+        @targeting_key_attribute = targeting_key_attribute
+        @metadata = ::OpenFeature::SDK::Provider::ProviderMetadata.new(name: 'Togul').freeze
+        @closed = false
+        client.on_cache_invalidated { |flag_key| on_invalidated(flag_key) }
+      end
+
+      def init(_evaluation_context = nil); end
+
+      # Stop forwarding invalidations. The client is left to its owner.
+      def shutdown
+        @closed = true
+      end
+
+      def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve(flag_key, default_value, evaluation_context, 'boolean') do |v|
+          [v == true || v == false, v]
+        end
+      end
+
+      def fetch_string_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve(flag_key, default_value, evaluation_context, 'string') { |v| [v.is_a?(String), v] }
+      end
+
+      def fetch_number_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve(flag_key, default_value, evaluation_context, 'number') { |v| [v.is_a?(Numeric), v] }
+      end
+
+      # Togul has a single "number" type; JSON parses "3.0" as a Float.
+      def fetch_integer_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve(flag_key, default_value, evaluation_context, 'integer') do |v|
+          whole = v.is_a?(Integer) || (v.is_a?(Float) && v.finite? && v == v.floor)
+          [whole, whole ? v.to_i : nil]
+        end
+      end
+
+      def fetch_float_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve(flag_key, default_value, evaluation_context, 'float') do |v|
+          [v.is_a?(Numeric), v.is_a?(Numeric) ? v.to_f : nil]
+        end
+      end
+
+      def fetch_object_value(flag_key:, default_value:, evaluation_context: nil)
+        resolve(flag_key, default_value, evaluation_context, 'object') do |v|
+          [v.is_a?(Hash) || v.is_a?(Array), v]
+        end
+      end
+
+      private
+
+      def on_invalidated(flag_key)
+        return if @closed
+
+        details = { message: 'Togul cache invalidated' }
+        details[:flags_changed] = [flag_key] unless flag_key.to_s.empty?
+        emit_event(::OpenFeature::SDK::ProviderEvent::PROVIDER_CONFIGURATION_CHANGED, details)
+      end
+
+      # @yieldparam value [Object] the flag value
+      # @yieldreturn [Array(Boolean, Object)] [matches, coerced value]
+      def resolve(flag_key, default_value, evaluation_context, expected_type)
+        begin
+          result = @client.evaluate(flag_key, togul_context(evaluation_context))
+        rescue Togul::Error => e
+          not_found = e.status_code == 404 && e.error_code == 'evaluate.flag_not_found'
+          return error(default_value, not_found ? ErrorCode::FLAG_NOT_FOUND : ErrorCode::GENERAL, e.message)
+        rescue StandardError => e
+          return error(default_value, ErrorCode::GENERAL, e.message)
+        end
+
+        # OpenFeature spec: a disabled flag resolves to the caller's default.
+        return ResolutionDetails.new(value: default_value, reason: Reason::DISABLED) unless result.enabled?
+
+        # A json flag created without a default stores null: nothing to serve.
+        return ResolutionDetails.new(value: default_value, reason: map_reason(result.reason)) if result.value.nil?
+
+        matches, value = yield(result.value)
+        unless matches
+          return error(default_value, ErrorCode::TYPE_MISMATCH,
+                       "Flag \"#{flag_key}\" has value_type \"#{result.value_type}\", requested #{expected_type}")
+        end
+
+        ResolutionDetails.new(value: value, reason: map_reason(result.reason))
+      end
+
+      def map_reason(reason)
+        case reason
+        when 'rule_match' then Reason::TARGETING_MATCH
+        when 'default' then Reason::DEFAULT
+        when 'disabled' then Reason::DISABLED
+        else Reason::UNKNOWN
+        end
+      end
+
+      def error(default_value, code, message)
+        ResolutionDetails.new(value: default_value, reason: Reason::ERROR, error_code: code, error_message: message)
+      end
+
+      # Togul evaluates against a flat Hash<String, String>, and Togul::Client
+      # builds its cache key by concatenating those values.
+      def togul_context(evaluation_context)
+        return {} if evaluation_context.nil?
+
+        targeting_key_field = ::OpenFeature::SDK::EvaluationContext::TARGETING_KEY
+        out = {}
+        evaluation_context.fields.each do |key, value|
+          next if key == targeting_key_field
+
+          string_value = stringify_attribute(value)
+          out[key.to_s] = string_value unless string_value.nil?
+        end
+
+        # An explicitly set attribute wins over the targeting key.
+        targeting_key = evaluation_context.targeting_key
+        if targeting_key && !targeting_key.to_s.empty? && !out.key?(@targeting_key_attribute)
+          out[@targeting_key_attribute] = targeting_key.to_s
+        end
+        out
+      end
+
+      # Rules compare with plain string equality ("eq", "in", ...), so every
+      # format must match what users type in the dashboard. nil drops the
+      # attribute.
+      def stringify_attribute(value)
+        case value
+        when nil then nil
+        when true, false then value.to_s
+        when Integer then value.to_s
+        when Float
+          return nil unless value.finite?
+
+          value == value.floor ? value.to_i.to_s : value.to_s
+        when Time, DateTime then value.iso8601
+        when Hash, Array then JSON.generate(value)
+        else value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/togul.rb

@@ -4,4 +4,5 @@ require_relative "togul/config"
 require_relative "togul/cache"
 require_relative "togul/error"
 require_relative "togul/evaluate_result"
+require_relative "togul/stream_client"
 require_relative "togul/client"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: togul
 version: !ruby/object:Gem::Version
-  version: 3.0.1
+  version: 3.1.0
 platform: ruby
 authors:
 - Togul
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-23 00:00:00.000000000 Z
+date: 2026-09-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -38,6 +38,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: openfeature-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
 description: Client library for evaluating feature flags from a Togul server with
   TTL caching, retry, and fallback support.
 email:
@@ -51,6 +79,7 @@ files:
 - lib/togul/config.rb
 - lib/togul/error.rb
 - lib/togul/evaluate_result.rb
+- lib/togul/open_feature.rb
 - lib/togul/stream_client.rb
 homepage: https://github.com/togulapp/togul-ruby
 licenses: