rsmp 0.48.3 → 0.51.0

data/lib/rsmp/event_source.rb

@@ -0,0 +1,36 @@
+module RSMP
+  # Reactor-confined, ordered delivery of background lifecycle events.
+  module EventSource
+    attr_reader :event_receivers
+
+    def initialize_event_source
+      @event_receivers = []
+    end
+
+    def add_event_receiver(receiver)
+      raise ArgumentError, 'event receiver must respond to receive_event' unless receiver.respond_to?(:receive_event)
+
+      @event_receivers << receiver unless @event_receivers.include?(receiver)
+      receiver
+    end
+
+    def remove_event_receiver(receiver)
+      @event_receivers.delete(receiver)
+      receiver
+    end
+
+    def publish_event(event)
+      raise ArgumentError, 'event must be an RSMP::Event' unless event.is_a?(Event)
+
+      @event_receivers.dup.each do |receiver|
+        receiver.receive_event(event)
+      rescue StandardError => e
+        remove_event_receiver(receiver)
+        raise unless receiver.respond_to?(:crash)
+
+        receiver.crash(e)
+      end
+      event
+    end
+  end
+end

data/lib/rsmp/exchange.rb

@@ -0,0 +1,10 @@
+require 'forwardable'
+
+module RSMP
+  # A sent request and the immutable collection produced in response.
+  Exchange = Data.define(:request, :collection) do
+    extend Forwardable
+
+    def_delegators :collection, :messages, :reached, :matcher_status
+  end
+end

data/lib/rsmp/failure.rb

@@ -0,0 +1,23 @@
+module RSMP
+  # An expected operational failure. Failures are values: they describe why an
+  # operation could not complete without changing Async task control flow.
+  Failure = Data.define(:code, :message, :source, :context, :cause) do
+    def initialize(code:, message:, source:, context: {}, cause: nil)
+      raise ArgumentError, 'failure code must be a Symbol' unless code.is_a?(Symbol)
+      raise ArgumentError, 'failure source must be a Symbol' unless source.is_a?(Symbol)
+      raise ArgumentError, 'failure context must be a Hash' unless context.is_a?(Hash)
+
+      super(
+        code: code,
+        message: message.to_s.freeze,
+        source: source,
+        context: context.dup.freeze,
+        cause: cause
+      )
+    end
+
+    def to_s
+      message.empty? ? code.to_s : message
+    end
+  end
+end

data/lib/rsmp/helpers/error.rb

@@ -8,24 +8,24 @@ module RSMP
   class MalformedMessage < Error
   end
 
+  # Semantic failures which may be raised while processing a schema-valid peer
+  # message. The receive boundary converts only this explicit family to a peer
+  # Failure; unrelated exceptions retain their original stack trace.
+  class PeerMessageError < Error
+  end
+
   # Raised when schema validation fails.
   class SchemaError < Error
     attr_accessor :schemas
   end
 
-  class InvalidMessage < Error
+  class InvalidMessage < PeerMessageError
   end
 
   class UnknownMessage < Error
   end
 
-  class MissingAcknowledgment < Error
-  end
-
-  class MissingWatchdog < Error
-  end
-
-  class MessageRejected < Error
+  class MessageRejected < PeerMessageError
   end
 
   class MissingAttribute < InvalidMessage
@@ -37,36 +37,27 @@ module RSMP
   class HandshakeError < FatalError
   end
 
-  class NotReady < Error
-  end
-
-  class TimeoutError < Error
-  end
-
-  class DisconnectError < Error
-  end
-
   class ConnectionError < Error
   end
 
-  class UnknownComponent < Error
+  class UnknownComponent < PeerMessageError
   end
 
-  class UnknownCommand < Error
+  class UnknownCommand < PeerMessageError
   end
 
-  class UnknownStatus < Error
+  class UnknownStatus < PeerMessageError
   end
 
   class ConfigurationError < Error
   end
 
-  class RepeatedAlarmError < Error
+  class RepeatedAlarmError < PeerMessageError
   end
 
-  class RepeatedStatusError < Error
+  class RepeatedStatusError < PeerMessageError
   end
 
-  class TimestampError < Error
+  class TimestampError < PeerMessageError
   end
 end

data/lib/rsmp/message.rb

@@ -164,11 +164,14 @@ module RSMP
     end
 
     def validate(schemas)
-      errors = RSMP::Schema.validate attributes, schemas
-      return unless errors
+      RSMP::Schema.validate attributes, schemas
+    end
+
+    def validate!(schemas)
+      validation = validate(schemas)
+      return self if validation.valid?
 
-      error_string = errors.map { |item| item.reject { |e| e == '' } }.compact.join(', ').strip
-      err = SchemaError.new error_string.to_s
+      err = SchemaError.new validation.message
       err.schemas = schemas
       raise err
     end
@@ -199,13 +202,12 @@ module RSMP
 
   # Represents a malformed message with invalid attributes.
   class Malformed < Message
-    # rubocop:disable Lint/MissingSuper
+    # rubocop:disable-next Lint/MissingSuper
     def initialize(attributes = {})
       # don't call super, just copy (potentially invalid) attributes
       @attributes = {}
       @invalid_attributes = attributes
     end
-    # rubocop:enable Lint/MissingSuper
   end
 
   # Version message, lists supported versions and SXL information.
@@ -391,7 +393,7 @@ module RSMP
     end
 
     def original=(message)
-      raise InvalidArgument unless message
+      raise ArgumentError, 'original message is required' unless message
 
       @original = message
     end

data/lib/rsmp/node/node.rb

@@ -3,16 +3,16 @@ module RSMP
   class Node
     include Logging
     include Task
+    include EventSource
 
-    attr_reader :archive, :logger, :task, :deferred, :error_queue, :clock, :collector
+    attr_reader :archive, :logger, :task, :deferred, :clock, :collector
 
     def initialize(options = {})
       initialize_logging options
       initialize_task
+      initialize_event_source
       @deferred = []
       @clock = Clock.new
-      @error_queue = Async::Queue.new
-      @ignore_errors = []
       @collect = options[:collect]
     end
 
@@ -31,24 +31,6 @@ module RSMP
       super
     end
 
-    def ignore_errors(classes)
-      was = @ignore_errors
-      @ignore_errors = [classes].flatten
-      yield
-    ensure
-      @ignore_errors = was
-    end
-
-    def distribute_error(error, options = {})
-      return if @ignore_errors.find { |klass| error.is_a? klass }
-
-      if options[:level] == :internal
-        log ["#{error} in task: #{Async::Task.current}", error.backtrace].flatten.join("\n"),
-            level: :error
-      end
-      @error_queue.enqueue error
-    end
-
     def defer(key, item = nil)
       @deferred << [key, item]
     end

data/lib/rsmp/node/site/connections.rb

@@ -9,30 +9,25 @@ module RSMP
       end
     end
 
-    def listen_for_supervisors
+    def listen_for_supervisors(parent:)
       ip = @site_settings['ip'] || '0.0.0.0'
       port = @site_settings['port']
       log "Starting #{site_type_name} listener on #{ip}:#{port}", level: :info, timestamp: @clock.now
       @endpoint = IO::Endpoint.tcp(ip, port)
-      @accept_task = Async::Task.current.async do |task|
+      @accept_task = parent.async do |task|
         task.annotate 'site accept loop'
         accept_supervisor_connections
       end
 
       @ready_condition.signal
-      @accept_task.wait
+      @accept_task
     end
 
     def accept_supervisor_connections
       @endpoint.accept do |socket|
         accept_supervisor_connection socket
-      rescue StandardError => e
-        distribute_error e, level: :internal
       end
-    rescue Async::Stop
-      # Expected during shutdown - no action needed
-    rescue StandardError => e
-      distribute_error e, level: :internal
+      Async::Task.current.wait_all
     end
 
     def accept_supervisor_connection(socket)

data/lib/rsmp/node/site/site.rb

@@ -106,13 +106,24 @@ module RSMP
 
     def run
       log_site_starting
-      start_status_timer
+      barrier = Async::Barrier.new(parent: @task)
+      termination_task = barrier.async { wait_for_termination }
+      start_auxiliary_tasks(barrier)
       if server_role?
-        listen_for_supervisors
+        listen_for_supervisors(parent: barrier)
       else
-        @proxies.each(&:start)
-        @proxies.each(&:wait)
+        @proxies.each { |proxy| proxy.start(parent: barrier) }
       end
+      barrier.wait do |finished|
+        result = finished.wait
+        break result if finished.equal?(termination_task)
+      end
+    ensure
+      barrier.cancel if barrier && !barrier.empty?
+    end
+
+    def start_auxiliary_tasks(parent)
+      start_status_timer(parent: parent)
     end
 
     def aggregated_status_changed(component, _options = {})
@@ -135,16 +146,16 @@ module RSMP
 
     def send_alarm(alarm)
       @proxies.each do |proxy|
-        proxy.send_message alarm if proxy.receive_alarms?
+        proxy.send_generated_message alarm if proxy.receive_alarms?
       end
     end
 
-    def start_status_timer
+    def start_status_timer(parent:)
       return if @status_timer
 
       interval = @site_settings['intervals']['timer'] || 1
       log "Starting site status timer with interval #{interval} seconds", level: :debug
-      @status_timer = @task.async do |task|
+      @status_timer = parent.async do |task|
         task.annotate 'site status timer'
         run_status_timer task, interval
       end
@@ -155,11 +166,8 @@ module RSMP
       loop do
         now = Clock.now
         tick_status_subscriptions now
-      rescue StandardError => e
-        distribute_error e, level: :internal
-      ensure
         next_time += interval
-        duration = next_time - Time.now.to_f
+        duration = [next_time - Time.now.to_f, 0].max
         task.sleep duration
       end
     end
@@ -169,14 +177,14 @@ module RSMP
     end
 
     def stop_status_timer
-      @status_timer&.stop
+      @status_timer&.cancel if @status_timer&.running?
     ensure
       @status_timer = nil
     end
 
     def stop_subtasks
       stop_status_timer
-      @accept_task&.stop
+      @accept_task&.cancel if @accept_task&.running?
       @accept_task = nil
       @endpoint = nil
       super
@@ -190,11 +198,18 @@ module RSMP
 
     def wait_for_supervisor(ip, timeout:)
       supervisor = find_supervisor ip
-      return supervisor if supervisor
+      return Result.success(supervisor) if supervisor
 
       wait_for_condition(@proxies_condition, timeout: timeout) { find_supervisor ip }
-    rescue Async::TimeoutError
-      raise RSMP::TimeoutError, "Supervisor '#{ip}' did not connect within #{timeout}s"
+        .map { |proxy| proxy }
+    end
+
+    def wait_for_supervisor!(ip, timeout:)
+      result = wait_for_supervisor(ip, timeout: timeout)
+      return result.value! if result.success?
+
+      failure = result.failure.with(message: "Supervisor '#{ip}' did not connect within #{timeout}s")
+      Result.failure(failure: failure).value!
     end
 
     def find_supervisor(ip)

data/lib/rsmp/node/supervisor/modules/connection.rb

@@ -15,15 +15,29 @@ module RSMP
             reject_connection socket, info
           end
         rescue ConnectionError, HandshakeError => e
-          log "Rejected connection from #{remote_ip}:#{remote_port}, #{e}", level: :warning
-          distribute_error e
-        rescue StandardError => e
-          log "Connection: #{e}", exception: e, level: :error
-          distribute_error e, level: :internal
+          report_connection_rejection(e, remote_ip, remote_port)
         ensure
           close socket, info
         end
 
+        def report_connection_rejection(error, remote_ip, remote_port)
+          log "Rejected connection from #{remote_ip}:#{remote_port}, #{error}", level: :warning
+          failure = Failure.new(
+            code: error.is_a?(HandshakeError) ? :handshake_failed : :connection_rejected,
+            message: error.message,
+            source: :peer,
+            context: { ip: remote_ip, port: remote_port }
+          )
+          publish_event(
+            Event.new(
+              type: :connection_rejected,
+              source: self,
+              failure: failure,
+              context: { ip: remote_ip, port: remote_port }
+            )
+          )
+        end
+
         def accept?(_socket, _info)
           true
         end

data/lib/rsmp/node/supervisor/modules/sites.rb

@@ -23,24 +23,35 @@ module RSMP
 
         def wait_for_site(site_id, timeout:)
           site = find_site site_id
-          return site if site
+          return Result.success(site) if site
 
           wait_for_condition(@site_id_condition, timeout: timeout) do
             find_site site_id
           end
-        rescue Async::TimeoutError
+        end
+
+        def wait_for_site!(site_id, timeout:)
+          result = wait_for_site(site_id, timeout: timeout)
+          return result.value! if result.success?
+
           str = if site_id == :any
                   'No site connected'
                 else
                   "Site '#{site_id}' did not connect"
                 end
-          raise RSMP::TimeoutError, "#{str} within #{timeout}s"
+          Result.failure(failure: result.failure.with(message: "#{str} within #{timeout}s")).value!
         end
 
         def wait_for_site_disconnect(site_id, timeout:)
           wait_for_condition(@site_id_condition, timeout: timeout) { true unless find_site site_id }
-        rescue Async::TimeoutError
-          raise RSMP::TimeoutError, "Site '#{site_id}' did not disconnect within #{timeout}s"
+        end
+
+        def wait_for_site_disconnect!(site_id, timeout:)
+          result = wait_for_site_disconnect(site_id, timeout: timeout)
+          return result.value! if result.success?
+
+          failure = result.failure.with(message: "Site '#{site_id}' did not disconnect within #{timeout}s")
+          Result.failure(failure: failure).value!
         end
 
         def check_site_id(site_id)

data/lib/rsmp/node/supervisor/supervisor.rb

@@ -38,23 +38,19 @@ module RSMP
           timestamp: @clock.now
 
       @endpoint = IO::Endpoint.tcp('0.0.0.0', @supervisor_settings['port'])
-      @accept_task = Async::Task.current.async do |task|
+      barrier = Async::Barrier.new(parent: @task)
+      @accept_task = barrier.async do |task|
         task.annotate 'supervisor accept loop'
-        @endpoint.accept do |socket| # creates fibers
+        @endpoint.accept do |socket|
           handle_connection(socket)
-        rescue StandardError => e
-          distribute_error e, level: :internal
         end
-      rescue Async::Stop
-        # Expected during shutdown - no action needed
-      rescue StandardError => e
-        distribute_error e, level: :internal
+        task.wait_all
       end
 
       @ready_condition.signal
-      @accept_task.wait
-    rescue StandardError => e
-      distribute_error e, level: :internal
+      barrier.wait
+    ensure
+      barrier.cancel if barrier && !barrier.empty?
     end
 
     def connect_to_sites
@@ -63,8 +59,11 @@ module RSMP
           timestamp: @clock.now
       build_outbound_proxies
       @ready_condition.signal
-      @proxies.each(&:start)
-      @proxies.each(&:wait)
+      barrier = Async::Barrier.new(parent: @task)
+      @proxies.each { |proxy| proxy.start(parent: barrier) }
+      barrier.wait
+    ensure
+      barrier.cancel if barrier && !barrier.empty?
     end
 
     def build_outbound_proxies
@@ -93,7 +92,7 @@ module RSMP
     def stop
       log "Stopping supervisor #{@supervisor_settings['site_id']}", level: :info
 
-      @accept_task&.stop
+      @accept_task&.cancel if @accept_task&.running?
       @accept_task = nil
 
       @endpoint = nil

data/lib/rsmp/node/task.rb

@@ -1,95 +1,101 @@
 module RSMP
-  class Restart < StandardError
-  end
-
-  # Task helpers for starting and managing an Async task lifecycle.
+  # Explicit ownership for a long-running Async task tree.
   module Task
+    class ConditionWaitTimeout < Async::TimeoutError; end
+
     attr_reader :task
 
     def initialize_task
       @task = nil
+      @termination_completion = Completion.new
     end
 
-    # start our async tasks and return immediately
-    # run() will be called inside the task to perform actual long-running work
-    def start
-      return if @task
-
-      # Use current task context if available, otherwise create new reactor
-      if Async::Task.current?
-        Async::Task.current.async do |task|
-          task.annotate "#{self.class.name} main task"
-          @task = task
-          run
-          stop_subtasks
-          @task = nil
-        end
-      else
-        Async do |task|
-          task.annotate "#{self.class.name} main task"
-          @task = task
-          run
-          stop_subtasks
-          @task = nil
-        end
+    # Start under an explicit Async parent. A current task is accepted for
+    # convenience, but this library never creates a hidden root reactor.
+    def start(parent: Async::Task.current)
+      return @task if @task&.running?
+
+      valid_parent = parent.respond_to?(:async) && (!parent.respond_to?(:running?) || parent.running?)
+      raise ArgumentError, 'an active Async parent task is required' unless valid_parent
+
+      child = parent.async do |task|
+        task.annotate "#{self.class.name} main task"
+        @task = task
+        run
+      ensure
+        stop_subtasks
       end
-      self
+      @task = child
     end
 
-    # initiate restart by raising a Restart exception
     def restart
-      raise Restart, "restart initiated by #{self.class.name}:#{object_id}"
+      termination_completion.succeed(Termination.new(reason: :restart, source: self))
+    end
+
+    def wait_for_termination
+      termination_completion.wait
     end
 
-    # get the status of our task, or nil of no task
     def task_status
       @task&.status
     end
 
-    # perform any long-running work
-    # the method will be called from an async task, and should not return
-    # if subtasks are needed, the method should call wait() on each of them
-    # once running, ready() must be called
     def run
       start_subtasks
     end
 
-    # wait for our task to complete
+    # Async::Task#wait raises unexpected child failures and returns nil for
+    # cancellation, matching Async's native task contract.
     def wait
       @task&.wait
     end
 
-    # stop our task
     def stop
-      stop_subtasks
-      stop_task if @task
+      stop_task
     end
 
     def stop_subtasks; end
 
-    # stop our task and any subtask
     def stop_task
-      @task.stop
-      @task = nil
+      task = @task
+      return unless task&.running?
+
+      task.cancel
+      task.wait unless task.current?
     end
 
-    # wait for an async condition to signal, then yield to block
-    # if block returns true we're done. otherwise, wait again
+    # Wait for an edge-triggered condition and return an expected timeout as a
+    # Result. Async cancellation is not rescued and therefore propagates.
     def wait_for_condition(condition, timeout:, task: Async::Task.current, &block)
-      raise "Can't wait without a task" unless task
+      raise ArgumentError, 'an active Async task is required' unless task&.running?
 
-      task.with_timeout(timeout) do
-        while task.running?
-          value = condition.wait
-          return value unless block
+      value = task.with_timeout(timeout, ConditionWaitTimeout) do
+        loop do
+          signalled = condition.wait
+          break signalled unless block
 
-          result = yield value
-          return result if result
+          matched = yield(signalled)
+          break matched if matched
         end
-        raise "Can't wait for condition because task #{task.object_id} #{task.annotation} is not running"
       end
-    rescue Async::TimeoutError
-      raise RSMP::TimeoutError
+      Result.success(value)
+    rescue ConditionWaitTimeout => e
+      Result.failure(
+        :timeout,
+        message: "Condition was not met within #{timeout}s",
+        source: :timeout,
+        cause: e
+      )
+    end
+
+    def wait_for_condition!(...)
+      wait_for_condition(...).value!
+    end
+
+    private
+
+    def termination_completion
+      @termination_completion ||= Completion.new
     end
   end
 end