consistent_random 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 22c5eb562537bed9919f77d7d5daeafcd33c8279e91c902d66cfc48b07183a19
+  data.tar.gz: 27000167f87f8b8a02723d8e160d054f59a4d077bf5e22c5834a978e99f6f492
+SHA512:
+  metadata.gz: 6c2d988676f767b138d64e44c6f87f97e08058a5c2fd0a7ce528b4728f624d8c887753182b409c9b343ee3ece9d93f681306fcbecbf7967c5e9c524eb4c95b19
+  data.tar.gz: 7ff4c55d561b0947d7d51d7c96b11e9bf85dcccdc0e11c7f1b6c25923cc3b23696dcdd8ee3069c46c358a81506ab46cc3980a7fc3e3f12929d86c97c7ed19c50

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+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).
+
+## 1.0.0
+
+### Added
+- Initial release.

data/MIT-LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright 2024 Brian Durand
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,128 @@
+# Constant 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)
+[![Gem Version](https://badge.fury.io/rb/consistent_random.svg)](https://badge.fury.io/rb/consistent_random)
+
+## 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.
+
+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.
+
+## 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.
+
+```ruby
+ConsistentRandom.scope do
+  random = ConsistentRandom.new("foobar")
+  a = random.rand(100) # Generates a random number between 0 and 99 tied to "foobar"
+  b = random.rand(100) # Same random number as 'a', because "foobar" is reused
+  a == b # => true
+end
+```
+
+This can be used to implement things like feature flags for rolling out new features on a percentage of your requests.
+
+```ruby
+class FeatureFlag
+  def initialize(name, roll_out_percentage)
+    @name = name
+    @roll_out_percentage = roll_out_percentage
+  end
+
+  def enabled?
+    ConsistentRandom.new("FeatureFlag.#{@name}").rand < @roll_out_percentage
+  end
+end
+```
+
+Checking a feature flag will return the same value within a scope.
+
+```ruby
+class MyService
+  def call(arg)
+    if FeatureFlag.new("new_feature", 0.1).enabled?
+      # Do something new 10% of the time
+    else
+      # Do something else
+    end
+  end
+end
+
+ConsistentRandom.scope do
+  things.each do |thing|
+    MyService.new.call(thing) # You won't get a mix of new and old behavior within this iteration
+  end
+end
+```
+
+If there is no scope defined, the random values will be different each time for different instances of `ConsistentRandom`. So, if your code is executed outside of a scope, it will still work but with random values being generated rather than consistent values.
+
+```ruby
+random = ConsistentRandom.new("foobar")
+random.rand != random.rand # => true
+```
+
+### 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.
+
+#### Rack Middleware
+
+In a Rack application:
+
+```ruby
+Rack::Builder.app do
+  use ConsistentRandom::RackMiddleware
+  run MyApp
+end
+```
+
+Or in a Rails application:
+
+```ruby
+# config/application.rb
+config.middleware.use ConsistentRandom::RackMiddleware
+```
+
+#### Sidekiq Middleware
+
+Add the middleware to your Sidekiq server configuration:
+
+```ruby
+Sidekiq.configure_server do |config|
+  config.server_middleware do |chain|
+    chain.add ConsistentRandom::SidekiqMiddleware
+  end
+end
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "consistent_random"
+```
+
+Then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install consistent_random
+```
+
+## Contributing
+
+Open a pull request on [GitHub](https://github.com/bdurand/consistent_random).
+
+Please use the [standardrb](https://github.com/testdouble/standard) syntax and lint your code with `standardrb --fix` before submitting.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/consistent_random.gemspec

@@ -0,0 +1,41 @@
+Gem::Specification.new do |spec|
+  spec.name = "consistent_random"
+  spec.version = File.read(File.expand_path("../VERSION", __FILE__)).strip
+  spec.authors = ["Brian Durand"]
+  spec.email = ["bbdurand@gmail.com"]
+
+  spec.summary = "Generates consistent random values within a defined scope, ensuring deterministic behavior for use in feature rollouts and other scoped operations."
+
+  spec.homepage = "https://github.com/bdurand/consistent_random"
+  spec.license = "MIT"
+
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => spec.homepage,
+    "changelog_uri" => "#{spec.homepage}/blob/main/CHANGELOG.md"
+  }
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  ignore_files = %w[
+    .
+    Appraisals
+    Gemfile
+    Gemfile.lock
+    Rakefile
+    config.ru
+    assets/
+    bin/
+    gemfiles/
+    spec/
+  ]
+  spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| ignore_files.any? { |path| f.start_with?(path) } }
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 2.5"
+
+  spec.add_development_dependency "bundler"
+end

data/lib/consistent_random/context.rb

@@ -0,0 +1,21 @@
+# 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

data/lib/consistent_random/rack_middleware.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+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)
+      @app = app
+    end
+
+    def call(env)
+      ConsistentRandom.scope do
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/consistent_random/sidekiq_middleware.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class ConsistentRandom
+  # Sidekiq server middleware that wraps job execution with consistent random scope
+  # so that you can generate consistent random values within a job.
+  class SidekiqMiddleware
+    if defined?(Sidekiq::ServerMiddleware)
+      include Sidekiq::ServerMiddleware
+    end
+
+    def call(job_instance, job_payload, queue)
+      ConsistentRandom.scope do
+        yield
+      end
+    end
+  end
+end

data/lib/consistent_random.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "consistent_random/context"
+require_relative "consistent_random/rack_middleware"
+require_relative "consistent_random/sidekiq_middleware"
+
+class ConsistentRandom
+  class << self
+    # Define a scope where consistent random values will be generated.
+    #
+    # @yield block of code to execute within the scope
+    # @return the result of the block
+    def scope
+      existing_context = Thread.current[:consistent_random_context]
+      begin
+        context = Context.new(existing_context)
+        Thread.current[:consistent_random_context] = context
+        yield
+      ensure
+        Thread.current[:consistent_random_context] = existing_context
+      end
+    end
+  end
+
+  # @param name [Object] a name used to identifuy a consistent random value
+  def initialize(name)
+    @name = name
+  end
+
+  # Generate a random float. This method works the same as Kernel#rand.
+  #
+  # @param max [Integer, Range] the maximum value of the random float or a range indicating
+  #  the minimum and maximum values.
+  # @return [Numeric] a random number. If the max argument is a range, then the result will be
+  #   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)
+  end
+
+  # Generate a random integer. 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)
+  end
+
+  # Generate a random number generator for the given name. The generator will always
+  # have the same seed within a scope.
+  #
+  # @return [Random] a random number generator
+  def random
+    Random.new(current_context.seed(@name))
+  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
+  end
+
+  private
+
+  def current_context
+    Thread.current[:consistent_random_context] || Context.new
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: consistent_random
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Brian Durand
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-10-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email:
+- bbdurand@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE.txt
+- README.md
+- VERSION
+- consistent_random.gemspec
+- lib/consistent_random.rb
+- lib/consistent_random/context.rb
+- lib/consistent_random/rack_middleware.rb
+- lib/consistent_random/sidekiq_middleware.rb
+homepage: https://github.com/bdurand/consistent_random
+licenses:
+- MIT
+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
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Generates consistent random values within a defined scope, ensuring deterministic
+  behavior for use in feature rollouts and other scoped operations.
+test_files: []