solid_objects 0.9.0 → 0.10.1

data/lib/solid_objects/actor_channel.rb

@@ -78,19 +78,59 @@ module SolidObjects
       return if payload_names.nil? || payload_names.empty?
       return unless newer_payload_revision?(snapshot)
 
-      payload_names.each do |name|
-        payload = PayloadBroadcast.new(
-          snapshot:,
-          name:,
-          authorization_context: connection
-        ).call
-        transmit TurboStreamRenderer.state_payload(payload)
-      rescue Unauthorized
-        next
-      end
+      # The watermark records what the subscriber has, so a revision with a
+      # failed payload must not advance it: dedup would skip every later
+      # attempt at that revision and the actor may not mutate again for a long
+      # time. Every name is still attempted before the decision is made.
+      attempts = payload_names.map { |name| transmit_state_payload(snapshot, name) }
+      return if attempts.any?(false)
+
       @payload_revision = [ snapshot.instance_id, snapshot.revision ]
     end
 
+    # A payload is one subscriber's view of one name. Letting it raise through
+    # here would reject the subscription or abandon the rest of a broadcast, so
+    # a failure is confined to the payload that caused it and reported. The
+    # exception message is deliberately not instrumented: a payload block reads
+    # actor state, so its message is the one place subscriber state could leak
+    # into logs.
+    #
+    # Returns whether this revision was settled for the name. An unauthorized
+    # payload is settled: the decision is stable, so retrying it would only
+    # re-deliver its authorized siblings.
+    # @rbs (ActorSnapshot, String) -> bool
+    def transmit_state_payload(snapshot, name)
+      payload = PayloadBroadcast.new(
+        snapshot:,
+        name:,
+        authorization_context: payload_authorization_context(name)
+      ).call
+      transmit TurboStreamRenderer.state_payload(payload)
+      true
+    rescue Unauthorized
+      true
+    rescue => error
+      SolidObjects.instrument(
+        :payload_broadcast_failed,
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id,
+        payload_name: name,
+        error_class: error.class.name
+      )
+      false
+    end
+
+    # Resolves the Cable connection to whatever the application uses as an
+    # authorization subject, so a payload block and `authorize_query` see the
+    # same object a controller render would pass.
+    # @rbs (String) -> untyped
+    def payload_authorization_context(name)
+      callable = SolidObjects.configuration.payload_authorization_context
+      return callable.call(connection:) unless CallableKeywords.accepts?(callable, :payload_name)
+
+      callable.call(connection:, payload_name: name)
+    end
+
     # @rbs (ActorSnapshot) -> bool
     def newer_payload_revision?(snapshot)
       current = @payload_revision

data/lib/solid_objects/callable_keywords.rb

@@ -0,0 +1,29 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  # Authorization context resolvers gained keywords after applications had
+  # already written them, so a resolver is called with what it declared it
+  # accepts rather than with everything the caller could offer.
+  module CallableKeywords
+    class << self
+      # @rbs (untyped, Symbol) -> bool
+      def accepts?(callable, keyword)
+        parameters(callable).any? do |type, name|
+          type == :keyrest || (%i[key keyreq].include?(type) && name == keyword)
+        end
+      end
+
+      private
+
+      # A lambda answers `parameters` directly; a callable object answers it
+      # through its `call` method.
+      # @rbs (untyped) -> Array[[ Symbol, Symbol ]]
+      def parameters(callable)
+        return callable.parameters if callable.respond_to?(:parameters)
+        return callable.method(:call).parameters if callable.respond_to?(:call)
+
+        []
+      end
+    end
+  end
+end

data/lib/solid_objects/component_subscriptions.rb

@@ -52,26 +52,19 @@ module SolidObjects
         registration.dependencies.include?(observable_name) &&
           newer_revision?(registration.dom_id, instance_id, revision)
       end
-      batched, individual = changed.partition(&:batch)
-      streams = individual.map { |registration| refresh(registration, instance_id, revision) }
-      batched.group_by(&:batch).each_value do |group|
-        group.each { |registration| record_revision(registration, instance_id, revision) }
-        streams << TurboStreamRenderer.batch_refresh(group, instance_id, revision)
-      end
-      streams
+      refresh_streams(changed, instance_id, revision)
     end
 
     # @rbs (ActorSnapshot) -> Array[String]
     def reconnect_refreshes(snapshot)
-      registrations.filter_map do |registration|
-        next unless newer_revision?(
+      stale = registrations.select do |registration|
+        newer_revision?(
           registration.dom_id,
           snapshot.instance_id,
           snapshot.revision
         )
-
-        refresh(registration, snapshot.instance_id, snapshot.revision)
       end
+      refresh_streams(stale, snapshot.instance_id, snapshot.revision)
     end
 
     class << self
@@ -91,6 +84,21 @@ module SolidObjects
 
     attr_reader :registrations, :revisions
 
+    # Live invalidations and reconnect replays share this, so a reconnecting
+    # client pays the same number of requests a connected one does.
+    # @rbs (Array[ComponentRegistration], Integer, Integer) -> Array[String]
+    def refresh_streams(changed, instance_id, revision)
+      batched, individual = changed.partition(&:batch)
+      streams = individual.map do |registration|
+        refresh(registration, instance_id, revision)
+      end
+      batched.group_by(&:batch).each_value do |group|
+        group.each { |registration| record_revision(registration, instance_id, revision) }
+        streams << TurboStreamRenderer.batch_refresh(group, instance_id, revision)
+      end
+      streams
+    end
+
     # @rbs (ComponentRegistration, Integer, Integer) -> void
     def record_revision(registration, instance_id, revision)
       revisions[registration.dom_id] = [ instance_id, revision ]

data/lib/solid_objects/configuration.rb

@@ -22,6 +22,7 @@ module SolidObjects
     # @rbs @process_alive_threshold: Float
     # @rbs @shutdown_timeout: Float
     # @rbs @supervisor_monitor_interval: Float
+    # @rbs @retention_interval: Float
     # @rbs @dead_process_cleanup_interval: Float
     # @rbs @message_retention: Numeric
     # @rbs @message_retention_by_actor_type: Hash[String, Numeric]
@@ -39,6 +40,7 @@ module SolidObjects
     # @rbs @wake_up_adapter: untyped
     # @rbs @component_path_resolver: Proc?
     # @rbs @component_authorization_context: Proc
+    # @rbs @payload_authorization_context: Proc
     # @rbs @authorize_message: Proc
     # @rbs @authorize_query: Proc
     # @rbs @authorize_destroy: Proc
@@ -65,6 +67,7 @@ module SolidObjects
       :process_alive_threshold,
       :shutdown_timeout,
       :supervisor_monitor_interval,
+      :retention_interval,
       :dead_process_cleanup_interval,
       :message_retention,
       :message_retention_by_actor_type,
@@ -82,6 +85,7 @@ module SolidObjects
       :wake_up_adapter,
       :component_path_resolver,
       :component_authorization_context,
+      :payload_authorization_context,
       :authorize_message,
       :authorize_query,
       :authorize_destroy,
@@ -108,6 +112,7 @@ module SolidObjects
       @lock_retry_attempts = 10
       @supervisor_monitor_interval = 1.0
       @dead_process_cleanup_interval = 60.0
+      @retention_interval = 3600.0
       @process_heartbeat_interval = 15.0
       @process_alive_threshold = 60.0
       @shutdown_timeout = 15.0
@@ -126,6 +131,7 @@ module SolidObjects
       @wake_up_adapter = nil
       @component_path_resolver = nil
       @component_authorization_context = ->(controller:) { controller }
+      @payload_authorization_context = ->(connection:) { connection }
       @logger = if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
         Rails.logger
       else
@@ -144,6 +150,10 @@ module SolidObjects
         raise ArgumentError, "table_name_prefix must contain lowercase letters, digits, and underscores"
       end
 
+      if retention_interval.negative?
+        raise ArgumentError, "retention_interval must not be negative"
+      end
+
       unless supervisor_monitor_interval.positive?
         raise ArgumentError, "supervisor_monitor_interval must be positive"
       end
@@ -176,6 +186,9 @@ module SolidObjects
       unless component_authorization_context.respond_to?(:call)
         raise ArgumentError, "component_authorization_context must respond to call"
       end
+      unless payload_authorization_context.respond_to?(:call)
+        raise ArgumentError, "payload_authorization_context must respond to call"
+      end
 
       self
     end

data/lib/solid_objects/database_adapter.rb

@@ -7,15 +7,35 @@ module SolidObjects
     TRANSACTION_CLOCK = :solid_objects_transaction_clock
     TRANSACTION_CLOCK_SCOPE = :solid_objects_transaction_clock_scope
 
+    # An adapter name is a client name, not a protocol name. Trilogy reports
+    # "Trilogy" while speaking MySQL, so a pattern that only knows the mysql2
+    # gem rejects a database Solid Objects fully supports. Every decision that
+    # depends on the database goes through this one table, so a client cannot
+    # be accepted in one place and rejected in another.
+    FAMILIES = {
+      postgresql: /postgres/i,
+      mysql: /mysql|trilogy/i,
+      sqlite: /sqlite/i
+    }.freeze
+
     class << self
+      # @rbs (untyped) -> Symbol?
+      def family(connection)
+        adapter_name = connection.adapter_name
+        FAMILIES.each do |family, pattern|
+          return family if adapter_name.match?(pattern)
+        end
+        nil
+      end
+
       # @rbs (untyped) -> DatabaseAdapter
       def for(connection)
-        case connection.adapter_name
-        when /postgres/i
+        case family(connection)
+        when :postgresql
           DatabaseAdapters::Postgresql.new(connection)
-        when /mysql/i
+        when :mysql
           DatabaseAdapters::Mysql.new(connection)
-        when /sqlite/i
+        when :sqlite
           DatabaseAdapters::Sqlite.new(connection)
         else
           raise UnsupportedDatabase, "unsupported database adapter #{connection.adapter_name.inspect}"

data/lib/solid_objects/database_adapters/mysql.rb

@@ -3,6 +3,8 @@
 module SolidObjects
   module DatabaseAdapters
     class Mysql < DatabaseAdapter
+      MAXIMUM_EXECUTION_TIME_EXCEEDED = 3024
+
       # @rbs () -> bool
       def supports_skip_locked?
         true
@@ -78,19 +80,33 @@ module SolidObjects
         end
       end
 
+      # A deadline is enforced by asking the server to interrupt the statement,
+      # so recognising that interruption is what turns it back into a timeout
+      # the caller asked for. Active Record classifies it for every client, and
+      # the raw code is the fallback: mysql2 names it `error_number` and
+      # Trilogy names it `error_code`, so both are read.
       # @rbs (Exception) -> bool
       def deadline_error?(error)
         return false unless SyncDeadline.active?
         return true if error.is_a?(ActiveRecord::LockWaitTimeout)
+        return true if error.is_a?(ActiveRecord::StatementTimeout)
 
         cause = error
         while cause
-          return true if cause.respond_to?(:error_number) && cause.error_number == 3024
+          return true if error_code(cause) == MAXIMUM_EXECUTION_TIME_EXCEEDED
 
           cause = cause.cause
         end
         false
       end
+
+      # @rbs (Exception) -> Integer?
+      def error_code(error)
+        return error.error_number if error.respond_to?(:error_number)
+        return error.error_code if error.respond_to?(:error_code)
+
+        nil
+      end
     end
   end
 end

data/lib/solid_objects/payload_broadcast.rb

@@ -41,7 +41,7 @@ module SolidObjects
     # @rbs (ActorDefinition::Handler) -> untyped
     def rendered_payload(handler)
       payload = Serialization.dump(
-        handler.block.call(snapshot.actor, authorization_context),
+        evaluated_payload(handler),
         max_bytes: MAXIMUM_PAYLOAD_BYTES
       )
       return payload if payload.is_a?(Hash) || payload.is_a?(Array)
@@ -50,6 +50,34 @@ module SolidObjects
         "payload broadcast #{name.inspect} must return a JSON object or array"
     end
 
+    # The block runs against the actor instance, like every other block in the
+    # actor DSL, and still receives the actor and the resolved authorization
+    # context as arguments, so blocks written to the documented signature are
+    # unaffected.
+    # @rbs (ActorDefinition::Handler) -> untyped
+    def evaluated_payload(handler)
+      actor = snapshot.actor
+      actor.instance_exec(actor, authorization_context, &handler.block)
+    rescue NameError => error
+      raise unless class_level_receiver?(error)
+
+      raise InvalidPayloadBroadcast,
+        "payload broadcast #{name.inspect} called #{error.name.inspect} on the " \
+          "actor class. Payload blocks now run against the actor instance, like " \
+          "every other actor block. Call it on the class explicitly."
+    end
+
+    # Distinguishes a block that relied on the old class-level receiver from an
+    # ordinary typo, so the one behaviour change reports itself instead of
+    # surfacing as an unexplained NameError.
+    # @rbs (NameError[untyped]) -> bool
+    def class_level_receiver?(error)
+      error.receiver.equal?(snapshot.actor) &&
+        snapshot.actor_class.respond_to?(error.name)
+    rescue ArgumentError, NameError
+      false
+    end
+
     # @rbs () -> void
     def authorize!
       authorized = SolidObjects.configuration.authorize_query.call(

data/lib/solid_objects/supervisor.rb

@@ -2,11 +2,14 @@
 
 module SolidObjects
   class Supervisor
+    MAXIMUM_RETENTION_BACKOFF_DOUBLINGS = 16
+
     # @rbs @components: Array[Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor]
     # @rbs @threads: Array[Thread]
     # @rbs @monitor: Thread?
     # @rbs @started: bool
     # @rbs @cleaned_up_at: Float
+    # @rbs @retention: Thread?
     # @rbs @lifecycle: Thread::Mutex
 
     # @rbs (?worker_count: Integer, ?effect_worker_count: Integer, ?broadcast_worker_count: Integer, ?reminder_scheduler_count: Integer) -> void
@@ -26,6 +29,7 @@ module SolidObjects
       @monitor = nil
       @started = false
       @cleaned_up_at = nil
+      @retention = nil
       @lifecycle = Thread::Mutex.new
     end
 
@@ -44,6 +48,7 @@ module SolidObjects
       @started = true
       @threads = components.map { |component| supervise(component) }
       @monitor = Thread.new { monitor_loop }
+      @retention = Thread.new { retention_loop }
       SolidObjects.instrument(:"supervisor.started", component_count: components.length)
     end
 
@@ -57,6 +62,7 @@ module SolidObjects
         # list, or never starts.
         @lifecycle.synchronize { @started = false }
         stop_monitor
+        stop_retention
         components.each(&:request_shutdown)
         join_until_timeout
         components.reject(&:stopped?).each(&:stop)
@@ -133,6 +139,76 @@ module SolidObjects
       error.class.name
     end
 
+    # Retention gets its own thread rather than sharing the monitor's. A large
+    # backlog or a lock wait can make a pass slow, and role replacement must not
+    # wait behind housekeeping.
+    # @rbs () -> void
+    def retention_loop
+      failures = 0
+      while @started
+        begin
+          prune_expired_records
+          failures = 0
+        rescue => error
+          failures += 1
+          SolidObjects.instrument(
+            :"supervisor.retention_failed",
+            error_class: error.class.name,
+            error_message: error.message
+          )
+        end
+        wait_for_next_retention(failures)
+      end
+    end
+
+    # Sleeping the whole interval would make shutdown wait out an hour-long
+    # nap, so the pause is taken in short steps that notice a stop request.
+    # @rbs (Integer) -> void
+    def wait_for_next_retention(failures)
+      deadline = monotonic_now + retention_pause(failures)
+      step = SolidObjects.configuration.supervisor_monitor_interval
+      while @started && monotonic_now < deadline
+        sleep [ step, deadline - monotonic_now ].min
+      end
+    end
+
+    # Every actor call writes a durable message row, so retention that is only
+    # configured and never run leaves those rows to grow without bound. The
+    # supervisor runs it rather than requiring every application to schedule
+    # its own job.
+    # @rbs () -> void
+    def prune_expired_records
+      return unless SolidObjects.configuration.retention_interval.positive?
+
+      MessagePruner.new.prune
+      ProcessPruner.new.prune
+    end
+
+    # A transient lock or connection error must not defer retention for the
+    # whole interval, so a failed pass retries at monitor cadence. The pause
+    # then doubles per consecutive failure, capped by the interval, so a
+    # database that stays down is not polled once a second forever.
+    # @rbs (Integer) -> Float
+    def retention_pause(failures)
+      interval = SolidObjects.configuration.retention_interval
+      interval = SolidObjects.configuration.supervisor_monitor_interval unless interval.positive?
+      return interval if failures.zero?
+
+      backoff = SolidObjects.configuration.supervisor_monitor_interval *
+        (2**[ failures - 1, MAXIMUM_RETENTION_BACKOFF_DOUBLINGS ].min)
+      [ backoff, interval ].min
+    end
+
+    # @rbs () -> void
+    def stop_retention
+      retention = @retention
+      @retention = nil
+      return unless retention
+
+      retention.join(SolidObjects.configuration.shutdown_timeout)
+      retention.kill if retention.alive?
+    end
+
     # @rbs () -> void
     def cleanup_dead_processes
       interval = SolidObjects.configuration.dead_process_cleanup_interval

data/lib/solid_objects/version.rb

@@ -1,5 +1,5 @@
 # rbs_inline: enabled
 
 module SolidObjects
-  VERSION = "0.9.0"
+  VERSION = "0.10.1"
 end

data/lib/solid_objects/wake_up_adapters.rb

@@ -15,7 +15,7 @@ module SolidObjects
     #
     # @rbs (?untyped) -> untyped
     def for(connection = Record.connection)
-      return Postgresql.new if connection.adapter_name.match?(/postgres/i)
+      return Postgresql.new if DatabaseAdapter.family(connection) == :postgresql
 
       WakeUp.new
     end

data/lib/solid_objects.rb

@@ -13,6 +13,7 @@ require "securerandom"
 require "solid_objects/version"
 require "solid_objects/errors"
 require "solid_objects/sync_deadline"
+require "solid_objects/callable_keywords"
 require "solid_objects/configuration"
 require "solid_objects/instrumentation"
 require "solid_objects/log_subscriber"
@@ -45,6 +46,7 @@ require "solid_objects/state_snapshot"
 require "solid_objects/actor_view"
 require "solid_objects/actor_channel"
 require "solid_objects/action_cable_broadcast_adapter"
+require "solid_objects/database_adapter"
 require "solid_objects/wake_up"
 require "solid_objects/wake_up_adapters/postgresql"
 require "solid_objects/wake_up_adapters/redis"

data/sig/generated/controllers/solid_objects/components_controller.rbs

@@ -27,14 +27,6 @@ module SolidObjects
     # @rbs (Array[ComponentRegistration]) -> untyped
     def component_authorization_context: (Array[ComponentRegistration]) -> untyped
 
-    # A lambda answers `parameters` directly; a callable object answers it
-    # through its `call` method.
-    # @rbs (untyped) -> bool
-    def accepts_registrations?: (untyped) -> bool
-
-    # @rbs (untyped) -> Array[[ Symbol, Symbol ]]
-    def callable_parameters: (untyped) -> Array[[ Symbol, Symbol ]]
-
     # @rbs (ComponentRegistration) -> Hash[Symbol, untyped]
     def registration_payload: (ComponentRegistration) -> Hash[Symbol, untyped]
 

data/sig/generated/lib/solid_objects/actor_channel.rbs

@@ -21,6 +21,25 @@ module SolidObjects
     # @rbs (ActorSnapshot) -> void
     def transmit_state_payloads: (ActorSnapshot) -> void
 
+    # A payload is one subscriber's view of one name. Letting it raise through
+    # here would reject the subscription or abandon the rest of a broadcast, so
+    # a failure is confined to the payload that caused it and reported. The
+    # exception message is deliberately not instrumented: a payload block reads
+    # actor state, so its message is the one place subscriber state could leak
+    # into logs.
+    #
+    # Returns whether this revision was settled for the name. An unauthorized
+    # payload is settled: the decision is stable, so retrying it would only
+    # re-deliver its authorized siblings.
+    # @rbs (ActorSnapshot, String) -> bool
+    def transmit_state_payload: (ActorSnapshot, String) -> bool
+
+    # Resolves the Cable connection to whatever the application uses as an
+    # authorization subject, so a payload block and `authorize_query` see the
+    # same object a controller render would pass.
+    # @rbs (String) -> untyped
+    def payload_authorization_context: (String) -> untyped
+
     # @rbs (ActorSnapshot) -> bool
     def newer_payload_revision?: (ActorSnapshot) -> bool
 

data/sig/generated/lib/solid_objects/callable_keywords.rbs

@@ -0,0 +1,16 @@
+# Generated from lib/solid_objects/callable_keywords.rb with RBS::Inline
+
+module SolidObjects
+  # Authorization context resolvers gained keywords after applications had
+  # already written them, so a resolver is called with what it declared it
+  # accepts rather than with everything the caller could offer.
+  module CallableKeywords
+    # @rbs (untyped, Symbol) -> bool
+    def self.accepts?: (untyped, Symbol) -> bool
+
+    # A lambda answers `parameters` directly; a callable object answers it
+    # through its `call` method.
+    # @rbs (untyped) -> Array[[ Symbol, Symbol ]]
+    private def self.parameters: (untyped) -> Array[[ Symbol, Symbol ]]
+  end
+end

data/sig/generated/lib/solid_objects/component_subscriptions.rbs

@@ -31,6 +31,11 @@ module SolidObjects
 
     attr_reader revisions: untyped
 
+    # Live invalidations and reconnect replays share this, so a reconnecting
+    # client pays the same number of requests a connected one does.
+    # @rbs (Array[ComponentRegistration], Integer, Integer) -> Array[String]
+    def refresh_streams: (Array[ComponentRegistration], Integer, Integer) -> Array[String]
+
     # @rbs (ComponentRegistration, Integer, Integer) -> void
     def record_revision: (ComponentRegistration, Integer, Integer) -> void
 

data/sig/generated/lib/solid_objects/configuration.rbs

@@ -2,10 +2,10 @@
 
 module SolidObjects
   class Configuration
-    @shutdown_timeout: Float
-
     @supervisor_monitor_interval: Float
 
+    @retention_interval: Float
+
     @dead_process_cleanup_interval: Float
 
     @message_retention: Numeric
@@ -40,6 +40,8 @@ module SolidObjects
 
     @component_authorization_context: Proc
 
+    @payload_authorization_context: Proc
+
     @authorize_message: Proc
 
     @authorize_query: Proc
@@ -86,6 +88,8 @@ module SolidObjects
 
     @process_alive_threshold: Float
 
+    @shutdown_timeout: Float
+
     attr_accessor table_name_prefix: untyped
 
     attr_accessor polling_interval: untyped
@@ -126,6 +130,8 @@ module SolidObjects
 
     attr_accessor supervisor_monitor_interval: untyped
 
+    attr_accessor retention_interval: untyped
+
     attr_accessor dead_process_cleanup_interval: untyped
 
     attr_accessor message_retention: untyped
@@ -160,6 +166,8 @@ module SolidObjects
 
     attr_accessor component_authorization_context: untyped
 
+    attr_accessor payload_authorization_context: untyped
+
     attr_accessor authorize_message: untyped
 
     attr_accessor authorize_query: untyped

data/sig/generated/lib/solid_objects/database_adapter.rbs

@@ -6,6 +6,16 @@ module SolidObjects
 
     TRANSACTION_CLOCK_SCOPE: ::Symbol
 
+    # An adapter name is a client name, not a protocol name. Trilogy reports
+    # "Trilogy" while speaking MySQL, so a pattern that only knows the mysql2
+    # gem rejects a database Solid Objects fully supports. Every decision that
+    # depends on the database goes through this one table, so a client cannot
+    # be accepted in one place and rejected in another.
+    FAMILIES: untyped
+
+    # @rbs (untyped) -> Symbol?
+    def self.family: (untyped) -> Symbol?
+
     # @rbs (untyped) -> DatabaseAdapter
     def self.for: (untyped) -> DatabaseAdapter
 

data/sig/generated/lib/solid_objects/database_adapters/mysql.rbs

@@ -3,6 +3,8 @@
 module SolidObjects
   module DatabaseAdapters
     class Mysql < DatabaseAdapter
+      MAXIMUM_EXECUTION_TIME_EXCEEDED: ::Integer
+
       # @rbs () -> bool
       def supports_skip_locked?: () -> bool
 
@@ -28,8 +30,16 @@ module SolidObjects
       # @rbs (untyped) { () -> untyped } -> untyped
       def with_transaction_deadline: (untyped) { () -> untyped } -> untyped
 
+      # A deadline is enforced by asking the server to interrupt the statement,
+      # so recognising that interruption is what turns it back into a timeout
+      # the caller asked for. Active Record classifies it for every client, and
+      # the raw code is the fallback: mysql2 names it `error_number` and
+      # Trilogy names it `error_code`, so both are read.
       # @rbs (Exception) -> bool
       def deadline_error?: (Exception) -> bool
+
+      # @rbs (Exception) -> Integer?
+      def error_code: (Exception) -> Integer?
     end
   end
 end