cutoff 0.2.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64171df8b5550b99b603ba4bae4874174cc5e4bcce2632318be777ecc932dce3
-  data.tar.gz: 39ee62f1f743fdce6d9dd3e873bd3acf4d7efd09907d0f9e265e98c786cb7dc9
+  metadata.gz: d00ff1f831beec4fed582b5faa9ed42c350c13b32217bdcab0b850445ba9c358
+  data.tar.gz: 77d466db54a822240d2d27cfdb120f98aa7f7435ec62ae15191292702580de79
 SHA512:
-  metadata.gz: bb41605b534178706b45f3e6921aad80ff0ff50606038d95d9d50267910a590df59969cb77b1c7879d0b2cd429c60205a418e1ff590b1dd7b4e7f4394b0f4f3c
-  data.tar.gz: 713d75df722a2f82414373d482d4a981e9a579069de55262afe12004287abdd5b6f2e7e09052130a3b0ce875658e8177ce519bdadb549dbb92dc8970f9cd0813
+  metadata.gz: 9821d7010a4663ce25497a129c5a04166b5f701bd30d1d7a20f183cd274444605f3ac14099857c22117d45ac980056f4ccbaf09e8b65403e83a93abc923ced90
+  data.tar.gz: ec1f98a8885f8938ba421d87cb82f7f16a79161a778d2e4c230204f2243009b001e4c5de8c95ca1153746a8eebb90f969ca5efe80390cd08f901ee943a06581f

data/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.2] - 2021-10-14
+
+- Add sidekiq middleware
+- Select checkpoints to enable or disable
+
+## [0.4.1] - 2021-10-02
+
+- Fix Net::HTTP patch to override timeouts given to start
+
+## [0.4.0] - 2021-10-01
+
+- Add benchmarks and slight performance improvements
+- Add Rails controller integration
+
+## [0.3.0] - 2021-08-20
+
+- Allow timers to be disabled globally with `Cutoff.disable!`
+
 ## [0.2.0] - 2021-07-22
 
 ### Added
@@ -20,6 +38,10 @@ 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.2.0...HEAD
+[Unreleased]: https://github.com/justinhoward/cutoff/compare/v0.4.1...HEAD
+[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
 [0.1.0]: https://github.com/justinhoward/cutoff/releases/tag/v0.1.0

data/README.md

@@ -217,28 +217,78 @@ 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
 ---------------------------
 
-One use of a cutoff is to add a deadline to a Rails controller action.
+One use of a cutoff is to add a deadline to a Rails controller action. This is
+typically preferable to approaches like `Rack::Timeout` that use the dangerous
+`Timeout` class.
+
+Cutoff includes a built-in integration for this purpose. If Rails is installed,
+the `#cutoff` class method is available in your controllers.
 
 ```ruby
-around_action { |_controller, action| Cutoff.wrap(2.5) { action.call } }
+class ApplicationController < ActionController::Base
+  # You may want to set a long global cutoff, but it's not required
+  cutoff 30
+end
+
+class UsersController < ApplicationController
+  cutoff 5.0
+
+  def index
+    # Now in your action, you can call `checkpoint!`, or if you're using the
+    # patches, checkpoints will be added automatically
+    Cutoff.checkpoint!
+  end
+end
 ```
 
-Now in your action, you can call `checkpoint!`, or if you're using the Mysql2
-patch, checkpoints will be added automatically.
+Just like with controller filters, you can use filters with the cutoff method.
 
 ```ruby
-def index
-  # Do thing one
-  Cutoff.checkpoint!
+class UsersController < ApplicationController
+  # For example, use an :only filter
+  cutoff 5.0, only: :index
+
+  # Multiple calls work just fine. Last match wins
+  cutoff 2.5, only: :show
 
-  # Do something else
+  def index
+    # ...
+  end
+
+  def show
+    # ...
+  end
 end
 ```
 
-Consider adding a global error handler for the `Cutoff::CutoffExceededError`
+Consider adding a global error handler for the `Cutoff::CutoffExceededError` in
+case you want to display a nice error page for timeouts.
 
 ```ruby
 class ApplicationController < ActionController::Base
@@ -250,6 +300,42 @@ 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
+------------
+
+When testing or debugging an application that uses Cutoff, you may want to
+disable Cutoff entirely. These methods are not thread-safe and not intended for
+production.
+
+```ruby
+# This disables all cutoff timers, for both global and local instances
+Cutoff.disable!
+Cutoff.disabled? # => true
+
+# Re-enable cutoff
+Cutoff.enable!
+```
+
 Multi-threading
 -----------------
 

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
@@ -45,8 +46,8 @@ class Cutoff
 
           # Loop through tokens like "WORD " or "/* "
           while @scanner.scan(/(\S+)\s+/)
-            # Get the word part. None of our tokens care about case
-            handle_token(@scanner[1].downcase)
+            # Get the word part
+            handle_token(@scanner[1])
           end
 
           return @scanner.string unless @found_select
@@ -68,7 +69,7 @@ class Cutoff
             hint_comment
           elsif token.start_with?('/*')
             block_comment
-          elsif token.start_with?('select')
+          elsif token.match?(/^select/i)
             select
           else
             other

data/lib/cutoff/patch/net_http.rb

@@ -4,27 +4,39 @@ require 'net/http'
 
 class Cutoff
   module Patch
-    # Adds a checkpoint for starting HTTP requests and sets network timeouts
-    # to the remaining time
+    # 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
-      # Construct a {Net::HTTP}, but with the timeouts set to the remaining
-      # cutoff time if one is active
-      def initialize(address, port = nil)
-        super
-        return unless (cutoff = Cutoff.current)
+      def self.gen_timeout_method(name)
+        <<~RUBY
+          if #{name}.nil? || #{name} > remaining
+            self.#{name} = cutoff.seconds_remaining
+          end
+        RUBY
+      end
 
-        @open_timeout = cutoff.seconds_remaining
-        @read_timeout = cutoff.seconds_remaining
-        @write_timeout = cutoff.seconds_remaining
+      def self.use_write_timeout?
+        Gem::Version.new(RUBY_VERSION) > Gem::Version.new('2.6')
       end
 
-      # Same as the original start, but with a cutoff checkpoint
+      # Same as the original start, but adds a checkpoint for starting HTTP
+      # requests and sets network timeouts to the remaining time
       #
-      # @see {Net::HTTP#start}
-      def start
-        Cutoff.checkpoint!
-        super
-      end
+      # @see Net::HTTP#start
+      module_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+        def start
+          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!(:net_http)
+          end
+          super
+        end
+      RUBY
     end
   end
 end

data/lib/cutoff/rails/controller.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'action_controller'
+
+class Cutoff
+  module Rails
+    # Rails controller integration
+    module Controller
+      # Set a cutoff for the controller
+      #
+      # Can be called multiple times with different options to configure
+      # cutoffs for various conditions. If multiple conditions match a given
+      # controller, the last applied cutoff "wins".
+      #
+      # @example
+      #   class ApplicationController
+      #     # Apply a global maximum
+      #     cutoff 30
+      #   end
+      #
+      #   class UsersController < ApplicationController
+      #     # Override the base time limit
+      #     cutoff 5.0
+      #     cutoff 3.0, only: :show
+      #     cutoff 7, if: :signed_in
+      #   end
+      #
+      # @param seconds [Float, Integer] The allowed seconds for a controller
+      #   action
+      # @param options [Hash] Options to pass to `around_action`. For example,
+      #   pass `:only`, `:except`, `:if`, to limit the scope of the cutoff.
+      def cutoff(seconds, options = {})
+        prepend_around_action(options) do |_controller, action|
+          next action.call if @cutoff_wrapped
+
+          begin
+            @cutoff_wrapped = true
+            Cutoff.wrap(seconds, &action)
+          ensure
+            @cutoff_wrapped = false
+          end
+        end
+      end
+    end
+  end
+end
+
+ActionController::Base.extend(Cutoff::Rails::Controller)

data/lib/cutoff/rails.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'cutoff/rails/controller' if Gem.loaded_specs['actionpack']

data/lib/cutoff/sidekiq.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'sidekiq'
+
+class Cutoff
+  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 = worker.class.sidekiq_options['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

@@ -0,0 +1,32 @@
+# frozen_string_literal:true
+
+class Cutoff
+  module Timer
+    if defined?(Process::CLOCK_MONOTONIC_RAW)
+      # The current 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
+      #
+      # @return [Float] The current time as a float
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC_RAW)
+      end
+    elsif defined?(Process::CLOCK_MONOTONIC)
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    elsif Gem.loaded_specs['concurrent-ruby']
+      require 'concurrent-ruby'
+
+      def now
+        Concurrent.monotonic_time
+      end
+    else
+      def now
+        Time.now.to_f
+      end
+    end
+  end
+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.2.0')
+    Gem::Version.new('0.4.2')
   end
 end

data/lib/cutoff.rb

@@ -1,13 +1,21 @@
 # frozen_string_literal:true
 
-require_relative 'cutoff/version'
-require_relative 'cutoff/error'
-require_relative 'cutoff/patch'
+require 'set'
+
+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'
   private_constant :CURRENT_STACK_KEY
 
+  extend Timer
+
   class << self
     # Get the current {Cutoff} if one is set
     def current
@@ -21,13 +29,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
@@ -64,9 +73,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)
@@ -78,38 +88,36 @@ 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
 
-    if defined?(Process::CLOCK_MONOTONIC_RAW)
-      # The current 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
-      #
-      # @return [Float] The current time as a float
-      def now
-        Process.clock_gettime(Process::CLOCK_MONOTONIC_RAW)
-      end
-    elsif defined?(Process::CLOCK_MONOTONIC)
-      def now
-        Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      end
-    elsif Gem.loaded_specs['concurrent-ruby']
-      require 'concurrent-ruby'
+    # Disable Cutoff globally. Useful for testing and debugging
+    #
+    # Should not be used in production
+    #
+    # @return [void]
+    def disable!
+      @disabled = true
+    end
 
-      def now
-        Concurrent.monotonic_time
-      end
-    else
-      def now
-        Time.now.to_f
-      end
+    # Enable Cutoff globally if it has been disabled
+    #
+    # Should not be used in production
+    #
+    # @return [void]
+    def enable!
+      @disabled = false
+    end
+
+    # True if cutoff was disabled with {.disable!}
+    #
+    # @return [Boolean] True if disabled
+    def disabled?
+      @disabled == true
     end
   end
 
@@ -120,10 +128,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
@@ -144,6 +164,8 @@ class Cutoff
   #
   # @return [Float] The number of seconds
   def elapsed_seconds
+    return 0 if Cutoff.disabled?
+
     Cutoff.now - @start_time
   end
 
@@ -158,9 +180,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.2.0
+  version: 0.4.2
 platform: ruby
 authors:
 - Justin Howard
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-07-23 00:00:00.000000000 Z
+date: 2021-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.10'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -88,13 +102,17 @@ files:
 - lib/cutoff/patch.rb
 - lib/cutoff/patch/mysql2.rb
 - 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
 licenses:
 - MIT
 metadata:
   changelog_uri: https://github.com/justinhoward/cutoff/blob/master/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/gems/cutoff/0.2.0
+  documentation_uri: https://www.rubydoc.info/gems/cutoff/0.4.2
 post_install_message: 
 rdoc_options: []
 require_paths: