consistent_random 2.1.1 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e59a824de4f8d0a629bf033a675d48f3f5d40b6ffda07f0cf32c8f39d50dc7a2
-  data.tar.gz: '08df13b6bbc9005e38fef21e05768b23eb1c1cbe36cda08694a0ce16bd800baa'
+  metadata.gz: 1fd62d51e962f285e32463d2b1854f22a3d7fee49e7cb6f44cb3f09dc6af9654
+  data.tar.gz: f2dd72200a420d2b36dbae1336f477cafe971993772b0d5afac5a269856a3a7e
 SHA512:
-  metadata.gz: 31a8b9bb4996cefee885f4c2c3c251931b86db801443bbe9cafc383c882e7e4ae8be133a8d1d6b5032dcd1422c9906b33c2813ad1f857a0e81b2c81074a7a29d
-  data.tar.gz: 76ae572f27d9e1ca92216e77d878b75bd934f0c81a03abdb1e811181a49fdd0e22231ce1a236f019274701aa35d80c16d3e3e6a898a853df85294a82edb561bd
+  metadata.gz: 56111c5d7231bf39fadca5ef39f1bef04b23df47962646774355f18c9a543dfec3f74eb5e3ad0a32acd0db66d684f8852eb2161cca4c4d5bb5a10fe729726103
+  data.tar.gz: 8daa15435772ad90dcb34c1797edaece7dcf78c34f088a532b843fa9c371f062fb9cd969f99d8afe40702f11c8bcbd6f439d6efc71ab60a1b50aa72f92cfcf97

data/CHANGELOG.md

@@ -4,6 +4,26 @@ 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
+
+- Added `ConsistentRandom.testing` method to allow for deterministic testing of random values.
+- Added `ConsistentRandom#name` method to return the name used for seeding the random value.
+
 ## 2.1.1
 
 ### Fixed

data/README.md

@@ -14,10 +14,12 @@ 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)
   - [ActiveJob](#activejob)
+- [Testing](#testing)
 - [Installation](#installation)
 - [Contributing](#contributing)
 - [License](#license)
@@ -77,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.
@@ -138,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
@@ -206,6 +226,36 @@ class MyJob < ApplicationJob
 end
 ```
 
+## Testing
+
+The gem provides a `ConsistentRandom.testing` method to allow for deterministic testing of random values. This method can be used to set fixed values within the block so that your tests will produce consistent results.
+
+```ruby
+# Specify that all random values should be 0.5
+ConsistentRandom.testing.rand(0.5) do
+  expect(ConsistentRandom.new("foo").rand).to eq(0.5)
+  expect(ConsistentRandom.new("bar").rand).to eq(0.5)
+
+  # The rand value must be between 0 and 1, but it will be scaled to fit
+  # any size or range specified for `rand`.
+  expect(ConsistentRandom.new("foo").rand(10)).to eq(5)
+end
+
+# You can also specify values for specific names.
+# If a values isn't specified, it will return a random value.
+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
+
+# You can also specify values for the `bytes` and `seed` methods. The methods
+# for setting test valus can be chained together.
+ConsistentRandom.testing.bytes(foo: "bar").seed(baz: 123) do
+  expect(ConsistentRandom.new("foo").bytes(6)).to eq("barbar")
+  expect(ConsistentRandom.new("baz").seed).to eq(123)
+end
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/VERSION

@@ -1 +1 @@
-2.1.1
+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

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+class ConsistentRandom
+  # This class returns an object that can be used to generate deterministic values
+  # for use in testing.
+  #
+  # @example
+  #  ConsistentRandom.testing.rand(foo: 0.5).bytes(foo: "foobar").seed(123) do
+  #    expect(ConsistentRandom.new("foo").rand).to eq(0.5)
+  #    expect(ConsistentRandom.new("bar").rand).not_to eq(0.5)
+  #
+  #    expect(ConsistentRandom.new("foo").bytes(12)).to eq("foobarfoobar")
+  #
+  #    expect(ConsistentRandom.new("foo").seed).to eq(123)
+  #  end
+  class ConsistentRandom::Testing
+    class << self
+      # Get the testing object if any for the current block.
+      #
+      # @return [ConsistentRandom::Testing, nil] the testing object or nil if not set
+      # @api private
+      def current
+        Thread.current[:consistent_random_testing]
+      end
+    end
+
+    def initialize
+      @rand_hash = {}
+      @bytes_hash = {}
+      @seed_hash = {}
+    end
+
+    # Set the random value returned by ConsistentRandom#rand.
+    #
+    # param options [Float, Hash<String, Float>] the value to return for rand. If a Float is given
+    #  then it will be used as the value for all calls to rand. If a Hash is given then the value
+    #  will only be returned for ConsitentRandom objects with the names specified in the keys.
+    # @yield block of code to execute with the test values.
+    # @return [ConsistentRandom::Testing, Object] If a block is specified, then the result
+    #   of the block is returned. Otherwise the testing object is returned so that you can
+    #   chain calls to set up more test values.
+    def rand(options, &block)
+      options = validate_rand(options)
+      unless options
+        raise ArgumentError.new("Argument must be a Float between 0 and 1 or a Hash with Float values")
+      end
+
+      @rand_hash = options.default ? options.merge(@rand_hash) : @rand_hash.merge(options)
+      if block
+        use(&block)
+      else
+        self
+      end
+    end
+
+    # Set the random bytes returned by ConsistentRandom#bytes.
+    #
+    # param options [String, Hash<String, String>] the value to return for bytes. If a String is given
+    #  then it will be used as the value for all calls to bytes. If a Hash is given then the value
+    #  will only be returned for ConsitentRandom objects with the names specified in the keys.
+    # @yield block of code to execute with the test values.
+    # @return [ConsistentRandom::Testing, Object] If a block is specified, then the result
+    #   of the block is returned. Otherwise the testing object is returned so that you can
+    #   chain calls to set up more test values.
+    def bytes(options, &block)
+      options = validate_bytes(options)
+      unless options
+        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)
+      if block
+        use(&block)
+      else
+        self
+      end
+    end
+
+    # Set the seed value returned by ConsistentRandom#seed.
+    #
+    # param options [Integer, Hash<String, Integer>] the value to return for seed. If an Integer is given
+    #   then it will be used as the value for all calls to seed. If a Hash is given then the value
+    #   will only be returned for ConsitentRandom objects with the names specified in the keys.
+    # @yield block of code to execute with the test values.
+    # @return [ConsistentRandom::Testing, Object] If a block is specified, then the result
+    #   of the block is returned. Otherwise the testing object is returned so that you can
+    #   chain calls to set up more test
+    def seed(options, &block)
+      options = validate_seed(options)
+      unless options
+        raise ArgumentError.new("Argument must be an Integer or a Hash with Integer values")
+      end
+
+      @seed_hash = options.default ? options.merge(@seed_hash) : @seed_hash.merge(options)
+      if block
+        use(&block)
+      else
+        self
+      end
+    end
+
+    # Use the test values within a block of code.
+    #
+    # @yield block of code to execute with the test values.
+    # @return [Object] the result of the block
+    def use(&block)
+      save_val = Thread.current[:consistent_random_testing]
+      begin
+        Thread.current[:consistent_random_testing] = self
+        yield
+      ensure
+        Thread.current[:consistent_random_testing] = save_val
+      end
+    end
+
+    # Get the test value for rand.
+    #
+    # @param name [String] the name of the ConsistentRandom object
+    # @return [Float, nil] the test value for rand if there is a test value for the name
+    # @api private
+    def rand_for(name)
+      @rand_hash[name]
+    end
+
+    # Get the test value for bytes.
+    #
+    # @param name [String] the name of the ConsistentRandom object
+    # @return [String, nil] the test value for bytes if there is a test value for the name
+    # @api private
+    def bytes_for(name)
+      @bytes_hash[name]
+    end
+
+    # Get the test value for seed.
+    #
+    # @param name [String] the name of the ConsistentRandom object
+    # @return [Integer, nil] the test value for seed if there is a test value for the name
+    # @api private
+    def seed_for(name)
+      @seed_hash[name]
+    end
+
+    private
+
+    def validate_rand(options)
+      if options.is_a?(Hash) && options.values.all? { |value| value.is_a?(Float) && (0...1).cover?(value) }
+        options.each_with_object({}) { |(key, value), hash| hash[key.to_s] = value }
+      elsif options.is_a?(Float) && (0...1).cover?(options)
+        Hash.new(options)
+      end
+    end
+
+    def validate_bytes(options)
+      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) && !options.empty?
+        Hash.new(options)
+      end
+    end
+
+    def validate_seed(options)
+      if options.is_a?(Hash) && options.values.all? { |value| value.is_a?(Integer) }
+        options.each_with_object({}) { |(key, value), hash| hash[key.to_s] = value }
+      elsif options.is_a?(Integer)
+        Hash.new(options)
+      end
+    end
+  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,19 +46,25 @@ 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
+
+    def testing
+      Testing.new
+    end
   end
 
+  attr_reader :name
+
   # @param name [Object] a name used to identifuy a consistent random value
   def initialize(name)
-    @name = name
+    @name = (name.is_a?(String) ? name.dup : name.to_s).freeze
   end
 
   # Generate a random number. The same number will be generated within a scope block.
@@ -68,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 = seed / SEED_DIVISOR
+    value = Testing.current&.rand_for(name) || (seed >> 11) / FLOAT_DIVISOR
     case max
     when nil
       value
@@ -85,8 +94,13 @@ class ConsistentRandom
   # @param size [Integer] the number of bytes to generate.
   # @return [String] a string of random bytes.
   def bytes(size)
+    test_bytes = Testing.current&.bytes_for(name)
+    chunk_size = (test_bytes ? test_bytes.length : 20)
+
     bytes = []
-    ((size + 19) / 20).times { |i| bytes << seed_hash("#{@name}#{i}").to_s }
+    (size / chunk_size.to_f).ceil.times do |i|
+      bytes << (test_bytes || seed_hash("#{name}#{i}").to_s)
+    end
     bytes.join[0, size]
   end
 
@@ -95,13 +109,17 @@ class ConsistentRandom
   #
   # @return [Integer] a 64 bit integer for seeding random values
   def seed
-    hash = seed_hash(@name)
+    test_seed = Testing.current&.seed_for(name)
+    return test_seed if test_seed
+
+    hash = seed_hash(name)
     hash.byteslice(0, 8).unpack1("Q>")
   end
 
   # @return [Boolean] true if the other object is a ConsistentRandom that returns
   #   the same random number generator. If called outside of a scope, then it will
-  #   always return false.
+  #   always return false. The functionality is designed to be similar to the
+  #   same behavior as Random.
   def ==(other)
     other.is_a?(self.class) && other.seed == seed
   end
@@ -131,10 +149,20 @@ 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
+
+require_relative "consistent_random/testing"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: consistent_random
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  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: []
@@ -41,6 +39,7 @@ files:
 - lib/consistent_random/rack_middleware.rb
 - lib/consistent_random/sidekiq_client_middleware.rb
 - lib/consistent_random/sidekiq_middleware.rb
+- lib/consistent_random/testing.rb
 homepage: https://github.com/bdurand/consistent_random
 licenses:
 - MIT
@@ -48,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
@@ -56,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.