consistent_random 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87b396dd6b089d0fb4c99777531eb0824a4d78b2180bce9eeee6484efd06ddbd
-  data.tar.gz: f5ade642f1222468d68ca326cfad4a206b9e74b97fe786e2497d13e9a67a0459
+  metadata.gz: 1fd62d51e962f285e32463d2b1854f22a3d7fee49e7cb6f44cb3f09dc6af9654
+  data.tar.gz: f2dd72200a420d2b36dbae1336f477cafe971993772b0d5afac5a269856a3a7e
 SHA512:
-  metadata.gz: 8ab235ba4d2b6b447e05614cd603c739461e1d3e0efad6c088ff07b966b6daf207f76c413a49dc00d78125ee12f1ca252b91cba01154d00441bc03dd00523628
-  data.tar.gz: 4a5ca92427978a6f496bc75b057c6982bf7a9eac870eef9139ab5e1cce36aab236c2da6acaf50b551d483d696ce6235d063ba4883a37110569b8f4395571e5e7
+  metadata.gz: 56111c5d7231bf39fadca5ef39f1bef04b23df47962646774355f18c9a543dfec3f74eb5e3ad0a32acd0db66d684f8852eb2161cca4c4d5bb5a10fe729726103
+  data.tar.gz: 8daa15435772ad90dcb34c1797edaece7dcf78c34f088a532b843fa9c371f062fb9cd969f99d8afe40702f11c8bcbd6f439d6efc71ab60a1b50aa72f92cfcf97

data/CHANGELOG.md

@@ -4,6 +4,19 @@ 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).
 
+## 2.3.0
+
+### Fixed
+
+- `ConsistentRandom#rand` can no longer return an out of range value. Previously there was a very small chance (about 1 in 2⁵³) that a seed could produce a value of exactly 1.0, causing `rand` to return 1.0, `rand(n)` to return `n`, and `rand(range)` to return a value above the range. Random floats are now derived from the top 53 bits of the seed, guaranteeing a uniform value in `[0, 1)`. **Note:** this changes the exact values generated for existing seeds (the distribution is unchanged), so percentage rollouts in flight during an upgrade may reassign.
+- Fixed distribution bias in `ConsistentRandom#rand` for ranges with negative bounds. Values were truncated toward zero instead of floored, so for a range like `-5..5` the minimum value was never returned and zero was returned twice as often as other values.
+- `ConsistentRandom#rand` now raises an `ArgumentError` for empty ranges (e.g. `5..1`) and non-numeric ranges instead of returning out of range values or raising a `NoMethodError`.
+- `ConsistentRandom::Testing#bytes` now raises an `ArgumentError` for empty strings, which were previously accepted but silently ignored, producing non-deterministic values in tests.
+
+### Changed
+
+- `ConsistentRandom.current_seed` is now public API; it can be used to propagate a scope into threads or fibers, which do not inherit the fiber-local scope state.
+
 ## 2.2.0
 
 ### Added

data/README.md

@@ -14,6 +14,7 @@ For example, consider rolling out a new feature to a subset of requests. You may
 
 ## Table of Contents
 - [Usage](#usage)
+  - [Threads and Fibers](#threads-and-fibers)
 - [Middlewares](#middlewares)
   - [Rack Middleware](#rack-middleware)
   - [Sidekiq Middleware](#sidekiq-middleware)
@@ -78,6 +79,24 @@ random = ConsistentRandom.new("foobar")
 random.rand != random.rand # => true
 ```
 
+### Threads and Fibers
+
+Scopes are stored in fiber-local state, so they do not propagate to threads or fibers spawned inside the scope block. Code running in a `Thread.new` block, an `Enumerator` (which runs on its own fiber), or Rails' `load_async` will not see the surrounding scope and will generate independent random values.
+
+If you need consistent values in spawned threads or fibers, capture the current seed and re-establish the scope inside them:
+
+```ruby
+ConsistentRandom.scope do
+  seed = ConsistentRandom.current_seed
+
+  Thread.new do
+    ConsistentRandom.scope(seed) do
+      # Values here are consistent with the parent scope.
+    end
+  end
+end
+```
+
 ## Middlewares
 
 The gem provides built-in middlewares for Rack, Sidekiq, and ActiveJob. These middlewares allow you to automatically scope web requests and propagate consistent random values from the original request to asynchronous jobs.
@@ -139,7 +158,7 @@ Sidekiq.configure_client do |config|
 end
 ```
 
-Consistent random values will be propagated from the original request to any Sidekiq jobs so you will get consistent behavior on any ansynchronous jobs. You can disable this behavior on a job by setting the `conistent_random` sidekiq option to `false`:
+Consistent random values will be propagated from the original request to any Sidekiq jobs so you will get consistent behavior on any asynchronous jobs. You can disable this behavior on a job by setting the `consistent_random` sidekiq option to `false`:
 
 ```ruby
 class MyWorker
@@ -224,7 +243,7 @@ end
 
 # You can also specify values for specific names.
 # If a values isn't specified, it will return a random value.
-ConsistentRandom.testing(foo: 0.5, bar: 0.8) do
+ConsistentRandom.testing.rand(foo: 0.5, bar: 0.8) do
   expect(ConsistentRandom.new("foo").rand).to eq(0.5)
   expect(ConsistentRandom.new("bar").rand).to eq(0.8)
 end

data/VERSION

@@ -1 +1 @@
-2.2.0
+2.3.0

data/consistent_random.gemspec

@@ -35,7 +35,7 @@ Gem::Specification.new do |spec|
 
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = ">= 2.5"
+  spec.required_ruby_version = ">= 2.6"
 
   spec.add_development_dependency "bundler"
 end

data/lib/consistent_random/active_job.rb

@@ -2,10 +2,12 @@
 
 class ConsistentRandom
   module ActiveJob
-    def self.included(base)
-      attr_reader :consistent_random_seeds
+    # @return [String, nil] the seed deserialized from the job data
+    # @api private
+    attr_reader :consistent_random_seed
 
-      base.around_perform :peform_with_consistent_random_scope
+    def self.included(base)
+      base.around_perform :perform_with_consistent_random_scope
 
       base.class_attribute :inherit_consistent_random_scope, instance_writer: false
     end
@@ -21,14 +23,14 @@ class ConsistentRandom
 
     def deserialize(job_data)
       super
-      @consistent_random_seeds = job_data["consistent_random_seed"]
+      @consistent_random_seed = job_data["consistent_random_seed"]
     end
 
     private
 
-    def peform_with_consistent_random_scope(&block)
-      seeds = consistent_random_seeds unless inherit_consistent_random_scope == false
-      ConsistentRandom.scope(seeds, &block)
+    def perform_with_consistent_random_scope(&block)
+      seed = consistent_random_seed unless inherit_consistent_random_scope == false
+      ConsistentRandom.scope(seed, &block)
     end
   end
 end

data/lib/consistent_random/testing.rb

@@ -65,7 +65,7 @@ class ConsistentRandom
     def bytes(options, &block)
       options = validate_bytes(options)
       unless options
-        raise ArgumentError.new("Argument must be a String or a Hash with String values")
+        raise ArgumentError.new("Argument must be a non-empty String or a Hash with non-empty String values")
       end
 
       @bytes_hash = options.default ? options.merge(@bytes_hash) : @bytes_hash.merge(options)
@@ -151,9 +151,9 @@ class ConsistentRandom
     end
 
     def validate_bytes(options)
-      if options.is_a?(Hash) && options.values.all? { |value| value.is_a?(String) }
+      if options.is_a?(Hash) && options.values.all? { |value| value.is_a?(String) && !value.empty? }
         options.each_with_object({}) { |(key, value), hash| hash[key.to_s] = value.encode(Encoding::ASCII_8BIT) }
-      elsif options.is_a?(String)
+      elsif options.is_a?(String) && !options.empty?
         Hash.new(options)
       end
     end

data/lib/consistent_random.rb

@@ -4,8 +4,11 @@ require "digest/sha1"
 require "securerandom"
 
 class ConsistentRandom
-  SEED_DIVISOR = (2**64 - 1).to_f
-  private_constant :SEED_DIVISOR
+  # Divisor for converting the top 53 bits of a seed into a Float. Using 53 bits
+  # ensures the result is exactly representable so values are uniform in [0, 1)
+  # and can never round up to 1.0.
+  FLOAT_DIVISOR = 2.0**53
+  private_constant :FLOAT_DIVISOR
 
   autoload :RackMiddleware, "consistent_random/rack_middleware"
   autoload :SidekiqMiddleware, "consistent_random/sidekiq_middleware"
@@ -15,7 +18,7 @@ class ConsistentRandom
   class << self
     # Define a scope where consistent random values will be generated.
     #
-    # @param seeds [String, Symbol, Integer, Array<String>, Array<Integer>, nil] optional value to
+    # @param seed [String, Symbol, Integer, Array<String>, Array<Integer>, nil] optional value to
     #   use for generating random numbers. By default a random value will be generated. If the
     #   scope is nested in another scope block, then the seed from the parent scope will be used
     #   by default.
@@ -29,7 +32,7 @@ class ConsistentRandom
       when String, Symbol, Integer
         seed.to_s
       when Array
-        seed.map { |s| s.to_s }.join("\x1C")
+        seed.join("\x1C")
       else
         raise ArgumentError, "Invalid seed value: #{seed.inspect}"
       end
@@ -43,11 +46,11 @@ class ConsistentRandom
     end
 
     # Get the current seed used to generate random numbers. This will return nil if called
-    # outside of a scope.
+    # outside of a scope. The value can be passed to a new scope to generate the same
+    # random values in another thread or fiber.
     #
     # @return [String, nil] the seed value for the current scope
     #  or nil if called outside of a scope.
-    # @api private
     def current_seed
       Thread.current[:consistent_random_seed]
     end
@@ -74,7 +77,7 @@ class ConsistentRandom
   #   a number in that range. If max is an number, then it will be an integer between 0 and that
   #   value. Otherwise, it will be a float between 0 and 1.
   def rand(max = nil)
-    value = Testing.current&.rand_for(name) || seed / SEED_DIVISOR
+    value = Testing.current&.rand_for(name) || (seed >> 11) / FLOAT_DIVISOR
     case max
     when nil
       value
@@ -92,7 +95,6 @@ class ConsistentRandom
   # @return [String] a string of random bytes.
   def bytes(size)
     test_bytes = Testing.current&.bytes_for(name)
-    test_bytes = nil if test_bytes&.empty?
     chunk_size = (test_bytes ? test_bytes.length : 20)
 
     bytes = []
@@ -147,11 +149,19 @@ class ConsistentRandom
       raise ArgumentError, "Cannot generate random value for infinite range"
     end
 
+    unless min.is_a?(Numeric) && max.is_a?(Numeric)
+      raise ArgumentError, "Cannot generate random value for non-numeric range"
+    end
+
+    if min > max || (range.exclude_end? && min == max)
+      raise ArgumentError, "Cannot generate random value for empty range"
+    end
+
     int_range = min.is_a?(Integer) && max.is_a?(Integer)
     max += 1 if int_range && range.include?(max)
 
     val = (value * (max - min)) + min
-    int_range ? val.to_i : val
+    int_range ? val.floor : val
   end
 end
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: consistent_random
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Brian Durand
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-20 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -24,7 +23,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
 email:
 - bbdurand@gmail.com
 executables: []
@@ -49,7 +47,6 @@ metadata:
   homepage_uri: https://github.com/bdurand/consistent_random
   source_code_uri: https://github.com/bdurand/consistent_random
   changelog_uri: https://github.com/bdurand/consistent_random/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -57,15 +54,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Generates consistent random values within a defined scope, ensuring deterministic
   behavior for use in feature rollouts and other scoped operations.