rsmp 0.51.3 → 0.52.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 883735d537c281828ffe79225cf667fef84b88e2055e39820cc4213168f715ec
-  data.tar.gz: 7c577e4ee8998cf1dbcb7308aa486122ba430d967375e4827030dd89c075f408
+  metadata.gz: cfba3255efe256eae701725584e74d80a7ba66fe94708ef9bdc76cbd678c7700
+  data.tar.gz: b0aebcd26383d1ed77fbcdd18351fecc0a7afcc962d582f17a3f488a53aaeb22
 SHA512:
-  metadata.gz: ae9f566fd7a1f2bc9c16f59507abfd1becacb0326489fa5308363daaee89122cb32863cbabf187f033fa34d18dfb6648a6e9f1150678e1c32d60aaa2f898be55
-  data.tar.gz: 6c2348ed50374b5d9f1b1b99313420d3190c588ac70bb562815c0b418e46ebd697fcdf8f8809915392ad8f42f70f5637b7154eb33df40d9d6695ce52b25c131a
+  metadata.gz: f7796d54dbed77a9d230a4e49f3ddadd22b3833b29fa05c882f9d7a6c540ed64ae55745f5b8dbe38a9fe095fa49b45684f9ebaf0a954d9fa021d892f2bdc5cec
+  data.tar.gz: 5bf194b21059fd35d82e41093c68658585fe083cc061f5759e98d95df1f45e5fbd0958051cb3dbac8b771f915fc0511c056f72c887339f1b5df6c60f73d6a57f

data/CHANGELOG.md

@@ -719,3 +719,19 @@ Initial release.
 
 ## 0.51.1
 - cleanup semantic versioning handling of version strings and use canonical schema versions internally
+
+## 0.51.2
+- bumb patch version for test purposes, no changes othewise
+
+## 0.51.3
+- ensure socket shutdown when stopping node
+
+## 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.3)
+    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/documentation/configuration.md

@@ -16,6 +16,18 @@ RSMP uses option classes to handle configuration for sites and supervisors. Thes
 
 Each class applies defaults and validates the configuration against a JSON Schema located in `lib/rsmp/options/schemas/`.
 
+Field types and unknown keys are checked before defaults are applied. The `required_settings.json`
+and `required_supervisor_settings.json` schemas then check required settings after defaults and
+supervisor site inheritance are resolved:
+
+- Every configured signal plan must have a `cycle_time`.
+- Configured components must include exactly one `main` component. Sites supply a default main
+  component when omitted; supervisor site settings can inherit it from `default`.
+- A site in `server` role must have a `port`, either explicitly or from its first supervisor endpoint.
+  With `supervisors: []`, the port must be explicit.
+
+`inputs.programming: {}` is allowed and means no programmed input actions.
+
 ## Version strings
 
 Core 3.3.0 and later use exact `MAJOR.MINOR.PATCH` version strings for both Core and SXL negotiation.

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/options/options.rb

@@ -34,7 +34,9 @@ module RSMP
       validate_log_settings! if validate
       config = normalize_config(options || {})
       validate!(config) if validate
-      @data = normalize(apply_defaults(config))
+      config = apply_defaults(config)
+      validate_effective!(config) if validate
+      @data = normalize(config)
     end
 
     def defaults = {}
@@ -56,10 +58,10 @@ module RSMP
       raise RSMP::ConfigurationError, "Invalid log configuration#{source_suffix}:\n#{message}"
     end
 
-    def validate!(data = @data)
-      return unless schema_path && File.exist?(schema_path)
+    def validate!(data = @data, path: schema_path)
+      return unless path && File.exist?(path)
 
-      schemer = JSONSchemer.schema(Pathname.new(schema_path))
+      schemer = JSONSchemer.schema(Pathname.new(path))
       errors = schemer.validate(data).to_a
       return if errors.empty?
 
@@ -86,6 +88,8 @@ module RSMP
 
     private
 
+    def validate_effective!(_config); end
+
     def apply_defaults(options)
       defaults.deep_merge(options)
     end

data/lib/rsmp/options/schemas/required_settings.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$comment": "Validate after applying defaults and inherited site settings; structural validation uses the other config schemas.",
+  "type": "object",
+  "properties": {
+    "components": {
+      "type": "object",
+      "required": ["main"],
+      "properties": {
+        "main": {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 1
+        }
+      }
+    },
+    "signal_plans": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["cycle_time"]
+      }
+    }
+  },
+  "if": {
+    "required": ["connection_role"],
+    "properties": { "connection_role": { "const": "server" } }
+  },
+  "then": { "required": ["port"] }
+}

data/lib/rsmp/options/schemas/required_supervisor_settings.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$comment": "Validate each site after merging supervisor defaults, without changing the stored overrides.",
+  "type": "object",
+  "properties": {
+    "default": { "$ref": "required_settings.json" },
+    "sites": {
+      "type": "object",
+      "additionalProperties": { "$ref": "required_settings.json" }
+    }
+  }
+}

data/lib/rsmp/options/site_options.rb

@@ -23,6 +23,10 @@ module RSMP
 
       private
 
+      def validate_effective!(config)
+        validate!(config, path: File.join(SCHEMAS_PATH, 'required_settings.json'))
+      end
+
       def default_message_buffer
         {
           'max_messages' => 10_000,
@@ -54,7 +58,8 @@ module RSMP
         defaults = defaults()
         defaults['components']['main'] = options['components']['main'] if options.dig('components', 'main')
         data = defaults.deep_merge(options)
-        data['port'] ||= data.dig('supervisors', 0, 'port')
+        port = data.dig('supervisors', 0, 'port')
+        data['port'] ||= port if port
         data
       end
     end

data/lib/rsmp/options/supervisor_options.rb

@@ -28,6 +28,15 @@ module RSMP
       def schema_file
         'supervisor.json'
       end
+
+      private
+
+      def validate_effective!(config)
+        base = config['default'] || {}
+        sites = (config['sites'] || {}).transform_values { |settings| base.deep_merge(settings) }
+        effective = config.merge('sites' => sites)
+        validate!(effective, path: File.join(SCHEMAS_PATH, 'required_supervisor_settings.json'))
+      end
     end
   end
 end

data/lib/rsmp/proxy/modules/acknowledgements.rb

@@ -103,6 +103,8 @@ module RSMP
               component_list_acknowledged
             when 'StatusSubscribe'
               status_subscribe_acknowledged original
+            when 'StatusUnsubscribe'
+              status_unsubscribe_acknowledged original
             end
 
             check_outgoing_acknowledged original

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/proxy/site/modules/status.rb

@@ -3,6 +3,16 @@ module RSMP
     module Modules
       # Handles status requests, responses, subscriptions and updates
       module Status
+        def clear
+          super
+          @pending_status_unsubscriptions = {}
+        end
+
+        def process_not_ack(message)
+          @pending_status_unsubscriptions.delete(message.attribute('oMId'))
+          super
+        end
+
         # Build and send a StatusRequest. Returns Result<StatusRequest>.
         def request_status(status_list, component: nil, m_id: nil, validate: true)
           readiness = validate_ready 'request status'
@@ -75,9 +85,9 @@ module RSMP
           subscribe_list.each do |item|
             code = item['sCI']
             name = item['n']
-            sub = ensure_subscription_path(component_id, code, name)
-            sub['uRt'] = item['uRt']
-            sub['sOc'] = item['sOc']
+            ensure_subscription_path(component_id, code, name)
+            # Replace the record so an older unsubscribe ACK cannot remove it.
+            @status_subscriptions[component_id][code][name] = item.slice('uRt', 'sOc')
           end
         end
 
@@ -147,20 +157,46 @@ module RSMP
         def unsubscribe_to_status(status_list, component: nil, validate: nil)
           component ||= main.c_id
 
-          status_list.each do |item|
-            remove_subscription_item(component, item['sCI'], item['n'])
-          end
-
           # Local subscription state must be cleaned up even when the peer has
           # already disconnected. In that case there is nothing left to send.
-          return Result.success(nil) unless ready?
+          unless ready?
+            status_list.each do |item|
+              remove_subscription_item(component, item['sCI'], item['n'])
+            end
+            return Result.success(nil)
+          end
 
           message = RSMP::StatusUnsubscribe.new({
                                                   'cId' => component,
                                                   'sS' => status_list
                                                 })
           apply_nts_message_attributes message
-          send_message(message, validate: validate).map(&:message)
+          track_status_unsubscribe(message)
+          delivery = send_message(message, validate: validate)
+          delivery.map(&:message)
+        ensure
+          @pending_status_unsubscriptions.delete(message.m_id) if message && !delivery&.success?
+        end
+
+        def track_status_unsubscribe(message)
+          component = message.attribute('cId')
+          @pending_status_unsubscriptions[message.m_id] = message.attribute('sS').map do |item|
+            code = item['sCI']
+            name = item['n']
+            [code, name, @status_subscriptions.dig(component, code, name)]
+          end
+        end
+
+        def status_unsubscribe_acknowledged(original)
+          component = original.attribute('cId')
+          subscriptions = @pending_status_unsubscriptions.delete(original.m_id)
+          return unless subscriptions
+
+          subscriptions.each do |code, name, subscription|
+            next unless @status_subscriptions.dig(component, code, name).equal?(subscription)
+
+            remove_subscription_item(component, code, name)
+          end
         end
 
         def unsubscribe_to_status!(...)

data/lib/rsmp/tlc/modules/inputs.rb

@@ -190,6 +190,8 @@ module RSMP
         end
 
         def programming_hash_to_array(normalized)
+          return [] if normalized.empty?
+
           max_key = normalized.keys.max
           program_array = Array.new(max_key + 1)
           normalized.each do |index, value|

data/lib/rsmp/version.rb

@@ -1,3 +1,3 @@
 module RSMP
-  VERSION = '0.51.3'.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.3
+  version: 0.52.0
 platform: ruby
 authors:
 - Emil Tin
@@ -218,6 +218,8 @@ files:
 - lib/rsmp/options/options.rb
 - lib/rsmp/options/schemas/config_common.json
 - lib/rsmp/options/schemas/log.json
+- lib/rsmp/options/schemas/required_settings.json
+- lib/rsmp/options/schemas/required_supervisor_settings.json
 - lib/rsmp/options/schemas/site.json
 - lib/rsmp/options/schemas/supervisor.json
 - lib/rsmp/options/schemas/supervisor_site.json