rsmp 0.38.0 → 0.40.0

data/lib/rsmp/log/logger.rb

@@ -1,4 +1,5 @@
 module RSMP
+  # Formats and outputs log messages according to configured settings.
   class Logger
     include Filtering
     include Colorization

data/lib/rsmp/log/logging.rb

@@ -3,6 +3,7 @@
 #
 
 module RSMP
+  # Logging integration providing `archive` and `logger` helpers.
   module Logging
     attr_reader :archive, :logger
 

data/lib/rsmp/message.rb

@@ -2,6 +2,7 @@ require 'rsmp_schema'
 
 # rsmp messages
 module RSMP
+  # Base RSMP message class used to represent parsed and built messages.
   class Message
     include Inspect
 
@@ -191,6 +192,7 @@ module RSMP
     end
   end
 
+  # Represents a malformed message with invalid attributes.
   class Malformed < Message
     # rubocop:disable Lint/MissingSuper
     def initialize(attributes = {})
@@ -201,6 +203,7 @@ module RSMP
     # rubocop:enable Lint/MissingSuper
   end
 
+  # Version message, lists supported versions and SXL information.
   class Version < Message
     def initialize(attributes = {})
       super({
@@ -213,9 +216,11 @@ module RSMP
     end
   end
 
+  # Unknown message type wrapper.
   class Unknown < Message
   end
 
+  # AggregatedStatus message type.
   class AggregatedStatus < Message
     def initialize(attributes = {})
       super({
@@ -224,6 +229,7 @@ module RSMP
     end
   end
 
+  # AggregatedStatusRequest message type.
   class AggregatedStatusRequest < Message
     def initialize(attributes = {})
       super({
@@ -232,6 +238,7 @@ module RSMP
     end
   end
 
+  # Alarm base message type.
   class Alarm < Message
     def initialize(attributes = {})
       super({
@@ -253,6 +260,7 @@ module RSMP
     end
   end
 
+  # Alarm issue specialization.
   class AlarmIssue < Alarm
     def initialize(attributes = {})
       super({
@@ -261,6 +269,7 @@ module RSMP
     end
   end
 
+  # Alarm request specialization.
   class AlarmRequest < Alarm
     def initialize(attributes = {})
       super({
@@ -269,6 +278,7 @@ module RSMP
     end
   end
 
+  # Alarm acknowledge message.
   class AlarmAcknowledge < Alarm
     def initialize(attributes = {})
       super({
@@ -277,6 +287,7 @@ module RSMP
     end
   end
 
+  # Alarm acknowledged (acknowledged state) message.
   class AlarmAcknowledged < Alarm
     def initialize(attributes = {})
       super({
@@ -286,6 +297,7 @@ module RSMP
     end
   end
 
+  # Alarm suspend message.
   class AlarmSuspend < Alarm
     def initialize(attributes = {})
       super({
@@ -294,6 +306,7 @@ module RSMP
     end
   end
 
+  # Alarm suspended (suspended state) message.
   class AlarmSuspended < Alarm
     def initialize(attributes = {})
       super({
@@ -303,6 +316,7 @@ module RSMP
     end
   end
 
+  # Alarm resume message.
   class AlarmResume < Alarm
     def initialize(attributes = {})
       super({
@@ -311,6 +325,7 @@ module RSMP
     end
   end
 
+  # Alarm resumed (not suspended) message.
   class AlarmResumed < Alarm
     def initialize(attributes = {})
       super({
@@ -320,6 +335,7 @@ module RSMP
     end
   end
 
+  # Watchdog message type.
   class Watchdog < Message
     def initialize(attributes = {})
       super({
@@ -328,6 +344,7 @@ module RSMP
     end
   end
 
+  # Base class for acking messages (MessageAck / MessageNotAck).
   class MessageAcking < Message
     attr_reader :original
 
@@ -348,6 +365,7 @@ module RSMP
     end
   end
 
+  # Acknowledgement for a received message.
   class MessageAck < MessageAcking
     def initialize(attributes = {})
       super({
@@ -360,6 +378,7 @@ module RSMP
     end
   end
 
+  # Negative acknowledgement for a received message.
   class MessageNotAck < MessageAcking
     def initialize(attributes = {})
       super({
@@ -370,6 +389,7 @@ module RSMP
     end
   end
 
+  # Command request message type.
   class CommandRequest < Message
     def initialize(attributes = {})
       super({
@@ -378,6 +398,7 @@ module RSMP
     end
   end
 
+  # Command response message type.
   class CommandResponse < Message
     def initialize(attributes = {})
       super({
@@ -386,6 +407,7 @@ module RSMP
     end
   end
 
+  # Status request message type.
   class StatusRequest < Message
     def initialize(attributes = {})
       super({
@@ -394,6 +416,7 @@ module RSMP
     end
   end
 
+  # Status response message type.
   class StatusResponse < Message
     def initialize(attributes = {})
       super({
@@ -402,6 +425,7 @@ module RSMP
     end
   end
 
+  # Status subscribe message type.
   class StatusSubscribe < Message
     def initialize(attributes = {})
       super({
@@ -410,6 +434,7 @@ module RSMP
     end
   end
 
+  # Status unsubscribe message type.
   class StatusUnsubscribe < Message
     def initialize(attributes = {})
       super({
@@ -418,6 +443,7 @@ module RSMP
     end
   end
 
+  # Status update message type.
   class StatusUpdate < Message
     def initialize(attributes = {})
       super({

data/lib/rsmp/node/node.rb

@@ -1,6 +1,5 @@
-# Base class for sites and supervisors
-
 module RSMP
+  # Base class for sites and supervisors.
   class Node
     include Logging
     include Inspect

data/lib/rsmp/node/protocol.rb

@@ -1,4 +1,5 @@
 module RSMP
+  # Simple protocol wrapper for reading/writing RSMP framed messages.
   class Protocol
     def initialize(stream)
       @stream = stream

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

@@ -1,13 +1,14 @@
-# RSMP site
-# The site initializes the connection to the supervisor.
-# Connections to supervisors are handles via supervisor proxies.
-
 module RSMP
+  # RSMP site implementation that manages proxies and components.
   class Site < Node
     include Components
 
     attr_reader :core_version, :site_settings, :logger, :proxies
 
+    def self.options_class
+      RSMP::Site::Options
+    end
+
     def initialize(options = {})
       super
       initialize_components
@@ -26,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/node/supervisor/supervisor.rb

@@ -1,8 +1,5 @@
-# RSMP supervisor (server)
-# The supervisor waits for sites to connect.
-# Connections to sites are handles via site proxies.
-
 module RSMP
+  # RSMP supervisor (server) that accepts site connections.
   class Supervisor < Node
     include Modules::Configuration
     include Modules::Connection

data/lib/rsmp/node/task.rb

@@ -2,6 +2,7 @@ module RSMP
   class Restart < StandardError
   end
 
+  # Task helpers for starting and managing an Async task lifecycle.
   module Task
     attr_reader :task
 

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