restrainer 1.1.0 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e999370930d2d5686a75214e30aa63223b828f77ba5ba94d48506f5afcca8c9
-  data.tar.gz: 494b772ddc967646f15f3ba1db809fd34eb6f12a0714242f327326e33af1b648
+  metadata.gz: c49c2e29f3d29970f0975f8219d99dc74a79668f263b5c923ab0eb2ff92f8fae
+  data.tar.gz: 7af2876a48e9a34d4ff3aad0cd5fb7b12bc5e20c7ee2e875760a59276cc7c601
 SHA512:
-  metadata.gz: b2b8dd65c7cd2a5d96daa8c67fe2d7b3a71a77a9035ff00a065b693d179ec1d71f6084ab1d1d8b98f5b9d62bda7628e0d898a0c32d637bc1fcb02032e3e6d7fa
-  data.tar.gz: e4c85a817f9e0f9b2445e000b8f1f3c2cc79d74023020b8f02fa9f9895e61ee528f6b69aacc88dde8a3fbe6c04cb10f494075e7188bacf37e049486e516a2513
+  metadata.gz: 23d0627b6b1cca6b1c8c84ffeb20c595570c2918db27c73ce0a4a9aa158f8cf4df67cdd331d2e3b001106185c8adacffd070b215e2f47ac69b013cee1f3d11c0
+  data.tar.gz: c7fc3e5188fa06628d7ab0f5fb4b27b74db917bb95f32ca76875c40be1052237ce83e9018c4bde079e99c09c19514dc1825a2df765f62787c910733e32e4c3f5

data/CHANGELOG.md

@@ -0,0 +1,33 @@
+# 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.1.2
+
+### Changed
+- Redis instance will now default to a Redis instance with the default options
+  instead of throwing an error if it was not set.
+- Minumum Ruby version set to 2.5
+
+## 1.1.1
+
+### Fixed
+- Circular reference warning
+
+## 1.1.0
+
+### Added
+- Expose manually locking and unlocking processes.
+- Allow passing in a redis connection in the constructor.
+
+## 1.0.1
+
+### Fixed
+- Use Lua script to avoid race conditions and ensure no extra processes slip through.
+
+## 1.0.0
+
+### Added
+- Initial release.

data/MIT_LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2015 WHI, Inc.
+Copyright (c) 2015 Brian Durand
 
 MIT License
 

data/README.md

@@ -1,3 +1,7 @@
+[![Continuous Integration](https://github.com/bdurand/restrainer/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/bdurand/restrainer/actions/workflows/continuous_integration.yml)
+[![Regression Test](https://github.com/bdurand/restrainer/actions/workflows/regression_test.yml/badge.svg)](https://github.com/bdurand/restrainer/actions/workflows/regression_test.yml)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
+
 This gem provides a method of throttling calls across processes that can be very useful if you have to call an external service with limited resources.
 
 A [redis server](http://redis.io/) is required to use this gem.
@@ -59,3 +63,31 @@ restrainer = Restrainer.new(:my_service, 100, timeout: 10)
 ```
 
 This gem does clean up after itself nicely, so that it won't ever leave unused data lying around in redis.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'restrainer'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install restrainer
+```
+
+## Contributing
+
+Open a pull request on GitHub.
+
+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

@@ -1 +1 @@
-1.1.0
+1.1.2

data/lib/restrainer.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require 'redis'
-require 'securerandom'
+require "redis"
+require "securerandom"
 
 # Redis backed throttling mechanism to ensure that only a limited number of processes can
 # be executed at any one time.
@@ -14,7 +14,6 @@ require 'securerandom'
 # If more than the specified number of processes as identified by the name argument is currently
 # running, then the throttle block will raise an error.
 class Restrainer
-
   attr_reader :name, :limit
 
   ADD_PROCESS_SCRIPT = <<-LUA
@@ -41,7 +40,7 @@ class Restrainer
       redis.call('zadd', sorted_set, now, process_id)
       redis.call('expire', sorted_set, ttl)
     end
-    
+
     -- Return the number of processes running before the process was added.
     return process_count
   LUA
@@ -53,60 +52,75 @@ class Restrainer
   class ThrottledError < StandardError
   end
 
+  @redis = nil
+
   class << self
     # Either configure the redis instance using a block or yield the instance. Configuring with
     # a block allows you to use things like connection pools etc. without hard coding a single
     # instance.
     #
-    # Example: `Restrainer.redis { redis_pool.instance }`
+    # @param block [Proc] A block that returns a redis instance.
+    # @return [Redis] The redis instance.
+    # @example
+    #   Restrainer.redis { redis_pool.instance }
     def redis(&block)
       if block
         @redis = block
-      elsif defined?(@redis) && @redis
-        @redis.call
       else
-        raise "#{self.class.name}.redis not configured"
+        unless @redis
+          client = Redis.new
+          @redis = lambda { client }
+        end
+        @redis.call
       end
     end
 
-    # Set the redis instance to a specific instance. It is usually preferable to use the block
-    # form for configurating the instance so that it can be evaluated at runtime.
+    # Set the redis instance to a specific instance. It is usually preferable to use
+    # the block form for configurating the instance so that it can be evaluated at
+    # runtime.
     #
-    # Example: `Restrainer.redis = Redis.new`
+    # @param conn [Redis]
+    # @return [void]
+    # @example
+    #   Restrainer.redis = Redis.new
     def redis=(conn)
-      @redis = lambda{ conn }
+      @redis = lambda { conn }
     end
   end
 
-  # Create a new restrainer. The name is used to identify the Restrainer and group processes together.
-  # You can create any number of Restrainers with different names.
+  # Create a new restrainer. The name is used to identify the Restrainer and group
+  # processes together. You can create any number of Restrainers with different names.
   #
-  # The required limit parameter specifies the maximum number of processes that will be allowed to execute the
-  # throttle block at any point in time.
+  # The required limit parameter specifies the maximum number of processes that
+  # will be allowed to execute the throttle block at any point in time.
   #
-  # The timeout parameter is used for cleaning up internal data structures so that jobs aren't orphaned
-  # if their process is killed. Processes will automatically be removed from the running jobs list after the
-  # specified number of seconds. Note that the Restrainer will not handle timing out any code itself. This
+  # The timeout parameter is used for cleaning up internal data structures so that
+  # jobs aren't orphaned if their process is killed. Processes will automatically
+  # be removed from the running jobs list after the specified number of seconds.
+  # Note that the Restrainer will not handle timing out any code itself. This
   # value is just used to insure the integrity of internal data structures.
   def initialize(name, limit:, timeout: 60, redis: nil)
     @name = name
     @limit = limit
     @timeout = timeout
-    @key = "#{self.class.name}.#{name.to_s}"
-    @redis ||= redis
+    @key = "#{self.class.name}.#{name}"
+    @redis = redis
   end
 
-  # Wrap a block with this method to throttle concurrent execution. If more than the alotted number
-  # of processes (as identified by the name) are currently executing, then a Restrainer::ThrottledError
-  # will be raised.
+  # Wrap a block with this method to throttle concurrent execution. If more than the
+  # alotted number of processes (as identified by the name) are currently executing,
+  # then a Restrainer::ThrottledError will be raised.
   #
-  # The limit argument can be used to override the value set in the constructor.
+  # @param limit [Integer] The maximum number of processes that can be executing
+  #   at any one time. Defaults to the value passed to the constructor.
+  # @return [void]
+  # @raise [Restrainer::ThrottledError] If the throttle would be exceeded.
   def throttle(limit: nil)
     limit ||= self.limit
 
     # limit of less zero is no limit; limit of zero is allow none
     return yield if limit < 0
-    
+
     process_id = lock!(limit: limit)
     begin
       yield
@@ -114,15 +128,18 @@ class Restrainer
       release!(process_id)
     end
   end
-  
+
   # Obtain a lock on one the allowed processes. The method returns a process
   # identifier that must be passed to the release! to release the lock.
   # You can pass in a unique identifier if you already have one.
   #
-  # Raises a Restrainer::ThrottledError if the lock cannot be obtained.
-  #
-  # The limit argument can be used to override the value set in the constructor.
-  def lock!(process_id = nil, limit: limit)
+  # @param process_id [String] A unique identifier for the process. If none is
+  #   passed, a unique value will be generated.
+  # @param limit [Integer] The maximum number of processes that can be executing
+  #   at any one time. Defaults to the value passed to the constructor.
+  # @return [String] The process identifier.
+  # @raise [Restrainer::ThrottledError] If the throttle would be exceeded.
+  def lock!(process_id = nil, limit: nil)
     process_id ||= SecureRandom.uuid
     limit ||= self.limit
 
@@ -133,18 +150,28 @@ class Restrainer
     add_process!(redis, process_id, limit)
     process_id
   end
-  
-  # release one of the allowed processes. You must pass in a process id returned by the lock method.
+
+  # Release one of the allowed processes. You must pass in a process id
+  # returned by the lock method.
+  #
+  # @param process_id [String] The process identifier returned by the lock call.
+  # @return [Boolean] True if the process was released, false if it was not found.
   def release!(process_id)
-    remove_process!(redis, process_id) unless process_id.nil?
+    return false if process_id.nil?
+
+    remove_process!(redis, process_id)
   end
 
   # Get the number of processes currently being executed for this restrainer.
+  #
+  # @return [Integer] The number of processes currently being executed.
   def current
     redis.zcard(key).to_i
   end
-  
-  # Clear all locks
+
+  # Clear all locks.
+  #
+  # @return [void]
   def clear!
     redis.del(key)
   end
@@ -154,29 +181,29 @@ class Restrainer
   def redis
     @redis || self.class.redis
   end
-  
+
   # Hash key in redis to story a sorted set of current processes.
-  def key
-    @key
-  end
+  attr_reader :key
 
   # Add a process to the currently run set.
   def add_process!(redis, process_id, throttle_limit)
-    process_count = eval_script(redis, process_id, throttle_limit)    
+    process_count = eval_script(redis, process_id, throttle_limit)
     if process_count >= throttle_limit
       raise ThrottledError.new("#{self.class}: #{@name} already has #{process_count} processes running")
     end
   end
 
-  # Remove a process to the currently run set.
+  # Remove a process to the currently run set. Returns true if the process was removed.
   def remove_process!(redis, process_id)
-    redis.zrem(key, process_id)
+    result = redis.zrem(key, process_id)
+    result = true if result == 1
+    result
   end
 
   # Evaluate and execute a Lua script on the redis server.
   def eval_script(redis, process_id, throttle_limit)
     sha1 = @add_process_sha1
-    if sha1 == nil
+    if sha1.nil?
       sha1 = redis.script(:load, ADD_PROCESS_SCRIPT)
       @add_process_sha1 = sha1
     end
@@ -184,7 +211,7 @@ class Restrainer
     begin
       redis.evalsha(sha1, [], [key, process_id, throttle_limit, @timeout, Time.now.to_i])
     rescue Redis::CommandError => e
-      if e.message.include?('NOSCRIPT')
+      if e.message.include?("NOSCRIPT")
         sha1 = redis.script(:load, ADD_PROCESS_SCRIPT)
         @add_process_sha1 = sha1
         retry

data/restrainer.gemspec

@@ -1,27 +1,34 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-
 Gem::Specification.new do |spec|
-  spec.name          = "restrainer"
-  spec.version       = File.read(File.expand_path("../VERSION", __FILE__)).chomp
-  spec.authors       = ["We Heart It", "Brian Durand"]
-  spec.email         = ["dev@weheartit.com", "bbdurand@gmail.com"]
-  spec.summary       = "Code for throttling workloads so as not to overwhelm external services"
-  spec.description   = "Code for throttling workloads so as not to overwhelm external services."
-  spec.homepage      = "https://github.com/weheartit/restrainer"
-  spec.license       = "MIT"
-  spec.files         = `git ls-files`.split($/)
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.name = "restrainer"
+  spec.version = File.read(File.expand_path("VERSION", __dir__)).strip
+  spec.authors = ["Brian Durand"]
+  spec.email = ["bbdurand@gmail.com"]
+
+  spec.summary = "Code for throttling workloads so as not to overwhelm external services"
+  spec.homepage = "https://github.com/bdurand/restrainer"
+  spec.license = "MIT"
+
+  # 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
+    bin/
+    gemfiles/
+    spec/
+  ]
+  spec.files = Dir.chdir(__dir__) 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.0'
+  spec.required_ruby_version = ">= 2.5"
 
-  spec.add_dependency('redis')
+  spec.add_dependency("redis")
 
-  spec.add_development_dependency "bundler", "~> 1.3"
-  spec.add_development_dependency "rake"
-  spec.add_development_dependency "rspec"
-  spec.add_development_dependency "timecop"
+  spec.add_development_dependency "bundler"
 end

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: restrainer
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.2
 platform: ruby
 authors:
-- We Heart It
 - Brian Durand
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2019-07-17 00:00:00.000000000 Z
+date: 2023-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -27,48 +26,6 @@ dependencies:
         version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
-- !ruby/object:Gem::Dependency
-  name: rake
-  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'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  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'
-- !ruby/object:Gem::Dependency
-  name: timecop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -81,29 +38,24 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Code for throttling workloads so as not to overwhelm external services.
+description:
 email:
-- dev@weheartit.com
 - bbdurand@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- CHANGE_LOG.md
+- CHANGELOG.md
 - MIT_LICENSE.txt
 - README.md
-- Rakefile
 - VERSION
 - lib/restrainer.rb
 - restrainer.gemspec
-- spec/restrainer_spec.rb
-- spec/spec_helper.rb
-homepage: https://github.com/weheartit/restrainer
+homepage: https://github.com/bdurand/restrainer
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -111,17 +63,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.0'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.4.12
+signing_key:
 specification_version: 4
 summary: Code for throttling workloads so as not to overwhelm external services
-test_files:
-- spec/restrainer_spec.rb
-- spec/spec_helper.rb
+test_files: []

data/.gitignore

@@ -1,17 +0,0 @@
-*.gem
-*.rbc
-.bundle
-.config
-.yardoc
-Gemfile.lock
-InstalledFiles
-_yardoc
-coverage
-doc/
-lib/bundler/man
-pkg
-rdoc
-spec/reports
-test/tmp
-test/version_tmp
-tmp

data/CHANGE_LOG.md

@@ -1,9 +0,0 @@
-# 1.1.0
-
-* Expose manually locking and unlocking processes.
-
-* Allow passing in a redis connection in the constructor.
-
-# 1.0.1
-
-* Use Lua script to avoid race conditions and ensure no extra processes slip through.

data/Rakefile

@@ -1,6 +0,0 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-task :default => :spec

data/spec/restrainer_spec.rb

@@ -1,138 +0,0 @@
-# frozen_string_literal: true
-
-require 'spec_helper'
-
-describe Restrainer do
-
-  before(:each) do
-    Restrainer.new(:restrainer_test, limit: 1).clear!
-  end
-
-  it "should have a name and max_processes" do
-    restrainer = Restrainer.new(:restrainer_test, limit: 1)
-    expect(restrainer.name).to eq(:restrainer_test)
-    expect(restrainer.limit).to eq(1)
-  end
-
-  it "should run a block!" do
-    restrainer = Restrainer.new(:restrainer_test, limit: 1)
-    x = nil
-    expect(restrainer.throttle{ x = restrainer.current }).to eq(1)
-    expect(x).to eq(1)
-    expect(restrainer.current).to eq(0)
-  end
-
-  it "should throw an error if too many processes are already running" do
-    restrainer = Restrainer.new(:restrainer_test, limit: 5)
-    x = nil
-    restrainer.throttle do
-      restrainer.throttle do
-        restrainer.throttle do
-          restrainer.throttle do
-            restrainer.throttle do
-              expect(lambda{restrainer.throttle{ x = 1 }}).to raise_error(Restrainer::ThrottledError)
-            end
-          end
-        end
-      end
-    end
-    expect(x).to eq(nil)
-  end
-
-  it "should not throw an error if the number of processes is under the limit" do
-    restrainer = Restrainer.new(:restrainer_test, limit: 2)
-    x = nil
-    restrainer.throttle do
-      restrainer.throttle{ x = 1 }
-    end
-    expect(x).to eq(1)
-  end
-
-  it "should let the throttle method override the limit" do
-    restrainer = Restrainer.new(:restrainer_test, limit: 1)
-    x = nil
-    restrainer.throttle do
-      restrainer.throttle(limit: 2){ x = 1 }
-    end
-    expect(x).to eq(1)
-  end
-
-  it "should allow processing to be turned off entirely by setting the limit to zero" do
-    restrainer = Restrainer.new(:restrainer_test, limit: 1)
-    x = nil
-    expect(lambda{restrainer.throttle(limit: 0){ x = 1 }}).to raise_error(Restrainer::ThrottledError)
-    expect(x).to eq(nil)
-  end
-
-  it "should allow the throttle to be opened up entirely with a negative limit" do
-    restrainer = Restrainer.new(:restrainer_test, limit: 0)
-    x = nil
-    restrainer.throttle(limit: -1){ x = 1 }
-    expect(x).to eq(1)
-  end
-
-  it "should cleanup the running process list if orphaned processes exist" do
-    restrainer = Restrainer.new(:restrainer_test, limit: 1, timeout: 10)
-    x = nil
-    restrainer.throttle do
-      Timecop.travel(11) do
-        restrainer.throttle{ x = 1 }
-      end
-    end
-    expect(x).to eq(1)
-  end
-
-  it "should be able to lock! and release! processes manually" do
-    restrainer = Restrainer.new(:restrainer_test, limit: 5)
-    p1 = restrainer.lock!
-    begin
-      p2 = restrainer.lock!
-      begin
-        p3 = restrainer.lock!
-        begin
-          p4 = restrainer.lock!
-          begin
-            p5 = restrainer.lock!
-            begin
-              expect{ restrainer.lock! }.to raise_error(Restrainer::ThrottledError)
-            ensure
-              restrainer.release!(p5)
-            end
-            p6 = restrainer.lock!
-            restrainer.release!(p6)
-          ensure
-            restrainer.release!(p4)
-          end
-        ensure
-          restrainer.release!(p3)
-        end
-      ensure
-        restrainer.release!(p2)
-      end
-    ensure
-      restrainer.release!(p1)
-    end
-  end
-
-  it "should be able to pass in the process id" do
-    restrainer = Restrainer.new(:restrainer_test, limit: 1)
-    expect(restrainer.lock!("foo")).to eq "foo"
-  end
-
-  it "should not get a lock! if the limit is 0" do
-    restrainer = Restrainer.new(:restrainer_test, limit: 0)
-    expect{ restrainer.lock! }.to raise_error(Restrainer::ThrottledError)
-  end
-
-  it "should get a lock! if the limit is negative" do
-    restrainer = Restrainer.new(:restrainer_test, limit: -1)
-    process_id = restrainer.lock!
-    expect(process_id).to eq nil
-    restrainer.release!(nil)
-  end
-
-  it "should be able to override the limit in lock!" do
-    restrainer = Restrainer.new(:restrainer_test, limit: 0)
-    restrainer.lock!(limit: 1)
-  end
-end

data/spec/spec_helper.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-require File.expand_path('../../lib/restrainer', __FILE__)
-require 'timecop'
-
-RSpec.configure do |config|
-  config.run_all_when_everything_filtered = true
-  config.filter_run :focus
-
-  # Run specs in random order to surface order dependencies. If you find an
-  # order dependency and want to debug it, you can fix the order by providing
-  # the seed, which is printed after each run.
-  #     --seed 1234
-  config.order = 'random'
-
-  Restrainer.redis = Redis.new
-end