capsium 0.3.0 → 0.6.0

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

@@ -4,19 +4,43 @@ module Capsium
     # datasets, handler-route 501s), mixed into Reactor. Includes route
     # inheritance processing per 05x-routing.
     module Serving
+      include Responses
+
       private
 
-      def serve_route: (Package::Route route, untyped response) -> untyped
+      # 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: (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: (Package::Route route, String content_path) -> 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: (String dataset_name, untyped response) -> untyped
+      def serve_dataset: (Mount mount, String dataset_name, untyped response) -> untyped
     end
   end
 end

data/sig/capsium/reactor.rbs

@@ -3,10 +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
@@ -17,12 +20,22 @@ module Capsium
     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,
                      ?store: (Package::Store | String)? store,
-                     ?deploy: (Hash[String, untyped] | String)? deploy) -> void
+                     ?deploy: (Hash[String, untyped] | String)? deploy,
+                     ?registry: (Capsium::Registry | String)? registry,
+                     ?workdir: String? workdir) -> void
 
     def serve: () -> untyped
 
@@ -31,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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capsium
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Ribose Inc.
@@ -37,6 +37,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: graphql
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -113,6 +127,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rnp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: rubyzip
   requirement: !ruby/object:Gem::Requirement
@@ -223,9 +251,11 @@ files:
 - lib/capsium/cli/reactor.rb
 - lib/capsium/converters.rb
 - lib/capsium/converters/jekyll.rb
+- lib/capsium/log_buffer.rb
 - lib/capsium/package.rb
 - lib/capsium/package/authentication.rb
 - lib/capsium/package/authentication_config.rb
+- lib/capsium/package/bundle.rb
 - lib/capsium/package/cipher.rb
 - lib/capsium/package/composition.rb
 - lib/capsium/package/dataset.rb
@@ -236,6 +266,9 @@ files:
 - lib/capsium/package/merged_view.rb
 - lib/capsium/package/metadata.rb
 - lib/capsium/package/metadata_config.rb
+- lib/capsium/package/open_pgp.rb
+- lib/capsium/package/open_pgp_cipher.rb
+- lib/capsium/package/open_pgp_signer.rb
 - lib/capsium/package/preparation.rb
 - lib/capsium/package/routes.rb
 - lib/capsium/package/routes_config.rb
@@ -260,18 +293,33 @@ files:
 - lib/capsium/packager.rb
 - lib/capsium/reactor.rb
 - lib/capsium/reactor/authenticator.rb
+- lib/capsium/reactor/content_api.rb
+- lib/capsium/reactor/data_api.rb
 - lib/capsium/reactor/deploy.rb
+- lib/capsium/reactor/endpoints.rb
+- lib/capsium/reactor/graphql_api.rb
+- lib/capsium/reactor/graphql_schema.rb
 - lib/capsium/reactor/htpasswd.rb
 - lib/capsium/reactor/introspection.rb
+- lib/capsium/reactor/metrics.rb
+- lib/capsium/reactor/mount.rb
 - lib/capsium/reactor/oauth2.rb
+- lib/capsium/reactor/overlay.rb
+- lib/capsium/reactor/package_saver.rb
+- lib/capsium/reactor/responses.rb
 - lib/capsium/reactor/serving.rb
 - lib/capsium/reactor/session.rb
+- lib/capsium/registry.rb
+- lib/capsium/registry/local.rb
+- lib/capsium/registry/remote.rb
 - lib/capsium/thor_ext.rb
 - lib/capsium/version.rb
 - sig/capsium.rbs
+- sig/capsium/log_buffer.rbs
 - sig/capsium/package.rbs
 - sig/capsium/package/authentication.rbs
 - sig/capsium/package/authentication_config.rbs
+- sig/capsium/package/bundle.rbs
 - sig/capsium/package/cipher.rbs
 - sig/capsium/package/composition.rbs
 - sig/capsium/package/dataset.rbs
@@ -282,6 +330,9 @@ files:
 - sig/capsium/package/merged_view.rbs
 - sig/capsium/package/metadata.rbs
 - sig/capsium/package/metadata_config.rbs
+- sig/capsium/package/open_pgp.rbs
+- sig/capsium/package/open_pgp_cipher.rbs
+- sig/capsium/package/open_pgp_signer.rbs
 - sig/capsium/package/preparation.rbs
 - sig/capsium/package/routes.rbs
 - sig/capsium/package/routes_config.rbs
@@ -306,12 +357,26 @@ files:
 - sig/capsium/packager.rbs
 - sig/capsium/reactor.rbs
 - sig/capsium/reactor/authenticator.rbs
+- sig/capsium/reactor/content_api.rbs
+- sig/capsium/reactor/data_api.rbs
 - sig/capsium/reactor/deploy.rbs
+- sig/capsium/reactor/endpoints.rbs
+- sig/capsium/reactor/graphql_api.rbs
+- sig/capsium/reactor/graphql_schema.rbs
 - sig/capsium/reactor/htpasswd.rbs
 - sig/capsium/reactor/introspection.rbs
+- sig/capsium/reactor/metrics.rbs
+- sig/capsium/reactor/mount.rbs
 - sig/capsium/reactor/oauth2.rbs
+- sig/capsium/reactor/overlay.rbs
+- sig/capsium/reactor/package_saver.rbs
+- sig/capsium/reactor/responses.rbs
 - sig/capsium/reactor/serving.rbs
 - sig/capsium/reactor/session.rbs
+- sig/capsium/registry.rbs
+- sig/capsium/registry/local.rbs
+- sig/capsium/registry/remote.rbs
+- sig/graphql.rbs
 homepage: https://github.com/capsiums/capsium
 licenses:
 - MIT