rsmp 0.46.0 → 0.48.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5a5d66114ac44b96bc823b0366eddc9225abeb1686ec75cdd60d25373c8e53b
-  data.tar.gz: 49387a2b58f4aa7cfd0e36226240cbb1e93d2f49e5fd5636eb9cf3cabd0e3b53
+  metadata.gz: 24b3e3fbb36a769054061eeb10f070096ec576468f20196932d43d1e4c3915c7
+  data.tar.gz: 3b6830d24f1225b721e21680b35c71c8dc508eb5bd6d684c595c71256c207ea0
 SHA512:
-  metadata.gz: f0cf699c114f7c61b03e42e199ecddee74270bb6a3fabe980c95f89951e7edc557cebc9b7c3eb1668614dc73a2c69a6c849be3010c6cdcb3210459a506ca04ef
-  data.tar.gz: 7b53bd11a26ad80c150862fbd28fe98b6a9fb0be238a613e2500ac0ffb439c34188b10f962f120c54fa491a371db05688a98d0f9ca27549eb9658a498f1d2d2a
+  metadata.gz: 1208ed7baf84741848f268c28a66d5410afdd172f8fd1f1010280816d8f16cc184870b3f979fcaa6e566f5746fd164608504a9bc00c9447f36bdfac77b457f34
+  data.tar.gz: b5c71f21c3369585b7740d85669a9fd4b3ebb030697984faeceb43f280fe9f6d86f6f78b3a005f0c133ceee50daef748868f6206c380726beb883fdfdbb1f295

data/.github/workflows/copilot-setup-steps.yml

@@ -26,7 +26,7 @@ jobs:
     # If you do not check out your code, Copilot will do this for you.
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - uses: ruby/setup-ruby@v1
         with:

data/.github/workflows/rubocop.yaml

@@ -9,7 +9,7 @@ jobs:
       fail-fast: false
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - uses: ruby/setup-ruby@v1
       with:
         bundler-cache: true

data/.github/workflows/sus.yaml

@@ -11,7 +11,7 @@ jobs:
         os: [ubuntu-latest, macos-latest, windows-latest]
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - uses: ruby/setup-ruby@v1
       with:
         ruby-version: 4.0

data/CHANGELOG.md

@@ -685,3 +685,17 @@ Initial release.
 
 ## 0.46.0
 - add outgoing message buffering for sites
+
+## 0.47.0
+- add cli command for checking configs
+- tighten config schemas
+
+## 0.48.0
+- implement RSMP Core 3.3.0 connection roles, allowing a site to listen and a supervisor to connect
+- enforce 3.3.0 command message rules, including one command code per CommandRequest/CommandResponse
+- update TLC schemas with JSON-native values and required/optional command arguments
+- add argument types to SXL indexes
+- encode/decode message values based on SXL type defintions
+- return `unknown` for unimplemented commands and statuses instead of rejecting the whole request
+- omit legacy NTS message attributes from outgoing Core 3.3.0 messages
+-  `CORE_VERSION` or `SXLS` environment variables with command line options `--core` and `--sxls`

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rsmp (0.46.0)
+    rsmp (0.48.0)
       async (~> 2.39)
       colorize (~> 1.1)
       io-endpoint (~> 0.17)
@@ -15,7 +15,7 @@ GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
-    async (2.39.0)
+    async (2.40.0)
       console (~> 1.29)
       fiber-annotation
       io-event (~> 1.11)
@@ -33,9 +33,9 @@ GEM
     fiber-storage (1.0.1)
     hana (1.3.7)
     io-endpoint (0.17.2)
-    io-event (1.16.1)
-    io-stream (0.13.0)
-    json (2.19.9)
+    io-event (1.16.4)
+    io-stream (0.13.1)
+    json (2.20.0)
     json_schemer (2.5.0)
       bigdecimal
       hana (~> 1.3)

data/README.md

@@ -28,7 +28,7 @@ require 'rsmp'
 RSMP::Supervisor.new.start  		# run supervisor until Ctlr-C is pressed
 ```
 
-Be default, a site will try to connect to a single supervisor on localhost 127.0.0.1, port 12111. By default, a supervisor will listen for sites on port 12111 and accept any site.
+By default, a site will try to connect to a single supervisor on localhost 127.0.0.1, port 12111. By default, a supervisor will listen for sites on port 12111 and accept any site.
 
 You can pass options to control ip adresseses, ports, logging and other behaviour:
 
@@ -144,6 +144,8 @@ sxls:
   tlc: '1.3.0'
 ```
 
+See [configuration](documentation/configuration.md) for connection-role examples and other YAML settings.
+
 ## Command-line tool
 Tools for easily running RSMP supervisors and sites. The binary is called ```rsmp```.
 

data/documentation/cli.md

@@ -0,0 +1,225 @@
+# RSMP CLI
+
+The `rsmp` command can run a site, run a supervisor, validate config files, generate JSON Schemas from an SXL, and print the gem version.
+
+Use help at any level:
+
+```console
+$ rsmp help
+$ rsmp help site
+$ rsmp help supervisor
+$ rsmp help config check
+$ rsmp help schema generate
+```
+
+## Quick Examples
+
+Run a TLC site that connects to the default supervisor endpoint, `127.0.0.1:12111`:
+
+```console
+$ rsmp site
+```
+
+Run a supervisor that listens on the default port, `12111`:
+
+```console
+$ rsmp supervisor
+```
+
+Run both with explicit config files:
+
+```console
+$ rsmp supervisor --config config/supervisor.yaml
+$ rsmp site --config config/tlc.yaml
+```
+
+Run a site against a specific supervisor endpoint:
+
+```console
+$ rsmp site --supervisors 192.0.2.10:12111
+```
+
+Show raw JSON messages in the log:
+
+```console
+$ rsmp site --json
+$ rsmp supervisor --json
+```
+
+Write logs to a file:
+
+```console
+$ rsmp supervisor --log log/supervisor.log
+$ rsmp site --log log/site.log
+```
+
+Validate config files before starting anything:
+
+```console
+$ rsmp config check config/tlc.yaml --type tlc
+$ rsmp config check config/supervisor.yaml --type supervisor
+```
+
+Generate JSON Schema files from an SXL YAML file:
+
+```console
+$ rsmp schema generate --in schemas/tlc/1.3.0/sxl.yaml --out /tmp/tlc-schema
+```
+
+## Configuration Files
+
+Most real runs should use YAML config files. The CLI accepts `--config`, `-c`, and `--options` as aliases:
+
+```console
+$ rsmp site -c config/tlc.yaml
+$ rsmp supervisor --options config/supervisor.yaml
+```
+
+CLI options override or add to settings loaded from the config file. For example, this loads `config/tlc.yaml` but changes the site id and supervisor endpoint for this run:
+
+```console
+$ rsmp site -c config/tlc.yaml --id RN+SI0420 --supervisors 127.0.0.1:13111
+```
+
+Core and SXL version overrides are command-line options.
+
+See `documentation/configuration.md` for the YAML format.
+
+## Commands
+
+### `rsmp site`
+
+Runs an RSMP site. The default site type is `tlc`, so this starts a TLC traffic controller site implementation.
+
+```console
+$ rsmp site
+```
+
+Common options:
+
+- `--config PATH`, `-c PATH`, `--options PATH`: load site settings from a YAML file.
+- `--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.
+- `--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.
+
+The `--supervisors` option accepts a comma-separated list:
+
+```console
+$ rsmp site --supervisors 127.0.0.1:12111,192.0.2.10:12111
+```
+
+If the IP address is omitted, `127.0.0.1` is used:
+
+```console
+$ rsmp site --supervisors :13111
+```
+
+If the port is omitted, the configured site default is used:
+
+```console
+$ rsmp site --supervisors 127.0.0.1
+```
+
+Use `--sxls` to specify several SXLs for a site:
+
+```console
+$ rsmp site --sxls tlc:1.3.0,vms:1.0.0
+```
+
+Example with explicit core and SXL versions:
+
+```console
+$ rsmp site -c config/tlc.yaml --core 3.3.0 --sxls tlc:1.3.0
+```
+
+### `rsmp supervisor`
+
+Runs an RSMP supervisor. By default it listens for site connections on port `12111`.
+
+```console
+$ rsmp supervisor
+```
+
+Common options:
+
+- `--config PATH`, `-c PATH`, `--options PATH`: load supervisor settings from a YAML file.
+- `--id ID`, `-i ID`: set the supervisor site id.
+- `--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.
+- `--log PATH`, `-l PATH`: write log output to a file.
+- `--json`, `-j`: include raw JSON messages in the log.
+
+Example:
+
+```console
+$ rsmp supervisor --ip 0.0.0.0 --port 13111 --core 3.3.0 --sxls tlc:1.3.0 --json
+```
+
+When `--core` or `--sxls` is used with the supervisor command, it overrides `default` and any configured `sites` entries for that run.
+
+### `rsmp config check`
+
+Validates one or more YAML config files without starting a site or supervisor.
+
+```console
+$ rsmp config check config/tlc.yaml
+$ rsmp config check config/tlc.yaml config/supervisor.yaml
+```
+
+Options:
+
+- `--type TYPE`, `-t TYPE`: choose the config type. Supported values are `auto`, `site`, `tlc`, and `supervisor`.
+
+The default type is `auto`. Auto-detection works when the config shape is clear. If the CLI cannot infer the type, pass `--type` explicitly:
+
+```console
+$ rsmp config check config/tlc.yaml --type tlc
+$ rsmp config check config/supervisor.yaml --type supervisor
+```
+
+Successful validation prints `OK` for each valid file. Invalid files print an error and the command exits with status `1`.
+
+Common validation errors include:
+
+- The file does not exist.
+- The path is a directory.
+- The file is not YAML.
+- A setting has the wrong type.
+- A config key is not allowed by the schema.
+
+### `rsmp schema generate`
+
+Generates JSON Schema files from an `sxl.yaml` file.
+
+```console
+$ rsmp schema generate --in schemas/tlc/1.3.0/sxl.yaml --out /tmp/tlc-schema
+```
+
+Options:
+
+- `--in PATH`, `-i PATH`: path to the input `sxl.yaml`. Defaults to `sxl.yaml`.
+- `--out PATH`, `-o PATH`: output directory. Defaults to the current directory.
+
+The command writes the generated status, command, alarm, root schema, definitions, and `sxl_index.json` files to the output directory.
+
+If the input file is missing, the command prints an error and exits with status `1`.
+
+### `rsmp version`
+
+Prints the installed `rsmp` gem version:
+
+```console
+$ rsmp version
+```
+
+## Exit Status
+
+Commands return status `0` on success. Validation and argument errors return a non-zero status.
+
+Long-running commands such as `rsmp site` and `rsmp supervisor` run until interrupted or until startup fails.

data/documentation/configuration.md

@@ -38,6 +38,7 @@ Both `--config` and `--options` are accepted as aliases.
 
 ```yaml
 site_id: RN+SI0001
+connection_role: client
 supervisors:
   - ip: 127.0.0.1
     port: 12111
@@ -46,14 +47,60 @@ sxls:
 components:
   main:
     TC:
+message_buffer:
+  max_messages: 10000
+  statuses: true
 log:
   json: true
 ```
 
+`connection_role` controls which side opens the TCP connection:
+
+- `client` means the node connects to configured remote endpoints.
+- `server` means the node listens for incoming connections.
+
+Configurable connection roles are available from Core 3.3.0.
+
+For sites, `client` is the default and uses the `supervisors` endpoint list. A site in `server` role listens on `ip` and `port` instead.
+
+```yaml
+site_id: RN+SI0001
+connection_role: server
+ip: 0.0.0.0
+port: 12111
+core_version: "3.3.0"
+sxls:
+  tlc: "1.3.0"
+```
+
+## Message Buffer
+
+Sites buffer outgoing alarm and aggregated status messages while a supervisor connection is down. Status updates are buffered according to `message_buffer.statuses`, which defaults to `true`.
+
+```yaml
+message_buffer:
+  max_messages: 10000
+  statuses: true
+```
+
+`statuses: true` buffers all subscribed status updates during communication disruption. To buffer only selected statuses, provide selectors:
+
+```yaml
+message_buffer:
+  statuses:
+    - sCI: S0001
+      n: signalgroupstatus
+```
+
+Use `statuses: false` or an empty list to avoid buffering status updates. Subscriptions for statuses that are not buffered are removed when the connection is lost.
+
+The current implementation uses an in-memory buffer per supervisor connection. Buffered messages survive reconnects while the process keeps running, but are lost if the process exits, crashes, or the host loses power. The RSMP core specification requires the outgoing communication buffer to survive communication failure and power outage, so this is not yet a complete persistent buffer implementation.
+
 ## Example: supervisor YAML
 
 ```yaml
 port: 12111
+connection_role: server
 default:
   sxls:
     tlc: "1.3.0"
@@ -79,6 +126,22 @@ sites:
 
 Per-site configuration follows the supervisor-side site schema (`lib/rsmp/options/schemas/supervisor_site.json`). Each site entry can define an `sxls` map, or inherit it from `default`. The SXL name `core` is reserved for the RSMP core schema and cannot be used as an SXL key.
 
+For supervisors, `server` is the default and listens on `ip`/`port`. A supervisor in `client` role connects out to the endpoints listed under each configured site. The outbound endpoint list uses the existing `supervisors` key in the per-site settings:
+
+```yaml
+connection_role: client
+sites:
+  RN+SI0001:
+    core_version: "3.3.0"
+    sxls:
+      tlc: "1.3.0"
+    supervisors:
+      - ip: 127.0.0.1
+        port: 12111
+```
+
+This reversed setup is used when the site listens and the supervision system initiates the connection.
+
 ## Supervisor settings
 
 The following lists the top-level supervisor settings and the keys available for per-site configuration under `sites`.
@@ -87,6 +150,7 @@ Top-level supervisor settings
 
 - `port`: integer|string - TCP port the supervisor listens on (default: `12111`).
 - `ip`: string - address to bind to.
+- `connection_role`: string - `server` to listen for sites, or `client` to connect to configured site endpoints (default: `server`).
 - `ips`: string or array - `'all'` or a list of allowed IP addresses.
 - `site_id`: string - optional site identifier for the supervisor itself.
 - `max_sites`: integer - limit concurrent connected sites.
@@ -119,6 +183,25 @@ Common per-site keys
 - `skip_validation` (array[string]): list of message types to skip JSON schema validation for this site.
 - `security_codes` (object): map of security code levels to secrets.
 
+## Site settings
+
+The following lists the top-level site settings.
+
+- `site_id` (string): site identifier sent in the Version message.
+- `type` (string): optional site type.
+- `connection_role` (string): `client` to connect to supervisors, or `server` to listen for supervisor connections (default: `client`).
+- `ip` (string): bind address when `connection_role` is `server` (default: `0.0.0.0`).
+- `port` (integer|string): listen port when `connection_role` is `server`. If omitted, it defaults to the first configured supervisor port.
+- `supervisors` (array): supervisor endpoints used when `connection_role` is `client`.
+- `sxls` (object): SXL versions used by the site, keyed by SXL name.
+- `core_version` (string): RSMP Core version to use.
+- `intervals` (object): timer settings - `timer`, `watchdog`, `reconnect`.
+- `timeouts` (object): timeout settings - `watchdog`, `acknowledgement`.
+- `send_after_connect` (boolean): whether to send messages after connect without waiting for additional events.
+- `message_buffer` (object): outgoing message buffer settings.
+- `components` (object): component definitions.
+- `security_codes` (object): map of security code levels to secrets.
+
 ### TLC-specific settings
 
 TLC-specific settings are used when a site uses the `tlc` SXL and include:

data/lib/rsmp/cli/configuration.rb

@@ -0,0 +1,30 @@
+module RSMP
+  class CLI < Thor
+    # Private helpers for loading CLI configuration files.
+    module Configuration
+      private
+
+      def load_site_configuration
+        load_configuration(site_options_class)
+      end
+
+      def load_supervisor_configuration
+        load_configuration(RSMP::Supervisor::Options)
+      end
+
+      def load_configuration(options_class)
+        settings = {}
+        log_settings = { 'active' => true }
+        return [settings, log_settings] unless options[:config]
+
+        options_object = options_class.load_file(options[:config])
+        settings = options_object.to_h
+        log_settings = log_settings.deep_merge(options_object.log_settings)
+        [settings, log_settings]
+      rescue RSMP::ConfigurationError => e
+        puts "Error: #{e}"
+        exit
+      end
+    end
+  end
+end

data/lib/rsmp/cli.rb

@@ -1,5 +1,6 @@
 require 'thor'
 require_relative '../rsmp'
+require_relative 'cli/configuration'
 
 module RSMP
   # CLI subcommands for SXL schema operations.
@@ -20,8 +21,36 @@ module RSMP
     end
   end
 
+  # CLI subcommands for RSMP configuration validation.
+  class ConfigCLI < Thor
+    namespace :config
+    desc 'check PATH...', 'Validate RSMP site or supervisor config files'
+    method_option :type, type: :string, aliases: '-t', default: 'auto',
+                         enum: ['auto'] + RSMP::Config.types,
+                         banner: 'Config type: auto, site, tlc or supervisor'
+    def check(*paths)
+      if paths.empty?
+        puts 'Error: config check requires at least one path'
+        exit 1
+      end
+
+      valid = true
+      paths.each do |path|
+        RSMP::Config.load_file(path, type: options[:type])
+        puts 'OK'
+      rescue RSMP::ConfigurationError => e
+        valid = false
+        puts "Error: #{e.message}"
+      end
+
+      exit 1 unless valid
+    end
+  end
+
   # CLI commands for running RSMP site and supervisor.
   class CLI < Thor
+    include Configuration
+
     desc 'version', 'Show version'
     def version
       puts RSMP::VERSION
@@ -33,6 +62,7 @@ module RSMP
     method_option :supervisors, type: :string, aliases: '-s',
                                 banner: 'ip:port,... list of supervisor to connect to'
     method_option :core, type: :string, banner: "Core version: [#{RSMP::Schema.core_versions.join(' ')}]", enum: RSMP::Schema.core_versions
+    method_option :sxls, type: :string, banner: 'SXL versions as name:version,...'
     method_option :type, type: :string, aliases: '-t', banner: 'Type of site: [tlc]', enum: ['tlc'],
                          default: 'tlc'
     method_option :log, type: :string, aliases: '-l', banner: 'Path to log file'
@@ -58,6 +88,7 @@ module RSMP
     method_option :ip, type: :string, banner: 'IP address to listen on'
     method_option :port, type: :string, aliases: '-p', banner: 'Port to listen on'
     method_option :core, type: :string, banner: "Core version: [#{RSMP::Schema.core_versions.join(' ')}]", enum: RSMP::Schema.core_versions
+    method_option :sxls, type: :string, banner: 'Default SXL versions as name:version,...'
     method_option :log, type: :string, aliases: '-l', banner: 'Path to log file'
     method_option :json, type: :boolean, aliases: '-j', banner: 'Show JSON messages in log'
     def supervisor
@@ -69,26 +100,7 @@ module RSMP
     end
 
     register SchemaCLI, 'schema', 'schema COMMAND', 'SXL schema commands'
-
-    no_commands do
-      def load_site_configuration
-        settings = {}
-        log_settings = { 'active' => true }
-
-        return [settings, log_settings] unless options[:config]
-
-        begin
-          options_object = site_options_class.load_file(options[:config])
-          settings = options_object.to_h
-          log_settings = log_settings.deep_merge(options_object.log_settings)
-        rescue RSMP::ConfigurationError => e
-          puts "Error: #{e}"
-          exit
-        end
-
-        [settings, log_settings]
-      end
-    end
+    register ConfigCLI, 'config', 'config COMMAND', 'Configuration commands'
 
     private
 
@@ -109,8 +121,8 @@ module RSMP
 
     def apply_basic_site_options(settings)
       settings['site_id'] = options[:id] if options[:id]
-      settings['core_version'] = options[:core] || ENV['CORE_VERSION'] if options[:core] || ENV['CORE_VERSION']
-      settings['sxls'] = parse_sxls(ENV['SXLS']) if ENV['SXLS']
+      settings['core_version'] = options[:core] if options[:core]
+      settings['sxls'] = parse_sxls(options[:sxls]) if options[:sxls]
     end
 
     def parse_sxls(value)
@@ -196,27 +208,9 @@ module RSMP
       end
     end
 
-    def load_supervisor_configuration
-      settings = {}
-      log_settings = { 'active' => true }
-
-      return [settings, log_settings] unless options[:config]
-
-      begin
-        options_object = RSMP::Supervisor::Options.load_file(options[:config])
-        settings = options_object.to_h
-        log_settings = log_settings.deep_merge(options_object.log_settings)
-      rescue RSMP::ConfigurationError => e
-        puts "Error: #{e}"
-        exit
-      end
-
-      [settings, log_settings]
-    end
-
     def apply_supervisor_options(settings, log_settings)
       apply_basic_supervisor_options(settings)
-      apply_core_version_option(settings)
+      apply_version_options(settings)
       apply_log_options(log_settings)
     end
 
@@ -226,11 +220,17 @@ module RSMP
       settings['port'] = options[:port] if options[:port]
     end
 
-    def apply_core_version_option(settings)
-      return unless options[:core]
+    def apply_version_options(settings)
+      return unless options[:core] || options[:sxls]
+
+      sxls = parse_sxls(options[:sxls]) if options[:sxls]
+      apply_version_overrides(settings['default'] ||= {}, sxls)
+      (settings['sites'] || {}).each_value { |site_settings| apply_version_overrides(site_settings, sxls) }
+    end
 
-      settings['default'] ||= {}
-      settings['default']['core_version'] = options[:core]
+    def apply_version_overrides(settings, sxls)
+      settings['core_version'] = options[:core] if options[:core]
+      settings['sxls'] = sxls if sxls
     end
 
     def apply_log_options(log_settings)

data/lib/rsmp/collect/command_matcher.rb

@@ -9,16 +9,25 @@ module RSMP
     end
 
     def match_value?(item)
-      return true unless @want['v']
+      return true unless @want.key?('v')
 
-      if @want['v'].is_a? Regexp
-        return false if item['v'] !~ @want['v']
-      elsif item['v'] != @want['v']
+      want = @want['v']
+      got = item['v']
+      if want.is_a? Regexp
+        return false unless regex_match?(got, want)
+      elsif got != want
         return false
       end
       true
     end
 
+    def regex_match?(got, want)
+      return got =~ want if got.is_a?(String)
+      return got.any? { |item| item.is_a?(String) && item =~ want } if got.is_a?(Array)
+
+      false
+    end
+
     def match(item)
       code_match = match_code(item)
       return code_match if code_match.nil?