rsmp-validator 0.1.0

data/lib/rsmp/validator/config_normalizer.rb

@@ -0,0 +1,103 @@
+module RSMP
+  module Validator
+    # Normalizes configuration settings before passing them to RSMP nodes.
+    module ConfigNormalizer
+      def self.normalize_site_settings(settings)
+        normalized = deep_dup(settings)
+
+        if normalized['security_codes'].nil? && normalized.dig('secrets', 'security_codes').is_a?(Hash)
+          normalized['security_codes'] = deep_dup(normalized['secrets']['security_codes'])
+        end
+
+        normalize_security_codes!(normalized)
+        normalize_input_programming!(normalized)
+        normalize_sxls_for_config!(normalized)
+
+        normalized
+      end
+
+      def self.normalize_supervisor_settings(settings)
+        normalized = deep_dup(settings)
+        normalize_sxls_for_config!(normalized)
+        normalized
+      end
+
+      def self.normalize_security_codes!(settings)
+        codes = settings['security_codes']
+        return unless codes.is_a?(Hash)
+
+        settings['security_codes'] = codes.each_with_object({}) do |(key, value), memo|
+          int_key = key.is_a?(String) && key.match?(/^\d+$/) ? key.to_i : key
+          memo[int_key] = value
+        end
+      end
+
+      def self.normalize_input_programming!(settings)
+        programming = settings.dig('inputs', 'programming')
+        return unless programming.is_a?(Hash)
+
+        normalized = normalize_programming_keys(programming)
+        return unless normalized.keys.all?(Integer)
+
+        settings['inputs'] ||= {}
+        settings['inputs']['programming'] = build_programming_array(normalized)
+      end
+
+      def self.normalize_programming_keys(programming)
+        programming.each_with_object({}) do |(key, value), memo|
+          int_key = key.is_a?(String) && key.match?(/^\d+$/) ? key.to_i : key
+          memo[int_key] = value
+        end
+      end
+
+      def self.build_programming_array(normalized)
+        max_key = normalized.keys.max
+        program_array = Array.new(max_key + 1)
+        normalized.each do |index, value|
+          program_array[index] = value
+        end
+        program_array
+      end
+
+      def self.normalize_sxls_for_config!(value)
+        case value
+        when Hash
+          value.each do |key, child|
+            value[key] = sxls_array_to_hash(child) if key == 'sxls'
+            normalize_sxls_for_config!(value[key])
+          end
+        when Array
+          value.each { |item| normalize_sxls_for_config!(item) }
+        end
+      end
+
+      def self.sxls_array_to_hash(value)
+        return value unless value.is_a?(Array)
+
+        value.each_with_object({}) do |item, memo|
+          next unless item.is_a?(Hash)
+
+          name = item['name']
+          next unless name
+
+          sxl = item.dup
+          sxl.delete('name')
+          version = sxl.delete('version')
+          sxl.delete('prefix')
+          memo[name] = sxl.empty? ? version : sxl.merge('version' => version)
+        end
+      end
+
+      def self.deep_dup(value)
+        case value
+        when Hash
+          value.transform_values { |v| deep_dup(v) }
+        when Array
+          value.map { |item| deep_dup(item) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/rsmp/validator/configuration/loader.rb

@@ -0,0 +1,79 @@
+module RSMP
+  module Validator
+    module Configuration
+      # Private helpers for loading YAML config files and building options objects.
+      module Loader
+        private
+
+        def build_tester_options(raw_config, config_path)
+          options_class = tester_options_class_for(raw_config)
+          build_options_from_raw(raw_config, config_path, options_class)
+        end
+
+        def apply_loaded_config(options)
+          self.config = options.to_h
+          self.config_log_settings = options.log_settings
+        end
+
+        def load_yaml_config!(path, using_message:, missing_message:)
+          ensure_config_exists!(path, missing_message)
+          @log_stream.puts using_message if using_message && !using_message.empty?
+          raw = YAML.load_file(path)
+          validate_config_hash!(raw, path)
+          raw || {}
+        rescue Psych::SyntaxError => e
+          raise RSMP::ConfigurationError, "Cannot read config file #{path}: #{e}"
+        end
+
+        def ensure_config_exists!(path, missing_message)
+          abort_with_error missing_message unless File.exist?(path)
+        end
+
+        def validate_config_hash!(raw, path)
+          return if raw.is_a?(Hash) || raw.nil?
+
+          raise RSMP::ConfigurationError, "Config #{path} must be a hash"
+        end
+
+        def build_options_from_raw(raw, path, option_class)
+          log_settings = raw.is_a?(Hash) ? raw['log'] : nil
+          options_hash = raw.is_a?(Hash) ? raw.dup : {}
+          options_hash.delete('log') if options_hash.is_a?(Hash)
+
+          option_class.new(options_hash, source: path, log_settings: log_settings)
+        rescue RSMP::ConfigurationError => e
+          abort_with_error e.message
+        end
+
+        def tester_options_class_for(_raw)
+          case mode
+          when :site
+            RSMP::Validator::SiteTest::Options
+          when :supervisor
+            RSMP::Validator::SupervisorTest::Options
+          else
+            abort_with_error "Unknown test mode: #{mode}"
+          end
+        end
+
+        def auto_node_options_class_for(raw)
+          case mode
+          when :site
+            site_options_class_for(raw)
+          when :supervisor
+            RSMP::Supervisor::Options
+          else
+            abort_with_error "Unknown test mode: #{mode}"
+          end
+        end
+
+        def site_options_class_for(raw)
+          return RSMP::Site::Options unless raw.is_a?(Hash)
+
+          type = raw['type']
+          type == 'tlc' ? RSMP::TLC::TrafficControllerSite::Options : RSMP::Site::Options
+        end
+      end
+    end
+  end
+end

data/lib/rsmp/validator/configuration/secrets.rb

@@ -0,0 +1,54 @@
+module RSMP
+  module Validator
+    module Configuration
+      # Private helpers for loading and normalizing secrets configuration.
+      module Secrets
+        private
+
+        def load_secrets(config_path)
+          load_secrets_file(config_path) unless config['secrets']
+          normalize_security_codes!
+          warn_missing_security_codes
+        end
+
+        def load_secrets_file(config_path)
+          basename = File.basename(config_path, '.yaml')
+          folder = File.dirname(config_path)
+          secrets_path = File.join(folder, "#{basename}_secrets.yaml")
+          return unless File.exist?(secrets_path)
+
+          config['secrets'] = YAML.load_file(secrets_path)
+        rescue Psych::SyntaxError => e
+          abort_with_error "Cannot read secrets file #{secrets_path}: #{e}"
+        end
+
+        def normalize_security_codes!
+          codes = config.dig('secrets', 'security_codes')
+          return unless codes.is_a?(Hash)
+
+          normalized = codes.each_with_object({}) do |(key, value), memo|
+            int_key = key.is_a?(String) && key.match?(/^\d+$/) ? key.to_i : key
+            memo[int_key] = value
+          end
+
+          config['secrets']['security_codes'] = normalized
+        end
+
+        def warn_missing_security_codes
+          return warn_no_security_code unless config.dig('secrets', 'security_codes')
+
+          warn_security_code_not_configured(1) unless config.dig('secrets', 'security_codes', 1)
+          warn_security_code_not_configured(2) unless config.dig('secrets', 'security_codes', 2)
+        end
+
+        def warn_no_security_code
+          log 'Warning: No security code configured', level: :warning
+        end
+
+        def warn_security_code_not_configured(index)
+          log "Warning: Security code #{index} is not configured", level: :warning
+        end
+      end
+    end
+  end
+end

data/lib/rsmp/validator/configuration/validation.rb

@@ -0,0 +1,115 @@
+module RSMP
+  module Validator
+    module Configuration
+      # Private helpers for validating and normalizing configuration values.
+      module Validation
+        private
+
+        def validate_mode_config!(config_path)
+          case mode
+          when :supervisor
+            validate_supervisor_mode_config!(config_path)
+          when :site
+            validate_site_mode_config!(config_path)
+          end
+        end
+
+        def validate_supervisor_mode_config!(config_path)
+          return if config['local_site'] && !top_level_site_settings?
+
+          if top_level_site_settings?
+            abort_with_error <<~HEREDOC
+              Error:
+              The config file at #{config_path} contains site settings at the top level.
+              For supervisor testing, put site settings under 'local_site'.
+              Check that you're using the right config file, or fix the config.
+            HEREDOC
+          else
+            abort_with_error <<~HEREDOC
+              Error:
+              The config file at #{config_path} is missing 'local_site'.
+              For supervisor testing, the config must describe the local site used during testing.
+              Check that you're using the right config file, or fix the config.
+            HEREDOC
+          end
+        end
+
+        def validate_site_mode_config!(config_path)
+          return if config['local_supervisor'] && !top_level_supervisor_settings?
+
+          if top_level_supervisor_settings?
+            abort_with_error <<~HEREDOC
+              Error:
+              The config file at #{config_path} contains supervisor settings at the top level.
+              For site testing, put supervisor settings under 'local_supervisor'.
+              Check that you're using the right config file, or fix the config.
+            HEREDOC
+          else
+            abort_with_error <<~HEREDOC
+              Error:
+              The config file at #{config_path} is missing 'local_supervisor'.
+              For site testing, the config must describe the local supervisor used during testing.
+              Check that you're using the right config file, or fix the config.
+            HEREDOC
+          end
+        end
+
+        def top_level_site_settings?
+          %w[site_id supervisors type].any? { |key| config.key?(key) }
+        end
+
+        def top_level_supervisor_settings?
+          %w[port ips max_sites].any? { |key| config.key?(key) }
+        end
+
+        def validate_components_config!
+          abort_with_error "Error: config 'components' settings is missing or empty" if config['components'] == {}
+
+          main_component = config.dig('components', 'main')&.keys&.first
+          abort_with_error "Error: config 'main' component settings is missing or empty" unless main_component
+
+          config['main_component'] = main_component
+        end
+
+        def validate_timeouts_config!
+          timeouts = config['timeouts']
+          abort_with_error "Error: config 'timeouts' settings is missing or empty" if timeouts.nil? || timeouts == {}
+        end
+
+        def normalize_core_version!
+          core_version = ENV['CORE_VERSION'] || config['core_version'] || RSMP::Schema.latest_core_version
+          core_version = RSMP::Schema.latest_core_version if core_version == 'latest'
+
+          known_versions = RSMP::Schema.core_versions
+          normalized = normalized_core_version(core_version, known_versions)
+          return config['core_version'] = normalized.to_s if normalized
+
+          abort_with_error "Unknown core version #{core_version}, must be one of [#{known_versions.join(', ')}]."
+        end
+
+        def normalized_core_version(core_version, known_versions)
+          known_versions.map { |v| Gem::Version.new(v) }.sort.reverse.detect do |v|
+            Gem::Requirement.new(core_version).satisfied_by?(v)
+          end
+        end
+
+        def normalize_sxls!
+          sxls = config['sxls']
+          if sxls.nil?
+            config['sxls'] = [{ 'name' => 'tlc', 'version' => RSMP::Schema.latest_version(:tlc) }]
+            return
+          end
+
+          sxls.each do |sxl|
+            name = sxl['name']
+            abort_with_error 'SXL name cannot be core.' if name.to_s == 'core'
+
+            RSMP::Schema.find_schema! name, sxl['version'], lenient: true
+          rescue RSMP::Schema::UnknownSchemaError => e
+            abort_with_error "Unknown SXL #{name} #{sxl['version']}: #{e}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rsmp/validator/configuration.rb

@@ -0,0 +1,129 @@
+require 'yaml'
+require_relative 'configuration/loader'
+require_relative 'configuration/validation'
+require_relative 'configuration/secrets'
+
+module RSMP
+  module Validator
+    # Handles loading and validating validator configuration files.
+    module Configuration
+      include Loader
+      include Validation
+      include Secrets
+
+      def load_tester_config
+        config_path = get_config_path
+        raw_config = load_yaml_config!(
+          config_path,
+          using_message: "Using #{mode} config: #{config_path}",
+          missing_message: "#{mode.capitalize} config file #{config_path} is missing"
+        )
+
+        apply_env_overrides!(raw_config)
+        options = build_tester_options(raw_config, config_path)
+        apply_loaded_config(options)
+        validate_and_finalize_config!(config_path)
+      end
+
+      def apply_env_overrides!(raw_config)
+        raw_config['core_version'] = ENV['CORE_VERSION'] if ENV['CORE_VERSION']
+        raw_config['sxls'] = parse_sxls(ENV['SXLS']) if ENV['SXLS']
+      end
+
+      def validate_and_finalize_config!(config_path)
+        validate_mode_config!(config_path)
+        validate_components_config!
+        validate_timeouts_config!
+        normalize_core_version!
+        normalize_sxls!
+        load_secrets config_path
+      end
+
+      def load_auto_node_config
+        path = auto_node_config_path
+        return unless path
+
+        @log_stream.puts "Will run auto #{mode} with config: #{path}"
+        raw_config = load_yaml_config!(
+          path,
+          using_message: '',
+          missing_message: "Auto #{mode} config file #{path} is missing"
+        )
+        raw_config['sxls'] = parse_sxls(ENV['SXLS']) if ENV['SXLS']
+        options_class = auto_node_options_class_for(raw_config)
+        options = build_options_from_raw(raw_config, path, options_class)
+        self.auto_node_config = options.to_h
+        self.auto_node_log_settings = options.log_settings
+      end
+
+      def get_config_path(local: false)
+        mode_name = mode.to_s
+        config_path = get_config_path_from_env(mode_name) || get_config_path_from_validator_yaml(mode_name)
+        abort_with_error "#{mode_name.capitalize} config path not set" unless config_path && config_path != ''
+
+        config_path = File.expand_path(config_path) if local
+        config_path
+      end
+
+      def auto_node_config_path
+        env_key = mode == :site ? 'AUTO_SITE_CONFIG' : 'AUTO_SUPERVISOR_CONFIG'
+        env_path = ENV.fetch(env_key, nil)
+        return env_path if env_path && !env_path.empty?
+
+        ref_path = 'config/validator.yaml'
+        return nil unless File.exist? ref_path
+
+        config_ref = YAML.load_file ref_path
+        key = mode == :site ? 'auto_site' : 'auto_supervisor'
+        path = config_ref[key].to_s.strip
+        path.empty? ? nil : path
+      end
+
+      def get_config(*path, **options)
+        value = config.dig(*path)
+        return value if value
+
+        path_name = path.inspect
+        default = options[:default]
+        assume = options[:assume]
+        if default
+          warning "Config #{path_name} not found, using default: #{default}"
+          default
+        elsif assume
+          assume
+        else
+          raise "Config #{path_name} is missing"
+        end
+      end
+
+      private
+
+      def get_config_path_from_env(mode_name)
+        key = "#{mode_name.upcase}_CONFIG"
+        ENV.fetch(key, nil)
+      end
+
+      def get_config_path_from_validator_yaml(mode_name)
+        ref_path = 'config/validator.yaml'
+        return nil unless File.exist? ref_path
+
+        config_ref = YAML.load_file ref_path
+        config_ref[mode_name].to_s.strip
+      end
+
+      def warning(message)
+        log "Warning: #{message}", level: :warning
+      end
+
+      def parse_sxls(value)
+        value.split(',').each_with_object({}) do |item, memo|
+          parts = item.split(':')
+          abort_with_error "Invalid SXLS item #{item.inspect}, expected name:version" unless parts.length == 2
+
+          name, version = parts
+          memo[name] = version
+        end
+      end
+    end
+  end
+end

data/lib/rsmp/validator/helpers/alarms.rb

@@ -0,0 +1,66 @@
+module RSMP
+  module Validator
+    module Helpers
+      # Helper methods for testing RSMP alarm behaviour.
+      module Alarms
+        include Input
+
+        def with_alarm_activated(site_proxy, alarm_code_id, initial_deactivation: true, &block)
+          input, component_id = find_alarm_programming(alarm_code_id)
+          component_id ||= RSMP::Validator.get_config('main_component')
+          timeout = RSMP::Validator.get_config('timeouts', 'status_update')
+          force_input_and_confirm(site_proxy, input:, value: 'False', within: timeout) if initial_deactivation
+          run_alarm_lifecycle(site_proxy, alarm_code_id, component_id, input, &block)
+        end
+
+        private
+
+        def run_alarm_lifecycle(site_proxy, alarm_code_id, component_id, input)
+          specialization, alarm_active, alarm_inactive = build_alarm_matchers(site_proxy)
+          alarm_timeout = RSMP::Validator.get_config('timeouts', 'alarm')
+          status_timeout = RSMP::Validator.get_config('timeouts', 'status_update')
+          state = false
+          begin
+            matcher = { 'cId' => component_id, 'aCId' => alarm_code_id,
+                        'aSp' => specialization, 'aS' => alarm_active }
+            collect_task = start_alarm_collector(site_proxy, matcher, alarm_timeout)
+            force_input_and_confirm site_proxy, input:, value: 'True', within: status_timeout
+            state = true
+            yield collect_task.wait, component_id
+
+            matcher = { 'cId' => component_id, 'aCId' => alarm_code_id,
+                        'aSp' => /Issue/i, 'aS' => alarm_inactive }
+            collect_task = start_alarm_collector(site_proxy, matcher, alarm_timeout)
+            force_input_and_confirm site_proxy, input:, value: 'False', within: status_timeout
+            state = false
+            [collect_task.wait, component_id]
+          ensure
+            force_input_and_confirm(site_proxy, input:, value: 'False', within: status_timeout) if state == true
+          end
+        end
+
+        def build_alarm_matchers(site_proxy)
+          if RSMP::Proxy.version_meets_requirement? site_proxy.core_version, '>=3.2'
+            [/Issue/, /Active/, /inActive/]
+          else
+            [/issue/i, /active/i, /inactive/i]
+          end
+        end
+
+        def start_alarm_collector(site_proxy, matcher, timeout)
+          Async::Task.current.async do
+            collector = RSMP::AlarmCollector.new(site_proxy, num: 1, matcher: matcher, timeout: timeout)
+            collector.collect!
+            collector.messages.first
+          end
+        end
+
+        def find_alarm_programming(alarm_code_id)
+          action = RSMP::Validator.config.dig('alarm_triggers', alarm_code_id)
+          skip "Alarm trigger #{alarm_code_id} not configured" unless action
+          [action['input'], action['component']]
+        end
+      end
+    end
+  end
+end

data/lib/rsmp/validator/helpers/clock.rb

@@ -0,0 +1,16 @@
+module RSMP
+  module Validator
+    module Helpers
+      # Helper methods for testing RSMP clock functionality.
+      module Clock
+        def with_clock_set(site_proxy, clock, within:)
+          site_proxy.tlc.set_clock(clock, within:)
+          site_proxy.clear_alarm_timestamps
+          yield
+        ensure
+          site_proxy.tlc.set_clock(Time.now.utc, within:)
+        end
+      end
+    end
+  end
+end

data/lib/rsmp/validator/helpers/connection.rb

@@ -0,0 +1,73 @@
+module RSMP
+  module Validator
+    module Helpers
+      # Helpers for connecting to a site or supervisor in tests, with optional
+      # version-based skipping via sxl: and core: keyword arguments.
+      #
+      # with_site(:connected, sxl: '>=1.2') do |supervisor, site_proxy|
+      #   ...
+      # end
+      #
+      # with_supervisor(:connected, core: '>=3.2') do |site, supervisor_proxy|
+      #   ...
+      # end
+      module Connection
+        VALID_STATES = %i[connected reconnected isolated disconnected].freeze
+
+        # Wraps an uncaught exception from a test block, preserving the original
+        # class name, message, and backtrace for clearer test failure output.
+        class UncaughtException < StandardError
+          def initialize(original)
+            super("#{original.class}: #{original.message}")
+            set_backtrace(original.backtrace)
+          end
+        end
+
+        def with_site(state, sxl: nil, core: nil, **opts, &block)
+          validate_state!(state)
+          check_version_requirements(sxl, core)
+          if state == :disconnected
+            RSMP::Validator::SiteTester.disconnected { block.call }
+          else
+            RSMP::Validator::SiteTester.public_send(state, **opts) do |_task, _node, proxy|
+              block.call(proxy)
+            rescue RSMP::TimeoutError => e
+              @__assertions__.assert false, e.message
+            rescue StandardError => e
+              @__assertions__.error!(UncaughtException.new(e))
+            end
+          end
+        end
+
+        def with_supervisor(state, sxl: nil, core: nil, **opts, &block)
+          validate_state!(state)
+          check_version_requirements(sxl, core)
+          if state == :disconnected
+            RSMP::Validator::SupervisorTester.disconnected { block.call }
+          else
+            RSMP::Validator::SupervisorTester.public_send(state, **opts) do |_task, _node, proxy|
+              block.call(proxy)
+            rescue RSMP::TimeoutError => e
+              @__assertions__.assert false, e.message
+            rescue StandardError => e
+              @__assertions__.error!(UncaughtException.new(e))
+            end
+          end
+        end
+
+        private
+
+        def validate_state!(state)
+          return if VALID_STATES.include?(state)
+
+          raise ArgumentError, "Unknown state #{state.inspect}, must be one of #{VALID_STATES}"
+        end
+
+        def check_version_requirements(sxl, core)
+          skip "requires sxl #{sxl}" unless sxl.nil? || RSMP::Validator.sxl_matches?(sxl)
+          skip "requires core #{core}" unless core.nil? || RSMP::Validator.core_matches?(core)
+        end
+      end
+    end
+  end
+end