eight_ball 3.1.1 → 3.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c9c10267989e4e3b8d774740ba5310657595a8564a66b5b1d76ec255d4e99be
-  data.tar.gz: 3b17726499ac88f88ae0762b8efe01fdada35dad21dbb92c3070a53d0dba4738
+  metadata.gz: 8b9dcfc459f280769679dbe39a36be388579403e1ea81700ecdb1f78ad42db30
+  data.tar.gz: e819abeae5c7d236f7c08b05c10069d0bbeb76210da389077d2621d0cb558227
 SHA512:
-  metadata.gz: 254787dbc62d7f79a6601098357a2c01a2a9fccaaa5d3a402f6ebd3e842177a1a84ce529e4793a53ed2e6862e33fee6923f78f933cbdc3f13866399bfad3b844
-  data.tar.gz: f0faffb243a73515b8bd584b58f5d1fad96eaae99116113ffc3f058d02249851364365b6de8507648993c3885b27dae50c75bddf986d8ed605642870550a8f1c
+  metadata.gz: b0d24c2ec843bfa235da786579a36fadff617cfbe3abbb0be7085b5b26b7f445a98c81e3a3b1e1f6747698130a894ad418134d41193f94edfd4fa1dfde1ab200
+  data.tar.gz: 1629b60c02126692d6a2c63fe0fd58d66b2d1e5e99e65f117b0e989852d2def11fc996f6e9f16848f8133ffb6691642606a53e86396e584e66b6c1d82381d41c

data/.ruby-version

@@ -1 +1 @@
-3.3.10
+3.4.5

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [3.3.2]
+
+- Fix the `tag-and-release` workflow to create the release tag with the `rewind-community-tagger` GitHub App token (`TAGGER_APP_ID`/`TAGGER_PRIVATE_KEY`) instead of the default `GITHUB_TOKEN`, which the organization `rewind-tag` ruleset does not permit to create `v*` tags (the previous release failed with `Reference update failed`).
+
+## [3.3.1]
+
+- Fix the `tag-and-release` workflow: grant the release job `contents: write` so tag and GitHub Release creation succeed. The repository's default GitHub Actions token permission had been changed to read-only, which broke the release step with `Resource not accessible by integration`.
+
+## [3.3.0]
+
+- Add `percentage` condition for sticky A/B bucketing. Canonical algorithm: `bucket = Integer(SHA256("<flagName>:<value>")[0,8], 16) % 100`, satisfied iff `bucket < percentage`; salted by flag name; buckets on a caller-supplied parameter.
+- Harden JSON unmarshalling: a flag containing an unknown or malformed condition (unknown `type`, or a known type with invalid params) now evaluates to `false` (OFF) and logs a warning, instead of raising and blacking out the entire feature set. Other flags in the blob are unaffected.
+- Add optional top-level `metadata` (`type`, `owner`, `expires_at`) to `Feature`, preserved through marshall/unmarshall and ignored during evaluation.
+
+## [3.2.0]
+
+- Upgrade Ruby to 3.4.5
+
 ## [3.1.1]
 
 - Loosen `required_ruby_version` to `>= 3.2` for Edge compatibility (EC-4270)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    eight_ball (3.1.1)
+    eight_ball (3.3.2)
       awrence (~> 1.1)
       logger (~> 1.7)
       plissken (~> 1.2)

data/README.md

@@ -81,6 +81,26 @@ A Condition must either be `true` or `false`. It describes when a Feature is ena
 - [List](lib/eight_ball/conditions/list.rb): This condition is satisfied if the given value belongs to its list of accepted values.
 - [Never](lib/eight_ball/conditions/never.rb): This condition is never satisfied.
 - [Range](lib/eight_ball/conditions/range.rb): This condition is satisfied if the given value is within the specified range (inclusive).
+- [Percentage](lib/eight_ball/conditions/percentage.rb): This condition is satisfied for a deterministic, sticky subset of subjects sized to `percentage` percent. Bucketing is salted by the flag name so a subject is decorrelated across flags. Wire form: `{"type":"percentage","parameter":"account_id","percentage":<0..100>}`.
+
+#### Sticky percentage bucketing
+
+The `percentage` condition buckets a subject deterministically:
+
+```
+bucket = Integer(Digest::SHA256.hexdigest("#{flagName}:#{value}")[0, 8], 16) % 100
+satisfied  iff  bucket < percentage
+```
+
+The salt is the **flag name**, so the same `account_id` lands in independent buckets across different flags. `value` is stringified before hashing. Any reimplementation must reproduce it exactly to produce the same buckets.
+
+**Re-randomizing requires a rename.** Because the salt is the flag name, an experiment cannot be re-randomized on the same flag. The salt is stable for the life of the name (this is what decorrelates a subject across flags), so a subject's bucket for a given flag is fixed forever. Changing `percentage` only moves the threshold (it does not reshuffle buckets); to draw fresh buckets, rename the flag.
+
+**Requires the bucketing parameter.** Like every parameterized condition, `percentage` requires its bucketing value (the `parameter` it was configured with) in the evaluation bag. If it is absent, evaluation raises `ArgumentError`; supply it or rescue.
+
+### Metadata
+
+A Feature may carry an optional, eval-agnostic `metadata` object (`type`, `owner`, `expires_at`, all optional strings). It is preserved through marshall/unmarshall and ignored during evaluation. Its keys go through the same case conversion as the rest of the wire format (e.g. `expires_at` serializes as `expiresAt`) and come back symbol-keyed after unmarshall.
 
 ### Provider
 

data/eight_ball.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |spec|
   spec.homepage      = 'https://github.com/rewindio/eight_ball'
   spec.license       = 'MIT'
 
-  spec.required_ruby_version = '>= 3.2'
+  spec.required_ruby_version = '>= 3.4'
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(spec|.github|examples)/}) }
   spec.bindir        = 'exe'

data/lib/eight_ball/conditions/base.rb

@@ -21,6 +21,23 @@ module EightBall::Conditions
       state.hash
     end
 
+    # The wire-format hash for this condition. Subclasses declare their fields via
+    # {wire_fields}; the type is the lower-cased class name, which must match a
+    # {EightBall::Conditions.by_name} key so the condition round-trips.
+    def to_wire
+      wire = { type: self.class.name.split('::').last.downcase }
+      wire_fields.each do |field|
+        value = public_send(field)
+        wire[field.to_s] = value unless value.nil?
+      end
+      wire
+    end
+
+    # The attributes this condition serializes, in output order (default: none).
+    def wire_fields
+      []
+    end
+
     protected
 
     def state

data/lib/eight_ball/conditions/conditions.rb

@@ -5,10 +5,13 @@ module EightBall::Conditions
   # @param [String] name The case insensitive name to find the Condition for
   # @return [EightBall::Conditions] the Condition class represented by the given name
   def self.by_name(name)
+    return nil unless name.is_a?(String)
+
     mappings = {
       always: EightBall::Conditions::Always,
       list: EightBall::Conditions::List,
       never: EightBall::Conditions::Never,
+      percentage: EightBall::Conditions::Percentage,
       range: EightBall::Conditions::Range
     }
     mappings[name.downcase.to_sym]

data/lib/eight_ball/conditions/list.rb

@@ -32,6 +32,10 @@ module EightBall::Conditions
       values.include? value
     end
 
+    def wire_fields
+      %i[values parameter]
+    end
+
     protected
 
     def state

data/lib/eight_ball/conditions/opaque.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module EightBall::Conditions
+  # Wraps a condition entry that could not be built (unknown type, invalid params,
+  # or a non-object entry). It is never satisfiable and re-serializes to its
+  # original raw input, so a Feature holding one is failed closed yet round-trips
+  # verbatim. Not registered in {by_name}; produced only as a parse fallback.
+  class Opaque < Base
+    attr_reader :raw
+
+    def initialize(raw)
+      @raw = raw
+    end
+
+    def satisfied?(*)
+      false
+    end
+
+    # Re-emit the original entry unchanged.
+    def to_wire
+      @raw
+    end
+
+    protected
+
+    def state
+      [@raw]
+    end
+  end
+end

data/lib/eight_ball/conditions/percentage.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module EightBall::Conditions
+  # The Percentage Condition is satisfied for a deterministic, sticky subset of
+  # values sized to +percentage+ percent. Bucketing is salted by the owning flag's
+  # name (injected by {EightBall::Feature}), so a value buckets independently per
+  # flag. See the README for the bucket algorithm.
+  class Percentage < Base
+    attr_reader :percentage, :flag_name
+
+    # @param [Hash] options
+    # @option options [Integer] :percentage Integer 0..100. 0 is never
+    #   satisfied; 100 is always satisfied.
+    # @option options [String] :parameter The name of the parameter this Condition
+    #   was created for (eg. "account_id").
+    def initialize(options = {})
+      options ||= {}
+
+      raise ArgumentError, 'Missing value for percentage' if options[:percentage].nil?
+
+      percentage = options[:percentage]
+      percentage = percentage.to_i if percentage.is_a?(Float) && percentage.to_i == percentage
+      unless percentage.is_a?(Integer) && percentage >= 0 && percentage <= 100
+        raise ArgumentError, 'percentage must be an integer between 0 and 100'
+      end
+
+      @percentage = percentage
+      @flag_name = nil
+
+      self.parameter = options[:parameter]
+    end
+
+    # Injected by {EightBall::Feature} so the bucket can be salted by flag name.
+    def flag_name=(name)
+      @flag_name = name
+    end
+
+    # @param value The value of {parameter} for the subject being evaluated.
+    # @return [Boolean] whether the subject falls within the bucket.
+    # @raise [ArgumentError] if {flag_name} was never injected.
+    def satisfied?(value)
+      raise ArgumentError, 'flag_name has not been set on Percentage condition' if @flag_name.nil?
+
+      bucket = Integer(Digest::SHA256.hexdigest("#{@flag_name}:#{value}")[0, 8], 16) % 100
+      bucket < @percentage
+    end
+
+    def wire_fields
+      %i[percentage parameter]
+    end
+
+    protected
+
+    # flag_name is a runtime injection, excluded from equality and the wire form.
+    def state
+      super + [@percentage]
+    end
+  end
+end

data/lib/eight_ball/conditions/range.rb

@@ -45,6 +45,10 @@ module EightBall::Conditions
       value >= min && value <= max
     end
 
+    def wire_fields
+      %i[min max parameter]
+    end
+
     protected
 
     def state

data/lib/eight_ball/feature.rb

@@ -4,7 +4,7 @@ module EightBall
   # A Feature is an element of your application that can be enabled or disabled
   # based on various {EightBall::Conditions}.
   class Feature
-    attr_reader :name, :enabled_for, :disabled_for
+    attr_reader :name, :enabled_for, :disabled_for, :metadata
 
     # Creates a new instance of an Interval RefreshPolicy.
     #
@@ -13,13 +13,17 @@ module EightBall
     #   The Condition(s) that need to be satisfied for the Feature to be enabled.
     # @param disabled_for [Array<EightBall::Conditions>, EightBall::Conditions]
     #   The Condition(s) that need to be satisfied for the Feature to be disabled.
+    # @param metadata [Hash, nil] Optional eval-agnostic metadata
+    #   (e.g. { "type" => ..., "owner" => ..., "expires_at" => ... }).
     #
     # @example A Feature which is always enabled
     #   feature = EightBall::Feature.new 'feature1', EightBall::Conditions::Always
-    def initialize(name, enabled_for = [], disabled_for = [])
+    def initialize(name, enabled_for = [], disabled_for = [], metadata: nil)
       @name = name
-      @enabled_for = Array enabled_for
-      @disabled_for = Array disabled_for
+      @enabled_for = inject_flag_name(Array(enabled_for))
+      @disabled_for = inject_flag_name(Array(disabled_for))
+      @metadata = metadata
+      @un_evaluable = false
     end
 
     # "EightBall, is this Feature enabled?"
@@ -42,18 +46,35 @@ module EightBall
     # @example The Feature's {EightBall::Conditions} require an account ID
     #   feature.enabled? account_id: 123
     def enabled?(parameters = {})
+      return false if @un_evaluable
+
       return true if @enabled_for.empty? && @disabled_for.empty?
       return true if @enabled_for.empty? && !any_satisfied?(@disabled_for, parameters)
 
       any_satisfied?(@enabled_for, parameters) && !any_satisfied?(@disabled_for, parameters)
     end
 
+    # Marks this Feature un-evaluable: {enabled?} always returns +false+ and its
+    # Conditions are never inspected. Used by Marshallers to fail a bad flag closed.
+    #
+    # @return [nil]
+    def un_evaluable!
+      @un_evaluable = true
+      nil
+    end
+
+    # @return [Boolean] whether this Feature has been marked un-evaluable.
+    def un_evaluable?
+      @un_evaluable
+    end
+
     def ==(other)
       name == other.name &&
         enabled_for.size == other.enabled_for.size &&
         enabled_for.all? { |condition| other.enabled_for.any? { |other_condition| condition == other_condition } } &&
         disabled_for.size == other.disabled_for.size &&
-        disabled_for.all? { |condition| other.disabled_for.any? { |other_condition| condition == other_condition } }
+        disabled_for.all? { |condition| other.disabled_for.any? { |other_condition| condition == other_condition } } &&
+        metadata == other.metadata
     end
     alias eql? ==
 
@@ -69,5 +90,16 @@ module EightBall
         condition.satisfied? value
       end
     end
+
+    # Percentage conditions bucket on a salt of the flag name. Give any condition
+    # that accepts it the owning name, duping first so a condition shared across
+    # Features is not re-salted in place. Others pass through untouched.
+    def inject_flag_name(conditions)
+      conditions.map do |condition|
+        next condition unless condition.respond_to?(:flag_name=)
+
+        condition.dup.tap { |copy| copy.flag_name = @name }
+      end
+    end
   end
 end

data/lib/eight_ball/marshallers/json.rb

@@ -62,54 +62,75 @@ module EightBall::Marshallers
     #   marshaller = EightBall::Marshallers::Json.new
     #   marshaller.unmarshall json_string => [Features]
     def unmarshall(json)
-      parsed = JSON.parse(json, symbolize_names: true).to_snake_keys
+      parsed = JSON.parse(json, symbolize_names: true)
 
       raise ArgumentError, 'JSON input was not an array' unless parsed.is_a? Array
 
-      parsed.map do |feature|
-        enabled_for = create_conditions_from_json feature[:enabled_for]
-        disabled_for = create_conditions_from_json feature[:disabled_for]
-
-        EightBall::Feature.new feature[:name], enabled_for, disabled_for
+      parsed.to_snake_keys.filter_map do |feature|
+        build_feature feature
       end
     rescue JSON::ParserError => e
-      EightBall.logger.error { "Failed to parse JSON: #{e.message}" }
+      EightBall.logger.error { "Failed to parse JSON: #{e.message.inspect}" }
       []
     end
 
     private
 
-    def feature_to_hash(feature)
-      hash = {
-        name: feature.name
-      }
+    def build_feature(feature)
+      unless feature.is_a?(Hash)
+        EightBall.logger.warn { "Skipping non-object feature entry: #{feature.inspect}" }
+        return nil
+      end
 
-      hash[:enabled_for] = feature.enabled_for.map { |condition| condition_to_hash(condition) } unless feature.enabled_for.empty?
-      hash[:disabled_for] = feature.disabled_for.map { |condition| condition_to_hash(condition) } unless feature.disabled_for.empty?
+      enabled_for = create_conditions_from_json feature[:enabled_for]
+      disabled_for = create_conditions_from_json feature[:disabled_for]
+      built = EightBall::Feature.new feature[:name], enabled_for, disabled_for, metadata: feature[:metadata]
 
-      hash
+      unparseable = (enabled_for + disabled_for).select { |condition| condition.is_a?(EightBall::Conditions::Opaque) }
+
+      # A nameless flag can't be looked up, and its flag-name-salted conditions raise at eval; fail it closed.
+      if feature[:name].nil?
+        EightBall.logger.warn { 'Feature entry has no name; marking it un-evaluable (OFF)' }
+        built.un_evaluable!
+      elsif !unparseable.empty?
+        EightBall.logger.warn { "Feature #{feature[:name].inspect} has unparseable condition(s) #{unparseable.map(&:raw).inspect}; marking it un-evaluable (OFF)" }
+        built.un_evaluable!
+      end
+
+      built
     end
 
-    def condition_to_hash(condition)
+    def feature_to_hash(feature)
       hash = {
-        type: condition.class.name.split('::').last.downcase
+        name: feature.name
       }
-      condition.instance_variables.each do |var|
-        next unless condition.instance_variable_get(var)
 
-        hash[var.to_s.delete('@')] = condition.instance_variable_get(var)
-      end
+      hash[:enabled_for] = feature.enabled_for.map(&:to_wire) unless feature.enabled_for.empty?
+      hash[:disabled_for] = feature.disabled_for.map(&:to_wire) unless feature.disabled_for.empty?
+      hash[:metadata] = feature.metadata unless feature.metadata.nil?
 
       hash
     end
 
     def create_conditions_from_json(json_conditions)
-      return [] unless json_conditions&.is_a?(Array)
+      return [] if json_conditions.nil?
+      return [EightBall::Conditions::Opaque.new(json_conditions)] unless json_conditions.is_a?(Array)
 
-      json_conditions.map do |condition|
-        condition_class = EightBall::Conditions.by_name condition[:type]
-        condition_class.new condition
-      end
+      json_conditions.map { |condition| build_condition condition }
+    end
+
+    # Build one condition, or wrap anything unbuildable (non-object, unknown type,
+    # invalid params) in an Opaque condition so a single bad entry fails only its
+    # flag closed instead of aborting the whole parse.
+    def build_condition(condition)
+      return EightBall::Conditions::Opaque.new(condition) unless condition.is_a?(Hash)
+
+      condition_class = EightBall::Conditions.by_name condition[:type]
+      return EightBall::Conditions::Opaque.new(condition) if condition_class.nil?
+
+      condition_class.new condition
+    rescue StandardError
+      EightBall::Conditions::Opaque.new(condition)
     end
   end
 end

data/lib/eight_ball/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EightBall
-  VERSION = '3.1.1'
+  VERSION = '3.3.2'
 end

data/lib/eight_ball.rb

@@ -11,6 +11,8 @@ require 'eight_ball/conditions/base'
 require 'eight_ball/conditions/always'
 require 'eight_ball/conditions/list'
 require 'eight_ball/conditions/never'
+require 'eight_ball/conditions/opaque'
+require 'eight_ball/conditions/percentage'
 require 'eight_ball/conditions/range'
 
 require 'eight_ball/marshallers/json'

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: eight_ball
 version: !ruby/object:Gem::Version
-  version: 3.1.1
+  version: 3.3.2
 platform: ruby
 authors:
 - Rewind.io
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-17 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: awrence
@@ -175,6 +174,8 @@ files:
 - lib/eight_ball/conditions/conditions.rb
 - lib/eight_ball/conditions/list.rb
 - lib/eight_ball/conditions/never.rb
+- lib/eight_ball/conditions/opaque.rb
+- lib/eight_ball/conditions/percentage.rb
 - lib/eight_ball/conditions/range.rb
 - lib/eight_ball/configuration_error.rb
 - lib/eight_ball/feature.rb
@@ -187,7 +188,6 @@ homepage: https://github.com/rewindio/eight_ball
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -195,15 +195,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      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: The most cost efficient way to flag features
 test_files: []