rsmp 0.29.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 128be65ff4ece071590a4ed3dc113cbfdf1a697115033a02a113d894935a6cad
-  data.tar.gz: 4f025722621f8edb751dcbf6f38acbb146c26fddac53a29f14673e8751609ddb
+  metadata.gz: fd4daeeb9fb712ab275d4b0711a6ea69e766124a2fcd55ea955eeb1c46f05ed3
+  data.tar.gz: a47c38c49b46fb2ad412ced388f6e654653292dd439ea31d2bbaf33988f024f0
 SHA512:
-  metadata.gz: 89086c19b7ec7b64f234ec19ec70688ae08e62524ec307b66ccb27e159c3d5ea9eee5bcb360de41d457ad3db3174d9b31d159802a92759596cf10dc24525dcc6
-  data.tar.gz: 6ee2489e60c466c9de16d4698b0cfef4e8bb065e9f358b9e0f55133759eab6b5adab248f0ab29ca021bae3cf9138b32c54d955ef2fbf629e2815a6a7f57947f1
+  metadata.gz: ec4a4057b53a27d12e1c81af4623b03bcd7cf93b39bad72f1d228c1a0dfd74495541abae496a3fa783c159a16df2e161eb0f5fbaa13d96daa8d8c99a847a0f9f
+  data.tar.gz: 704c11a6d854a0fb48f9cb6d84514ac40791bb85fe56186b9ff217e876458be6a214fbb69b8c3aaf09db35bd334345f7ca6ee31da8f9fbf717a3ae790e77252a

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rsmp (0.29.0)
+    rsmp (0.31.0)
       async (~> 2.12.0)
       async-io (~> 1.43.0)
       colorize (~> 1.1)
@@ -16,16 +16,16 @@ GEM
       cucumber (>= 8.0, < 10.0)
       rspec-expectations (~> 3.4)
       thor (~> 1.0)
-    async (2.12.0)
+    async (2.12.1)
       console (~> 1.25, >= 1.25.2)
       fiber-annotation
-      io-event (~> 1.6)
+      io-event (~> 1.6, >= 1.6.5)
     async-io (1.43.2)
       async
     bigdecimal (3.1.8)
     builder (3.3.0)
     colorize (1.1.0)
-    console (1.25.2)
+    console (1.27.0)
       fiber-annotation
       fiber-local (~> 1.1)
       json
@@ -64,9 +64,9 @@ GEM
     fiber-annotation (0.2.0)
     fiber-local (1.1.0)
       fiber-storage
-    fiber-storage (0.1.2)
+    fiber-storage (1.0.0)
     hana (1.3.7)
-    io-event (1.6.4)
+    io-event (1.6.5)
     json (2.7.2)
     json_schemer (2.3.0)
       bigdecimal

data/documentation/collecting_message.md

@@ -3,30 +3,45 @@ You often need to collect messages or responses. The collector classes are used
 
 A collector can collect ingoing and/or outgoing messages.
 
-An object that includes the Notifier module (or implements the same functionality) must be provided when you construct a Collected. The collector will attach itself to this notifier when it starts collecting, to receive messages. The SiteProxy and SupervisorProxy classes both include the Notifier module, and can therefore be used as message sources.
+An object that includes the Distributor module (or implements the same functionality) must be provided when you construct a Collected. The collector will attach itself to this distributor when it starts collecting, to receive messages. The SiteProxy and SupervisorProxy classes both include the Distributor module, and can therefore be used as message sources.
 
 Messages that match the relevant criteria are stored by the collector.
 
-When the collection is done, the collector detaches from the notifier, and returns the status.
+When the collection is done, the collector detaches from the distributor, and returns the status.
 
 
 ## Collector
-Class uses for collecting messages filtered by message type, direction and/or component id. A block can be used for custom filtering.
+Class used for collecting messages filtered by message type, direction and/or component id. A block can be used for custom filtering.
 
 You can choose to collect a specific number of message and/or for a specific duration.
 
 A collector has a status, which is `:ready` initialialy. When you start collecting, it changes to `:collecting`. It will be `:ok` once collection completes successfully, or `:cancel` if it was cancelled to to some error or by a filter block.
 
 ### Initialization
-When you create a collector, you specify the messages types you want to collect.
-You can also specify ingoing and/or outgoing direction and the RSMP component.
+When you create a collector, you provide a Filter to specify the messages types you want to collect. You can also specify ingoing and/or outgoing direction and the RSMP component.
 
 ```ruby
-collector = MessageCollector.new notifier, num: 10, ingoing: true, outgoing: true
+collector = MessageCollector.new(distributor,
+	num: 10,
+	filter: Filter.new(ingoing: true, outgoing: true)
 ```
 
 num: The number of messages to collect. If not provided, a timeout must be set instead.
-timeout: The number of seconds to collect
+filter: filter to identify the types of messages to look for.
+
+### Filter
+The Filter class is used to filter messages according to message type, direction and component.
+
+```ruby
+filter = Filter.new(
+	type: 'Alarm',
+	ingoing: true,
+	outgoing: false,
+	component: 'DL1'
+	)
+```
+
+type: a string, or an array of string, specifiying one or more RSMP message types.
 ingoing: Whether to collect ingoing messages. Defaults to true
 outgoing: Whether to collect outgoing messages. Defaults to true
 component: An RSMP component id.
@@ -48,7 +63,7 @@ result = collector.wait
 ```
 
 ### Custom filtering
-You can use a block to do extra filtering. The block will be callled for each messages that fulfils the  correct message type, direction and component id.
+You can use a block to do extra filtering. The block will be callled for each messages that passes the Filter provided when initializing the collector.
 
 The block must return nil or a list of symbols to indicate whether the message should be kept, and whether collection should be cancelled.
 
@@ -69,7 +84,7 @@ Exceptions in the block will cause the collector to abort. If the collect! or wa
 The method collect!() will raise exceptions in case of errors, and will return the collect message directly.
 
 ```ruby
-message = collector.collect # => collected message.
+message = collector.collect! # => collected message.
 ```
 
 Similar, `wait!()` will raise an exception in case of timeouts or errors:
@@ -181,7 +196,7 @@ result[:collector].messages # => list of collected messages
 
 ### Processing responses
 If you pass a block, the block will be used to construct a collector. The block will be called for each matching  status item received.
-Collection will continue until the block returns :cancel, or it times.
+Collection will continue until the block returns :cancel, or it times out.
 
 ```ruby
 options = {

data/documentation/message_distribution.md

@@ -1,23 +1,23 @@
 # Message distribution
 
-Proxy - - Notifier --> Listeners
+Proxy - - Distributor --> Receivers
 
-A proxy distributes messages to listeners, when they are installed.
+A proxy distributes messages to receivers, when they are installed.
 
-Collectors are special listenerws that waits for specific message, and are used to implement methods for waiting for RMSP responses, statuses, alarms, etc.
+Collectors are special receiverws that waits for specific message, and are used to implement methods for waiting for RMSP responses, statuses, alarms, etc.
 
-Note that Archive is not a listener, and does not receive messages via the Notifier. Instead the Archive gets and stores messages via the log() interface in the Logging module. The reason is that the items that the Archive and the Logger contain other data as well as the message, like error messages, warnings, text descriptions, colors codes, etc. The Distributor and Receiver handles only Message objects.
+Note that Archive is not a receiver, and does not receive messages via the Distributor. Instead the Archive gets and stores messages via the log() interface in the Logging module. The reason is that the items that the Archive and the Logger contain other data as well as the message, like error messages, warnings, text descriptions, colors codes, etc. The Distributor and Receiver handles only Message objects.
 
-## Notifier
+## Distributor
 A module that handles distributing messages to receivers.
 
-## Listener
+## Receiver
 Receives messages as long as it's installed into a distributor.
 
 ## Collector
-A subclass of Receiver that wait for specific messages. Once received
+Includes the Receiver module to wait for specific messages. Once received
 the client receives the collection.
 
 ## Proxy
-A proxy includes the Notifier module and distributes each message to listerens after processing it.
+A proxy includes the Distributor module and distributes each message to receivers after processing it.
 

data/lib/rsmp/collect/ack_collector.rb

@@ -3,14 +3,16 @@ module RSMP
   class AckCollector < Collector
     def initialize proxy, options={}
       raise ArgumentError.new("m_id must be provided") unless options[:m_id]
-      required = { type: 'MessageAck', num: 1, title: 'message acknowledgement' }
-      super proxy, options.merge(required)
+      super proxy, options.merge(
+        filter: RSMP::Filter.new(ingoing: true, outgoing: false, type: 'MessageAck'),
+        num: 1,
+        title: 'message acknowledgement'
+      )
     end
 
     # Check if we the MessageAck related to initiating request, identified by @m_id.
-    def type_match? message
-      return false if super(message) == false
-      return message.attribute('oMId') == @options[:m_id]
+    def acceptable? message
+      super(message) && message.attribute('oMId') == @m_id
     end
   end
 end

data/lib/rsmp/collect/aggregated_status_collector.rb

@@ -2,8 +2,10 @@ module RSMP
   # Class for waiting for an aggregated status response
   class AggregatedStatusCollector < Collector
     def initialize proxy, options={}
-      required = { type: 'AggregatedStatus', title: 'aggregated status' }
-      super proxy, options.merge(required)
+      super proxy, options.merge(
+        filter: RSMP::Filter.new(ingoing: true, outgoing: false, type: 'AggregatedStatus'),
+        title: 'aggregated status'
+      )
     end
   end
 end

data/lib/rsmp/collect/alarm_collector.rb

@@ -2,20 +2,20 @@ module RSMP
   # Class for waiting for specific command responses
   class AlarmCollector < Collector
     def initialize proxy,options={}
-      @query = options[:query] || {}
+      @matcher = options[:matcher] || {}
       super proxy, options.merge(
-        type: 'Alarm',
+        filter: RSMP::Filter.new(ingoing: true, outgoing: false, type: 'Alarm'),
         title:'alarm'
       )
     end
 
     # match alarm attributes
-    def type_match? message
+    def acceptable? message
       return false if super(message) == false
 
       # match fixed attributes
       %w{cId aCId aSp ack aS sS cat pri}.each do |key|
-        want = @query[key]
+        want = @matcher[key]
         got = message.attribute(key)
         case want
         when Regexp
@@ -26,13 +26,13 @@ module RSMP
       end
 
       # match rvs items
-      if @query['rvs']
-        query_rvs = @query['rvs']
+      if @matcher['rvs']
+        matcher_rvs = @matcher['rvs']
         message_rvs = message.attributes['rvs']
         return false unless message_rvs
-        return false unless query_rvs.all? do |query_item|
+        return false unless matcher_rvs.all? do |matcher_item|
           return false unless message_rvs.any? do |message_item|
-            next message_item['n'] == query_item['n'] && message_item['v'] == query_item['v']
+            next message_item['n'] == matcher_item['n'] && message_item['v'] == matcher_item['v']
           end
           next true
         end
@@ -41,8 +41,8 @@ module RSMP
     end
 
     # return a string that describes what we're collecting
-    def describe_query
-      "#{describe_num_and_type} #{ {component: @options[:component]}.merge(@query).compact }"
+    def describe_matcher
+      "#{describe_num_and_type} #{ {component: @options[:component]}.merge(@matcher).compact }"
     end
 
   end

data/lib/rsmp/collect/{alarm_query.rb → alarm_matcher.rb}

@@ -1,7 +1,7 @@
 module RSMP
   # Match a specific alarm
-  class AlarmQuery < Query
-    # Match an alarm value against a query
+  class AlarmMatcher < Matcher
+    # Match an alarm value against a matcher
     def match? item
       return false if @want['n'] && @want['n'] != item['n']
       if @want['v'].is_a? Regexp

data/lib/rsmp/collect/collector.rb

@@ -1,40 +1,53 @@
 module RSMP
 
-  # Collects messages from a notifier.
+  # 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.
-  class Collector < Listener
-    attr_reader :condition, :messages, :status, :error, :task
+  class Collector
+    include Receiver
+    attr_reader :condition, :messages, :status, :error, :task, :m_id
 
-    def initialize notifier, options={}
-      super notifier, options
+    def initialize distributor, options={}
+      initialize_receiver distributor, filter: options[:filter]
       @options = {
         cancel: {
           schema_error: true,
           disconnect: false,
         }
       }.deep_merge options
-      @ingoing = options[:ingoing] == nil ? true  : options[:ingoing]
-      @outgoing = options[:outgoing] == nil ? false : options[:outgoing]
+      @timeout = options[:timeout]
+      @num = options[:num]
+      @m_id = options[:m_id]
       @condition = Async::Notification.new
-      @title = options[:title] || [@options[:type]].flatten.join('/')
-      if options[:task]
-        @task = options[:task]
+      make_title options[:title]
+      
+      if task
+        @task = task
       else
-         # if notifier is a Proxy, or some other object that implements task(),
+         # if distributor is a Proxy, or some other object that implements task(),
          # then try to get the task that way
-        if notifier.respond_to? 'task'
-          @task = notifier.task
+        if distributor.respond_to? 'task'
+          @task = distributor.task
         end
       end
       reset
     end
 
+    def make_title title
+      if title
+        @title = title
+      elsif @filter
+        @title = [@filter.type].flatten.join('/')
+      else
+        @title = ""
+      end
+    end
+
     def use_task task
       @task = task
     end
 
-    # Clear all query results
+    # Clear all matcher results
     def reset
       @messages = []
       @error = nil
@@ -95,7 +108,7 @@ module RSMP
       wait
       @status
     ensure
-      @notifier.remove_listener self if @notifier
+      @distributor.remove_receiver self if @distributor
     end
 
     # Collect message
@@ -110,8 +123,8 @@ module RSMP
     # the desired messages have been collected, or timeout is reached.
     def wait
       if collecting?
-        if @options[:timeout]
-          @task.with_timeout(@options[:timeout]) { @condition.wait }
+        if @timeout
+          @task.with_timeout(@timeout) { @condition.wait }
         else
           @condition.wait
         end
@@ -136,39 +149,41 @@ module RSMP
     def start &block
       raise RuntimeError.new("Can't start collectimng unless ready (currently #{@status})") unless ready?
       @block = block
-      raise ArgumentError.new("Num, timeout or block must be provided") unless @options[:num] || @options[:timeout] || @block
+      raise ArgumentError.new("Num, timeout or block must be provided") unless @num || @timeout || @block
       reset
       @status = :collecting
       log_start
-      @notifier.add_listener self if @notifier
+      @distributor.add_receiver self if @distributor
     end
 
     # Build a string describing how how progress reached before timeout
     def describe_progress
       str = "#{identifier}: #{@title.capitalize} collection "
-      str << "in response to #{@options[:m_id]} " if @options[:m_id]
-      str << "didn't complete within #{@options[:timeout]}s, "
-      str << "reached #{@messages.size}/#{@options[:num]}"
+      str << "in response to #{@m_id} " if @m_id
+      str << "didn't complete within #{@timeout}s, "
+      str << "reached #{@messages.size}/#{@num}"
       str
     end
 
     # Check if we receive a NotAck related to initiating request, identified by @m_id.
     def reject_not_ack message
-      return unless @options[:m_id]
+      return unless @m_id
       if message.is_a?(MessageNotAck)
-        if message.attribute('oMId') == @options[:m_id]
-          m_id_short = RSMP::Message.shorten_m_id @options[:m_id], 8
+        if message.attribute('oMId') == @m_id
+          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')}'")
-          @notifier.log "#{identifier}: cancelled due to a NotAck", level: :debug
+          @distributor.log "#{identifier}: cancelled due to a NotAck", level: :debug
           true
         end
       end
     end
 
     # Handle message. and return true when we're done collecting
-    def notify message
+    def receive message
       raise ArgumentError unless message
-      raise RuntimeError.new("can't process message when status is :#{@status}, title: #{@title}, desc: #{describe}") unless ready? || collecting?
+      unless ready? || collecting?
+        raise RuntimeError.new("can't process message when status is :#{@status}, title: #{@title}, desc: #{describe}") 
+      end
       if perform_match message
         if done?
           complete
@@ -185,8 +200,8 @@ module RSMP
     # Match message against our collection criteria
     def perform_match message
       return false if reject_not_ack(message)
-      return false unless type_match?(message)
-      #@notifier.log "#{identifier}: Looking at #{message.type} #{message.m_id_short}", level: :collect
+      return false unless acceptable?(message)
+      #@distributor.log "#{identifier}: Looking at #{message.type} #{message.m_id_short}", level: :collect
       if @block
         status = [@block.call(message)].flatten
         return unless collecting?
@@ -198,10 +213,10 @@ module RSMP
 
     # Have we collected the required number of messages?
     def done?
-      @options[:num] && @messages.size >= @options[:num]
+      @num && @messages.size >= @num
     end
 
-    # Called when we're done collecting. Remove ourself as a listener,
+    # Called when we're done collecting. Remove ourself as a receiver,
     # se we don't receive message notifications anymore
     def complete
       @status = :ok
@@ -214,39 +229,39 @@ module RSMP
       log_incomplete
     end
 
-    # Remove ourself as a listener, so we don't receive message notifications anymore,
+    # Remove ourself as a receiver, so we don't receive message notifications anymore,
     # and wake up the async condition
     def do_stop
-      @notifier.remove_listener self
+      @distributor.remove_receiver self
       @condition.signal
     end
 
     # An error occured upstream.
     # Check if we should cancel.
-    def notify_error error, options={}
+    def receive_error error, options={}
       case error
       when RSMP::SchemaError
-        notify_schema_error error, options
+        receive_schema_error error, options
       when RSMP::DisconnectError
-        notify_disconnect error, options
+        receive_disconnect error, options
       end
     end
 
     # Cancel if we received e schema error for a message type we're collecting
-    def notify_schema_error error, options
+    def receive_schema_error error, options
       return unless @options.dig(:cancel,:schema_error)
       message = options[:message]
       return unless message
       klass = message.class.name.split('::').last
-      return unless @options[:type] == nil || [@options[:type]].flatten.include?(klass)
-      @notifier.log "#{identifier}: cancelled due to schema error in #{klass} #{message.m_id_short}", level: :debug
+      return unless @filter&.type == nil || [@filter&.type].flatten.include?(klass)
+      @distributor.log "#{identifier}: cancelled due to schema error in #{klass} #{message.m_id_short}", level: :debug
       cancel error
     end
 
     # Cancel if we received e notificaiton about a disconnect
-    def notify_disconnect error, options
+    def receive_disconnect error, options
       return unless @options.dig(:cancel,:disconnect)
-      @notifier.log "#{identifier}: cancelled due to a connection error: #{error.to_s}", level: :debug
+      @distributor.log "#{identifier}: cancelled due to a connection error: #{error.to_s}", level: :debug
       cancel error
     end
 
@@ -264,39 +279,27 @@ module RSMP
 
     # Check a message against our match criteria
     # Return true if there's a match, false if not
-    def type_match? message
-      return false if message.direction == :in && @ingoing == false
-      return false if message.direction == :out && @outgoing == false
-      if @options[:type]
-        if @options[:type].is_a? Array
-          return false unless @options[:type].include? message.type
-        else
-          return false unless message.type == @options[:type]
-        end
-      end
-      if @options[:component]
-        return false if message.attributes['cId'] && message.attributes['cId'] != @options[:component]
-      end
-      true
+    def acceptable? message
+      @filter == nil || @filter.accept?(message)
     end
 
     # return a string describing the types of messages we're collecting
     def describe_types
-      [@options[:type]].flatten.join('/')
+      [@filter&.type].flatten.join('/')
     end
 
     # return a string that describes whe number of messages, and type of message we're collecting
     def describe_num_and_type
-      if @options[:num] && @options[:num] > 1
-        "#{@options[:num]} #{describe_types}s"
+      if @num && @num > 1
+        "#{@num} #{describe_types}s"
       else
         describe_types
       end
     end
 
     # return a string that describes the attributes that we're looking for
-    def describe_query
-      h = {component: @options[:component]}.compact
+    def describe_matcher
+      h = {component: @filter&.component}.compact
       if h.empty?
         describe_num_and_type
       else
@@ -306,8 +309,8 @@ module RSMP
 
     # return a string that describe how many many messages have been collected
     def describe_progress
-      if @options[:num]
-        "#{@messages.size} of #{@options[:num]} message#{'s' if @messages.size!=1} collected"
+      if @num
+        "#{@messages.size} of #{@num} message#{'s' if @messages.size!=1} collected"
       else
         "#{@messages.size} message#{'s' if @messages.size!=1} collected"
       end        
@@ -315,17 +318,17 @@ module RSMP
 
     # log when we start collecting
     def log_start
-      @notifier.log "#{identifier}: Waiting for #{describe_query}".strip, level: :collect
+      @distributor.log "#{identifier}: Waiting for #{describe_matcher}".strip, level: :collect
     end
 
     # log current progress
     def log_incomplete
-      @notifier.log "#{identifier}: #{describe_progress}", level: :collect
+      @distributor.log "#{identifier}: #{describe_progress}", level: :collect
     end
 
     # log when we end collecting
     def log_complete
-      @notifier.log "#{identifier}: Done", level: :collect
+      @distributor.log "#{identifier}: Done", level: :collect
     end
 
     # get a short id in hex format, identifying ourself

data/lib/rsmp/collect/{command_query.rb → command_matcher.rb}

@@ -1,7 +1,7 @@
 module RSMP
   # Match a specific command responses
-  class CommandQuery < Query
-    # Match a return value item against a query
+  class CommandMatcher < Matcher
+    # Match a return value item against a matcher
     def match? item
       return nil if @want['cCI'] && @want['cCI'] != item['cCI']
       return nil if @want['n'] && @want['n'] != item['n']

data/lib/rsmp/collect/command_response_collector.rb

@@ -3,13 +3,13 @@ module RSMP
   class CommandResponseCollector < StateCollector
     def initialize proxy, want, options={}
       super proxy, want, options.merge(
-        type: 'CommandResponse',
+        filter: RSMP::Filter.new(ingoing: true, outgoing: false, type: 'CommandResponse'),
         title:'command response'
       )
     end
 
-    def build_query want
-      CommandQuery.new want
+    def build_matcher want
+      CommandMatcher.new want
     end
 
     # Get items, in our case the return values

data/lib/rsmp/collect/distributor.rb

@@ -0,0 +1,65 @@
+# Distributes messages to receivers
+
+module RSMP
+  module Distributor
+    attr_reader :receivers
+
+    include Inspect
+
+    def inspect
+      "#<#{self.class.name}:#{self.object_id}, #{inspector(:@receivers)}>"
+    end
+
+    def initialize_distributor
+      @receivers = []
+      @defer_distribution = false
+      @deferred_messages = []
+    end
+
+    def clear_deferred_distribution &block
+      @deferred_messages = []
+    end
+
+    def with_deferred_distribution &block
+      was, @defer_distribution = @defer_distribution, true
+      yield
+      distribute_queued
+    ensure
+      @defer_distribution = was
+      @deferred_messages = []
+    end
+
+    def distribute_queued
+      @deferred_messages.each { |message| distribute_immediately message }
+    ensure
+      @deferred_messages = []
+    end
+
+    def add_receiver receiver
+      raise ArgumentError unless receiver
+      @receivers << receiver unless @receivers.include? receiver
+    end
+
+    def remove_receiver receiver
+      raise ArgumentError unless receiver
+      @receivers.delete receiver
+    end
+
+    def distribute message
+      raise ArgumentError unless message
+      if @defer_distribution
+        @deferred_messages << message
+      else
+        distribute_immediately message
+      end
+    end
+
+    def distribute_immediately message
+      @receivers.each { |receiver| receiver.receive message }
+    end
+
+    def distribute_error error, options={}
+      @receivers.each { |receiver| receiver.receive_error error, options }
+    end
+  end
+end