capsium 0.3.0 → 0.6.0

data/lib/capsium/reactor.rb

@@ -1,40 +1,86 @@
 # frozen_string_literal: true
 
+require "fileutils"
 require "json"
 require "listen"
 require "tmpdir"
 require "webrick"
 
+# WEBrick's ProcHandler only dispatches do_GET/do_POST/do_PUT; the
+# writable-package API (REST CRUD, content writes) also needs DELETE
+# and PATCH. AbstractServlet#service looks the do_<METHOD> up per
+# request, so aliasing the missing verbs routes them to the same proc.
+# rubocop:disable Style/OneClassPerFile
+module WEBrick
+  module HTTPServlet
+    class ProcHandler < AbstractServlet
+      alias do_DELETE do_GET # rubocop:disable Naming/MethodName
+      alias do_PATCH do_GET # rubocop:disable Naming/MethodName
+    end
+  end
+end
+
 module Capsium
   class Reactor
     autoload :Authenticator, "capsium/reactor/authenticator"
+    autoload :ContentApi, "capsium/reactor/content_api"
+    autoload :DataApi, "capsium/reactor/data_api"
     autoload :Deploy, "capsium/reactor/deploy"
+    autoload :Endpoints, "capsium/reactor/endpoints"
+    autoload :GraphqlApi, "capsium/reactor/graphql_api"
+    autoload :GraphqlSchema, "capsium/reactor/graphql_schema"
     autoload :Htpasswd, "capsium/reactor/htpasswd"
     autoload :Introspection, "capsium/reactor/introspection"
+    autoload :Metrics, "capsium/reactor/metrics"
+    autoload :Mount, "capsium/reactor/mount"
+    autoload :MountConflictError, "capsium/reactor/mount"
     autoload :OAuth2, "capsium/reactor/oauth2"
+    autoload :Overlay, "capsium/reactor/overlay"
+    autoload :PackageSaver, "capsium/reactor/package_saver"
+    autoload :Responses, "capsium/reactor/responses"
     autoload :Serving, "capsium/reactor/serving"
     autoload :Session, "capsium/reactor/session"
 
+    include Responses
+    include Endpoints
     include Serving
 
     DEFAULT_PORT = 8864
     DEFAULT_CACHE_CONTROL = "public, max-age=31536000"
+    PACKAGE_SAVE_PATTERN = %r{\A/package/(?<name>[^/]+)/save\z}
 
     attr_reader :package, :package_path, :routes, :port, :cache_control,
-                :server, :server_thread, :introspection, :authenticator
-
-    def initialize(package:, port: DEFAULT_PORT,
+                :server, :server_thread, :introspection, :authenticator,
+                :store, :registry, :started_at, :metrics, :log_buffer,
+                :mounts, :workdir
+
+    # Serves one or more packages: either a single `package` (directory,
+    # .cap file or Package, mounted at "/") or a list of `mounts`
+    # (Reactor::Mount) resolved by longest-prefix matching. `workdir`
+    # holds the writable overlays (ARCHITECTURE.md section 5a) and
+    # saved packages; it defaults to a temporary directory the reactor
+    # removes on cleanup.
+    def initialize(package: nil, mounts: nil, port: DEFAULT_PORT,
                    cache_control: DEFAULT_CACHE_CONTROL, do_not_listen: false,
-                   store: nil, deploy: nil)
-      @package = package.is_a?(String) ? Package.new(package, store: store) : package
-      @package_path = @package.path
+                   store: nil, deploy: nil, registry: nil, workdir: nil)
       @store = store
+      @registry = registry
+      @workdir = workdir || Dir.mktmpdir("capsium-reactor-")
+      @own_workdir = workdir.nil?
+      @mounts = mounts || [Mount.new(path: Mount::ROOT_PATH, package: package,
+                                     store: store, registry: registry)]
+      @mounts.each { |mount| mount.attach_workdir(@workdir) }
       @port = port
       @cache_control = cache_control
+      @started_at = Time.now
+      @metrics = Metrics.new
+      @log_buffer = Capsium::LogBuffer.new
       @deploy_config = Deploy.load(deploy)
       setup_server(do_not_listen)
       load_state
       mount_routes
+      @log_buffer.add("reactor started: " \
+                      "#{@mounts.map(&:summary).join(', ')} on port #{@port}")
     end
 
     def serve
@@ -43,44 +89,43 @@ module Capsium
       start_listener
     end
 
+    # Entry point for every mounted path: dispatches the request, then
+    # records it in the request metrics and the log buffer.
     def handle_request(request, response)
-      if @authenticator.endpoint?(request.path)
-        @authenticator.serve_endpoint(request, response)
-        return
-      end
-
-      identity = @authenticator.authenticate(request)
-      return @authenticator.challenge(response) if @authenticator.enabled? && identity.nil?
-      return serve_introspection(request, response) if @introspection.endpoint?(request.path)
-
-      route = @routes.resolve(request.path)
-      return respond_not_found(response) unless route
-
-      case @authenticator.authorize(identity, route.access_control)
-      when :unauthenticated then return @authenticator.challenge(response)
-      when :forbidden then return respond_forbidden(response)
-      end
-
-      serve_route(route, response)
+      dispatch_request(request, response)
+    ensure
+      record_request(request, response)
     end
 
     def mount_routes
-      paths = @routes.config.routes.map(&:serving_path) +
-              Introspection::PATHS + @authenticator.endpoints
+      paths = Introspection::PATHS + Introspection::REACTOR_PATHS +
+              @authenticator.endpoints
+      paths.concat(@mounts.flat_map(&:server_paths))
       paths.each do |path|
         @server.mount_proc(path.to_s) { |req, res| handle_request(req, res) }
       end
+      # WEBrick longest-prefix matching: catches every "/package/...".
+      @server.mount_proc(Introspection::PACKAGE_MOUNT) do |req, res|
+        handle_request(req, res)
+      end
     end
 
     def restart_server
       @server.shutdown
       @server_thread&.join
-      load_package
+      load_packages
       setup_server(false)
       mount_routes
       @server_thread = start_server
     end
 
+    # Cleans up every mounted package (Package#cleanup for all) and the
+    # workdir when the reactor created it.
+    def cleanup
+      @mounts.each { |mount| mount.package.cleanup }
+      FileUtils.remove_entry(@workdir) if @own_workdir && File.directory?(@workdir)
+    end
+
     private
 
     def setup_server(do_not_listen)
@@ -113,15 +158,20 @@ module Capsium
       @server_thread.join
     end
 
-    def load_package
-      @package = Package.new(@package_path, store: @store)
+    def load_packages
+      @mounts.each do |mount|
+        @log_buffer.add("package reloaded: #{mount.reload.name}")
+      end
       load_state
     end
 
     def load_state
-      @routes = @package.routes
-      @merged_view = @package.merged_view
-      @introspection = Introspection.new(@package)
+      root = root_mount
+      @package = root.package
+      @package_path = @package.path
+      @routes = root.routes
+      @merged_view = root.merged_view
+      @introspection = Introspection.new(@mounts.map(&:package), reactor: self)
       @authenticator = Authenticator.new(
         @package.authentication,
         deploy: @deploy_config,
@@ -131,26 +181,23 @@ module Capsium
       )
     end
 
-    def serve_introspection(request, response)
-      return respond_method_not_allowed(response) unless request.request_method == "GET"
-
-      response.status = 200
-      response["Content-Type"] = "application/json"
-      response.body = JSON.generate(@introspection.report_for(request.path))
-    end
-
-    def respond_not_found(response) = respond_text(response, 404, "Not Found")
-
-    def respond_forbidden(response) = respond_text(response, 403, "Forbidden")
+    def dispatch_request(request, response)
+      if @authenticator.endpoint?(request.path)
+        @authenticator.serve_endpoint(request, response)
+        return
+      end
 
-    def respond_not_implemented(response) = respond_text(response, 501, "Not Implemented")
+      identity = @authenticator.authenticate(request)
+      return @authenticator.challenge(response) if @authenticator.enabled? && identity.nil?
+      return serve_introspection(request, response) if @introspection.endpoint?(request.path)
+      return serve_package_save(request, response) if PACKAGE_SAVE_PATTERN.match?(request.path)
 
-    def respond_method_not_allowed(response) = respond_text(response, 405, "Method Not Allowed")
+      mount = resolve_mount(request.path)
+      return respond_not_found(response) unless mount
 
-    def respond_text(response, status, body)
-      response.status = status
-      response["Content-Type"] = "text/plain"
-      response.body = body
+      serve_mounted_request(mount, identity, request, response)
     end
   end
 end
+
+# rubocop:enable Style/OneClassPerFile

data/lib/capsium/registry/local.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+
+module Capsium
+  class Registry
+    # A static registry in a local directory (read-write). Push
+    # validates the .cap (Capsium::Package::Validator), copies it into
+    # the registry directory and atomically rewrites index.json
+    # (tmp + rename) with recomputed sha256 and size.
+    class Local < Registry
+      attr_reader :dir
+
+      def initialize(dir)
+        super()
+        if File.exist?(dir) && !File.directory?(dir)
+          raise InvalidRegistryError, "registry path is not a directory: #{dir}"
+        end
+
+        @dir = dir
+      end
+
+      def location = dir
+
+      # Validates cap_path, copies it into the registry as
+      # "<name>-<version>.cap" and records it in index.json. Returns the
+      # recorded Entry. Raises InvalidPackageError when the package
+      # fails validation.
+      def push(cap_path)
+        validate_package!(cap_path)
+        entry = build_entry(read_metadata(cap_path), cap_path)
+        FileUtils.mkdir_p(dir)
+        atomic_copy(cap_path, File.join(dir, entry.file))
+        record(entry)
+        entry
+      end
+
+      private
+
+      def index
+        @index ||= begin
+          path = File.join(dir, INDEX_FILE)
+          File.file?(path) ? parse_index(File.read(path)) : { "packages" => {} }
+        end
+      end
+
+      def with_entry_file(entry)
+        path = File.join(dir, entry.file)
+        unless File.file?(path)
+          raise InvalidRegistryError, "#{location}: indexed file missing: #{entry.file}"
+        end
+
+        yield path
+      end
+
+      def validate_package!(cap_path)
+        raise InvalidPackageError, "not a file: #{cap_path}" unless File.file?(cap_path)
+
+        failures = Package::Validator.new(cap_path).run.reject(&:ok?)
+        return if failures.empty?
+
+        details = failures.flat_map do |failure|
+          failure.messages.map { |message| "#{failure.name}: #{message}" }
+        end
+        raise InvalidPackageError,
+              "package validation failed for #{cap_path} — #{details.join('; ')}"
+      end
+
+      def read_metadata(cap_path)
+        Packager.new.with_unpacked_cap(cap_path) do |unpacked|
+          JSON.parse(File.read(File.join(unpacked, Package::METADATA_FILE)))
+        end
+      end
+
+      def build_entry(metadata, cap_path)
+        guid = metadata["guid"]
+        name = metadata["name"]
+        version = metadata["version"]
+        unless guid.is_a?(String) && name.is_a?(String) && version.is_a?(String)
+          raise InvalidPackageError, "metadata.json must declare guid, name and version"
+        end
+
+        Entry.new(guid: guid, name: name, version: parse_package_version(version),
+                  file: "#{name}-#{version}.cap",
+                  sha256: Digest::SHA256.file(cap_path).hexdigest,
+                  size: File.size(cap_path))
+      end
+
+      def parse_package_version(string)
+        Package::Version.parse(string)
+      rescue Capsium::Error => e
+        raise InvalidPackageError, "metadata.json version is invalid: #{e.message}"
+      end
+
+      def record(entry)
+        listing = index["packages"][entry.guid] ||
+                  { "name" => entry.name, "versions" => {} }
+        listing["versions"][entry.version.to_s] = {
+          "file" => entry.file, "sha256" => entry.sha256, "size" => entry.size
+        }
+        index["packages"][entry.guid] = listing
+        atomic_write(File.join(dir, INDEX_FILE), JSON.pretty_generate(index))
+      end
+
+      def atomic_copy(source, destination)
+        tmp = "#{destination}.tmp-#{Process.pid}"
+        FileUtils.cp(source, tmp)
+        File.rename(tmp, destination)
+      end
+
+      def atomic_write(path, content)
+        tmp = "#{path}.tmp-#{Process.pid}"
+        File.write(tmp, content)
+        File.rename(tmp, path)
+      end
+    end
+  end
+end

data/lib/capsium/registry/remote.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "json"
+require "net/http"
+require "openssl"
+require "tempfile"
+require "timeout"
+require "uri"
+
+module Capsium
+  class Registry
+    # A read-only static registry behind an https base URL (any static
+    # host: GitHub Pages, S3, nginx). index.json and .cap files are
+    # fetched over net/http with redirect following and timeouts; plain
+    # http is accepted for loopback hosts only (local development).
+    class Remote < Registry
+      OPEN_TIMEOUT = 5
+      READ_TIMEOUT = 15
+      MAX_REDIRECTS = 5
+      LOOPBACK_NETWORKS = [IPAddr.new("127.0.0.0/8"), IPAddr.new("::1/128")].freeze
+
+      attr_reader :base_url
+
+      def initialize(base_url)
+        super()
+        @base_url = base_url.to_s.sub(%r{/+\z}, "")
+        validate_scheme!(request_uri(INDEX_FILE))
+      end
+
+      def location = base_url
+
+      private
+
+      def index
+        @index ||= parse_index(fetch_bytes(INDEX_FILE))
+      rescue FetchError => e
+        raise InvalidRegistryError, "no readable #{INDEX_FILE} at #{base_url}: #{e.message}"
+      end
+
+      def with_entry_file(entry)
+        Tempfile.create(["capsium-registry", ".cap"]) do |tmp|
+          tmp.binmode
+          tmp.write(fetch_bytes(entry.file))
+          tmp.flush
+          yield tmp.path
+        end
+      end
+
+      def fetch_bytes(relative_path)
+        uri = request_uri(relative_path)
+        MAX_REDIRECTS.times do
+          response = http_get(uri)
+          return response.body if response.is_a?(Net::HTTPSuccess)
+
+          uri = follow_redirect(uri, response)
+        end
+        raise FetchError, "GET #{uri}: too many redirects (limit #{MAX_REDIRECTS})"
+      end
+
+      def follow_redirect(uri, response)
+        location = response["location"] if response.is_a?(Net::HTTPRedirection)
+        raise FetchError, "GET #{uri} failed: HTTP #{response.code}" if location.nil?
+
+        target = URI.join(uri.to_s, location)
+        validate_scheme!(target)
+        target
+      end
+
+      def http_get(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.is_a?(URI::HTTPS)
+        http.open_timeout = OPEN_TIMEOUT
+        http.read_timeout = READ_TIMEOUT
+        http.request(Net::HTTP::Get.new(uri.request_uri))
+      rescue Timeout::Error, SocketError, SystemCallError,
+             OpenSSL::SSL::SSLError => e
+        raise FetchError, "GET #{uri} failed: #{e.message}"
+      end
+
+      def request_uri(relative_path)
+        URI.parse("#{base_url}/#{relative_path}")
+      rescue URI::InvalidURIError => e
+        raise InvalidRegistryError, "invalid registry URL #{base_url.inspect}: #{e.message}"
+      end
+
+      def validate_scheme!(uri)
+        return if uri.is_a?(URI::HTTPS)
+        return if uri.is_a?(URI::HTTP) && loopback_host?(uri.host)
+
+        raise InvalidRegistryError,
+              "registry URL must use https (plain http for loopback only): #{uri}"
+      end
+
+      def loopback_host?(host)
+        return true if host == "localhost" || host.to_s.end_with?(".localhost")
+
+        address = IPAddr.new(host)
+        LOOPBACK_NETWORKS.any? { |network| network.include?(address) }
+      rescue IPAddr::InvalidAddressError
+        false
+      end
+    end
+  end
+end

data/lib/capsium/registry.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+
+module Capsium
+  # A static package registry: a directory or a static https base URL
+  # holding an index.json plus .cap files stored relative to the
+  # registry root, so any static host (GitHub Pages, S3, nginx) can
+  # serve it. Index shape:
+  #
+  #   { "packages": { "<guid>": { "name": "story-of-claire",
+  #     "versions": { "1.0.0": { "file": "story-of-claire-1.0.0.cap",
+  #                              "sha256": "<hex>", "size": 642047 } } } } }
+  #
+  # Registry.fetch(ref) returns the implementation for a reference: a
+  # Local directory (read-write) or a Remote http(s) base URL
+  # (read-only). Both resolve and install; only Local pushes.
+  class Registry
+    autoload :Local, "capsium/registry/local"
+    autoload :Remote, "capsium/registry/remote"
+
+    INDEX_FILE = "index.json"
+    ENV_VAR = "CAPSIUM_REGISTRY"
+
+    # 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.
+    Entry = Data.define(:guid, :name, :version, :file, :sha256, :size) do
+      # The canonical store file name for this entry's .cap.
+      def cap_file_name = "#{name}-#{version}.cap"
+    end
+
+    class << self
+      # The registry at the given reference: a Local directory or a
+      # Remote http(s) base URL. Raises RegistryNotConfiguredError when
+      # no reference is given.
+      def fetch(ref)
+        if ref.nil? || ref.to_s.empty?
+          raise RegistryNotConfiguredError,
+                "no registry configured (pass --registry or set #{ENV_VAR})"
+        end
+
+        ref.to_s.match?(%r{\Ahttps?://}) ? Remote.new(ref.to_s) : Local.new(ref.to_s)
+      end
+
+      # The registry named by the CAPSIUM_REGISTRY environment variable,
+      # or nil when unset.
+      def default
+        ref = ENV.fetch(ENV_VAR, nil)
+        ref.nil? || ref.empty? ? nil : fetch(ref)
+      end
+    end
+
+    def initialize
+      @index = nil
+    end
+
+    # Where this registry lives (directory path or base URL), for
+    # messages and reports.
+    def location = raise(NotImplementedError)
+
+    # The newest indexed version of the package GUID satisfying the
+    # semver constraint (default "*"). Raises PackageNotFoundError or
+    # UnsatisfiableConstraintError.
+    def resolve(guid, constraint = "*")
+      listing = packages[guid]
+      raise PackageNotFoundError, "no package #{guid} in registry #{location}" if listing.nil?
+
+      versions = listing_versions(guid, listing)
+      range = Package::VersionRange.parse(constraint)
+      satisfying = versions.keys.select { |version| range.satisfied_by?(version) }
+      raise_unsatisfiable(guid, constraint, versions) if satisfying.empty?
+
+      entry_for(guid, listing, satisfying.max)
+    end
+
+    # Resolves the newest satisfying version, fetches its .cap (verifying
+    # the sha256 declared in the index) and installs it into the package
+    # store as "<name>-<version>.cap". Returns the installed store path.
+    def install(guid, constraint = "*", store:)
+      entry = resolve(guid, constraint)
+      with_entry_file(entry) do |path|
+        verify_checksum!(entry, path)
+        store_for(store).install(path, guid: entry.guid, file_name: entry.cap_file_name)
+      end
+    end
+
+    # Only Local registries are writable; Remote overrides nothing.
+    def push(_cap_path)
+      raise RegistryError, "registry is read-only: #{location}"
+    end
+
+    private
+
+    # Subclass hooks: the parsed index.json hash, and a yield of a local
+    # filesystem path holding the entry's .cap bytes.
+    def index = raise(NotImplementedError)
+
+    def with_entry_file(entry) = raise(NotImplementedError)
+
+    def packages
+      all = index["packages"]
+      unless all.is_a?(Hash)
+        raise InvalidRegistryError, "#{location}: #{INDEX_FILE} has no \"packages\" object"
+      end
+
+      all
+    end
+
+    def parse_index(json_text)
+      JSON.parse(json_text)
+    rescue JSON::ParserError => e
+      raise InvalidRegistryError, "#{location}: #{INDEX_FILE} is not valid JSON: #{e.message}"
+    end
+
+    def listing_versions(guid, listing)
+      versions = listing["versions"]
+      unless versions.is_a?(Hash) && !versions.empty?
+        raise InvalidRegistryError, "#{location}: no versions indexed for #{guid}"
+      end
+
+      versions.to_h { |string, data| [parse_index_version(guid, string), data] }
+    end
+
+    def parse_index_version(guid, string)
+      Package::Version.parse(string)
+    rescue Capsium::Error
+      raise InvalidRegistryError, "#{location}: invalid version #{string.inspect} for #{guid}"
+    end
+
+    def raise_unsatisfiable(guid, constraint, versions)
+      available = versions.keys.map(&:to_s).sort.join(", ")
+      raise UnsatisfiableConstraintError,
+            "no version of #{guid} satisfies '#{constraint}' (registry has: #{available})"
+    end
+
+    def entry_for(guid, listing, version)
+      data = listing.fetch("versions").fetch(version.to_s)
+      unless data["file"].is_a?(String) && data["sha256"].is_a?(String)
+        raise InvalidRegistryError,
+              "#{location}: incomplete index entry for #{guid} #{version} (file/sha256)"
+      end
+
+      Entry.new(guid: guid, name: listing["name"].to_s, version: version,
+                file: data["file"], sha256: data["sha256"], size: data["size"].to_i)
+    end
+
+    def verify_checksum!(entry, path)
+      actual = Digest::SHA256.file(path).hexdigest
+      return if actual == entry.sha256.downcase
+
+      raise ChecksumMismatchError,
+            "sha256 mismatch for #{entry.cap_file_name} from #{location}: " \
+            "index declares #{entry.sha256}, file hashes to #{actual}"
+    end
+
+    # A Store for the given Store or directory path (created when
+    # missing, so installing into a fresh store directory works).
+    def store_for(store)
+      return store if store.is_a?(Package::Store)
+
+      FileUtils.mkdir_p(store.to_s)
+      Package::Store.new(store.to_s)
+    end
+  end
+end

data/lib/capsium/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Capsium
-  VERSION = "0.3.0"
+  VERSION = "0.6.0"
 end

data/lib/capsium.rb

@@ -6,8 +6,10 @@ module Capsium
   autoload :VERSION, "capsium/version"
   autoload :Cli, "capsium/cli"
   autoload :Converters, "capsium/converters"
+  autoload :LogBuffer, "capsium/log_buffer"
   autoload :Package, "capsium/package"
   autoload :Packager, "capsium/packager"
   autoload :Reactor, "capsium/reactor"
+  autoload :Registry, "capsium/registry"
   autoload :ThorExt, "capsium/thor_ext"
 end

data/sig/capsium/log_buffer.rbs

@@ -0,0 +1,30 @@
+module Capsium
+  # A small thread-safe ring buffer of timestamped log entries with a
+  # fixed capacity: when full, the oldest entry is dropped.
+  class LogBuffer
+    DEFAULT_CAPACITY: Integer
+
+    # One buffer entry: a UTC timestamp and a message.
+    class Entry
+      def self.new: (timestamp: Time, message: String) -> void
+
+      def timestamp: () -> Time
+      def message: () -> String
+
+      # "2026-07-19T15:00:00Z message"
+      def line: () -> String
+    end
+
+    attr_reader capacity: Integer
+
+    def initialize: (?capacity: Integer capacity) -> void
+
+    def add: (String message, ?timestamp: Time timestamp) -> LogBuffer
+
+    # The last n entries, oldest first.
+    def last: (Integer count) -> Array[Entry]
+
+    # The last n entries as formatted lines, oldest first.
+    def lines: (Integer count) -> Array[String]
+  end
+end