rsmp 0.53.3 → 0.54.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c48475e71b559098bd7e9d1f5b7839fff9159a889322c5e93d52be87464d3b7
-  data.tar.gz: 340338647b8e8f5d95fa5d82335596ad5ed2e4b7d45c41b10f75aaf6aed92d54
+  metadata.gz: 634c31243e8753c8e71a0617a3bd9a2747a320fdeb8b78827746095202eb0092
+  data.tar.gz: ff873bb9211175d9577595dabe5e747f47fceb556e584d33f1ee6c1d86db2420
 SHA512:
-  metadata.gz: 496ce34aaca4d14a011a44a02680284be45865ba8c72b9d1961e50f5ff2c708040ccb475ebe968716d5704180f7faa0fb930e750b3caa90c3d296966b6d10170
-  data.tar.gz: 7129e21dc9a85b063edaf793d1ef2bf605205f5c8e0492a83eccd6b3b3c21946c65761696a95fd8579e341e96f679b30b269a5905d1738854fe83339d809a39a
+  metadata.gz: e774cdf65f73e20fa881bc269011afb791c0b695eabdbe2c1aa4c953ad408c2bc5deb21894820829cbde16c9c2448ddd64c685d4bec638d0d049a93e9ac36ad8
+  data.tar.gz: b9eb1b8cd9abedc414236b74749b9ba818619137a95b5edae74fc4881b9299a1fae6f804001858b42dc4ff668d5634aa32261fd44eba7f0e8bc819b4fcf016da

data/CHANGELOG.md

@@ -745,3 +745,18 @@ Initial release.
 ## 0.53.2
 - fix issues with Alarm enum casing
 - update TLC schemas
+
+## 0.53.3
+- prevent possible sxl negotiation race
+
+## 0.54.4
+- accept only the sxl version the supervisor has configured
+- require configured sxl versions to use strick SemVer format major.minor.patch
+
+## Unreleased
+
+- support ordered SXL version lists: sites start with the first version; supervisors accept any listed version
+- add optional testing hints in legacy-only initial Version rejections, allowing sites with version lists to reconnect using an allowed hinted version
+- retain hinted selections per supervisor across reconnects and rejections, while fixed-version sites ignore hints
+- clear subscriptions and buffered messages when switching SXL versions
+- document that hint-based switching is a testing convention outside the RSMP Core specification

data/Gemfile.lock

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

data/README.md

@@ -159,6 +159,12 @@ sxls:
   tlc: '1.3.0'
 ```
 
+Each SXL name has a configured version string or an ordered list of versions in `MAJOR.MINOR.PATCH` form.
+Supervisors accept only matching SXL versions; legacy equipment may use an equivalent spelling such as `1.2` for `1.2.0`.
+On sites, a list starts with its first version and enables [SXL hints for testing](documentation/configuration.md#sxl-hints-for-testing)
+when the handshake offers only Core versions before 3.3.0.
+Hint-based reconnects are a testing convention, not part of the RSMP Core specification.
+
 See [configuration](documentation/configuration.md) for connection-role examples and other YAML settings.
 
 ## Command-line tool

data/documentation/cli.md

@@ -116,7 +116,7 @@ Common options:
 - `--id ID`, `-i ID`: set the site id.
 - `--supervisors LIST`, `-s LIST`: set one or more supervisor endpoints.
 - `--core VERSION`: set the RSMP Core version.
-- `--sxls LIST`: set the SXLs announced by the site as a comma-separated `name:version` list.
+- `--sxls LIST`: set the SXLs announced by the site as a comma-separated `name:version` list, with one `MAJOR.MINOR.PATCH` version per SXL name.
 - `--type tlc`, `-t tlc`: choose the site type. Currently `tlc` is the supported CLI type.
 - `--log PATH`, `-l PATH`: write log output to a file.
 - `--json`, `-j`: include raw JSON messages in the log.
@@ -145,6 +145,19 @@ Use `--sxls` to specify several SXLs for a site:
 $ rsmp site --sxls tlc:1.3.0,vms:1.0.0
 ```
 
+`--sxls` sets one fixed version per SXL name. To enable the optional hint/reconnect testing convention,
+configure ordered version lists in YAML and use `--config` without overriding those SXLs:
+
+```yaml
+core_version: '3.2.2'
+sxls:
+  tlc: ['1.2.1', '1.0.15', '1.2.0']
+```
+
+See [SXL hints for testing](configuration.md#sxl-hints-for-testing). This convention is not part of RSMP Core
+and applies only when the initial handshake offers Core versions before 3.3.0.
+For a supervisor, YAML version lists specify the accepted versions; `--sxls` replaces them with fixed versions.
+
 Example with explicit core and SXL versions:
 
 ```console
@@ -166,7 +179,7 @@ Common options:
 - `--ip ADDRESS`: set the listen address.
 - `--port PORT`, `-p PORT`: set the listen port.
 - `--core VERSION`: override the accepted RSMP Core version.
-- `--sxls LIST`: override SXL versions as a comma-separated `name:version` list.
+- `--sxls LIST`: override supported SXL versions as a comma-separated `name:version` list, with one `MAJOR.MINOR.PATCH` version per SXL name.
 - `--log PATH`, `-l PATH`: write log output to a file.
 - `--json`, `-j`: include raw JSON messages in the log.
 

data/documentation/configuration.md

@@ -37,7 +37,71 @@ Core 3.3.0 and later use exact `MAJOR.MINOR.PATCH` version strings for both Core
 
 Earlier Core versions retain their historical wire formats for compatibility. In particular, the Core 3.2 release may be written as either `3.2` or `3.2.0`. The library resolves both to the `3.2.0` schema internally, but a supervisor responding to a legacy Version message uses the exact Core and SXL strings sent by the site. Ambiguous versions such as `3.1` are rejected because they do not identify one of the supported 3.1.x releases.
 
-Legacy SXL strings such as `1.1` and `1.2` remain supported for connections using a Core version before 3.3.0. Their three-part equivalents are used only for internal schema lookup.
+Configured SXL versions must use `MAJOR.MINOR.PATCH`, for example `sxls: { tlc: '1.2.0' }`.
+Each SXL name maps to a version string or a non-empty, ordered list of distinct version strings.
+Abbreviated versions such as `1.2` and versions with suffixes are rejected in configuration and CLI overrides.
+For connections using a Core version before 3.3.0, equipment may still send legacy SXL strings such as `1.2`.
+The supervisor compares their three-part equivalents against the configured version and uses the original string in its response.
+
+The supervisor rejects a legacy Version message when the offered SXL version
+does not match its effective configuration for that site, even if a schema for the offered version is available.
+For example, with `tlc: '1.2.1'` configured, an offer of `1.0.15` receives `MessageNotAck` and the
+connection closes. Its `rea` field identifies the requested and supported versions.
+Core 3.3.0 uses the SXL response statuses described below.
+
+## SXL hints for testing
+
+**SXL hints and reconnect-based switching are an optional testing convention, not part of the RSMP Core specification.**
+Other equipment is not expected to understand them. Hints apply only to handshakes offering Core versions
+before 3.3.0. Core 3.3.0 uses its standard SXL response statuses.
+
+A site configured with a single version string always uses that version and ignores hints.
+A list enables hint handling for that SXL name:
+
+```yaml
+core_version: '3.2.2'
+sxls:
+  tlc: ['1.2.1', '1.0.15', '1.2.0']
+```
+
+Configure a legacy Core version explicitly. An initial rejection does not identify the selected Core version,
+so hints are ignored if the request offers Core 3.3.0 or later, including mixed-version offers.
+
+The site initially offers the first version, `1.2.1` in this example. It follows a hint only when
+`MessageNotAck.oMId` refers to its outstanding initial Version request, before a Version response has been accepted.
+On rejection, it closes the connection and uses the normal `intervals.reconnect` delay before reconnecting in client role.
+A site in server role waits for the supervisor to reconnect.
+
+The hint is a case-sensitive `hint:` token in `MessageNotAck.rea`. It must start at a word boundary,
+so `thint:` does not count. The value must be a complete version, without extra version parts or suffixes,
+and end at whitespace, a semicolon or the end of the string. For example:
+
+```text
+SXL tlc version 1.2.1 requested, but only 1.0.15 supported; hint: 1.0.15
+```
+
+`hint: 1.0.15` refers to the connection's single legacy `SXL` version. The gem takes this SXL from
+the first entry in its `sxls` configuration. The hinted version must use `MAJOR.MINOR.PATCH` and appear
+in that entry's configured list. Named hints and rejections containing multiple `hint:` tokens are ignored.
+
+The last allowed hinted version is retained across ordinary reconnects and later rejections.
+Missing, malformed or unlisted hints leave it unchanged. Unknown message IDs, rejections of other messages,
+and rejections after Version acceptance cannot change the selection. Creating a new site instance or
+restarting the process restores the first configured version.
+
+Selections are kept separately for each supervisor address and port, without modifying the configuration.
+For sites in server role, selections are keyed by the supervisor's source IP because its source port changes
+on reconnect. When switching versions, the connection's subscriptions and buffered messages are cleared;
+the supervisor must subscribe again after reconnection.
+
+On a supervisor, a version list means that any listed version is supported. A legacy SXL mismatch is rejected
+with a hint for the first version in that list (or the single configured version). A supported offer is accepted
+even if it is not the first entry. All listed versions must have schemas available locally.
+Core 3.3.0 continues to report `mismatch` with a sorted `supported` list; that response does not trigger automatic switching.
+
+For matrix testing, use a separate run with one fixed supervisor version for each matrix entry.
+Wait for a matching handshake before running tests, and serialize runs sharing a physical site.
+A version retained from a previous run will then be rejected with the next run's required version.
 
 ## Core 3.3.0
 

data/lib/rsmp/node/site/site.rb

@@ -65,7 +65,7 @@ module RSMP
       return settings unless sxls.is_a?(Array)
 
       settings.merge(
-        'sxls' => sxls.to_h { |sxl| [sxl['name'], sxl['version']] }
+        'sxls' => sxls.to_h { |sxl| [sxl['name'], sxl['versions'] || sxl['version']] }
       )
     end
 
@@ -74,13 +74,19 @@ module RSMP
 
       sxls.each do |sxl|
         name = sxl['name']
-        version = sxl['version'].to_s
         raise RSMP::ConfigurationError, 'SXL name cannot be core' if name.to_s == 'core'
 
-        RSMP::Schema.find_schema! name, version, lenient: true
+        (sxl['versions'] || [sxl['version']]).each { |version| RSMP::Schema.find_schema! name, version }
       end
     end
 
+    # Keep testing selections separate from configuration and scoped to the peer.
+    # Incoming connections have changing source ports, so server sites use the IP.
+    def hinted_sxl_versions(ip, port)
+      @hinted_sxl_versions ||= {}
+      @hinted_sxl_versions[[ip, server_role? ? nil : port]] ||= {}
+    end
+
     def check_core_versions
       version = @site_settings['core_version']
       return unless version

data/lib/rsmp/node/supervisor/modules/configuration.rb

@@ -25,7 +25,7 @@ module RSMP
           return settings unless sxls.is_a?(Array)
 
           settings.merge(
-            'sxls' => sxls.to_h { |sxl| [sxl['name'], sxl['version']] }
+            'sxls' => sxls.to_h { |sxl| [sxl['name'], sxl['versions'] || sxl['version']] }
           )
         end
 
@@ -52,7 +52,7 @@ module RSMP
                     "Configuration error for site '#{site_id}': SXL name cannot be core"
             end
 
-            RSMP::Schema.find_schema! name, sxl['version'], lenient: true
+            (sxl['versions'] || [sxl['version']]).each { |version| RSMP::Schema.find_schema! name, version }
           end
         end
 

data/lib/rsmp/options/options.rb

@@ -1,9 +1,12 @@
 require 'yaml'
 require 'pathname'
+require_relative 'sxl_options'
 
 module RSMP
   # Base class for configuration options.
   class Options
+    include SxlOptions
+
     SCHEMAS_PATH = File.expand_path('schemas', __dir__)
 
     attr_reader :data, :log_settings, :source
@@ -108,19 +111,6 @@ module RSMP
       end
     end
 
-    def normalize_sxls(value)
-      case value
-      when Hash
-        value.map do |name, details|
-          normalize_sxl_item(name.to_s, details)
-        end
-      when Array
-        value.map { |item| normalize(item) }
-      else
-        value
-      end
-    end
-
     def normalize_config(value)
       case value
       when Hash
@@ -135,27 +125,6 @@ module RSMP
       end
     end
 
-    def normalize_config_sxls(value)
-      raise RSMP::ConfigurationError, 'sxls must be a hash of SXL names to versions' unless value.is_a?(Hash)
-
-      value.each_with_object({}) do |(name, details), memo|
-        raise RSMP::ConfigurationError, "sxls/#{name} must be a version string" if details.is_a?(Hash)
-
-        memo[name.to_s] = details.to_s
-      end
-    end
-
-    def normalize_sxl_item(name, details)
-      case details
-      when Hash
-        raise RSMP::ConfigurationError, "sxls/#{name} must be a version string"
-      when nil
-        { 'name' => name }
-      else
-        { 'name' => name, 'version' => details.to_s }
-      end
-    end
-
     def format_error(error)
       pointer = error_pointer(error)
       details = error_details(error)

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

@@ -2,6 +2,17 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "config_common.json",
   "$defs": {
+    "sxl_versions": {
+      "oneOf": [
+        { "type": "string" },
+        {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$" }
+        }
+      ]
+    },
     "endpoint": {
       "type": "object",
       "properties": {

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

@@ -15,7 +15,7 @@
     "sxls": {
       "type": "object",
       "propertyNames": { "not": { "const": "core" } },
-      "additionalProperties": { "type": "string" }
+      "additionalProperties": { "$ref": "config_common.json#/$defs/sxl_versions" }
     },
     "core_version": { "type": "string" },
     "intervals": { "$ref": "config_common.json#/$defs/intervals" },

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

@@ -6,7 +6,7 @@
     "sxls": {
       "type": "object",
       "propertyNames": { "not": { "const": "core" } },
-      "additionalProperties": { "type": "string" }
+      "additionalProperties": { "$ref": "config_common.json#/$defs/sxl_versions" }
     },
     "core_version": { "type": "string" },
     "rsmp_versions": {

data/lib/rsmp/options/sxl_options.rb

@@ -0,0 +1,56 @@
+module RSMP
+  # Configuration and internal representation of supported SXL versions.
+  module SxlOptions
+    private
+
+    def normalize_sxls(value)
+      case value
+      when Hash
+        value.map do |name, details|
+          normalize_sxl_item(name.to_s, details)
+        end
+      when Array
+        value.map { |item| normalize(item) }
+      else
+        value
+      end
+    end
+
+    def normalize_config_sxls(value)
+      raise RSMP::ConfigurationError, 'sxls must be a hash of SXL names to versions' unless value.is_a?(Hash)
+
+      value.each_with_object({}) do |(name, details), memo|
+        validate_sxl_versions!(name, details)
+        memo[name.to_s] = details
+      end
+    end
+
+    def validate_sxl_versions!(name, details)
+      versions = details.is_a?(Array) ? details : [details]
+      if versions.empty? || versions.any? { |version| !version.is_a?(String) }
+        raise RSMP::ConfigurationError, "sxls/#{name} must be a version string or a non-empty list of version strings"
+      end
+
+      valid = versions.all? do |version|
+        RSMP::Schema.strict_version?(version) || (details.is_a?(String) && version == 'latest')
+      end
+      raise RSMP::ConfigurationError, "sxls/#{name} must use MAJOR.MINOR.PATCH" unless valid
+      return if versions.uniq == versions
+
+      raise RSMP::ConfigurationError, "sxls/#{name} must not contain duplicate versions"
+    end
+
+    def normalize_sxl_item(name, details)
+      case details
+      when Array
+        { 'name' => name, 'version' => details.first, 'versions' => details.dup }
+      when Hash
+        raise RSMP::ConfigurationError, "sxls/#{name} must be a version string"
+      when nil
+        { 'name' => name }
+      else
+        { 'name' => name, 'version' => details.to_s }
+      end
+    end
+  end
+end

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

@@ -45,7 +45,7 @@ module RSMP
 
         def sxl_request_items
           configured_sxls.map do |sxl|
-            version = RSMP::Schema.sanitize_version(sxl['version'].to_s)
+            version = sxl['version']
             item = { 'name' => sxl['name'], 'version' => version }
             prefix = RSMP::Schema.sxl_prefix(sxl['name'], version)
             item['prefix'] = prefix if prefix
@@ -120,7 +120,9 @@ module RSMP
             attributes.merge!(version_request_attributes)
             attributes['SXL'] = legacy_sxl unless @offered_core_versions.include?('3.3.0')
           end
-          send_generated_message Version.new(attributes), validate: false
+          message = Version.new(attributes)
+          @initial_version_request_id = message.m_id if step == 'Request'
+          send_generated_message message, validate: false
         end
 
         def version_message_attributes(site_id, core_versions)

data/lib/rsmp/proxy/proxy.rb

@@ -77,6 +77,7 @@ module RSMP
       @latest_watchdog_received = nil
       @watchdog_started = false
       @version_determined = false
+      @initial_version_request_id = nil
       @ingoing_acknowledged = {}
       @outgoing_acknowledged = {}
       @latest_watchdog_send_at = nil

data/lib/rsmp/proxy/site/sxl_selection.rb

@@ -14,13 +14,15 @@ module RSMP
 
     def select_legacy_sxl(message)
       primary = configured_sxls.first
-      unless primary
-        reason = 'Legacy Version message received, but no SXL is configured'
-        dont_acknowledge message, "Rejected #{message.type} message,", reason
-        raise HandshakeError, reason
-      end
+      raise HandshakeError, 'Legacy Version message received, but no SXL is configured' unless primary
 
       sanitized_version = RSMP::Schema.sanitize_version(message.attribute('SXL'))
+      versions = primary['versions'] || [primary['version']]
+      unless versions.include?(sanitized_version)
+        raise HandshakeError,
+              "SXL #{primary['name']} version #{message.attribute('SXL')} requested, " \
+              "but only #{versions.join(', ')} supported; hint: #{versions.first}"
+      end
       RSMP::Schema.find_schema! primary['name'], sanitized_version
       @accepted_sxls = [{ 'name' => primary['name'], 'version' => message.attribute('SXL') }]
       @rejected_sxls = []
@@ -39,12 +41,14 @@ module RSMP
       configured = configured_sxls.find { |item| item['name'] == requested['name'] }
       return { 'name' => requested['name'], 'status' => 'unsupported' } unless configured
 
-      version = RSMP::Schema.sanitize_version(configured['version'].to_s)
-      if version == requested['version']
+      versions = configured['versions'] || [configured['version']]
+      version = requested['version']
+      if versions.include?(version)
         RSMP::Schema.find_schema! requested['name'], version
         { 'name' => requested['name'], 'status' => 'ok', 'version' => version }
       else
-        { 'name' => requested['name'], 'status' => 'mismatch', 'supported' => [version] }
+        { 'name' => requested['name'], 'status' => 'mismatch',
+          'supported' => versions.sort_by { |item| Gem::Version.new(item) } }
       end
     end
   end

data/lib/rsmp/proxy/supervisor/modules/sxl_hints.rb

@@ -0,0 +1,60 @@
+module RSMP
+  class SupervisorProxy < Proxy
+    module Modules
+      # Optional testing convention, not RSMP Core SXL negotiation.
+      module SxlHints
+        def start_handshake
+          @sxls = configured_sxls
+          @accepted_sxls = @sxls.dup
+          @rejected_sxls = []
+          send_version_request @site_settings['site_id'], advertised_core_versions
+        end
+
+        def configured_sxls
+          selections = @site.hinted_sxl_versions(@ip, @port)
+          super.map do |item|
+            version = selections[item['name']]
+            item['versions']&.include?(version) ? item.merge('version' => version) : item
+          end
+        end
+
+        def process_not_ack(message)
+          original = find_original_for_message(message)
+          initial = original.is_a?(Version) && original.m_id == @initial_version_request_id && !@version_determined
+          super
+          return unless initial
+
+          legacy = original.versions.all? { |version| version_meets_requirement?(version, '<3.3.0') }
+          apply_sxl_hint(message.attributes['rea']) if legacy
+          close(reason: :version_rejected)
+        end
+
+        def apply_sxl_hint(reason)
+          version = parse_sxl_hint(reason)
+          return unless version
+
+          configured = primary_configured_sxl
+          return unless configured && configured['versions']&.include?(version)
+          return if configured['version'] == version
+
+          name = configured['name']
+          @site.hinted_sxl_versions(@ip, @port)[name] = version
+          # Subscriptions and queued messages belong to the previous SXL version.
+          @status_subscriptions.clear
+          @message_buffer.clear
+          log "Following testing SXL hint: #{name} #{version} on next connection", level: :info
+        end
+
+        def parse_sxl_hint(reason)
+          return unless reason.is_a?(String)
+
+          hints = reason.scan(/\bhint:\s*([^\s;]+)/).flatten
+          return unless hints.size == 1
+
+          version = hints.first
+          version if RSMP::Schema.strict_version?(version)
+        end
+      end
+    end
+  end
+end

data/lib/rsmp/proxy/supervisor/supervisor_proxy.rb

@@ -1,4 +1,5 @@
 require 'digest'
+require_relative 'modules/sxl_hints'
 
 module RSMP
   # Proxy used by sites to connect to a remote supervisor.
@@ -8,6 +9,7 @@ module RSMP
     include Modules::Alarms
     include Modules::AggregatedStatus
     include Modules::MessageBuffer
+    include Modules::SxlHints
 
     attr_reader :supervisor_id, :site, :message_buffer
 
@@ -62,10 +64,6 @@ module RSMP
       close
     end
 
-    def start_handshake
-      send_version_request @site_settings['site_id'], advertised_core_versions
-    end
-
     def close(...)
       prune_unbuffered_status_subscriptions
       super

data/lib/rsmp/version.rb

@@ -1,3 +1,3 @@
 module RSMP
-  VERSION = '0.53.3'.freeze
+  VERSION = '0.54.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rsmp
 version: !ruby/object:Gem::Version
-  version: 0.53.3
+  version: 0.54.0
 platform: ruby
 authors:
 - Emil Tin
@@ -227,6 +227,7 @@ files:
 - lib/rsmp/options/schemas/traffic_controller_site.json
 - lib/rsmp/options/site_options.rb
 - lib/rsmp/options/supervisor_options.rb
+- lib/rsmp/options/sxl_options.rb
 - lib/rsmp/options/traffic_controller_site_options.rb
 - lib/rsmp/proxy/modules/acknowledgements.rb
 - lib/rsmp/proxy/modules/lifecycle.rb
@@ -251,6 +252,7 @@ files:
 - lib/rsmp/proxy/supervisor/modules/message_buffer.rb
 - lib/rsmp/proxy/supervisor/modules/status.rb
 - lib/rsmp/proxy/supervisor/modules/status_updates.rb
+- lib/rsmp/proxy/supervisor/modules/sxl_hints.rb
 - lib/rsmp/proxy/supervisor/supervisor_proxy.rb
 - lib/rsmp/result.rb
 - lib/rsmp/schema.rb