capsium 0.2.0 → 0.3.0

data/lib/capsium/package/testing/context.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Package
+    module Testing
+      # What a test run needs: the extracted package directory and, when
+      # route tests run, the base URL of the reactor serving the package.
+      Context = Data.define(:package_path, :base_url)
+    end
+  end
+end

data/lib/capsium/package/testing/data_validation_test.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "json"
+require "json-schema"
+require "yaml"
+
+module Capsium
+  class Package
+    module Testing
+      # A "data_validation" test (05x-testing): the rows of the data
+      # file (format: json or yaml) must validate against the JSON
+      # schema file. Array data validates row by row; a single document
+      # validates as one row.
+      class DataValidationTest < TestCase
+        FORMATS = %w[json yaml].freeze
+
+        attr_reader :format, :data_file, :schema_file
+
+        def initialize(name:, format:, data_file:, schema_file:)
+          super(name: name)
+          @format = format
+          @data_file = data_file
+          @schema_file = schema_file
+        end
+
+        def run(context)
+          problems = validation_problems(context)
+          Result.new(name: name, ok: problems.empty?, messages: problems)
+        end
+
+        private
+
+        def validation_problems(context)
+          return ["unsupported data format: #{format}"] unless FORMATS.include?(format)
+
+          schema = load_structured(context, schema_file)
+          rows = load_structured(context, data_file)
+          rows = [rows] unless rows.is_a?(Array)
+          rows.each_with_index.flat_map { |row, index| row_problems(schema, row, index) }
+        rescue Errno::ENOENT, JSON::ParserError, Psych::SyntaxError => e
+          ["cannot load data or schema: #{e.message}"]
+        end
+
+        def load_structured(context, relative_path)
+          full_path = File.join(context.package_path, relative_path.delete_prefix("/"))
+          if File.extname(full_path).match?(/\A\.ya?ml\z/i)
+            YAML.load_file(full_path)
+          else
+            JSON.parse(File.read(full_path))
+          end
+        end
+
+        def row_problems(schema, row, index)
+          JSON::Validator.fully_validate(schema, row).map do |message|
+            "row #{index}: #{message}"
+          end
+        end
+      end
+
+      TestCase.register("data_validation", DataValidationTest)
+    end
+  end
+end

data/lib/capsium/package/testing/file_test.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Package
+    module Testing
+      # A "file" test (05x-testing): the file must exist in the package;
+      # optionally its content must contain a string.
+      class FileTest < TestCase
+        attr_reader :path, :contains
+
+        def initialize(name:, path:, contains: nil)
+          super(name: name)
+          @path = path
+          @contains = contains
+        end
+
+        def run(context)
+          problems = existence_problems(context) + contains_problems(context)
+          Result.new(name: name, ok: problems.empty?, messages: problems)
+        end
+
+        private
+
+        def full_path(context)
+          File.join(context.package_path, path.delete_prefix("/"))
+        end
+
+        def existence_problems(context)
+          return [] if File.file?(full_path(context))
+
+          ["file missing in package: #{path}"]
+        end
+
+        def contains_problems(context)
+          return [] unless contains && File.file?(full_path(context))
+          return [] if File.read(full_path(context)).include?(contains)
+
+          ["file #{path} does not contain #{contains.inspect}"]
+        end
+      end
+
+      TestCase.register("file", FileTest)
+    end
+  end
+end

data/lib/capsium/package/testing/report.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Package
+    module Testing
+      # The outcome of a test suite run: one Result per test case.
+      class Report
+        attr_reader :results
+
+        def initialize(results = [])
+          @results = results
+        end
+
+        def <<(result)
+          @results << result
+          self
+        end
+
+        def ok?
+          @results.all?(&:ok?)
+        end
+
+        def failures
+          @results.reject(&:ok?)
+        end
+
+        def summary
+          "#{@results.size} tests, #{failures.size} failures"
+        end
+      end
+    end
+  end
+end

data/lib/capsium/package/testing/route_test.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Capsium
+  class Package
+    module Testing
+      # A "route" test (05x-testing): requests the URL path from the
+      # reactor serving the package and checks the expected status, and
+      # optionally the content type and a response body substring.
+      class RouteTest < TestCase
+        attr_reader :url, :expected_status, :response_contains, :expected_content_type
+
+        def initialize(name:, url:, expected_status:, response_contains: nil,
+                       expected_content_type: nil)
+          super(name: name)
+          @url = url
+          @expected_status = expected_status
+          @response_contains = response_contains
+          @expected_content_type = expected_content_type
+        end
+
+        def run(context)
+          response = Net::HTTP.get_response(URI.join(context.base_url, request_path))
+          problems = status_problems(response) + content_type_problems(response) +
+                     body_problems(response)
+          Result.new(name: name, ok: problems.empty?, messages: problems)
+        end
+
+        private
+
+        # The DSL allows absolute URLs; only their path (and query) is
+        # used — the runner always targets its own reactor.
+        def request_path
+          uri = URI.parse(url)
+          uri.host ? uri.request_uri : url
+        end
+
+        def status_problems(response)
+          return [] if response.code.to_i == expected_status
+
+          ["expected status #{expected_status}, got #{response.code}"]
+        end
+
+        def content_type_problems(response)
+          return [] unless expected_content_type
+          return [] if response.content_type == expected_content_type
+
+          ["expected content type #{expected_content_type}, got #{response.content_type}"]
+        end
+
+        def body_problems(response)
+          return [] unless response_contains
+          return [] if response.body.to_s.include?(response_contains)
+
+          ["response does not contain #{response_contains.inspect}"]
+        end
+      end
+
+      TestCase.register("route", RouteTest)
+    end
+  end
+end

data/lib/capsium/package/testing/test_case.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Package
+    module Testing
+      # Base class for one test of the Capsium testing YAML DSL
+      # (05x-testing). Subclasses implement a test kind and register
+      # themselves under their DSL type name (open/closed registry).
+      class TestCase
+        # The outcome of running one test.
+        Result = Data.define(:name, :ok, :messages) do
+          def ok? = ok
+        end
+
+        # Raised for invalid test definitions (unknown type,
+        # missing/unknown attributes, non-hash entries).
+        class DefinitionError < Capsium::Error; end
+
+        attr_reader :name
+
+        def initialize(name:)
+          @name = name
+        end
+
+        # Runs the test against the context and returns a Result.
+        def run(context)
+          raise NotImplementedError
+        end
+
+        def self.register(type, klass)
+          types[type] = klass
+        end
+
+        def self.types
+          @types ||= {}
+        end
+
+        # Builds a test case from a YAML definition hash (string keys).
+        def self.build(definition)
+          unless definition.is_a?(Hash)
+            raise DefinitionError, "test definition is not a mapping: #{definition.inspect}"
+          end
+
+          type = definition["type"] ||
+                 raise(DefinitionError, "test #{definition['name'].inspect} has no type")
+          klass = types[type] || raise(DefinitionError, "unknown test type: #{type}")
+          klass.from_h(definition)
+        rescue ArgumentError => e
+          raise DefinitionError, "invalid #{type} test #{definition['name'].inspect}: #{e.message}"
+        end
+
+        def self.from_h(definition)
+          attributes = definition.transform_keys(&:to_sym)
+          attributes.delete(:type)
+          new(**attributes)
+        end
+      end
+    end
+  end
+end

data/lib/capsium/package/testing/test_suite.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "timeout"
+require "yaml"
+
+module Capsium
+  class Package
+    module Testing
+      # Loads and runs the package's tests/*.yaml suites (05x-testing).
+      # Route tests are served by a reactor on an ephemeral port for the
+      # duration of the run. Invalid test definitions are reported as
+      # failed results instead of aborting the run.
+      class TestSuite
+        TESTS_DIR = "tests"
+
+        # Referencing the built-in test kinds triggers their autoload,
+        # which registers them in TestCase.types (each kind file
+        # self-registers on load).
+        BUILTIN_TEST_KINDS = [RouteTest, FileTest, DataValidationTest, ConfigTest].freeze
+
+        attr_reader :package
+
+        def initialize(package)
+          @package = package
+        end
+
+        def test_files
+          Dir.glob(File.join(@package.path, TESTS_DIR, "*.{yaml,yml}"))
+        end
+
+        def run
+          report = Report.new
+          loaded = load_cases(report)
+          with_reactor(loaded) do |base_url|
+            context = Context.new(package_path: @package.path, base_url: base_url)
+            loaded.each { |test_case| report << run_case(test_case, context) }
+          end
+          report
+        end
+
+        private
+
+        def load_cases(report)
+          test_files.flat_map do |file|
+            definitions = YAML.load_file(file)
+            tests = definitions.is_a?(Hash) ? definitions["tests"] : nil
+            Array(tests).map { |definition| TestCase.build(definition) }
+          rescue Psych::SyntaxError, TestCase::DefinitionError => e
+            report << TestCase::Result.new(name: File.basename(file), ok: false,
+                                           messages: [e.message])
+            []
+          end
+        end
+
+        def run_case(test_case, context)
+          test_case.run(context)
+        rescue StandardError => e
+          TestCase::Result.new(name: test_case.name, ok: false,
+                               messages: ["#{e.class}: #{e.message}"])
+        end
+
+        def with_reactor(loaded)
+          return yield nil unless loaded.any?(RouteTest)
+
+          reactor = Capsium::Reactor.new(package: @package, port: 0)
+          server_thread = Thread.new { reactor.server.start }
+          # WEBrick race: shutdown before start reaches :Running would
+          # leave the server running forever.
+          wait_until_running(reactor.server)
+          yield "http://127.0.0.1:#{reactor.server.listeners.first.addr[1]}"
+        ensure
+          shutdown_reactor(reactor, server_thread) if reactor
+        end
+
+        def wait_until_running(server)
+          Timeout.timeout(5) { sleep 0.01 until server.status == :Running }
+        end
+
+        def shutdown_reactor(reactor, server_thread)
+          reactor.server.shutdown
+          server_thread.join
+        end
+      end
+    end
+  end
+end

data/lib/capsium/package/testing.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Package
+    # Runner for the Capsium package testing YAML DSL (05x-testing): a
+    # package declares tests in tests/*.yaml files (top-level "tests"
+    # list) of four kinds — route, file, data_validation and config —
+    # and the suite runner executes them against the package.
+    module Testing
+      autoload :ConfigTest, "capsium/package/testing/config_test"
+      autoload :Context, "capsium/package/testing/context"
+      autoload :DataValidationTest, "capsium/package/testing/data_validation_test"
+      autoload :FileTest, "capsium/package/testing/file_test"
+      autoload :Report, "capsium/package/testing/report"
+      autoload :RouteTest, "capsium/package/testing/route_test"
+      autoload :TestCase, "capsium/package/testing/test_case"
+      autoload :TestSuite, "capsium/package/testing/test_suite"
+    end
+  end
+end

data/lib/capsium/package/validator.rb

@@ -58,7 +58,7 @@ module Capsium
       def manifest_check
         manifest = Manifest.new(metadata_path(MANIFEST_FILE))
         missing = manifest.resources.keys.reject do |path|
-          File.file?(File.join(@package_path, path))
+          merged_view.resolve(path) || File.file?(File.join(@package_path, path))
         end
         result("manifest", missing.map { |path| "resource missing on disk: #{path}" })
       rescue StandardError => e
@@ -86,7 +86,7 @@ module Capsium
         if route.dataset_route? && !route.path.start_with?(Route::DATASET_PATH_PREFIX)
           problems << "dataset route #{route.path} not under #{Route::DATASET_PATH_PREFIX}"
         end
-        route.validate_target(@package_path, storage)
+        route.validate_target(@package_path, storage, merged_view: merged_view)
         problems
       rescue Error => e
         problems + [e.message]
@@ -95,7 +95,7 @@ module Capsium
       def index_problems(routes)
         index = routes.config.index
         return ["index route is missing"] if index.nil?
-        unless File.file?(File.join(@package_path, index))
+        unless merged_view.resolve(index) || File.file?(File.join(@package_path, index))
           return ["index missing on disk: #{index}"]
         end
         return [] if File.extname(index).downcase == ".html"
@@ -111,6 +111,17 @@ module Capsium
         failure("storage", ["storage.json is not valid: #{e.message}"])
       end
 
+      # The merged content view (ARCHITECTURE.md section 5a) over the
+      # package being validated; layered and tombstoned resources resolve
+      # the same way the reactor resolves them.
+      def merged_view
+        @merged_view ||= MergedView.new(
+          @package_path,
+          storage: Storage.new(metadata_path(STORAGE_FILE)),
+          manifest: Manifest.new(metadata_path(MANIFEST_FILE))
+        )
+      end
+
       def security_check
         security = Security.new(metadata_path(SECURITY_FILE))
         return result("security", []) unless security.present?

data/lib/capsium/package/verification.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Package
+    # Integrity and digital-signature verification of a loaded package
+    # (ARCHITECTURE.md section 6), mixed into Package.
+    module Verification
+      # Verifies the package against security.json. Returns a list of
+      # typed errors; empty when no security.json is present or all
+      # checksums match.
+      def verify_integrity
+        @security.present? ? @security.verify(@path) : []
+      end
+
+      def verify_integrity!
+        @security.verify!(@path) if @security.present?
+      end
+
+      # Whether security.json declares a digital signature for this package.
+      def signed? = @security.signed?
+
+      # Verifies the declared digital signature (RSA-SHA256) against the
+      # checksum-covered payload. True when the package is unsigned (nothing
+      # declared) or the signature verifies; false on mismatch.
+      def verify_signature = !signed? || Signer.new(@path).verify
+
+      def verify_signature!
+        Signer.new(@path).verify! if signed?
+      end
+    end
+  end
+end

data/lib/capsium/package/version.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Package
+    # A semantic version (MAJOR.MINOR.PATCH[-prerelease][+build]) with
+    # semver precedence ordering. Build metadata is parsed but ignored
+    # for precedence, per semver.org item 10.
+    class Version
+      include Comparable
+
+      PATTERN = /\A(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?\z/
+
+      attr_reader :major, :minor, :patch, :prerelease
+
+      def self.parse(string)
+        match = PATTERN.match(string.to_s.strip)
+        raise Error, "Invalid semver version: #{string.inspect}" unless match
+
+        new(match[1].to_i, match[2].to_i, match[3].to_i, match[4])
+      end
+
+      def initialize(major, minor, patch, prerelease = nil)
+        @major = major
+        @minor = minor
+        @patch = patch
+        @prerelease = prerelease
+      end
+
+      def <=>(other)
+        core = [major, minor, patch] <=> [other.major, other.minor, other.patch]
+        return core unless core.zero?
+
+        compare_prerelease(other)
+      end
+
+      def to_s
+        "#{major}.#{minor}.#{patch}#{"-#{prerelease}" if prerelease}"
+      end
+
+      private
+
+      # semver.org item 11: a release outranks its prereleases; numeric
+      # identifiers compare numerically and rank below alphanumeric ones;
+      # a longer identifier list outranks a shorter prefix.
+      def compare_prerelease(other)
+        own_rank = prerelease.nil? ? 1 : 0
+        their_rank = other.prerelease.nil? ? 1 : 0
+        return own_rank <=> their_rank unless own_rank == their_rank
+        return 0 if prerelease.nil?
+
+        compare_identifier_lists(prerelease.split("."),
+                                 other.prerelease.split("."))
+      end
+
+      def compare_identifier_lists(own_list, their_list)
+        [own_list.length, their_list.length].max.times do |index|
+          own = own_list[index]
+          theirs = their_list[index]
+          return 1 if theirs.nil?
+          return -1 if own.nil?
+
+          comparison = compare_identifier(own, theirs)
+          return comparison unless comparison.zero?
+        end
+        0
+      end
+
+      def compare_identifier(own, theirs)
+        own_numeric = own.match?(/\A\d+\z/)
+        theirs_numeric = theirs.match?(/\A\d+\z/)
+        return own.to_i <=> theirs.to_i if own_numeric && theirs_numeric
+        return -1 if own_numeric
+        return 1 if theirs_numeric
+
+        own <=> theirs
+      end
+    end
+
+    # A semver range for metadata.dependencies (ARCHITECTURE.md section
+    # 4a), covering the standard's examples: "*", exact versions,
+    # wildcards and partials ("1.x", "1.2.x", "1.2"), caret ("^1.2.3"),
+    # tilde ("~1.2.3"), comparison operators (>=, <=, >, <, =) and
+    # conjunctions joined by comma and/or space (">=1.0.0, <2.0.0").
+    class VersionRange
+      NUMERIC_PART = /\A(\d+)(?:\.(\d+)|\.(?:x|X|\*))?(?:\.(?:\d+|x|X|\*))?(?:-[^\s,]+)?\z/
+      WILDCARD_PART = /\A(?:x|X|\*)\z/
+
+      def self.parse(string)
+        terms = string.to_s.strip.split(/[,\s]+/).reject(&:empty?)
+        return new([[">=", Version.new(0, 0, 0)]]) if terms.empty? || terms == ["*"]
+
+        new(terms.flat_map { |term| expand_term(term) })
+      end
+
+      # Expands one range term to a list of [operator, Version] bounds.
+      def self.expand_term(term)
+        case term
+        when /\A\^(.+)\z/ then caret_bounds_for(Regexp.last_match(1))
+        when /\A~(.+)\z/ then tilde_bounds_for(Regexp.last_match(1))
+        when /\A(>=|<=|>|<|==?)(.+)\z/
+          [[normalize_operator(Regexp.last_match(1)), Version.parse(pad(Regexp.last_match(2)))]]
+        else
+          expand_bare(term)
+        end
+      end
+      private_class_method :expand_term
+
+      # Bare terms: exact versions, partials ("1", "1.2") and wildcards
+      # ("1.x", "1.2.x"). A partial behaves like the same-position
+      # wildcard: "1" is "1.x", "1.2" is "1.2.x".
+      def self.expand_bare(term)
+        raise Error, "Invalid semver range term: #{term.inspect}" unless NUMERIC_PART.match?(term)
+
+        parts = term.split("-", 2).first.split(".")
+        return caret_bounds(Version.new(parts[0].to_i, 0, 0)) if wildcard_at?(parts, 1)
+        return tilde_bounds(Version.new(parts[0].to_i, parts[1].to_i, 0)) if wildcard_at?(parts, 2)
+
+        [["=", Version.parse(term)]]
+      end
+      private_class_method :expand_bare
+
+      def self.wildcard_at?(parts, index)
+        parts.length <= index || WILDCARD_PART.match?(parts[index])
+      end
+      private_class_method :wildcard_at?
+
+      # Pads partial versions ("1.2") with zeros so operators accept them.
+      def self.pad(partial)
+        parts = partial.split("-", 2)
+        core = parts.first.split(".")
+        core << "0" while core.length < 3
+        [core.join("."), parts[1]].compact.join("-")
+      end
+      private_class_method :pad
+
+      # Caret bounds keeping the given precision: "^1" is < 2.0.0 and
+      # "^0.0" is < 0.1.0 (npm semantics); full versions use caret rules.
+      def self.caret_bounds_for(partial)
+        parts = partial.split("-", 2).first.split(".")
+        version = Version.parse(pad(partial))
+        return [[">=", version], ["<", Version.new(version.major + 1, 0, 0)]] if parts.length < 2
+        if parts.length < 3 && version.major.zero?
+          return [[">=", version], ["<", Version.new(0, version.minor + 1, 0)]]
+        end
+
+        caret_bounds(version)
+      end
+      private_class_method :caret_bounds_for
+
+      # Tilde bounds keeping the given precision: "~1" is < 2.0.0.
+      def self.tilde_bounds_for(partial)
+        parts = partial.split("-", 2).first.split(".")
+        version = Version.parse(pad(partial))
+        return [[">=", version], ["<", Version.new(version.major + 1, 0, 0)]] if parts.length < 2
+
+        tilde_bounds(version)
+      end
+      private_class_method :tilde_bounds_for
+
+      def self.caret_bounds(version)
+        upper = if version.major.positive?
+                  Version.new(version.major + 1, 0, 0)
+                elsif version.minor.positive?
+                  Version.new(0, version.minor + 1, 0)
+                else
+                  Version.new(0, 0, version.patch + 1)
+                end
+        [[">=", version], ["<", upper]]
+      end
+      private_class_method :caret_bounds
+
+      def self.tilde_bounds(version)
+        [[">=", version], ["<", Version.new(version.major, version.minor + 1, 0)]]
+      end
+      private_class_method :tilde_bounds
+
+      def self.normalize_operator(operator)
+        operator == "==" ? "=" : operator
+      end
+      private_class_method :normalize_operator
+
+      def initialize(bounds)
+        @bounds = bounds
+      end
+
+      def satisfied_by?(version)
+        version = Version.parse(version) unless version.is_a?(Version)
+        @bounds.all? { |operator, bound| holds?(operator, version <=> bound) }
+      end
+
+      private
+
+      def holds?(operator, comparison)
+        case operator
+        when ">=" then comparison >= 0
+        when "<=" then comparison <= 0
+        when ">" then comparison.positive?
+        when "<" then comparison.negative?
+        else comparison.zero?
+        end
+      end
+    end
+  end
+end