rsmp 0.48.4 → 0.51.1

data/lib/rsmp/sxl/processing/manifest.rb

@@ -0,0 +1,144 @@
+require 'date'
+require 'psych'
+require 'time'
+
+module RSMP
+  module SXL
+    module Processing
+      # Creates and verifies deterministic SXL manifests.
+      module Manifest
+        TOP_LEVEL_KEYS = %w[meta sxls].freeze
+        META_KEYS = %w[created_at created_by format].freeze
+
+        def self.create(documents, format:, now: Time.now)
+          validate_documents!(documents, format)
+          {
+            'meta' => {
+              'created_at' => now.utc.iso8601,
+              'created_by' => "rsmp v#{RSMP::VERSION}",
+              'format' => format.to_s
+            },
+            'sxls' => NaturalSort.sort(documents.map(&:name)).to_h do |name|
+              document = documents.find { |candidate| candidate.name == name }
+              [name, document.version_string]
+            end
+          }
+        end
+
+        def self.dump(manifest)
+          Psych.safe_dump(manifest, permitted_classes: [], aliases: false, line_width: -1)
+        end
+
+        def self.load(path)
+          raise Error, "Manifest #{path} not found" unless File.exist?(path)
+          raise Error, "Manifest #{path} is not a file" unless File.file?(path)
+
+          parse(File.read(path, encoding: 'UTF-8'), path: path)
+        rescue EncodingError => e
+          raise Error, "Cannot read manifest #{path}: #{e.message}"
+        end
+
+        def self.parse(source, path: '(manifest)')
+          Psych.safe_load(source, permitted_classes: [Date, Time], permitted_symbols: [], aliases: false)
+        rescue Psych::Exception => e
+          raise Error, "Cannot read manifest #{path}: #{e.message}"
+        end
+
+        def self.verify!(manifest, catalogue)
+          meta, sxls = validate_shape!(manifest)
+          documents = load_documents!(sxls, catalogue)
+          validate_dependency_closure!(documents, sxls)
+          validate_documents!(documents, meta['format'])
+          documents
+        end
+
+        def self.validate_documents!(documents, format)
+          format_version = VersionRequirement.exact_version(format, label: 'manifest format')
+          documents.each do |document|
+            next unless document.minimum_core_version && document.minimum_core_version > format_version
+
+            raise Error,
+                  "SXL #{document.name} #{document.version_string} requires Core " \
+                  "#{document.minimum_core_version}, newer than manifest format #{format}"
+          end
+          cycle = DependencyGraph.cycle(documents)
+          raise Error, "Cyclic dependency #{cycle.join(' -> ')}" if cycle
+
+          ConflictChecker.check!(documents)
+        end
+
+        def self.validate_shape!(manifest)
+          raise Error, 'Invalid manifest; expected a mapping' unless manifest.is_a?(Hash)
+
+          reject_unknown_keys!(manifest, TOP_LEVEL_KEYS, 'manifest')
+
+          meta = manifest['meta']
+          sxls = manifest['sxls']
+          raise Error, 'Invalid manifest meta; expected a mapping' unless meta.is_a?(Hash)
+          raise Error, 'Invalid manifest sxls; expected a non-empty mapping' unless sxls.is_a?(Hash) && !sxls.empty?
+
+          reject_unknown_keys!(meta, META_KEYS, 'manifest meta')
+          validate_metadata!(meta)
+          validate_sxls!(sxls)
+          [meta, sxls]
+        end
+
+        def self.validate_metadata!(meta)
+          missing = META_KEYS.reject { |key| meta.key?(key) }
+          raise Error, "Manifest meta is missing #{missing.join(', ')}" unless missing.empty?
+
+          Time.iso8601(meta['created_at'].to_s)
+          unless meta['created_by'].is_a?(String) && !meta['created_by'].empty?
+            raise Error, 'Manifest created_by must be a non-empty string'
+          end
+
+          VersionRequirement.exact_version(meta['format'], label: 'manifest format')
+        rescue ArgumentError
+          raise Error, 'Manifest created_at must be an ISO 8601 timestamp'
+        end
+
+        def self.validate_sxls!(sxls)
+          sxls.each_pair do |name, version|
+            Document.validate_name!(name)
+            VersionRequirement.exact_version(version, label: "version for #{name}")
+          end
+          expected_order = NaturalSort.sort(sxls.keys)
+          return if sxls.keys == expected_order
+
+          raise Error, 'Manifest SXLs are not in natural name order'
+        end
+
+        def self.load_documents!(sxls, catalogue)
+          sxls.map do |name, version|
+            document = catalogue.fetch(name, version)
+            raise Error, "SXL #{name} #{version} is not available from the supplied sources" unless document
+
+            document
+          end
+        end
+
+        def self.validate_dependency_closure!(documents, sxls)
+          documents.each do |document|
+            document.dependencies.each_pair do |name, requirement|
+              version = sxls[name]
+              raise Error, "Manifest is missing dependency #{name} required by #{document.name}" unless version
+              next if requirement.satisfied_by?(version)
+
+              raise Error,
+                    "Manifest dependency #{name} #{version} does not satisfy #{requirement.source} " \
+                    "required by #{document.name}"
+            end
+          end
+        end
+
+        def self.reject_unknown_keys!(hash, expected, label)
+          unknown = hash.keys - expected
+          raise Error, "Unknown #{label} key(s): #{unknown.join(', ')}" unless unknown.empty?
+        end
+
+        private_class_method :validate_shape!, :validate_metadata!, :validate_sxls!, :load_documents!,
+                             :validate_dependency_closure!, :reject_unknown_keys!
+      end
+    end
+  end
+end

data/lib/rsmp/sxl/processing/natural_sort.rb

@@ -0,0 +1,22 @@
+module RSMP
+  module SXL
+    module Processing
+      # Natural sorting for identifiers containing decimal digit sequences.
+      module NaturalSort
+        def self.key(value)
+          value.scan(/\d+|\D+/).map do |part|
+            if part.match?(/\A\d+\z/)
+              [0, part.to_i, part.length]
+            else
+              [1, part]
+            end
+          end
+        end
+
+        def self.sort(values)
+          values.sort_by { |value| key(value) }
+        end
+      end
+    end
+  end
+end

data/lib/rsmp/sxl/processing/resolver.rb

@@ -0,0 +1,94 @@
+module RSMP
+  module SXL
+    module Processing
+      # Resolves root requirements to a deterministic set of exact SXL versions.
+      class Resolver
+        def initialize(catalogue)
+          @catalogue = catalogue
+          @diagnostics = []
+        end
+
+        def resolve(root_requirements)
+          constraints = Hash.new { |hash, key| hash[key] = [] }
+          root_requirements.each do |name, requirement|
+            Document.validate_name!(name)
+            constraints[name] << requirement
+          end
+          raise Error, 'At least one root SXL is required' if constraints.empty?
+
+          solution = search({}, constraints)
+          return sorted(solution.values) if solution
+
+          detail = @diagnostics.uniq.first(3).join('; ')
+          raise Error, "Cannot resolve SXL dependencies#{": #{detail}" unless detail.empty?}"
+        end
+
+        private
+
+        def search(selected, constraints)
+          return nil unless selected_versions_valid?(selected, constraints)
+
+          unresolved = NaturalSort.sort(constraints.keys.reject { |name| selected.key?(name) })
+          return selected if unresolved.empty?
+
+          name = unresolved.first
+          candidates = @catalogue.candidates(name, constraints[name])
+          record_missing_candidate(name, constraints[name]) if candidates.empty?
+
+          candidates.each do |document|
+            solution = search_candidate(name, document, selected, constraints)
+            return solution if solution
+          end
+          nil
+        end
+
+        def search_candidate(name, document, selected, constraints)
+          next_selected = selected.merge(name => document)
+          next_constraints = copy_constraints(constraints)
+          document.dependencies.each_pair do |dependency_name, requirement|
+            next_constraints[dependency_name] << requirement
+          end
+
+          cycle = DependencyGraph.cycle(next_selected.values)
+          if cycle
+            @diagnostics << "cyclic dependency #{cycle.join(' -> ')}"
+            return nil
+          end
+
+          search(next_selected, next_constraints)
+        end
+
+        def selected_versions_valid?(selected, constraints)
+          selected.each_pair do |name, document|
+            next if constraints[name].all? { |requirement| requirement.satisfied_by?(document.version) }
+
+            requirements = constraints[name].map(&:source).join(', ')
+            @diagnostics << "#{name} #{document.version_string} does not satisfy #{requirements}"
+            return false
+          end
+          true
+        end
+
+        def record_missing_candidate(name, requirements)
+          available = @catalogue.versions(name)
+          if available.empty?
+            @diagnostics << "no versions available for #{name}"
+          else
+            expected = requirements.map(&:source).join(', ')
+            @diagnostics << "no version of #{name} satisfies #{expected} (available: #{available.join(', ')})"
+          end
+        end
+
+        def copy_constraints(constraints)
+          constraints.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |(name, requirements), copy|
+            copy[name] = requirements.dup
+          end
+        end
+
+        def sorted(documents)
+          documents.sort_by { |document| NaturalSort.key(document.name) }
+        end
+      end
+    end
+  end
+end

data/lib/rsmp/sxl/processing/version_requirement.rb

@@ -0,0 +1,86 @@
+require 'rubygems'
+
+module RSMP
+  module SXL
+    module Processing
+      # Parses the version requirement syntax defined by RSMP Core.
+      class VersionRequirement
+        EXACT_VERSION = /\A(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)\z/
+        PARTIAL_VERSION = /\A(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\.(0|[1-9]\d*))?\z/
+        CLAUSE = /\A(~|>=|<=|>|<)?\s*(\d+(?:\.\d+){1,2})\z/
+
+        attr_reader :source
+
+        def self.exact_version(value, label: 'version')
+          string = value.to_s
+          unless EXACT_VERSION.match?(string)
+            raise Error, "Invalid #{label} #{value.inspect}; expected MAJOR.MINOR.PATCH"
+          end
+
+          Gem::Version.new(string)
+        end
+
+        def initialize(source)
+          @source = source.to_s
+          @predicates = parse(@source)
+        end
+
+        def satisfied_by?(version)
+          version = self.class.exact_version(version) unless version.is_a?(Gem::Version)
+          @predicates.all? { |predicate| predicate.call(version) }
+        end
+
+        private
+
+        def parse(source)
+          raise Error, 'Version requirement cannot be empty' if source.strip.empty?
+
+          source.split(/\s+and\s+/).map { |clause| parse_clause(clause.strip) }
+        end
+
+        def parse_clause(clause)
+          match = CLAUSE.match(clause)
+          raise Error, "Invalid version requirement #{source.inspect}" unless match
+
+          operator = match[1]
+          version_string = match[2]
+          return compatible_predicate(version_string) if operator == '~'
+
+          version = self.class.exact_version(version_string, label: 'requirement version')
+          comparison_predicate(operator || '=', version)
+        end
+
+        def compatible_predicate(version_string)
+          match = PARTIAL_VERSION.match(version_string)
+          raise Error, "Invalid compatibility requirement #{source.inspect}" unless match
+
+          major, minor, patch = match.captures.map { |part| part&.to_i }
+          return major_zero_predicate(major, minor, patch) if major.zero?
+
+          lower = Gem::Version.new("#{major}.#{minor}.#{patch || 0}")
+          upper = Gem::Version.new("#{major + 1}.0.0")
+          ->(version) { version >= lower && version < upper }
+        end
+
+        def major_zero_predicate(major, minor, patch)
+          unless patch
+            raise Error, "Major-zero compatibility requirement #{source.inspect} must include an exact patch version"
+          end
+
+          exact = Gem::Version.new("#{major}.#{minor}.#{patch}")
+          ->(version) { version == exact }
+        end
+
+        def comparison_predicate(operator, expected)
+          case operator
+          when '=' then ->(version) { version == expected }
+          when '>' then ->(version) { version > expected }
+          when '>=' then ->(version) { version >= expected }
+          when '<' then ->(version) { version < expected }
+          when '<=' then ->(version) { version <= expected }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rsmp/sxl/processing.rb

@@ -0,0 +1,18 @@
+require_relative '../version'
+require_relative 'processing/error'
+require_relative 'processing/natural_sort'
+require_relative 'processing/version_requirement'
+require_relative 'processing/document'
+require_relative 'processing/catalogue'
+require_relative 'processing/dependency_graph'
+require_relative 'processing/resolver'
+require_relative 'processing/conflict_checker'
+require_relative 'processing/manifest'
+
+module RSMP
+  module SXL
+    # Dependency resolution, conflict checks, and manifests for SXL definitions.
+    module Processing
+    end
+  end
+end

data/lib/rsmp/sxl/supervisor_interface.rb

@@ -8,12 +8,19 @@ module RSMP
 
       def_delegators :proxy,
                      :request_status,
+                     :request_status!,
                      :request_status_and_collect,
+                     :request_status_and_collect!,
                      :subscribe_to_status,
+                     :subscribe_to_status!,
                      :subscribe_to_status_and_collect,
+                     :subscribe_to_status_and_collect!,
                      :unsubscribe_to_status,
+                     :unsubscribe_to_status!,
                      :send_command,
-                     :send_command_and_collect
+                     :send_command!,
+                     :send_command_and_collect,
+                     :send_command_and_collect!
 
       def process_message(_message); end
     end

data/lib/rsmp/termination.rb

@@ -0,0 +1,10 @@
+module RSMP
+  # An explicit reason for a long-running service task to finish normally.
+  Termination = Data.define(:reason, :source) do
+    def initialize(reason:, source:)
+      raise ArgumentError, 'termination reason must be a Symbol' unless reason.is_a?(Symbol)
+
+      super
+    end
+  end
+end

data/lib/rsmp/tlc/modules/plans.rb

@@ -213,8 +213,6 @@ module RSMP
             end.join(',')
             TrafficControllerSite.make_status times
           end
-        rescue StandardError => e
-          puts e
         end
       end
     end

data/lib/rsmp/tlc/modules/system.rb

@@ -64,7 +64,7 @@ module RSMP
 
         # S0091 - Operator logged in/out OP-panel
         def handle_s0091(_status_code, status_name = nil, options = {})
-          if RSMP::Proxy.version_meets_requirement?(options[:sxl_version], '>=1.1')
+          if RSMP::Proxy.version_meets_requirement?(options[:sxl_version], '>=1.1.0')
             case status_name
             when 'user'
               TrafficControllerSite.make_status 0
@@ -81,7 +81,7 @@ module RSMP
 
         # S0092 - Operator logged in/out web-interface
         def handle_s0092(_status_code, status_name = nil, options = {})
-          if RSMP::Proxy.version_meets_requirement?(options[:sxl_version], '>=1.1')
+          if RSMP::Proxy.version_meets_requirement?(options[:sxl_version], '>=1.1.0')
             case status_name
             when 'user'
               TrafficControllerSite.make_status 0

data/lib/rsmp/tlc/proxy/control.rb

@@ -6,20 +6,29 @@ module RSMP
       module Control
         # M0001 - Set functional position (NormalControl, YellowFlash, Dark).
         def set_functional_position(status, within:, timeout_minutes: 0)
-          validate_ready 'set functional position'
+          readiness = validate_ready 'set functional position'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           command_list = functional_position_command_list(status, timeout_minutes)
           confirm_status = functional_position_confirm_status(status)
-          collector = send_command_and_collect(command_list, within: within)
-          collector.ok!
-          wait_for_status "functional position #{status}", confirm_status, timeout: within unless confirm_status.empty?
-          { collector: collector }
+          send_command_and_collect(command_list, within: within).and_then do |exchange|
+            next Result.success(exchange) if confirm_status.empty?
+
+            wait_for_status("functional position #{status}", confirm_status, timeout: within).map { exchange }
+          end
+        end
+
+        def set_functional_position!(...)
+          set_functional_position(...).value!
         end
 
         # M0005 - Set or clear an emergency route.
         def set_emergency_route(route:, active:, within:)
-          validate_ready 'set emergency route'
+          readiness = validate_ready 'set emergency route'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           security_code = security_code_for(2)
@@ -41,12 +50,18 @@ module RSMP
             'v' => command_value('M0005', 'emergencyroute', route)
           }]
 
-          send_command_and_collect(command_list, within: within).ok!
+          send_command_and_collect(command_list, within: within)
+        end
+
+        def set_emergency_route!(...)
+          set_emergency_route(...).value!
         end
 
         # M0007 - Enable or disable fixed-time control.
         def set_fixed_time(status, within:)
-          validate_ready 'set fixed time'
+          readiness = validate_ready 'set fixed time'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           security_code = security_code_for(2)
@@ -64,13 +79,20 @@ module RSMP
           }]
 
           confirm_status = [{ 'sCI' => 'S0009', 'n' => 'status', 's' => [boolean_value(status)] }]
-          send_command_and_collect(command_list, within: within).ok!
-          wait_for_status "fixed time #{status}", confirm_status, timeout: within
+          send_command_and_collect(command_list, within: within).and_then do |exchange|
+            wait_for_status("fixed time #{status}", confirm_status, timeout: within).map { exchange }
+          end
+        end
+
+        def set_fixed_time!(...)
+          set_fixed_time(...).value!
         end
 
         # M0003 - Set traffic situation (activate a specific situation number).
         def set_traffic_situation(situation, within:)
-          validate_ready 'set traffic situation'
+          readiness = validate_ready 'set traffic situation'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           security_code = security_code_for(2)
@@ -93,13 +115,20 @@ module RSMP
           }]
 
           confirm_status = [{ 'sCI' => 'S0015', 'n' => 'status', 's' => integer_value(situation) }]
-          send_command_and_collect(command_list, within: within).ok!
-          wait_for_status "traffic situation #{situation}", confirm_status, timeout: within
+          send_command_and_collect(command_list, within: within).and_then do |exchange|
+            wait_for_status("traffic situation #{situation}", confirm_status, timeout: within).map { exchange }
+          end
+        end
+
+        def set_traffic_situation!(...)
+          set_traffic_situation(...).value!
         end
 
         # M0003 - Clear the active traffic situation.
         def unset_traffic_situation(within:)
-          validate_ready 'unset traffic situation'
+          readiness = validate_ready 'unset traffic situation'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           security_code = security_code_for(2)
@@ -122,8 +151,13 @@ module RSMP
           }]
 
           confirm_status = [{ 'sCI' => 'S0015', 'n' => 'status', 's' => 1 }]
-          send_command_and_collect(command_list, within: within).ok!
-          wait_for_status 'traffic situation unset', confirm_status, timeout: within
+          send_command_and_collect(command_list, within: within).and_then do |exchange|
+            wait_for_status('traffic situation unset', confirm_status, timeout: within).map { exchange }
+          end
+        end
+
+        def unset_traffic_situation!(...)
+          unset_traffic_situation(...).value!
         end
 
         private

data/lib/rsmp/tlc/proxy/detectors.rb

@@ -7,7 +7,8 @@ module RSMP
         # M0008 - Force detector logic to a given mode and status.
         # component_id must refer to the detector logic component, not main.
         def force_detector_logic(component_id, status:, mode:, within:)
-          validate_ready 'force detector logic'
+          readiness = validate_ready 'force detector logic'
+          return readiness if readiness.failure?
 
           security_code = security_code_for(2)
 
@@ -27,12 +28,18 @@ module RSMP
             'n' => 'mode',
             'v' => command_value('M0008', 'mode', mode)
           }]
-          send_command_and_collect(command_list, component: component_id, within: within).ok!
+          send_command_and_collect(command_list, component: component_id, within: within)
+        end
+
+        def force_detector_logic!(...)
+          force_detector_logic(...).value!
         end
 
         # M0021 - Set the trigger level for traffic counting.
         def set_trigger_level(status, within:)
-          validate_ready 'set trigger level'
+          readiness = validate_ready 'set trigger level'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           security_code = security_code_for(2)
@@ -48,7 +55,11 @@ module RSMP
             'n' => 'securityCode',
             'v' => security_code.to_s
           }]
-          send_command_and_collect(command_list, within: within).ok!
+          send_command_and_collect(command_list, within: within)
+        end
+
+        def set_trigger_level!(...)
+          set_trigger_level(...).value!
         end
       end
     end