rsmp 0.48.4 → 0.51.0

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

@@ -0,0 +1,158 @@
+require 'psych'
+
+module RSMP
+  module SXL
+    module Processing
+      # A validated SXL YAML document with a normalized component structure.
+      class Document
+        NAME = %r{\A[a-z0-9][a-z0-9_/-]*\z}
+        PREFIX = %r{\A[a-zA-Z0-9_/-]+/\z}
+        MESSAGE_KINDS = %w[alarms statuses commands].freeze
+
+        SymbolDefinition = Struct.new(:id, :kind, :location, keyword_init: true)
+
+        attr_reader :path, :data, :name, :version, :version_string, :minimum_core_version,
+                    :dependencies, :component_types, :message_codes
+
+        def self.load(path)
+          expanded_path = File.expand_path(path)
+          raise Error, "SXL source #{path} not found" unless File.exist?(expanded_path)
+          raise Error, "SXL source #{path} is not a file" unless File.file?(expanded_path)
+
+          parse(File.read(expanded_path, encoding: 'UTF-8'), path: expanded_path)
+        rescue EncodingError => e
+          raise Error, "Cannot read SXL source #{path}: #{e.message}"
+        end
+
+        def self.parse(source, path: '(SXL source)')
+          data = Psych.safe_load(source, permitted_classes: [], permitted_symbols: [], aliases: false)
+          new(path: path, data: data)
+        rescue Psych::Exception => e
+          raise Error, "Cannot read SXL source #{path}: #{e.message}"
+        end
+
+        def self.validate_name!(value, label: 'SXL name')
+          return value if value.is_a?(String) && NAME.match?(value)
+
+          raise Error, "Invalid #{label} #{value.inspect}"
+        end
+
+        def initialize(path:, data:)
+          @path = path
+          @data = normalize_document(require_hash(data, 'document'))
+          read_metadata
+          read_dependencies
+          read_symbols
+        rescue Error => e
+          raise Error, "#{path}: #{e.message}"
+        end
+
+        private
+
+        def normalize_document(document)
+          components = component_definitions(document)
+          document.except('objects').merge('components' => components)
+        end
+
+        def component_definitions(document)
+          if document.key?('components') && document.key?('objects')
+            raise Error, 'Invalid document; use either components or objects, not both'
+          end
+
+          key = document.key?('components') ? 'components' : 'objects'
+          require_hash(document[key], key)
+        end
+
+        def read_metadata
+          meta = require_hash(data['meta'], 'meta')
+          @name = self.class.validate_name!(meta['name'])
+          @version_string = meta['version'].to_s
+          @version = VersionRequirement.exact_version(meta['version'], label: 'SXL version')
+          @minimum_core_version = read_minimum_core_version(meta)
+          @prefix = data['prefix']
+          validate_prefix!
+        end
+
+        def read_minimum_core_version(meta)
+          minimum = meta['minimum_core_version']
+          return unless minimum
+
+          VersionRequirement.exact_version(minimum, label: 'minimum Core version')
+        end
+
+        def validate_prefix!
+          return if @prefix.nil? || (@prefix.is_a?(String) && PREFIX.match?(@prefix))
+
+          raise Error, "Invalid SXL prefix #{@prefix.inspect}; it must end with /"
+        end
+
+        def read_dependencies
+          dependency_data = data['dependencies'] || {}
+          require_hash(dependency_data, 'dependencies')
+          @dependencies = dependency_data.to_h do |dependency_name, requirement|
+            self.class.validate_name!(dependency_name, label: 'dependency name')
+            unless requirement.is_a?(String)
+              raise Error, "Invalid requirement for #{dependency_name.inspect}; expected a string"
+            end
+
+            [dependency_name, VersionRequirement.new(requirement)]
+          end
+        end
+
+        def read_symbols
+          components = data['components']
+          @component_types = []
+          @message_codes = []
+          seen_components = {}
+          seen_messages = {}
+
+          components.each_pair do |component_id, component|
+            component_id = require_identifier(component_id, 'component type')
+            full_component_id = prefixed(component_id)
+            ensure_unique!(seen_components, full_component_id, 'component type')
+            @component_types << SymbolDefinition.new(id: full_component_id, kind: :component,
+                                                     location: component_id)
+            read_component_messages(component_id, component, seen_messages)
+          end
+        end
+
+        def read_component_messages(component_id, component, seen_messages)
+          component = require_hash(component, "component #{component_id.inspect}")
+          MESSAGE_KINDS.each do |kind|
+            messages = component[kind] || {}
+            require_hash(messages, "#{kind} for component #{component_id.inspect}")
+            messages.each_key do |code|
+              code = require_identifier(code, 'message code')
+              full_code = prefixed(code)
+              ensure_unique!(seen_messages, full_code, 'message code')
+              @message_codes << SymbolDefinition.new(id: full_code, kind: kind.delete_suffix('s').to_sym,
+                                                     location: "#{component_id}/#{kind}/#{code}")
+            end
+          end
+        end
+
+        def require_hash(value, label)
+          return value if value.is_a?(Hash)
+
+          raise Error, "Invalid #{label}; expected a mapping"
+        end
+
+        def require_identifier(value, label)
+          return value if value.is_a?(String) && !value.empty?
+
+          raise Error, "Invalid #{label} #{value.inspect}; expected a non-empty string"
+        end
+
+        def prefixed(identifier)
+          "#{@prefix}#{identifier}"
+        end
+
+        def ensure_unique!(seen, identifier, label)
+          raise Error, "Duplicate #{label} #{identifier.inspect}" if seen[identifier]
+
+          seen[identifier] = true
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,8 @@
+module RSMP
+  module SXL
+    module Processing
+      # Base error for SXL dependency and manifest processing.
+      class Error < StandardError; end
+    end
+  end
+end

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