rsmp 0.39.0 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95c0244d87cf4f53324931c8a898915c54a520ddf0112c4753ef41b03099122c
-  data.tar.gz: d09df39a9b9042fc1c9a118986138fff5436e74d743146776b69d22a300826e5
+  metadata.gz: 7db642eae802d3f31456b221ab6297516eb081375f1778cf06cd25b597ae3d07
+  data.tar.gz: e64b67b905975ca8862dd3610a2c3553c8527378db05fc0242dbd56996f850a5
 SHA512:
-  metadata.gz: 96bfd44c55d893634aebbed5eb0a8d830190b0fc7abdeb644f2fe9da1fecae60b1e1a723806d93cdfb124e33e3a89e7e0ca28e2ba14111b43346741e9dfd4086
-  data.tar.gz: 32dc5721a03a4d2a5161954e5c0a2b9273c3b245dcb1769902b13001582cc34ba13bc8e301954bad68b3d336e7be8bbf565aede3edcfc8e7e3f504504dcf44be
+  metadata.gz: 9dbceb076fdfd4aee419daceb587c7802eaf664f3bde3bcd7bb944e9e1408e78b9da0987ca7b56ab0e29d65cc120822f2e2c501bff3de2f22676141194394af3
+  data.tar.gz: 25cdeff92403011140b4164541ad94a785ad8b62449563a49f1ae1ccdc99f8489e940a310d140ddda3db34f66bcded08382d5e3bfdc5cf5307cb7529c11f94d7

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rsmp (0.39.0)
+    rsmp (0.40.0)
       async (~> 2.32)
       colorize (~> 1.1)
       io-endpoint (~> 0.15)

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

@@ -10,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'
@@ -32,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'
@@ -63,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
 
@@ -135,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/node/site/site.rb

@@ -5,6 +5,10 @@ module RSMP
 
     attr_reader :core_version, :site_settings, :logger, :proxies
 
+    def self.options_class
+      RSMP::Site::Options
+    end
+
     def initialize(options = {})
       super
       initialize_components
@@ -23,39 +27,11 @@ module RSMP
       @site_settings['site_id']
     end
 
-    def default_site_settings
-      {
-        'site_id' => 'RN+SI0001',
-        'supervisors' => [
-          { 'ip' => '127.0.0.1', 'port' => 12_111 }
-        ],
-        'sxl' => 'tlc',
-        'sxl_version' => RSMP::Schema.latest_version(:tlc),
-        'intervals' => {
-          'timer' => 0.1,
-          'watchdog' => 1,
-          'reconnect' => 0.1
-        },
-        'timeouts' => {
-          'watchdog' => 2,
-          'acknowledgement' => 2
-        },
-        'send_after_connect' => true,
-        'components' => {
-          'main' => {
-            'C1' => {}
-          }
-        }
-      }
-    end
-
     def handle_site_settings(options = {})
-      defaults = default_site_settings
-      defaults['components']['main'] = options[:site_settings]['components']['main'] if options.dig(
-        :site_settings, 'components', 'main'
-      )
-
-      @site_settings = defaults.deep_merge options[:site_settings]
+      options_class = self.class.options_class
+      settings = options[:site_settings] || {}
+      @site_options = options_class.new(settings)
+      @site_settings = @site_options.to_h
 
       check_sxl_version
       check_core_versions

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

@@ -4,25 +4,9 @@ module RSMP
       # Handles supervisor configuration and site settings
       module Configuration
         def handle_supervisor_settings(supervisor_settings)
-          defaults = {
-            'port' => 12_111,
-            'ips' => 'all',
-            'guest' => {
-              'sxl' => 'tlc',
-              'intervals' => {
-                'timer' => 1,
-                'watchdog' => 1
-              },
-              'timeouts' => {
-                'watchdog' => 2,
-                'acknowledgement' => 2
-              }
-            }
-          }
-
-          # merge options into defaults
-          @supervisor_settings = defaults.deep_merge(supervisor_settings)
-          @core_version = @supervisor_settings['guest']['core_version']
+          options = RSMP::Supervisor::Options.new(supervisor_settings || {})
+          @supervisor_settings = options.to_h
+          @core_version = @supervisor_settings.dig('guest', 'core_version')
           check_site_sxl_types
         end
 

data/lib/rsmp/options/options.rb

@@ -0,0 +1,185 @@
+require 'yaml'
+require 'pathname'
+
+module RSMP
+  # Base class for configuration options.
+  class Options
+    SCHEMAS_PATH = File.expand_path('schemas', __dir__)
+
+    attr_reader :data, :log_settings, :source
+
+    def self.load_file(path, validate: true)
+      raise RSMP::ConfigurationError, "Config #{path} not found" unless File.exist?(path)
+
+      raw = YAML.load_file(path)
+      raise RSMP::ConfigurationError, "Config #{path} must be a hash" unless raw.is_a?(Hash) || raw.nil?
+
+      raw ||= {}
+      log_settings = raw.delete('log') || {}
+      new(raw, source: path, log_settings: log_settings, validate: validate)
+    rescue Psych::SyntaxError => e
+      raise RSMP::ConfigurationError, "Cannot read config file #{path}: #{e}"
+    end
+
+    def initialize(options = nil, source: nil, log_settings: nil, validate: true, **extra)
+      options = extra if options.nil? && extra.any?
+      @source = source
+      @log_settings = normalize(log_settings || {})
+      normalized = normalize(options || {})
+      @data = apply_defaults(normalized)
+      validate! if validate
+    end
+
+    def defaults
+      {}
+    end
+
+    def schema_file
+      nil
+    end
+
+    def schema_path
+      return unless schema_file
+
+      File.join(SCHEMAS_PATH, schema_file)
+    end
+
+    def validate!
+      return unless schema_path && File.exist?(schema_path)
+
+      schemer = JSONSchemer.schema(Pathname.new(schema_path))
+      errors = schemer.validate(@data).to_a
+      return if errors.empty?
+
+      message = errors.map { |error| format_error(error) }.join("\n")
+      raise RSMP::ConfigurationError, "Invalid configuration#{source_suffix}:\n#{message}"
+    end
+
+    def dig(*path, default: nil, assume: nil)
+      value = @data.dig(*path)
+      return value unless value.nil?
+      return default unless default.nil?
+      return assume unless assume.nil?
+
+      raise RSMP::ConfigurationError, "Config #{path.inspect} is missing"
+    end
+
+    def [](key)
+      @data[key]
+    end
+
+    def to_h
+      @data
+    end
+
+    private
+
+    def apply_defaults(options)
+      defaults.deep_merge(options)
+    end
+
+    def normalize(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, val), memo|
+          memo[key.to_s] = normalize(val)
+        end
+      when Array
+        value.map { |item| normalize(item) }
+      else
+        value
+      end
+    end
+
+    def format_error(error)
+      pointer = error_pointer(error)
+      details = error_details(error)
+      type_hint = error_type_hint(error)
+      schema_suffix = schema_pointer_suffix(error)
+
+      "#{pointer}: #{details}#{type_hint}#{schema_suffix}"
+    end
+
+    def error_pointer(error)
+      pointer = error['data_pointer'] || error['instanceLocation'] || error['dataPath']
+      pointer = pointer.to_s
+      pointer.empty? ? '/' : pointer
+    end
+
+    def error_details(error)
+      details = error['message'] || error['error']
+      details ||= begin
+        type = error['type'] || error['keyword']
+        extra = error['details']
+        [type, extra].compact.join(' ')
+      end
+      details.to_s
+    end
+
+    def error_type_hint(error)
+      expected = expected_type(error['schema'])
+      actual = describe_type(error['data'])
+      return '' unless expected && actual
+
+      " (expected #{expected}, got #{actual})"
+    end
+
+    def schema_pointer_suffix(error)
+      schema_pointer = error['schema_pointer'] || error['schemaLocation'] || error['keywordLocation']
+      schema_pointer = schema_pointer.to_s
+      schema_pointer.empty? ? '' : " (schema #{schema_pointer})"
+    end
+
+    def expected_type(schema)
+      return unless schema.is_a?(Hash)
+
+      type = schema['type']
+      return format_type(type) if type
+
+      types = []
+      %w[oneOf anyOf].each do |key|
+        next unless schema[key].is_a?(Array)
+
+        types.concat(schema[key].map { |item| item['type'] }.compact)
+      end
+
+      format_type(types) if types.any?
+    end
+
+    def format_type(type)
+      case type
+      when Array
+        type.join(' or ')
+      when nil
+        nil
+      else
+        type.to_s
+      end
+    end
+
+    def describe_type(value)
+      case value
+      when NilClass
+        'null'
+      when String
+        'string'
+      when Integer
+        'integer'
+      when Float
+        'number'
+      when TrueClass, FalseClass
+        'boolean'
+      when Array
+        'array'
+      when Hash
+        'object'
+      else
+        value.class.name
+      end
+    end
+
+    def source_suffix
+      source ? " (#{source})" : ''
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "site.json",
+  "type": "object",
+  "properties": {
+    "site_id": { "type": "string" },
+    "type": { "type": "string" },
+    "supervisors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "ip": { "type": "string" },
+          "port": { "type": ["integer", "string"] }
+        },
+        "required": ["ip", "port"],
+        "additionalProperties": true
+      }
+    },
+    "sxl": { "type": "string" },
+    "sxl_version": { "type": "string" },
+    "core_version": { "type": "string" },
+    "intervals": {
+      "type": "object",
+      "properties": {
+        "timer": { "type": "number" },
+        "watchdog": { "type": "number" },
+        "reconnect": { "type": "number" }
+      },
+      "additionalProperties": true
+    },
+    "timeouts": {
+      "type": "object",
+      "properties": {
+        "watchdog": { "type": "number" },
+        "acknowledgement": { "type": "number" }
+      },
+      "additionalProperties": true
+    },
+    "send_after_connect": { "type": "boolean" },
+    "components": { "type": "object" },
+    "security_codes": { "type": "object" },
+    "startup_sequence": { "type": "string" },
+    "signal_plans": { "type": "object" },
+    "inputs": { "type": "object" },
+    "live_output": { "type": ["string", "null"] }
+  },
+  "additionalProperties": true
+}

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

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "port": { "type": ["integer", "string"] },
+    "ip": { "type": "string" },
+    "ips": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
+    "site_id": { "type": "string" },
+    "max_sites": { "type": "integer" },
+    "guest": {
+      "type": "object",
+      "properties": {
+        "sxl": { "type": "string" },
+        "sxl_version": { "type": "string" },
+        "core_version": { "type": "string" },
+        "intervals": {
+          "type": "object",
+          "properties": {
+            "timer": { "type": "number" },
+            "watchdog": { "type": "number" }
+          },
+          "additionalProperties": true
+        },
+        "timeouts": {
+          "type": "object",
+          "properties": {
+            "watchdog": { "type": "number" },
+            "acknowledgement": { "type": "number" }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+    "sites": { "type": "object" }
+  },
+  "additionalProperties": true
+}

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

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "traffic_controller_site.json",
+  "allOf": [
+    { "$ref": "site.json" },
+    {
+      "type": "object",
+      "properties": {
+        "security_codes": { "type": "object" },
+        "startup_sequence": { "type": "string" },
+        "signal_plans": { "type": "object" },
+        "inputs": { "type": "object" },
+        "live_output": { "type": ["string", "null"] }
+      },
+      "additionalProperties": true
+    }
+  ]
+}

data/lib/rsmp/options/site_options.rb

@@ -0,0 +1,44 @@
+module RSMP
+  class Site < Node
+    # Configuration options for sites.
+    class Options < RSMP::Options
+      def defaults
+        {
+          'site_id' => 'RN+SI0001',
+          'supervisors' => [
+            { 'ip' => '127.0.0.1', 'port' => 12_111 }
+          ],
+          'sxl' => 'tlc',
+          'sxl_version' => RSMP::Schema.latest_version(:tlc),
+          'intervals' => {
+            'timer' => 0.1,
+            'watchdog' => 1,
+            'reconnect' => 0.1
+          },
+          'timeouts' => {
+            'watchdog' => 2,
+            'acknowledgement' => 2
+          },
+          'send_after_connect' => true,
+          'components' => {
+            'main' => {
+              'C1' => {}
+            }
+          }
+        }
+      end
+
+      def schema_file
+        'site.json'
+      end
+
+      private
+
+      def apply_defaults(options)
+        defaults = defaults()
+        defaults['components']['main'] = options['components']['main'] if options.dig('components', 'main')
+        defaults.deep_merge(options)
+      end
+    end
+  end
+end

data/lib/rsmp/options/supervisor_options.rb

@@ -0,0 +1,28 @@
+module RSMP
+  class Supervisor < Node
+    # Configuration options for supervisors.
+    class Options < RSMP::Options
+      def defaults
+        {
+          'port' => 12_111,
+          'ips' => 'all',
+          'guest' => {
+            'sxl' => 'tlc',
+            'intervals' => {
+              'timer' => 1,
+              'watchdog' => 1
+            },
+            'timeouts' => {
+              'watchdog' => 2,
+              'acknowledgement' => 2
+            }
+          }
+        }
+      end
+
+      def schema_file
+        'supervisor.json'
+      end
+    end
+  end
+end

data/lib/rsmp/options/traffic_controller_site_options.rb

@@ -0,0 +1,12 @@
+module RSMP
+  module TLC
+    class TrafficControllerSite < Site
+      # Configuration options for traffic controller sites.
+      class Options < RSMP::Site::Options
+        def schema_file
+          'traffic_controller_site.json'
+        end
+      end
+    end
+  end
+end

data/lib/rsmp/tlc/traffic_controller_site.rb

@@ -4,6 +4,10 @@ module RSMP
     class TrafficControllerSite < Site
       attr_accessor :main, :signal_plans
 
+      def self.options_class
+        RSMP::TLC::TrafficControllerSite::Options
+      end
+
       def initialize(options = {})
         # setup options before calling super initializer,
         # since build of components depend on options

data/lib/rsmp/version.rb

@@ -1,3 +1,3 @@
 module RSMP
-  VERSION = '0.39.0'.freeze
+  VERSION = '0.40.0'.freeze
 end

data/lib/rsmp.rb

@@ -53,6 +53,10 @@ require_relative 'rsmp/node/supervisor/modules/configuration'
 require_relative 'rsmp/node/supervisor/modules/connection'
 require_relative 'rsmp/node/supervisor/modules/sites'
 require_relative 'rsmp/node/supervisor/supervisor'
+require_relative 'rsmp/options/options'
+require_relative 'rsmp/options/site_options'
+require_relative 'rsmp/options/supervisor_options'
+require_relative 'rsmp/options/traffic_controller_site_options'
 require_relative 'rsmp/proxy/modules/state'
 require_relative 'rsmp/proxy/modules/watchdogs'
 require_relative 'rsmp/proxy/modules/acknowledgements'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rsmp
 version: !ruby/object:Gem::Version
-  version: 0.39.0
+  version: 0.40.0
 platform: ruby
 authors:
 - Emil Tin
@@ -138,6 +138,7 @@ files:
 - cucumber.yml
 - documentation/classes_and_modules.md
 - documentation/collecting_message.md
+- documentation/configuration.md
 - documentation/message_distribution.md
 - documentation/tasks.md
 - exe/rsmp
@@ -186,6 +187,13 @@ files:
 - lib/rsmp/node/supervisor/modules/sites.rb
 - lib/rsmp/node/supervisor/supervisor.rb
 - lib/rsmp/node/task.rb
+- lib/rsmp/options/options.rb
+- lib/rsmp/options/schemas/site.json
+- lib/rsmp/options/schemas/supervisor.json
+- lib/rsmp/options/schemas/traffic_controller_site.json
+- lib/rsmp/options/site_options.rb
+- lib/rsmp/options/supervisor_options.rb
+- lib/rsmp/options/traffic_controller_site_options.rb
 - lib/rsmp/proxy/modules/acknowledgements.rb
 - lib/rsmp/proxy/modules/receive.rb
 - lib/rsmp/proxy/modules/send.rb