capsium 0.2.0 → 0.6.0

data/lib/capsium/reactor/introspection.rb

@@ -3,12 +3,16 @@
 require "digest"
 require "json"
 require "time"
+require "uri"
 
 module Capsium
   class Reactor
-    # Monitoring HTTP API reports for the package this reactor serves
-    # (ARCHITECTURE.md section 7). Each report wraps its single entry in
-    # the list shape all reactors converge on.
+    # Monitoring HTTP API reports for the packages this reactor serves
+    # (ARCHITECTURE.md section 7): the package-level
+    # /api/v1/introspect/* endpoints aggregate ALL mounted packages, the
+    # 07-reactor follow-ons add reactor-level /introspect/* (status,
+    # config, metrics) and per-package /package/:id/* (status, metadata,
+    # logs) resolved by package name.
     class Introspection
       METADATA_PATH = "/api/v1/introspect/metadata"
       ROUTES_PATH = "/api/v1/introspect/routes"
@@ -17,70 +21,186 @@ module Capsium
       PATHS = [METADATA_PATH, ROUTES_PATH, CONTENT_HASHES_PATH,
                CONTENT_VALIDITY_PATH].freeze
 
-      attr_reader :package
+      STATUS_PATH = "/introspect/status"
+      CONFIG_PATH = "/introspect/config"
+      METRICS_PATH = "/introspect/metrics"
+      REACTOR_PATHS = [STATUS_PATH, CONFIG_PATH, METRICS_PATH].freeze
 
-      def initialize(package)
-        @package = package
+      # Per-package endpoints: "/package/<name>/status|metadata|logs".
+      # PACKAGE_MOUNT is the mount point (WEBrick longest-prefix
+      # matching routes all "/package/..." requests to the reactor);
+      # the name resolves against every mounted package, anything else
+      # is a 404.
+      PACKAGE_MOUNT = "/package"
+      PACKAGE_PATH_PATTERN = %r{\A/package/(?<name>[^/]+)/(?<report>status|metadata|logs)\z}
+      DEFAULT_LOG_LINES = 100
+      MAX_LOG_LINES = 1000
+
+      attr_reader :packages
+
+      # The packages this reactor serves (one per mount; ARCHITECTURE.md
+      # section 7 introspection aggregates all of them).
+      def initialize(packages, reactor: nil)
+        @packages = packages
+        @reactor = reactor
       end
 
+      # The first mounted package (the single-package view).
+      def package = @packages.first
+
       def endpoint?(path)
-        PATHS.include?(path)
+        PATHS.include?(path) || package_endpoint?(path) ||
+          (!@reactor.nil? && REACTOR_PATHS.include?(path))
       end
 
-      # The report body for an introspection endpoint, or nil when the
-      # path is not an introspection endpoint.
-      def report_for(path)
+      # 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(path, params: {})
         case path
         when METADATA_PATH then metadata_report
         when ROUTES_PATH then routes_report
         when CONTENT_HASHES_PATH then content_hashes_report
         when CONTENT_VALIDITY_PATH then content_validity_report
+        when STATUS_PATH then status_report
+        when CONFIG_PATH then config_report
+        when METRICS_PATH then metrics_report
+        else package_report_for(path, params)
         end
       end
 
       def metadata_report
-        metadata = package.metadata
-        { packages: [{
-          name: metadata.name,
-          version: metadata.version,
-          author: metadata.author,
-          description: metadata.description
-        }] }
+        { packages: @packages.map { |pkg| metadata_entry(pkg) } }
       end
 
       def routes_report
-        entries = package.routes.config.routes.map do |route|
-          { method: route.http_method || "GET", path: route.path }
+        entries = @packages.map do |pkg|
+          routes = pkg.routes.config.routes.map do |route|
+            { method: route.http_method || "GET", path: route.path }
+          end
+          { package: pkg.name, routes: routes }
         end
-        { routes: [{ package: package.name, routes: entries }] }
+        { routes: entries }
       end
 
       def content_hashes_report
-        { contentHashes: [{ package: package.name, hash: content_hash }] }
+        entries = @packages.map do |pkg|
+          { package: pkg.name, hash: content_hash(pkg) }
+        end
+        { contentHashes: entries }
       end
 
       def content_validity_report
-        errors = package.verify_integrity
-        entry = {
-          package: package.name,
-          valid: errors.empty?,
-          lastChecked: Time.now.utc.iso8601
+        { contentValidity: @packages.map { |pkg| content_validity_entry(pkg) } }
+      end
+
+      def status_report
+        { status: "running", uptime: uptime, packagesLoaded: @packages.size }
+      end
+
+      # Reactor configuration; secrets (deploy.json, registry URL
+      # credentials) are never exposed.
+      def config_report
+        {
+          port: @reactor.port,
+          storeDir: store_dir,
+          cacheControl: @reactor.cache_control,
+          authEnabled: @reactor.authenticator.enabled?,
+          registry: registry_location
         }
-        entry[:reason] = errors.map(&:message).join("; ") unless errors.empty?
-        { contentValidity: [entry] }
       end
 
+      def metrics_report = @reactor.metrics.snapshot.merge(uptime: uptime)
+
       private
 
+      def package_endpoint?(path) = !PACKAGE_PATH_PATTERN.match(path).nil?
+
+      def package_report_for(path, params)
+        match = PACKAGE_PATH_PATTERN.match(path)
+        return nil unless match
+
+        pkg = @packages.find { |candidate| candidate.name == match[:name] }
+        return nil unless pkg
+
+        case match[:report]
+        when "status" then package_status_report(pkg)
+        when "metadata" then package_metadata_report(pkg)
+        when "logs" then package_logs_report(pkg, params)
+        end
+      end
+
+      def metadata_entry(pkg)
+        metadata = pkg.metadata
+        { name: metadata.name, version: metadata.version,
+          author: metadata.author, description: metadata.description }
+      end
+
+      def content_validity_entry(pkg)
+        errors = pkg.verify_integrity
+        entry = { package: pkg.name, valid: errors.empty?,
+                  lastChecked: Time.now.utc.iso8601,
+                  signed: pkg.signed?, encrypted: pkg.encrypted? }
+        entry[:signatureValid] = pkg.verify_signature if pkg.signed?
+        entry[:reason] = errors.map(&:message).join("; ") unless errors.empty?
+        entry
+      end
+
+      def package_status_report(pkg)
+        { package: pkg.name, version: pkg.metadata.version,
+          status: "loaded", valid: pkg.verify_integrity.empty? }
+      end
+
+      def package_metadata_report(pkg)
+        metadata = pkg.metadata
+        { name: metadata.name, version: metadata.version,
+          description: metadata.description, author: metadata.author,
+          guid: metadata.guid }
+      end
+
+      def package_logs_report(pkg, params)
+        lines = @reactor ? @reactor.log_buffer.lines(log_line_count(params)) : []
+        { package: pkg.name, logs: lines }
+      end
+
+      def log_line_count(params)
+        Integer(params["lines"] || DEFAULT_LOG_LINES).clamp(1, MAX_LOG_LINES)
+      rescue ArgumentError, TypeError
+        DEFAULT_LOG_LINES
+      end
+
+      def uptime = (Time.now - @reactor.started_at).round
+
+      def store_dir
+        store = @reactor.store
+        store.is_a?(Package::Store) ? store.dir : store
+      end
+
+      def registry_location
+        registry = @reactor.registry
+        redact(registry.is_a?(Capsium::Registry) ? registry.location : registry)
+      end
+
+      # Strips any userinfo (credentials) from a URL reference.
+      def redact(ref)
+        return ref unless ref.is_a?(String) && ref.match?(%r{\Ahttps?://})
+
+        uri = URI.parse(ref)
+        uri.password = nil
+        uri.user = nil
+        uri.to_s
+      rescue URI::InvalidURIError
+        ref
+      end
+
       # SHA-256 of the .cap blob when the package was loaded from one.
       # For directory sources there is no blob, so the hash covers a
       # canonical (sorted-key) JSON serialization of the package content
       # checksums — the same data security.json integrityChecks carry.
-      def content_hash
-        cap_file = package.cap_file_path
+      def content_hash(pkg)
+        cap_file = pkg.cap_file_path
         return Digest::SHA256.file(cap_file).hexdigest if cap_file
 
-        checksums = Package::Security.checksums_for(package.path)
+        checksums = Package::Security.checksums_for(pkg.path)
         Digest::SHA256.hexdigest(JSON.generate(checksums))
       end
     end

data/lib/capsium/reactor/metrics.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Reactor
+    # Minimal in-memory request counters for the /introspect/metrics
+    # endpoint (07-reactor): total requests plus a breakdown by HTTP
+    # status, thread-safe via Mutex (WEBrick serves concurrently).
+    class Metrics
+      def initialize
+        @mutex = Mutex.new
+        @total = 0
+        @by_status = Hash.new(0)
+      end
+
+      def record(status)
+        @mutex.synchronize do
+          @total += 1
+          @by_status[status.to_i] += 1
+        end
+        self
+      end
+
+      def snapshot
+        @mutex.synchronize do
+          { requestsTotal: @total, requestsByStatus: @by_status.dup }
+        end
+      end
+    end
+  end
+end

data/lib/capsium/reactor/mount.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "json"
+
+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 (routes, merged view; ARCHITECTURE.md section 7).
+    # The reactor serves a list of mounts resolved by longest-prefix
+    # matching. Default mount points: the first source at "/", each
+    # additional source at "/<metadata.name>/".
+    class Mount
+      ROOT_PATH = "/"
+      SPEC_SEPARATOR = "="
+
+      # 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 or .cap file, "store" optionally
+      # overrides the global package store for this mount.
+      Entry = Data.define(:path, :source, :store)
+
+      attr_reader :path, :package, :overlay
+
+      # Parses a "--mount PATH=SOURCE" command-line value into an Entry.
+      def self.parse_spec(spec)
+        path, separator, source = spec.to_s.partition(SPEC_SEPARATOR)
+        if separator.empty? || path.empty? || source.empty?
+          raise Error, "Invalid mount spec #{spec.inspect} (expected PATH=SOURCE)"
+        end
+
+        Entry.new(path: path, source: source, store: nil)
+      end
+
+      # The mount entries of a JSON config file:
+      # {"mounts": [{"path": "/", "source": "dir-or.cap", "store": "..."}]}
+      def self.config_entries(config_file)
+        doc = JSON.parse(File.read(config_file))
+        mounts = doc.is_a?(Hash) ? doc["mounts"] : nil
+        unless mounts.is_a?(Array) && mounts.all?(Hash)
+          raise Error, "Invalid mount config #{config_file}: expected " \
+                       '{"mounts": [{"path": ..., "source": ...}]}'
+        end
+
+        mounts.map do |entry|
+          unless entry["source"].is_a?(String)
+            raise Error, "Invalid mount config #{config_file}: every mount " \
+                         "needs a \"source\""
+          end
+
+          Entry.new(path: entry["path"], source: entry["source"],
+                    store: entry["store"])
+        end
+      rescue JSON::ParserError => e
+        raise Error, "Invalid mount config #{config_file}: #{e.message}"
+      end
+
+      # Builds the mounts for a list of entries: loads each package,
+      # assigns default paths (first entry "/", each additional
+      # "/<metadata.name>/") and rejects duplicate prefixes with a
+      # MountConflictError. On failure every package loaded so far is
+      # cleaned up again.
+      def self.build(entries, store: nil, registry: nil)
+        built = []
+        entries.each_with_index do |entry, index|
+          package_store = entry.store || store
+          package = load_package(entry.source, package_store, registry)
+          path = entry.path || default_path(index, package)
+          built << new(path: path, package: package,
+                       store: package_store, registry: registry)
+        end
+        check_conflicts!(built)
+        built
+      rescue StandardError
+        built.each { |mount| mount.package.cleanup }
+        raise
+      end
+
+      # Loads a mount source (a package directory, .cap file or an
+      # already-built Package) with the given resolution context.
+      def self.load_package(source, store, registry)
+        return source unless source.is_a?(String)
+
+        Package.new(source, store: store, registry: registry)
+      end
+
+      def self.default_path(index, package)
+        index.zero? ? ROOT_PATH : "#{ROOT_PATH}#{package.name}"
+      end
+      private_class_method :default_path
+
+      def self.check_conflicts!(built)
+        paths = built.map(&:path)
+        duplicates = paths.tally.select { |_path, count| count > 1 }.keys
+        return if duplicates.empty?
+
+        raise MountConflictError,
+              "mount path conflict: #{duplicates.join(', ')} is mounted twice"
+      end
+      private_class_method :check_conflicts!
+
+      # Canonical mount prefix: leading "/", no trailing "/" (except the
+      # root itself).
+      def self.normalize_path(path)
+        return ROOT_PATH if path.nil? || path == ROOT_PATH
+
+        normalized = path.start_with?(ROOT_PATH) ? path : "#{ROOT_PATH}#{path}"
+        normalized.chomp(ROOT_PATH)
+      end
+
+      def initialize(path:, package:, store: nil, registry: nil, workdir: nil)
+        @path = self.class.normalize_path(path)
+        @store = store
+        @registry = registry
+        @package = self.class.load_package(package, store, registry)
+        attach_workdir(workdir) if workdir
+      end
+
+      # Attaches the reactor workdir: the writable overlay (topmost
+      # layer, ARCHITECTURE.md section 5a) lives under it. Reads always
+      # resolve through the overlay; writes require #writable?.
+      def attach_workdir(workdir)
+        @overlay = Overlay.new(root: File.join(workdir, "overlays", @package.name))
+      end
+
+      # Writable unless the package declares "readOnly": true; writes
+      # then produce 403s and no overlay state is recorded.
+      def writable?
+        !@overlay.nil? && @package.metadata.read_only != true
+      end
+
+      # Whether this mount answers the given request path: the prefix
+      # itself or anything below it. The root mount answers everything.
+      def matches?(request_path)
+        path == ROOT_PATH || request_path == path ||
+          request_path.start_with?("#{path}#{ROOT_PATH}")
+      end
+
+      # The package-local path for a request path under this mount
+      # ("/" when the request hits the mount prefix itself).
+      def inner_path(request_path)
+        inner = request_path.delete_prefix(path)
+        return ROOT_PATH if inner.empty?
+        return inner if inner.start_with?(ROOT_PATH)
+
+        "#{ROOT_PATH}#{inner}"
+      end
+
+      def routes = @package.routes
+
+      # The merged content view; the overlay is always the topmost
+      # layer when a workdir is attached (hot-swap: content writes and
+      # tombstones resolve on the next request).
+      def merged_view
+        @merged_view ||= if @overlay
+                           @package.merged_view(extra_layers: [@overlay.layer])
+                         else
+                           @package.merged_view
+                         end
+      end
+
+      # The dataset as served: base data merged with the overlay's
+      # mutation log.
+      def dataset_data(dataset)
+        @overlay ? @overlay.dataset_data(dataset) : dataset.data
+      end
+
+      def data_api = @data_api ||= DataApi.new(self)
+
+      def content_api = @content_api ||= ContentApi.new(self)
+
+      # Whether this mount exposes a GraphQL API (any file-backed
+      # dataset; SQLite datasets are skipped).
+      def graphql?
+        @package.storage.datasets.any? { |dataset| !dataset.config.sqlite? }
+      end
+
+      def graphql_api = @graphql_api ||= GraphqlApi.new(self)
+
+      # The one-line "name version" summary used in reactor logs.
+      def summary = "#{@package.name} #{@package.metadata.version}"
+
+      # The WEBrick mount points serving this mount: every serving path
+      # for the root mount (unchanged single-package behavior), the
+      # prefix itself for a non-root mount (longest-prefix matching
+      # routes everything below it to the reactor).
+      def server_paths
+        return [path] unless path == ROOT_PATH
+
+        routes.config.routes.map(&:serving_path)
+      end
+
+      # Reloads the package from its (prepared) path, e.g. after the
+      # filesystem listener noticed changes. The overlay survives (it
+      # lives in the reactor workdir, not in the package).
+      def reload
+        @merged_view = nil
+        @graphql_api = nil
+        @package = Package.new(@package.path, store: @store, registry: @registry)
+      end
+    end
+  end
+end

data/lib/capsium/reactor/oauth2.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "securerandom"
+require "uri"
+
+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. State is a random nonce signed
+    # with the session HMAC key (CSRF protection, self-contained).
+    class OAuth2
+      # The token exchange or userinfo fetch failed at the provider.
+      class FlowError < Capsium::Error; end
+
+      GRANT_TYPE = "authorization_code"
+
+      attr_reader :config
+
+      def initialize(config, client_secret:, session:, base_url: nil)
+        @config = config
+        @client_secret = client_secret
+        @session = session
+        @base_url = base_url
+      end
+
+      # The provider URL the login endpoint redirects the browser to.
+      def authorization_url(request)
+        params = {
+          "response_type" => "code",
+          "client_id" => @config.client_id,
+          "redirect_uri" => callback_uri(request),
+          "state" => generate_state
+        }
+        params["scope"] = @config.scopes.join(" ") unless @config.scopes.empty?
+        "#{@config.authorization_url}?#{URI.encode_www_form(params)}"
+      end
+
+      def valid_state?(state)
+        nonce, signature = state.to_s.split(".", 2)
+        return false if nonce.nil? || nonce.empty? || signature.nil?
+
+        Reactor.secure_compare(@session.sign(nonce), signature)
+      end
+
+      # Exchanges the authorization code and fetches the userinfo claims.
+      # Returns the raw userinfo hash; raises FlowError on provider
+      # errors.
+      def complete(code, request)
+        userinfo(exchange_code(code, callback_uri(request)))
+      end
+
+      def callback_uri(request)
+        "#{base_url_for(request)}#{@config.redirect_path}"
+      end
+
+      private
+
+      def generate_state
+        nonce = SecureRandom.hex(16)
+        "#{nonce}.#{@session.sign(nonce)}"
+      end
+
+      def base_url_for(request)
+        @base_url || "http://#{request['Host']}"
+      end
+
+      def exchange_code(code, redirect_uri)
+        response = Net::HTTP.post_form(
+          URI(@config.token_url),
+          "grant_type" => GRANT_TYPE, "code" => code,
+          "redirect_uri" => redirect_uri, "client_id" => @config.client_id,
+          "client_secret" => @client_secret
+        )
+        unless response.is_a?(Net::HTTPSuccess)
+          raise FlowError, "token exchange failed (HTTP #{response.code})"
+        end
+
+        JSON.parse(response.body).fetch("access_token") do
+          raise FlowError, "token response without access_token"
+        end
+      rescue JSON::ParserError
+        raise FlowError, "token response was not JSON"
+      end
+
+      def userinfo(access_token)
+        uri = URI(@config.userinfo_url)
+        response = Net::HTTP.start(uri.host, uri.port,
+                                   use_ssl: uri.scheme == "https") do |http|
+          http.get(uri.request_uri,
+                   "authorization" => "Bearer #{access_token}",
+                   "accept" => "application/json")
+        end
+        unless response.is_a?(Net::HTTPSuccess)
+          raise FlowError, "userinfo request failed (HTTP #{response.code})"
+        end
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise FlowError, "userinfo response was not JSON"
+      end
+    end
+  end
+end