rsmp 0.48.4 → 0.51.1

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

data/lib/rsmp/proxy/modules/acknowledgements.rb

@@ -5,16 +5,16 @@ module RSMP
       # Manages sending/receiving acks and nacks, and tracking acknowledged messages
       module Acknowledgements
         def acknowledge(original)
-          raise InvalidArgument unless original
+          raise ArgumentError, 'original message is required' unless original
 
           ack = MessageAck.build_from(original)
           ack.original = original.clone
-          send_message ack, "for #{ack.original.type} #{original.m_id_short}"
+          send_generated_message ack, "for #{ack.original.type} #{original.m_id_short}"
           check_ingoing_acknowledged original
         end
 
         def dont_acknowledge(original, prefix = nil, reason = nil, force: true)
-          raise InvalidArgument unless original
+          raise ArgumentError, 'original message is required' unless original
 
           str = [prefix, reason].join(' ')
           log str, message: original, level: :warning if reason
@@ -23,7 +23,7 @@ module RSMP
                                         'rea' => reason || 'Unknown reason'
                                       })
           message.original = original.clone
-          send_message message, "for #{original.type} #{original.m_id_short}", force: force
+          send_generated_message message, "for #{original.type} #{original.m_id_short}", force: force
         end
 
         def expect_acknowledgement(message)
@@ -45,12 +45,25 @@ module RSMP
 
             str = "No acknowledgements for #{message.type} #{message.m_id_short} within #{timeout} seconds"
             log str, level: :error
-            begin
-              close
-            ensure
-              distribute_error MissingAcknowledgment.new(str)
-            end
+            failure = Failure.new(
+              code: :missing_acknowledgement,
+              message: str,
+              source: :peer,
+              context: { message: message, reason: :missing_acknowledgement, session_id: session_id }
+            )
+            distribute_event(
+              Event.new(
+                type: :missing_acknowledgement,
+                source: self,
+                session_id: session_id,
+                message: message,
+                failure: failure
+              )
+            )
+            return Result.failure(failure: failure)
           end
+
+          Result.success
         end
 
         def find_original_for_message(message)

data/lib/rsmp/proxy/modules/lifecycle.rb

@@ -0,0 +1,134 @@
+module RSMP
+  class Proxy
+    module Modules
+      # Owns one connection session and translates expected termination into
+      # lifecycle events without swallowing unexpected task exceptions.
+      module Lifecycle
+        def disconnect
+          close(reason: :local_stop)
+          Result.success(self)
+        end
+
+        def disconnect!
+          disconnect.value!
+        end
+
+        def connect!
+          connect.value!
+        end
+
+        def wait_for_reader
+          wait_for_session
+        end
+
+        def begin_session
+          clear
+          @session_id += 1
+          @session_closed = false
+          @session_id
+        end
+
+        def close(reason: :peer_closed, failure: nil, session_id: @session_id)
+          return if session_id != @session_id || @session_closed
+
+          @session_closed = true
+          log 'Closing connection', level: :warning
+          close_stream
+          close_socket
+          stop_reader
+          self.state = :disconnected
+          publish_connection_end(reason, failure, session_id)
+          stop_timer
+        end
+
+        def stop_subtasks
+          stop_timer
+          stop_reader
+          clear
+          super
+        end
+
+        def stop_timer
+          current = Async::Task.current?
+          @timer&.cancel unless @timer.equal?(current)
+        ensure
+          @timer = nil
+        end
+
+        def stop_reader
+          current = Async::Task.current?
+          @reader&.cancel unless @reader.equal?(current)
+        ensure
+          @reader = nil
+        end
+
+        def close_stream
+          @stream&.close
+        ensure
+          @stream = nil
+        end
+
+        def close_socket
+          @socket&.close
+        ensure
+          @socket = nil
+        end
+
+        def stop_task
+          close(reason: :local_stop)
+          super
+        end
+
+        def distribute_event(event)
+          super
+          @node&.publish_event(event)
+          event
+        end
+
+        def connection_end_failure(reason)
+          local = reason == :local_stop
+          Failure.new(
+            code: local ? :cancelled : :disconnected,
+            message: "Connection ended (#{reason})",
+            source: local ? :local : :connection,
+            context: { reason: reason, session_id: @session_id }
+          )
+        end
+
+        def close_from_result(result)
+          return close(reason: :peer_closed) if result.nil? || result.success?
+
+          reason = result.failure.context[:reason] || :transport_failure
+          close(reason: reason, failure: result.failure)
+        end
+
+        def publish_connection_attempt_failure(failure)
+          log failure.message, level: :warning
+          distribute_event(
+            Event.new(
+              type: :connection_attempt_failed,
+              source: self,
+              session_id: @session_id,
+              failure: failure
+            )
+          )
+        end
+
+        private
+
+        def publish_connection_end(reason, failure, session_id)
+          failure ||= connection_end_failure(reason)
+          distribute_event(
+            Event.new(
+              type: :connection_ended,
+              source: self,
+              session_id: session_id,
+              failure: failure,
+              context: { reason: reason }
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rsmp/proxy/modules/receive.rb

@@ -1,12 +1,11 @@
 module RSMP
   class Proxy
     module Modules
-      # Message processing functionality
-      # Handles receiving and processing incoming messages
+      # Message processing functionality. Peer-controlled invalid input is
+      # represented by Result::Failure; unexpected implementation errors escape.
       module Receive
         def should_validate_ingoing_message?(message)
           return false if message.is_a?(Version) && !@version_determined
-
           return true unless @site_settings
 
           skip = @site_settings['skip_validation']
@@ -24,93 +23,137 @@ module RSMP
           expect_version_message(message) unless @version_determined
         end
 
-        def handle_invalid_packet(json, error)
-          str = "Received invalid package, must be valid JSON but got #{json.size} bytes: #{error.message}"
-          distribute_error error.exception(str)
-          log str, level: :warning
-          nil
+        def process_packet(json)
+          attributes = Message.parse_attributes(json)
+          message = Message.build(attributes, json)
+          process_incoming_message(message)
+        rescue InvalidPacket => e
+          reject_invalid_packet(json, e)
+        rescue MalformedMessage => e
+          reject_malformed_packet(json, attributes, e)
+        rescue PeerMessageError => e
+          reject_processed_message(message, e)
+        rescue HandshakeError, FatalError => e
+          reject_fatal_message(message, e)
+        ensure
+          @node&.clear_deferred
         end
 
-        def handle_malformed_message(attributes, error)
-          str = "Received malformed message, #{error.message}"
-          distribute_error error.exception(str)
-          log str, message: Malformed.new(attributes), level: :warning
-          nil
+        def process_incoming_message(message)
+          validate = should_validate_ingoing_message?(message)
+          if validate
+            validation = message.validate(schemas)
+            return reject_invalid_message(message, validation) if validation.invalid?
+          end
+
+          verify_sequence(message)
+          message.decode_for(schemas) if validate
+          with_deferred_distribution do
+            distribute(message)
+            process_message(message)
+          end
+          process_deferred
+          Result.success(message)
         end
 
-        def handle_schema_error(message, error)
-          failed_schemas = error.respond_to?(:schemas) && error.schemas ? error.schemas : schemas
-          schemas_string = failed_schemas.map { |schema| "#{schema.first}: #{schema.last}" }.join(', ')
-          reason = "schema errors (#{schemas_string}): #{error.message}"
-          str = "Received invalid #{message.type}"
-          distribute_error error.exception(str), message: message
-          dont_acknowledge message, str, reason
-          message
+        def reject_invalid_packet(json, error)
+          reject_packet(
+            :invalid_packet,
+            "Received invalid packet, expected JSON but got #{json.size} bytes: #{error.message}",
+            raw: json
+          )
         end
 
-        def handle_invalid_message(message, error)
-          reason = error.message.to_s
-          str = "Received invalid #{message.type},"
-          distribute_error error.exception("#{str} #{message.json}"), message: message
-          dont_acknowledge message, str, reason
-          message
+        def reject_malformed_packet(json, attributes, error)
+          reject_packet(
+            :malformed_message,
+            "Received malformed message: #{error.message}",
+            raw: json,
+            message: Malformed.new(attributes || {})
+          )
         end
 
-        def handle_fatal_error(message, error)
-          reason = error.message
-          str = "Rejected #{message.type},"
-          distribute_error error.exception(str), message: message
-          dont_acknowledge message, str, reason
-          close
-          message
+        def reject_invalid_message(message, validation)
+          schemas_string = schemas.map { |schema| "#{schema.first}: #{schema.last}" }.join(', ')
+          reason = "schema errors (#{schemas_string}): #{validation.message}"
+          text = "Received invalid #{message.type}"
+          failure = peer_failure(
+            :invalid_peer_message,
+            "#{text}: #{validation.message}",
+            message: message,
+            validation: validation
+          )
+          publish_peer_failure(failure, message: message)
+          log(text, message: message, level: :warning)
+          dont_acknowledge(message, text, reason)
+          Result.failure(failure: failure)
         end
 
-        def process_packet(json)
-          attributes = Message.parse_attributes json
-          message = Message.build attributes, json
-          validate = should_validate_ingoing_message?(message)
-          message.validate(schemas) if validate
-          verify_sequence message
-          message.decode_for(schemas) if validate
-          with_deferred_distribution do
-            distribute message
-            process_message message
-          end
-          process_deferred
-          message
-        rescue InvalidPacket => e
-          handle_invalid_packet(json, e)
-        rescue MalformedMessage => e
-          handle_malformed_message(attributes, e)
-        rescue SchemaError, RSMP::Schema::Error => e
-          handle_schema_error(message, e)
-        rescue InvalidMessage, MessageRejected => e
-          handle_invalid_message(message, e)
-        rescue FatalError => e
-          handle_fatal_error(message, e)
-        ensure
-          @node.clear_deferred
+        def reject_packet(code, text, raw:, message: nil)
+          failure = peer_failure(code, text, message: message, raw: raw)
+          publish_peer_failure(failure, message: message)
+          log(text, message: message, level: :warning)
+          Result.failure(failure: failure)
+        end
+
+        def reject_processed_message(message, error)
+          code = error.is_a?(MessageRejected) ? :message_rejected : :invalid_peer_message
+          text = "Received invalid #{message.type}: #{error.message}"
+          failure = peer_failure(code, text, message: message)
+          publish_peer_failure(failure, message: message)
+          dont_acknowledge(message, "Received invalid #{message.type}", error.message.to_s)
+          Result.failure(failure: failure)
+        end
+
+        def reject_fatal_message(message, error)
+          text = "Rejected #{message&.type || 'message'}: #{error.message}"
+          failure = peer_failure(:protocol_failure, text, message: message)
+          publish_peer_failure(failure, message: message)
+          dont_acknowledge(message, "Rejected #{message.type}", error.message.to_s) if message
+          close(reason: :protocol_failure, failure: failure)
+          Result.failure(failure: failure)
+        end
+
+        def peer_failure(code, text, message: nil, **context)
+          Failure.new(
+            code: code,
+            message: text,
+            source: :peer,
+            context: context.merge(message: message).compact
+          )
+        end
+
+        def publish_peer_failure(failure, message:)
+          distribute_event(
+            Event.new(
+              type: :invalid_message,
+              source: self,
+              session_id: session_id,
+              message: message,
+              failure: failure
+            )
+          )
         end
 
         def process_message(message)
           case message
           when MessageAck
-            process_ack message
+            process_ack(message)
           when MessageNotAck
-            process_not_ack message
+            process_not_ack(message)
           when Version
-            process_version message
+            process_version(message)
           when RSMP::Watchdog
-            process_watchdog message
+            process_watchdog(message)
           else
-            dont_acknowledge message, 'Received', "unknown message (#{message.type})"
+            dont_acknowledge(message, 'Received', "unknown message (#{message.type})")
           end
         end
 
         def will_not_handle(message)
-          reason ||= "since we're a #{self.class.name.downcase}"
+          reason = "since we're a #{self.class.name.downcase}"
           log "Ignoring #{message.type}, #{reason}", message: message, level: :warning
-          dont_acknowledge message, nil, reason
+          dont_acknowledge(message, nil, reason)
         end
 
         def expect_version_message(message)