capsium 0.2.0 → 0.6.0

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

@@ -26,6 +26,7 @@ module Capsium
 
       def run
         Dir.mktmpdir do |dir|
+          @workdir = dir
           @package_path = prepare(dir)
           [metadata_check, manifest_check, routes_check,
            storage_check, security_check, content_check]
@@ -58,7 +59,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 +87,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 +96,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 +112,41 @@ 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. For encapsulated
+      # packages the bundled dependencies (packages/, recursively) act
+      # as read-only exported layers exactly as at activation, so
+      # fallthrough routes referencing dependency content validate.
+      def merged_view
+        @merged_view ||= MergedView.new(
+          @package_path,
+          storage: Storage.new(metadata_path(STORAGE_FILE)),
+          manifest: Manifest.new(metadata_path(MANIFEST_FILE)),
+          dependency_views: dependency_views(@package_path)
+        )
+      end
+
+      # The [guid, exported MergedView] layers of the dependencies
+      # bundled under the package directory's packages/ (empty when the
+      # package embeds no bundle).
+      def dependency_views(package_path)
+        bundle = Bundle.new(package_path)
+        return [] unless bundle.present?
+
+        bundle.entries.map do |guid, entry|
+          dependency_dir = File.join(@workdir, "bundles", guid.gsub(/[^A-Za-z0-9.-]/, "_"))
+          Packager.new.unpack(entry.file, dependency_dir)
+          [guid, MergedView.new(
+            dependency_dir,
+            storage: Storage.new(File.join(dependency_dir, STORAGE_FILE)),
+            manifest: Manifest.new(File.join(dependency_dir, MANIFEST_FILE)),
+            dependency_views: dependency_views(dependency_dir),
+            exported_only: true
+          )]
+        end
+      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,34 @@
+# 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 against the
+      # checksum-covered payload, through the signer matching the
+      # declared certificateType (OpenPgpSigner for OpenPGP, the
+      # RSA-SHA256 Signer otherwise). True when the package is unsigned
+      # (nothing declared) or the signature verifies; false on mismatch.
+      def verify_signature = !signed? || Signer.signer_class_for(@path).new(@path).verify
+
+      def verify_signature!
+        Signer.signer_class_for(@path).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