cutoff 0.4.1 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ac27ce016591276e55afa82f64c08de370a969cb6552cc0d5ae69093d3a9e0c
-  data.tar.gz: 31e989979ae04de967a22e8d2457d6da654862603f380dd7521e415c9220148b
+  metadata.gz: 7ab1dba25fcad8b3f65d816d1740dbd2c2e1b6102f4009e19fa36fd0baf8236c
+  data.tar.gz: 7a86b6dbf5c0d0bd6631281687c674ec21dc19102097bee351b8e13a3b2a53c3
 SHA512:
-  metadata.gz: 4241c63fc4c647c44860aa0781e2966a5eadc1d7edea259851018308d1877d664c46a8d90bd5553f725d2e1fa5f767995b0f27327482bf2ce5128701908aa684
-  data.tar.gz: 64d599559055f6d8b3c384b88b5268b02317784bd44fd6be2384fd3c56b1f9da5a9cfb435c4af05c083ba20af6d8865f0c73a8fc46afff261ad70d43fc9c35e4
+  metadata.gz: e23dcd3d2fa5b44bcc3630aa4976cff12eef9771f4c1010a2cd12cc820ef5caabf1e54b0dba83de60af1ce2142eea4d53bae7c79e5c02ac34ec91d1e07cfba62
+  data.tar.gz: bfc01027499784eaeaf89f5bc4114483bf89bc41eb2db6668a297ace172b58136ae58b214df6f0929a027729aff417ff56b9fb4dfacd45cb979d280b675f3868

data/.yardopts

@@ -1,3 +1,4 @@
 --markup markdown
 --markup-provider redcarpet
 --no-private
+--no-api

data/CHANGELOG.md

@@ -7,17 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.1] - 2022-09-06
+
+### Changed
+
+- Upgrade rubocop to latest version #12 justinhoward
+- Add codecov.io code coverage #11 justinhoward
+- Complete yard documentation and fix warnings #13 justinhoward
+
+### Fixed
+
+- Pull cutoff option from job, not worker #14 mperham
+
+## [0.5.0] - 2022-08-10
+
+### Changed
+
+- Use CLOCK_MONOTONIC instead of CLOCK_MONOTONIC_RAW #10 justinhoward
+- Change CutoffExceededError to inherit from Timeout::Error #9 justinhoward
+
+### Breaking
+
+PR #9 changes the parent class of `Cutoff::CutoffExceededError` from `CutoffError`
+to `Timeout::Error`. `CutoffError` changes from a class to a module.
+
+## [0.4.2] - 2021-10-14
+
+### Added
+
+- Add sidekiq middleware
+- Select checkpoints to enable or disable
+
 ## [0.4.1] - 2021-10-02
 
+### Fixed
+
 - Fix Net::HTTP patch to override timeouts given to start
 
 ## [0.4.0] - 2021-10-01
 
+### Added
+
 - Add benchmarks and slight performance improvements
 - Add Rails controller integration
 
 ## [0.3.0] - 2021-08-20
 
+### Added
+
 - Allow timers to be disabled globally with `Cutoff.disable!`
 
 ## [0.2.0] - 2021-07-22
@@ -33,8 +70,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Cutoff class
 - Mysql2 patch
 
-[Unreleased]: https://github.com/justinhoward/cutoff/compare/v0.4.1...HEAD
-[0.4.0]: https://github.com/justinhoward/cutoff/compare/v0.4.0...v0.4.1
+[Unreleased]: https://github.com/justinhoward/cutoff/compare/v0.5.1...HEAD
+[0.5.1]: https://github.com/justinhoward/cutoff/compare/v0.5.0...v0.5.1
+[0.5.0]: https://github.com/justinhoward/cutoff/compare/v0.4.2...v0.5.0
+[0.4.2]: https://github.com/justinhoward/cutoff/compare/v0.4.1...v0.4.2
+[0.4.1]: https://github.com/justinhoward/cutoff/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/justinhoward/cutoff/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/justinhoward/cutoff/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/justinhoward/cutoff/compare/v0.1.0...v0.2.0

data/README.md

@@ -4,7 +4,7 @@ Cutoff
 [![Gem Version](https://badge.fury.io/rb/cutoff.svg)](https://badge.fury.io/rb/cutoff)
 [![CI](https://github.com/justinhoward/cutoff/workflows/CI/badge.svg)](https://github.com/justinhoward/cutoff/actions?query=workflow%3ACI+branch%3Amaster)
 [![Code Quality](https://app.codacy.com/project/badge/Grade/2748da79ec294f909996a56f11caac4a)](https://www.codacy.com/gh/justinhoward/cutoff/dashboard?utm_source=github.com&utm_medium=referral&utm_content=justinhoward/cutoff&utm_campaign=Badge_Grade)
-[![Code Coverage](https://app.codacy.com/project/badge/Coverage/2748da79ec294f909996a56f11caac4a)](https://www.codacy.com/gh/justinhoward/cutoff/dashboard?utm_source=github.com&utm_medium=referral&utm_content=justinhoward/cutoff&utm_campaign=Badge_Coverage)
+[![Code Coverage](https://codecov.io/gh/justinhoward/cutoff/branch/master/graph/badge.svg?token=COVM3D2PTG)](https://codecov.io/gh/justinhoward/cutoff)
 [![Inline docs](http://inch-ci.org/github/justinhoward/cutoff.svg?branch=master)](http://inch-ci.org/github/justinhoward/cutoff)
 
 A deadlines library for Ruby inspired by Shopify and
@@ -217,6 +217,29 @@ Cutoff.wrap(3) do
 end
 ```
 
+Selecting Checkpoints
+---------------------------
+
+In some cases, you may want to select some checkpoints to use, but not others.
+For example, you may want to run some code that contains MySQL queries, but not
+use the mysql2 patch. The `exclude` and `only` options support this.
+
+```ruby
+Cutoff.wrap(10, exclude: :mysql2) do
+  # The mysql2 patch won't be used here
+end
+
+Cutoff.wrap(10, only: %i[foo bar]) do
+  # These checkpoints will be used
+  Cutoff.checkpoint!(:foo)
+  Cutoff.checkpoint!(:bar)
+
+  # These checkpoints will be skipped
+  Cutoff.checkpoint!(:asdf)
+  Cutoff.checkpoint!
+end
+```
+
 Timing a Rails Controller
 ---------------------------
 
@@ -277,6 +300,26 @@ class ApplicationController < ActionController::Base
 end
 ```
 
+Timing Sidekiq Workers
+------------
+
+If Sidekiq is loaded, Cutoff includes middleware to support a `:cutoff` option.
+
+```ruby
+class MyWorker
+  include Sidekiq::Worker
+
+  sidekiq_options cutoff: 6.0
+
+  def perform
+    # ...
+    Cutoff.checkpoint!
+    # ...
+  end
+end
+```
+
+
 Disabling Cutoff for Testing and Development
 ------------
 

data/lib/cutoff/error.rb

@@ -2,7 +2,7 @@
 
 class Cutoff
   # The Cutoff base error class
-  class CutoffError < StandardError
+  module CutoffError
     private
 
     def message_with_meta(message, **meta)
@@ -15,7 +15,9 @@ class Cutoff
   end
 
   # Raised by {Cutoff#checkpoint!} if the time has been exceeded
-  class CutoffExceededError < CutoffError
+  class CutoffExceededError < Timeout::Error
+    include CutoffError
+
     attr_reader :cutoff
 
     def initialize(cutoff)

data/lib/cutoff/patch/mysql2.rb

@@ -6,7 +6,8 @@ require 'mysql2'
 class Cutoff
   module Patch
     # Sets the max execution time for SELECT queries if there is an active
-    # cutoff and it has time remaining
+    # cutoff and it has time remaining. You can select this patch with
+    # `exclude` or `only` using the checkpoint name `:mysql2`.
     module Mysql2
       # Overrides `Mysql2::Client#query` to insert a MAX_EXECUTION_TIME query
       # hint with the remaining cutoff time
@@ -19,9 +20,9 @@ class Cutoff
       #   be executed in this case.
       def query(sql, options = {})
         cutoff = Cutoff.current
-        return super unless cutoff
+        return super unless cutoff&.selected?(:mysql2)
 
-        cutoff.checkpoint!
+        cutoff.checkpoint!(:mysql2)
         sql = QueryWithMaxTime.new(sql, cutoff.ms_remaining.ceil).to_s
         super
       end
@@ -166,4 +167,9 @@ class Cutoff
   end
 end
 
-Mysql2::Client.prepend(Cutoff::Patch::Mysql2)
+# @api external
+module Mysql2
+  class Client
+    prepend Cutoff::Patch::Mysql2
+  end
+end

data/lib/cutoff/patch/net_http.rb

@@ -4,32 +4,40 @@ require 'net/http'
 
 class Cutoff
   module Patch
+    # Set checkpoints for Ruby HTTP requests. Also sets the Net::HTTP timeouts
+    # to the remaining cutoff time. You can select this patch with
+    # `exclude` or `only` using the checkpoint name `:net_http`.
     module NetHttp
-      def self.gen_timeout_method(name)
-        <<~RUBY
-          if #{name}.nil? || #{name} > remaining
-            self.#{name} = cutoff.seconds_remaining
-          end
-        RUBY
-      end
+      class << self
+        private
+
+        def gen_timeout_method(name)
+          <<~RUBY
+            if #{name}.nil? || #{name} > remaining
+              self.#{name} = cutoff.seconds_remaining
+            end
+          RUBY
+        end
 
-      def self.use_write_timeout?
-        Gem::Version.new(RUBY_VERSION) > Gem::Version.new('2.6')
+        def use_write_timeout?
+          Gem::Version.new(RUBY_VERSION) > Gem::Version.new('2.6')
+        end
       end
 
       # Same as the original start, but adds a checkpoint for starting HTTP
       # requests and sets network timeouts to the remaining time
       #
+      # @method start
       # @see Net::HTTP#start
       module_eval(<<~RUBY, __FILE__, __LINE__ + 1)
         def start
-          if (cutoff = Cutoff.current)
+          if (cutoff = Cutoff.current) && cutoff.selected?(:net_http)
             remaining = cutoff.seconds_remaining
             #{gen_timeout_method('open_timeout')}
             #{gen_timeout_method('read_timeout')}
             #{gen_timeout_method('write_timeout') if use_write_timeout?}
             #{gen_timeout_method('continue_timeout')}
-            Cutoff.checkpoint!
+            Cutoff.checkpoint!(:net_http)
           end
           super
         end
@@ -38,4 +46,9 @@ class Cutoff
   end
 end
 
-Net::HTTP.prepend(Cutoff::Patch::NetHttp)
+# @api external
+module Net
+  class HTTP
+    prepend Cutoff::Patch::NetHttp
+  end
+end

data/lib/cutoff/rails/controller.rb

@@ -3,6 +3,7 @@
 require 'action_controller'
 
 class Cutoff
+  # Cutoff Rails extensions
   module Rails
     # Rails controller integration
     module Controller
@@ -45,4 +46,9 @@ class Cutoff
   end
 end
 
-ActionController::Base.extend(Cutoff::Rails::Controller)
+# @api external
+module ActionController
+  class Base
+    extend Cutoff::Rails::Controller
+  end
+end

data/lib/cutoff/rails.rb

@@ -1,7 +1,3 @@
 # frozen_string_literal: true
 
-# Namespace for Rails integration
-module Rails
-end
-
 require 'cutoff/rails/controller' if Gem.loaded_specs['actionpack']

data/lib/cutoff/sidekiq.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'sidekiq'
+
+class Cutoff
+  # Cutoff sidekiq extensions
+  module Sidekiq
+    # Add an option `cutoff` for sidekiq workers
+    #
+    # @example
+    #   class MyWorker
+    #     include Sidekiq::Worker
+    #
+    #     sidekiq_options cutoff: 6.0
+    #
+    #     def perform
+    #       # ...
+    #     end
+    #   end
+    class ServerMiddleware
+      # @param _worker [Object] the worker instance
+      # @param job [Hash] the full job payload
+      # @param _queue [String] queue the name of the queue the job was pulled
+      #   from
+      # @yield the next middleware in the chain or worker `perform` method
+      # @return [void]
+      def call(_worker, job, _queue)
+        allowed_seconds = job['cutoff']
+        return yield if allowed_seconds.nil?
+
+        Cutoff.wrap(allowed_seconds) { yield }
+      end
+    end
+  end
+end
+
+::Sidekiq.configure_server do |config|
+  config.server_middleware do |chain|
+    chain.add(Cutoff::Sidekiq::ServerMiddleware)
+  end
+end

data/lib/cutoff/timer.rb

@@ -1,19 +1,19 @@
 # frozen_string_literal:true
 
 class Cutoff
+  # Tracks the current time for cutoff
   module Timer
-    if defined?(Process::CLOCK_MONOTONIC_RAW)
-      # The current time
+    if defined?(Process::CLOCK_MONOTONIC)
+      # The current relative time
       #
       # If it is available, this will use a monotonic clock. This is a clock
-      # that always moves forward in time. If that is not available on this
-      # system, `Time.now` will be used
+      # that always moves forward in time and starts at an arbitrary point
+      # (such as system startup time). If that is not available on this system,
+      # `Time.now` will be used.
       #
-      # @return [Float] The current time as a float
-      def now
-        Process.clock_gettime(Process::CLOCK_MONOTONIC_RAW)
-      end
-    elsif defined?(Process::CLOCK_MONOTONIC)
+      # This does not represent current real time
+      #
+      # @return [Float] The current relative time as a float
       def now
         Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end

data/lib/cutoff/version.rb

@@ -3,6 +3,6 @@
 class Cutoff
   # @return [Gem::Version] The current version of the cutoff gem
   def self.version
-    Gem::Version.new('0.4.1')
+    Gem::Version.new('0.5.1')
   end
 end

data/lib/cutoff.rb

@@ -1,10 +1,15 @@
 # frozen_string_literal:true
 
+require 'set'
+require 'timeout'
+
 require 'cutoff/version'
 require 'cutoff/error'
 require 'cutoff/patch'
 require 'cutoff/timer'
+
 require 'cutoff/rails'
+require 'cutoff/sidekiq' if Gem.loaded_specs['sidekiq']
 
 class Cutoff
   CURRENT_STACK_KEY = 'cutoff_deadline_stack'
@@ -25,13 +30,14 @@ class Cutoff
     # If a cutoff is already started for this thread, then `start` uses the
     # minimum of the current remaining time and the given time
     #
-    # @param seconds [Float, Integer] The number of seconds for the cutoff. May
-    #   be overridden if there is an active cutoff and it has less remaining
-    #   time.
+    # @param (see #initialize)
     # @return [Cutoff] The {Cutoff} instance
-    def start(seconds)
-      seconds = [seconds, current.seconds_remaining].min if current
-      cutoff = Cutoff.new(seconds)
+    def start(allowed_seconds, **options)
+      if current
+        allowed_seconds = [allowed_seconds, current.seconds_remaining].min
+      end
+
+      cutoff = new(allowed_seconds, **options)
       Thread.current[CURRENT_STACK_KEY] ||= []
       Thread.current[CURRENT_STACK_KEY] << cutoff
       cutoff
@@ -68,9 +74,10 @@ class Cutoff
     #
     # @see .start
     # @see .stop
+    # @param (see #initialize)
     # @return The value that returned from the block
-    def wrap(seconds)
-      cutoff = start(seconds)
+    def wrap(allowed_seconds, **options)
+      cutoff = start(allowed_seconds, **options)
       yield cutoff
     ensure
       stop(cutoff)
@@ -82,11 +89,11 @@ class Cutoff
     #
     # @raise CutoffExceededError If there is an active expired cutoff
     # @return [void]
-    def checkpoint!
+    def checkpoint!(name = nil)
       cutoff = current
       return unless cutoff
 
-      cutoff.checkpoint!
+      cutoff.checkpoint!(name)
     end
 
     # Disable Cutoff globally. Useful for testing and debugging
@@ -107,7 +114,7 @@ class Cutoff
       @disabled = false
     end
 
-    # True if cutoff was disabled with {#disable!}
+    # True if cutoff was disabled with {.disable!}
     #
     # @return [Boolean] True if disabled
     def disabled?
@@ -122,10 +129,22 @@ class Cutoff
   #
   # The timer starts immediately upon creation
   #
-  # @param allowed_seconds [Integer, Float] The total number of seconds to allow
-  def initialize(allowed_seconds)
+  # @param allowed_seconds [Float, Integer] The total number of seconds to allow
+  # @param exclude [Enumberable<Symbol>, Symbol, nil] If given a name or
+  #   list of checkpoint names to skip
+  # @param only [Enumberable<Symbol>, Symbol, nil] If given a name or
+  #   list of checkpoint names to allow
+  def initialize(allowed_seconds, exclude: nil, only: nil)
     @allowed_seconds = allowed_seconds.to_f
     @start_time = Cutoff.now
+
+    if exclude
+      @exclude = Set.new(exclude.is_a?(Enumerable) ? exclude : [exclude])
+    end
+
+    if only
+      @only = Set.new(only.is_a?(Enumerable) ? only : [only])
+    end
   end
 
   # The number of seconds left on the clock
@@ -162,9 +181,29 @@ class Cutoff
   #
   # @raise CutoffExceededError If there is an active expired cutoff
   # @return [void]
-  def checkpoint!
+  def checkpoint!(name = nil)
+    unless name.nil? || name.is_a?(Symbol)
+      raise ArgumentError, 'name must be a symbol'
+    end
+
+    return unless selected?(name)
     raise CutoffExceededError, self if exceeded?
 
     nil
   end
+
+  # True if the named checkpoint is selected by the `exclude` and `only`
+  # options. If these options are not given, a checkpoint is considered to be
+  # selected. If the checkpoint is not named, it is also considered to be
+  # selected.
+  #
+  # @param name [Symbol, nil] The name of the checkpoint
+  # @return [Boolean] True if the checkpoint is selected
+  def selected?(name)
+    return true if name.nil? && @exclude
+    return false if @exclude&.include?(name)
+    return false if @only && !@only.include?(name)
+
+    true
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cutoff
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.1
 platform: ruby
 authors:
 - Justin Howard
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-10-02 00:00:00.000000000 Z
+date: 2022-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -38,34 +38,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: 0.81.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: 0.81.0
-- !ruby/object:Gem::Dependency
-  name: rubocop-rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: 1.38.1
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: 1.38.1
 - !ruby/object:Gem::Dependency
   name: timecop
   requirement: !ruby/object:Gem::Requirement
@@ -104,6 +76,7 @@ files:
 - lib/cutoff/patch/net_http.rb
 - lib/cutoff/rails.rb
 - lib/cutoff/rails/controller.rb
+- lib/cutoff/sidekiq.rb
 - lib/cutoff/timer.rb
 - lib/cutoff/version.rb
 homepage: https://github.com/justinhoward/cutoff
@@ -111,7 +84,8 @@ licenses:
 - MIT
 metadata:
   changelog_uri: https://github.com/justinhoward/cutoff/blob/master/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/gems/cutoff/0.4.1
+  documentation_uri: https://www.rubydoc.info/gems/cutoff/0.5.1
+  rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
 require_paths: