restrainer 1.1.1 → 1.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1cd37f4ccca910bb1a619d15cd176f656eae9c28832a493ae0ce14901afabaf
-  data.tar.gz: f55d26dfa66944e52fe1de59d791b7f8215f7afd4b0f13bb2c4cc77833c908d8
+  metadata.gz: fd2f59427326450c5159980282e4d463d275dac6fceaa2a31423a5433ff1502f
+  data.tar.gz: ddf65e8c8915e920a9689f78bce879d6feae920740890acc7c3df5f5c8ccb2d4
 SHA512:
-  metadata.gz: 073671e4736562c7619f732b4fd4af031afc04617e294e4ff779f8b2c4a815c090c5ccc8bb9a7426a8c7777a86258a84c28733458b0e56c34fb2c64aa2763aec
-  data.tar.gz: d48174a050a831d91dc1b237aa63a584ad831936a3c310b999af7ac96f418b06c04251b98963c581a41833a95577b21b5573c7d1c5b53928e9fc432d3a169656
+  metadata.gz: 4166271f5f617a48286024f8e57ab7ebc662c0edfd357ced9e4e40d3998b975db1abcb4db6a1c8de2922ffc57ace7593e752798f39a6f552659877a146fff1b5
+  data.tar.gz: 032357eb1992399ba5d10681b7194e667d852ca000b51dcc6ac592f8d10b4734306225208c918d9c3f73faec11adf690a6d0a1ffccefab57deef09438854437a

data/CHANGELOG.md

@@ -0,0 +1,44 @@
+# 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.3
+
+### Added
+
+- Support for using fractional seconds in the lock timeout.
+
+## 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,8 @@
+[![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)
+[![Gem Version](https://badge.fury.io/rb/restrainer.svg)](https://badge.fury.io/rb/restrainer)
+
 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 +64,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.1
+1.1.3

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
@@ -39,7 +38,7 @@ class Restrainer
     -- Success so add to the list and set a global expiration so the list cleans up after itself.
     if process_count < limit then
       redis.call('zadd', sorted_set, now, process_id)
-      redis.call('expire', sorted_set, ttl)
+      redis.call('pexpire', sorted_set, math.ceil(ttl * 1000))
     end
 
     -- Return the number of processes running before the process was added.
@@ -53,54 +52,69 @@ 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
 
@@ -119,9 +133,12 @@ class Restrainer
   # 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.
+  # @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
@@ -134,17 +151,30 @@ class Restrainer
     process_id
   end
 
-  # release one of the allowed processes. You must pass in a process id returned by the lock method.
+  def lock(process_id = nil, limit: nil)
+  end
+
+  # 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
@@ -156,9 +186,7 @@ class Restrainer
   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)
@@ -168,23 +196,25 @@ class Restrainer
     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
 
     begin
-      redis.evalsha(sha1, [], [key, process_id, throttle_limit, @timeout, Time.now.to_i])
+      redis.evalsha(sha1, [], [key, process_id, throttle_limit, @timeout, Time.now.to_f])
     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.1
+  version: 1.1.3
 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-12-22 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.20
+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,13 +0,0 @@
-# 1.1.1
-
-* Circular reference warning fix
-
-# 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,19 +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'
-
-  redis_opts = {}
-  redis_opts = {url: ENV["REDIS_URL"]} if ENV["REDIS_URL"]
-  Restrainer.redis = Redis.new(redis_opts)
-end