capsium 0.1.2 → 0.2.0

data/lib/capsium/reactor/introspection.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "time"
+
+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.
+    class Introspection
+      METADATA_PATH = "/api/v1/introspect/metadata"
+      ROUTES_PATH = "/api/v1/introspect/routes"
+      CONTENT_HASHES_PATH = "/api/v1/introspect/content-hashes"
+      CONTENT_VALIDITY_PATH = "/api/v1/introspect/content-validity"
+      PATHS = [METADATA_PATH, ROUTES_PATH, CONTENT_HASHES_PATH,
+               CONTENT_VALIDITY_PATH].freeze
+
+      attr_reader :package
+
+      def initialize(package)
+        @package = package
+      end
+
+      def endpoint?(path)
+        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)
+        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
+        end
+      end
+
+      def metadata_report
+        metadata = package.metadata
+        { packages: [{
+          name: metadata.name,
+          version: metadata.version,
+          author: metadata.author,
+          description: metadata.description
+        }] }
+      end
+
+      def routes_report
+        entries = package.routes.config.routes.map do |route|
+          { method: route.http_method || "GET", path: route.path }
+        end
+        { routes: [{ package: package.name, routes: entries }] }
+      end
+
+      def content_hashes_report
+        { contentHashes: [{ package: package.name, hash: content_hash }] }
+      end
+
+      def content_validity_report
+        errors = package.verify_integrity
+        entry = {
+          package: package.name,
+          valid: errors.empty?,
+          lastChecked: Time.now.utc.iso8601
+        }
+        entry[:reason] = errors.map(&:message).join("; ") unless errors.empty?
+        { contentValidity: [entry] }
+      end
+
+      private
+
+      # 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
+        return Digest::SHA256.file(cap_file).hexdigest if cap_file
+
+        checksums = Package::Security.checksums_for(package.path)
+        Digest::SHA256.hexdigest(JSON.generate(checksums))
+      end
+    end
+  end
+end

data/lib/capsium/reactor.rb

@@ -1,52 +1,59 @@
 # frozen_string_literal: true
 
-require "webrick"
 require "json"
 require "listen"
-require "capsium/package"
+require "webrick"
 
 module Capsium
   class Reactor
+    autoload :Introspection, "capsium/reactor/introspection"
+
     DEFAULT_PORT = 8864
+    DEFAULT_CACHE_CONTROL = "public, max-age=31536000"
 
-    attr_accessor :package, :package_path, :routes, :port, :server,
-                  :server_thread
+    attr_reader :package, :package_path, :routes, :port, :cache_control,
+                :server, :server_thread, :introspection
 
-    def initialize(package:, port: DEFAULT_PORT, do_not_listen: false)
+    def initialize(package:, port: DEFAULT_PORT,
+                   cache_control: DEFAULT_CACHE_CONTROL, do_not_listen: false)
       @package = package.is_a?(String) ? Package.new(package) : package
       @package_path = @package.path
       @port = port
+      @cache_control = cache_control
       setup_server(do_not_listen)
-      @routes = @package.routes
+      load_state
       mount_routes
     end
 
     def serve
+      trap("INT") { shutdown_server }
       @server_thread = start_server
       start_listener
     end
 
     def handle_request(request, response)
+      return serve_introspection(request, response) if @introspection.endpoint?(request.path)
+
       route = @routes.resolve(request.path)
-      if route
-        target = route.target
-        content_path = target.fs_path(@package.manifest)
-        if File.exist?(content_path)
-          response.status = 200
-          response["Content-Type"] = target.mime(@package.manifest)
-          response.body = File.read(content_path)
-        else
-          response.status = 404
-          response["Content-Type"] = "text/plain"
-          response.body = "Not Found"
-        end
-      else
-        response.status = 404
-        response["Content-Type"] = "text/plain"
-        response.body = "Not Found"
+      route ? serve_route(route, response) : respond_not_found(response)
+    end
+
+    def mount_routes
+      paths = @routes.config.routes.map(&:path) + Introspection::PATHS
+      paths.each do |path|
+        @server.mount_proc(path.to_s) { |req, res| handle_request(req, res) }
       end
     end
 
+    def restart_server
+      @server.shutdown
+      @server_thread&.join
+      load_package
+      setup_server(false)
+      mount_routes
+      @server_thread = start_server
+    end
+
     private
 
     def setup_server(do_not_listen)
@@ -55,18 +62,8 @@ module Capsium
       @server = WEBrick::HTTPServer.new(server_options)
     end
 
-    def mount_routes
-      @routes.config.routes.each do |route|
-        path = route.path
-        @server.mount_proc(path.to_s) do |req, res|
-          handle_request(req, res)
-        end
-      end
-    end
-
     def start_server
       Thread.new do
-        trap("INT") { shutdown_server }
         puts "Starting server on http://localhost:#{@port}"
         @server.start
       end
@@ -78,15 +75,6 @@ module Capsium
       exit
     end
 
-    def restart_server
-      @server.shutdown
-      @server_thread&.join
-      load_package
-      setup_server(false)
-      mount_routes
-      @server_thread = start_server
-    end
-
     def start_listener
       listener = Listen.to(@package_path) do |_modified, _added, _removed|
         puts "Changes detected, reloading..."
@@ -100,7 +88,67 @@ module Capsium
 
     def load_package
       @package = Package.new(@package_path)
+      load_state
+    end
+
+    def load_state
       @routes = @package.routes
+      @introspection = Introspection.new(@package)
+    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 serve_route(route, response)
+      case route.kind
+      when :dataset then serve_dataset(route.dataset, response)
+      when :resource then serve_file(route, response)
+      else respond_not_implemented(response)
+      end
+    end
+
+    def serve_file(route, response)
+      content_path = route.fs_path(@package.path)
+      if content_path && File.exist?(content_path)
+        response.status = 200
+        response["Content-Type"] = route.mime(@package.manifest) || "application/octet-stream"
+        headers_for(route).each { |name, value| response[name] = value }
+        response.body = File.read(content_path)
+      else
+        respond_not_found(response)
+      end
+    end
+
+    def headers_for(route)
+      route.headers || (@cache_control ? { "Cache-Control" => @cache_control } : {})
+    end
+
+    def serve_dataset(dataset_name, response)
+      dataset = @package.storage.dataset(dataset_name)
+      if dataset
+        response.status = 200
+        response["Content-Type"] = "application/json"
+        response.body = JSON.generate(dataset.data)
+      else
+        respond_not_found(response)
+      end
+    end
+
+    def respond_not_found(response) = respond_text(response, 404, "Not Found")
+
+    def respond_not_implemented(response) = respond_text(response, 501, "Not Implemented")
+
+    def respond_method_not_allowed(response) = respond_text(response, 405, "Method Not Allowed")
+
+    def respond_text(response, status, body)
+      response.status = status
+      response["Content-Type"] = "text/plain"
+      response.body = body
     end
   end
 end

data/lib/capsium/version.rb

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

data/lib/capsium.rb

@@ -1,15 +1,13 @@
 # frozen_string_literal: true
 
-require_relative "capsium/version"
-require "shale"
-require "shale/adapter/nokogiri"
-Shale.xml_adapter = Shale::Adapter::Nokogiri
-
 module Capsium
   class Error < StandardError; end
 
-  # Your code goes here...
+  autoload :VERSION, "capsium/version"
+  autoload :Cli, "capsium/cli"
+  autoload :Converters, "capsium/converters"
+  autoload :Package, "capsium/package"
+  autoload :Packager, "capsium/packager"
+  autoload :Reactor, "capsium/reactor"
+  autoload :ThorExt, "capsium/thor_ext"
 end
-
-require_relative "capsium/package"
-require_relative "capsium/packager"

data/sig/capsium/package/dataset.rbs

@@ -0,0 +1,28 @@
+module Capsium
+  class Package
+    # A loaded dataset. "source"/"schemaFile"/"databaseFile" are
+    # package-relative paths resolved against the package directory.
+    class Dataset
+      attr_reader name: String
+      attr_reader config: DatasetConfig
+      attr_reader data: untyped
+      attr_reader package_path: String
+
+      def initialize: (name: String name, config: DatasetConfig config,
+                       package_path: String package_path) -> void
+
+      def source_path: () -> String
+
+      def schema_path: () -> String?
+
+      def load_data: () -> untyped
+
+      def validate: () -> bool
+
+      # File-existence and schema validations; empty when valid.
+      def validation_errors: () -> Array[String]
+
+      def to_json: (*untyped args) -> String
+    end
+  end
+end

data/sig/capsium/package/manifest.rbs

@@ -0,0 +1,34 @@
+module Capsium
+  class Package
+    # Loads, generates and writes manifest.json (ARCHITECTURE.md
+    # section 3).
+    class Manifest
+      attr_reader path: String
+      attr_reader content_path: String
+      attr_reader config: ManifestConfig
+
+      def initialize: (String path) -> void
+
+      # Auto-generation: scan content/ recursively, detect MIME types,
+      # default visibility "exported", deterministic (sorted) output.
+      def generate_manifest: () -> Hash[String, Resource]
+
+      def resources: () -> Hash[String, Resource]
+
+      def lookup: (String path) -> Resource?
+
+      def type_for: (String path) -> String?
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+
+      def save_to_file: (?String output_path) -> void
+
+      def path_to_content_file: (String path) -> Pathname
+
+      def content_file_exists?: (String path) -> bool
+
+      def relative_path: (String path) -> String
+    end
+  end
+end

data/sig/capsium/package/manifest_config.rbs

@@ -0,0 +1,38 @@
+module Capsium
+  class Package
+    # A single manifest resource entry (ARCHITECTURE.md section 3).
+    class Resource
+      VISIBILITIES: Array[String]
+
+      attr_accessor type: String?
+      attr_accessor visibility: String
+      attr_accessor version: String?
+
+      def initialize: (?type: String? type, ?visibility: String? visibility,
+                       ?version: String? version) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # Canonical manifest.json model: an object keyed by package-relative
+    # resource path. The legacy array form is normalized on read;
+    # writers emit only the object form.
+    class ManifestConfig
+      attr_accessor resources: Hash[String, Resource]
+
+      def initialize: (?resources: Hash[String, Resource] resources) -> void
+
+      def self.from_json: (String json) -> instance
+
+      def resources_from_json: (ManifestConfig model, untyped value) -> void
+
+      def resources_to_json: (ManifestConfig model, Hash[String, untyped] doc) -> void
+
+      def sort!: () -> ManifestConfig
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/metadata.rbs

@@ -0,0 +1,26 @@
+module Capsium
+  class Package
+    # Loads and writes metadata.json; field access is delegated to the
+    # wrapped MetadataData config (ARCHITECTURE.md section 2).
+    class Metadata
+      attr_reader path: String
+      attr_reader config: MetadataData
+
+      def initialize: (String path) -> void
+
+      def save_to_file: (?String output_path) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+      def name: () -> String?
+      def version: () -> String?
+      def description: () -> String?
+      def guid: () -> String?
+      def uuid: () -> String?
+      def author: () -> String?
+      def license: () -> String?
+      def repository: () -> Repository?
+      def dependencies: () -> Hash[String, String]
+    end
+  end
+end

data/sig/capsium/package/metadata_config.rbs

@@ -0,0 +1,49 @@
+module Capsium
+  class Package
+    # The repository object of metadata.json.
+    class Repository
+      attr_accessor type: String?
+      attr_accessor url: String?
+
+      def initialize: (?type: String? type, ?url: String? url) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # Canonical metadata.json model (ARCHITECTURE.md section 2). The
+    # legacy array form of "dependencies" is normalized on read; writers
+    # emit only the object form.
+    class MetadataData
+      KEBAB_CASE_PATTERN: Regexp
+      SEMVER_PATTERN: Regexp
+      UUID_PATTERN: Regexp
+
+      attr_accessor name: String?
+      attr_accessor version: String?
+      attr_accessor description: String?
+      attr_accessor guid: String?
+      attr_accessor uuid: String?
+      attr_accessor author: String?
+      attr_accessor license: String?
+      attr_accessor repository: Repository?
+      attr_accessor dependencies: Hash[String, String]
+      attr_accessor read_only: bool?
+
+      def initialize: (?name: String? name, ?version: String? version,
+                       ?description: String? description, ?guid: String? guid,
+                       ?uuid: String? uuid, ?author: String? author,
+                       ?license: String? license, ?repository: Repository? repository,
+                       ?dependencies: Hash[String, String] dependencies,
+                       ?read_only: bool? read_only) -> void
+
+      def self.from_json: (String json) -> instance
+
+      # Field-level format validations; empty when valid.
+      def format_errors: () -> Array[String]
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/routes.rbs

@@ -0,0 +1,37 @@
+module Capsium
+  class Package
+    # Loads, generates and writes routes.json (ARCHITECTURE.md
+    # section 4).
+    class Routes
+      INDEX_ROUTE: String
+      INDEX_RESOURCE: String
+      DATASET_ROUTE_PREFIX: String
+
+      attr_reader path: String
+      attr_reader config: RoutesConfig
+      attr_reader manifest: Manifest
+      attr_reader storage: Storage
+
+      def initialize: (String path, Manifest manifest, Storage storage) -> void
+
+      def resolve: (String url_path) -> Route?
+
+      def add_route: (String route, String target) -> Route
+
+      def update_route: (String route, String updated_route, String updated_target) -> Route
+
+      def remove_route: (String route) -> Array[Route]
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+
+      def save_to_file: (?String output_path) -> void
+
+      # Auto-generation (ARCHITECTURE.md section 4): every manifest
+      # resource gets a route at its path relative to content/; HTML
+      # files get two routes; the index HTML additionally gets "/";
+      # every dataset gets /api/v1/data/<id>. Deterministic output.
+      def generate_routes: () -> RoutesConfig
+    end
+  end
+end

data/sig/capsium/package/routes_config.rbs

@@ -0,0 +1,74 @@
+module Capsium
+  class Package
+    # A single route entry (ARCHITECTURE.md section 4). Kinds are
+    # discriminated by key, MECE: static file, dataset route, or dynamic
+    # handler (accepted-and-ignored; reactors respond 501).
+    class Route
+      DATASET_PATH_PREFIX: String
+
+      attr_accessor path: String?
+      attr_accessor resource: String?
+      attr_accessor headers: Hash[String, String]?
+      attr_accessor headers_file: String?
+      attr_accessor visibility: String
+      attr_accessor dataset: String?
+      attr_accessor access_control: Hash[String, untyped]?
+      attr_accessor http_method: String?
+      attr_accessor handler: String?
+
+      def initialize: (?path: String? path, ?resource: String? resource,
+                       ?headers: Hash[String, String]? headers,
+                       ?headers_file: String? headers_file,
+                       ?visibility: String? visibility, ?dataset: String? dataset,
+                       ?access_control: Hash[String, untyped]? access_control,
+                       ?http_method: String? http_method,
+                       ?handler: String? handler) -> void
+
+      def self.from_json: (String json) -> instance
+
+      def kind: () -> (:resource | :dataset | :handler)
+
+      def dataset_route?: () -> bool
+
+      def handler_route?: () -> bool
+
+      def fs_path: (String package_path) -> String?
+
+      def mime: (Manifest manifest) -> String?
+
+      def validate_target: (String package_path, Storage storage) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # Canonical routes.json model: optional top-level "index" plus a
+    # "routes" array. The legacy object/target form is normalized on
+    # read; writers emit only the canonical form.
+    class RoutesConfig
+      attr_accessor index: String?
+      attr_accessor routes: Array[Route]
+
+      def initialize: (?index: String? index, ?routes: Array[Route] routes) -> void
+
+      def self.from_json: (String json) -> instance
+
+      def routes_from_json: (RoutesConfig model, untyped value) -> void
+
+      def routes_to_json: (RoutesConfig model, Hash[String, untyped] doc) -> void
+
+      def resolve: (String path) -> Route?
+
+      def add: (String path, String target) -> Route
+
+      def update: (String path, String updated_path, String updated_target) -> Route
+
+      def remove: (String path) -> Array[Route]
+
+      def sort!: () -> RoutesConfig
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/security.rbs

@@ -0,0 +1,65 @@
+module Capsium
+  class Package
+    # Loads, generates and verifies security.json (ARCHITECTURE.md
+    # section 6). Checksums cover every file in the package except
+    # security.json itself.
+    class Security
+      class IntegrityError < Capsium::Error
+      end
+
+      # A file whose SHA-256 does not match the recorded checksum.
+      class ChecksumMismatch
+        attr_reader path: String
+        attr_reader expected: String
+        attr_reader actual: String
+
+        def initialize: (path: String path, expected: String expected, actual: String actual) -> void
+
+        def message: () -> String
+      end
+
+      # A checksum listed for a file that is missing on disk.
+      class MissingFile
+        attr_reader path: String
+        attr_reader expected: String
+
+        def initialize: (path: String path, expected: String expected) -> void
+
+        def message: () -> String
+      end
+
+      # A file on disk not covered by any checksum.
+      class UncheckedFile
+        attr_reader path: String
+
+        def initialize: (path: String path) -> void
+
+        def message: () -> String
+      end
+
+      attr_reader path: String
+      attr_reader config: SecurityConfig?
+
+      def initialize: (String path, ?SecurityConfig? config) -> void
+
+      def self.generate: (String package_path) -> Security
+
+      def self.checksums_for: (String package_path) -> Hash[String, String]
+
+      def self.package_files: (String package_path) -> Array[String]
+
+      def present?: () -> bool
+
+      def checksums: () -> Hash[String, String]
+
+      def verify: (String package_path) -> Array[ChecksumMismatch | MissingFile | UncheckedFile]
+
+      def verify!: (String package_path) -> void
+
+      def save_to_file: (?String output_path) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end