consistent_random 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 980cb06e9d5c20085243ecb114932f744343830090a6148db527d5c685458c46
-  data.tar.gz: 8872129783254ab5cd4ae70f4051ceb5901c4d28852168dfa0e4b229c8541d13
+  metadata.gz: 53c979ca8b32310fc3357e231ed29a029964396e19f1bafd0ac44220be535a1a
+  data.tar.gz: 35e7431d888b473db4063a8cec225314aae0e445740388a97ee9296d5a559c03
 SHA512:
-  metadata.gz: 99ad2eb1aaf87bdee2aa1c1052d73c8e9db13e392c9d501c9d8d445644902414a0602ef4f8da3c63199cd55e2da0519bd15dd48b7070bbec59414506d181613c
-  data.tar.gz: 76a775637c84fa12fb56bf6437943ffdc59cb7a454ec1fa9af44fda471d614237e61297c18251744fb45d5de2c0d18b8ec84ef1a3603b4e56b16ce954bb4a5e1
+  metadata.gz: cbc32f5cbbf0ad48742e9ede2e14a187530a32b2e832a0b9af5b293c9716f3e9893795601853ccc4b32ad9cbb24b70decb88f9b94f2c17b7ba687bfca2cd1810
+  data.tar.gz: 80ebaa9bfd1ba8519e755369cf76184e89c97c88302979a7b4fe0d176fbb107a3734a9fa2aa820ad80d0f5f3b370f7755b721080be7ec79219df48a0e6c5d3a9

data/CHANGELOG.md

@@ -4,6 +4,13 @@ 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

data/README.md

@@ -8,11 +8,23 @@
 
 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.
 
+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,35 @@ 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
+```
+
+If the seed block returns `nil`, then a random seed will be generated for the request.
 
-Add the middlewares to your Sidekiq configuration:
+### 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
 
@@ -119,6 +152,20 @@ class MyWorker
 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.
@@ -147,6 +194,18 @@ class MyJob < ApplicationJob
 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
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/VERSION

@@ -1 +1 @@
-2.0.0
+2.1.0

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_middleware.rb

@@ -8,6 +8,26 @@ 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(job_payload["consistent_random_seed"]) do
         yield

data/lib/consistent_random.rb

@@ -3,15 +3,15 @@
 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
 
+  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.
     #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: consistent_random
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Brian Durand
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-24 00:00:00.000000000 Z
+date: 2024-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler