rsmp 0.38.0 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f1f32aacd75ffad7d36662c3e7abd0b0a851b35b287f444dd63cdebc9db1c00
-  data.tar.gz: 32d9db803bc5ef274c1838cb961f677863745bb2e2eca105eb17b8ee4f39cea1
+  metadata.gz: 7db642eae802d3f31456b221ab6297516eb081375f1778cf06cd25b597ae3d07
+  data.tar.gz: e64b67b905975ca8862dd3610a2c3553c8527378db05fc0242dbd56996f850a5
 SHA512:
-  metadata.gz: a655dab4868d9544a0242303da7d26254f3d953ecc5d789c78f7e4553e946b98eebab7f59fa4ee69c736123dfa198417885595db490724b6238fa051b1fb2a87
-  data.tar.gz: f24fe238a17439e6e0b91e75f816733da49f9e348dd22cc00f3c68938505ca68ba7ed32575a71e9dfc18330a10f2b92fe23ade7679bdb3f0878b37e894fd55aa
+  metadata.gz: 9dbceb076fdfd4aee419daceb587c7802eaf664f3bde3bcd7bb944e9e1408e78b9da0987ca7b56ab0e29d65cc120822f2e2c501bff3de2f22676141194394af3
+  data.tar.gz: 25cdeff92403011140b4164541ad94a785ad8b62449563a49f1ae1ccdc99f8489e940a310d140ddda3db34f66bcded08382d5e3bfdc5cf5307cb7529c11f94d7

data/.rubocop.yml

@@ -1,3 +1,7 @@
+plugins:
+  - rubocop-rspec
+  - rubocop-rake
+
 AllCops:
   NewCops: enable
   TargetRubyVersion: 3.4
@@ -43,17 +47,10 @@ Metrics/BlockLength:
     - 'features/**/*'
     - '*.gemspec'
 
-# Keep some reasonable exceptions
-Style/Documentation:
-  Enabled: false
-
+# From Ruby 3.4, frozen string literals are the default anyways
 Style/FrozenStringLiteralComment:
   Enabled: false
 
-# Allow double negation for boolean coercion - common Ruby pattern
-Style/DoubleNegation:
-  Enabled: false
-
 # Allow mix-in usage at top level in test files
 Style/MixinUsage:
   Exclude:
@@ -65,14 +62,6 @@ Lint/ConstantDefinitionInBlock:
   Exclude:
     - 'spec/**/*'
 
-# Keep critical domain-specific logic intact
-Style/ReturnNilInPredicateMethodDefinition:
-  Enabled: false
-
-
-plugins:
-  - rubocop-rspec
-
 RSpec/MultipleExpectations:
   Max: 20
 

data/.tool-versions

@@ -1 +1 @@
-ruby 3.4
+ruby 4

data/Gemfile

@@ -6,12 +6,13 @@ gemspec
 
 group :development do
   gem 'aruba', '~> 2.3'
-  gem 'bundler', '~> 2.6'
+  gem 'bundler', '~> 4.0'
   gem 'cucumber', '~> 9.2'
   gem 'rake', '~> 13.2'
   gem 'rspec', '~> 3.13'
   gem 'rspec-expectations', '~> 3.13'
   gem 'rubocop', '~> 1.65'
+  gem 'rubocop-rake', require: false
   gem 'rubocop-rspec', require: false
   gem 'timecop', '~> 0.9'
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rsmp (0.38.0)
+    rsmp (0.40.0)
       async (~> 2.32)
       colorize (~> 1.1)
       io-endpoint (~> 0.15)
@@ -13,27 +13,27 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    aruba (2.3.1)
-      bundler (>= 1.17, < 3.0)
+    aruba (2.3.3)
+      bundler (>= 1.17)
       contracts (>= 0.16.0, < 0.18.0)
       cucumber (>= 8.0, < 11.0)
-      rspec-expectations (~> 3.4)
+      rspec-expectations (>= 3.4, < 5.0)
       thor (~> 1.0)
     ast (2.4.3)
-    async (2.32.0)
+    async (2.35.2)
       console (~> 1.29)
       fiber-annotation
       io-event (~> 1.11)
       metrics (~> 0.12)
       traces (~> 0.18)
-    bigdecimal (3.2.3)
+    bigdecimal (4.0.1)
     builder (3.3.0)
     colorize (1.1.0)
-    console (1.34.0)
+    console (1.34.2)
       fiber-annotation
       fiber-local (~> 1.1)
       json
-    contracts (0.17.2)
+    contracts (0.17.3)
     cucumber (9.2.1)
       builder (~> 3.2)
       cucumber-ci-environment (> 9, < 11)
@@ -55,22 +55,25 @@ GEM
       bigdecimal
     cucumber-gherkin (27.0.0)
       cucumber-messages (>= 19.1.4, < 23)
-    cucumber-html-formatter (21.14.0)
+    cucumber-html-formatter (21.15.1)
       cucumber-messages (> 19, < 28)
     cucumber-messages (22.0.0)
     cucumber-tag-expressions (6.1.2)
     diff-lcs (1.6.2)
-    ffi (1.17.2)
-    ffi (1.17.2-arm64-darwin)
+    ffi (1.17.3)
+    ffi (1.17.3-arm64-darwin)
+    ffi (1.17.3-x64-mingw-ucrt)
+    ffi (1.17.3-x86_64-darwin)
+    ffi (1.17.3-x86_64-linux-gnu)
     fiber-annotation (0.2.0)
     fiber-local (1.1.0)
       fiber-storage
     fiber-storage (1.0.1)
     hana (1.3.7)
-    io-endpoint (0.15.2)
-    io-event (1.14.0)
-    io-stream (0.10.0)
-    json (2.14.1)
+    io-endpoint (0.16.0)
+    io-event (1.14.2)
+    io-stream (0.11.1)
+    json (2.18.0)
     json_schemer (2.4.0)
       bigdecimal
       hana (~> 1.3)
@@ -85,31 +88,31 @@ GEM
     multi_test (1.1.0)
     ostruct (0.6.3)
     parallel (1.27.0)
-    parser (3.3.9.0)
+    parser (3.3.10.0)
       ast (~> 2.4.1)
       racc
-    prism (1.5.1)
+    prism (1.8.0)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.0)
-    regexp_parser (2.11.2)
-    rsmp_schema (0.8.9)
+    rake (13.3.1)
+    regexp_parser (2.11.3)
+    rsmp_schema (0.9.1)
       json_schemer (~> 2.4.0)
       thor (~> 1.4.0)
-    rspec (3.13.1)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.5)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.5)
+    rspec-mocks (3.13.7)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.5)
-    rubocop (1.81.0)
+    rspec-support (3.13.6)
+    rubocop (1.82.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -117,15 +120,18 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.47.1, < 2.0)
+      rubocop-ast (>= 1.48.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.47.1)
+    rubocop-ast (1.49.0)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
-    rubocop-rspec (3.7.0)
+      prism (~> 1.7)
+    rubocop-rake (0.7.1)
       lint_roller (~> 1.1)
-      rubocop (~> 1.72, >= 1.72.1)
+      rubocop (>= 1.72.1)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
     ruby-progressbar (1.13.0)
     simpleidn (0.2.3)
     sys-uname (1.4.1)
@@ -136,31 +142,27 @@ GEM
     traces (0.18.2)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
-    unicode-emoji (4.1.0)
+    unicode-emoji (4.2.0)
 
 PLATFORMS
-  arm64-darwin-22
   arm64-darwin-23
   arm64-darwin-24
   x64-mingw-ucrt
-  x64-mingw32
-  x86_64-darwin-19
-  x86_64-darwin-20
-  x86_64-darwin-21
   x86_64-darwin-22
   x86_64-linux
 
 DEPENDENCIES
   aruba (~> 2.3)
-  bundler (~> 2.6)
+  bundler (~> 4.0)
   cucumber (~> 9.2)
   rake (~> 13.2)
   rsmp!
   rspec (~> 3.13)
   rspec-expectations (~> 3.13)
   rubocop (~> 1.65)
+  rubocop-rake
   rubocop-rspec
   timecop (~> 0.9)
 
 BUNDLED WITH
-   2.6.3
+  4.0.3

data/README.md

@@ -31,6 +31,9 @@ Be default, a site will try to connect to a single supervisor on localhost 127.0
 
 You can pass options to control ip adresseses, ports, logging and other behaviour:
 
+Configuration files can be loaded from YAML using the CLI or the options classes. These are validated
+against JSON schemas and will raise errors with details on what is wrong.
+
 ```ruby
 require 'rsmp'
 settings = {
@@ -45,8 +48,6 @@ settings = {
 RSMP::Site.new(site_settings:settings)
 ```
 
-See lib/rsmp/site.rb and lib/rsmp/supervisor.rb for a list of settings and their default values.
-
 ### Concurrency
 The [async](https://github.com/socketry/async) and [async-io](https://github.com/socketry/async-io) gems are used to handle concurrency. Everything happens in a single thread, but fibers are used to switch between tasks whenever an IO operation blocks.
 
@@ -162,7 +163,7 @@ Use the ```tlc``` site type to run an emulation of a traffic light controller. T
 ### CLI help and options.
 Use ```--help <command>``` to get a list of available options.
 
-Use ```--config <path>``` to point to a .yaml config file, controlling things like IP adresses, ports, and log output. Examples of config files can be found the folder ```config/```.
+Use ```--config <path>``` or ```--options <path>``` to point to a .yaml config file, controlling things like IP adresses, ports, and log output. Examples of config files can be found the folder ```config/```.
 
 ## Tests
 ### RSpec

data/documentation/configuration.md

@@ -0,0 +1,76 @@
+# Configuration
+
+## Overview
+RSMP uses option classes to handle configuration for sites and supervisors. These classes provide:
+
+- File-based configuration via YAML
+- JSON Schema validation with descriptive errors
+- Safe access to nested values using Ruby's `dig`
+- Deep merging of provided values with defaults
+
+## Option classes
+
+- `RSMP::Site::Options` for sites
+- `RSMP::Supervisor::Options` for supervisors
+- `RSMP::TLC::TrafficControllerSite::Options` for TLC sites
+
+Each class applies defaults and validates the configuration against a JSON Schema located in `lib/rsmp/options/schemas/`.
+
+## Loading a configuration file
+
+Use the option classes to load a YAML configuration file:
+
+- `RSMP::Site::Options.load_file(path)`
+- `RSMP::Supervisor::Options.load_file(path)`
+
+The top-level `log` section is separated into `log_settings`. Other keys are treated as settings for the site or supervisor.
+
+## CLI usage
+
+Use the CLI with a config file:
+
+- `rsmp site --config path/to/site.yaml`
+- `rsmp supervisor --options path/to/supervisor.yaml`
+
+Both `--config` and `--options` are accepted as aliases.
+
+## Example: site YAML
+
+```yaml
+site_id: RN+SI0001
+supervisors:
+  - ip: 127.0.0.1
+    port: 12111
+sxl: tlc
+sxl_version: "1.2.1"
+components:
+  main:
+    TC:
+log:
+  json: true
+```
+
+## Example: supervisor YAML
+
+```yaml
+port: 12111
+guest:
+  sxl: tlc
+  intervals:
+    timer: 0.1
+    watchdog: 0.1
+log:
+  json: true
+```
+
+## Validation
+
+Invalid configurations raise `RSMP::ConfigurationError` with details about the failing path. The CLI prints these errors when loading config files.
+
+Errors include the failing JSON pointer and helpful type hints, for example:
+
+- `/supervisors: value at \`/supervisors\` is not an array (expected array, got string)`
+
+## Defaults and overrides
+
+Configuration values override defaults via deep merge. A notable exception is `components.main`, which replaces the default component list when provided.

data/lib/rsmp/cli.rb

@@ -2,6 +2,7 @@ require 'thor'
 require_relative '../rsmp'
 
 module RSMP
+  # CLI commands for running RSMP site and supervisor.
   class CLI < Thor
     desc 'version', 'Show version'
     def version
@@ -9,7 +10,7 @@ module RSMP
     end
 
     desc 'site', 'Run RSMP site'
-    method_option :config, type: :string, aliases: '-c', banner: 'Path to .yaml config file'
+    method_option :config, type: :string, aliases: ['-c', '--options'], banner: 'Path to .yaml config file'
     method_option :id, type: :string, aliases: '-i', banner: 'RSMP site id'
     method_option :supervisors, type: :string, aliases: '-s',
                                 banner: 'ip:port,... list of supervisor to connect to'
@@ -31,7 +32,7 @@ module RSMP
     end
 
     desc 'supervisor', 'Run RSMP supervisor'
-    method_option :config, type: :string, aliases: '-c', banner: 'Path to .yaml config file'
+    method_option :config, type: :string, aliases: ['-c', '--options'], banner: 'Path to .yaml config file'
     method_option :id, type: :string, aliases: '-i', banner: 'RSMP site id'
     method_option :ip, type: :string, banner: 'IP address to listen on'
     method_option :port, type: :string, aliases: '-p', banner: 'Port to listen on'
@@ -62,11 +63,12 @@ module RSMP
 
         return [settings, log_settings] unless options[:config]
 
-        if File.exist? options[:config]
-          settings = YAML.load_file options[:config]
-          log_settings = settings.delete('log') || log_settings
-        else
-          puts "Error: Config #{options[:config]} not found"
+        begin
+          options_object = RSMP::Site::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
 
@@ -134,11 +136,12 @@ module RSMP
 
       return [settings, log_settings] unless options[:config]
 
-      if File.exist? options[:config]
-        settings = YAML.load_file options[:config]
-        log_settings = settings.delete('log') || log_settings
-      else
-        puts "Error: Config #{options[:config]} not found"
+      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
 

data/lib/rsmp/collect/alarm_matcher.rb

@@ -1,13 +1,13 @@
 module RSMP
   # Match a specific alarm
   class AlarmMatcher < Matcher
-    def match?(item)
-      return false if @want['n'] && @want['n'] != item['n']
+    def match(item)
+      return nil if @want['n'] && @want['n'] != item['n']
 
       if @want['v'].is_a? Regexp
-        return false if item['v'] !~ @want['v']
+        return nil if item['v'] !~ @want['v']
       elsif @want['v']
-        return false if item['v'] != @want['v']
+        return nil if item['v'] != @want['v']
       end
       true
     end

data/lib/rsmp/collect/collector/logging.rb

@@ -1,5 +1,6 @@
 module RSMP
   class Collector
+    # Logging helpers for Collector instances.
     module Logging
       def log_start
         @distributor.log "#{identifier}: Waiting for #{describe_matcher}".strip, level: :collect

data/lib/rsmp/collect/command_matcher.rb

@@ -1,7 +1,7 @@
 module RSMP
   # Class for matching a command
   class CommandMatcher < Matcher
-    def match_code?(item)
+    def match_code(item)
       return nil if @want['cCI'] && @want['cCI'] != item['cCI']
       return nil if @want['n'] && @want['n'] != item['n']
 
@@ -19,8 +19,8 @@ module RSMP
       true
     end
 
-    def match?(item)
-      code_match = match_code?(item)
+    def match(item)
+      code_match = match_code(item)
       return code_match if code_match.nil?
 
       match_value?(item)

data/lib/rsmp/collect/matcher.rb

@@ -9,7 +9,7 @@ module RSMP
       @message = nil
     end
 
-    # Are we done, i.e. did the last checked item match?
+    # Are we done, i.e. did the last checked item match
     def done?
       @got != nil
     end
@@ -17,7 +17,7 @@ module RSMP
     # Check an item and set @done to true if it matches
     # Store the item and corresponding message if there's a positive or negative match
     def perform_match(item, _message, block)
-      matched = match? item
+      matched = match item
       if !matched.nil? && block
         status = block.call(nil, item)
         matched = status if [true, false].include?(status)
@@ -35,6 +35,6 @@ module RSMP
       @got = nil
     end
 
-    def match?(item); end
+    def match(item); end
   end
 end

data/lib/rsmp/collect/queue.rb

@@ -1,7 +1,7 @@
-# Receives items from a Distributor and keeps them in a queue.
-# The client can wait for mesages and will get them one by one.
-
+# Top-level RSMP namespace.
 module RSMP
+  # Receives items from a Distributor and keeps them in a queue.
+  # The client can wait for messages and will get them one by one.
   class Queue
     include Receiver
 

data/lib/rsmp/collect/receiver.rb

@@ -1,8 +1,6 @@
-# Receives items from a Distributor, as long as it's
-# installed as a receiver.
-# Optionally filter mesage using a Filter.
-
 module RSMP
+  # Receives items from a Distributor when included as a receiver.
+  # Optionally filter messages using a Filter.
   module Receiver
     include Inspect
 

data/lib/rsmp/collect/status_matcher.rb

@@ -1,9 +1,10 @@
 module RSMP
+  # Match a specific status
   class StatusMatcher < Matcher
-    def match_code?(item)
-      return false if @want['sCI'] && @want['sCI'] != item['sCI']
-      return false if @want['cO'] && @want['cO'] != item['cO']
-      return false if @want['n'] && @want['n'] != item['n']
+    def match_code(item)
+      return nil if @want['sCI'] && @want['sCI'] != item['sCI']
+      return nil if @want['cO'] && @want['cO'] != item['cO']
+      return nil if @want['n'] && @want['n'] != item['n']
 
       true
     end
@@ -19,8 +20,8 @@ module RSMP
       true
     end
 
-    def match?(item)
-      return nil unless match_code?(item)
+    def match(item)
+      return nil unless match_code(item)
 
       match_value?(item)
     end

data/lib/rsmp/component/alarm_state.rb

@@ -3,7 +3,6 @@ module RSMP
   # The alarm state is for a particular alarm code,
   # a component typically have an alarm state for each
   # alarm code that is defined for the component type.
-
   class AlarmState
     attr_reader :component_id, :code, :acknowledged, :suspended, :active, :timestamp, :category, :priority, :rvs
 
@@ -24,9 +23,9 @@ module RSMP
       @component = component
       @component_id = component.c_id
       @code = code
-      @suspended = !!options[:suspended]
-      @acknowledged = !!options[:acknowledged]
-      @active = !!options[:active]
+      @suspended = options[:suspended] == true
+      @acknowledged = options[:acknowledged] == true
+      @active = options[:active] == true
       @timestamp = options[:timestamp]
       @category = options[:category] || 'D'
       @priority = options[:priority] || 2

data/lib/rsmp/component/component_base.rb

@@ -1,6 +1,5 @@
 module RSMP
   # RSMP component base class.
-
   class ComponentBase
     include Inspect
 

data/lib/rsmp/component/components.rb

@@ -1,6 +1,5 @@
-# Things shared between sites and site proxies
-
 module RSMP
+  # Things shared between sites and site proxies
   module Components
     attr_reader :components, :main
 

data/lib/rsmp/convert/export/json_schema.rb

@@ -7,6 +7,8 @@ require 'fileutils'
 module RSMP
   module Convert
     module Export
+      # Converts SXL (YAML) structures into JSON Schema files.
+      # Converts SXL (YAML) structures into JSON Schema files.
       module JSONSchema
         JSON_OPTIONS = {
           array_nl: "\n",

data/lib/rsmp/convert/import/yaml.rb

@@ -7,6 +7,7 @@ require 'fileutils'
 module RSMP
   module Convert
     module Import
+      # Importer for SXL in YAML format.
       module YAML
         def self.read(path)
           convert ::YAML.load_file(path)

data/lib/rsmp/helpers/clock.rb

@@ -1,11 +1,9 @@
-# Get the current time in UTC, with optional adjustment
-# Convertion to string uses the RSMP format 2015-06-08T12:01:39.654Z
-# Note that using to_s on a my_clock.to_s will not produce an RSMP formatted timestamp,
-# you need to use Clock.to_s my_clock
-
 require 'time'
 
 module RSMP
+  # Get the current time in UTC, with optional adjustment.
+  # Conversion to string uses the RSMP format 2015-06-08T12:01:39.654Z
+  # Use `Clock.to_s` to format times in RSMP format.
   class Clock
     attr_reader :adjustment
 

data/lib/rsmp/helpers/deep_merge.rb

@@ -1,3 +1,4 @@
+# Extensions to Hash providing a `deep_merge` helper.
 class Hash
   def deep_merge(other_hash)
     return self unless other_hash

data/lib/rsmp/helpers/error.rb

@@ -8,6 +8,7 @@ module RSMP
   class MalformedMessage < Error
   end
 
+  # Raised when schema validation fails.
   class SchemaError < Error
     attr_accessor :schemas
   end

data/lib/rsmp/helpers/inspect.rb

@@ -1,16 +1,15 @@
-# Costume inspect, to reduce noise
-#
-# Instance variables of classes starting with Async or RSMP are shown
-# with only their class name and object id, which reduces output,
-# especially for deep object structures.
-# Additionally, a list of variables to shown in short format can be passed.
-#
-# The short form is generated by using to_s() insted of inspect()
-#
-# Array#to_s and Hash#to_s usually show items, but here we show just number
-# of items, when the short form is requested.
-
 module RSMP
+  # Custom inspect, to reduce noise
+  #
+  # Instance variables of classes starting with Async or RSMP are shown
+  # with only their class name and object id, which reduces output,
+  # especially for deep object structures.
+  # Additionally, a list of variables to shown in short format can be passed.
+  #
+  # The short form is generated by using to_s() insted of inspect()
+  #
+  # Array#to_s and Hash#to_s usually show items, but here we show just number
+  # of items, when the short form is requested.
   module Inspect
     def inspector *short_items
       instance_variables.map do |var_name|

data/lib/rsmp/log/archive.rb

@@ -1,7 +1,6 @@
-# Archive of log items, which can be messages or info items.
-# All items are timestamped, and stored chronologically.
-
 module RSMP
+  # Archive of log items, which can be messages or info items.
+  # All items are timestamped, and stored chronologically.
   class Archive
     include Inspect