capsium 0.1.2 → 0.3.0

data/sig/capsium/package/routes_config.rbs

@@ -0,0 +1,107 @@
+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). Route
+    # inheritance attributes per 05x-routing.
+    class Route
+      DATASET_PATH_PREFIX: String
+
+      attr_accessor path: String?
+      attr_accessor resource: String?
+      attr_accessor headers: Hash[String, String]?
+      attr_accessor headers_file: String?
+      attr_accessor visibility: String
+      attr_accessor dataset: String?
+      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,
+                       ?headers_file: String? headers_file,
+                       ?visibility: String? visibility, ?dataset: String? dataset,
+                       ?access_control: Hash[String, untyped]? access_control,
+                       ?http_method: String? http_method,
+                       ?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
+
+      def kind: () -> (:resource | :dataset | :handler)
+
+      def dataset_route?: () -> bool
+
+      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, ?merged_view: MergedView? merged_view) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # Canonical routes.json model: optional top-level "index" plus a
+    # "routes" array. The legacy object/target form is normalized on
+    # read; writers emit only the canonical form.
+    class RoutesConfig
+      attr_accessor index: String?
+      attr_accessor routes: Array[Route]
+
+      def initialize: (?index: String? index, ?routes: Array[Route] routes) -> void
+
+      def self.from_json: (String json) -> instance
+
+      def routes_from_json: (RoutesConfig model, untyped value) -> void
+
+      def routes_to_json: (RoutesConfig model, Hash[String, untyped] doc) -> void
+
+      def resolve: (String path) -> Route?
+
+      def add: (String path, String target) -> Route
+
+      def update: (String path, String updated_path, String updated_target) -> Route
+
+      def remove: (String path) -> Array[Route]
+
+      def sort!: () -> RoutesConfig
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/security.rbs

@@ -0,0 +1,72 @@
+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 and signature.sig.
+    class Security
+      class IntegrityError < Capsium::Error
+      end
+
+      # A file whose SHA-256 does not match the recorded checksum.
+      class ChecksumMismatch
+        attr_reader path: String
+        attr_reader expected: String
+        attr_reader actual: String
+
+        def initialize: (path: String path, expected: String expected, actual: String actual) -> void
+
+        def message: () -> String
+      end
+
+      # A checksum listed for a file that is missing on disk.
+      class MissingFile
+        attr_reader path: String
+        attr_reader expected: String
+
+        def initialize: (path: String path, expected: String expected) -> void
+
+        def message: () -> String
+      end
+
+      # A file on disk not covered by any checksum.
+      class UncheckedFile
+        attr_reader path: String
+
+        def initialize: (path: String path) -> void
+
+        def message: () -> String
+      end
+
+      attr_reader path: String
+      attr_reader config: SecurityConfig?
+
+      def initialize: (String path, ?SecurityConfig? config) -> void
+
+      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]
+
+      def verify!: (String package_path) -> void
+
+      def save_to_file: (?String output_path) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/security_config.rbs

@@ -0,0 +1,57 @@
+module Capsium
+  class Package
+    # The "integrityChecks" object of security.json: SHA-256 checksums
+    # keyed by package-relative path.
+    class IntegrityChecks
+      ALGORITHMS: Array[String]
+
+      attr_accessor checksum_algorithm: String
+      attr_accessor checksums: Hash[String, String]
+
+      def initialize: (?checksum_algorithm: String? checksum_algorithm,
+                       ?checksums: Hash[String, String] checksums) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # The "digitalSignatures" object of security.json (parsed only;
+    # signing is a later phase).
+    class DigitalSignatures
+      attr_accessor public_key: String?
+      attr_accessor signature_file: String?
+
+      def initialize: (?public_key: String? public_key,
+                       ?signature_file: String? signature_file) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # The "security" object of security.json.
+    class SecurityData
+      attr_accessor integrity_checks: IntegrityChecks?
+      attr_accessor digital_signatures: DigitalSignatures?
+
+      def initialize: (?integrity_checks: IntegrityChecks? integrity_checks,
+                       ?digital_signatures: DigitalSignatures? digital_signatures) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # Canonical security.json model (generated at pack time).
+    class SecurityConfig
+      attr_accessor security: SecurityData?
+
+      def initialize: (?security: SecurityData? security) -> void
+
+      def self.from_json: (String json) -> instance
+
+      def checksums: () -> Hash[String, String]
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

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.rbs

@@ -0,0 +1,28 @@
+module Capsium
+  class Package
+    # Loads and writes storage.json and instantiates its datasets
+    # (ARCHITECTURE.md section 5).
+    class Storage
+      attr_reader path: String
+      attr_reader config: StorageConfig
+      attr_reader datasets: Array[Dataset]
+
+      def initialize: (String path) -> void
+
+      def data_sets: () -> Hash[String, DatasetConfig]
+
+      def load_datasets: () -> Array[Dataset]
+
+      def dataset: (String name) -> Dataset?
+
+      def dataset_names: () -> Array[String]
+
+      def empty?: () -> bool
+
+      def save_to_file: (?String output_path) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/storage_config.rbs

@@ -0,0 +1,85 @@
+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
+      FORMATS: Hash[String, String]
+      SCHEMA_TYPES: Array[String]
+
+      attr_accessor source: String?
+      attr_accessor schema_file: String?
+      attr_accessor schema_type: String?
+      attr_accessor database_file: String?
+      attr_accessor table: String?
+
+      def initialize: (?source: String? source, ?schema_file: String? schema_file,
+                       ?schema_type: String? schema_type,
+                       ?database_file: String? database_file,
+                       ?table: String? table) -> void
+
+      def format: () -> String
+
+      def sqlite?: () -> bool
+
+      def backing_file: () -> String
+
+      def to_dataset: (String name, String package_path) -> Dataset
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # 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,
+                       ?layers: Array[LayerConfig] layers) -> void
+
+      def data_sets_from_json: (StorageData model, untyped value) -> void
+
+      def data_sets_to_json: (StorageData model, Hash[String, untyped] doc) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # Canonical storage.json model. The legacy array form is normalized
+    # on read; writers emit only the canonical form.
+    class StorageConfig
+      attr_accessor storage: StorageData?
+
+      def initialize: (?storage: StorageData? storage) -> void
+
+      def self.from_json: (String json) -> instance
+
+      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
+  end
+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/validator.rbs

@@ -0,0 +1,29 @@
+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
+      EXTERNAL_REFERENCE_PATTERN: Regexp
+      TEXT_CONTENT_MIME: Regexp
+
+      # One named validation check with its problems; ok when messages
+      # is empty.
+      class CheckResult
+        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
+
+      def initialize: (String package_path) -> void
+
+      def run: () -> Array[CheckResult]
+
+      def valid?: () -> bool
+    end
+  end
+end