safe_request_timeout 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 742cdb842214b5b66fa2fb127c79005ce2b3072776c59a20564433a9f5e82a8c
+  data.tar.gz: 592e4127ace138dadeabcf7e9dc5bbb129a20e8895e600a009e588249cea668f
+SHA512:
+  metadata.gz: 61be0a04e1f993c83dd520c151d7a76817be66eff64200898d336cfda5e70668c53a320462a5c161818e017ad17c6ab39c11fc2ceae1405c5ca1682eb511b17e
+  data.tar.gz: bcf57aafa0db0db508283d5c6f49ec611a6b3366e19542a014015f731e623c3dfc1f9eda4b239661f24b673a9310887355a37dbed568489fe7961ebda8d108dc

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# 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.0.0
+
+### Added
+- Initial release.

data/MIT_LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2023 Brian Durand
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,165 @@
+# Request Timeout
+
+[![Continuous Integration](https://github.com/bdurand/safe_request_timeout/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/bdurand/safe_request_timeout/actions/workflows/continuous_integration.yml)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
+
+This gem provides a safe and convenient mechanism for adding a timeout mechanism to a block of code. The gem ensures that the timeout is safe to call and will not raise timeout errors from random places in your code which can leave your application in an indeterminate state.
+
+It is designed to work in situations where there is a general timeout needed on some kind of request. For instance, consider a Rack HTTP request. This request may be behind a web server running in a separate process with it's own timeout where it sends an error back to the client when the application is taking too long to process the request. However, your Ruby application won't know anything about this and will continue processing the request and generating a response for a client that is no longer going to receive the response which just wastes server resources.
+
+When requests start timing out due to an external issue like a slow database query, then it is more difficult to recover and can cascade an isolated issue into a general site outage. Often the timeouts you have on resources like database connections won't cover this case either since individual queries might never hit the timeout limit.
+
+Unlike the `Timeout` class in the Ruby standard library, this code is very explicit about where timeout errors can be raised, so you don't need to worry about a timeout error in an unexpected place leaving your application in an indeterminate state.
+
+There is built in support for Rails applications. For other frameworks you will need to add some middleware and hooks to implement the timeout mechanism.
+
+## Usage
+
+You can wrap code in a timout block.
+
+```ruby
+SafeRequestTimeout.timeout(15) do
+   ...
+end
+```
+
+By itself, this won't do anything. Unlike normal timeouts, there is no background process that will kill the operation after a defined period. Instead, you will need to periodically call `SafeRequestTimeout.check_timeout!` from within your code. Calling this method within a timeout block will raise an error if the time spent in that block has exceeded the max allowed. Calling it outside of a timeout block will do nothing.
+
+It is generally best to call the `check_timeout!` method before doing an expensive operation since there's no point in timing out after the work has already been done. This method will also clear the current timeout, so you don't have to worry about it generating a cascading series of timeout errors in any error handling code.
+
+```ruby
+SafeRequestTimeout.timeout(5) do
+  1000.times do
+    # This will raise an error if the loop takes longer than 5 seconds.
+    SafeRequestTimeout.check_timeout!
+    do_somthing
+  end
+end
+```
+
+You can also set a timeout value retroactively from within a `timeout` block. You can use this feature to change the timeout based on application state.
+
+```ruby
+# Setting a timeout of nil will set up a block that will never timout.
+SafeRequestTimeout.timeout(nil) do
+  # Set the timeout duration to 5 seconds for non-admin users
+  SafeRequestTimeout.set_timeout(5) unless current_user.admin?
+
+  do_something
+end
+```
+
+You can also set the timeout duration with a `Proc` that will be evaluated at runtime.
+
+```ruby
+SafeRequestTimeout.timeout(lambda { CurrentUser.new.admin? ? nil : 5 })
+  ...
+end
+```
+
+You can clear the timeout if you want to ensure a block of code can run without begin timed out (i.e. if you need to run cleanup code).
+
+```ruby
+SafeRequestTimeout.timeout(5) do
+  begin
+    do_something
+  ensure
+    SafeRequestTimeout.clear_timeout
+    cleanup_request
+  end
+end
+```
+
+### Hooks
+
+You can add hooks into other classes to check the current timeout if you don't want to have to sprinkle `SafeRequestTimeout.check_timeout!` throughout your code. To do this, use the `SafeRequestTimeout.add_timeout!` method. You need to specify the class and methods where you want to add the timeout hooks:
+
+```ruby
+# Add a timeout check to the MyDriver#make_request method.
+SafeRequestTimeout::Hooks.add_timeout!(MyDriver, [:make_request])
+```
+
+### Rack Middleware
+
+This gem ships with Rack middleware that can set up a timeout block on all Rack requests. In a Rack application you would use this code to add a 15 second timeout to all requests to `app`.
+
+```ruby
+RackBuilder.new do
+  use SafeRequestTimeout::RackMiddleware, 15
+  run app
+end
+```
+
+If you want to customize the timeout per request, you can call `SafeRequestTimeout.set_timeout` inside your request handling to change the value for the current request. You can also define the timeout duration with a `Proc` which will be called at runtime with the `env` object passed for the request.
+
+```ruby
+RackBuilder.new do
+  use SafeRequestTimeout::RackMiddleware, lambda { |env|
+    10 unless Rack::Request.new(env).path.start_with?("/admin")
+  }
+  run app
+end
+```
+
+### Sidekiq Middleware
+
+This gem ships with Sidekiq middleware that can add timeout support to Sidekiq workers. The middleware needs to be added to the server middleware in the Sidekiq initialization.
+
+```ruby
+Sidekiq.configure_server do |config|
+  config.server_middleware do |chain|
+    chain.add SafeRequestTimeout::SidekiqMiddleware
+  end
+end
+```
+
+You can then specify a timeout per worker with the `safe_request_timeout` sidekiq option.
+
+```
+class SlowWorker
+  include Sidekiq::Worker
+
+  # Set a 15 second timeout for the worker to finish.
+  sidekiq_options safe_request_timeout: 15
+end
+```
+
+### Rails
+
+This gem comes with built in support for Rails applications.
+
+- The Rack middleware is added to the middleware chain. There is no timeout value set by default. You can specify a global one by setting `safe_request_timout.rack_timeout` in your Rails configuration.
+
+- If Sidekiq is being used, then the Sidekiq middleware is added. Sidekiq workers can specify a timeout with the `safe_request_timeout` option.
+
+- A timeout block is added around ActiveJob execution. Jobs can specify a timeout by calling `SafeRequestTimeout.set_timeout` in the `perform` method or in a `before_perform` callback.
+
+- A timeout check is added on all ActiveRecord queries. The timeout is cleared when a database transaction is committed so that you won't unexpectedly timeout a request after making persistent changes. You can disable these hooks by setting `safe_request_timeout.active_record_hook` to false in your Rails configuration.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'safe_request_timeout'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install safe_request_timeout
+```
+
+## 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

@@ -0,0 +1 @@
+1.0.0

data/dependabot.yml

@@ -0,0 +1,12 @@
+# Dependabot update strategy
+version: 2
+updates:
+  - package-ecosystem: bundler
+    directory: "/"
+    schedule:
+      interval: daily
+    allow:
+      # Automatically keep all runtime dependencies updated
+      - dependency-name: "*"
+        dependency-type: "production"
+    versioning-strategy: lockfile-only

data/lib/safe_request_timeout/active_record_hook.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SafeRequestTimeout
+  class ActiveRecordHook
+    class << self
+      # Add the timeout hook to the connection class.
+      #
+      # @param connection_class [Class] The class to add the timeout hook to.
+      # @return [void]
+      def add_timeout!(connection_class = nil)
+        connection_class ||= ::ActiveRecord::Base.connection.class
+
+        SafeRequestTimeout::Hooks.add_timeout!(connection_class, [:exec_query])
+
+        SafeRequestTimeout::Hooks.clear_timeout!(connection_class, [:commit_db_transaction])
+      end
+    end
+  end
+end

data/lib/safe_request_timeout/hooks.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SafeRequestTimeout
+  # Hooks into other classes from other libraries with timeout blocks. This allows
+  # timeouts to be automatically checked before making requests to external services.
+  module Hooks
+    class << self
+      # Hooks into a class by surrounding specified instance methods with timeout checks.
+      def add_timeout!(klass, methods, module_name = nil)
+        hooks_module = create_module(klass, module_name, "AddTimeout")
+
+        Array(methods).each do |method_name|
+          hooks_module.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+            def #{method_name}(#{splat_args})
+              SafeRequestTimeout.check_timeout!
+              super(#{splat_args})
+            end
+          RUBY
+        end
+
+        klass.prepend(hooks_module)
+      end
+
+      def clear_timeout!(klass, methods, module_name = nil)
+        hooks_module = create_module(klass, module_name, "ClearTimeout")
+
+        Array(methods).each do |method_name|
+          hooks_module.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+            def #{method_name}(#{splat_args})
+              SafeRequestTimeout.clear_timeout
+              super(#{splat_args})
+            end
+          RUBY
+        end
+
+        klass.prepend(hooks_module)
+      end
+
+      private
+
+      def create_module(klass, module_name, module_type)
+        # Create a module that will be prepended to the specified class.
+        unless module_name
+          camelized_name = name.to_s.gsub(/[^a-z0-9]+([a-z0-9])/i) { |m| m[m.length - 1, m.length].upcase }
+          camelized_name = "#{camelized_name[0].upcase}#{camelized_name[1, camelized_name.length]}"
+          module_name = "#{klass.name.split("::").join}#{camelized_name}#{module_type}"
+        end
+
+        if const_defined?(module_name)
+          raise ArgumentError.new("Cannot create duplicate #{module_name} for hooking #{name} into #{klass.name}")
+        end
+
+        # Dark arts & witchery to dynamically generate the module methods.
+        const_set(module_name, Module.new)
+      end
+
+      def splat_args
+        # The method of overriding kwargs changed in ruby 2.7
+        ruby_major, ruby_minor, _ = RUBY_VERSION.split(".").collect(&:to_i)
+        ruby_3_args = (ruby_major >= 3 || (ruby_major == 2 && ruby_minor >= 7))
+        (ruby_3_args ? "..." : "*args, &block")
+      end
+    end
+  end
+end

data/lib/safe_request_timeout/rack_middleware.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SafeRequestTimeout
+  # Rack middleware that adds a timeout block to all requests.
+  class RackMiddleware
+    # @param app [Object] The Rack application to wrap.
+    # @param timeout [Integer, Proc, nil] The timeout in seconds.
+    def initialize(app, timeout = nil)
+      @app = app
+      @timeout = timeout
+      @timeout_block = true if timeout.is_a?(Proc) && timeout.arity == 1
+    end
+
+    def call(env)
+      SafeRequestTimeout.timeout(@timeout_block ? @timeout.call(env) : @timeout) do
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/safe_request_timeout/railtie.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SafeRequestTimeout
+  class Railtie < Rails::Railtie
+    config.safe_request_timeout = ActiveSupport::OrderedOptions.new
+    config.safe_request_timeout.active_record_hook = true
+    config.safe_request_timeout.rack_timeout = nil
+
+    initializer "safe_request_timeout" do |app|
+      if app.config.safe_request_timeout.active_record_hook
+        ActiveSupport.on_load(:active_record) do
+          SafeRequestTimeout::ActiveRecordHook.add_timeout!
+        end
+      end
+
+      if defined?(ActiveJob::Base.around_perform)
+        ActiveJob::Base.around_perform do |job, block|
+          SafeRequestTimeout.timeout(nil, &block)
+        end
+      end
+
+      app.middleware.use SafeRequestTimeout::RackMiddleware, app.config.safe_request_timeout.rack_timeout
+
+      if defined?(Sidekiq.server?) && Sidekiq.server?
+        Sidekiq.configure_server do |sidekiq_config|
+          sidekiq_config.server_middleware do |chain|
+            chain.add SafeRequestTimeout::SidekiqMiddleware
+          end
+        end
+      end
+    end
+  end
+end

data/lib/safe_request_timeout/sidekiq_middleware.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module SafeRequestTimeout
+  # Sidekiq server middleware that wraps job execution with a timeout. The timeout
+  # is set in a job's "safe_request_timeout" option.
+  class SidekiqMiddleware
+    if defined?(Sidekiq::ServerMiddleware)
+      include Sidekiq::ServerMiddleware
+    end
+
+    def call(job_instance, job_payload, queue)
+      SafeRequestTimeout.timeout(job_payload["safe_request_timeout"]) do
+        yield
+      end
+    end
+  end
+end

data/lib/safe_request_timeout/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SafeRequestTimeout
+  VERSION = File.read(File.expand_path("../../VERSION", __dir__)).chomp.freeze
+end

data/lib/safe_request_timeout.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+# This module adds the capability to add a general timeout to any block of code.
+# Unlike the Timeout module, an error is not raised to indicate a timeout.
+# Instead, the `timed_out?` method can be used to check if the block of code
+# has taken longer than the specified duration so the application can take
+# the appropriate action.
+#
+# This is a safer alternative to the Timeout module because it does not fork new
+# threads or risk raising errors from unexpected places.
+#
+# @example
+#   SafeRequestTimeout.timeout(5) do
+#     # calling check_timeout! will raise an error if the block has taken
+#     # longer than 5 seconds to execute.
+#     SafeRequestTimeout.check_timeout!
+#   end
+module SafeRequestTimeout
+  class TimeoutError < ::Timeout::Error
+  end
+
+  class << self
+    # Execute the given block with a timeout. If the block takes longer than the specified
+    # duration to execute, then the `timed_out?`` method will return true within the block.
+    #
+    # @param duration [Integer] the number of seconds to wait before timing out
+    # @yield the block to execute
+    # @yieldreturn [Object] the result of the block
+    def timeout(duration, &block)
+      duration = duration.call if duration.respond_to?(:call)
+
+      previous_start_at = Thread.current[:safe_request_timeout_started_at]
+      previous_timeout_at = Thread.current[:safe_request_timeout_timeout_at]
+
+      start_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      timeout_at = start_at + duration if duration
+      if timeout_at && previous_timeout_at && previous_timeout_at < timeout_at
+        timeout_at = previous_timeout_at
+      end
+
+      begin
+        Thread.current[:safe_request_timeout_started_at] = start_at
+        Thread.current[:safe_request_timeout_timeout_at] = timeout_at
+        yield
+      ensure
+        Thread.current[:safe_request_timeout_started_at] = previous_start_at
+        Thread.current[:safe_request_timeout_timeout_at] = previous_timeout_at
+      end
+    end
+
+    # Check if the current timeout block has timed out.
+    #
+    # @return [Boolean] true if the current timeout block has timed out
+    def timed_out?
+      timeout_at = Thread.current[:safe_request_timeout_timeout_at]
+      !!timeout_at && Process.clock_gettime(Process::CLOCK_MONOTONIC) > timeout_at
+    end
+
+    # Raise an error if the current timeout block has timed out. If there is no timeout block,
+    # then this method does nothing. If an error is raised, then the current timeout
+    # is cleared to prevent the error from being raised multiple times.
+    #
+    # @return [void]
+    # @raise [SafeRequestTimeout::TimeoutError] if the current timeout block has timed out
+    def check_timeout!
+      if timed_out?
+        Thread.current[:safe_request_timeout_timeout_at] = nil
+        raise TimeoutError.new("after #{time_elapsed.round(6)} seconds")
+      end
+    end
+
+    # Get the number of seconds remaining in the current timeout block or nil if there is no
+    # timeout block.
+    #
+    # @return [Float, nil] the number of seconds remaining in the current timeout block
+    def time_remaining
+      timeout_at = Thread.current[:safe_request_timeout_timeout_at]
+      [timeout_at - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0.0].max if timeout_at
+    end
+
+    # Get the number of seconds elapsed in the current timeout block or nil if there is no
+    # timeout block.
+    #
+    # @return [Float, nil] the number of seconds elapsed in the current timeout block began
+    def time_elapsed
+      start_at = Thread.current[:safe_request_timeout_started_at]
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_at if start_at
+    end
+
+    # Set the duration for the current timeout block. This is useful if you want to set the duration
+    # after the timeout block has started. The timer for the timeout block will restart whenever
+    # a new duration is set.
+    #
+    # @return [void]
+    def set_timeout(duration)
+      if Thread.current[:safe_request_timeout_started_at]
+        start_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        duration = duration.call if duration.respond_to?(:call)
+        timeout_at = start_at + duration if duration
+        Thread.current[:safe_request_timeout_started_at] = start_at
+        Thread.current[:safe_request_timeout_timeout_at] = timeout_at
+      end
+    end
+
+    # Clear the current timeout. If a block is passed, then the timeout will be cleared
+    # only for the duration of the block.
+    #
+    # @yield the block to execute if one is given
+    # @yieldreturn [Object] the result of the block
+    def clear_timeout(&block)
+      if block
+        timeout(nil, &block)
+      else
+        set_timeout(nil)
+      end
+    end
+  end
+end
+
+require_relative "safe_request_timeout/hooks"
+require_relative "safe_request_timeout/active_record_hook"
+require_relative "safe_request_timeout/rack_middleware"
+require_relative "safe_request_timeout/sidekiq_middleware"
+require_relative "safe_request_timeout/version"
+
+if defined?(Rails::Railtie)
+  require_relative "safe_request_timeout/railtie"
+end

data/safe_request_timeout.gemspec

@@ -0,0 +1,34 @@
+Gem::Specification.new do |spec|
+  spec.name = "safe_request_timeout"
+  spec.version = File.read(File.expand_path("../VERSION", __FILE__)).strip
+  spec.authors = ["Brian Durand"]
+  spec.email = ["bbdurand@gmail.com"]
+
+  spec.summary = "Mechanism for safely aborting long-running requests after a specified timeout."
+  spec.homepage = "https://github.com/bdurand/safe_request_timeout"
+  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(File.expand_path("..", __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| ignore_files.any? { |path| f.start_with?(path) } }
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "redis"
+
+  spec.add_development_dependency "bundler"
+
+  spec.required_ruby_version = ">= 2.5"
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: safe_request_timeout
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Brian Durand
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-06-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  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'
+description:
+email:
+- bbdurand@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT_LICENSE.txt
+- README.md
+- VERSION
+- dependabot.yml
+- lib/safe_request_timeout.rb
+- lib/safe_request_timeout/active_record_hook.rb
+- lib/safe_request_timeout/hooks.rb
+- lib/safe_request_timeout/rack_middleware.rb
+- lib/safe_request_timeout/railtie.rb
+- lib/safe_request_timeout/sidekiq_middleware.rb
+- lib/safe_request_timeout/version.rb
+- safe_request_timeout.gemspec
+homepage: https://github.com/bdurand/safe_request_timeout
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.12
+signing_key:
+specification_version: 4
+summary: Mechanism for safely aborting long-running requests after a specified timeout.
+test_files: []