consistent_random 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22c5eb562537bed9919f77d7d5daeafcd33c8279e91c902d66cfc48b07183a19
-  data.tar.gz: 27000167f87f8b8a02723d8e160d054f59a4d077bf5e22c5834a978e99f6f492
+  metadata.gz: 980cb06e9d5c20085243ecb114932f744343830090a6148db527d5c685458c46
+  data.tar.gz: 8872129783254ab5cd4ae70f4051ceb5901c4d28852168dfa0e4b229c8541d13
 SHA512:
-  metadata.gz: 6c2d988676f767b138d64e44c6f87f97e08058a5c2fd0a7ce528b4728f624d8c887753182b409c9b343ee3ece9d93f681306fcbecbf7967c5e9c524eb4c95b19
-  data.tar.gz: 7ff4c55d561b0947d7d51d7c96b11e9bf85dcccdc0e11c7f1b6c25923cc3b23696dcdd8ee3069c46c358a81506ab46cc3980a7fc3e3f12929d86c97c7ed19c50
+  metadata.gz: 99ad2eb1aaf87bdee2aa1c1052d73c8e9db13e392c9d501c9d8d445644902414a0602ef4f8da3c63199cd55e2da0519bd15dd48b7070bbec59414506d181613c
+  data.tar.gz: 76a775637c84fa12fb56bf6437943ffdc59cb7a454ec1fa9af44fda471d614237e61297c18251744fb45d5de2c0d18b8ec84ef1a3603b4e56b16ce954bb4a5e1

data/CHANGELOG.md

@@ -4,6 +4,17 @@ 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.0.0
+
+### Changed
+
+- `ConsistentRandom#rand` uses a faster hashing algorithm for generating random values. This will make the value consistent across different Ruby versions and platforms.
+
+### Added
+
+- Added `ConsistentRandom::SidekiqClientMiddleware` to allow persisting consistent random seeds to Sidekiq jobs so behavior is consistent between when jobs are enqueued and when they are executed.
+- Added `ConsistentRandom::ActiveJob` for hooking into ActiveJob to persist consistent random seeds to jobs.
+
 ## 1.0.0
 
 ### Added

data/README.md

@@ -1,4 +1,4 @@
-# Constant Random
+# Consistent Random
 
 [![Continuous Integration](https://github.com/bdurand/consistent_random/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/bdurand/consistent_random/actions/workflows/continuous_integration.yml)
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
@@ -6,9 +6,9 @@
 
 ## Introduction
 
-This Ruby gem allows you to generate consistent random values tied to a specific name within a defined scope. It ensures that random behavior remains consistent within a particular context, such as handling feature rollouts.
+This Ruby gem allows you to generate consistent random values tied to a specific name within a defined scope. It ensures that random behavior remains consistent within a particular context.
 
-For example, consider rolling out a new feature to a subset of requests, such as enabling the feature for 10% of requests. You want to randomize which requests get the new feature, but ensure that within each request, the feature is consistently enabled or disabled across all actions. This gem allows you to achieve that by tying random values to specific names and defining a scope. Within that scope, the same value will be consistently generated for each named variable.
+For example, consider rolling out a new feature to a subset of requests. You may want to do this to allow testing a new feature by only enabling it for 10% of requests. You want to randomize which requests get the new feature, but ensure that within each request, the feature is consistently enabled or disabled across all actions. This gem allows you to achieve that by tying random values to specific names and defining a scope. Within that scope, the same value will be consistently generated for each named variable.
 
 ## Usage
 
@@ -89,7 +89,7 @@ config.middleware.use ConsistentRandom::RackMiddleware
 
 #### Sidekiq Middleware
 
-Add the middleware to your Sidekiq server configuration:
+Add the middlewares to your Sidekiq configuration:
 
 ```ruby
 Sidekiq.configure_server do |config|
@@ -97,6 +97,54 @@ Sidekiq.configure_server do |config|
     chain.add ConsistentRandom::SidekiqMiddleware
   end
 end
+
+Sidekiq.configure_client do |config|
+  config.client_middleware do |chain|
+    chain.add ConsistentRandom::SidekiqClientMiddleware
+  end
+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`:
+
+```ruby
+class MyWorker
+  include Sidekiq::Job
+
+  sidekiq_options consistent_random: false
+
+  def perform
+    # Each job will use it's own random scope.
+  end
+end
+```
+
+### ActiveJob
+
+You can use consistent random values in your ActiveJob jobs by including the `ConsistentRandom::ActiveJob` module.
+
+```ruby
+class MyJob < ApplicationJob
+  include ConsistentRandom::ActiveJob
+
+  def perform
+    # Job will use consistent random values using the same scope from when it was enqueued.
+  end
+end
+```
+
+Jobs will inherit the same consistent random values as the request that spawned the job. You can force a job to use it's own random scope by setting the `consistent_random` option to `false`:
+
+```ruby
+class MyJob < ApplicationJob
+  include ConsistentRandom::ActiveJob
+
+  self.inherit_consistent_random_scope = false
+
+  def perform
+    # Job will use it's own random scope.
+  end
+end
 ```
 
 ## Installation

data/VERSION

@@ -1 +1 @@
-1.0.0
+2.0.0

data/lib/consistent_random/active_job.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class ConsistentRandom
+  module ActiveJob
+    def self.included(base)
+      attr_reader :consistent_random_seeds
+
+      base.around_perform :peform_with_consistent_random_scope
+
+      base.class_attribute :inherit_consistent_random_scope, instance_writer: false
+    end
+
+    def serialize
+      job_data = super
+      if inherit_consistent_random_scope != false
+        seed = ConsistentRandom.current_seed
+        job_data["consistent_random_seed"] = seed unless seed.nil?
+      end
+      job_data
+    end
+
+    def deserialize(job_data)
+      super
+      @consistent_random_seeds = 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)
+    end
+  end
+end

data/lib/consistent_random/sidekiq_client_middleware.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class ConsistentRandom
+  # Sidekiq client middleware that adds the current seeds to the job options. These
+  # seeds will be deserialized and used when the job is run on the server so that
+  # the client and server can share consistent random values.
+  class SidekiqClientMiddleware
+    if defined?(Sidekiq::ClientMiddleware)
+      include Sidekiq::ClientMiddleware
+    end
+
+    def call(job_class_or_string, job, queue, redis_pool)
+      unless job["consistent_random"] == false
+        seed = ConsistentRandom.current_seed
+        job["consistent_random_seed"] = seed unless seed.nil?
+      end
+      yield
+    end
+  end
+end

data/lib/consistent_random/sidekiq_middleware.rb

@@ -9,7 +9,7 @@ class ConsistentRandom
     end
 
     def call(job_instance, job_payload, queue)
-      ConsistentRandom.scope do
+      ConsistentRandom.scope(job_payload["consistent_random_seed"]) do
         yield
       end
     end

data/lib/consistent_random.rb

@@ -1,25 +1,56 @@
 # frozen_string_literal: true
 
-require_relative "consistent_random/context"
+require "digest/sha1"
+require "securerandom"
+
 require_relative "consistent_random/rack_middleware"
 require_relative "consistent_random/sidekiq_middleware"
+require_relative "consistent_random/sidekiq_client_middleware"
+require_relative "consistent_random/active_job"
 
 class ConsistentRandom
+  SEED_DIVISOR = (2**64 - 1).to_f
+  private_constant :SEED_DIVISOR
+
   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
+    #   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.
     # @yield block of code to execute within the scope
     # @return the result of the block
-    def scope
-      existing_context = Thread.current[:consistent_random_context]
+    def scope(seed = nil)
+      existing_seed = Thread.current[:consistent_random_seed]
+      seed_value = case seed
+      when nil
+        existing_seed || SecureRandom.hex
+      when String, Symbol, Integer
+        seed.to_s
+      when Array
+        seed.map { |s| s.to_s }.join("\x1C")
+      else
+        raise ArgumentError, "Invalid seed value: #{seed.inspect}"
+      end
+
       begin
-        context = Context.new(existing_context)
-        Thread.current[:consistent_random_context] = context
+        Thread.current[:consistent_random_seed] = seed_value
         yield
       ensure
-        Thread.current[:consistent_random_context] = existing_context
+        Thread.current[:consistent_random_seed] = existing_seed
       end
     end
+
+    # Get the current seed used to generate random numbers. This will return nil if called
+    # outside of a scope.
+    #
+    # @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
   end
 
   # @param name [Object] a name used to identifuy a consistent random value
@@ -27,7 +58,9 @@ class ConsistentRandom
     @name = name
   end
 
-  # Generate a random float. This method works the same as Kernel#rand.
+  # Generate a random number. The same number will be generated within a scope block.
+  # This method works the same as Kernel#rand. It will generate a consistent value even
+  # across Ruby versions and platforms.
   #
   # @param max [Integer, Range] the maximum value of the random float or a range indicating
   #  the minimum and maximum values.
@@ -35,35 +68,73 @@ 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)
-    random.rand(max || 1.0)
+    value = seed / SEED_DIVISOR
+    case max
+    when nil
+      value
+    when Numeric
+      (value * max.to_i).to_i
+    when Range
+      cap_to_range(value, max)
+    end
   end
 
-  # Generate a random integer. This method works the same as Random#bytes.
+  # Generate a random array of bytes. The same number will be generated within a scope block.
+  # This method works the same as Random#bytes.
   #
   # @param size [Integer] the number of bytes to generate.
   # @return [String] a string of random bytes.
   def bytes(size)
-    random.bytes(size)
+    bytes = []
+    ((size + 19) / 20).times { |i| bytes << seed_hash("#{@name}#{i}").to_s }
+    bytes.join[0, size]
   end
 
-  # Generate a random number generator for the given name. The generator will always
-  # have the same seed within a scope.
+  # Generate a seed that can be used to generate random numbers. This seed will be
+  # return a consistent value when called within a scope.
   #
-  # @return [Random] a random number generator
-  def random
-    Random.new(current_context.seed(@name))
+  # @return [Integer] a 64 bit integer for seeding random values
+  def 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.
   def ==(other)
-    other.is_a?(self.class) && other.random = random
+    other.is_a?(self.class) && other.seed = seed
+  end
+
+  # Generate a random number generator for the given name. The generator will always
+  # have the same seed within a scope.
+  #
+  # This value is dependent on the Ruby Random class and may not generate consistent values
+  # across Ruby versions and platforms.
+  #
+  # @return [Random] a random number generator
+  def random
+    Random.new(seed)
   end
 
   private
 
-  def current_context
-    Thread.current[:consistent_random_context] || Context.new
+  def seed_hash(name)
+    random_seed = self.class.current_seed || SecureRandom.hex
+    Digest::SHA1.digest("#{random_seed}\x1C#{name}")
+  end
+
+  def cap_to_range(value, range)
+    min = range.begin
+    max = range.end
+    if min.nil? || max.nil?
+      raise ArgumentError, "Cannot generate random value for infinite 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
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: consistent_random
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Brian Durand
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-06 00:00:00.000000000 Z
+date: 2024-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -37,8 +37,9 @@ files:
 - VERSION
 - consistent_random.gemspec
 - lib/consistent_random.rb
-- lib/consistent_random/context.rb
+- lib/consistent_random/active_job.rb
 - lib/consistent_random/rack_middleware.rb
+- lib/consistent_random/sidekiq_client_middleware.rb
 - lib/consistent_random/sidekiq_middleware.rb
 homepage: https://github.com/bdurand/consistent_random
 licenses:

data/lib/consistent_random/context.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-class ConsistentRandom
-  class Context
-    # @api private
-    attr_reader :seeds
-
-    # @param existing_context [Context, nil] Existing context to copy generators from
-    def initialize(existing_context = nil)
-      @seeds = (existing_context ? existing_context.seeds.dup : {})
-    end
-
-    # Return a random number generator for the given name and seed
-    #
-    # @param name [String] Name of the generator
-    # @return [Random] Random number generator
-    def seed(name)
-      @seeds[name] ||= Random.new_seed
-    end
-  end
-end