solid_objects 0.8.0 → 0.10.0

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

@@ -32,6 +32,43 @@ module SolidObjects
       @fixed_connection = connection_pool ? nil : connection
     end
 
+    # The oldest server the adapter has been exercised against. Reported rather
+    # than enforced: refusing to boot on an untested server would be a worse
+    # failure than running on one.
+    # @rbs () -> Gem::Version?
+    def minimum_server_version
+      nil
+    end
+
+    # @rbs () -> Gem::Version
+    def server_version
+      with_connection do |connection|
+        Gem::Version.new(connection.database_version.to_s)
+      end
+    end
+
+    # One observed version decides both the status and the message. Reading it
+    # again could let a transient failure replace an already determined result.
+    # @rbs (?Gem::Version?) -> Array[String]
+    def unsupported_server_reasons(observed = nil)
+      observed ||= server_version
+      reasons = []
+      minimum = minimum_server_version
+      if minimum && observed < minimum
+        reasons << "#{self.class.name.demodulize} #{observed} is older than " \
+          "Solid Objects requires, which is #{minimum}"
+      end
+      reasons.concat(additional_server_reasons)
+      reasons
+    rescue => error
+      [ "the database server could not be verified: #{error.class}: #{error.message}" ]
+    end
+
+    # @rbs () -> Array[String]
+    def additional_server_reasons
+      []
+    end
+
     # @rbs () -> bool
     def supports_skip_locked?
       false

data/lib/solid_objects/database_adapters/mysql.rb

@@ -13,6 +13,34 @@ module SolidObjects
         "FOR UPDATE SKIP LOCKED"
       end
 
+      # A non-transactional engine would silently break fenced commits, so the
+      # storage engine is verified rather than assumed.
+      # @rbs () -> Array[String]
+      def additional_server_reasons
+        tables = non_innodb_tables
+        return [] if tables.empty?
+
+        [ "these Solid Objects tables do not use InnoDB, so their commits are " \
+          "not transactional: #{tables.join(", ")}" ]
+      end
+
+      # @rbs () -> Array[String]
+      def non_innodb_tables
+        names = SolidObjects::Doctor::EXPECTED_COLUMNS.keys.map { |name| SolidObjects.table_name(name) }
+        with_connection do |connection|
+          connection.select_rows(<<~SQL.squish).filter_map { |table, engine| table if engine != "InnoDB" }
+            SELECT table_name, engine FROM information_schema.tables
+            WHERE table_schema = DATABASE()
+              AND table_name IN (#{names.map { |name| connection.quote(name) }.join(", ")})
+          SQL
+        end
+      end
+
+      # @rbs () -> Gem::Version?
+      def minimum_server_version
+        Gem::Version.new("8.0")
+      end
+
       # @rbs () -> String
       def current_time_expression
         "CURRENT_TIMESTAMP(6)"

data/lib/solid_objects/database_adapters/postgresql.rb

@@ -3,6 +3,21 @@
 module SolidObjects
   module DatabaseAdapters
     class Postgresql < DatabaseAdapter
+      # @rbs () -> Gem::Version?
+      def minimum_server_version
+        Gem::Version.new("13")
+      end
+
+      # PostgreSQL reports a packed integer, 170010 for 17.10, so comparing it
+      # directly would make every server look newer than any minimum.
+      # @rbs () -> Gem::Version
+      def server_version
+        packed = with_connection { |connection| connection.database_version.to_i }
+        return super unless packed.positive?
+
+        Gem::Version.new("#{packed / 10_000}.#{packed % 10_000}")
+      end
+
       # @rbs () -> bool
       def supports_skip_locked?
         true

data/lib/solid_objects/database_adapters/sqlite.rb

@@ -8,6 +8,11 @@ module SolidObjects
       LOCK_RETRY_MUTEX = Thread::Mutex.new
       LOCK_RETRY_CONDITION = Thread::ConditionVariable.new
 
+      # @rbs () -> Gem::Version?
+      def minimum_server_version
+        Gem::Version.new("3.35")
+      end
+
       # @rbs () -> String
       def current_time_expression
         "STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')"

data/lib/solid_objects/doctor.rb

@@ -111,6 +111,7 @@ module SolidObjects
         configuration_check,
         schema_check,
         check_authorization,
+        check_database_server,
         schema_check.failed? ? skipped_runtime : check_runtime,
         ready_for_round_trip?(configuration_check, schema_check) ?
           check_sync_round_trip :
@@ -191,6 +192,21 @@ module SolidObjects
       pass(:authorization, "#{allowed.length} of 5 policies allowed a neutral context")
     end
 
+    # @rbs () -> Check
+    def check_database_server
+      adapter = SolidObjects.database_adapter
+      observed = adapter.server_version
+      reasons = adapter.unsupported_server_reasons(observed)
+      return warn_check(:database_server, reasons.join("; ")) unless reasons.empty?
+
+      pass(
+        :database_server,
+        "#{adapter.class.name.demodulize} #{observed} meets the tested minimum"
+      )
+    rescue => error
+      warn_check(:database_server, "#{error.class}: #{error.message}")
+    end
+
     # @rbs () -> Check
     def check_runtime
       cutoff = SolidObjects.database_adapter.database_now -

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.8.0"
+  VERSION = "0.10.0"
 end