toggly 0.6.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f6a78a0c74623574333be32320578cdd12ee7bf1415ed199c2584716b5e98aa
-  data.tar.gz: c38ea07fda43a2ce57af893804471bd45ac819d51019e47e082aeccf0411e157
+  metadata.gz: d728557cdb56574a22377e85047ec649a801532f9cea3574ae66ccba703e320e
+  data.tar.gz: 5054b15ad5ad1b48fde5c6fb174698c701bd8fa38b6054cc8afd6ff015e196ce
 SHA512:
-  metadata.gz: 9e6ce90750098dd4d67642925c3239f1a39a43d5f894d6de60949614d5e6c1de662912073001b9e1c1db42cc6baf9fd39e99efbeeb629d71dd92c54420461539
-  data.tar.gz: 3dce06734ce96188493c9fef22d030f17e538f8ae8711a128c5918a7c9c9ecdedd3786e1d6881553b1c962185940523df22a576ec059e8649c670d70053becd2
+  metadata.gz: 8871e715209c606026d37367ec46522c3bbcc7925633f9f511bad51179f141924cb4b7e123978212e1a1697050072d0bfacff0463e53cf02510012cb28531db1
+  data.tar.gz: c3536488d775b49aeefa375f72f3c6b88a993fb4b6464a19e8c5ae73bde75222c310bc820e563f94039509bd6dbbc698ddb04c33cd89de6beba2e7c1ac29dd56

data/CHANGELOG.md

@@ -5,6 +5,53 @@ 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).
 
+## [1.1.0] - 2026-09-23
+
+### Added
+
+- Ambient targeting identity for catalog-local variants: `Config#identity`,
+  `Client#identity` / `Client#set_identity`. When `get_variant` /
+  `get_variant_value` are called with a nil context or a blank
+  `context.identity`, the client identity is used as the allocator
+  `userId`. Groups still come only from the per-call context (never Config).
+  Prefer config / `set_identity` (or Rails ambient context) over building
+  `Context.new(identity: …)` at every call site.
+  `Config#identity=` is configuration-time only (`Toggly.configure` /
+  `Config.new`); after `Client` is built, use `Client#set_identity`.
+
+## [1.0.0] - 2026-09-23
+
+### Changed (Breaking)
+
+- **Catalog-local, MF-parity feature variants**, replacing the
+  `enable_variants` / `evaluated-variants-signed` dual-rail from 0.6.0.
+  `Client#get_variant` / `#get_variant_value` now assign variants **locally**
+  from the same `variants` / `allocation` payload on the `definitions` /
+  `definitions-signed` catalog that drives `enabled?` — there is no separate
+  network call. Assignment matches `Microsoft.FeatureManagement` 4.7.0's
+  `IVariantFeatureManager` bit-for-bit (user → group → percentile → default,
+  `StatusOverride`, percentile SHA-256 hashing) and is verified against the
+  shared `variant-allocator-corpus/cases.json` gold corpus (100% pass).
+  - `get_variant(feature_key, context: nil)` / `get_variant_value(feature_key,
+    context: nil)` now take the same `context:` (`userId` + `groups`) used by
+    `enabled?`, instead of a client-wide `variant_identity`.
+  - `VariantResult` gains `enabled` (effective enabled after the assigned
+    variant's `StatusOverride` — `enabled?` itself stays filter-based only)
+    and `reason` (`"User"` | `"Group"` | `"Percentile"` |
+    `"DefaultWhenEnabled"` | `"DefaultWhenDisabled"`).
+  - New `FeatureDefinition#variants` / `#allocation` (`FeatureVariant`,
+    `FeatureVariantAllocation`), parsed from the `definitions` wire.
+- **Removed**: `Config#enable_variants` / `#variant_identity` /
+  `#variant_groups` / `#variant_claims` / `#variants_endpoint`,
+  `Client#variant_defs` / `#set_variant_identity`, `EvaluatedVariantDef`,
+  and the `evaluated-variants-signed` fetch/cache rail (including the
+  `SnapshotProviders` `save_variants` / `load_variants` hooks — variants are
+  now part of the ordinary definitions snapshot via `FeatureDefinition`).
+
+**Migration**: drop `enable_variants` / `variant_identity` /
+`set_variant_identity` from your config. Pass targeting via
+`get_variant(key, context: Toggly::Context.new(identity: ..., groups: ...))`.
+
 ## [0.6.0] - 2026-09-22
 
 ### Added

data/README.md

@@ -38,6 +38,34 @@ if client.enabled?(:my_feature)
 end
 ```
 
+## Feature variants (catalog-local, MF-parity)
+
+`get_variant` / `get_variant_value` assign a variant purely from the
+feature's `variants` / `allocation` catalog data (no network round-trip),
+matching `Microsoft.FeatureManagement`'s `IVariantFeatureManager`
+bit-for-bit — verified against the shared
+`variant-allocator-corpus/cases.json` gold corpus.
+
+```ruby
+# Prefer ambient identity: Config#identity, Client#set_identity, or Rails
+# feature_variant (uses toggly_context). Per-call context is an override.
+client = Toggly::Client.new(app_key: '...', environment: 'Production', identity: 'user-1')
+client.set_identity('user-2') # optional runtime update
+
+variant = client.get_variant('checkout-flow') # uses client identity
+variant = client.get_variant('checkout-flow', context: Toggly::Context.new(identity: 'override'))
+variant&.name                 # assigned variant name, or nil
+variant&.configuration_value  # untyped configuration payload
+variant&.enabled               # effective enabled after StatusOverride
+variant&.reason                # "User" | "Group" | "Percentile" | "DefaultWhenEnabled" | "DefaultWhenDisabled"
+
+client.get_variant_value('checkout-flow') # shortcut for configuration_value
+```
+
+`enabled?` stays filter-based only. The `enable_variants` /
+`evaluated-variants-signed` dual-rail (and `set_variant_identity`) was
+removed in 1.0 — see [CHANGELOG.md](CHANGELOG.md).
+
 ## Usage & metrics telemetry
 
 When `app_key` is set, usage tracking and metrics default **on** (disable with

data/lib/toggly/client/snapshot_support.rb

@@ -2,31 +2,22 @@
 
 module Toggly
   class 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.
+    # Durable snapshot load/save helpers for Client. Definitions (including
+    # `variants` / `allocation`) are the only persisted rail — there is no
+    # separate evaluated-variants snapshot (removed with the dual-rail).
     module SnapshotSupport
       private
 
-      # @return [Boolean] true when any durable snapshot rail was applied
-      #   into memory (definitions and/or evaluated variants)
+      # @return [Boolean] true when the durable snapshot was applied into memory
       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
+        load_definitions_snapshot
       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
 
@@ -36,17 +27,6 @@ module Toggly
         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
@@ -59,20 +39,6 @@ module Toggly
         log_debug("Loaded #{@definitions.size} features from snapshot")
         true
       end
-
-      def load_variants_snapshot
-        return false unless @config.snapshot_provider.respond_to?(:load_variants)
-
-        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
 end

data/lib/toggly/client.rb

@@ -33,10 +33,6 @@ 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
 
@@ -48,10 +44,10 @@ module Toggly
       @config.validate!
 
       @definitions = {}
-      @variant_defs = {}
       # True once a revision (including empty) or durable snapshot was applied.
       @definitions_loaded = false
       @mutex = Mutex.new
+      @identity = normalize_client_identity(@config.identity)
       @ready = false
       @closed = false
 
@@ -85,10 +81,9 @@ module Toggly
 
       definition = @mutex.synchronize { @definitions[key] }
 
-      # 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.
+      # `enabled?` stays filter-based only (definitions/definitions-signed).
+      # It never reflects a variant's StatusOverride — see `get_variant`
+      # (`VariantResult#enabled`) for MF-identical effective-enabled semantics.
       result = if definition.nil?
                  if !default.nil?
                    default
@@ -117,52 +112,81 @@ 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.
+    # Get the assigned variant for a feature, computed locally from the
+    # feature's catalog `variants` / `allocation` (MF-parity, bit-for-bit
+    # with `Microsoft.FeatureManagement`'s `IVariantFeatureManager`). Returns
+    # nil when the feature is unknown, has no variants configured, or no
+    # variant resolves for this context (see {VariantAllocator}).
+    #
+    # There is no network round-trip here — this superseded the
+    # `enable_variants` / `evaluated-variants-signed` dual-rail removed in
+    # 1.0 (see CHANGELOG).
+    #
+    # Targeting identity resolution (first non-empty wins):
+    # 1. per-call `context.identity`
+    # 2. {#identity} from Config / {#set_identity}
+    # 3. empty (MF anonymous)
+    #
+    # Groups come only from the per-call context (never Config). Prefer
+    # Rails `feature_variant` / ambient `toggly_context`, or
+    # `set_identity` / `Config#identity` for non-HTTP hosts — not a
+    # hand-built identity on every call.
     #
     # 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.
+    # a free-form usage tag (defaults to "enabled"/"disabled").
     #
     # @param feature_key [String, Symbol] The feature key
+    # @param context [Context, nil] Optional targeting context (userId + groups)
     # @return [VariantResult, nil]
-    def get_variant(feature_key)
-      return nil unless @config.enable_variants
-
+    def get_variant(feature_key, context: nil)
       key = feature_key.to_s
-      entry = @mutex.synchronize { @variant_defs[key] }
-      return nil if entry.nil? || entry.variant.nil? || entry.variant.to_s.empty?
+      definition = @mutex.synchronize { @definitions[key] }
+      return nil if definition.nil?
+
+      enabled = @engine.evaluate(definition, context)
+      assignment = VariantAllocator.assign(
+        definition,
+        enabled: enabled,
+        identity: variant_user_id(context),
+        groups: context&.groups || []
+      )
+      return nil if assignment.variant_name.nil?
 
-      VariantResult.new(name: entry.variant, configuration_value: entry.configuration_value)
+      VariantResult.new(
+        name: assignment.variant_name,
+        configuration_value: assignment.configuration_value,
+        enabled: assignment.enabled,
+        reason: assignment.reason
+      )
     end
 
     # Get the configuration value for the assigned variant, if any.
     #
     # @param feature_key [String, Symbol] The feature key
+    # @param context [Context, nil] Optional targeting context (userId + groups)
     # @return [Object, nil]
-    def get_variant_value(feature_key)
-      get_variant(feature_key)&.configuration_value
+    def get_variant_value(feature_key, context: nil)
+      get_variant(feature_key, context: context)&.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.
+    # Default targeting userId used by {#get_variant} / {#get_variant_value}
+    # when the per-call context has no identity.
     #
-    # @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
+    # @return [String, nil]
+    def identity
+      @mutex.synchronize { @identity }
+    end
 
-      changed
+    # Set the default targeting userId (overrides Config#identity at runtime).
+    # Pass +nil+ or an empty string to clear.
+    #
+    # Named +set_identity+ (not +identity=+) to match Python/Java/Go SDK APIs.
+    #
+    # @param value [String, nil]
+    # @return [String, nil]
+    def set_identity(value) # rubocop:disable Naming/AccessorMethodName
+      @mutex.synchronize { @identity = normalize_client_identity(value) }
     end
 
     # Get detailed evaluation result
@@ -217,15 +241,7 @@ module Toggly
       end
 
       begin
-        # 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
+        refresh_definitions_rail(force: force)
       ensure
         drain_pending = false
         @mutex.synchronize do
@@ -334,9 +350,9 @@ 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`.
+    # `definitions` / `definitions-signed` → local rule eval. The sole
+    # source of truth for `enabled?`; also carries `variants` / `allocation`
+    # for the catalog-local `get_variant` assignment.
     def refresh_definitions_rail(force:)
       refresh_definitions(force: force)
     rescue StandardError => e
@@ -365,36 +381,6 @@ module Toggly
       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
@@ -419,7 +405,7 @@ module Toggly
       log_error("Failed to initialize definitions: #{e.message}")
 
       # Use snapshot or defaults as fallback
-      @ready = true if @definitions.any? || @variant_defs.any? || @config.defaults.any?
+      @ready = true if @definitions.any? || @config.defaults.any?
     end
 
     def start_background_refresh
@@ -496,6 +482,20 @@ module Toggly
       @telemetry.record_check(feature_key, enabled, identity)
     end
 
+    # Allocator userId: per-call context identity when present, else client identity.
+    def variant_user_id(context)
+      return context.identity if context&.identity?
+
+      identity
+    end
+
+    def normalize_client_identity(value)
+      return nil if value.nil?
+
+      text = value.to_s
+      text.empty? ? nil : text
+    end
+
     def log_info(message)
       @config.logger&.info("[Toggly] #{message}")
     end

data/lib/toggly/config.rb

@@ -12,6 +12,17 @@ module Toggly
     # @return [String] Application key from Toggly dashboard
     attr_reader :app_key
 
+    # Default targeting userId for catalog-local +get_variant+ /
+    # +get_variant_value+ when neither a per-call +Context#identity+ nor
+    # Rails ambient context supplies one. Groups are never taken from Config.
+    #
+    # Set at configuration time only ({Config.new}, +Toggly.configure+ block).
+    # After a {Client} is built, mutating this value has no effect — use
+    # {Client#set_identity} for runtime updates.
+    #
+    # @return [String, nil]
+    attr_reader :identity
+
     # @return [String] Environment name (e.g., "Production", "Staging")
     attr_accessor :environment
 
@@ -55,25 +66,6 @@ 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
 
@@ -108,6 +100,7 @@ module Toggly
 
     def initialize(**options)
       @app_key = options[:app_key]
+      @identity = normalize_identity(options[:identity])
       @environment = options[:environment] || DEFAULT_ENVIRONMENT
       @base_url = normalize_url(options[:base_url] || DEFAULT_BASE_URL)
       @definitions_url = options[:definitions_url]
@@ -123,10 +116,6 @@ 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)
@@ -150,16 +139,6 @@ 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
@@ -205,12 +184,23 @@ module Toggly
       (@app_key.nil? || @app_key.empty?) && !@defaults.empty?
     end
 
+    # Configuration-time identity only (e.g. inside +Toggly.configure+ before
+    # {Client} is constructed). Does not update an existing client's targeting
+    # identity — call {Client#set_identity} after initialization.
+    #
+    # @param value [String, nil]
+    # @return [String, nil]
+    def identity=(value)
+      @identity = normalize_identity(value)
+    end
+
     # Convert to hash
     #
     # @return [Hash]
     def to_h
       {
         app_key: @app_key,
+        identity: @identity,
         environment: @environment,
         base_url: @base_url,
         definitions_url: @definitions_url,
@@ -219,7 +209,6 @@ 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,
@@ -242,5 +231,12 @@ module Toggly
 
       url.end_with?("/") ? url : "#{url}/"
     end
+
+    def normalize_identity(value)
+      return nil if value.nil?
+
+      text = value.to_s
+      text.empty? ? nil : text
+    end
   end
 end