capsium 0.1.2 → 0.3.0

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

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "json"
+require "marcel"
+require "pathname"
+require "tmpdir"
+
+module Capsium
+  class Package
+    # Validates a package directory or .cap file against the canonical
+    # schemas (ARCHITECTURE.md sections 2-6) and reports one result per
+    # check. Used by `capsium package validate`.
+    class Validator
+      CheckResult = Data.define(:name, :ok, :messages) do
+        def ok?
+          ok
+        end
+      end
+
+      EXTERNAL_REFERENCE_PATTERN = %r{(?:src|href)\s*=\s*["']https?://}in
+      TEXT_CONTENT_MIME = %r{\Atext/|application/(json|javascript|xml)|image/svg\+xml}
+
+      def initialize(package_path)
+        @given_path = package_path
+      end
+
+      def run
+        Dir.mktmpdir do |dir|
+          @package_path = prepare(dir)
+          [metadata_check, manifest_check, routes_check,
+           storage_check, security_check, content_check]
+        end
+      end
+
+      def valid?
+        run.all?(&:ok?)
+      end
+
+      private
+
+      def prepare(dir)
+        return @given_path if File.directory?(@given_path)
+
+        destination = File.join(dir, "package")
+        Packager.new.unpack(@given_path, destination)
+        destination
+      end
+
+      def metadata_check
+        path = metadata_path(METADATA_FILE)
+        return failure("metadata", ["metadata.json is missing"]) unless File.exist?(path)
+
+        result("metadata", Metadata.new(path).config.format_errors)
+      rescue StandardError => e
+        failure("metadata", ["metadata.json is not valid: #{e.message}"])
+      end
+
+      def manifest_check
+        manifest = Manifest.new(metadata_path(MANIFEST_FILE))
+        missing = manifest.resources.keys.reject do |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
+        failure("manifest", ["manifest.json is not valid: #{e.message}"])
+      end
+
+      def routes_check
+        manifest = Manifest.new(metadata_path(MANIFEST_FILE))
+        storage = Storage.new(metadata_path(STORAGE_FILE))
+        routes = Routes.new(metadata_path(ROUTES_FILE), manifest, storage)
+        problems = route_problems(routes, storage) + index_problems(routes)
+        result("routes", problems)
+      rescue StandardError => e
+        failure("routes", ["routes.json is not valid: #{e.message}"])
+      end
+
+      def route_problems(routes, storage)
+        routes.config.routes.flat_map do |route|
+          route_target_problems(route, storage)
+        end
+      end
+
+      def route_target_problems(route, storage)
+        problems = []
+        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, merged_view: merged_view)
+        problems
+      rescue Error => e
+        problems + [e.message]
+      end
+
+      def index_problems(routes)
+        index = routes.config.index
+        return ["index route is missing"] if index.nil?
+        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"
+
+        ["index is not an HTML file: #{index}"]
+      end
+
+      def storage_check
+        storage = Storage.new(metadata_path(STORAGE_FILE))
+        problems = storage.datasets.flat_map(&:validation_errors)
+        result("storage", problems)
+      rescue StandardError => e
+        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?
+
+        result("security", security.verify(@package_path).map(&:message))
+      end
+
+      def content_check
+        offenders = Dir.glob(File.join(@package_path, CONTENT_DIR, "**", "*")).select do |file|
+          File.file?(file) && text_file?(file) &&
+            File.binread(file).match?(EXTERNAL_REFERENCE_PATTERN)
+        end
+        result("content", offenders.map do |file|
+          "external reference in #{file.delete_prefix("#{@package_path}/")}"
+        end)
+      end
+
+      def text_file?(path)
+        mime = Marcel::MimeType.for(Pathname.new(path), name: File.basename(path))
+        mime.match?(TEXT_CONTENT_MIME)
+      end
+
+      def metadata_path(file_name)
+        File.join(@package_path, file_name)
+      end
+
+      def result(name, problems)
+        CheckResult.new(name: name, ok: problems.empty?, messages: problems)
+      end
+
+      def failure(name, messages)
+        CheckResult.new(name: name, ok: false, messages: messages)
+      end
+    end
+  end
+end

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