rsmp 0.47.0 → 0.48.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c206e0c53de4f523b03832b8821b698ea0f0440c11cdb51f5685382f4bdaebf5
-  data.tar.gz: 2b35690dbe819d58cf76fe82faf1baec3392e6ecf54fbcd71b0e15c4fd7b7887
+  metadata.gz: 24b3e3fbb36a769054061eeb10f070096ec576468f20196932d43d1e4c3915c7
+  data.tar.gz: 3b6830d24f1225b721e21680b35c71c8dc508eb5bd6d684c595c71256c207ea0
 SHA512:
-  metadata.gz: 4e7c84bc1a7c35f5f58108db5803cc8f0a9abe58ab9edc83a09d778d62479bcc1e0310eb2af9c0e9fe1cad75bf187303ba0d8759ff8b793dd15ae1abe118bcfe
-  data.tar.gz: 562f88737283e91ab232c68c70344c9f668e5d08b0aa488b24ac21af57d07c30936b297c647aa00bedc7dae585faf8ed6be3593849c3f63721b1974b809b1696
+  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

@@ -689,3 +689,13 @@ Initial release.
 ## 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.47.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
@@ -53,6 +54,25 @@ 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`.
@@ -80,6 +100,7 @@ The current implementation uses an in-memory buffer per supervisor connection. B
 
 ```yaml
 port: 12111
+connection_role: server
 default:
   sxls:
     tlc: "1.3.0"
@@ -105,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`.
@@ -113,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.
@@ -145,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.
@@ -48,6 +49,8 @@ module RSMP
 
   # CLI commands for running RSMP site and supervisor.
   class CLI < Thor
+    include Configuration
+
     desc 'version', 'Show version'
     def version
       puts RSMP::VERSION
@@ -59,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'
@@ -84,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
@@ -97,26 +102,6 @@ module RSMP
     register SchemaCLI, 'schema', 'schema COMMAND', 'SXL schema commands'
     register ConfigCLI, 'config', 'config COMMAND', 'Configuration 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
-
     private
 
     def site_options_class
@@ -136,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)
@@ -223,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
 
@@ -253,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?

data/lib/rsmp/collect/status_matcher.rb

@@ -11,15 +11,25 @@ module RSMP
 
     def match_value?(item)
       return false if @want['q'] && @want['q'] != item['q']
+      return true unless @want.key?('s')
 
-      if @want['s'].is_a? Regexp
-        return false if item['s'] !~ @want['s']
-      elsif @want['s']
-        return false if item['s'] != @want['s']
+      want = @want['s']
+      got = item['s']
+      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)
       return nil unless match_code(item)
 

data/lib/rsmp/command_list.rb

@@ -18,7 +18,7 @@ module RSMP
           'cCI' => command_code_id.to_s,
           'cO' => command_name.to_s,
           'n' => n.to_s,
-          'v' => v.to_s
+          'v' => v
         }
       end
     end