rsmp 0.43.2 → 0.45.1

data/lib/rsmp/schema/message_resolution.rb

@@ -0,0 +1,104 @@
+module RSMP
+  # Resolves SXL schemas from message code ownership.
+  module Schema
+    MESSAGE_CODE_EXTRACTORS = {
+      'StatusRequest' => ->(message) { status_codes(message) },
+      'StatusSubscribe' => ->(message) { status_codes(message) },
+      'StatusUnsubscribe' => ->(message) { status_codes(message) },
+      'StatusResponse' => ->(message) { status_codes(message) },
+      'StatusUpdate' => ->(message) { status_codes(message) },
+      'CommandRequest' => ->(message) { request_command_codes(message) },
+      'CommandResponse' => ->(message) { response_command_codes(message) },
+      'Alarm' => ->(message) { alarm_codes(message) }
+    }.freeze
+
+    MESSAGE_CODE_KINDS = {
+      'StatusRequest' => :statuses,
+      'StatusSubscribe' => :statuses,
+      'StatusUnsubscribe' => :statuses,
+      'StatusResponse' => :statuses,
+      'StatusUpdate' => :statuses,
+      'CommandRequest' => :commands,
+      'CommandResponse' => :commands,
+      'Alarm' => :alarms
+    }.freeze
+
+    def self.message_codes(message)
+      extractor = MESSAGE_CODE_EXTRACTORS[message['type']]
+      extractor ? extractor.call(message).uniq : []
+    end
+
+    def self.status_codes(message)
+      (message['sS'] || []).map { |item| item['sCI'] }.compact
+    end
+
+    def self.request_command_codes(message)
+      (message['arg'] || []).map { |item| item['cCI'] }.compact
+    end
+
+    def self.response_command_codes(message)
+      (message['rvs'] || []).map { |item| item['cCI'] }.compact
+    end
+
+    def self.alarm_codes(message)
+      [message['aCId']].compact
+    end
+
+    def self.message_code_kind(message)
+      MESSAGE_CODE_KINDS[message['type']]
+    end
+
+    def self.sxl_defines_codes?(type, version, kind, codes, options)
+      version = sanitize_version(version.to_s) if options[:lenient]
+      catalogue = sxl_catalogue(type, version, kind)
+      prefix = sxl_prefix(type, version, options)
+      codes.all? do |code|
+        unprefixed = prefix && code.start_with?(prefix) ? code[prefix.length..] : code
+        catalogue.key?(code) || catalogue.key?(code.to_sym) ||
+          catalogue.key?(unprefixed) || catalogue.key?(unprefixed.to_sym)
+      end
+    end
+
+    def self.message_code_kind_name(kind)
+      {
+        statuses: 'status',
+        commands: 'command',
+        alarms: 'alarm'
+      }.fetch(kind) { kind.to_s.delete_suffix('s') }
+    end
+
+    def self.resolve_sxl(message, schemas:, **options)
+      kind = message_code_kind(message)
+      codes = message_codes(message)
+      return nil unless kind && codes.any?
+
+      matches = matching_sxl_schemas(schemas, kind, codes, options)
+      raise_if_no_sxl_match(kind, codes) if matches.empty?
+      raise_if_ambiguous_sxl_match(codes, matches) if matches.size > 1
+
+      matches.first
+    end
+
+    def self.matching_sxl_schemas(schemas, kind, codes, options)
+      sxl_schemas(schemas).select do |type, version|
+        sxl_defines_codes?(type, version, kind, codes, options)
+      rescue UnknownSchemaError
+        false
+      end
+    end
+
+    def self.sxl_schemas(schemas)
+      schemas.reject { |type, _version| type.to_sym == :core }
+    end
+
+    def self.raise_if_no_sxl_match(kind, codes)
+      raise UnknownMessageCodeError,
+            "No accepted SXL defines #{message_code_kind_name(kind)} code(s) #{codes.join(', ')}"
+    end
+
+    def self.raise_if_ambiguous_sxl_match(codes, matches)
+      names = matches.map { |type, version| "#{type} #{version}" }.join(', ')
+      raise AmbiguousMessageCodeError, "Message code(s) #{codes.join(', ')} match multiple accepted SXLs: #{names}"
+    end
+  end
+end

data/lib/rsmp/schema/validation.rb

@@ -0,0 +1,57 @@
+module RSMP
+  # Provides JSON Schema validation for RSMP messages across core and SXL versions.
+  module Schema
+    def self.core_message_type?(message)
+      type = message['type']
+      %w[
+        MessageAck
+        MessageNotAck
+        Version
+        ComponentList
+        AggregatedStatus
+        AggregatedStatusRequest
+        Watchdog
+      ].include?(type)
+    end
+
+    def self.validate_core(message, schemas, options)
+      core_version = schemas[:core] || schemas['core']
+      raise ArgumentError, 'schemas must include core' unless core_version
+
+      schema = find_schema! :core, core_version, options
+      validate_using_schema(message, schema)
+    end
+
+    def self.validate_sxls(message, schemas, options)
+      sxl_schemas = schemas.reject { |type, _version| type.to_sym == :core }
+      return [] if sxl_schemas.empty? || core_message_type?(message)
+
+      resolved = resolve_sxl(message, schemas: schemas, **options)
+      return validate_resolved_sxl(message, resolved, schemas, options) if resolved
+
+      all_errors = []
+      sxl_schemas.each do |type, version|
+        schema = find_core_sxl_schema! type, version, schema_core_version(schemas), options
+        errors = validate_using_schema(message, schema)
+        return [] if errors.empty?
+
+        all_errors.concat errors
+      end
+      all_errors
+    end
+
+    # Core must pass. SXL-defined messages pass if at least one SXL schema passes.
+    def self.validate(message, schemas, options = {})
+      raise ArgumentError, 'message missing' unless message
+      raise ArgumentError, 'schemas missing' unless schemas
+      raise ArgumentError, 'schemas must be a Hash' unless schemas.is_a?(Hash)
+      raise ArgumentError, 'schemas cannot be empty' unless schemas.any?
+
+      errors = validate_core(message, schemas, options)
+      errors.concat validate_sxls(message, schemas, options) if errors.empty?
+      return nil if errors.empty?
+
+      errors
+    end
+  end
+end

data/lib/rsmp/schema.rb

@@ -1,4 +1,5 @@
 require 'json_schemer'
+require 'json'
 
 # RSMP (Road Side Message Protocol) schema validation library.
 module RSMP
@@ -8,13 +9,20 @@ module RSMP
 
     def self.setup
       @schemas = {}
-      schemas_path = File.expand_path(File.join(__dir__, '..', '..', 'schemas'))
+      @schema_paths = {}
+      @sxl_indexes = {}
+      @core_sxl_schemas = {}
+      schemas_path = schema_root_path
       Dir.glob("#{schemas_path}/*").select { |f| File.directory? f }.each do |type_path|
         type = File.basename(type_path).to_sym
         load_schema_type type, type_path
       end
     end
 
+    def self.schema_root_path
+      File.expand_path(File.join(__dir__, '..', '..', 'schemas'))
+    end
+
     # load an schema from a folder. schemas are organized by version, and contain
     # json schema files, with the entry point being rsmp.jspon, eg:
     # tlc
@@ -26,23 +34,43 @@ module RSMP
     #
     #  an error is raised if the schema type already exists, and force is not set to true
     def self.load_schema_type(type, type_path, force: false)
-      raise "Schema type #{type} already loaded" if @schemas[type] && force != true
+      type = type.to_sym
+      ensure_schema_type_available(type, force)
 
       @schemas[type] = {}
-      Dir.glob("#{type_path}/*").select { |f| File.directory? f }.each do |schema_path|
-        version = File.basename(schema_path)
-        file_path = File.join(schema_path, 'rsmp.json')
-        next unless File.exist? file_path
-
-        @schemas[type][version] = JSONSchemer.schema(
-          Pathname.new(File.join(schema_path, 'rsmp.json'))
-        )
-      end
+      @schema_paths ||= {}
+      @schema_paths[type] = {}
+      clear_sxl_index(type)
+      clear_core_sxl_schemas(type)
+      schema_version_paths(type_path).each { |schema_path| load_schema_version(type, schema_path) }
+    end
+
+    def self.ensure_schema_type_available(type, force)
+      raise "Schema type #{type} already loaded" if @schemas[type] && force != true
+    end
+
+    def self.schema_version_paths(type_path)
+      Dir.glob("#{type_path}/*").select { |path| File.directory? path }
+    end
+
+    def self.load_schema_version(type, schema_path)
+      version = File.basename(schema_path)
+      file_path = File.join(schema_path, 'rsmp.json')
+      return unless File.exist? file_path
+
+      @schemas[type][version] = JSONSchemer.schema(Pathname.new(file_path))
+      @schema_paths[type][version] = schema_path
+      clear_sxl_index(type, version)
+      clear_core_sxl_schemas(type, version)
     end
 
     # remove a schema type
     def self.remove_schema_type(type)
+      type = type.to_sym
       schemas.delete type
+      @schema_paths&.delete type
+      clear_sxl_index(type)
+      clear_core_sxl_schemas(type)
     end
 
     # get schemas types
@@ -174,37 +202,64 @@ module RSMP
       find_schema(type, version, options) != nil
     end
 
+    def self.sxl_metadata(type, version, options = {})
+      version = sanitize_version version if options[:lenient]
+      find_schema! type, version
+
+      sxl_index(type, version).fetch('meta', {})
+    end
+
+    def self.sxl_prefix(type, version, options = {})
+      sxl_metadata(type, version, options)['prefix']
+    end
+
     # return a catalogue of statuses for a particular schema type and version
     # returns a hash of { status_code_id_sym => [arg_name_sym, ...] }
-    # raises an error if the schema type/version is not found, or has no sxl.yaml
+    # raises an error if the schema type/version is not found, or has no status catalogue
     def self.status_catalogue(type, version)
+      sxl_catalogue(type, version, :statuses).transform_keys(&:to_sym).transform_values do |status|
+        status.fetch('arguments', []).map(&:to_sym)
+      end
+    end
+
+    def self.sxl_catalogue(type, version, kind)
       find_schema! type, version
-      schemas_path = File.expand_path(File.join(__dir__, '..', '..', 'schemas'))
-      yaml_path = File.join(schemas_path, type.to_s, version, 'sxl.yaml')
-      raise "No sxl.yaml for #{type} #{version}" unless File.exist?(yaml_path)
+      catalogue = sxl_index(type, version)[kind.to_s]
+      raise "No #{kind} catalogue for #{type} #{version}" unless catalogue
 
-      sxl = RSMP::Convert::Import::YAML.read(yaml_path)
-      sxl[:statuses].transform_keys(&:to_sym).transform_values do |status|
-        (status['arguments'] || {}).keys.map(&:to_sym)
-      end
+      catalogue
     end
 
-    # validate using a particular schema and version
-    # raises error if schema is not found
-    # return nil if validation succeds, otherwise returns an array of errors
-    def self.validate(message, schemas, options = {})
-      raise ArgumentError, 'message missing' unless message
-      raise ArgumentError, 'schemas missing' unless schemas
-      raise ArgumentError, 'schemas must be a Hash' unless schemas.is_a?(Hash)
-      raise ArgumentError, 'schemas cannot be empty' unless schemas.any?
+    def self.clear_sxl_index(type = nil, version = nil)
+      @sxl_indexes ||= {}
+      return @sxl_indexes.clear unless type
 
-      errors = schemas.flat_map do |type, version|
-        schema = find_schema! type, version, options
-        validate_using_schema(message, schema)
+      type = type.to_sym
+      if version
+        @sxl_indexes.delete([type, version.to_s])
+      else
+        @sxl_indexes.delete_if { |key, _value| key.first == type }
       end
-      return nil if errors.empty?
+    end
+
+    def self.sxl_index(type, version)
+      key = [type.to_sym, version.to_s]
+      @sxl_indexes ||= {}
+      @sxl_indexes[key] ||= load_sxl_index(type, version)
+    end
+
+    def self.load_sxl_index(type, version)
+      schema_path = @schema_paths&.dig(type.to_sym, version.to_s)
+      raise UnknownSchemaVersionError, "Unknown schema version #{type} #{version}" unless schema_path
 
-      errors
+      index_path = File.join(schema_path, 'sxl_index.json')
+      raise Error, "Missing SXL index #{index_path}" unless File.exist?(index_path)
+
+      JSON.parse(File.read(index_path, encoding: 'UTF-8'))
     end
   end
 end
+
+require_relative 'schema/core_sxl_resolution'
+require_relative 'schema/message_resolution'
+require_relative 'schema/validation'

data/lib/rsmp/schema_error.rb

@@ -1,6 +1,6 @@
 module RSMP
   module Schema
-    # Base error class for rsmp_schema.
+    # Base error class for schema validation.
     class Error < StandardError
     end
 
@@ -15,5 +15,11 @@ module RSMP
     # Raised when the requested schema version does not exist.
     class UnknownSchemaVersionError < UnknownSchemaError
     end
+
+    class UnknownMessageCodeError < Error
+    end
+
+    class AmbiguousMessageCodeError < Error
+    end
   end
 end

data/lib/rsmp/sxl/interface.rb

@@ -0,0 +1,48 @@
+require 'forwardable'
+
+module RSMP
+  module SXL
+    # Base interface for SXL-specific behavior on a proxy connection.
+    class Interface
+      extend Forwardable
+
+      def_delegators :proxy, :send_message, :send_message_and_collect, :validate_ready, :log
+
+      attr_reader :proxy, :name, :version
+
+      def initialize(proxy:, name:, version:)
+        @proxy = proxy
+        @name = name
+        @version = version
+      end
+
+      def node
+        proxy.node
+      end
+
+      def components
+        proxy.respond_to?(:components) ? proxy.components : proxy.site.components
+      end
+
+      def main
+        proxy.respond_to?(:main) ? proxy.main : proxy.site.main
+      end
+
+      def sxl_version
+        version
+      end
+
+      def core_version
+        proxy.core_version
+      end
+
+      def use_soc?
+        return false unless core_version
+
+        RSMP::Proxy.version_meets_requirement?(core_version, '>=3.1.5')
+      end
+
+      def validate_message!(_message); end
+    end
+  end
+end

data/lib/rsmp/sxl/registry.rb

@@ -0,0 +1,55 @@
+module RSMP
+  module SXL
+    # Registry of SXL interface classes keyed by SXL name and connection side.
+    module Registry
+      @interfaces = {}
+
+      def self.register(name, side, klass)
+        @interfaces[[name.to_s, side.to_sym]] = klass
+      end
+
+      def self.register_interface(klass)
+        register sxl_name_for(klass), side_for(klass), klass
+      end
+
+      def self.fetch(name, side)
+        @interfaces[[name.to_s, side.to_sym]]
+      end
+
+      def self.build(proxy, sxl, side)
+        klass = fetch(sxl['name'], side) || default_class(side)
+        klass.new(proxy: proxy, name: sxl['name'], version: sxl['version'])
+      end
+
+      def self.build_for(proxy, sxl)
+        case proxy
+        when RSMP::SiteProxy
+          build(proxy, sxl, :supervisor)
+        when RSMP::SupervisorProxy
+          build(proxy, sxl, :site)
+        else
+          raise ArgumentError, "Unknown proxy class #{proxy.class}"
+        end
+      end
+
+      def self.default_class(side)
+        side.to_sym == :site ? SiteInterface : SupervisorInterface
+      end
+
+      def self.side_for(klass)
+        return :site if klass < SiteInterface
+        return :supervisor if klass < SupervisorInterface
+
+        raise ArgumentError, "Cannot infer SXL interface side for #{klass}"
+      end
+
+      def self.sxl_name_for(klass)
+        namespace = klass.name.split('::')[0...-1].join('::')
+        owner = Object.const_get(namespace)
+        return owner.sxl_name if owner.respond_to?(:sxl_name)
+
+        raise ArgumentError, "Cannot infer SXL name for #{klass}"
+      end
+    end
+  end
+end

data/lib/rsmp/sxl/site_interface.rb

@@ -0,0 +1,10 @@
+module RSMP
+  module SXL
+    # SXL interface used by a site-side proxy.
+    class SiteInterface < Interface
+      def process_message(message)
+        proxy.process_sxl_request message
+      end
+    end
+  end
+end

data/lib/rsmp/sxl/supervisor_interface.rb

@@ -0,0 +1,21 @@
+require 'forwardable'
+
+module RSMP
+  module SXL
+    # SXL interface used by a supervisor-side proxy.
+    class SupervisorInterface < Interface
+      extend Forwardable
+
+      def_delegators :proxy,
+                     :request_status,
+                     :request_status_and_collect,
+                     :subscribe_to_status,
+                     :subscribe_to_status_and_collect,
+                     :unsubscribe_to_status,
+                     :send_command,
+                     :send_command_and_collect
+
+      def process_message(_message); end
+    end
+  end
+end

data/lib/rsmp/tlc/detector_logic.rb

@@ -4,8 +4,8 @@ module RSMP
     class DetectorLogic < Component
       attr_reader :forced, :value
 
-      def initialize(node:, id:)
-        super(node: node, id: id, grouped: false)
+      def initialize(node:, id:, type: nil, name: nil)
+        super(node: node, id: id, type: type, name: name, grouped: false)
         @forced = 0
         @value = 0
       end

data/lib/rsmp/tlc/signal_group.rb

@@ -5,8 +5,8 @@ module RSMP
       attr_reader :plan, :state
 
       # plan is a string, with each character representing a signal phase at a particular second in the cycle
-      def initialize(node:, id:)
-        super(node: node, id: id, grouped: false)
+      def initialize(node:, id:, type: nil, name: nil)
+        super(node: node, id: id, type: type, name: name, grouped: false)
       end
 
       def timer

data/lib/rsmp/tlc/site_interface.rb

@@ -0,0 +1,10 @@
+module RSMP
+  # Traffic Light Controller SXL support.
+  module TLC
+    # Site-side TLC SXL interface.
+    class SiteInterface < RSMP::SXL::SiteInterface
+    end
+
+    RSMP::SXL::Registry.register_interface SiteInterface
+  end
+end

data/lib/rsmp/tlc/{traffic_controller_proxy.rb → supervisor_interface.rb}

@@ -1,11 +1,8 @@
-# Proxy for handling communication with a remote Traffic Light Controller (TLC).
-# Provides high-level methods for interacting with TLC functionality.
-# Acts as a mirror of the remote TLC by automatically subscribing to status updates.
-
 module RSMP
+  # Traffic Light Controller SXL support.
   module TLC
-    # Proxy for handling communication with a remote traffic light controller.
-    class TrafficControllerProxy < SiteProxy
+    # Supervisor-side TLC SXL interface.
+    class SupervisorInterface < RSMP::SXL::SupervisorInterface
       include Proxy::Control
       include Proxy::IO
       include Proxy::Plans
@@ -16,16 +13,7 @@ module RSMP
       attr_reader :timeplan_source, :timeplan, :timeouts,
                   :functional_position, :yellow_flash, :traffic_situation
 
-      # Backwards-compatible accessors expected by tests and callers
-      def current_plan
-        @timeplan
-      end
-
-      def plan_source
-        @timeplan_source
-      end
-
-      def initialize(options)
+      def initialize(...)
         super
         @timeplan_source = nil
         @timeplan = nil
@@ -35,6 +23,14 @@ module RSMP
         @timeouts = node.supervisor_settings.dig('default', 'timeouts') || {}
       end
 
+      def current_plan
+        @timeplan
+      end
+
+      def plan_source
+        @timeplan_source
+      end
+
       def subscribe_to_timeplan
         validate_ready 'subscribe to timeplan'
 
@@ -49,32 +45,23 @@ module RSMP
         subscribe_to_status status_list, component: main.c_id
       end
 
-      # Override status update processing to automatically store cached status values.
       def process_status_update(message)
-        super
-
         status_values = message.attribute('sS')
         return unless status_values
 
         status_values.each { |item| cache_status_item(item) }
       end
 
-      # Get all timeplan attributes stored in the main ComponentProxy.
-      def timeplan_attributes
-        main&.statuses&.dig('S0014') || {}
+      def process_message(message)
+        process_status_update message if message.is_a?(RSMP::StatusUpdate)
       end
 
-      # Returns true if sOc (send on change) should be used.
-      # sOc is supported in RSMP core version 3.1.5 and later.
-      def use_soc?
-        return false unless core_version
-
-        RSMP::Proxy.version_meets_requirement?(core_version, '>=3.1.5')
+      def timeplan_attributes
+        main&.statuses&.dig('S0014') || {}
       end
 
       private
 
-      # Automatically subscribe to key TLC statuses to keep proxy in sync.
       def auto_subscribe_to_statuses
         return unless main
 
@@ -82,17 +69,14 @@ module RSMP
         subscribe_to_key_statuses
       end
 
-      # Look up security code for a given level from site settings.
-      # Expects @site_settings['security_codes'] = { 1 => 'code1', 2 => 'code2' }
       def security_code_for(level)
-        codes = @site_settings&.dig('security_codes') || {}
+        codes = proxy.site_settings&.dig('security_codes') || {}
         code = codes[level] || codes[level.to_s]
         raise ArgumentError, "Security code for level #{level} is not configured" unless code
 
         code
       end
 
-      # Process a single status item and update the corresponding cached value.
       def cache_status_item(item)
         case item['sCI']
         when 'S0007' then @functional_position = item['s'] if item['n'] == 'status'
@@ -102,7 +86,6 @@ module RSMP
         end
       end
 
-      # Update cached values for S0014 (timeplan) status attributes.
       def cache_s0014_attribute(item)
         case item['n']
         when 'status' then @timeplan = item['s'].to_i
@@ -110,5 +93,7 @@ module RSMP
         end
       end
     end
+
+    RSMP::SXL::Registry.register_interface SupervisorInterface
   end
 end

data/lib/rsmp/tlc/traffic_controller.rb

@@ -20,8 +20,16 @@ module RSMP
       attr_reader :pos, :cycle_time, :plan, :cycle_counter,
                   :functional_position, :startup_sequence
 
-      def initialize(node:, id:, ntsoid: nil, xnid: nil, **options)
-        super(node: node, id: id, ntsoid: ntsoid, xnid: xnid, grouped: true)
+      def initialize(node:, id:, **options)
+        super(
+          node: node,
+          id: id,
+          type: options[:type],
+          name: options[:name],
+          ntsoid: options[:ntsoid],
+          xnid: options[:xnid],
+          grouped: true
+        )
         @signal_groups = []
         @detector_logics = []
         @plans = options[:signal_plans]

data/lib/rsmp/tlc/traffic_controller_site.rb

@@ -63,6 +63,8 @@ module RSMP
         when 'main'
           TrafficController.new node: self,
                                 id: id,
+                                type: type,
+                                name: settings['name'],
                                 ntsoid: settings['ntsOId'],
                                 xnid: settings['xNId'],
                                 startup_sequence: @startup_sequence,
@@ -70,11 +72,11 @@ module RSMP
                                 live_output: @site_settings['live_output'],
                                 inputs: @site_settings['inputs']
         when 'signal_group'
-          group = SignalGroup.new node: self, id: id
+          group = SignalGroup.new node: self, id: id, type: type, name: settings['name']
           main.add_signal_group group
           group
         when 'detector_logic'
-          logic = DetectorLogic.new node: self, id: id
+          logic = DetectorLogic.new node: self, id: id, type: type, name: settings['name']
           main.add_detector_logic logic
           logic
         end