capsium 0.2.0 → 0.3.0

data/sig/capsium/package/merged_view.rbs

@@ -0,0 +1,46 @@
+module Capsium
+  class Package
+    # The merged (overlay) view of a package's content, per ARCHITECTURE.md
+    # section 5a. Shared by Package (validation) and Reactor (serving).
+    class MergedView
+      # A single read layer: an absolute root directory mirroring the
+      # content/ tree, plus its parsed tombstone set.
+      class Layer
+        def self.new: (String root, String visibility, Set[String] tombstones) -> void
+
+        def file?: (String content_relative_path) -> bool
+
+        def absolute: (String content_relative_path) -> String
+
+        def root: () -> String
+
+        def visibility: () -> String
+
+        def tombstones: () -> Set[String]
+      end
+
+      TOMBSTONE_FILE: String
+      CONTENT_PREFIX: String
+
+      attr_reader package_path: String
+      attr_reader layers: Array[Layer]
+      attr_reader dependency_views: Array[[String, MergedView]]
+
+      def initialize: (String package_path, storage: Storage storage,
+                       manifest: Manifest manifest,
+                       ?dependency_views: Array[[String, MergedView]] dependency_views,
+                       ?exported_only: bool exported_only) -> void
+
+      # The absolute filesystem path serving a resource reference: a
+      # package-relative content path ("content/app.js"), or a dependency
+      # reference ("<dependency-guid>/content/app.js"). nil when no layer
+      # provides the path or it is tombstoned. Non-content paths never
+      # resolve through the view.
+      def resolve: (String? reference) -> String?
+
+      # The [GUID, view] pair whose GUID prefixes the reference (longest
+      # GUID first, so nested GUIDs address the innermost dependency).
+      def dependency_pair_for: (String reference) -> [String, MergedView]?
+    end
+  end
+end

data/sig/capsium/package/preparation.rbs

@@ -0,0 +1,23 @@
+module Capsium
+  class Package
+    # Package-source preparation (ARCHITECTURE.md section 1), mixed into
+    # Package: directory/.cap/encrypted-cap detection, extraction and
+    # decryption into a readable package directory.
+    module Preparation
+      def prepare_package: (Pathname path) -> (String | Pathname)
+
+      def decompress_cap_file: (String | Pathname file_path) -> String
+
+      # Decrypts an encrypted package (.cap file or uncompressed directory)
+      # into a temporary directory and returns its path. Raises
+      # Cipher::KeyRequiredError when no decryption_key was given.
+      def decrypt_cap_file: (String | Pathname source_path) -> String
+
+      def determine_load_type: (String | Pathname path) -> Symbol
+
+      # Whether the package was loaded from an encrypted source
+      # (ARCHITECTURE.md section 6b layout).
+      def encrypted?: () -> bool
+    end
+  end
+end

data/sig/capsium/package/routes_config.rbs

@@ -1,8 +1,22 @@
 module Capsium
   class Package
+    # The "responseRewrite" object of an inherited route (05x-routing
+    # section "Route Inheritance"): replaces the served body and/or
+    # overrides response headers.
+    class ResponseRewrite
+      attr_accessor body: String?
+      attr_accessor headers: Hash[String, String]?
+
+      def initialize: (?body: String? body, ?headers: Hash[String, String]? headers) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
     # A single route entry (ARCHITECTURE.md section 4). Kinds are
     # discriminated by key, MECE: static file, dataset route, or dynamic
-    # handler (accepted-and-ignored; reactors respond 501).
+    # handler (accepted-and-ignored; reactors respond 501). Route
+    # inheritance attributes per 05x-routing.
     class Route
       DATASET_PATH_PREFIX: String
 
@@ -15,6 +29,10 @@ module Capsium
       attr_accessor access_control: Hash[String, untyped]?
       attr_accessor http_method: String?
       attr_accessor handler: String?
+      attr_accessor remap: String?
+      attr_accessor response_rewrite: ResponseRewrite?
+      attr_accessor response_headers: Hash[String, String]?
+      attr_accessor request_headers: Hash[String, String]?
 
       def initialize: (?path: String? path, ?resource: String? resource,
                        ?headers: Hash[String, String]? headers,
@@ -22,7 +40,10 @@ module Capsium
                        ?visibility: String? visibility, ?dataset: String? dataset,
                        ?access_control: Hash[String, untyped]? access_control,
                        ?http_method: String? http_method,
-                       ?handler: String? handler) -> void
+                       ?handler: String? handler, ?remap: String? remap,
+                       ?response_rewrite: ResponseRewrite? response_rewrite,
+                       ?response_headers: Hash[String, String]? response_headers,
+                       ?request_headers: Hash[String, String]? request_headers) -> void
 
       def self.from_json: (String json) -> instance
 
@@ -32,11 +53,23 @@ module Capsium
 
       def handler_route?: () -> bool
 
+      # The URL path this route answers at: the remapped path when the
+      # route remaps an inherited route, its own path otherwise.
+      def serving_path: () -> String?
+
+      # Whether the resource addresses content of a dependency package
+      # ("<dependency-guid>/<path>" — a URI rather than a
+      # package-relative path).
+      def dependency_reference?: () -> bool
+
+      # Whether the route carries route-inheritance attributes.
+      def inherited?: () -> bool
+
       def fs_path: (String package_path) -> String?
 
       def mime: (Manifest manifest) -> String?
 
-      def validate_target: (String package_path, Storage storage) -> void
+      def validate_target: (String package_path, Storage storage, ?merged_view: MergedView? merged_view) -> void
 
       def to_json: (*untyped args) -> String
       def to_hash: () -> Hash[String, untyped]

data/sig/capsium/package/security.rbs

@@ -2,7 +2,7 @@ module Capsium
   class Package
     # Loads, generates and verifies security.json (ARCHITECTURE.md
     # section 6). Checksums cover every file in the package except
-    # security.json itself.
+    # security.json itself and signature.sig.
     class Security
       class IntegrityError < Capsium::Error
       end
@@ -42,14 +42,21 @@ module Capsium
 
       def initialize: (String path, ?SecurityConfig? config) -> void
 
-      def self.generate: (String package_path) -> Security
+      def self.generate: (String package_path, ?digital_signatures: DigitalSignatures? digital_signatures) -> Security
 
       def self.checksums_for: (String package_path) -> Hash[String, String]
 
       def self.package_files: (String package_path) -> Array[String]
 
+      def self.excluded?: (String relative_path) -> bool
+
       def present?: () -> bool
 
+      # The declared digitalSignatures block, or nil when absent.
+      def digital_signatures: () -> DigitalSignatures?
+
+      def signed?: () -> bool
+
       def checksums: () -> Hash[String, String]
 
       def verify: (String package_path) -> Array[ChecksumMismatch | MissingFile | UncheckedFile]

data/sig/capsium/package/signer.rbs

@@ -0,0 +1,59 @@
+module Capsium
+  class Package
+    # Signs and verifies Capsium packages with RSA-SHA256 digital
+    # signatures (05x-packaging "Digital Signature Using X.509",
+    # 05x-security "Digital Signatures"). The signed payload is the
+    # concatenation, in sorted package-relative path order, of the raw
+    # bytes of every file covered by the security.json integrity
+    # checksums (everything except security.json and signature.sig).
+    class Signer
+      ALGORITHM: String
+      MIN_KEY_BITS: Integer
+
+      # Package-relative name of the embedded public key PEM recorded in
+      # security.json digitalSignatures.publicKey.
+      PUBLIC_KEY_FILE: String
+
+      # Structural problems: no signature declared, missing signature or
+      # key files, unloadable keys, checksum-covered files missing.
+      class SignatureError < Capsium::Error
+      end
+
+      # A signature is declared but does not match the package contents.
+      class SignatureMismatchError < SignatureError
+      end
+
+      # Signature operations requested on an unsigned package.
+      class UnsignedPackageError < SignatureError
+      end
+
+      attr_reader package_path: String
+
+      def initialize: (String package_path) -> void
+
+      # Signs a package directory in place, or a .cap file (unpacked,
+      # signed, recompressed). Returns the signed path.
+      def self.sign_package: (String path, String private_key_path, ?String? certificate_path) -> String
+
+      # Verifies the declared signature of a package directory or .cap
+      # file (false on mismatch; raises typed SignatureError subclasses
+      # on structural problems, e.g. an unsigned package).
+      def self.verify_package: (String path, ?String? public_key_path) -> bool
+
+      # Signs the package directory in place: embeds the public key PEM,
+      # regenerates security.json (checksums plus digitalSignatures) and
+      # writes the raw RSA-SHA256 signature to signature.sig. Returns the
+      # path of the written signature file.
+      def sign: (String private_key_path, ?String? certificate_path) -> String
+
+      # True when the declared signature verifies against the payload;
+      # false on mismatch. Raises typed SignatureError subclasses on
+      # structural problems.
+      def verify: (?String? public_key_path) -> bool
+
+      def verify!: (?String? public_key_path) -> bool
+
+      def signed?: () -> bool
+    end
+  end
+end

data/sig/capsium/package/storage_config.rbs

@@ -1,5 +1,23 @@
 module Capsium
   class Package
+    # A single storage layer entry (ARCHITECTURE.md section 5a): a
+    # package-relative directory mirroring the content/ tree. Layers are
+    # stacked bottom -> top in declaration order; "visibility: private"
+    # layers are hidden from dependent packages.
+    class LayerConfig
+      attr_accessor path: String?
+      attr_accessor writable: bool
+      attr_accessor visibility: String
+
+      def initialize: (?path: String? path, ?writable: bool writable,
+                       ?visibility: String? visibility) -> void
+
+      def private?: () -> bool
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
     # A single dataset entry (ARCHITECTURE.md section 5): schema-backed
     # file (via "source") or SQLite ("databaseFile" + "table").
     class DatasetConfig
@@ -29,11 +47,13 @@ module Capsium
       def to_hash: () -> Hash[String, untyped]
     end
 
-    # The "storage" object holding the dataSets map.
+    # The "storage" object holding the dataSets map and the layers stack.
     class StorageData
       attr_accessor data_sets: Hash[String, DatasetConfig]
+      attr_accessor layers: Array[LayerConfig]
 
-      def initialize: (?data_sets: Hash[String, DatasetConfig] data_sets) -> void
+      def initialize: (?data_sets: Hash[String, DatasetConfig] data_sets,
+                       ?layers: Array[LayerConfig] layers) -> void
 
       def data_sets_from_json: (StorageData model, untyped value) -> void
 
@@ -54,6 +74,10 @@ module Capsium
 
       def data_sets: () -> Hash[String, DatasetConfig]
 
+      # The configured storage layers, bottom -> top (empty when the
+      # package uses the single implicit content/ layer).
+      def layers: () -> Array[LayerConfig]
+
       def to_json: (*untyped args) -> String
       def to_hash: () -> Hash[String, untyped]
     end

data/sig/capsium/package/store.rbs

@@ -0,0 +1,37 @@
+module Capsium
+  class Package
+    # A package store directory (ARCHITECTURE.md section 4a):
+    # "<name>-<version>.cap" files plus an optional index.json mapping
+    # dependency GUID -> file name. Dependencies resolve to the newest
+    # version satisfying their semver range.
+    class Store
+      INDEX_FILE: String
+      CAP_GLOB: String
+
+      # One store .cap with its identity per its metadata.json.
+      class CatalogEntry
+        def self.new: (String path, String? guid, Version version) -> void
+
+        def path: () -> String
+        def guid: () -> String?
+        def version: () -> Version
+      end
+
+      attr_reader dir: String
+
+      # The store configured via the CAPSIUM_STORE environment variable,
+      # or nil when unset.
+      def self.default: () -> Store?
+
+      def initialize: (String dir) -> void
+
+      # The newest .cap providing the dependency GUID whose version
+      # satisfies the range string. Raises DependencyNotFoundError or
+      # UnsatisfiableDependencyError when it cannot.
+      def find: (String guid, String range_string) -> String
+
+      # Every .cap in the store with its metadata identity (memoized).
+      def catalog: () -> Array[CatalogEntry]
+    end
+  end
+end

data/sig/capsium/package/testing/config_test.rbs

@@ -0,0 +1,21 @@
+module Capsium
+  class Package
+    module Testing
+      # A "config" test (05x-testing): the configuration file must exist
+      # in the package and parse as the declared format; known Capsium
+      # package configs are additionally validated against their
+      # canonical models.
+      class ConfigTest < TestCase
+        FORMATS: Array[String]
+
+        attr_reader format: String
+        attr_reader config_file: String
+
+        def initialize: (name: String name, format: String format,
+                         config_file: String config_file) -> void
+
+        def run: (Context context) -> TestCase::Result
+      end
+    end
+  end
+end

data/sig/capsium/package/testing/context.rbs

@@ -0,0 +1,14 @@
+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.
+      class Context
+        attr_reader package_path: String
+        attr_reader base_url: String?
+
+        def initialize: (package_path: String package_path, base_url: String? base_url) -> void
+      end
+    end
+  end
+end

data/sig/capsium/package/testing/data_validation_test.rbs

@@ -0,0 +1,22 @@
+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.
+      class DataValidationTest < TestCase
+        FORMATS: Array[String]
+
+        attr_reader format: String
+        attr_reader data_file: String
+        attr_reader schema_file: String
+
+        def initialize: (name: String name, format: String format,
+                         data_file: String data_file,
+                         schema_file: String schema_file) -> void
+
+        def run: (Context context) -> TestCase::Result
+      end
+    end
+  end
+end

data/sig/capsium/package/testing/file_test.rbs

@@ -0,0 +1,17 @@
+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: String
+        attr_reader contains: String?
+
+        def initialize: (name: String name, path: String path,
+                         ?contains: String? contains) -> void
+
+        def run: (Context context) -> TestCase::Result
+      end
+    end
+  end
+end

data/sig/capsium/package/testing/report.rbs

@@ -0,0 +1,20 @@
+module Capsium
+  class Package
+    module Testing
+      # The outcome of a test suite run: one Result per test case.
+      class Report
+        attr_reader results: Array[TestCase::Result]
+
+        def initialize: (?Array[TestCase::Result] results) -> void
+
+        def <<: (TestCase::Result result) -> Report
+
+        def ok?: () -> bool
+
+        def failures: () -> Array[TestCase::Result]
+
+        def summary: () -> String
+      end
+    end
+  end
+end

data/sig/capsium/package/testing/route_test.rbs

@@ -0,0 +1,22 @@
+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: String
+        attr_reader expected_status: Integer
+        attr_reader response_contains: String?
+        attr_reader expected_content_type: String?
+
+        def initialize: (name: String name, url: String url,
+                         expected_status: Integer expected_status,
+                         ?response_contains: String? response_contains,
+                         ?expected_content_type: String? expected_content_type) -> void
+
+        def run: (Context context) -> TestCase::Result
+      end
+    end
+  end
+end

data/sig/capsium/package/testing/test_case.rbs

@@ -0,0 +1,41 @@
+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.
+        class Result
+          attr_reader name: String
+          attr_reader ok: bool
+          attr_reader messages: Array[String]
+
+          def initialize: (name: String name, ok: bool ok, messages: Array[String] messages) -> void
+
+          def ok?: () -> bool
+        end
+
+        # Raised for invalid test definitions.
+        class DefinitionError < Capsium::Error
+        end
+
+        attr_reader name: String
+
+        def initialize: (name: String name) -> void
+
+        # Runs the test against the context and returns a Result.
+        def run: (Context context) -> Result
+
+        def self.register: (String type, singleton(TestCase) klass) -> void
+
+        def self.types: () -> Hash[String, singleton(TestCase)]
+
+        # Builds a test case from a YAML definition hash (string keys).
+        def self.build: (untyped definition) -> TestCase
+
+        def self.from_h: (Hash[String, untyped] definition) -> TestCase
+      end
+    end
+  end
+end

data/sig/capsium/package/testing/test_suite.rbs

@@ -0,0 +1,20 @@
+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.
+      class TestSuite
+        TESTS_DIR: String
+
+        attr_reader package: Capsium::Package
+
+        def initialize: (Capsium::Package package) -> void
+
+        def test_files: () -> Array[String]
+
+        def run: () -> Report
+      end
+    end
+  end
+end

data/sig/capsium/package/testing.rbs

@@ -0,0 +1,7 @@
+module Capsium
+  class Package
+    # Runner for the Capsium package testing YAML DSL (05x-testing).
+    module Testing
+    end
+  end
+end

data/sig/capsium/package/verification.rbs

@@ -0,0 +1,24 @@
+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: () -> Array[Security::ChecksumMismatch | Security::MissingFile | Security::UncheckedFile]
+
+      def verify_integrity!: () -> void
+
+      # Whether security.json declares a digital signature for this package.
+      def signed?: () -> bool
+
+      # Verifies the declared digital signature (RSA-SHA256) against the
+      # checksum-covered payload. True when the package is unsigned or the
+      # signature verifies; false on mismatch.
+      def verify_signature: () -> bool
+
+      def verify_signature!: () -> void
+    end
+  end
+end

data/sig/capsium/package/version.rbs

@@ -0,0 +1,39 @@
+module Capsium
+  class Package
+    # A semantic version (MAJOR.MINOR.PATCH[-prerelease][+build]) with
+    # semver precedence ordering.
+    class Version
+      include Comparable
+
+      PATTERN: Regexp
+
+      attr_reader major: Integer
+      attr_reader minor: Integer
+      attr_reader patch: Integer
+      attr_reader prerelease: String?
+
+      def self.parse: (String string) -> Version
+
+      def initialize: (Integer major, Integer minor, Integer patch,
+                       ?String? prerelease) -> void
+
+      def <=>: (Version other) -> Integer
+
+      def to_s: () -> String
+    end
+
+    # A semver range for metadata.dependencies (ARCHITECTURE.md section
+    # 4a): "*", exact versions, wildcards/partials, caret, tilde,
+    # comparison operators and comma/space conjunctions.
+    class VersionRange
+      NUMERIC_PART: Regexp
+      WILDCARD_PART: Regexp
+
+      def self.parse: (String string) -> VersionRange
+
+      def initialize: (Array[[String, Version]] bounds) -> void
+
+      def satisfied_by?: (String | Version version) -> bool
+    end
+  end
+end

data/sig/capsium/package.rbs

@@ -2,11 +2,17 @@ module Capsium
   # A Capsium package loaded from a directory or a .cap file
   # (ARCHITECTURE.md section 1).
   class Package
+    include Verification
+    include Composition
+    include Preparation
+
     MANIFEST_FILE: String
     METADATA_FILE: String
     STORAGE_FILE: String
     ROUTES_FILE: String
     SECURITY_FILE: String
+    SIGNATURE_FILE: String
+    AUTHENTICATION_FILE: String
     CONTENT_DIR: String
     DATA_DIR: String
 
@@ -18,36 +24,38 @@ module Capsium
     attr_reader storage: Storage
     attr_reader security: Security
     attr_reader load_type: Symbol
-
-    def initialize: (String | Pathname path, ?load_type: Symbol? load_type) -> void
-
-    def prepare_package: (Pathname path) -> (String | Pathname)
+    attr_reader resolved_dependencies: Array[ResolvedDependency]
+    attr_reader authentication: Authentication
+
+    # Loads a package directory or .cap file. Composite packages
+    # (metadata.dependencies, ARCHITECTURE.md section 4a) resolve against
+    # the package store given as `store` (directory path or Store) or via
+    # CAPSIUM_STORE. `dependency_chain` is internal: the ancestor GUIDs
+    # used for circular-dependency detection during recursive resolution.
+    def initialize: (String | Pathname path, ?load_type: Symbol? load_type,
+                     ?decryption_key: String? decryption_key,
+                     ?store: (Store | String)? store,
+                     ?dependency_chain: Array[String] dependency_chain) -> void
 
     def solidify: () -> void
 
-    def decompress_cap_file: (String | Pathname file_path) -> String
-
     def load_package: () -> void
 
-    # Removes the temporary extraction directory of a .cap-loaded
-    # package; a no-op for directory loads.
+    # Removes the temporary extraction directories of the package and its
+    # resolved dependencies; a no-op for directory loads.
     def cleanup: () -> void
 
     def datasets: () -> Array[Dataset]
 
+    # The merged content view across the storage layers (ARCHITECTURE.md
+    # section 5a); exported_only gives the dependent-package view (section 4a).
+    # Resolved dependencies act as read-only layers below all own layers.
+    def merged_view: (?exported_only: bool exported_only) -> MergedView
+
     # The .cap file this package was loaded from, or nil when loaded
     # from a directory.
     def cap_file_path: () -> String?
 
     def content_files: () -> Array[String]
-
-    def determine_load_type: (String | Pathname path) -> Symbol
-
-    # Verifies the package against security.json (ARCHITECTURE.md
-    # section 6). Returns a list of typed errors; empty when no
-    # security.json is present or all checksums match.
-    def verify_integrity: () -> Array[Security::ChecksumMismatch | Security::MissingFile | Security::UncheckedFile]
-
-    def verify_integrity!: () -> void
   end
 end

data/sig/capsium/packager.rbs

@@ -18,6 +18,15 @@ module Capsium
 
     def compress_package: (Package package, String cap_file) -> void
 
+    # Unpacks a .cap into a temporary directory, yields it for read-only
+    # inspection and returns the block's value.
+    def with_unpacked_cap: (String cap_path) { (String dir) -> untyped } -> untyped
+
+    # Unpacks a .cap into a temporary directory, yields it for
+    # modification, then recompresses the result back over cap_path.
+    # Returns cap_path.
+    def transform_cap: (String cap_path) { (String dir) -> untyped } -> String
+
     def relative_path_current: (String absolute_path) -> String
   end
 end