capsium 0.1.2 → 0.3.0

data/lib/capsium/package/merged_view.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Capsium
+  class Package
+    # The merged (overlay) view of a package's content, per ARCHITECTURE.md
+    # section 5a. Shared by Package (validation) and Reactor (serving).
+    #
+    # The content/ tree is always the implicit bottom layer; layers from
+    # storage.layers stack on top of it, bottom -> top in declaration
+    # order. Resolution scans from the TOP down and the first hit wins.
+    # Deletions are recorded as tombstones: a `.capsium-tombstones` JSON
+    # file in a writable layer listing content/-relative paths; a
+    # tombstoned path resolves to nil even when a lower layer (including a
+    # dependency's content) holds the file, while a file reappearing in a
+    # layer ABOVE the tombstone is served again.
+    #
+    # Composite packages (section 4a): `dependency_views` are
+    # [dependency GUID, MergedView] pairs acting as read-only layers below
+    # ALL own layers. A resource reference that is a URI of the form
+    # "<dependency-guid>/<path>" resolves explicitly against that
+    # dependency's view; plain content paths fall through to the
+    # dependency layers in declaration order after all own layers miss.
+    #
+    # With `exported_only: true` (the view a dependent package gets):
+    # layers whose visibility is "private" are hidden entirely, and a path
+    # resolves only when the manifest lists the resource as "exported".
+    class MergedView
+      # A single read layer: an absolute root directory mirroring the
+      # content/ tree, plus its parsed tombstone set.
+      Layer = Data.define(:root, :visibility, :tombstones) do
+        def file?(content_relative_path)
+          File.file?(absolute(content_relative_path))
+        end
+
+        def absolute(content_relative_path)
+          File.join(root, content_relative_path)
+        end
+      end
+
+      TOMBSTONE_FILE = ".capsium-tombstones"
+      CONTENT_PREFIX = "#{Package::CONTENT_DIR}/".freeze
+
+      attr_reader :package_path, :layers, :dependency_views
+
+      def initialize(package_path, storage:, manifest:, dependency_views: [],
+                     exported_only: false)
+        @package_path = package_path
+        @storage = storage
+        @manifest = manifest
+        @exported_only = exported_only
+        @dependency_views = dependency_views
+        @layers = build_layers
+      end
+
+      # The absolute filesystem path serving a resource reference: a
+      # package-relative content path ("content/app.js"), or a dependency
+      # reference ("<dependency-guid>/content/app.js"). nil when no layer
+      # provides the path or it is tombstoned. Non-content paths never
+      # resolve through the view.
+      def resolve(reference)
+        return unless reference.is_a?(String)
+
+        if reference.include?("://")
+          pair = dependency_pair_for(reference)
+          return unless pair
+
+          return pair[1].resolve(reference.delete_prefix("#{pair[0]}/"))
+        end
+
+        content_relative = content_relative(reference)
+        return unless content_relative
+        return if content_relative == TOMBSTONE_FILE
+
+        result = resolve_own(content_relative)
+        return if result == :tombstoned
+        return result if result
+
+        resolve_dependencies(reference)
+      end
+
+      # The [GUID, view] pair whose GUID prefixes the reference (longest
+      # GUID first, so nested GUIDs address the innermost dependency).
+      def dependency_pair_for(reference)
+        @dependency_views
+          .sort_by { |guid, _view| -guid.length }
+          .find { |guid, _view| reference.start_with?("#{guid}/") }
+      end
+
+      private
+
+      # The serving path from the package's own layers, :tombstoned when
+      # a tombstone at or above the first hit suppresses it (tombstones
+      # also suppress the lower dependency layers), or nil when no own
+      # layer provides the path.
+      def resolve_own(content_relative)
+        tombstoned = false
+        @layers.reverse_each do |layer|
+          tombstoned ||= layer.tombstones.include?(content_relative)
+          next unless layer.file?(content_relative)
+          return :tombstoned if tombstoned
+
+          return layer.absolute(content_relative)
+        end
+        tombstoned ? :tombstoned : nil
+      end
+
+      def resolve_dependencies(relative_path)
+        @dependency_views.each do |pair|
+          found = pair.last.resolve(relative_path)
+          return found if found
+        end
+        nil
+      end
+
+      # Own layers, bottom -> top: the implicit content/ layer plus the
+      # configured storage.layers. Private layers are dropped when the view
+      # is exported-only (hidden from dependents, section 5a).
+      def build_layers
+        configs = [nil] + @storage.config.layers
+        configs = configs.reject { |config| config&.private? } if @exported_only
+        configs.filter_map { |config| build_layer(config) }
+      end
+
+      def build_layer(config)
+        root = config ? File.join(@package_path, config.path) : content_root
+        Layer.new(root: root,
+                  visibility: config&.visibility || "exported",
+                  tombstones: load_tombstones(root))
+      end
+
+      def content_root
+        File.join(@package_path, Package::CONTENT_DIR)
+      end
+
+      def load_tombstones(root)
+        tombstone_path = File.join(root, TOMBSTONE_FILE)
+        return Set.new unless File.file?(tombstone_path)
+
+        entries = JSON.parse(File.read(tombstone_path))
+        unless entries.is_a?(Array) && entries.all?(String)
+          raise Error, "Malformed #{TOMBSTONE_FILE} (expected a JSON array " \
+                       "of paths): #{tombstone_path}"
+        end
+
+        Set.new(entries)
+      rescue JSON::ParserError => e
+        raise Error, "Malformed #{TOMBSTONE_FILE}: #{tombstone_path}: #{e.message}"
+      end
+
+      def content_relative(relative_path)
+        return unless relative_path.is_a?(String)
+        return unless relative_path.start_with?(CONTENT_PREFIX)
+
+        content_relative = relative_path.delete_prefix(CONTENT_PREFIX)
+        return if @exported_only && !exported?(relative_path)
+
+        content_relative
+      end
+
+      def exported?(relative_path)
+        resource = @manifest.lookup(relative_path)
+        resource&.visibility == "exported"
+      end
+    end
+  end
+end

data/lib/capsium/package/metadata.rb

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 
-# lib/capsium/package/metadata.rb
-require "shale"
 require "forwardable"
-require_relative "metadata_config"
 
 module Capsium
   class Package
@@ -11,11 +8,10 @@ module Capsium
       attr_reader :path, :config
 
       extend Forwardable
-      def_delegator :@config, :to_json
-      def_delegator :@config, :name
-      def_delegator :@config, :version
-      def_delegator :@config, :description # Delegate description method
-      def_delegator :@config, :dependencies
+
+      def_delegators :@config, :to_json, :to_hash, :name, :version,
+                     :description, :guid, :uuid, :author, :license,
+                     :repository, :dependencies
 
       def initialize(path)
         @path = path

data/lib/capsium/package/metadata_config.rb

@@ -1,17 +1,105 @@
-require "shale"
+# frozen_string_literal: true
+
+require "json"
+require "lutaml/model"
+require "uri"
 
 module Capsium
   class Package
-    class Dependency < Shale::Mapper
-      attribute :name, Shale::Type::String
-      attribute :version, Shale::Type::String
+    class Repository < Lutaml::Model::Serializable
+      attribute :type, :string
+      attribute :url, :string
+
+      json do
+        map :type, to: :type
+        map :url, to: :url
+      end
     end
 
-    class MetadataData < Shale::Mapper
-      attribute :name, Shale::Type::String
-      attribute :version, Shale::Type::String
-      attribute :description, Shale::Type::String # Add description attribute
-      attribute :dependencies, Dependency, collection: true
+    # Canonical metadata.json model (ARCHITECTURE.md section 2).
+    #
+    # The legacy gem form of "dependencies" (an array of {name, version}
+    # objects) is accepted on read and normalized to the canonical object
+    # form; writers emit only the object form.
+    class MetadataData < Lutaml::Model::Serializable
+      KEBAB_CASE_PATTERN = /\A[a-z0-9]+(-[a-z0-9]+)*\z/
+      SEMVER_PATTERN = /\A\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?\z/
+      UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+
+      attribute :name, :string
+      attribute :version, :string
+      attribute :description, :string
+      attribute :guid, :string
+      attribute :uuid, :string
+      attribute :author, :string
+      attribute :license, :string
+      attribute :repository, Repository
+      attribute :dependencies, :hash, default: {}
+      attribute :read_only, :boolean
+
+      json do
+        map :name, to: :name
+        map :version, to: :version
+        map :description, to: :description
+        map :guid, to: :guid
+        map :uuid, to: :uuid
+        map :author, to: :author
+        map :license, to: :license
+        map :repository, to: :repository
+        map :dependencies, to: :dependencies
+        map "readOnly", to: :read_only
+      end
+
+      def self.from_json(json)
+        doc = JSON.parse(json)
+        doc["dependencies"] = normalize_dependencies(doc["dependencies"])
+        super(JSON.generate(doc))
+      end
+
+      def self.normalize_dependencies(dependencies)
+        return {} if dependencies.nil?
+        return dependencies unless dependencies.is_a?(Array)
+
+        dependencies.to_h { |dep| [dep["name"], dep["version"]] }
+      end
+      private_class_method :normalize_dependencies
+
+      # Field-level format validations (ARCHITECTURE.md section 2).
+      # Returns a list of human-readable problems; empty when valid.
+      def format_errors
+        presence_errors + format_field_errors
+      end
+
+      private
+
+      def presence_errors
+        problems = []
+        problems << "name is missing" if name.to_s.empty?
+        problems << "version is missing" if version.to_s.empty?
+        problems << "description is missing" if description.to_s.empty?
+        problems << "guid is missing" if guid.to_s.empty?
+        problems << "uuid is missing" if uuid.to_s.empty?
+        problems
+      end
+
+      def format_field_errors
+        problems = []
+        problems << "name must be kebab-case" if invalid?(name, KEBAB_CASE_PATTERN)
+        problems << "version must be semver" if invalid?(version, SEMVER_PATTERN)
+        problems << "guid must be a URI" if guid && !uri?(guid)
+        problems << "uuid is not a valid UUID" if invalid?(uuid, UUID_PATTERN)
+        problems
+      end
+
+      def invalid?(value, pattern)
+        !value.nil? && !value.match?(pattern)
+      end
+
+      def uri?(value)
+        URI.parse(value).is_a?(URI::Generic)
+      rescue URI::InvalidURIError
+        false
+      end
     end
   end
 end

data/lib/capsium/package/preparation.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+module Capsium
+  class Package
+    # Package-source preparation (ARCHITECTURE.md section 1), mixed into
+    # Package: directory/.cap/encrypted-cap detection, extraction and
+    # decryption into a readable package directory.
+    module Preparation
+      def prepare_package(path)
+        return decrypt_cap_file(path) if Cipher.encrypted?(path)
+        return path if File.directory?(path)
+        raise Error, "Invalid package path: #{path}" unless File.file?(path)
+        raise Error, "The package must have a .cap extension" unless File.extname(path) == ".cap"
+
+        decompress_cap_file(path)
+      end
+
+      def decompress_cap_file(file_path)
+        package_path = File.join(Dir.mktmpdir, package_stem(file_path))
+        FileUtils.mkdir_p(package_path)
+        Packager.new.unpack(file_path, package_path)
+        package_path
+      end
+
+      # Decrypts an encrypted package (.cap file or uncompressed directory)
+      # into a temporary directory and returns its path. The metadata.json
+      # of an encrypted package stays cleartext, but everything else is
+      # only readable with the recipient's private key.
+      def decrypt_cap_file(source_path)
+        unless @decryption_key
+          raise Cipher::KeyRequiredError,
+                "Package is encrypted; provide the private key via decryption_key:"
+        end
+
+        Cipher.decrypt_to_directory(source_path, @decryption_key)
+      end
+
+      def determine_load_type(path)
+        return :directory if File.directory?(path)
+
+        File.extname(path) == ".cap" ? :cap_file : :unsaved
+      end
+
+      # Whether the package was loaded from an encrypted source
+      # (ARCHITECTURE.md section 6b layout).
+      def encrypted?
+        Cipher.encrypted?(@original_path)
+      end
+
+      private
+
+      def package_stem(file_path)
+        File.basename(file_path, ".cap")
+      end
+
+      def create_package_structure
+        FileUtils.mkdir_p(content_path)
+        FileUtils.mkdir_p(data_path)
+      end
+
+      def content_path = File.join(@path, CONTENT_DIR)
+
+      def data_path = File.join(@path, DATA_DIR)
+
+      def routes_path = File.join(@path, ROUTES_FILE)
+
+      def storage_path = File.join(@path, STORAGE_FILE)
+
+      def metadata_path = File.join(@path, METADATA_FILE)
+
+      def manifest_path = File.join(@path, MANIFEST_FILE)
+
+      def security_path = File.join(@path, SECURITY_FILE)
+
+      def authentication_path = File.join(@path, AUTHENTICATION_FILE)
+    end
+  end
+end

data/lib/capsium/package/routes.rb

@@ -1,27 +1,22 @@
 # frozen_string_literal: true
 
-# lib/capsium/package/routes.rb
-require "json"
-require "fileutils"
-require_relative "routes_config"
+require "forwardable"
 
 module Capsium
   class Package
     class Routes
       extend Forwardable
-      attr_reader :config
 
-      def_delegators :@config, :to_json
+      attr_reader :path, :config, :manifest, :storage
 
-      attr_reader :path, :config, :index, :manifest, :storage
+      def_delegators :@config, :to_hash
 
-      ROUTES_FILE = "routes.json"
-      DEFAULT_INDEX_TARGET = "content/index.html"
       INDEX_ROUTE = "/"
+      INDEX_RESOURCE = "content/index.html"
+      DATASET_ROUTE_PREFIX = "/api/v1/data/"
 
       def initialize(path, manifest, storage)
         @path = path
-        @dir = File.dirname(path)
         @manifest = manifest
         @storage = storage
         @config = if File.exist?(path)
@@ -29,8 +24,6 @@ module Capsium
                   else
                     generate_routes
                   end
-        validate_index_path(@config.resolve(INDEX_ROUTE)&.target&.file)
-        validate
       end
 
       def resolve(url_path)
@@ -38,12 +31,10 @@ module Capsium
       end
 
       def add_route(route, target)
-        validate_route_target(route, target)
         @config.add(route, target)
       end
 
       def update_route(route, updated_route, updated_target)
-        validate_route_target(updated_route, updated_target)
         @config.update(route, updated_route, updated_target)
       end
 
@@ -51,48 +42,55 @@ module Capsium
         @config.remove(route)
       end
 
-      def validate
-        @config.routes.each do |route|
-          route.target.validate(@manifest, @storage)
-        end
-      end
-
       def to_json(*_args)
-        @config.sort!.to_json
+        @config.to_json
       end
 
       def save_to_file(output_path = @path)
         File.write(output_path, to_json)
       end
 
+      # Auto-generation (ARCHITECTURE.md section 4): every manifest
+      # resource gets a route at its path relative to content/; HTML files
+      # get two routes (basename without extension and full filename); the
+      # index HTML additionally gets "/"; every dataset in storage gets
+      # /api/v1/data/<id>. Output is deterministic (sorted by path).
+      def generate_routes
+        routes = resource_routes + dataset_routes
+        RoutesConfig.new(index: index_resource, routes: routes.sort_by(&:path))
+      end
+
       private
 
-      def generate_routes
-        r = RoutesConfig.new
-        manifest.config.sort!.content.each_with_object({}) do |data_item, _hash|
-          relative_path = data_item.file.sub(/^#{Package::CONTENT_DIR}/o, "")
-          r.add(relative_path, data_item.file)
-
-          # Ensure the index route is included
-          if File.basename(relative_path, ".*") == "index"
-            r.add("/index", data_item.file)
-            r.add("/", data_item.file)
-          end
-        end
+      def index_resource
+        INDEX_RESOURCE if @manifest.resources.key?(INDEX_RESOURCE)
+      end
 
-        r
+      def resource_routes
+        @manifest.resources.keys.flat_map do |resource_path|
+          routes_for_resource(resource_path)
+        end.uniq(&:path)
       end
 
-      def validate_index_path(index_path)
-        return unless index_path
+      def routes_for_resource(resource_path)
+        url_path = resource_path.sub(%r{\A#{Package::CONTENT_DIR}/}o, "")
+        routes = [Route.new(path: "/#{url_path}", resource: resource_path)]
+        return routes unless File.extname(resource_path) == ".html"
 
-        target_path = @manifest.path_to_content_file(index_path)
-        raise "Index file does not exist: #{target_path}" unless File.exist?(target_path)
-        raise "Index file is not an HTML file: #{target_path}" unless File.extname(target_path).downcase == ".html"
+        basename = File.basename(url_path, ".html")
+        routes << Route.new(path: "/#{basename}", resource: resource_path)
+        routes << Route.new(path: INDEX_ROUTE, resource: resource_path) if index?(resource_path)
+        routes
       end
 
-      def validate_route_target(route, target)
-        # Add any necessary validation logic for the route and target
+      def index?(resource_path)
+        resource_path == INDEX_RESOURCE
+      end
+
+      def dataset_routes
+        @storage.dataset_names.map do |name|
+          Route.new(path: "#{DATASET_ROUTE_PREFIX}#{name}", dataset: name)
+        end
       end
     end
   end