toggly 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cde892347959f5a15a5c42626562e9e9e5565fe3c1aa68bed4d0290ebfd08a1
-  data.tar.gz: d6825a1cc1616c69a9f4738b333e9a07bfc0d5ae3bd70d70221b158d4ecf0891
+  metadata.gz: 2f6a78a0c74623574333be32320578cdd12ee7bf1415ed199c2584716b5e98aa
+  data.tar.gz: c38ea07fda43a2ce57af893804471bd45ac819d51019e47e082aeccf0411e157
 SHA512:
-  metadata.gz: 5ff95be9cc331f8e8be111f25aafef777299ae3b2e38a0fdeeb22fdb3eeb2a54531266d3be5351283792e991d2aa00d427aa664a9ef6d2139bccb5baeb39b926
-  data.tar.gz: b27946b9231816193fb1aaeac0ebab94cb6dd8242664a4081108cfb5bf7c4e0dc2d9b6c4261be745e0e0364312efa6d9a0fff3610ce5cc5449cbc7cca41a20fc
+  metadata.gz: 9e6ce90750098dd4d67642925c3239f1a39a43d5f894d6de60949614d5e6c1de662912073001b9e1c1db42cc6baf9fd39e99efbeeb629d71dd92c54420461539
+  data.tar.gz: 3dce06734ce96188493c9fef22d030f17e538f8ae8711a128c5918a7c9c9ecdedd3786e1d6881553b1c962185940523df22a576ec059e8649c670d70053becd2

data/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-09-22
+
+### Added
+
+- Server-evaluated feature variants (dual-rail). Set `enable_variants: true`
+  on `Config` to additionally fetch `evaluated-variants-signed/{app_key}/
+  {environment}` on its own rail alongside the existing `definitions` /
+  `definitions-signed` pipeline. `definitions` / `definitions-signed` remain
+  the sole source of truth for `enabled?` regardless of `enable_variants` —
+  evaluated variants are additive and only feed `get_variant` /
+  `get_variant_value`; they never override `enabled?`. New `Config` options:
+  `enable_variants`, `variant_identity`, `variant_groups`, `variant_claims`.
+  New `Client#get_variant` / `Client#get_variant_value` return the assigned
+  variant name and `configuration_value`, or `nil` when unassigned or
+  disabled. New `Client#set_variant_identity` updates the `userId` sent to
+  `evaluated-variants-signed` and refreshes.
+- `SnapshotProviders::Base#save_variants` / `#load_variants` (default no-op)
+  so `Memory` and `File` providers persist evaluated variants across
+  restarts, independent of the `definitions` snapshot.
+
+**Note:** the new `get_variant` assignment is unrelated to the existing
+`variant:` label on `record_usage` / `record_view`, which is a free-form
+usage tag (defaults to `"enabled"`/`"disabled"`) and does not reflect
+`evaluated-variants-signed` results.
+
+## [0.5.2] - 2026-09-17
+
+### Fixed
+
+- Default usage/metrics gRPC host is `https://metrics.toggly.io/`.
+
 ## [0.5.1] - 2026-09-16
 
 ### Fixed

data/lib/toggly/client/snapshot_support.rb

@@ -2,14 +2,52 @@
 
 module Toggly
   class Client
-    # Durable snapshot load/save helpers for Client.
+    # Durable snapshot load/save helpers for Client. Dual-rail: `definitions`
+    # is always persisted/restored (sole source of truth for `enabled?`).
+    # `variant_defs` is an additive rail, persisted/restored independently
+    # only when `config.enable_variants` is true — it never replaces the
+    # definitions snapshot.
     module SnapshotSupport
       private
 
-      # @return [Boolean] true when a durable snapshot was applied into memory
+      # @return [Boolean] true when any durable snapshot rail was applied
+      #   into memory (definitions and/or evaluated variants)
       def load_snapshot
         return false unless @config.snapshot_provider
 
+        definitions_loaded = load_definitions_snapshot
+        variants_loaded = @config.enable_variants && load_variants_snapshot
+
+        definitions_loaded || variants_loaded
+      rescue StandardError => e
+        log_warn("Failed to load snapshot: #{e.message}")
+        false
+      end
+
+      # Persist the definitions rail. Always available regardless of
+      # `config.enable_variants` — definitions remain authoritative for
+      # `enabled?`.
+      def save_definitions_snapshot
+        return unless @config.snapshot_provider
+
+        @config.snapshot_provider.save(@definitions)
+        log_debug("Saved snapshot with #{@definitions.size} features")
+      rescue StandardError => e
+        log_warn("Failed to save snapshot: #{e.message}")
+      end
+
+      # Persist the evaluated-variants rail. Additive only; called only when
+      # `config.enable_variants` is true.
+      def save_variants_snapshot
+        return unless @config.snapshot_provider
+
+        @config.snapshot_provider.save_variants(@variant_defs)
+        log_debug("Saved variants snapshot with #{@variant_defs.size} features")
+      rescue StandardError => e
+        log_warn("Failed to save variants snapshot: #{e.message}")
+      end
+
+      def load_definitions_snapshot
         data = @config.snapshot_provider.load
         return false unless data
 
@@ -20,18 +58,20 @@ module Toggly
 
         log_debug("Loaded #{@definitions.size} features from snapshot")
         true
-      rescue StandardError => e
-        log_warn("Failed to load snapshot: #{e.message}")
-        false
       end
 
-      def save_snapshot
-        return unless @config.snapshot_provider
+      def load_variants_snapshot
+        return false unless @config.snapshot_provider.respond_to?(:load_variants)
 
-        @config.snapshot_provider.save(@definitions)
-        log_debug("Saved snapshot with #{@definitions.size} features")
-      rescue StandardError => e
-        log_warn("Failed to save snapshot: #{e.message}")
+        data = @config.snapshot_provider.load_variants
+        return false unless data
+
+        @mutex.synchronize do
+          @variant_defs = data[:variants] || {}
+        end
+
+        log_debug("Loaded #{@variant_defs.size} evaluated variants from snapshot")
+        true
       end
     end
   end

data/lib/toggly/client.rb

@@ -33,6 +33,10 @@ module Toggly
     # @return [Hash<String, FeatureDefinition>] Current definitions
     attr_reader :definitions
 
+    # @return [Hash<String, EvaluatedVariantDef>] Current evaluated variants
+    #   (populated only when `config.enable_variants` is true)
+    attr_reader :variant_defs
+
     # @return [Boolean] Whether the client is ready
     attr_reader :ready
 
@@ -44,6 +48,7 @@ module Toggly
       @config.validate!
 
       @definitions = {}
+      @variant_defs = {}
       # True once a revision (including empty) or durable snapshot was applied.
       @definitions_loaded = false
       @mutex = Mutex.new
@@ -80,7 +85,10 @@ module Toggly
 
       definition = @mutex.synchronize { @definitions[key] }
 
-      # Check defaults if not found
+      # Dual-rail: definitions/definitions-signed are the sole source of
+      # truth for enabled? — this holds even when config.enable_variants is
+      # true. Evaluated variants (@variant_defs) are an additive rail read
+      # only by get_variant / get_variant_value and never override this.
       result = if definition.nil?
                  if !default.nil?
                    default
@@ -109,6 +117,54 @@ module Toggly
       !enabled?(feature_key, context: context, default: default.nil? ? nil : !default)
     end
 
+    # Get the assigned variant for a feature. Requires `config.enable_variants`;
+    # returns nil when variants are disabled, unknown, or unassigned.
+    #
+    # NOTE: this is the actual A/B assignment. It is unrelated to the
+    # `variant:` telemetry label on `record_usage` / `record_view`, which is
+    # a free-form usage tag (defaults to "enabled"/"disabled") and does not
+    # reflect `evaluated-variants-signed` results.
+    #
+    # @param feature_key [String, Symbol] The feature key
+    # @return [VariantResult, nil]
+    def get_variant(feature_key)
+      return nil unless @config.enable_variants
+
+      key = feature_key.to_s
+      entry = @mutex.synchronize { @variant_defs[key] }
+      return nil if entry.nil? || entry.variant.nil? || entry.variant.to_s.empty?
+
+      VariantResult.new(name: entry.variant, configuration_value: entry.configuration_value)
+    end
+
+    # Get the configuration value for the assigned variant, if any.
+    #
+    # @param feature_key [String, Symbol] The feature key
+    # @return [Object, nil]
+    def get_variant_value(feature_key)
+      get_variant(feature_key)&.configuration_value
+    end
+
+    # Update the `userId` sent to `evaluated-variants-signed` and, when
+    # `config.enable_variants` is true, clear cached variants and refresh.
+    # No-op (besides updating provider state) when variants are disabled.
+    # Named as an action (not `variant_identity=`) because it also triggers
+    # a network refresh — it is not a passive attribute writer.
+    #
+    # @param identity [String, nil]
+    # @return [Boolean] true if the identity changed
+    # rubocop:disable-next Naming/AccessorMethodName
+    def set_variant_identity(identity)
+      changed = @provider.set_variant_identity(identity)
+
+      if changed && @config.enable_variants
+        @mutex.synchronize { @variant_defs = {} }
+        refresh(force: true) unless @config.offline_mode?
+      end
+
+      changed
+    end
+
     # Get detailed evaluation result
     #
     # @param feature_key [String, Symbol] The feature key
@@ -161,27 +217,15 @@ module Toggly
       end
 
       begin
-        result = @provider.fetch(force: force)
-        record_refresh_cache_outcome(result.cache_outcome)
-
-        if result.definitions
-          @mutex.synchronize do
-            @definitions = result.definitions
-            @definitions_loaded = true
-            @ready = true
-          end
-
-          save_snapshot
-          log_info("Definitions refreshed (#{result.definitions.size} features)")
-          true
-        else
-          false
-        end
-      rescue StandardError => e
-        log_error("Failed to refresh definitions: #{e.message}")
-        # Network error / timeout keeping last-good revision (incl. empty) — hit.
-        record_definition_cache_hit if definitions_cached?
-        false
+        # Dual-rail: definitions/definitions-signed are always refreshed —
+        # the sole source of truth for enabled?. When config.enable_variants
+        # is true, evaluated-variants-signed is ALSO fetched on its own rail,
+        # additive only for get_variant / get_variant_value. A failure on
+        # either rail must never affect the other.
+        definitions_updated = refresh_definitions_rail(force: force)
+        variants_updated = @config.enable_variants ? refresh_variants_rail(force: force) : false
+
+        definitions_updated || variants_updated
       ensure
         drain_pending = false
         @mutex.synchronize do
@@ -290,6 +334,67 @@ module Toggly
 
     private
 
+    # Definitions rail: `definitions` / `definitions-signed` → local rule eval.
+    # Always runs (dual-rail): the sole source of truth for `enabled?`,
+    # regardless of `config.enable_variants`.
+    def refresh_definitions_rail(force:)
+      refresh_definitions(force: force)
+    rescue StandardError => e
+      log_error("Failed to refresh definitions: #{e.message}")
+      # Network error / timeout keeping last-good revision (incl. empty) — hit.
+      record_definition_cache_hit if definitions_cached?
+      false
+    end
+
+    def refresh_definitions(force:)
+      result = @provider.fetch(force: force)
+      record_refresh_cache_outcome(result.cache_outcome)
+
+      if result.definitions
+        @mutex.synchronize do
+          @definitions = result.definitions
+          @definitions_loaded = true
+          @ready = true
+        end
+
+        save_definitions_snapshot
+        log_info("Definitions refreshed (#{result.definitions.size} features)")
+        true
+      else
+        false
+      end
+    end
+
+    # Variants rail: `evaluated-variants-signed` → server-evaluated assignment.
+    # Additive only (used by get_variant / get_variant_value); runs only when
+    # `config.enable_variants` is true and never influences `enabled?`. A
+    # failure here must never affect the definitions rail above, and is not
+    # counted in definition cache-hit/miss telemetry (that metric is scoped
+    # to the definitions rail).
+    def refresh_variants_rail(force:)
+      refresh_variants(force: force)
+    rescue StandardError => e
+      log_error("Failed to refresh evaluated variants: #{e.message}")
+      false
+    end
+
+    def refresh_variants(force:)
+      result = @provider.fetch_variants(force: force)
+
+      if result.variants
+        @mutex.synchronize do
+          @variant_defs = result.variants
+          @ready = true
+        end
+
+        save_variants_snapshot
+        log_info("Evaluated variants refreshed (#{result.variants.size} features)")
+        true
+      else
+        false
+      end
+    end
+
     def initialize_definitions
       # Startup served from durable snapshot before first network — cache hit.
       # Distinct from the subsequent refresh() network outcome (no double-count
@@ -314,7 +419,7 @@ module Toggly
       log_error("Failed to initialize definitions: #{e.message}")
 
       # Use snapshot or defaults as fallback
-      @ready = true if @definitions.any? || @config.defaults.any?
+      @ready = true if @definitions.any? || @variant_defs.any? || @config.defaults.any?
     end
 
     def start_background_refresh

data/lib/toggly/config.rb

@@ -55,6 +55,25 @@ module Toggly
     # @return [Array<String>] Allowed key IDs for signed definitions
     attr_accessor :allowed_key_ids
 
+    # @return [Boolean] When true, additionally fetch server-evaluated variants
+    #   from `evaluated-variants-signed` on their own rail (dual-rail).
+    #   `definitions` / `definitions-signed` remain the sole source of truth
+    #   for `enabled?` regardless of this setting — evaluated variants are
+    #   additive and only feed `Client#get_variant` / `#get_variant_value`.
+    attr_accessor :enable_variants
+
+    # @return [String, nil] `userId` sent to `evaluated-variants-signed` for targeting.
+    #   Separate from the per-call `Context#identity` used for local rule evaluation.
+    attr_accessor :variant_identity
+
+    # @return [Array<String>] Application-wide group memberships sent to
+    #   `evaluated-variants-signed` (not request-local booleans).
+    attr_accessor :variant_groups
+
+    # @return [Hash<String, String>] Application-wide string claims sent to
+    #   `evaluated-variants-signed` (at most 20 on the wire).
+    attr_accessor :variant_claims
+
     # @return [Logger, nil] Logger instance
     attr_accessor :logger
 
@@ -84,7 +103,7 @@ module Toggly
     DEFAULT_REFRESH_INTERVAL = 300 # 5 minutes
     DEFAULT_HTTP_TIMEOUT = 10 # seconds
     DEFAULT_ENVIRONMENT = "Production"
-    DEFAULT_METRICS_BASE_URL = "https://app.toggly.io/"
+    DEFAULT_METRICS_BASE_URL = "https://metrics.toggly.io/"
     DEFAULT_TELEMETRY_FLUSH_SECONDS = 60.0
 
     def initialize(**options)
@@ -104,6 +123,10 @@ module Toggly
       @snapshot_provider = options[:snapshot_provider]
       @use_signed_definitions = options[:use_signed_definitions] || false
       @allowed_key_ids = options[:allowed_key_ids] || []
+      @enable_variants = options[:enable_variants] || false
+      @variant_identity = options[:variant_identity]
+      @variant_groups = Array(options[:variant_groups])
+      @variant_claims = options[:variant_claims] || {}
       @logger = options[:logger]
 
       @usage_tracking_explicit = options.key?(:enable_usage_tracking)
@@ -127,6 +150,16 @@ module Toggly
       "#{normalize_url(base)}#{endpoint}/#{@app_key}/#{@environment}"
     end
 
+    # Get the evaluated-variants-signed endpoint URL. Always signed; query
+    # params (userId/groups/claims) are added by the provider since they can
+    # change at runtime (see `Client#set_variant_identity`).
+    #
+    # @return [String]
+    def variants_endpoint
+      base = @definitions_url || @base_url
+      "#{normalize_url(base)}evaluated-variants-signed/#{@app_key}/#{@environment}"
+    end
+
     # Validate the configuration
     #
     # @raise [ConfigError] if configuration is invalid
@@ -186,6 +219,7 @@ module Toggly
         enable_undefined_in_dev: @enable_undefined_in_dev,
         disable_background_refresh: @disable_background_refresh,
         enable_live_updates: @enable_live_updates,
+        enable_variants: @enable_variants,
         app_version: @app_version,
         instance_name: @instance_name,
         use_signed_definitions: @use_signed_definitions,

data/lib/toggly/definitions_provider.rb

@@ -17,6 +17,12 @@ module Toggly
     # Result of one HTTP definitions fetch with cache telemetry outcome.
     FetchResult = Struct.new(:definitions, :cache_outcome, keyword_init: true)
 
+    # Result of one HTTP evaluated-variants fetch with cache telemetry outcome.
+    VariantFetchResult = Struct.new(:variants, :cache_outcome, keyword_init: true)
+
+    # Maximum number of string claims sent on the evaluated-variants-signed wire.
+    MAX_VARIANT_CLAIMS = 20
+
     # Fallback HTTP refresh interval when WebSocket is connected (20 minutes)
     FALLBACK_REFRESH_INTERVAL = 20 * 60
 
@@ -37,6 +43,13 @@ module Toggly
       @last_modified = nil
       @last_ts = 0
 
+      # Evaluated-variants rail state — separate ETag/Last-Modified/timestamp
+      # namespace from definitions so the two rails never cross-invalidate.
+      @variant_etag = nil
+      @variant_last_modified = nil
+      @variant_last_ts = 0
+      @variant_identity = config.variant_identity
+
       # WebSocket state
       @ws = nil
       @ws_connected = false
@@ -77,6 +90,56 @@ module Toggly
       @last_ts = 0
     end
 
+    # Fetch server-evaluated variants from `evaluated-variants-signed`.
+    # Independent ETag/timestamp cache from {#fetch} (separate rail).
+    #
+    # @param force [Boolean] Force fetch even if cached
+    # @return [VariantFetchResult] variants (Hash or nil) plus :hit / :miss outcome
+    # @raise [NetworkError] On network failures
+    # @raise [DefinitionsError] On API errors
+    def fetch_variants(force: false)
+      return VariantFetchResult.new(variants: nil, cache_outcome: :hit) if @config.offline_mode?
+
+      uri = URI.parse(build_variant_request_url)
+      http = build_http(uri)
+      request = build_variant_request(uri, force)
+
+      response = http.request(request)
+      handle_variant_response(response)
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise NetworkError, "Request timeout: #{e.message}"
+    rescue SocketError, Errno::ECONNREFUSED => e
+      raise NetworkError, "Connection failed: #{e.message}"
+    rescue NetworkError, DefinitionsError
+      raise
+    rescue StandardError => e
+      raise NetworkError, "Request failed: #{e.message}"
+    end
+
+    # Update the `userId` sent to `evaluated-variants-signed`. Distinct from
+    # any per-call `Context#identity` used for local rule evaluation. Named
+    # as an action (not `variant_identity=`) because it also invalidates the
+    # variants cache — it is not a passive attribute writer.
+    #
+    # @param identity [String, nil]
+    # @return [Boolean] true if the identity changed (cache invalidated)
+    # rubocop:disable-next Naming/AccessorMethodName
+    def set_variant_identity(identity)
+      normalized = identity&.to_s
+      return false if normalized == @variant_identity
+
+      @variant_identity = normalized
+      reset_variant_cache
+      true
+    end
+
+    # Reset cached variant headers/timestamp (force full fetch next time)
+    def reset_variant_cache
+      @variant_etag = nil
+      @variant_last_modified = nil
+      @variant_last_ts = 0
+    end
+
     # Check whether the periodic refresh should be skipped because the
     # WebSocket connection is active and the fallback interval has not elapsed.
     #
@@ -195,7 +258,7 @@ module Toggly
       when :new_content
         handle_new_content(response, response_etag, response_lm)
       when :error_status
-        handle_error_status(status, response)
+        handle_error_status(status, response, resource: "definitions")
       end
     end
 
@@ -216,12 +279,12 @@ module Toggly
       raise DefinitionsError, "Failed to parse definitions: #{e.message}"
     end
 
-    def handle_error_status(status, response)
+    def handle_error_status(status, response, resource: "definitions")
       case status
       when 401, 403
         raise DefinitionsError, "Authentication failed: #{status}"
       when 404
-        raise DefinitionsError, "Definitions not found (check app_key and environment)"
+        raise DefinitionsError, "#{resource.capitalize} not found (check app_key and environment)"
       else
         raise NetworkError.new(
           "API error: #{status}",
@@ -236,6 +299,110 @@ module Toggly
       @last_modified = last_modified if last_modified && !last_modified.empty?
     end
 
+    def build_variant_request_url
+      pairs = variant_query_pairs
+      base = @config.variants_endpoint
+      pairs.empty? ? base : "#{base}?#{URI.encode_www_form(pairs)}"
+    end
+
+    def variant_query_pairs
+      pairs = []
+      pairs << ["userId", @variant_identity] if @variant_identity && !@variant_identity.empty?
+
+      Array(@config.variant_groups).each do |group|
+        next unless group.is_a?(String)
+
+        trimmed = group.strip
+        pairs << ["g", trimmed] unless trimmed.empty?
+      end
+
+      normalized_claims = {}
+      (@config.variant_claims || {}).each do |key, value|
+        next unless key.is_a?(String) && value.is_a?(String)
+        next if key.empty? || value.empty?
+
+        normalized_claims[key] = value
+      end
+      normalized_claims.keys.sort.first(MAX_VARIANT_CLAIMS).each do |key|
+        pairs << ["claim.#{key}", normalized_claims[key]]
+      end
+
+      pairs
+    end
+
+    def build_variant_request(uri, force)
+      request = Net::HTTP::Get.new(uri)
+      request["Accept"] = "application/json"
+      request["User-Agent"] = "toggly-ruby/#{Toggly::VERSION}"
+      request["X-App-Version"] = @config.app_version if @config.app_version
+      request["X-Instance-Name"] = @config.instance_name if @config.instance_name
+
+      unless force
+        request["If-None-Match"] = @variant_etag if @variant_etag
+        request["If-Modified-Since"] = @variant_last_modified if @variant_last_modified
+      end
+
+      request
+    end
+
+    def handle_variant_response(response)
+      status = response.code.to_i
+      response_etag = response["ETag"]
+      response_lm = response["Last-Modified"]
+      kind = DefinitionCache.classify_http(
+        status,
+        @variant_etag,
+        response_etag,
+        existing_last_modified: @variant_last_modified,
+        response_last_modified: response_lm
+      )
+
+      case kind
+      when :not_modified
+        log_debug("Evaluated variants not modified")
+        VariantFetchResult.new(variants: nil, cache_outcome: :hit)
+      when :same_revision
+        log_debug("Evaluated variants revision matches existing (ETag or Last-Modified)")
+        store_variant_revision_headers(response_etag, response_lm)
+        VariantFetchResult.new(variants: nil, cache_outcome: :hit)
+      when :new_content
+        handle_new_variant_content(response, response_etag, response_lm)
+      when :error_status
+        handle_error_status(status, response, resource: "evaluated variants")
+      end
+    end
+
+    def handle_new_variant_content(response, response_etag, response_lm)
+      data = JSON.parse(response.body)
+      signed_ts = extract_signed_timestamp(data)
+      if DefinitionCache.cached_signed_timestamp?(@variant_last_ts, signed_ts)
+        log_debug("Evaluated variants signed timestamp is not newer than cached revision")
+        store_variant_revision_headers(response_etag, response_lm)
+        return VariantFetchResult.new(variants: nil, cache_outcome: :hit)
+      end
+
+      variants = parse_variant_defs(data)
+      store_variant_revision_headers(response_etag, response_lm)
+      @variant_last_ts = signed_ts if signed_ts&.positive?
+      VariantFetchResult.new(variants: variants, cache_outcome: :miss)
+    rescue JSON::ParserError => e
+      raise DefinitionsError, "Failed to parse evaluated variants: #{e.message}"
+    end
+
+    def store_variant_revision_headers(etag, last_modified)
+      @variant_etag = etag if etag && !etag.empty?
+      @variant_last_modified = last_modified if last_modified && !last_modified.empty?
+    end
+
+    def parse_variant_defs(data)
+      raw = data.is_a?(Hash) ? data["defs"] : nil
+      return {} unless raw.is_a?(Hash)
+
+      raw.each_with_object({}) do |(key, value), hash|
+        hash[key] = EvaluatedVariantDef.from_hash(value) if value.is_a?(Hash)
+      end
+    end
+
     def extract_signed_timestamp(data)
       return nil unless data.is_a?(Hash)
 

data/lib/toggly/evaluated_variant.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Toggly
+  # Server-evaluated variant entry for a single feature flag, as returned by
+  # `evaluated-variants-signed`. This is distinct from `FeatureDefinition`
+  # (client-side rules): the server has already picked the winning variant.
+  class EvaluatedVariantDef
+    # @return [Boolean] Whether the feature is enabled for this assignment
+    attr_reader :enabled
+
+    # @return [String, nil] Assigned variant name, if any
+    attr_reader :variant
+
+    # @return [Object, nil] Configuration payload for the variant (shape depends on the feature)
+    attr_reader :configuration_value
+
+    def initialize(enabled:, variant: nil, configuration_value: nil)
+      @enabled = enabled ? true : false
+      @variant = variant
+      @configuration_value = configuration_value
+    end
+
+    # Create from a hash (API response or snapshot; camelCase or snake_case).
+    #
+    # @param hash [Hash]
+    # @return [EvaluatedVariantDef]
+    def self.from_hash(hash)
+      hash = symbolize_keys(hash)
+      configuration_value = if hash.key?(:configurationValue)
+                              hash[:configurationValue]
+                            else
+                              hash[:configuration_value]
+                            end
+
+      new(
+        enabled: hash[:enabled],
+        variant: hash[:variant],
+        configuration_value: configuration_value
+      )
+    end
+
+    # Convert to a hash for serialization (snapshot persistence).
+    #
+    # @return [Hash]
+    def to_h
+      {
+        enabled: @enabled,
+        variant: @variant,
+        configuration_value: @configuration_value
+      }
+    end
+
+    def ==(other)
+      other.is_a?(EvaluatedVariantDef) &&
+        @enabled == other.enabled &&
+        @variant == other.variant &&
+        @configuration_value == other.configuration_value
+    end
+    alias eql? ==
+
+    def self.symbolize_keys(hash)
+      return hash unless hash.is_a?(Hash)
+
+      hash.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
+    end
+    private_class_method :symbolize_keys
+  end
+
+  # Assigned variant name and configuration value for a feature, returned by
+  # `Client#get_variant` when `Config#enable_variants` is true.
+  class VariantResult
+    # @return [String] Variant name assigned by the server
+    attr_reader :name
+
+    # @return [Object, nil] Optional configuration payload for the variant
+    attr_reader :configuration_value
+
+    def initialize(name:, configuration_value: nil)
+      @name = name
+      @configuration_value = configuration_value
+    end
+
+    # @return [Hash]
+    def to_h
+      { name: @name, configuration_value: @configuration_value }
+    end
+  end
+end

data/lib/toggly/snapshot_providers/base.rb

@@ -40,6 +40,21 @@ module Toggly
         false
       end
 
+      # Save evaluated variants snapshot (dual-rail, used when
+      # `config.enable_variants` is true). Default: no-op. Override in
+      # subclasses to persist variants across restarts.
+      #
+      # @param variants [Hash<String, EvaluatedVariantDef>] Variants to save
+      # @param metadata [Hash] Optional metadata
+      def save_variants(_variants, _metadata = {}); end
+
+      # Load evaluated variants snapshot (dual-rail).
+      #
+      # @return [Hash, nil] Hash with :variants and :metadata, or nil if not available
+      def load_variants
+        nil
+      end
+
       protected
 
       # Serialize definitions to a storable format
@@ -62,6 +77,26 @@ module Toggly
           hash[definition.feature_key] = definition
         end
       end
+
+      # Serialize evaluated variants to a storable format
+      #
+      # @param variants [Hash<String, EvaluatedVariantDef>] Variants
+      # @return [Hash<String, Hash>]
+      def serialize_variants(variants)
+        variants.transform_values(&:to_h)
+      end
+
+      # Deserialize evaluated variants from stored format
+      #
+      # @param data [Hash<String, Hash>] Serialized variants
+      # @return [Hash<String, EvaluatedVariantDef>]
+      def deserialize_variants(data)
+        return {} unless data.is_a?(Hash)
+
+        data.each_with_object({}) do |(key, value), hash|
+          hash[key.to_s] = EvaluatedVariantDef.from_hash(value)
+        end
+      end
     end
   end
 end

data/lib/toggly/snapshot_providers/file.rb

@@ -12,10 +12,14 @@ module Toggly
       # @return [String] Path to the snapshot file
       attr_reader :path
 
+      # @return [String] Path to the evaluated-variants snapshot file (dual-rail)
+      attr_reader :variants_path
+
       # @param path [String] Path to the snapshot file
       def initialize(path:)
         super()
         @path = path
+        @variants_path = derive_variants_path(path)
         @mutex = Mutex.new
       end
 
@@ -66,6 +70,7 @@ module Toggly
       def clear
         @mutex.synchronize do
           FileUtils.rm_f(@path)
+          FileUtils.rm_f(@variants_path)
         end
       rescue StandardError => e
         raise SnapshotError, "Failed to clear snapshot: #{e.message}"
@@ -78,6 +83,48 @@ module Toggly
         ::File.exist?(@path)
       end
 
+      # Save evaluated variants to file using atomic write (dual-rail)
+      #
+      # @param variants [Hash<String, EvaluatedVariantDef>] Variants
+      # @param metadata [Hash] Optional metadata
+      def save_variants(variants, metadata = {})
+        @mutex.synchronize do
+          ensure_directory_exists
+
+          data = {
+            "variants" => serialize_variants(variants),
+            "metadata" => metadata.merge("saved_at" => Time.now.utc.iso8601)
+          }
+
+          temp_path = "#{@variants_path}.tmp"
+          ::File.write(temp_path, JSON.pretty_generate(data))
+          ::File.rename(temp_path, @variants_path)
+        end
+      rescue StandardError => e
+        raise SnapshotError, "Failed to save variants snapshot: #{e.message}"
+      end
+
+      # Load evaluated variants from file (dual-rail)
+      #
+      # @return [Hash, nil] Hash with :variants and :metadata
+      def load_variants
+        @mutex.synchronize do
+          return nil unless ::File.exist?(@variants_path)
+
+          content = ::File.read(@variants_path)
+          data = JSON.parse(content)
+
+          {
+            variants: deserialize_variants(data["variants"]),
+            metadata: symbolize_keys(data["metadata"] || {})
+          }
+        end
+      rescue JSON::ParserError => e
+        raise SnapshotError, "Failed to parse variants snapshot: #{e.message}"
+      rescue StandardError => e
+        raise SnapshotError, "Failed to load variants snapshot: #{e.message}"
+      end
+
       private
 
       def ensure_directory_exists
@@ -85,6 +132,13 @@ module Toggly
         FileUtils.mkdir_p(dir) unless ::File.directory?(dir)
       end
 
+      def derive_variants_path(path)
+        dir = ::File.dirname(path)
+        ext = ::File.extname(path)
+        base = ::File.basename(path, ext)
+        ::File.join(dir, "#{base}_variants#{ext}")
+      end
+
       def symbolize_keys(hash)
         return {} unless hash.is_a?(Hash)
 

data/lib/toggly/snapshot_providers/memory.rb

@@ -9,6 +9,7 @@ module Toggly
       def initialize
         super
         @data = nil
+        @variants_data = nil
         @mutex = Mutex.new
       end
 
@@ -43,6 +44,7 @@ module Toggly
       def clear
         @mutex.synchronize do
           @data = nil
+          @variants_data = nil
         end
       end
 
@@ -54,6 +56,33 @@ module Toggly
           !@data.nil?
         end
       end
+
+      # Save evaluated variants to memory (dual-rail)
+      #
+      # @param variants [Hash<String, EvaluatedVariantDef>] Variants
+      # @param metadata [Hash] Optional metadata
+      def save_variants(variants, metadata = {})
+        @mutex.synchronize do
+          @variants_data = {
+            variants: serialize_variants(variants),
+            metadata: metadata.merge(saved_at: Time.now.utc.iso8601)
+          }
+        end
+      end
+
+      # Load evaluated variants from memory (dual-rail)
+      #
+      # @return [Hash, nil] Hash with :variants and :metadata
+      def load_variants
+        @mutex.synchronize do
+          return nil unless @variants_data
+
+          {
+            variants: deserialize_variants(@variants_data[:variants]),
+            metadata: @variants_data[:metadata]
+          }
+        end
+      end
     end
   end
 end

data/lib/toggly/telemetry/grpc_clients.rb

@@ -6,7 +6,7 @@ module Toggly
   module Telemetry
     # Optional gRPC transport helpers for usage and metrics telemetry.
     module GrpcClients
-      DEFAULT_METRICS_BASE_URL = "https://app.toggly.io/"
+      DEFAULT_METRICS_BASE_URL = "https://metrics.toggly.io/"
       DEFAULT_TELEMETRY_FLUSH_SECONDS = 60.0
 
       # HTTP/2 metadata is case-insensitive; .NET/Go/Node send ``UA``.

data/lib/toggly/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Toggly
-  VERSION = "0.5.1"
+  VERSION = "0.6.0"
 end

data/lib/toggly.rb

@@ -10,6 +10,7 @@ require_relative "toggly/user_agent_parser"
 require_relative "toggly/context"
 require_relative "toggly/errors"
 require_relative "toggly/feature_definition"
+require_relative "toggly/evaluated_variant"
 require_relative "toggly/evaluators/base"
 require_relative "toggly/evaluators/segment_helpers"
 require_relative "toggly/evaluators/always_on"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toggly
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Ops.ai
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-17 00:00:00.000000000 Z
+date: 2026-09-23 00:00:00.000000000 Z
 dependencies: []
 description: High-performance Ruby SDK for Toggly feature flag management. Works with
   or without Toggly.io.
@@ -31,6 +31,7 @@ files:
 - lib/toggly/definitions_provider.rb
 - lib/toggly/entity_context.rb
 - lib/toggly/errors.rb
+- lib/toggly/evaluated_variant.rb
 - lib/toggly/evaluation_engine.rb
 - lib/toggly/evaluators/always_off.rb
 - lib/toggly/evaluators/always_on.rb