activerecord-dynamic_timeout 0.0.1.rc2 → 0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55639dda91869cb0dc47c52543cd9becb00c99d0401fe3ba8de74895137798c6
-  data.tar.gz: 7435229decada73df01abdaad9183da8d850512aeb30f2efe30148a0e6e9d981
+  metadata.gz: ddb706eb329656e5e5651e508e50720ad46051805d00ae10b49dbb7ff484d446
+  data.tar.gz: 249cfadad65543235ba52b251d56097c0b8180eaf1ae370400611da0989c5598
 SHA512:
-  metadata.gz: 296df3e1d3484a39921f718ab1ed19ba23fdb009d7adba17cddb7e6320babb23b146cd08e3272bdde7260b150a12a942e75d56ff9405bcc806ba20aa404eb478
-  data.tar.gz: 45ef043b9e41620cb3b8e2561b8f09b12d4d523001f0fa146eff7dbfd35c5db335d172954bbe2cc2d4b1acec743a70f3e0384a01af19549e0617c4910968d4e9
+  metadata.gz: ae50c77306307acf78925ad6c124630b49629614f47b370397e156ea100ef8090c6dd986197e6d6a1be84d4bed38a3a7f33dedb67c1944b3f7a6a82bb58510c7
+  data.tar.gz: 2af7ea2c782e232433571e79ed8e2a4f60a2f85acd646de338e89ec5274e71744cef9acd49a8ae3263748edbcee35de2fd46f77cee4aebf0d4786f0b886ce6f0

data/Appraisals

@@ -3,13 +3,7 @@
 require "appraisal/matrix"
 
 appraisal_matrix(activerecord: "6.1") do |activerecord:|
-  if activerecord < "7.2"
+  if activerecord < "7.1"
     gem "sqlite3", "~> 1.4"
   end
 end
-# appraisal_matrix(activerecord: "6.1", mysql2: { versions: ["~> 0.5"], step: :major })
-# appraisal_matrix(activerecord: "6.1", pg: { versions: ["~> 1.5"], step: :major })
-#
-# appraisal_matrix(activerecord: [">= 6.1", "< 7.2"], sqlite3: { versions: ["~> 1.4"], step: :major })
-# appraisal_matrix(activerecord: "7.2", sqlite3: { versions: [">= 1.4"], step: :major })
-# appraisal_matrix(activerecord: "7.1", trilogy: { versions: [">= 2.8"], step: :major })

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# CHANGELOG for `activerecord-dynamic_timeout`
+
+Inspired by [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+Note: this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.1.0 (Unreleased)
+- Initial release

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    activerecord-dynamic_timeout (0.0.1.rc2)
+    activerecord-dynamic_timeout (0.0.1)
       activerecord (>= 6.1)
 
 GEM
@@ -70,7 +70,7 @@ GEM
       rspec-support (~> 3.13.0)
     rspec-support (3.13.1)
     securerandom (0.3.1)
-    sqlite3 (2.0.4-arm64-darwin)
+    sqlite3 (2.0.0-arm64-darwin)
     stringio (3.1.1)
     thor (1.3.2)
     timeout (0.4.1)

data/README.md

@@ -1,2 +1,143 @@
 # activerecord-dynamic_timeout
-Dynamic Timeouts within ActiveRecord
+Dynamic query timeouts within ActiveRecord!
+
+## Installation
+
+Add this line to your application's Gemfile:
+```ruby
+gem 'activerecord-dynamic_timeout', require: 'active_record/dynamic_timeout/railtie'
+```
+
+### Non-Rails Applications
+If you are using this gem in a non-rails application, you will need run the initializer manually.
+```ruby
+require "active_record/dynamic_timeout"
+ActiveRecord::DynamicTimeout::Initializer.initialize!
+```
+
+## Usage
+To use this gem, you can set a timeout for a block of code that runs queries using ActiveRecord.
+Within the block, if a query takes longer than the timeout value (in seconds), an `ActiveRecord::QueryAborted` error (or a subclass of it) will be raised.
+
+#### Example
+```ruby
+class MyModel < ActiveRecord::Base
+  # Model code...
+end
+
+MyModel.all # A long query that takes over 5 seconds
+# => ActiveRecord::Relation<MyModel>...
+
+# Set a timeout for all queries run within the block
+MyModel.with_timeout(5.seconds) do
+  MyModel.all # A long running query that takes over 5 seconds
+end
+# => Raises ActiveRecord::QueryAborted error (or a subclass of it) after 5 seconds.
+```
+
+## Supported Adapters
+* mysql2
+* trilogy - ActiveRecord versions 7.1+
+* postgresql
+* sqlite3 (version >= 2.0) - Note - ActiveRecord < 7.1 does not support sqlite3 >= 2.0
+
+See [OtherAdapters](#other-adapters) on how to add support for other adapters.
+
+### Mysql2
+Timeouts are set using the client read_timeout and write_timeout attributes on the client. At the moment this is a bit of a hack as the mysql2 gem doesn't provide
+a clean way to set these attributes (via a public method).
+
+A Pull Request has been open for over 6 years to add per-query read_timeouts: https://github.com/brianmario/mysql2/pull/955
+
+No queries are executed to set the timeouts.
+
+#### Warning on Raw Inserts and Updates
+If you are using raw inserts or updates, ensure you wrap them in a transaction. If you do not, the timeout will still occur but the query on the server side will still continue.
+If you are using normal ActiveRecord methods (e.g. `MyModel.create`, `MyModel.update`, etc.), you do not need to worry about this because these run the queries within a transaction already.
+
+```ruby
+### Bad!!!
+MyModel.count
+# => 0
+MyModel.with_timeout(1.seconds) do
+  MyModel.connection.execute("INSERT INTO my_models SELECT SLEEP(2)") # This will take longer than 1 second and cause a timeout.
+end
+# Wait ~1-2 seconds...
+MyModel.count
+# => 1 # The query still completed on the server side even though the client has timed out.
+
+### Good
+# Wrap the raw query in a transaction
+# This will cause the query to be rolled back if the timeout occurs.
+MyModel.with_timeout(1.seconds) do
+  MyModel.transaction do
+    MyModel.connection.execute("INSERT INTO my_models SELECT SLEEP(2)") # This will take longer than 1 second and cause a timeout.
+  end
+end
+```
+
+### Trilogy
+Timeouts are set via the client read_timeout and write_timeout attributes on the clients. No queries are executed to set the timeouts.
+
+#### Warning on Raw Inserts and Updates (Trilogy)
+See [this section](#warning-on-raw-inserts-and-updates) for more information.
+
+### Postgresql
+Timeouts are set via setting the session variable via the following query `SET SESSION statement_timeout TO <timeout>`.
+
+See more information at https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-STATEMENT-TIMEOUT
+
+**Note** - Because this executes a query to set the timeout, we will lazily set and reset the timeout on the connection. This is done to reduce
+the number of queries run.
+
+### Sqlite3
+Timeouts are set via the `Sqlite3::Database#statement_timeout=` method. See more information at https://www.rubydoc.info/gems/sqlite3/SQLite3/Database:statement_timeout=
+
+Under the hood, this sets a progress_handler that will check every 1000 virtual machine instructions if the timeout has been exceeded. If it has,
+it will interrupt the query and raise out.
+
+More information about Sqlite Progress Handlers: https://www.sqlite.org/draft/c3ref/progress_handler.html
+
+More information about Sqlite interrupt: https://www.sqlite.org/c3ref/interrupt.html
+
+**Note** - Because this executes a query to set the timeout, we will lazily set and reset the timeout on the connection. This is done to reduce
+the number of queries run.
+
+### Other Adapters
+If you would like to add support for a different adapter, add the following code to the adapter:
+1. `#supports_dynamic_timeouts?` - Must return true
+2. `#set_connection_timeout(raw_connection, timeout)` - Set the timeout on the connection
+3. `#reset_connection_timeout(raw_connection)` - Reset the timeout on the connection
+4. `#timeout_set_client_side?` - Used to decide if the timeout should be set lazily (and reset) or not
+
+```ruby
+class MyAdapter < ActiveRecord::ConnectionAdapters::AbstractAdapter
+  # @return [Boolean]
+  def supports_dynamic_timeouts?
+    true # Must return true.
+  end
+
+  # @param raw_connection [Object] The raw connection object of the adapter
+  # @param timeout [Integer] The timeout passed in by the user
+  def set_connection_timeout(raw_connection, timeout)
+    # Set the timeout on the connection
+  end
+
+  # @param raw_connection [Object] The raw connection object of the adapter
+  def reset_connection_timeout(raw_connection)
+    # Reset the timeout on the connection, to the default value or the value set in the database configuration file.
+  end
+
+  # @return [Boolean]
+  def timeout_set_client_side?
+    false
+    # Return true if the timeout does not require a query to be executed in order to set the timeout
+    # Return false if the timeout requires a query to be executed in order to set the timeout. When false, the timeout will be set lazily, only when necessary.
+  end
+  
+  # Adapter code...
+end
+```
+
+## Contributing
+Bug reports and pull requests are welcome on GitHub.

data/activerecord-dynamic_timeout.gemspec

@@ -1,6 +1,7 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
-$:.unshift File.expand_path("../lib", __FILE__)
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "active_record/dynamic_timeout/version"
 
 Gem::Specification.new do |s|

data/lib/active_record/dynamic_timeout/extensions/abstract_adapter_extension.rb

@@ -2,7 +2,6 @@
 
 require "active_support"
 require "active_support/concern"
-require_relative "../../dynamic_timeout"
 
 module ActiveRecord::DynamicTimeout
   module AbstractAdapterExtension
@@ -18,29 +17,29 @@ module ActiveRecord::DynamicTimeout
       false
     end
 
-    def set_dynamic_timeout(raw_connection, timeout)
-      return unless supports_dynamic_timeouts?
-      return if active_record_dynamic_timeout == timeout
-      if timeout.nil?
-        reset_dynamic_timeout(raw_connection)
-      else
-        set_connection_timeout(raw_connection, timeout)
-        self.active_record_dynamic_timeout = timeout
+    def set_dynamic_timeout(raw_connection, timeout_seconds)
+      if supports_dynamic_timeouts? && timeout_seconds != active_record_dynamic_timeout
+        if timeout_seconds.nil?
+          reset_dynamic_timeout(raw_connection)
+        else
+          set_connection_timeout(raw_connection, timeout_seconds)
+          self.active_record_dynamic_timeout = timeout_seconds
+        end
       end
     end
 
     def reset_dynamic_timeout(raw_connection)
-      return unless supports_dynamic_timeouts?
-      return if active_record_dynamic_timeout.nil?
-      reset_connection_timeout(raw_connection)
-      self.active_record_dynamic_timeout = nil
+      if supports_dynamic_timeouts? && active_record_dynamic_timeout
+        reset_connection_timeout(raw_connection)
+        self.active_record_dynamic_timeout = nil
+      end
     end
   end
 
   module TimeoutAdapterExtension
     def with_raw_connection(*args, **kwargs, &block)
       super do |raw_connection|
-        set_dynamic_timeout(raw_connection, ActiveRecord::Base.current_timeout)
+        set_dynamic_timeout(raw_connection, ActiveRecord::Base.current_timeout_seconds)
         yield raw_connection
       ensure
         if timeout_set_client_side?
@@ -69,7 +68,7 @@ module ActiveRecord::DynamicTimeout
   module TimeoutAdapterExtension_Rails_7_0
     def log(*args, **kwargs, &block)
       super do
-        set_dynamic_timeout(@connection, ActiveRecord::Base.current_timeout)
+        set_dynamic_timeout(@connection, ActiveRecord::Base.current_timeout_seconds)
         yield
       ensure
         if timeout_set_client_side?

data/lib/active_record/dynamic_timeout/extensions/base_extension.rb

@@ -8,15 +8,19 @@ module ActiveRecord::DynamicTimeout
     extend ActiveSupport::Concern
 
     module ClassMethods
-      def with_timeout(timeout)
-        (timeout.is_a?(Integer) || timeout.nil?) or raise ArgumentError, "timeout must be an Integer or NilClass, got: `#{timeout.inspect}`"
-        timeout_stack << timeout
-        yield
-      ensure
-        timeout_stack.pop
+      # @param [Numeric, NilClass] timeout_seconds The timeout in seconds, or nil to disable the timeout.
+      def with_timeout(timeout_seconds)
+        (timeout_seconds.is_a?(Numeric) || timeout_seconds.nil?) or raise ArgumentError, "timeout_seconds must be Numeric or nil, got: `#{timeout_seconds.inspect}`"
+        begin
+          timeout_stack << timeout_seconds
+          yield
+        ensure
+          timeout_stack.pop
+        end
       end
 
-      def current_timeout
+      # @return [Numeric, NilClass] The current timeout in seconds, or nil if no timeout is set.
+      def current_timeout_seconds
         timeout_stack.last
       end
 

data/lib/active_record/dynamic_timeout/extensions/mysql2_adapter_extension.rb

@@ -1,6 +1,7 @@
 module ActiveRecord::DynamicTimeout
   module Mysql2AdapterExtension
-    def set_connection_timeout(raw_connection, timeout)
+    def set_connection_timeout(raw_connection, timeout_seconds)
+      timeout = timeout_seconds.ceil.to_i # Round floats up to the nearest integer
       set_timeouts_on_connection(raw_connection, read_timeout: timeout, write_timeout: timeout)
     end
 

data/lib/active_record/dynamic_timeout/extensions/postgres_adapter_extension.rb

@@ -1,15 +1,21 @@
 module ActiveRecord::DynamicTimeout
   module PostgresAdapterExtension
-    def set_connection_timeout(raw_connection, timeout)
-      if timeout.nil? || timeout == ":default" || timeout == :default
+    def set_connection_timeout(raw_connection, timeout_seconds)
+      if set_to_default_timeout?(timeout_seconds)
         raw_connection.query("SET SESSION statement_timeout TO DEFAULT")
       else
+        timeout = (timeout_seconds * 1000).to_i
         raw_connection.query("SET SESSION statement_timeout TO #{quote(timeout)}")
       end
     end
 
     def reset_connection_timeout(raw_connection)
-      set_connection_timeout(raw_connection, default_statement_timeout)
+      timeout = default_statement_timeout
+      if set_to_default_timeout?(timeout)
+        raw_connection.query("SET SESSION statement_timeout TO DEFAULT")
+      else
+        raw_connection.query("SET SESSION statement_timeout TO #{quote(timeout)}")
+      end
     end
 
     def timeout_set_client_side?
@@ -22,6 +28,12 @@ module ActiveRecord::DynamicTimeout
 
     private
 
+    # This method is copying how Rails configures session variables from the database config file.
+    # https://github.com/rails/rails/blob/main/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb#L970-L984
+    def set_to_default_timeout?(timeout)
+      timeout.nil? || timeout == ":default" || timeout == :default
+    end
+
     def default_statement_timeout
       unless defined?(@default_statement_timeout)
         @default_statement_timeout = @config.fetch(:variables, {}).stringify_keys["statement_timeout"]

data/lib/active_record/dynamic_timeout/extensions/sqlite_adapter_extension.rb

@@ -2,25 +2,24 @@
 
 module ActiveRecord::DynamicTimeout
   module SqliteAdapterExtension
-    def set_connection_timeout(raw_connection, timeout)
-      if timeout
-        raw_connection.busy_timeout(timeout)
+    def set_connection_timeout(raw_connection, timeout_seconds)
+      if timeout_seconds
+        raw_connection.statement_timeout = (timeout_seconds * 1000).to_i
       else
-        raw_connection.busy_timeout(0)
+        raw_connection.statement_timeout = 0
       end
     end
 
     def reset_connection_timeout(raw_connection)
-      timeout = @config[:timeout]
-      set_connection_timeout(raw_connection, self.class.type_cast_config_to_integer(timeout))
+      raw_connection.statement_timeout = 0
     end
 
     def timeout_set_client_side?
-      false
+      true
     end
 
     def supports_dynamic_timeouts?
-      true
+      SQLite3::VERSION >= "2"
     end
   end
 end

data/lib/active_record/dynamic_timeout/extensions/trilogy_adapter_extension.rb

@@ -1,6 +1,7 @@
 module ActiveRecord::DynamicTimeout
   module TrilogyAdapterExtension
-    def set_connection_timeout(raw_connection, timeout)
+    def set_connection_timeout(raw_connection, timeout_seconds)
+      timeout = timeout_seconds.ceil.to_i # Round floats up to the nearest integer
       set_timeouts_on_connection(raw_connection, read_timeout: timeout, write_timeout: timeout)
     end
 

data/lib/active_record/dynamic_timeout/initializer.rb

@@ -2,7 +2,6 @@
 
 require "active_record"
 require "active_support"
-require_relative "../dynamic_timeout"
 require_relative "extensions/base_extension"
 require_relative "extensions/abstract_adapter_extension"
 require_relative "extensions/mysql2_adapter_extension"
@@ -36,7 +35,7 @@ module ActiveRecord::DynamicTimeout
                     when "ActiveRecord::ConnectionAdapters::PostgreSQLAdapter"
                       ActiveRecord::DynamicTimeout::PostgresAdapterExtension
                     end
-        adapter_class.prepend(extension) if extension
+        adapter_class.include(extension) if extension
       end
     end
   end

data/lib/active_record/dynamic_timeout/railtie.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../dynamic_timeout"
 require_relative "initializer"
 
 module ActiveRecord::DynamicTimeout

data/lib/active_record/dynamic_timeout/version.rb

@@ -1,5 +1,5 @@
 module ActiveRecord
   module DynamicTimeout
-    VERSION = '0.0.1.rc2'
+    VERSION = '0.0.1'
   end
 end

data/lib/active_record/dynamic_timeout.rb

@@ -3,6 +3,9 @@
 require "active_record"
 require "active_support"
 
+require_relative "dynamic_timeout/version"
+require_relative "dynamic_timeout/initializer"
+
 module ActiveRecord
   module DynamicTimeout
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-dynamic_timeout
 version: !ruby/object:Gem::Version
-  version: 0.0.1.rc2
+  version: 0.0.1
 platform: ruby
 authors:
 - Tristan Starck
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-22 00:00:00.000000000 Z
+date: 2024-10-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -33,6 +33,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - Appraisals
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.md
@@ -66,9 +67,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.3.27
 signing_key: