rsmp 0.48.4 → 0.51.0

data/lib/rsmp/collect/collector.rb

@@ -1,37 +1,25 @@
 module RSMP
-  # Collects messages from a distributor.
-  # Can filter by message type, componet and direction.
-  # Wakes up the once the desired number of messages has been collected.
+  # Collects matching messages and resolves once with an immutable Result.
   class Collector
     include Receiver
-    include Status
     include Reporting
     include Logging
 
-    attr_reader :condition, :messages, :status, :error, :task, :m_id, :initiator
+    attr_reader :messages, :m_id, :initiator
 
     def initialize(distributor, options = {})
       initialize_receiver distributor, filter: options[:filter]
       @options = {
         cancel: {
-          schema_error: true,
-          disconnect: false
+          invalid_message: true,
+          disconnect: true
         }
-      }.deep_merge options
+      }.deep_merge(options)
       @timeout = options[:timeout]
       @num = options[:num]
       @initiator = options[:initiator]
       @m_id = options[:m_id] || @initiator&.attributes&.dig('mId')
-      @condition = Async::Notification.new
-      make_title options[:title]
-
-      if task
-        @task = task
-      elsif distributor.respond_to? 'task'
-        # if distributor is a Proxy, or some other object that implements task(),
-        # then try to get the task that way
-        @task = distributor.task
-      end
+      make_title(options[:title])
       reset
     end
 
@@ -45,207 +33,202 @@ module RSMP
                end
     end
 
-    def use_task(task)
-      @task = task
-    end
-
     def reset
       @messages = []
-      @error = nil
-      @status = :ready
+      @completion = Completion.new
+      @active = false
     end
 
-    # Inspect formatter that shows the message we have collected
-    def inspect
-      "#<#{self.class.name}:#{object_id}, message:#{@messages}>"
+    def active?
+      @active
     end
 
-    # if an errors caused collection to abort, then raise it
-    # return self, so this can be tucked on to calls that return a collector
-    def ok!
-      raise @error if @error
+    alias collecting? active?
 
-      self
+    def inspect
+      "#<#{self.class.name}:#{object_id}, message:#{@messages}>"
     end
 
-    # Collect message
-    # Will return once all messages have been collected, or timeout is reached
     def collect(&)
       start(&)
       wait
-      @status
     ensure
-      @distributor&.remove_receiver self
+      stop
     end
 
-    # Collect message
-    # Returns the collected messages, or raise an exception in case of a time out.
     def collect!(&)
-      collect(&)
-      ok!
-      @messages
+      collect(&).value!.messages
     end
 
-    # If collection is not active, return status immeditatly. Otherwise wait until
-    # the desired messages have been collected, or timeout is reached.
+    # The configured timeout terminates this collection. Completion retains the
+    # result, so every current or future waiter observes the same value.
     def wait
-      if collecting?
-        if @timeout
-          @task.with_timeout(@timeout) { @condition.wait }
-        else
-          @condition.wait
-        end
+      raise 'collector has not been started' unless active? || @completion.resolved?
+
+      observed = @completion.wait(timeout: @timeout)
+      if timeout_result?(observed)
+        finish_failure(observed.failure.with(message: describe_progress))
+        observed = @completion.wait
       end
-      @status
-    rescue Async::TimeoutError
-      @error = RSMP::TimeoutError.new describe_progress
-      @status = :timeout
+      observed
     end
 
-    # If collection is not active, raise an error. Otherwise wait until
-    # the desired messages have been collected.
-    # If timeout is reached or collection was cancelled with an error, an exception is raised.
     def wait!
-      wait
-      raise @error if timeout? || (cancelled? && @error)
-
-      @messages
+      wait.value!.messages
     end
 
-    # Start collection and return immediately
-    # You can later use wait() to wait for completion
     def start(&block)
-      raise "Can't start collectimng unless ready (currently #{@status})" unless ready?
+      raise 'collector is already active' if active?
 
       @block = block
-      raise ArgumentError, 'Num, timeout or block must be provided' unless @num || @timeout || @block
+      raise ArgumentError, 'num, timeout or block must be provided' unless @num || @timeout || @block
 
       reset
-      @status = :collecting
+      @active = true
       log_start
-      @distributor&.add_receiver self
+      @distributor.add_receiver(self)
+      self
     end
 
-    # Check if we receive a NotAck related to initiating request, identified by @m_id.
-    def reject_not_ack(message)
-      return unless @m_id
+    def stop
+      return self unless @active
 
-      return unless message.is_a?(MessageNotAck)
-      return unless message.attribute('oMId') == @m_id
+      @active = false
+      @distributor.remove_receiver(self)
+      self
+    end
 
-      m_id_short = RSMP::Message.shorten_m_id @m_id, 8
-      cancel RSMP::MessageRejected.new("#{@title} #{m_id_short} was rejected with '#{message.attribute('rea')}'")
-      @distributor.log "#{identifier}: cancelled due to a NotAck", level: :debug
+    # Check for a NotAck related to the initiating request.
+    def reject_not_ack?(message)
+      return false unless @m_id
+      return false unless message.is_a?(MessageNotAck)
+      return false unless message.attribute('oMId') == @m_id
+
+      m_id_short = RSMP::Message.shorten_m_id(@m_id, 8)
+      finish_failure(
+        Failure.new(
+          code: :message_rejected,
+          message: "#{@title} #{m_id_short} was rejected with '#{message.attribute('rea')}'",
+          source: :peer,
+          context: { message: message, original_message_id: @m_id }
+        )
+      )
+      @distributor.log "#{identifier}: rejected by a NotAck", level: :debug
       true
     end
 
-    # Handle message and return true if we're done collecting
     def receive(message)
-      raise ArgumentError unless message
-      unless ready? || collecting?
-        raise "can't process message when status is :#{@status}, title: #{@title}, desc: #{describe}"
-      end
+      return unless active?
 
-      if perform_match message
-        if done?
-          complete
-        else
-          incomplete
-        end
+      if perform_match?(message)
+        done? ? complete : incomplete
       end
-      @status
+      active?
     end
 
     def describe; end
 
-    # Match message against our collection criteria
-    def perform_match(message)
-      return false if reject_not_ack(message)
+    def perform_match?(message)
+      return false if reject_not_ack?(message)
       return false unless acceptable?(message)
 
       if @block
-        status = [@block.call(message)].flatten
-        return unless collecting?
+        status = Array(@block.call(message))
+        return false unless active?
 
-        keep message if status.include?(:keep)
+        keep(message) if status.include?(:keep)
       else
-        keep message
+        keep(message)
       end
+      true
     end
 
-    # Have we collected the required number of messages?
     def done?
       @num && @messages.size >= @num
     end
 
-    # Called when we're done collecting. Remove ourself as a receiver,
-    # se we don't receive message notifications anymore
     def complete
-      @status = :ok
-      do_stop
+      finish_success(build_collection)
       log_complete
     end
 
-    # called when we received a message, but are not done yet
     def incomplete
       log_incomplete
     end
 
-    # Remove ourself as a receiver, so we don't receive message notifications anymore,
-    # and wake up the async condition
-    def do_stop
-      @distributor.remove_receiver self
-      @condition.signal
-    end
+    def receive_event(event)
+      return unless active?
 
-    # Handle upstream error
-    def receive_error(error, options = {})
-      case error
-      when RSMP::SchemaError
-        receive_schema_error error, options
-      when RSMP::DisconnectError
-        receive_disconnect error, options
+      case event.type
+      when :invalid_message
+        receive_invalid_message(event)
+      when :connection_ended
+        receive_connection_ended(event)
       end
     end
 
-    # Cancel if we received e schema error for a message type we're collecting
-    def receive_schema_error(error, options)
-      return unless @options.dig(:cancel, :schema_error)
+    def receive_invalid_message(event)
+      return unless @options.dig(:cancel, :invalid_message)
+      return unless event.message
+      return unless acceptable?(event.message)
 
-      message = options[:message]
-      return unless message
+      finish_failure(event.failure)
+    end
 
-      klass = message.class.name.split('::').last
-      return unless @filter&.type.nil? || [@filter&.type].flatten.include?(klass)
+    def receive_connection_ended(event)
+      return unless @options.dig(:cancel, :disconnect)
 
-      @distributor.log "#{identifier}: cancelled due to schema error in #{klass} #{message.m_id_short}", level: :debug
-      cancel error
+      finish_failure(event.failure)
     end
 
-    # Cancel if we received e notifiction about a disconnect
-    def receive_disconnect(error, _options)
-      return unless @options.dig(:cancel, :disconnect)
+    # Explicit cancellation is an expected caller-controlled result.
+    def cancel(reason = 'Collection cancelled')
+      finish_failure(
+        Failure.new(code: :cancelled, message: reason.to_s, source: :local)
+      )
+    end
+
+    def fail(failure)
+      raise ArgumentError, 'failure must be an RSMP::Failure' unless failure.is_a?(Failure)
 
-      @distributor.log "#{identifier}: cancelled due to a connection error: #{error}", level: :debug
-      cancel error
+      finish_failure(failure)
     end
 
-    # Abort collection
-    def cancel(error = nil)
-      @error = error
-      @status = :cancelled
-      do_stop
+    # Unexpected receiver/callback failures reject the completion so waiters see
+    # the original exception and stack trace.
+    def crash(error)
+      return unless active?
+
+      @completion.crash(error)
+      stop
     end
 
-    # Store a message in the result array
     def keep(message)
       @messages << message
     end
 
-    # Check a message against our match criteria
-    # Return true if there's a match, false if not
     def acceptable?(message)
       @filter.nil? || @filter.accept?(message)
     end
+
+    def build_collection
+      Collection.new(messages: @messages)
+    end
+
+    private
+
+    def timeout_result?(result)
+      result.failure? && result.failure.code == :timeout && !@completion.resolved?
+    end
+
+    def finish_success(collection)
+      @completion.succeed(collection)
+      stop
+    end
+
+    def finish_failure(failure)
+      @completion.fail(failure)
+      stop
+    end
   end
 end

data/lib/rsmp/collect/distributor.rb

@@ -56,11 +56,24 @@ module RSMP
     end
 
     def distribute_immediately(message)
-      @receivers.each { |receiver| receiver.receive message }
+      @receivers.dup.each { |receiver| deliver(receiver, :receive, message) }
     end
 
-    def distribute_error(error, options = {})
-      @receivers.each { |receiver| receiver.receive_error error, options }
+    def distribute_event(event)
+      raise ArgumentError, 'event must be an RSMP::Event' unless event.is_a?(RSMP::Event)
+
+      @receivers.dup.each { |receiver| deliver(receiver, :receive_event, event) }
+    end
+
+    private
+
+    def deliver(receiver, method, value)
+      receiver.public_send(method, value)
+    rescue StandardError => e
+      remove_receiver(receiver)
+      raise unless receiver.respond_to?(:crash)
+
+      receiver.crash(e)
     end
   end
 end

data/lib/rsmp/collect/queue.rb

@@ -7,10 +7,9 @@ module RSMP
 
     attr_reader :messages
 
-    def initialize(distributor, task:, filter: nil)
+    def initialize(distributor, filter: nil)
       initialize_receiver distributor, filter: filter
       @condition = Async::Notification.new
-      @task = task
       clear
     end
 
@@ -21,14 +20,23 @@ module RSMP
     def wait_for_message(timeout: nil)
       if @messages.empty?
         if timeout
-          @task.with_timeout(timeout) { @condition.wait }
+          Async::Task.current.with_timeout(timeout) { @condition.wait }
         else
           @condition.wait
         end
       end
-      @messages.shift
-    rescue Async::TimeoutError
-      raise RSMP::TimeoutError
+      Result.success(@messages.shift)
+    rescue Async::TimeoutError => e
+      Result.failure(
+        :timeout,
+        message: "No message was received within #{timeout}s",
+        source: :timeout,
+        cause: e
+      )
+    end
+
+    def wait_for_message!(...)
+      wait_for_message(...).value!
     end
 
     def handle_message(message)

data/lib/rsmp/collect/receiver.rb

@@ -23,7 +23,7 @@ module RSMP
       handle_message(message) if accept_message?(message)
     end
 
-    def receive_error(error, options = {}); end
+    def receive_event(event); end
 
     def accept_message?(message)
       @filter.nil? || @filter.accept?(message)

data/lib/rsmp/collect/state_collector.rb

@@ -106,9 +106,9 @@ module RSMP
       end
     end
 
-    def perform_match(message)
+    def perform_match?(message)
       return false if super == false
-      return unless collecting?
+      return false unless collecting?
 
       @matchers.each do |matcher|
         break unless collecting?
@@ -120,6 +120,7 @@ module RSMP
           handle_match_result(matched, matcher, message, item)
         end
       end
+      true
     end
 
     # don't collect anything. Matcher will collect them instead
@@ -248,5 +249,13 @@ module RSMP
     def log_complete
       @distributor.log "#{identifier}: Completed with #{matcher_got_hash}", level: :collect
     end
+
+    def build_collection
+      Collection.new(
+        messages: messages,
+        reached: reached,
+        matcher_status: matcher_status
+      )
+    end
   end
 end

data/lib/rsmp/collection.rb

@@ -0,0 +1,12 @@
+module RSMP
+  # Immutable snapshot returned by a completed collector.
+  Collection = Data.define(:messages, :reached, :matcher_status) do
+    def initialize(messages:, reached: [], matcher_status: {})
+      super(
+        messages: messages.dup.freeze,
+        reached: reached.dup.freeze,
+        matcher_status: matcher_status.dup.freeze
+      )
+    end
+  end
+end

data/lib/rsmp/completion.rb

@@ -0,0 +1,49 @@
+module RSMP
+  # A resolve-once Async completion. Expected failures resolve to Result::Failure;
+  # unexpected exceptions reject the promise and retain their original backtrace.
+  class Completion
+    def initialize
+      @promise = Async::Promise.new
+    end
+
+    def resolved?
+      @promise.resolved?
+    end
+
+    def succeed(value = nil)
+      @promise.resolve(Result.success(value))
+    end
+
+    def fail(failure = nil, **)
+      result = if failure.is_a?(RSMP::Failure)
+                 Result.failure(failure: failure)
+               else
+                 Result.failure(failure, **)
+               end
+      @promise.resolve(result)
+    end
+
+    def crash(exception)
+      @promise.reject(exception)
+    end
+
+    # A wait timeout bounds this caller's wait; it does not resolve or cancel the
+    # underlying operation.
+    def wait(timeout: nil)
+      @promise.wait(timeout: timeout)
+    rescue Async::TimeoutError => e
+      return @promise.wait if @promise.resolved?
+
+      Result.failure(
+        :timeout,
+        message: "Operation did not complete within #{timeout}s",
+        source: :timeout,
+        cause: e
+      )
+    end
+
+    def wait!(timeout: nil)
+      wait(timeout: timeout).value!
+    end
+  end
+end

data/lib/rsmp/component/component_base.rb

@@ -70,7 +70,7 @@ module RSMP
 
     def set_aggregated_status(status, options = {})
       status = [status] if status.is_a? Symbol
-      raise InvalidArgument unless status.is_a? Array
+      raise ArgumentError, 'aggregated status must be an Array' unless status.is_a? Array
 
       input = status & AGGREGATED_STATUS_KEYS
       return unless input != @aggregated_status
@@ -82,8 +82,8 @@ module RSMP
     end
 
     def aggregated_status_bools=(status)
-      raise InvalidArgument unless status.is_a? Array
-      raise InvalidArgument unless status.size == 8
+      raise ArgumentError, 'aggregated status must be an Array' unless status.is_a? Array
+      raise ArgumentError, 'aggregated status must contain 8 elements' unless status.size == 8
 
       return unless status != @aggregated_status_bools
 

data/lib/rsmp/convert/export/json_schema/index.rb

@@ -6,8 +6,10 @@ module RSMP
         def self.output_sxl_index(out, sxl)
           out['sxl_index.json'] = output_json({
                                                 'meta' => sxl[:meta],
-                                                'statuses' => index_items(sxl[:statuses], legacy_types: legacy_types?(sxl)),
-                                                'commands' => index_items(sxl[:commands], legacy_types: legacy_types?(sxl)),
+                                                'statuses' => index_items(sxl[:statuses],
+                                                                          legacy_types: legacy_types?(sxl)),
+                                                'commands' => index_items(sxl[:commands],
+                                                                          legacy_types: legacy_types?(sxl)),
                                                 'alarms' => index_items(sxl[:alarms], legacy_types: legacy_types?(sxl))
                                               })
         end
@@ -69,7 +71,10 @@ module RSMP
 
         def self.argument_array_descriptor(argument, legacy_types:)
           descriptor = { 'type' => argument['type'] }
-          descriptor['items'] = typed_arguments(argument['items'], legacy_types: legacy_types) if argument['items'].is_a?(Hash)
+          if argument['items'].is_a?(Hash)
+            descriptor['items'] =
+              typed_arguments(argument['items'], legacy_types: legacy_types)
+          end
           descriptor
         end
 

data/lib/rsmp/convert/import/yaml.rb

@@ -20,7 +20,7 @@ module RSMP
         def self.convert(yaml)
           sxl = build_empty_sxl
           sxl[:meta] = yaml['meta']
-          merge_objects(sxl, yaml['objects'])
+          merge_components(sxl, component_definitions(yaml))
           sxl
         end
 
@@ -28,16 +28,20 @@ module RSMP
           { meta: {}, alarms: {}, statuses: {}, commands: {} }
         end
 
-        def self.merge_objects(sxl, objects)
-          objects.each_pair do |_type, object|
-            merge_object_items(sxl, object)
+        def self.component_definitions(yaml)
+          yaml.fetch('components') { yaml.fetch('objects') }
+        end
+
+        def self.merge_components(sxl, components)
+          components.each_pair do |_type, component|
+            merge_component_items(sxl, component)
           end
         end
 
-        def self.merge_object_items(sxl, object)
-          object['alarms']&.each { |id, item| sxl[:alarms][id] = item }
-          object['statuses']&.each { |id, item| sxl[:statuses][id] = item }
-          object['commands']&.each { |id, item| sxl[:commands][id] = item }
+        def self.merge_component_items(sxl, component)
+          component['alarms']&.each { |id, item| sxl[:alarms][id] = item }
+          component['statuses']&.each { |id, item| sxl[:statuses][id] = item }
+          component['commands']&.each { |id, item| sxl[:commands][id] = item }
         end
       end
     end

data/lib/rsmp/delivery.rb

@@ -0,0 +1,18 @@
+module RSMP
+  # The disposition of a successfully submitted outbound message.
+  Delivery = Data.define(:message, :state) do
+    def initialize(message:, state:)
+      raise ArgumentError, 'delivery state must be :sent or :buffered' unless %i[sent buffered].include?(state)
+
+      super
+    end
+
+    def sent?
+      state == :sent
+    end
+
+    def buffered?
+      state == :buffered
+    end
+  end
+end

data/lib/rsmp/event.rb

@@ -0,0 +1,19 @@
+module RSMP
+  # A typed occurrence produced by a long-running node or connection.
+  Event = Data.define(:type, :source, :session_id, :message, :failure, :context, :at) do
+    def initialize(type:, source:, session_id: nil, message: nil, failure: nil, context: {}, at: Time.now)
+      raise ArgumentError, 'event type must be a Symbol' unless type.is_a?(Symbol)
+      raise ArgumentError, 'event context must be a Hash' unless context.is_a?(Hash)
+
+      super(
+        type: type,
+        source: source,
+        session_id: session_id,
+        message: message,
+        failure: failure,
+        context: context.dup.freeze,
+        at: at
+      )
+    end
+  end
+end