consistent_random 1.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22c5eb562537bed9919f77d7d5daeafcd33c8279e91c902d66cfc48b07183a19
-  data.tar.gz: 27000167f87f8b8a02723d8e160d054f59a4d077bf5e22c5834a978e99f6f492
+  metadata.gz: 53c979ca8b32310fc3357e231ed29a029964396e19f1bafd0ac44220be535a1a
+  data.tar.gz: 35e7431d888b473db4063a8cec225314aae0e445740388a97ee9296d5a559c03
 SHA512:
-  metadata.gz: 6c2d988676f767b138d64e44c6f87f97e08058a5c2fd0a7ce528b4728f624d8c887753182b409c9b343ee3ece9d93f681306fcbecbf7967c5e9c524eb4c95b19
-  data.tar.gz: 7ff4c55d561b0947d7d51d7c96b11e9bf85dcccdc0e11c7f1b6c25923cc3b23696dcdd8ee3069c46c358a81506ab46cc3980a7fc3e3f12929d86c97c7ed19c50
+  metadata.gz: cbc32f5cbbf0ad48742e9ede2e14a187530a32b2e832a0b9af5b293c9716f3e9893795601853ccc4b32ad9cbb24b70decb88f9b94f2c17b7ba687bfca2cd1810
+  data.tar.gz: 80ebaa9bfd1ba8519e755369cf76184e89c97c88302979a7b4fe0d176fbb107a3734a9fa2aa820ad80d0f5f3b370f7755b721080be7ec79219df48a0e6c5d3a9

data/CHANGELOG.md

@@ -4,6 +4,24 @@ 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.1.0
+
+### Added
+
+- Added optional seed block to the Rack middleware to allow for custom seed values based on the request.
+- Added helper method `ConsistentRandom::SidekiqMiddleware.install` to install both the client and server middlewares in one call.
+
+## 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,13 +6,25 @@
 
 ## 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.
+Consistent Random is designed to simplify feature rollouts and other scenarios where you need to generate random values, but need those values to remain consistent within defined contexts.
+
+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.
+
+## Table of Contents
+- [Usage](#usage)
+- [Middlewares](#middlewares)
+  - [Rack Middleware](#rack-middleware)
+  - [Sidekiq Middleware](#sidekiq-middleware)
+  - [ActiveJob](#activejob)
+- [Installation](#installation)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Usage
 
-To generate consistent random values, you need to define a scope. You do this with the `ConsistentRandom.scope` method. Within the scope block, calls to `ConsistentRandom` will return the same random values for the same name.
+To generate consistent random values, you need to define a scope. Scopes are defined with the `ConsistentRandom.scope` method. Within the scope block, calls to `ConsistentRandom` will return the same random values for the same name. Scopes are isolated to the block in which they're defined, meaning random values are consistent within each scoped block but independent across threads or separate invocations.
 
 ```ruby
 ConsistentRandom.scope do
@@ -65,11 +77,11 @@ random = ConsistentRandom.new("foobar")
 random.rand != random.rand # => true
 ```
 
-### Middlewares
+## Middlewares
 
-The gem provides built-in middlewares for Rack and Sidekiq, automatically scoping requests and jobs. This ensures that consistent random values are generated within the request/job context.
+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.
 
-#### Rack Middleware
+### Rack Middleware
 
 In a Rack application:
 
@@ -87,14 +99,109 @@ Or in a Rails application:
 config.middleware.use ConsistentRandom::RackMiddleware
 ```
 
-#### Sidekiq Middleware
+You can also specify a seed value based on the request. This can be useful if you want to generate random values based on a specific request attribute, such as the current user.
+
+```ruby
+Rack::Builder.app do
+  use ConsistentRandom::RackMiddleware, ->(env) { env["warden"].user.id }
+  run MyApp
+end
+```
 
-Add the middleware to your Sidekiq server configuration:
+If the seed block returns `nil`, then a random seed will be generated for the request.
+
+### Sidekiq Middleware
+
+Add the middlewares to your Sidekiq in an initializer:
+
+```ruby
+ConsistentRandom::SidekiqMiddleware.install
+```
+
+This will install both the client and server middleware. You can also install them manually if you need more control on the order of the middlewares. You should install the client middleware on both the server and client configurations.
 
 ```ruby
 Sidekiq.configure_server do |config|
   config.server_middleware do |chain|
-    chain.add ConsistentRandom::SidekiqMiddleware
+    chain.prepend ConsistentRandom::SidekiqMiddleware
+  end
+
+  config.client_middleware do |chain|
+    chain.add ConsistentRandom::SidekiqClientMiddleware
+  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
+```
+
+You can still specify a custom seed value in your worker if, for example, you want to ensure that values are consistent based on a user when the job is not enqueued from a Rack request.
+
+```ruby
+class MyWorker
+  include Sidekiq::Job
+
+  def perform(user_id)
+    ConsistentRandom.scope(user_id) do
+      ...
+    end
+  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
+```
+
+You can still specify a custom seed value in your worker if, for example, you want to ensure that values are consistent based on a user when the job is not enqueued from a Rack request.
+
+```ruby
+class MyJob < ApplicationJob
+  def perform(user_id)
+    ConsistentRandom.scope(user_id) do
+      ...
+    end
   end
 end
 ```

data/VERSION

@@ -1 +1 @@
-1.0.0
+2.1.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/rack_middleware.rb

@@ -4,12 +4,19 @@ class ConsistentRandom
   # Rack middleware that wraps a request with consistent random scope
   # so that you can generate consistent random values within a request.
   class RackMiddleware
-    def initialize(app)
+    # @param app [Object] Rack application to wrap
+    # @param seed_block [Proc, #call, nil] block to generate seed for the request
+    #   If provided, the block will be called with the request env and
+    #   the return value will be used as the seed for the request. You can
+    #   use this to generate a seed based on the request state..
+    def initialize(app, seed_block = nil)
       @app = app
+      @seed_block = seed_block
     end
 
     def call(env)
-      ConsistentRandom.scope do
+      seed = @seed_block.call(env) if @seed_block
+      ConsistentRandom.scope(seed) do
         @app.call(env)
       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

@@ -8,8 +8,28 @@ class ConsistentRandom
       include Sidekiq::ServerMiddleware
     end
 
+    class << self
+      def install
+        Sidekiq.configure_server do |config|
+          config.server_middleware do |chain|
+            chain.prepend ConsistentRandom::SidekiqMiddleware
+          end
+
+          config.client_middleware do |chain|
+            chain.add ConsistentRandom::SidekiqClientMiddleware
+          end
+        end
+
+        Sidekiq.configure_client do |config|
+          config.client_middleware do |chain|
+            chain.add ConsistentRandom::SidekiqClientMiddleware
+          end
+        end
+      end
+    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_relative "consistent_random/rack_middleware"
-require_relative "consistent_random/sidekiq_middleware"
+require "digest/sha1"
+require "securerandom"
 
 class ConsistentRandom
+  SEED_DIVISOR = (2**64 - 1).to_f
+  private_constant :SEED_DIVISOR
+
+  autoload :RackMiddleware, "consistent_random/rack_middleware"
+  autoload :SidekiqMiddleware, "consistent_random/sidekiq_middleware"
+  autoload :SidekiqClientMiddleware, "consistent_random/sidekiq_client_middleware"
+  autoload :ActiveJob, "consistent_random/active_job"
+
   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.1.0
 platform: ruby
 authors:
 - Brian Durand
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-06 00:00:00.000000000 Z
+date: 2024-10-27 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