capsium 0.2.0 → 0.6.0

data/sig/capsium/reactor/graphql_api.rbs

@@ -0,0 +1,27 @@
+module Capsium
+  class Reactor
+    # GraphQL over a mount's datasets (POST and GET <mount>/graphql):
+    # executes the derived schema and maps typed overlay errors into
+    # the "errors" array.
+    class GraphqlApi
+      include Responses
+
+      PATH: String
+
+      def self.path?: (String inner_path) -> bool
+
+      def initialize: (Mount mount) -> void
+
+      def handle: (untyped request, untyped response) -> untyped
+
+      # Query/mutation resolvers called from the derived schema.
+      def collection: (Package::Dataset dataset, ?id: String? id) -> Array[untyped]
+
+      def create_item: (Package::Dataset dataset, item: untyped item) -> untyped
+
+      def update_item: (Package::Dataset dataset, id: String id, item: untyped item) -> untyped
+
+      def remove_item: (Package::Dataset dataset, id: String id) -> bool
+    end
+  end
+end

data/sig/capsium/reactor/graphql_schema.rbs

@@ -0,0 +1,20 @@
+module Capsium
+  class Reactor
+    # Builds the GraphQL schema for a mounted package: per dataset a
+    # query field "<dataset>" (list, optional "id:") plus
+    # create<Dataset>/update<Dataset>/delete<Dataset> mutations. Item
+    # types are inferred from the dataset's JSON schema when present.
+    class GraphqlSchema
+      # Permissive scalar carrying any JSON value.
+      class JsonScalar < GraphQL::Schema::Scalar
+        def self.coerce_input: (untyped input_value, untyped _context) -> untyped
+
+        def self.coerce_result: (untyped ruby_value, untyped _context) -> untyped
+      end
+
+      def initialize: (Mount mount, GraphqlApi api) -> void
+
+      def build: () -> singleton(GraphQL::Schema)
+    end
+  end
+end

data/sig/capsium/reactor/htpasswd.rbs

@@ -0,0 +1,36 @@
+module Capsium
+  class Reactor
+    # Apache htpasswd verification (05x-authentication). Supported hash
+    # formats: bcrypt ($2a$/$2b$/$2y$), Apache apr1 MD5 and md5-crypt
+    # ($apr1$/$1$), unsalted SHA-1 ({SHA}), and a crypt(3) fallback for
+    # the rest (platform-dependent).
+    class Htpasswd
+      # md5-crypt as deployed by Apache htpasswd, OpenSSL and glibc.
+      module Md5Crypt
+        ITOA64: String
+        DIGEST_GROUPS: Array[Array[Integer]]
+
+        def self.verify: (String hash, String password) -> bool
+
+        def self.digest: (String password, String salt, String magic) -> String
+
+        def self.initial_digest: (String password, String salt, String magic) -> String
+
+        def self.stretch_digest: (Integer iteration, String password, String salt, String final) -> String
+
+        def self.to64: (String final) -> String
+      end
+
+      attr_reader path: String
+
+      def initialize: (String path) -> void
+
+      def usernames: () -> Array[String]
+
+      def verify?: (String username, String password) -> bool
+    end
+
+    # Constant-time string comparison (length-check first).
+    def self.secure_compare: (String own, String theirs) -> bool
+  end
+end

data/sig/capsium/reactor/introspection.rbs

@@ -1,23 +1,36 @@
 module Capsium
   class Reactor
-    # Monitoring HTTP API reports for the package this reactor serves
-    # (ARCHITECTURE.md section 7).
+    # Monitoring HTTP API reports (ARCHITECTURE.md section 7):
+    # /api/v1/introspect/* aggregates every mounted package, plus
+    # reactor-level /introspect/* and per-package /package/:id/*
+    # endpoints resolved by package name.
     class Introspection
       METADATA_PATH: String
       ROUTES_PATH: String
       CONTENT_HASHES_PATH: String
       CONTENT_VALIDITY_PATH: String
       PATHS: Array[String]
+      STATUS_PATH: String
+      CONFIG_PATH: String
+      METRICS_PATH: String
+      REACTOR_PATHS: Array[String]
+      PACKAGE_MOUNT: String
+      PACKAGE_PATH_PATTERN: Regexp
+      DEFAULT_LOG_LINES: Integer
+      MAX_LOG_LINES: Integer
 
-      attr_reader package: Package
+      attr_reader packages: Array[Package]
 
-      def initialize: (Package package) -> void
+      def initialize: (Array[Package] packages, ?reactor: Reactor? reactor) -> void
+
+      # The first mounted package (the single-package view).
+      def package: () -> Package
 
       def endpoint?: (String path) -> bool
 
-      # The report body for an introspection endpoint, or nil when the
-      # path is not an introspection endpoint.
-      def report_for: (String path) -> Hash[Symbol, untyped]?
+      # The report body for an endpoint, or nil when the path is not an
+      # endpoint or the package name does not match (404).
+      def report_for: (String path, ?params: Hash[String, String] params) -> Hash[Symbol, untyped]?
 
       def metadata_report: () -> Hash[Symbol, untyped]
 
@@ -26,6 +39,13 @@ module Capsium
       def content_hashes_report: () -> Hash[Symbol, untyped]
 
       def content_validity_report: () -> Hash[Symbol, untyped]
+
+      def status_report: () -> Hash[Symbol, untyped]
+
+      # Reactor configuration; secrets are never exposed.
+      def config_report: () -> Hash[Symbol, untyped]
+
+      def metrics_report: () -> Hash[Symbol, untyped]
     end
   end
 end

data/sig/capsium/reactor/metrics.rbs

@@ -0,0 +1,13 @@
+module Capsium
+  class Reactor
+    # Minimal in-memory request counters for the /introspect/metrics
+    # endpoint, thread-safe via Mutex.
+    class Metrics
+      def initialize: () -> void
+
+      def record: (Integer status) -> Metrics
+
+      def snapshot: () -> Hash[Symbol, untyped]
+    end
+  end
+end

data/sig/capsium/reactor/mount.rbs

@@ -0,0 +1,83 @@
+module Capsium
+  class Reactor
+    # Raised when two mounts claim the same URL prefix, whether given
+    # explicitly or derived from package names.
+    class MountConflictError < Capsium::Error
+    end
+
+    # One mounted package: the URL prefix it answers under plus its
+    # serving state. The reactor serves a list of mounts resolved by
+    # longest-prefix matching; default mount points are "/" for the
+    # first source and "/<metadata.name>/" for each additional one.
+    class Mount
+      ROOT_PATH: String
+      SPEC_SEPARATOR: String
+
+      # A mount entry as accepted from the CLI or a JSON config file:
+      # "path" may be nil (the default is assigned on build), "source"
+      # is a package directory, .cap file or Package, "store"
+      # optionally overrides the global package store for this mount.
+      class Entry
+        def self.new: (path: String? path, source: (Package | String) source, store: (Package::Store | String)? store) -> void
+
+        def path: () -> String?
+
+        def source: () -> (Package | String)
+
+        def store: () -> (Package::Store | String)?
+
+        def with: (?path: String? path, ?source: (Package | String) source, ?store: (Package::Store | String)? store) -> Entry
+      end
+
+      attr_reader path: String
+      attr_reader package: Package
+      attr_reader overlay: Overlay?
+
+      def self.parse_spec: (String spec) -> Entry
+
+      def self.config_entries: (String config_file) -> Array[Entry]
+
+      def self.build: (Array[Entry] entries, ?store: (Package::Store | String)? store, ?registry: (Capsium::Registry | String)? registry) -> Array[Mount]
+
+      def self.load_package: ((Package | String) source, (Package::Store | String)? store, (Capsium::Registry | String)? registry) -> Package
+
+      def self.normalize_path: (String? path) -> String
+
+      def initialize: (path: String? path, package: (Package | String) package, ?store: (Package::Store | String)? store, ?registry: (Capsium::Registry | String)? registry, ?workdir: String? workdir) -> void
+
+      # Attaches the reactor workdir (creates the writable overlay).
+      def attach_workdir: (String workdir) -> void
+
+      # Writable unless the package declares "readOnly": true.
+      def writable?: () -> bool
+
+      def matches?: (String request_path) -> bool
+
+      def inner_path: (String request_path) -> String
+
+      def routes: () -> Package::Routes
+
+      def merged_view: () -> Package::MergedView
+
+      # The dataset as served: base data merged with overlay mutations.
+      def dataset_data: (Package::Dataset dataset) -> untyped
+
+      def data_api: () -> DataApi
+
+      def content_api: () -> ContentApi
+
+      # Whether this mount exposes a GraphQL API (any file-backed dataset).
+      def graphql?: () -> bool
+
+      def graphql_api: () -> GraphqlApi
+
+      # The one-line "name version" summary used in reactor logs.
+      def summary: () -> String
+
+      # The WEBrick mount points serving this mount.
+      def server_paths: () -> Array[String]
+
+      def reload: () -> Package
+    end
+  end
+end

data/sig/capsium/reactor/oauth2.rbs

@@ -0,0 +1,31 @@
+module Capsium
+  class Reactor
+    # OAuth2 authorization-code flow client (05x-authentication), used by
+    # the Authenticator. Talks to the provider over net/http; the client
+    # secret never comes from the package.
+    class OAuth2
+      # The token exchange or userinfo fetch failed at the provider.
+      class FlowError < Capsium::Error
+      end
+
+      GRANT_TYPE: String
+
+      attr_reader config: Package::OAuth2Config
+
+      def initialize: (Package::OAuth2Config config, client_secret: String client_secret,
+                       session: Session session, ?base_url: String? base_url) -> void
+
+      # The provider URL the login endpoint redirects the browser to.
+      def authorization_url: (untyped request) -> String
+
+      def valid_state?: (String? state) -> bool
+
+      # Exchanges the authorization code and fetches the userinfo
+      # claims. Returns the raw userinfo hash; raises FlowError on
+      # provider errors.
+      def complete: (String? code, untyped request) -> Hash[String, untyped]
+
+      def callback_uri: (untyped request) -> String
+    end
+  end
+end

data/sig/capsium/reactor/overlay.rbs

@@ -0,0 +1,72 @@
+module Capsium
+  class Reactor
+    # The writable top overlay layer of a mounted package
+    # (ARCHITECTURE.md section 5a): an append-only record of writes in
+    # the reactor workdir (content files, tombstones, per-dataset
+    # mutation logs). The immutable package never changes on disk.
+    class Overlay
+      # Base class for the typed overlay errors the APIs map to HTTP
+      # statuses.
+      class Error < Capsium::Error
+      end
+
+      # The addressed item does not exist in the merged collection (404).
+      class ItemNotFoundError < Error
+      end
+
+      # The write conflicts with existing state (409).
+      class ConflictError < Error
+      end
+
+      # The dataset cannot take item writes or the path is unsafe.
+      class UnsupportedDatasetError < Error
+      end
+
+      # The candidate document violates the dataset's JSON schema (422).
+      class SchemaViolationError < Error
+        attr_reader messages: Array[String]
+
+        def initialize: (Array[String] messages) -> void
+      end
+
+      TOMBSTONE_FILE: String
+      SAFE_NAME_PATTERN: Regexp
+
+      attr_reader root: String
+      attr_reader tombstones: Set[String]
+
+      def initialize: (root: String root) -> void
+
+      def content_root: () -> String
+
+      def data_root: () -> String
+
+      # The overlay as the topmost MergedView layer.
+      def layer: () -> Package::MergedView::Layer
+
+      def write_content: (String content_relative, String body) -> void
+
+      def delete_content: (String content_relative) -> void
+
+      # The dataset as served: base data merged with the mutation log.
+      def dataset_data: (Package::Dataset dataset) -> untyped
+
+      # The merged item collection.
+      def items: (Package::Dataset dataset) -> Array[untyped]
+
+      def item: (Package::Dataset dataset, String id) -> untyped
+
+      def append_item: (Package::Dataset dataset, untyped item) -> String
+
+      def replace_item: (Package::Dataset dataset, String id, untyped item) -> void
+
+      def delete_item: (Package::Dataset dataset, String id) -> nil
+
+      # Whether the dataset has recorded mutations.
+      def mutations?: (String name) -> bool
+
+      # The item id convention: an "id" field, else nil (positional).
+      def item_id: (untyped item) -> String?
+    end
+  end
+end

data/sig/capsium/reactor/package_saver.rbs

@@ -0,0 +1,12 @@
+module Capsium
+  class Reactor
+    # Folds a mounted package's base plus its overlay into a NEW
+    # versioned .cap (name-version+patch.cap) in the reactor workdir.
+    class PackageSaver
+      def initialize: (Mount mount) -> void
+
+      # Saves and returns the {"path", "sha256", "name", "version"} hash.
+      def save: (String workdir) -> Hash[String, String]
+    end
+  end
+end

data/sig/capsium/reactor/responses.rbs

@@ -0,0 +1,23 @@
+module Capsium
+  class Reactor
+    # Plain HTTP response writers shared by the reactor dispatch, the
+    # route serving and the API handlers (data, GraphQL, save).
+    module Responses
+      private
+
+      def respond_not_found: (untyped response) -> untyped
+
+      def respond_forbidden: (untyped response) -> untyped
+
+      def respond_not_implemented: (untyped response) -> untyped
+
+      def respond_method_not_allowed: (untyped response) -> untyped
+
+      def respond_text: (untyped response, Integer status, String body) -> untyped
+
+      def respond_json: (untyped response, Integer status, untyped body) -> untyped
+
+      def respond_error: (untyped response, Integer status, String message, ?messages: Array[String]? messages) -> untyped
+    end
+  end
+end

data/sig/capsium/reactor/serving.rbs

@@ -0,0 +1,46 @@
+module Capsium
+  class Reactor
+    # Serving of resolved routes (static files through the merged view,
+    # datasets, handler-route 501s), mixed into Reactor. Includes route
+    # inheritance processing per 05x-routing.
+    module Serving
+      include Responses
+
+      private
+
+      # One request metric and one log line per served request.
+      def record_request: (untyped request, untyped response) -> untyped
+
+      # The mount answering a request path: longest matching prefix wins.
+      def resolve_mount: (String path) -> Mount?
+
+      def mounts_by_length: () -> Array[Mount]
+
+      # The root ("/") mount, or the first mount when nothing is mounted
+      # at the root.
+      def root_mount: () -> Mount
+
+      # Serves a request that matched a mount.
+      def serve_mounted_request: (Mount mount, untyped identity, untyped request, untyped response) -> untyped
+
+      def serve_data_api: (Mount mount, untyped identity, String inner, untyped request, untyped response) -> untyped
+
+      def serve_content_api: (Mount mount, untyped identity, String inner, untyped request, untyped response) -> untyped
+
+      # Route-level access control; false when the response was written.
+      def authorized?: (untyped identity, Package::Route route, untyped response) -> bool
+
+      def serve_route: (Mount mount, Package::Route route, untyped response) -> untyped
+
+      def serve_file: (Mount mount, Package::Route route, untyped response) -> untyped
+
+      def inherited_processing: (Package::Route route, String body, Hash[String, String] headers) -> [String, Hash[String, String]]
+
+      def content_type_for: (Mount mount, Package::Route route, String content_path) -> String
+
+      def headers_for: (Package::Route route) -> Hash[String, String]
+
+      def serve_dataset: (Mount mount, String dataset_name, untyped response) -> untyped
+    end
+  end
+end

data/sig/capsium/reactor/session.rbs

@@ -0,0 +1,36 @@
+module Capsium
+  class Reactor
+    # HMAC-SHA256 signed session cookies (05x-authentication). The
+    # signing secret comes from deploy.json (sessionSecret) or is
+    # generated and persisted reactor-side (never in the package).
+    class Session
+      COOKIE_NAME: String
+      SECRET_BYTES: Integer
+
+      def self.hmac: (String secret, String data) -> String
+
+      # The persisted reactor-side secret: loaded from state_file when
+      # present, generated and written (mode 0600) otherwise.
+      def self.load_or_generate_secret: (String? state_file) -> String
+
+      attr_reader secret: String
+
+      def initialize: (?secret: String? secret, ?state_file: String? state_file) -> void
+
+      # HMAC-SHA256 of data with the session secret (hex).
+      def sign: (String data) -> String
+
+      def encode: (Hash[String, untyped] payload) -> String
+
+      # The verified payload, or nil when the cookie is missing or the
+      # signature does not match.
+      def decode: (String? cookie_value) -> Hash[String, untyped]?
+
+      # The identity for a request's Cookie header, or nil.
+      def identity_from: (untyped request) -> Hash[String, untyped]?
+
+      # A Set-Cookie value establishing the identity session.
+      def cookie_for: (Hash[String, untyped] identity) -> String
+    end
+  end
+end

data/sig/capsium/reactor.rbs

@@ -3,8 +3,13 @@ module Capsium
   # Monitoring HTTP API (ARCHITECTURE.md section 7) and reloads the
   # package on filesystem changes.
   class Reactor
+    include Responses
+    include Endpoints
+    include Serving
+
     DEFAULT_PORT: Integer
     DEFAULT_CACHE_CONTROL: String
+    PACKAGE_SAVE_PATTERN: Regexp
 
     attr_reader package: Package
     attr_reader package_path: String
@@ -14,10 +19,23 @@ module Capsium
     attr_reader server: untyped
     attr_reader server_thread: Thread?
     attr_reader introspection: Introspection
+    attr_reader authenticator: Authenticator
+    attr_reader store: (Package::Store | String)?
+    attr_reader registry: (Capsium::Registry | String)?
+    attr_reader started_at: Time
+    attr_reader metrics: Metrics
+    attr_reader log_buffer: Capsium::LogBuffer
+    attr_reader mounts: Array[Mount]
+    attr_reader workdir: String
 
-    def initialize: (package: Package | String package, ?port: Integer port,
+    def initialize: (?package: (Package | String)? package, ?mounts: Array[Mount]? mounts,
+                     ?port: Integer port,
                      ?cache_control: String? cache_control,
-                     ?do_not_listen: bool do_not_listen) -> void
+                     ?do_not_listen: bool do_not_listen,
+                     ?store: (Package::Store | String)? store,
+                     ?deploy: (Hash[String, untyped] | String)? deploy,
+                     ?registry: (Capsium::Registry | String)? registry,
+                     ?workdir: String? workdir) -> void
 
     def serve: () -> untyped
 
@@ -26,5 +44,7 @@ module Capsium
     def mount_routes: () -> void
 
     def restart_server: () -> Thread
+
+    def cleanup: () -> void
   end
 end

data/sig/capsium/registry/local.rbs

@@ -0,0 +1,16 @@
+module Capsium
+  class Registry
+    # A static registry in a local directory (read-write).
+    class Local < Registry
+      attr_reader dir: String
+
+      def initialize: (String dir) -> void
+
+      def location: () -> String
+
+      # Validates cap_path, copies it into the registry and records it
+      # in index.json. Returns the recorded Entry.
+      def push: (String cap_path) -> Entry
+    end
+  end
+end

data/sig/capsium/registry/remote.rbs

@@ -0,0 +1,18 @@
+module Capsium
+  class Registry
+    # A read-only static registry behind an https base URL (plain http
+    # for loopback hosts only).
+    class Remote < Registry
+      OPEN_TIMEOUT: Integer
+      READ_TIMEOUT: Integer
+      MAX_REDIRECTS: Integer
+      LOOPBACK_NETWORKS: Array[untyped]
+
+      attr_reader base_url: String
+
+      def initialize: (String base_url) -> void
+
+      def location: () -> String
+    end
+  end
+end

data/sig/capsium/registry.rbs

@@ -0,0 +1,83 @@
+module Capsium
+  # A static package registry (directory or https base URL with an
+  # index.json): Capsium::Registry::Local (read-write) and
+  # Capsium::Registry::Remote (read-only). See lib/capsium/registry.rb.
+  class Registry
+    INDEX_FILE: String
+    ENV_VAR: String
+
+    # Base error for every registry failure.
+    class RegistryError < Capsium::Error
+    end
+
+    # No registry reference was given (neither flag nor CAPSIUM_REGISTRY).
+    class RegistryNotConfiguredError < RegistryError
+    end
+
+    # The registry itself is unusable (bad path or URL, unreadable index).
+    class InvalidRegistryError < RegistryError
+    end
+
+    # A .cap offered to push failed package validation.
+    class InvalidPackageError < RegistryError
+    end
+
+    # The index has no entry for the requested package GUID.
+    class PackageNotFoundError < RegistryError
+    end
+
+    # The registry has the GUID but no version satisfies the constraint.
+    class UnsatisfiableConstraintError < RegistryError
+    end
+
+    # A fetched .cap does not match the sha256 declared in the index.
+    class ChecksumMismatchError < RegistryError
+    end
+
+    # A registry file could not be retrieved (network or HTTP failure).
+    class FetchError < RegistryError
+    end
+
+    # One indexed version of a registry package.
+    class Entry
+      def self.new: (guid: String, name: String, version: Package::Version,
+                     file: String, sha256: String, size: Integer) -> void
+
+      def guid: () -> String
+      def name: () -> String
+      def version: () -> Package::Version
+      def file: () -> String
+      def sha256: () -> String
+      def size: () -> Integer
+
+      # The canonical store file name for this entry's .cap.
+      def cap_file_name: () -> String
+    end
+
+    # The registry at the given reference: a Local directory or a Remote
+    # http(s) base URL. Raises RegistryNotConfiguredError when no
+    # reference is given.
+    def self.fetch: (String? ref) -> Registry
+
+    # The registry named by the CAPSIUM_REGISTRY environment variable,
+    # or nil when unset.
+    def self.default: () -> Registry?
+
+    def initialize: () -> void
+
+    # Where this registry lives (directory path or base URL).
+    def location: () -> String
+
+    # The newest indexed version of the package GUID satisfying the
+    # semver constraint.
+    def resolve: (String guid, ?String constraint) -> Entry
+
+    # Resolves, fetches, checksum-verifies and installs the newest
+    # satisfying .cap into the package store, returning the store path.
+    def install: (String guid, ?String constraint,
+                  store: (Package::Store | String) store) -> String
+
+    # Only Local registries are writable.
+    def push: (String cap_path) -> Entry
+  end
+end

data/sig/graphql.rbs

@@ -0,0 +1,12 @@
+# Minimal RBS stubs for the graphql gem: only the constants capsium's
+# own signatures reference (the gem ships full sigs, but this project
+# does not use an RBS collection).
+module GraphQL
+  class Schema
+    def self.execute: (String query, ?variables: Hash[String, untyped] variables, ?operation_name: String? operation_name) -> untyped
+
+    class Scalar
+      def self.graphql_name: (?String name) -> void
+    end
+  end
+end