rsmp 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9614e6db6381449fa893901766de8239b7bc025c4454724709dc32b75551b5f3
-  data.tar.gz: fce1a7fb067481f5ca199301bbd91953d0dd8d13f07e66ad365a5ffa24e58966
+  metadata.gz: 5316c50ad6cd09d30e7d1baab78e717fac4656c06178272ef4adc1c6647fb544
+  data.tar.gz: 6ef4d635b42f3eac19b94b68bbcb05c59ce94de96e0e27f1f5c7a6deefd4e470
 SHA512:
-  metadata.gz: b942ee93f8185051dadac06576087ca8b27b11f8e3c653cb9638a72464941dd72c82c566ede50a46d2bffeb16c809345ef78b3edef7174a74d8ea75e963fa8f1
-  data.tar.gz: 0052cb6afefed493e4ac4e2d48f4c587afe3f377ddabd2492fbeb3c223ff78e39b23ac7b01cd5e564abc3474a5f8f0b35b6edc93c24c453876597c478365ac2a
+  metadata.gz: 1947906505e532d0d47d93f1d9fe2c8c3199ff58d378b9be3df18865339e966a6ad5f74512aa168ee4a5d641624cf7b0f170436d2c11e4f495bd7d6b88be502f
+  data.tar.gz: ee0ecbb229637276d6cec21ccacc6414199ad7f0392324633231cb4a8632a8b64b1aa2ba5abd979a7699ed6721a5a40b9d9c531f45dc0f59345149662e608b12

data/Gemfile.lock

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

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 StatusUpdateCollector 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,9 +1,10 @@
 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, :status, :error
+    attr_reader :condition, :messages, :status, :error, :task
 
     def initialize proxy, options={}
       super proxy, options
@@ -17,15 +18,19 @@ module RSMP
       @outgoing = options[:outgoing] == nil ? false : options[:outgoing]
       @condition = Async::Notification.new
       @title = options[:title] || [@options[:type]].flatten.join('/')
+      @task = options[:task]
       reset
     end
 
+    def use_task task
+      @task = task
+    end
+
     # Clear all query results
     def reset
       @messages = []
       @error = nil
       @status = :ready
-      @why = nil
     end
 
     # Inspect formatter that shows the message we have collected
@@ -33,6 +38,31 @@ module RSMP
       "#<#{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
@@ -43,35 +73,53 @@ module RSMP
       @outgoing == true
     end
 
-    # If collection is complete, return immeditatly. Otherwise wait until
-    # the desired messages have been collected, or timeout is reached.
-    def wait task
-      wait! task
-    rescue RSMP::TimeoutError
+    # 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
     end
 
-    # If collection is complete, return immeditatly. Otherwise wait until
-    # the desired messages have been collected.
-    # If timeout is reached, an exceptioin is raised.
-    def wait! task
-      return @status unless @status == :collecting
-      if @options[:timeout]
-        task.with_timeout(@options[:timeout]) { @condition.wait }
-      else
-        @condition.wait
+    # Collect message
+    # 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
+      @messages
+    end
+
+    # 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
-      raise RSMP::TimeoutError.new(describe_progress)
+    end
+
+    # 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
 
     # Start collection and return immediately
     # You can later use wait() to wait for completion
-    def start options={}, &block
-      raise RuntimeError.new("Can't begin unless ready (currenty #{@status})") unless @status == :ready
-      @options.merge! options
+    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
@@ -79,16 +127,6 @@ module RSMP
       @notifier.add_listener self if @notifier
     end
 
-    # Collect message
-    # Will return once all messages have been collected, or timeout is reached
-    def collect task, options={}, &block
-      start options, &block
-      wait task
-      @status
-    ensure
-      @notifier.remove_listener self
-    end
-
     # Build a string describing how how progress reached before timeout
     def describe_progress
       str = "#{@title.capitalize} collection "
@@ -98,17 +136,6 @@ module RSMP
       str
     end
 
-    # Collect message
-    # Returns the collected messages, or raise an exception in case of a time out.
-    def collect! task, options={}, &block
-      case collect(task, options, &block)
-      when :timeout
-        raise RSMP::TimeoutError.new @why
-      else
-        @messages
-      end
-    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]
@@ -124,7 +151,7 @@ module RSMP
     # 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 done") unless @status == :ready || @status == :collecting
+      raise RuntimeError.new("can't process message when done") unless ready? || collecting?
       unless reject_not_ack(message)
         perform_match message
       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/message_matchers.rb

@@ -1,64 +0,0 @@
-module RSMP
-  # Class for waiting for specific command responses
-  class CommandResponseMatcher < Matcher
-    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
-
-  # Base class for waiting for status updates or responses
-  class StatusUpdateOrResponseMatcher < Matcher
-    def initialize proxy, want, options={}
-      super proxy, want, options.merge
-    end
-
-    def build_query want
-      StatusQuery.new want
-    end
-
-    # Get items, in our case status values
-    def get_items message
-      message.attributes['sS']
-    end
-  end
-
-  # Class for waiting for specific status responses
-  class StatusResponseMatcher < StatusUpdateOrResponseMatcher
-    def initialize proxy, want, options={}
-      super proxy, want, options.merge(
-        type: ['StatusResponse','MessageNotAck'],
-        title: 'status response'
-      )
-    end
-  end
-
-  # Class for waiting for specific status responses
-  class StatusUpdateMatcher < StatusUpdateOrResponseMatcher
-    def initialize proxy, want, options={}
-      super proxy, want, options.merge(
-        type: ['StatusUpdate','MessageNotAck'],
-        title:'status update'
-      )
-    end
-  end
-
-  # Class for waiting for an aggregated status response
-  class AggregatedStatusMatcher < Collector
-    def initialize proxy, options={}
-      required = { type: ['AggregatedStatus','MessageNotAck'], title: 'aggregated status' }
-      super proxy, options.merge(required)
-    end
-  end
-end

data/lib/rsmp/collect/{matcher.rb → state_collector.rb}

@@ -31,8 +31,7 @@ module RSMP
   #   {"cCI"=>"M0104", "cO"=>"setDate", "n"=>"month", "v"=>/\d+/} =>
   #     { <StatusResponse message>, {"cCI"=>"M0104", "cO"=>"setDate", "n"=>"month", "v"=>"9"} }
   # }
-
-  class Matcher < Collector
+  class StateCollector < Collector
     attr_reader :queries
 
     # Initialize with a list of wanted statuses

data/lib/rsmp/collect/{message_queries.rb → status_query.rb}

@@ -1,19 +1,4 @@
 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
-
   # Match a specific status response or update
   class StatusQuery < Query
     # Match a status value against a query

data/lib/rsmp/collect/status_response_collector.rb

@@ -0,0 +1,11 @@
+module RSMP
+  # Class for waiting for specific status responses
+  class StatusResponseCollector < StatusUpdateOrResponseCollector
+    def initialize proxy, want, options={}
+      super proxy, want, options.merge(
+        type: ['StatusResponse','MessageNotAck'],
+        title: 'status response'
+      )
+    end
+  end
+end

data/lib/rsmp/collect/status_update_collector.rb

@@ -0,0 +1,11 @@
+module RSMP
+  # Class for waiting for specific status responses
+  class StatusUpdateCollector < StatusUpdateOrResponseCollector
+    def initialize proxy, want, options={}
+      super proxy, want, options.merge(
+        type: ['StatusUpdate','MessageNotAck'],
+        title:'status update'
+      )
+    end
+  end
+end

data/lib/rsmp/collect/status_update_or_response_collector.rb

@@ -0,0 +1,17 @@
+module RSMP
+  # Base class for waiting for status updates or responses
+  class StatusUpdateOrResponseCollector < StateCollector
+    def initialize proxy, want, options={}
+      super proxy, want, options.merge
+    end
+
+    def build_query want
+      RSMP::StatusQuery.new want
+    end
+
+    # Get items, in our case status values
+    def get_items message
+      message.attributes['sS']
+    end
+  end
+end

data/lib/rsmp/proxy.rb

@@ -52,9 +52,9 @@ module RSMP
       node.clock
     end
 
-    def collect task, options, &block
-      collector = RSMP::Collector.new self, options
-      collector.collect task, &block
+    def collect options, &block
+      collector = RSMP::Collector.new self, options.merge(task: @task)
+      collector.collect &block
       collector
     end
 

data/lib/rsmp/site_proxy.rb

@@ -349,26 +349,26 @@ module RSMP
     end
 
     def collect_status_updates task, status_list, options
-      collector = StatusUpdateMatcher.new(self, status_list, options)
-      collector.collect task
+      collector = StatusUpdateCollector.new(self, status_list, options.merge(task:task))
+      collector.collect
       collector
     end
 
     def collect_status_responses task, status_list, options
-      collector = StatusResponseMatcher.new(self, status_list, options)
-      collector.collect task
+      collector = StatusResponseCollector.new(self, status_list, options.merge(task:task))
+      collector.collect
       collector
     end
 
     def collect_command_responses task, command_list, options
-      collector = CommandResponseMatcher.new(self, command_list, options)
-      collector.collect task
+      collector = CommandResponseCollector.new(self, command_list, options.merge(task:task))
+      collector.collect
       collector
     end
 
     def collect_aggregated_status task, options
-      collector = AggregatedStatusMatcher.new(self, options)
-      collector.collect task
+      collector = AggregatedStatusCollector.new(self, options.merge(task:task))
+      collector.collect
       collector
     end
   end

data/lib/rsmp/tlc/signal_group.rb

@@ -16,7 +16,7 @@ module RSMP
         return default unless plan.states
         states = plan.states[c_id]
         return default unless states
-        state =states[pos]
+        state = states[pos]
         return default unless state =~ /[a-hA-G0-9N-P]/  # valid signal group states
         state
       end

data/lib/rsmp/version.rb

@@ -1,3 +1,3 @@
 module RSMP
-  VERSION = "0.8.0"
+  VERSION = "0.8.1"
 end

data/lib/rsmp.rb

@@ -20,10 +20,15 @@ require 'rsmp/components'
 require 'rsmp/collect/notifier'
 require 'rsmp/collect/listener'
 require 'rsmp/collect/collector'
+require 'rsmp/collect/state_collector'
 require 'rsmp/collect/query'
-require 'rsmp/collect/matcher'
-require 'rsmp/collect/message_queries'
-require 'rsmp/collect/message_matchers'
+require 'rsmp/collect/status_query'
+require 'rsmp/collect/command_query'
+require 'rsmp/collect/status_update_or_response_collector'
+require 'rsmp/collect/status_response_collector'
+require 'rsmp/collect/status_update_collector'
+require 'rsmp/collect/command_response_collector'
+require 'rsmp/collect/aggregated_status_collector'
 require 'rsmp/component'
 require 'rsmp/site'
 require 'rsmp/proxy'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rsmp
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Emil Tin
@@ -201,19 +201,25 @@ files:
 - config/supervisor.yaml
 - config/tlc.yaml
 - documentation/classes_and_modules.md
+- documentation/collecting_message.md
 - documentation/message_distribution.md
 - exe/rsmp
 - lib/rsmp.rb
 - lib/rsmp/archive.rb
 - lib/rsmp/cli.rb
+- lib/rsmp/collect/aggregated_status_collector.rb
 - lib/rsmp/collect/collector.rb
+- lib/rsmp/collect/command_query.rb
+- lib/rsmp/collect/command_response_collector.rb
 - lib/rsmp/collect/listener.rb
-- lib/rsmp/collect/matcher.rb
-- lib/rsmp/collect/message_collector.rb
 - lib/rsmp/collect/message_matchers.rb
-- lib/rsmp/collect/message_queries.rb
 - lib/rsmp/collect/notifier.rb
 - lib/rsmp/collect/query.rb
+- lib/rsmp/collect/state_collector.rb
+- lib/rsmp/collect/status_query.rb
+- lib/rsmp/collect/status_response_collector.rb
+- lib/rsmp/collect/status_update_collector.rb
+- lib/rsmp/collect/status_update_or_response_collector.rb
 - lib/rsmp/component.rb
 - lib/rsmp/components.rb
 - lib/rsmp/convert/export/json_schema.rb

data/lib/rsmp/collect/message_collector.rb

@@ -1,209 +0,0 @@
-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.
-  class MessageCollector < Collector
-    attr_reader :condition, :messages, :done
-
-    def initialize proxy, options={}
-      super proxy, options
-      @options = {
-        cancel: {
-          schema_error: true,
-          disconnect: false,
-        }
-      }.deep_merge options
-      @ingoing = options[:ingoing] == nil ? true  : options[:ingoing]
-      @outgoing = options[:outgoing] == nil ? false : options[:outgoing]
-      @condition = Async::Notification.new
-      @title = options[:title] || [@options[:type]].flatten.join('/')
-      @options[:timeout] ||= 1
-      @options[:num] ||= 1
-      reset
-    end
-
-    # Inspect formatter that shows the message we have collected
-    def inspect
-      "#<#{self.class.name}:#{self.object_id}, #{inspector(:@messages)}>"
-    end
-
-    # Want ingoing messages?
-    def ingoing?
-      @ingoing == true
-    end
-
-    # Want outgoing messages?
-    def outgoing?
-      @outgoing == true
-    end
-
-    # Block until all messages have been collected
-    def wait
-      @condition.wait
-    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
-      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
-    end
-
-    # Return progress as collected vs. number requested
-    def progress
-      need = @options[:num]
-      reached =  @messages.size
-      { need: need, got: reached }
-    end
-
-    # Get the collected message.
-    def message
-      @messages.first
-    end
-
-    # Get the collected messages.
-    def messages
-      @messages
-    end
-
-    # Clear all query results
-    def reset
-      @messages = []
-      @error = nil
-      @done = false
-    end
-
-    # Check if we receive a NotAck related to initiating request, identified by @m_id.
-    def check_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
-        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
-      perform_match message
-      complete if done?
-      @done
-    end
-
-    # Match message against our collection criteria
-    def perform_match message
-      matched = type_match?(message) && block_match?(message)
-      if matched == true
-        keep message
-      elsif matched == false
-        forget message
-      end
-    end
-
-    # Have we collected the required number of messages?
-    def done?
-      @options[:num] && @messages.size >= @options[:num]
-    end
-
-    # 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
-      @condition.signal
-    end
-
-    # The proxy experienced some error.
-    # Check if this should cause us to cancel.
-    def notify_error error, options={}
-      case error
-      when RSMP::SchemaError
-        notify_schema_error error, options
-      when RSMP::ConnectionError
-        notify_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
-      return unless @options.dig(:cancel,:schema_error)
-      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
-      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
-      cancel error
-    end
-
-    # Abort collection
-    def cancel error
-      @error = error if error
-      @done = false
-      @proxy.remove_listener self
-      @condition.signal
-    end
-
-    # Store a message in the result array
-    def keep message
-      @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, 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
-    end
-  end
-
-  def block_match? message
-    @block.call(message) == true
-  end
-end