cutoff 0.1.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e27bb02cc23dc725a4bcd3b9585159723e3fa4d3c88f98ec207ff2b91cf438d4
-  data.tar.gz: 8ab5a3a462bbbb2a32837e69de70d55ac59b3e347ead1db889d374f2be5b9224
+  metadata.gz: 5ac27ce016591276e55afa82f64c08de370a969cb6552cc0d5ae69093d3a9e0c
+  data.tar.gz: 31e989979ae04de967a22e8d2457d6da654862603f380dd7521e415c9220148b
 SHA512:
-  metadata.gz: c957634f0bc03f9fa8fb058080338978322adb54fce2c2c952c7b684ea3a979165f076abdc29878e416a084acd7b904ad6e8d637f0c1b90091ffa179fdb6076d
-  data.tar.gz: b9ac92d37812b341fba24c6a3feb5c0f1f4c9265f1995aa5266b85e3d46e27c48e80fd4801ecc4f46d9a22b5195e0b1dfc35bc9c74449e2ac35c11ace28a5f15
+  metadata.gz: 4241c63fc4c647c44860aa0781e2966a5eadc1d7edea259851018308d1877d664c46a8d90bd5553f725d2e1fa5f767995b0f27327482bf2ce5128701908aa684
+  data.tar.gz: 64d599559055f6d8b3c384b88b5268b02317784bd44fd6be2384fd3c56b1f9da5a9cfb435c4af05c083ba20af6d8865f0c73a8fc46afff261ad70d43fc9c35e4

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- Net::HTTP patch
+
 ## [0.1.0] - 2021-07-19
 
 ### Added
@@ -14,4 +33,9 @@ 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
+[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

@@ -20,8 +20,8 @@ Cutoff.wrap(5) do
 end
 ```
 
-It has a built-in patch for Mysql2 to auto-insert checkpoints and timeout query
-hints.
+It has built-in patches for Mysql2 and Net::HTTP to auto-insert checkpoints and
+timeouts.
 
 ```ruby
 require 'cutoff/patch/mysql2'
@@ -50,7 +50,7 @@ single query will take longer than 3 seconds. However, imagine a bad controller
 action or background job executes 100 slow queries. In that case, the queries
 add up to 300 seconds, much too long.
 
-Deadlines keep track of the total elapsed time in a request of job and interrupt
+Deadlines keep track of the total elapsed time in a request or job and interrupt
 it if it takes too long.
 
 Installation
@@ -138,8 +138,11 @@ Patches
 -------------
 
 Cutoff is in early stages, but it aims to provide patches for common networked
-dependencies. The first of these is the `mysql2` patch. It is not loaded by
-default, so you need to require it manually.
+dependencies. Patches automatically insert useful checkpoints and timeouts. The
+patches so far are for `mysql2` and `Net::HTTP`. They are not loaded by default,
+so you need to require them manually.
+
+For example, to load the Mysql2 patch:
 
 ```ruby
 # In your Gemfile
@@ -152,10 +155,14 @@ require 'cutoff'
 require 'cutoff/patch/mysql2'
 ```
 
-Once it is enabled, any `Mysql2::Client` object will respect the current cutoff
-if one is set.
+### Mysql2
+
+Once it is enabled, any `Mysql2::Client` object will respect the current
+class-level cutoff if one is set.
 
 ```ruby
+require 'cutoff/patch/mysql2'
+
 client = Mysql2::Client.new
 Cutoff.wrap(3) do
   sleep(4)
@@ -183,28 +190,82 @@ Cutoff.wrap(3) do
 end
 ```
 
+### Net::HTTP
+
+Once it is enabled, any `Net::HTTP` requests will respect the current
+class-level cutoff if one is set.
+
+```ruby
+require 'cutoff/patch/net_http'
+
+Cutoff.wrap(3) do
+  sleep(5)
+
+  # The cutoff is expired, so this hits a checkpoint and will not be executed
+  Net::HTTP.get(URI.parse('http://example.com'))
+end
+
+Cutoff.wrap(3) do
+  sleep(1.5)
+
+  # The cutoff has 1.5 seconds left, so this request will be executed
+  # open_timeout, read_timeout, and write_timeout (Ruby >= 2.6) will each
+  # be set to 1.5
+  # This means the overall time can be > 1.5 since the combined phases can take
+  # up to 4.5 seconds
+  Net::HTTP.get(URI.parse('http://example.com'))
+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
 
-  # Do something else
+  # Multiple calls work just fine. Last match wins
+  cutoff 2.5, only: :show
+
+  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
@@ -216,6 +277,22 @@ class ApplicationController < ActionController::Base
 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
 -----------------
 
@@ -360,10 +437,9 @@ never interrupt a running program unless:
 - `checkpoint!` is called
 - a network timeout is exceeded
 
-Patches such as the current Mysql2 patch are designed to ease the burden on
-developers to manually call `checkpoint!` or configure network timeouts. The
-ruby `Timeout` class is not used. See Julia Evans' post on [Why Ruby's Timeout
-is dangerous][julia_evans].
+Patches are designed to ease the burden on developers to manually call
+`checkpoint!` or configure network timeouts. The ruby `Timeout` class is not
+used. See Julia Evans' post on [Why Ruby's Timeout is dangerous][julia_evans].
 
 Patches are only applied by explicit opt-in, and Cutoff can always be used as a
 standalone library.

data/lib/cutoff/patch/mysql2.rb

@@ -45,8 +45,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 +68,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

@@ -0,0 +1,41 @@
+# frozen_string_literal:true
+
+require 'net/http'
+
+class Cutoff
+  module Patch
+    module NetHttp
+      def self.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')
+      end
+
+      # 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
+      module_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+        def start
+          if (cutoff = Cutoff.current)
+            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!
+          end
+          super
+        end
+      RUBY
+    end
+  end
+end
+
+Net::HTTP.prepend(Cutoff::Patch::NetHttp)

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,7 @@
+# frozen_string_literal: true
+
+# Namespace for Rails integration
+module Rails
+end
+
+require 'cutoff/rails/controller' if Gem.loaded_specs['actionpack']

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.1.0')
+    Gem::Version.new('0.4.1')
   end
 end

data/lib/cutoff.rb

@@ -1,13 +1,17 @@
 # frozen_string_literal:true
 
-require_relative 'cutoff/version'
-require_relative 'cutoff/error'
-require_relative 'cutoff/patch'
+require 'cutoff/version'
+require 'cutoff/error'
+require 'cutoff/patch'
+require 'cutoff/timer'
+require 'cutoff/rails'
 
 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
@@ -85,31 +89,29 @@ class Cutoff
       cutoff.checkpoint!
     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'
-
-      def now
-        Concurrent.monotonic_time
-      end
-    else
-      def now
-        Time.now.to_f
-      end
+    # Disable Cutoff globally. Useful for testing and debugging
+    #
+    # Should not be used in production
+    #
+    # @return [void]
+    def disable!
+      @disabled = true
+    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
 
@@ -144,6 +146,8 @@ class Cutoff
   #
   # @return [Float] The number of seconds
   def elapsed_seconds
+    return 0 if Cutoff.disabled?
+
     Cutoff.now - @start_time
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cutoff
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Justin Howard
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-07-20 00:00:00.000000000 Z
+date: 2021-10-02 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
@@ -87,13 +101,17 @@ files:
 - lib/cutoff/error.rb
 - 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/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.1.0
+  documentation_uri: https://www.rubydoc.info/gems/cutoff/0.4.1
 post_install_message: 
 rdoc_options: []
 require_paths: