rsmp 0.51.4 → 0.52.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 653475280335ad2b867657cada46ef95d9cb61808cb12f3302762b0e2bcda790
-  data.tar.gz: 2d8b6cfe3c5b46623329cb1dbcb1a01544dd293ab93f5398b650fea8121d31fd
+  metadata.gz: cfba3255efe256eae701725584e74d80a7ba66fe94708ef9bdc76cbd678c7700
+  data.tar.gz: b0aebcd26383d1ed77fbcdd18351fecc0a7afcc962d582f17a3f488a53aaeb22
 SHA512:
-  metadata.gz: 82018c56d70a3cfa59db7d60b30c172f324765a01be8d650906d64c92109d68c52d80f75efdf388fd8332a9fa5028bc0ee1bed51e4293a1ffa6c5f441bfec8db
-  data.tar.gz: a1b83604f3b516da1dc0e8a3071cddd71cd4cadbc78f22406fe5ea0f73d21c06663ef1739de1666818d88ea85445cc6cc045ee024987fe2120a4ddc6e179b539
+  metadata.gz: f7796d54dbed77a9d230a4e49f3ddadd22b3833b29fa05c882f9d7a6c540ed64ae55745f5b8dbe38a9fe095fa49b45684f9ebaf0a954d9fa021d892f2bdc5cec
+  data.tar.gz: 5bf194b21059fd35d82e41093c68658585fe083cc061f5759e98d95df1f45e5fbd0958051cb3dbac8b771f915fc0511c056f72c887339f1b5df6c60f73d6a57f

data/CHANGELOG.md

@@ -729,3 +729,9 @@ Initial release.
 ## 0.51.4
 - don't update subscription list until unsubscribe is acknowledged
 
+## 0.52.0
+- allow the proxy's `collect:` option to accept a Proc that builds a collector or queue before the handshake
+- add optional `predicate:` filtering to collectors, including status collectors
+- add `start` and `stop` aliases to queues for use with proxy collection factories
+- fix status collectors to honor `component:` and `responses:`; the misspelled `reponses:` option is no longer used
+

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rsmp (0.51.4)
+    rsmp (0.52.0)
       async (~> 2.45)
       colorize (~> 1.1)
       io-endpoint (~> 0.17)

data/documentation/collecting_message.md

@@ -112,6 +112,118 @@ result = collector.collect do |message|
 end
 ```
 
+### Message predicates
+
+Use `predicate:` for conditions beyond the message type, direction, and component
+handled by `RSMP::Filter`. The Proc receives a whole message after the filter
+accepts it. Returning `false` or `nil` skips the message before collection
+callbacks or state-item matching; earlier item matches remain intact.
+
+```ruby
+collector = RSMP::Collector.new(
+  proxy,
+  filter: RSMP::Filter.new(type: 'StatusUpdate', ingoing: true, outgoing: false),
+  predicate: ->(message) { message.is_a?(RSMP::StatusUpdate) && message.attribute('sS').any? },
+  num: 1,
+  timeout: 5
+)
+```
+
+Predicates also work with `StatusCollector`. They do not suppress failures such
+as a rejection of the initiating request or an invalid peer message. `Filter`
+admits `MessageNotAck` even when a different message type is requested, so a
+predicate that accesses type-specific attributes should check the message type.
+
+### Status collection
+
+`StatusCollector` matches wanted status items within incoming messages. Both
+`StatusUpdate` and `StatusResponse` are accepted by default. Set `responses: false`
+to accept updates only, or `updates: false` to accept responses only.
+
+```ruby
+want = [{ 'sCI' => 'S0001', 'n' => 'signalgroupstatus' }]
+collector = RSMP::StatusCollector.new(
+  proxy, want, component: 'C1', responses: false, timeout: 5
+)
+```
+
+`component:` filters the message's `cId`; the wanted items describe entries in
+`sS`, which do not have their own component ID. Collection completes when all
+wanted items match, rather than after a fixed number of messages.
+
+### Collection during proxy setup
+
+The proxy's `collect:` option accepts the existing collector options hash:
+
+```ruby
+proxy_options = {
+  collect: {
+    filter: RSMP::Filter.new(type: 'StatusUpdate', ingoing: true, outgoing: false),
+    num: 1,
+    timeout: 5
+  }
+}
+```
+
+It also accepts a Proc that receives the new proxy and returns a collector or
+queue. The proxy calls `start` on the returned object and exposes it through
+`proxy.collector`. This starts receiving before the handshake can deliver
+messages. Return an unstarted object; the factory runs before version negotiation
+and should not rely on the proxy being fully initialized or connected.
+
+```ruby
+proxy_options = {
+  collect: proc do |proxy|
+    RSMP::StatusCollector.new(
+      proxy,
+      [{ 'sCI' => 'S0001', 'n' => 'signalgroupstatus' }],
+      component: 'C1', responses: false, timeout: 5
+    )
+  end
+}
+```
+
+Pass these options when creating the proxy. Use `proxy.collector.wait` or
+`wait!` for a collector, or `wait_for_message` or `wait_for_message!` for a queue.
+
+## Queues
+
+`RSMP::Queue` retains accepted messages until consumed, including messages that
+arrive before the caller starts waiting. Each wait returns one message, rather
+than a collection. `start` and `stop` are aliases for `start_receiving` and
+`stop_receiving`, so a queue can also be returned by a proxy's `collect:` factory.
+
+```ruby
+queue = RSMP::Queue.new(proxy, filter: RSMP::Filter.new(type: 'StatusUpdate'))
+queue.start
+begin
+  result = queue.wait_for_message(timeout: 5)
+  puts result.value if result.success?
+ensure
+  queue.stop
+end
+```
+
+A queue stays registered until stopped. Its `timeout:` applies to an individual
+wait: expiry returns a failure with code `:timeout`, or raises
+`RSMP::OperationError` through `wait_for_message!`.
+
+An enclosing Async timeout raised while waiting in the queue is converted in
+the same way, even when no queue timeout is supplied:
+
+```ruby
+begin
+  message = Async::Task.current.with_timeout(5) { queue.wait_for_message! }
+rescue RSMP::OperationError => error
+  raise unless error.failure.code == :timeout
+
+  warn 'The caller deadline expired'
+end
+```
+
+This example assumes the queue is already started. Both timeout sources use the
+same failure code; `failure.cause` retains the original Async exception.
+
 ## Sending and collecting atomically
 
 High-level send methods follow the same non-bang/bang convention:

data/lib/rsmp/collect/collector.rb

@@ -7,6 +7,9 @@ module RSMP
 
     attr_reader :messages, :m_id, :initiator
 
+    # :predicate optionally receives each message accepted by the filter. A falsey
+    # result skips the message before collection callbacks or item matching.
+    # Rejection and invalid-message failures are handled independently of it.
     def initialize(distributor, options = {})
       initialize_receiver distributor, filter: options[:filter]
       @options = {
@@ -17,6 +20,7 @@ module RSMP
       }.deep_merge(options)
       @timeout = options[:timeout]
       @num = options[:num]
+      @predicate = options[:predicate]
       @initiator = options[:initiator]
       @m_id = options[:m_id] || @initiator&.attributes&.dig('mId')
       make_title(options[:title])
@@ -131,6 +135,8 @@ module RSMP
     def perform_match?(message)
       return false if reject_not_ack?(message)
       return false unless acceptable?(message)
+      return false if @predicate && !@predicate.call(message)
+      return false unless active?
 
       if @block
         status = Array(@block.call(message))

data/lib/rsmp/collect/queue.rb

@@ -7,6 +7,10 @@ module RSMP
 
     attr_reader :messages
 
+    # Allow queues to be started by a proxy's collect factory, like collectors.
+    alias start start_receiving
+    alias stop stop_receiving
+
     def initialize(distributor, filter: nil)
       initialize_receiver distributor, filter: filter
       @condition = Async::Notification.new

data/lib/rsmp/collect/status_collector.rb

@@ -4,11 +4,11 @@ module RSMP
     def initialize(proxy, want, options = {})
       type = []
       type << 'StatusUpdate' unless options[:updates] == false
-      type << 'StatusResponse' unless options[:reponses] == false
+      type << 'StatusResponse' unless options[:responses] == false
 
       super(proxy, want, options.merge(
         title: 'status response',
-        filter: RSMP::Filter.new(ingoing: true, outgoing: false, type: type)
+        filter: RSMP::Filter.new(ingoing: true, outgoing: false, type: type, component: options[:component])
       ))
     end
 

data/lib/rsmp/proxy/proxy.rb

@@ -106,9 +106,15 @@ module RSMP
       @rejected_sxls = []
       @receive_alarms = true
       @site_settings = nil # can't pick until we know the site id
-      return unless options[:collect]
+      collect = options[:collect]
+      return unless collect
+
+      @collector = if collect.is_a?(Proc)
+                     collect.call(self)
+                   else
+                     RSMP::Collector.new self, collect
+                   end
 
-      @collector = RSMP::Collector.new self, options[:collect]
       @collector.start
     end
 

data/lib/rsmp/version.rb

@@ -1,3 +1,3 @@
 module RSMP
-  VERSION = '0.51.4'.freeze
+  VERSION = '0.52.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rsmp
 version: !ruby/object:Gem::Version
-  version: 0.51.4
+  version: 0.52.0
 platform: ruby
 authors:
 - Emil Tin