capsium 0.3.0 → 0.6.0

data/lib/capsium/reactor/overlay.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+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. The immutable package on disk never changes;
+    # content writes land under content/, deletions are tombstones in
+    # .capsium-tombstones, and dataset mutations are a per-dataset JSON
+    # operation log under data/. Everything is visible on the next
+    # request (hot-swap) and reloads from disk when the reactor starts
+    # over the same workdir.
+    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, e.g. a duplicate item
+      # id on append or a body id mismatch on replace (409).
+      class ConflictError < Error; end
+
+      # The dataset cannot take item writes (not a JSON collection) or
+      # the addressed path is unsafe (422/400).
+      class UnsupportedDatasetError < Error; end
+
+      # The candidate document violates the dataset's JSON schema (422);
+      # carries the schema error messages.
+      class SchemaViolationError < Error
+        attr_reader :messages
+
+        def initialize(messages)
+          @messages = messages
+          super(messages.join("; "))
+        end
+      end
+
+      TOMBSTONE_FILE = Package::MergedView::TOMBSTONE_FILE
+      SAFE_NAME_PATTERN = /\A[\w.-]+\z/
+
+      attr_reader :root, :tombstones
+
+      def initialize(root:)
+        @root = root
+        @tombstones = load_tombstones
+        @logs = {}
+      end
+
+      def content_root = File.join(@root, "content")
+
+      def data_root = File.join(@root, "data")
+
+      # The overlay as the topmost MergedView layer. The tombstones set
+      # is live: deletions are visible on the next resolve.
+      def layer
+        Package::MergedView::Layer.new(root: content_root,
+                                       visibility: "private",
+                                       tombstones: @tombstones)
+      end
+
+      # Writes a content file (create/overwrite), clearing any tombstone
+      # for the path so it is served again.
+      def write_content(content_relative, body)
+        path = safe_content_path(content_relative)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, body)
+        @tombstones.delete(content_relative)
+        persist_tombstones
+      end
+
+      # Tombstones a content path: it resolves 404 even when a lower
+      # layer holds the file (ARCHITECTURE.md section 5a).
+      def delete_content(content_relative)
+        FileUtils.rm_f(safe_content_path(content_relative))
+        @tombstones.add(content_relative)
+        persist_tombstones
+      end
+
+      # The dataset as served: the base data untouched when no mutations
+      # were recorded, the merged collection otherwise.
+      def dataset_data(dataset)
+        return dataset.data if mutation_log(dataset.name).empty?
+
+        items(dataset)
+      end
+
+      # The merged item collection: base data plus the replayed
+      # mutation log.
+      def items(dataset)
+        mutation_log(dataset.name).inject(base_items(dataset)) do |items, record|
+          apply_op(items, record)
+        end
+      end
+
+      def item(dataset, id)
+        current = items(dataset)
+        found = find_index(current, id)
+        raise ItemNotFoundError, "no item #{id} in dataset #{dataset.name}" unless found
+
+        current[found]
+      end
+
+      # Appends an item and returns its assigned id: the "id" field
+      # convention, else the 1-based index as a string.
+      def append_item(dataset, item)
+        current = items(dataset)
+        explicit = item_id(item)
+        if explicit && find_index(current, explicit)
+          raise ConflictError, "item id #{explicit} already exists in #{dataset.name}"
+        end
+
+        validate_candidate!(dataset, current + [item])
+        record_op(dataset.name, "op" => "append", "item" => item)
+        explicit || (current.size + 1).to_s
+      end
+
+      def replace_item(dataset, id, item)
+        current = items(dataset)
+        index = find_index(current, id)
+        raise ItemNotFoundError, "no item #{id} in dataset #{dataset.name}" unless index
+
+        explicit = item_id(item)
+        if explicit && explicit != id
+          raise ConflictError, "body id #{explicit} does not match #{id}"
+        end
+
+        validate_candidate!(dataset, replaced(current, index, item))
+        record_op(dataset.name, "op" => "replace", "id" => id, "item" => item)
+      end
+
+      def delete_item(dataset, id)
+        unless find_index(items(dataset), id)
+          raise ItemNotFoundError, "no item #{id} in dataset #{dataset.name}"
+        end
+
+        record_op(dataset.name, "op" => "delete", "id" => id)
+        nil
+      end
+
+      # The item id convention: an "id" field, else nil (positional).
+      def item_id(item)
+        item["id"].to_s if item.is_a?(Hash) && item.key?("id")
+      end
+
+      # Whether the dataset has recorded mutations.
+      def mutations?(name) = !mutation_log(name).empty?
+
+      private
+
+      def base_items(dataset)
+        base = dataset.data || []
+        return deep_dup(base) if base.is_a?(Array)
+
+        raise UnsupportedDatasetError,
+              "dataset #{dataset.name} is not a JSON collection"
+      end
+
+      def validate_candidate!(dataset, candidate)
+        errors = dataset.schema_errors_for(candidate)
+        raise SchemaViolationError, errors unless errors.empty?
+      end
+
+      def apply_op(items, record)
+        return items + [record["item"]] if record["op"] == "append"
+
+        index = find_index(items, record["id"])
+        return items unless index # base changed underneath: skip the op
+
+        case record["op"]
+        when "replace" then replaced(items, index, record["item"])
+        when "delete" then items[0...index] + items[(index + 1)..]
+        else raise Error, "unknown overlay op: #{record['op']}"
+        end
+      end
+
+      def replaced(items, index, item)
+        items[0...index] + [item] + items[(index + 1)..]
+      end
+
+      # Positional ids are the 1-based index as a string and only match
+      # items without an explicit "id" field.
+      def find_index(items, id)
+        by_field = items.index { |item| item_id(item) == id }
+        return by_field if by_field
+        return nil unless id.to_s.match?(/\A[1-9]\d*\z/)
+
+        index = id.to_i - 1
+        index < items.size && item_id(items[index]).nil? ? index : nil
+      end
+
+      def mutation_log(name)
+        @logs[name] ||= load_ops(name)
+      end
+
+      def record_op(name, record)
+        mutation_log(name) << record
+        FileUtils.mkdir_p(data_root)
+        File.write(ops_path(name), JSON.generate(mutation_log(name)))
+      end
+
+      def load_ops(name)
+        return [] unless name.match?(SAFE_NAME_PATTERN)
+
+        path = ops_path(name)
+        return [] unless File.file?(path)
+
+        JSON.parse(File.read(path))
+      end
+
+      def ops_path(name)
+        unless name.match?(SAFE_NAME_PATTERN)
+          raise Error, "unsafe dataset name for the overlay: #{name}"
+        end
+
+        File.join(data_root, "#{name}.json")
+      end
+
+      def safe_content_path(content_relative)
+        segments = content_relative.split("/")
+        if segments.empty? || segments.any? { |segment| segment.empty? || segment == ".." }
+          raise Error, "unsafe content path: #{content_relative}"
+        end
+
+        File.join(content_root, content_relative)
+      end
+
+      def deep_dup(data) = JSON.parse(JSON.generate(data))
+
+      def load_tombstones
+        path = File.join(content_root, TOMBSTONE_FILE)
+        return Set.new unless File.file?(path)
+
+        Set.new(JSON.parse(File.read(path)))
+      end
+
+      def persist_tombstones
+        FileUtils.mkdir_p(content_root)
+        File.write(File.join(content_root, TOMBSTONE_FILE),
+                   JSON.generate(@tombstones.to_a))
+      end
+    end
+  end
+end

data/lib/capsium/reactor/package_saver.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "tmpdir"
+require "yaml"
+
+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:
+    # overlay content files replace, tombstones delete, dataset mutation
+    # logs replay into the dataset files (JSON/YAML per the source
+    # extension). Manifest, routes and security.json are regenerated,
+    # so the saved package passes `capsium package validate`.
+    class PackageSaver
+      def initialize(mount)
+        @mount = mount
+        @package = mount.package
+        @overlay = mount.overlay
+      end
+
+      # Returns {path, sha256, name, version} of the saved .cap.
+      def save(workdir)
+        staging_parent = File.join(workdir, "saved")
+        FileUtils.mkdir_p(staging_parent)
+        stage = Dir.mktmpdir("fold-", staging_parent)
+        begin
+          fold_into(stage)
+          output = Packager.new.pack(Package.new(stage), { force: true })
+          { "path" => output,
+            "sha256" => Digest::SHA256.file(output).hexdigest,
+            "name" => @package.name,
+            "version" => bumped_version }
+        ensure
+          FileUtils.remove_entry(stage)
+        end
+      end
+
+      private
+
+      def fold_into(stage)
+        FileUtils.cp_r("#{@package.path}/.", stage)
+        apply_content_overlay(stage)
+        apply_dataset_overlays(stage)
+        write_bumped_metadata(stage)
+        # Regenerated at pack time from the folded tree.
+        FileUtils.rm_f(File.join(stage, Package::MANIFEST_FILE))
+        FileUtils.rm_f(File.join(stage, Package::ROUTES_FILE))
+        FileUtils.rm_f(File.join(stage, Package::SECURITY_FILE))
+      end
+
+      def apply_content_overlay(stage)
+        @overlay.tombstones.each do |relative|
+          FileUtils.rm_f(File.join(stage, Package::CONTENT_DIR, relative))
+        end
+        Dir.glob(File.join(@overlay.content_root, "**", "*"), File::FNM_DOTMATCH).each do |file|
+          next unless File.file?(file)
+
+          relative = file.delete_prefix("#{@overlay.content_root}/")
+          next if relative == Overlay::TOMBSTONE_FILE
+
+          target = File.join(stage, Package::CONTENT_DIR, relative)
+          FileUtils.mkdir_p(File.dirname(target))
+          FileUtils.cp(file, target)
+        end
+      end
+
+      def apply_dataset_overlays(stage)
+        @package.storage.datasets.each do |dataset|
+          next unless @overlay.mutations?(dataset.name)
+
+          write_merged_dataset(stage, dataset, @overlay.items(dataset))
+        end
+      end
+
+      def write_merged_dataset(stage, dataset, merged)
+        target = File.join(stage, dataset.config.backing_file)
+        case File.extname(target).downcase
+        when ".yaml", ".yml" then File.write(target, YAML.dump(merged))
+        else File.write(target, JSON.pretty_generate(merged))
+        end
+      end
+
+      def bumped_version
+        version = Package::Version.parse(@package.metadata.version)
+        "#{version.major}.#{version.minor}.#{version.patch + 1}"
+      end
+
+      def write_bumped_metadata(stage)
+        path = File.join(stage, Package::METADATA_FILE)
+        metadata = JSON.parse(File.read(path))
+        metadata["version"] = bumped_version
+        File.write(path, JSON.pretty_generate(metadata))
+      end
+    end
+  end
+end

data/lib/capsium/reactor/responses.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "json"
+
+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(response) = respond_text(response, 404, "Not Found")
+
+      def respond_forbidden(response) = respond_text(response, 403, "Forbidden")
+
+      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
+
+      def respond_json(response, status, body)
+        response.status = status
+        response["Content-Type"] = "application/json"
+        response.body = JSON.generate(body)
+      end
+
+      # A JSON error body ("error" plus optional "messages" details) —
+      # the shape the data/write APIs answer client errors with.
+      def respond_error(response, status, message, messages: nil)
+        body = { error: message }
+        body[:messages] = messages if messages
+        respond_json(response, status, body)
+      end
+    end
+  end
+end

data/lib/capsium/reactor/serving.rb

@@ -9,24 +9,103 @@ module Capsium
     # datasets, handler-route 501s), mixed into Reactor. Includes route
     # inheritance processing per 05x-routing.
     module Serving
+      include Responses
+
       private
 
-      def serve_route(route, response)
+      # One request metric and one log line per served request.
+      def record_request(request, response)
+        status = response.status
+        return if status.nil?
+
+        @metrics.record(status)
+        @log_buffer.add("#{request.request_method} #{request.path} -> #{status}")
+      end
+
+      # The mount answering a request path: longest matching prefix wins.
+      def resolve_mount(path)
+        mounts_by_length.find { |mount| mount.matches?(path) }
+      end
+
+      def mounts_by_length
+        @mounts_by_length ||= @mounts.sort_by { |mount| -mount.path.length }
+      end
+
+      # The root ("/") mount, or the first mount when nothing is mounted
+      # at the root: its package drives the single-package readers
+      # (package, routes, merged_view), authentication and the
+      # reactor-level introspection.
+      def root_mount
+        @mounts.find { |mount| mount.path == Mount::ROOT_PATH } || @mounts.first
+      end
+
+      # Serves a request that matched a mount: dataset CRUD and content
+      # writes go to the mount's APIs, everything else resolves against
+      # the mount's routes. Route-level access control is enforced for
+      # the addressed route in every case.
+      def serve_mounted_request(mount, identity, request, response)
+        inner = mount.inner_path(request.path)
+        return serve_data_api(mount, identity, inner, request, response) if DataApi.path?(inner)
+        if GraphqlApi.path?(inner) && mount.graphql?
+          return mount.graphql_api.handle(request, response)
+        end
+        if ContentApi.write_method?(request.request_method)
+          return serve_content_api(mount, identity, inner, request, response)
+        end
+
+        route = mount.routes.resolve(inner)
+        return respond_not_found(response) unless route
+        return unless authorized?(identity, route, response)
+
+        serve_route(mount, route, response)
+      end
+
+      def serve_data_api(mount, identity, inner, request, response)
+        route = mount.data_api.route_for(inner)
+        return respond_not_found(response) unless route
+        return unless authorized?(identity, route, response)
+
+        mount.data_api.handle(inner, request, response)
+      end
+
+      def serve_content_api(mount, identity, inner, request, response)
+        route = mount.routes.resolve(inner)
+        return unless !route || authorized?(identity, route, response)
+
+        mount.content_api.handle(inner, request, response)
+      end
+
+      # Route-level access control (05x-authentication): writes the
+      # challenge/forbidden response and returns false when the
+      # identity may not proceed.
+      def authorized?(identity, route, response)
+        case @authenticator.authorize(identity, route.access_control)
+        when :unauthenticated
+          @authenticator.challenge(response)
+          false
+        when :forbidden
+          respond_forbidden(response)
+          false
+        else true
+        end
+      end
+
+      def serve_route(mount, route, response)
         case route.kind
-        when :dataset then serve_dataset(route.dataset, response)
-        when :resource then serve_file(route, response)
+        when :dataset then serve_dataset(mount, route.dataset, response)
+        when :resource then serve_file(mount, route, response)
         else respond_not_implemented(response)
         end
       end
 
-      def serve_file(route, response)
-        content_path = @merged_view.resolve(route.resource)
+      def serve_file(mount, route, response)
+        content_path = mount.merged_view.resolve(route.resource)
         return respond_not_found(response) unless content_path
 
         body, headers = inherited_processing(route, File.read(content_path),
                                              headers_for(route))
         response.status = 200
-        response["Content-Type"] = content_type_for(route, content_path)
+        response["Content-Type"] = content_type_for(mount, route, content_path)
         headers.each { |name, value| response[name] = value }
         response.body = body
       end
@@ -50,8 +129,8 @@ module Capsium
       # The route's declared MIME type, detected from the resolved file
       # for resources the manifest does not list (dependency content
       # reached through inheritance, layer-only files).
-      def content_type_for(route, content_path)
-        route.mime(@package.manifest) ||
+      def content_type_for(mount, route, content_path)
+        route.mime(mount.package.manifest) ||
           Marcel::MimeType.for(Pathname.new(content_path),
                                name: File.basename(content_path))
       end
@@ -60,12 +139,12 @@ module Capsium
         route.headers || (@cache_control ? { "Cache-Control" => @cache_control } : {})
       end
 
-      def serve_dataset(dataset_name, response)
-        dataset = @package.storage.dataset(dataset_name)
+      def serve_dataset(mount, dataset_name, response)
+        dataset = mount.package.storage.dataset(dataset_name)
         if dataset
           response.status = 200
           response["Content-Type"] = "application/json"
-          response.body = JSON.generate(dataset.data)
+          response.body = JSON.generate(mount.dataset_data(dataset))
         else
           respond_not_found(response)
         end