capsium 0.3.0 → 0.6.0

data/lib/capsium/reactor/graphql_schema.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "graphql"
+
+module Capsium
+  class Reactor
+    # Builds the GraphQL schema for a mounted package (ARCHITECTURE.md
+    # section 5): per dataset a query field "<dataset>" (list, optional
+    # "id:" argument for a single item) plus
+    # create<Dataset>/update<Dataset>/delete<Dataset> mutations.
+    # Item types are inferred from the dataset's JSON schema when
+    # present, else map to a permissive JSON scalar. Field resolvers
+    # delegate to the given API object's public methods.
+    class GraphqlSchema
+      # Permissive scalar carrying any JSON value (schema-less items,
+      # mutation inputs, nested structures).
+      class JsonScalar < GraphQL::Schema::Scalar
+        graphql_name("JSON")
+        description "An arbitrary JSON value"
+
+        def self.coerce_input(input_value, _context) = input_value
+
+        def self.coerce_result(ruby_value, _context) = ruby_value
+      end
+
+      def initialize(mount, api)
+        @mount = mount
+        @api = api
+      end
+
+      def build
+        api = @api
+        query_type = Class.new(GraphQL::Schema::Object) { graphql_name("Query") }
+        mutation_type = Class.new(GraphQL::Schema::Object) { graphql_name("Mutation") }
+        @mount.package.storage.datasets.each do |dataset|
+          next if dataset.config.sqlite?
+
+          add_dataset_fields(query_type, mutation_type, dataset, api)
+        end
+        Class.new(GraphQL::Schema) do
+          query(query_type)
+          mutation(mutation_type)
+        end
+      end
+
+      private
+
+      def add_dataset_fields(query_type, mutation_type, dataset, api)
+        name = graphql_name_for(dataset.name)
+        type = item_type_for(dataset, name)
+        add_query_field(query_type, name, type, dataset, api)
+        add_mutation_fields(mutation_type, name, type, dataset, api)
+      end
+
+      # "<dataset>" returns the merged item list; with "id:" the single
+      # matching item (a one-element list, not-found in "errors").
+      def add_query_field(query_type, name, type, dataset, api)
+        query_type.class_eval do
+          field name, [type], null: false, camelize: false do
+            argument :id, String, required: false
+          end
+          define_method(name) { |id: nil| api.collection(dataset, id: id) }
+        end
+      end
+
+      # create<Dataset>/update<Dataset>/delete<Dataset> with the same
+      # semantics (and schema validation) as the REST verbs.
+      def add_mutation_fields(mutation_type, name, type, dataset, api)
+        capitalized = name.sub(/\A./, &:upcase)
+        mutation_type.class_eval do
+          field "create#{capitalized}", type, null: true, camelize: false do
+            argument :item, JsonScalar, required: true
+          end
+          define_method("create#{capitalized}") { |item:| api.create_item(dataset, item: item) }
+
+          field "update#{capitalized}", type, null: true, camelize: false do
+            argument :id, String, required: true
+            argument :item, JsonScalar, required: true
+          end
+          define_method("update#{capitalized}") do |id:, item:|
+            api.update_item(dataset, id: id, item: item)
+          end
+
+          field "delete#{capitalized}", GraphQL::Types::Boolean, null: false, camelize: false do
+            argument :id, String, required: true
+          end
+          define_method("delete#{capitalized}") { |id:| api.remove_item(dataset, id: id) }
+        end
+      end
+
+      # The item type inferred from the dataset's JSON schema (the
+      # schema describes the collection; its "items" describe an item),
+      # else the permissive JSON scalar.
+      def item_type_for(dataset, name)
+        properties = item_properties(dataset.json_schema)
+        return JsonScalar if properties.nil? || properties.empty?
+
+        fields = properties.to_h { |property, spec| [property, graphql_type_for(spec)] }
+        Class.new(GraphQL::Schema::Object) do
+          graphql_name("#{name.sub(/\A./, &:upcase)}Item")
+          fields.each do |property, type|
+            field property, type, null: true, camelize: false
+            define_method(property) { object[property] }
+          end
+        end
+      end
+
+      def item_properties(schema)
+        return nil unless schema.is_a?(Hash)
+
+        if schema["type"] == "array" && schema["items"].is_a?(Hash)
+          schema["items"]["properties"]
+        elsif schema["type"] == "object"
+          schema["properties"]
+        end
+      end
+
+      def graphql_type_for(spec)
+        case spec.is_a?(Hash) ? spec["type"] : nil
+        when "string" then String
+        when "integer" then Integer
+        when "number" then Float
+        when "boolean" then GraphQL::Types::Boolean
+        when "array" then [graphql_type_for(spec["items"] || {})]
+        else JsonScalar
+        end
+      end
+
+      # Dataset names become GraphQL identifiers ("my-data" -> "myData").
+      def graphql_name_for(name)
+        parts = name.split(/[^a-zA-Z0-9]+/).reject(&:empty?)
+        return "data" if parts.empty?
+
+        parts.first.downcase + parts.drop(1).map(&:capitalize).join
+      end
+    end
+  end
+end

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,73 +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,
-          signed: package.signed?,
-          encrypted: package.encrypted?
+        { 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[:signatureValid] = package.verify_signature if package.signed?
-        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