rsmp 0.7.5 → 0.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca0e580278192b1577388628e8a761a8b0fe61f175c40bdd6c40fc62ab61d700
-  data.tar.gz: 0dd69084856cd0ba08acd74655c6a856bc6222a00bfbfb0031aff24c8df2c17a
+  metadata.gz: f54121873905da2e5ffa4914f4f454fc4b59c7283e482b6b89b4035d686b7779
+  data.tar.gz: 523d2e310ebec8f4df07592fcb501d91f604ba8ea1c4625482c7d8d011340a6f
 SHA512:
-  metadata.gz: 4fa7f6e6f31e8d47369fb769a95d3a519262098d0821387ddfc29ef865e08ccd8f0cd49f65697eeb3ea28e0fb33783291feb2be9706784fc53891c4aaf8f6b66
-  data.tar.gz: 10b21ec864bb578e281686f1926303741d3182f42a2d6a82bb7a90f744fd4b50cfd704eeb773da99d96cdc1796a1876ea2b7f9d0296f303c4644d132f1d46761
+  metadata.gz: 807d2283a18f4a9c4e45594d4ae85e75464cde3792eb941342a825e8765a00d21f7d541fac03191680e28eb7e4af4c6624cb6ce80486da191cf3bc2b3f2d6431
+  data.tar.gz: 6adc50becc91e2deab2c8099808a492a2440d072188227147742bd51ec1310f8a1075e3bed72f2989581ba11125b9beeda8134704d8a42e131ac1dac9a76eca1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rsmp (0.7.5)
+    rsmp (0.8.3)
       async (~> 1.29.1)
       async-io (~> 1.32.1)
       colorize (~> 0.8.1)

data/config/tlc.yaml

@@ -21,10 +21,10 @@ signal_plans:
       1: 0
       2: 5
     states:
-      A1: '11NBBB'
-      A2: '1NBBBB'
-      B1: 'BBB11N'
-      B2: 'BBB1NB'
+      A1: '123efg'
+      A2: '123efg'
+      B1: '123efg'
+      B2: '123efg'
   2:
     states:
       A1: '111NBB'

data/documentation/classes_and_modules.md

@@ -19,9 +19,6 @@ Handle logging.
 ### Wait
 Handles waiting for an async condition and block.
 
-### SiteProxyWait
-Handles waiting for different types of messages and responses from a remote site.
-
 ### Components
 Component handling.
 
@@ -38,7 +35,7 @@ A Site has one or more SupervisorProxies (connections to supervisor).
 
 A site has one of more components.
 
-### Supervisor 
+### Supervisor
 A Supervisor represents an RSMP supervisor, typically a central supervisor system. An RSMP supervisor can handle connections one or more sites.
 
 A Supervisor has one or more SiteProxies (connections to sites).

data/documentation/collecting_message.md

@@ -0,0 +1,196 @@
+# Collection
+You often need to collect messages or responses. The collector classes are used to collect message asyncronously. Other tasks continue until the collection completes, time outs or is cancelled.
+
+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.
+
+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.
+
+
+## Collector
+Class uses 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.
+
+```ruby
+collector = MessageCollector.new notifier, num: 10, 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
+ingoing: Whether to collect ingoing messages. Defaults to true
+outgoing: Whether to collect outgoing messages. Defaults to true
+component: An RSMP component id.
+
+### Collecting
+Use collect() to start collecting and wait for completion or timeout. The status will be returned. 
+
+```ruby
+result = collector.collect # => :ok, :timeout or :cancelled
+collector.messages # => collected messages
+```
+
+If you want start collection, but not wait for the result, use `start()`. You can then later use `wait()` if you want:
+
+```ruby
+result = collector.start # => nil
+# do other stuff
+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.
+
+The block must return nil or a list of symbols to indicate whether the message should be kept, and whether collection should be cancelled.
+
+```ruby
+result = collector.collect do |message|
+	:keep, :cancel 		# example of how to keep the message and cancel collection
+end
+```
+
+`:keep` keeps (collect) this message
+`:cancel` cancel collection
+
+Note that you cannot use `return` in a block. You can either simply provide the values as the last expresssion in the block, or use next().
+
+Exceptions in the block will cause the collector to abort. If the collect! or wait! variants are used, the exception is propagated to the caller.
+
+### Bang version
+The method collect!() will raise exceptions in case of errors, and will return the collect message directly.
+
+```ruby
+message = collector.collect # => collected message.
+```
+
+Similar, `wait!()` will raise an exception in case of timeouts or errors:
+
+```ruby
+message = collector.wait! # => collected message.
+```
+
+
+### Schema Errors and Disconnects
+The collector can optionally cancel collection in special cases, controlled by the `:cancel` option provided when contructing the collector.
+
+```ruby
+options = {
+	cancel: {
+		disconnect: true,
+		schema_error: true
+	}
+}
+result = collector.collect options
+```
+
+disconnect: If the proxy which provides messages experience a disconnect, the collector will cancel collection.
+
+schema_error: If the proxy receives a message with a schema error, the collector will cancel collection, if the the invalid message has the correct message type.
+
+### NotAck
+A typical scenaria is that you send a command or status request, and want to collect the response. But if the original message is rejected by the site, you will received a NotAck instead of a reply. The collector classes can handle this, as long as you provide the message id of the original request in the `m_id` key of teh options when you construct the collector.
+
+If a NotAck is received with a matching `oMId` (original message id), the collection is cancelled.
+
+## StatusCollector
+Waits for a set of status criteria to be met.
+
+Note that a single RSMP status message can contain multiple status items. Unlike MessageCollector, a StatusCollector therefore operates on items, rather than messages, and you can't specify a number of messages to collect.
+
+
+### Criteria
+You construct a StatusCollector with set of criteria, specifying the status codes, names, and optionally values that must be met.
+
+### Collecting
+When you start collection, it will complete once all criteria are all fulfilled, the timeout is reached or a custom filtering block aborts the collection.
+
+```ruby
+collector = StatusCollector.new(options)
+result = matcher.collect(timeout: 5)
+```
+
+### Custom filtering
+You can use a block to do extra filtering. The block will be called for each individual status item that fulfils all criteria, like status code and name, component, etc.
+
+Like with MessageCollector, the block must return a hash specifing whether to keep the message and whether to continue collection.
+
+```ruby
+matcher = StatusCollector.new(options)
+result = matcher.collect(options) do |message,item|
+	next(:keep) if good_item?(item) 		# keep item
+end
+```
+
+## Subscribing to status updates
+The method `subscribe_to_status` can be used to subscribe to one of more status messages.
+
+### Without collection
+The simple form sends an RSMP status subscription message to the site and then returns immediatly. To collect incoming status messages, you need to manually use e.g. a Collector.
+
+A hash is returned, with `:sent` containing the send subscription messages.
+
+```ruby
+options = {
+	list: [{'sCI'=>'S0001','n'=>'signalgroupstatus'}],
+}
+result = subscribe_to_status(options)
+result.keys => # [:sent]
+```
+
+Note: If you want to use this simple form and manually collect responses, it's best to start collection in an asyncronous task _before_ you subscribe, to make sure you don't miss early responses:
+
+```ruby
+task = async do
+	MessageCollector.new(options).collect(num: 5, timeout:10)  # start listening for status messages
+end
+result = subscribe_to_status(options) # subscribe
+task.wait  # wait for collection task to complete (or time out)
+```
+
+### With collection
+If you provide `:collect` options, it will be used to construct a StatusCollector for collecting the relevant status messages. When collection completes the collector is returned in the `:collector` key:
+
+```ruby
+options = {
+	list: [{'sCI'=>'S0001','n'=>'signalgroupstatus'}],
+	collect: {timeout: 5}
+}
+result = subscribe_to_status(options)
+result.keys => # [:sent, :collector]
+result[:collector].messages # => list of collected messages
+```
+
+You can pass you own collector which will give you more control of how to collect the incoming status messages:
+
+```ruby
+collector = Collector.new(options)
+options = {collect: collector}
+result = subscribe_to_status(options)
+result.keys => # [:sent, :collector]
+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.
+
+```ruby
+options = {
+	list: [{'sCI'=>'S0001','n'=>'signalgroupstatus'}]
+}
+result = subscribe_to_status(options) do |message|
+	# do something with message
+	:keep # or not
+end
+result.keys => # [:sent, :collector]
+```
+

data/lib/rsmp/collect/aggregated_status_collector.rb

@@ -0,0 +1,9 @@
+module RSMP
+  # Class for waiting for an aggregated status response
+  class AggregatedStatusCollector < Collector
+    def initialize proxy, options={}
+      required = { type: ['AggregatedStatus','MessageNotAck'], title: 'aggregated status' }
+      super proxy, options.merge(required)
+    end
+  end
+end

data/lib/rsmp/collect/collector.rb

@@ -1,12 +1,13 @@
 module RSMP
 
-  # Collects ingoing and/or outgoing messages from a notifier.
-  # Can filter by message type and wakes up the client once the desired number of messages has been collected.
+  # Collects messages from a notifier.
+  # 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, :done
+    attr_reader :condition, :messages, :status, :error, :task
 
-    def initialize proxy, options={}
-      super proxy, options
+    def initialize notifier, options={}
+      super notifier, options
       @options = {
         cancel: {
           schema_error: true,
@@ -17,16 +18,59 @@ module RSMP
       @outgoing = options[:outgoing] == nil ? false : options[:outgoing]
       @condition = Async::Notification.new
       @title = options[:title] || [@options[:type]].flatten.join('/')
-      @options[:timeout] ||= 1
-      @options[:num] ||= 1
+      if options[:task]
+        @task = options[:task]
+      else
+         # if notifier 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
+        end
+      end
       reset
     end
 
+    def use_task task
+      @task = task
+    end
+
+    # Clear all query results
+    def reset
+      @messages = []
+      @error = nil
+      @status = :ready
+    end
+
     # Inspect formatter that shows the message we have collected
     def inspect
       "#<#{self.class.name}:#{self.object_id}, #{inspector(:@messages)}>"
     end
 
+    # Is collection active?
+    def collecting?
+      @status == :collecting
+    end
+
+    # Is collection active?
+    def ok?
+      @status == :ok
+    end
+
+    # Has collection time out?
+    def timeout?
+      @status == :timeout
+    end
+
+    # Is collection ready to start?
+    def ready?
+      @status == :ready
+    end
+
+    # Has collection been cancelled?
+    def cancelled?
+      @status == :cancelled
+    end
+
     # Want ingoing messages?
     def ingoing?
       @ingoing == true
@@ -37,91 +81,104 @@ module RSMP
       @outgoing == true
     end
 
-    # Block until all messages have been collected
-    def wait
-      @condition.wait
+    # Collect message
+    # Will return once all messages have been collected, or timeout is reached
+    def collect &block
+      start &block
+      wait
+      @status
+    ensure
+      @notifier.remove_listener self if @notifier
     end
 
     # Collect message
-    # Will block until all messages have been collected,
-    # or we time out 
-    def collect task, options={}, &block
-      @options.merge! options
-      @block = block
-      unless @done
-        listen do
-          task.with_timeout(@options[:timeout]) do
-            @condition.wait
-          end
-        end
+    # Returns the collected messages, or raise an exception in case of a time out.
+    def collect! &block
+      if collect(&block) == :timeout
+        raise RSMP::TimeoutError.new describe_progress
       end
-      return @error if @error
-      self
-    rescue Async::TimeoutError
-      str = "#{@title.capitalize} collection"
-      str << " in response to #{options[:m_id]}" if options[:m_id]
-      str << " didn't complete within #{@options[:timeout]}s"
-      reached = progress
-      str << ", reached #{progress[:reached]}/#{progress[:need]}"
-      raise RSMP::TimeoutError.new str
+      @messages
     end
 
-    # Return progress as collected vs. number requested
-    def progress
-      need = @options[:num]
-      reached =  @messages.size
-      { need: need, got: reached }
+    # If collection is not active, return status immeditatly. Otherwise wait until
+    # the desired messages have been collected, or timeout is reached.
+    def wait
+      if collecting?
+        if @options[:timeout]
+          @task.with_timeout(@options[:timeout]) { @condition.wait }
+        else
+          @condition.wait
+        end
+      end
+      @status
+    rescue Async::TimeoutError
+      @status = :timeout
     end
 
-    # Get the collected message.
-    def message
-      @messages.first
+    # If collection is not active, raise an error. Otherwise wait until
+    # the desired messages have been collected.
+    # If timeout is reached, an exceptioin is raised.
+    def wait!
+      wait
+      raise RSMP::TimeoutError.new(describe_progress) if timeout?
+      @messages
     end
 
-    # Get the collected messages.
-    def messages
-      @messages
+    # Start collection and return immediately
+    # You can later use wait() to wait for completion
+    def start &block
+      raise RuntimeError.new("Can't begin unless ready (currenty #{@status})") unless ready?
+      @block = block
+      raise ArgumentError.new("Num, timeout or block must be provided") unless @options[:num] || @options[:timeout] || @block
+      reset
+      @status = :collecting
+      @notifier.add_listener self if @notifier
     end
 
-    # Clear all query results
-    def reset
-      @messages = []
-      @error = nil
-      @done = false
+    # Build a string describing how how progress reached before timeout
+    def describe_progress
+      str = "#{@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
     end
 
     # Check if we receive a NotAck related to initiating request, identified by @m_id.
-    def check_not_ack message
+    def reject_not_ack message
       return unless @options[: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
-          @error = RSMP::MessageRejected.new("#{@title} #{m_id_short} was rejected with '#{message.attribute('rea')}'")
-          complete
+          cancel RSMP::MessageRejected.new("#{@title} #{m_id_short} was rejected with '#{message.attribute('rea')}'")
+          true
         end
-        false
       end
     end
 
     # Handle message. and return true when we're done collecting
     def notify message
       raise ArgumentError unless message
-      raise RuntimeError.new("can't process message when already done") if @done
-      check_not_ack(message)
-      return true if @done
-      check_match message
-      complete if done?
-      @done
+      raise RuntimeError.new("can't process message when status is :#{@status}, title: #{@title}, desc: #{describe}") unless ready? || collecting?
+      perform_match message
+      @status
+    end
+
+    def describe
     end
 
     # Match message against our collection criteria
-    def check_match message
-      matched = match? message
-      if matched == true
+    def perform_match message
+      return false if reject_not_ack(message)
+      return false unless type_match?(message)
+      if @block
+        status = [@block.call(message)].flatten
+        return unless collecting?
+        keep message if status.include?(:keep)
+      else
         keep message
-      elsif matched == false
-        forget message
       end
+      complete if done?
     end
 
     # Have we collected the required number of messages?
@@ -132,18 +189,24 @@ module RSMP
     # Called when we're done collecting. Remove ourself as a listener,
     # se we don't receive message notifications anymore
     def complete
-      @done = true
-      @proxy.remove_listener self
+      @status = :ok
+      do_stop
+    end
+
+    # Remove ourself as a listener, so we don't receive message notifications anymore,
+    # and wake up the async condition
+    def do_stop
+      @notifier.remove_listener self
       @condition.signal
     end
 
-    # The proxy experienced some error.
-    # Check if this should cause us to cancel.
+    # An error occured upstream.
+    # Check if we should cancel.
     def notify_error error, options={}
       case error
       when RSMP::SchemaError
         notify_schema_error error, options
-      when RSMP::ConnectionError
+      when RSMP::DisconnectError
         notify_disconnect error, options
       end
     end
@@ -154,24 +217,23 @@ module RSMP
       message = options[:message]
       return unless message
       klass = message.class.name.split('::').last
-      return unless [@options[:type]].flatten.include? klass
-      @proxy.log "Collect cancelled due to schema error in #{klass} #{message.m_id_short}", level: :debug
+      return unless @options[:type] == nil || [@options[:type]].flatten.include?(klass)
+      @notifier.log "Collection 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
       return unless @options.dig(:cancel,:disconnect)
-      @proxy.log "Collect cancelled due to a connection error: #{error.to_s}", level: :debug
+      @notifier.log "Collection cancelled due to a connection error: #{error.to_s}", level: :debug
       cancel error
     end
 
     # Abort collection
-    def cancel error
-      @error = error if error
-      @done = false
-      @proxy.remove_listener self
-      @condition.signal
+    def cancel error=nil
+      @error = error
+      @status = :cancelled
+      do_stop
     end
 
     # Store a message in the result array
@@ -179,30 +241,20 @@ module RSMP
       @messages << message
     end
 
-    # Remove a message from the result array
-    def forget message
-      @messages.delete message
-    end
-
     # Check a message against our match criteria
-    # Return true if there's a match
-    def match? message
-      raise ArgumentError unless message
-      return if message.direction == :in && @ingoing == false
-      return if message.direction == :out && @outgoing == false
+    # 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]
-        return if message == nil
         if @options[:type].is_a? Array
-          return unless @options[:type].include? message.type
+          return false unless @options[:type].include? message.type
         else
-          return unless message.type == @options[:type]
+          return false unless message.type == @options[:type]
         end
       end
       if @options[:component]
-        return if message.attributes['cId'] && message.attributes['cId'] != @options[:component]
-      end
-      if @block
-        return if @block.call(message) == false
+        return false if message.attributes['cId'] && message.attributes['cId'] != @options[:component]
       end
       true
     end

data/lib/rsmp/collect/command_query.rb

@@ -0,0 +1,16 @@
+module RSMP
+  # Match a specific command responses
+  class CommandQuery < Query
+    # Match a return value item against a query
+    def match? item
+      return nil if @want['cCI'] && @want['cCI'] != item['cCI']
+      return nil if @want['n'] && @want['n'] != item['n']
+      if @want['v'].is_a? Regexp
+        return false if @want['v'] && item['v'] !~ @want['v']
+      else
+        return false if @want['v'] && item['v'] != @want['v']
+      end
+      true
+    end
+  end
+end

data/lib/rsmp/collect/command_response_collector.rb

@@ -0,0 +1,20 @@
+module RSMP
+  # Class for waiting for specific command responses
+  class CommandResponseCollector < StateCollector
+    def initialize proxy, want, options={}
+      super proxy, want, options.merge(
+        type: ['CommandResponse','MessageNotAck'],
+        title:'command response'
+      )
+    end
+
+    def build_query want
+      CommandQuery.new want
+    end
+
+    # Get items, in our case the return values
+    def get_items message
+      message.attributes['rvs'] || []
+    end
+  end
+end

data/lib/rsmp/collect/filter.rb

@@ -0,0 +1,31 @@
+module RSMP
+
+  # Filter messages based on type, direction and component id.
+  # Used by Collectors.
+  class Filter
+    def initialize ingoing:true, outgoing:true, type:, component:nil
+      @ingoing = ingoing
+      @outgoing = outgoing
+      @type = type
+      @component = component
+    end
+
+    # Check a message against our match criteria
+    # Return true if there's a match, false if not
+    def accept? message
+      return false if message.direction == :in && @ingoing == false
+      return false if message.direction == :out && @outgoing == false
+      if @type
+        if @type.is_a? Array
+          return false unless @type.include? message.type
+        else
+          return false unless message.type == @type
+        end
+      end
+      if @component
+        return false if message.attributes['cId'] && message.attributes['cId'] != @component
+      end
+      true
+    end
+  end
+end