lutaml-store 0.2.4 → 0.3.1

data/lib/lutaml/store/source/base.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Store
+    module Source
+      # Contract shared by every source.
+      #
+      # Subclasses implement {#read} (bytes for one key, raising
+      # NotFoundError for a definitive miss and BackendError for transport
+      # trouble) and {#manifest_raw} (the manifest document). Everything
+      # else — keys, existence, typed reads — composes those two.
+      class Base
+        OPTIONS = [].freeze
+
+        attr_reader :options
+
+        def initialize(**options)
+          @options = options
+          missing = (self.class::OPTIONS - options.keys)
+          unless missing.empty?
+            raise ConfigurationError,
+                  "#{self.class.name.split("::").last.downcase} source requires: " \
+                  "#{missing.map(&:inspect).join(", ")}"
+          end
+          configure
+        end
+
+        # Bytes of one record. Raises NotFoundError (definitive) or
+        # BackendError (transport). Never returns nil.
+        #
+        # @param key [String]
+        # @return [String]
+        def read(_key)
+          raise NotImplementedError, "#{self.class}#read"
+        end
+
+        # The manifest document as a string.
+        #
+        # @return [String]
+        def manifest_raw
+          raise NotImplementedError, "#{self.class}#manifest_raw"
+        end
+
+        # The parsed manifest, memoized.
+        #
+        # @return [Manifest]
+        def manifest
+          @manifest ||= Manifest.parse(manifest_raw, format: manifest_format)
+        end
+
+        # All keys declared by the manifest. There is deliberately no
+        # fallback listing: an unenumerable source raises ConfigurationError
+        # instead of guessing.
+        #
+        # @return [Array<String>]
+        def keys
+          manifest.keys
+        end
+
+        # Manifest entry for one key.
+        #
+        # @param key [String]
+        # @return [Manifest::Entry, nil]
+        def entry_for(key)
+          manifest.entry_for(key)
+        end
+
+        def each_key(&block)
+          return to_enum(:each_key) unless block
+
+          keys.each(&block)
+        end
+
+        # Existence via a full read. A HEAD-based optimization may be
+        # provided per source; the default is honest and uniform.
+        #
+        # @param key [String]
+        # @return [Boolean]
+        def exist?(key)
+          read(key)
+          true
+        rescue NotFoundError
+          false
+        end
+
+        # Deserialized record using the consumer's model class — the model
+        # is declared by the caller, never inferred.
+        #
+        # @param key [String]
+        # @param model_class [Class] a Lutaml::Model::Serializable subclass
+        # @return the model instance
+        def get(key, model_class)
+          format_for(key).deserialize(read(key), model_class)
+        end
+
+        # Location of one key relative to the source. Manifest-declared
+        # locations win; otherwise the single-segment convention
+        # "entries/<percent-encoded key>" applies.
+        #
+        # @param key [String]
+        # @return [String]
+        def path_for(key)
+          entry = manifest.entry_for(key) if manifestable?
+          return entry.location if entry&.location
+
+          "entries/#{Source.encode_key(key)}"
+        end
+
+        private
+
+        def manifestable?
+          manifest
+          true
+        rescue NotImplementedError, BackendError, NotFoundError
+          false
+        end
+
+        def manifest_format
+          @options[:manifest_format] || :json
+        end
+
+        def format_for(key)
+          fmt = Format.for_extension(::File.extname(path_for(key).to_s))
+          fmt ||= Format.for_extension(::File.extname(key.to_s))
+          fmt ||= @options[:default_format] &&
+                  Format.resolve(@options[:default_format])
+          fmt || raise(ConfigurationError,
+                       "cannot determine the format of #{key.inspect}: pass default_format:")
+        end
+
+        def require_option(name)
+          @options[name] || raise(ConfigurationError, "#{name} is required")
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/store/source/directory.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "fileutils"
+
+module Lutaml
+  module Store
+    module Source
+      # A local package directory: `manifest.json` + `entries/`. This is the
+      # layout {Mirror}#pull writes and what a downloaded official package
+      # (GCR-style) ships — one reader for caches, distributions and
+      # checkouts.
+      class Directory < Base
+        OPTIONS = %i[path].freeze
+
+        attr_reader :package_root
+
+        private
+
+        def configure
+          @path = require_option(:path)
+          @package_root = @path
+          # A read-only source never writes - not even directory creation.
+          # A missing path simply holds no entries and no manifest.
+        end
+
+        def entry_path(key)
+          File.join(@path, path_for(key))
+        end
+
+        public
+
+        def read(key)
+          File.binread(entry_path(key))
+        rescue Errno::ENOENT
+          raise NotFoundError, "no entry #{key.inspect} in #{@path}"
+        rescue SystemCallError => e
+          raise BackendError, "cannot read #{key.inspect} in #{@path}: #{e.message}"
+        end
+
+        def manifest_raw
+          File.binread(File.join(@path, "manifest.json"))
+        rescue Errno::ENOENT
+          raise NotFoundError, "no manifest.json in #{@path}"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/store/source/https.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+
+module Lutaml
+  module Store
+    module Source
+      # Any static HTTP host — GitHub Pages, raw.githubusercontent, an
+      # object-storage bucket. The consumer states the base URL; the source
+      # appends one percent-encoded path segment per key.
+      #
+      # Every read may be wrapped in an explicit `cache:` (an
+      # HttpCacheConfig hash) so ETag/304 revalidation is handled by the
+      # store's HttpCache. With no cache configured, reads go straight to
+      # the network — nothing is implied.
+      #
+      # `transport:` accepts a callable for tests and alternative HTTP
+      # stacks: `->(uri, headers) { {status_code:, headers:, body:} }`.
+      class Https < Base
+        OPTIONS = %i[base_url].freeze
+
+        RETRIED_ERRORS = [
+          SocketError, Timeout::Error, IOError, SystemCallError,
+          OpenSSL::SSL::SSLError, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError,
+          Net::ProtocolError
+        ].freeze
+
+        private
+
+        def configure
+          base = require_option(:base_url)
+          @base = URI.parse(base.to_s)
+          raise ConfigurationError, "base_url must be http(s)" unless @base.is_a?(URI::HTTP) ||
+                                                                      @base.is_a?(URI::HTTPS)
+
+          @headers = @options.fetch(:headers, {})
+          @timeout = @options.fetch(:timeout, 60)
+          @open_timeout = @options.fetch(:open_timeout, 60)
+          @max_redirects = @options.fetch(:max_redirects, 3)
+          @transport = @options[:transport]
+          @cache = @options[:cache] && HttpCache.new(@options[:cache])
+        end
+
+        def fetch(uri, headers = {}, redirects = @max_redirects)
+          response = raw_fetch(uri, headers)
+          case response[:status_code]
+          when 200..299 then response
+          when 301, 302, 307, 308
+            raise BackendError, "too many redirects fetching #{uri}" if redirects.zero?
+
+            fetch(URI.parse(response[:headers]["location"]), headers, redirects - 1)
+          when 404 then raise NotFoundError, "no entry at #{uri}"
+          else raise BackendError, "HTTP #{response[:status_code]} fetching #{uri}"
+          end
+        end
+
+        def raw_fetch(uri, headers)
+          if @transport
+            begin
+              return @transport.call(uri, headers)
+            rescue *RETRIED_ERRORS => e
+              raise BackendError, "cannot fetch #{uri}: #{e.class}: #{e.message}"
+            end
+          end
+
+          if @cache
+            return @cache.fetch(:get, uri.to_s, headers) do |h|
+              http_get(uri, h)
+            end
+          end
+
+          http_get(uri, headers)
+        end
+
+        def http_get(uri, headers)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.is_a?(URI::HTTPS)
+          http.open_timeout = @open_timeout
+          http.read_timeout = @timeout
+          begin
+            resp = http.get(uri, @headers.merge(headers))
+            { status_code: resp.code.to_i, headers: resp.each_header.to_h, body: resp.body }
+          rescue *RETRIED_ERRORS => e
+            raise BackendError, "cannot fetch #{uri}: #{e.class}: #{e.message}"
+          end
+        end
+
+        def url_for(relative_path)
+          base = @base.to_s.sub(%r{/+\z}, "")
+          path = relative_path.sub(%r{\A/+}, "")
+          URI.parse("#{base}/#{path}")
+        end
+
+        public
+
+        def read(key)
+          fetch(url_for(Source.encode_key(key)))[:body]
+        end
+
+        def manifest_raw
+          fetch(url_for(@options.fetch(:manifest_path, "manifest.json")))[:body]
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/store/source/rest.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Lutaml
+  module Store
+    module Source
+      # A repository served by the lutaml cloud store API (the contract
+      # distilled from api.relaton.org):
+      #
+      #   GET {base}/collections                          → collection list
+      #   GET {base}/collections/{c}/manifest             → Manifest
+      #   GET {base}/collections/{c}/entries/{key}        → record
+      #
+      # 404 is a definitive "no such key/collection" (NotFoundError); every
+      # other non-2xx is a BackendError. Path shapes are fixed here so
+      # server implementers have one contract — not per-client guesswork.
+      class Rest < Https
+        OPTIONS = %i[base_url collection].freeze
+
+        private
+
+        def configure
+          super
+          @collection = require_option(:collection)
+        end
+
+        def collection_path(suffix)
+          "collections/#{Source.encode_key(@collection)}#{suffix}"
+        end
+
+        public
+
+        def read(key)
+          fetch(url_for(collection_path("/entries/#{Source.encode_key(key)}")))[:body]
+        end
+
+        def manifest_raw
+          fetch(url_for(collection_path("/manifest")))[:body]
+        end
+
+        # All collections the API publishes.
+        #
+        # @return [Array<Hash>]
+        def collections
+          JSON.parse(fetch(url_for("collections"))[:body])["collections"]
+        end
+
+        # The keys of one declared shard, when the collection's manifest
+        # advertises sharding. Shard-number semantics belong to the domain;
+        # this only fetches the named part.
+        #
+        # @param number [Integer]
+        # @return [Array<String>]
+        def shard(number)
+          JSON.parse(fetch(url_for(collection_path("/shards/#{Integer(number)}")))[:body])["keys"]
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/store/source/zip.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "zip"
+
+module Lutaml
+  module Store
+    module Source
+      # A packaged repository read in place from a .zip — the shape of a
+      # downloaded official package. Same internal layout as
+      # {Directory}: manifest.json + entries/.
+      class Zip < Base
+        OPTIONS = %i[path].freeze
+
+        private
+
+        def configure
+          @path = require_option(:path)
+          return if File.file?(@path)
+
+          raise ConfigurationError, "no such package file: #{@path}"
+        end
+
+        def with_zip(&block)
+          ::Zip::File.open(@path, &block)
+        rescue ::Zip::Error => e
+          raise BackendError, "cannot open package #{@path}: #{e.message}"
+        end
+
+        public
+
+        def read(key)
+          inner = path_for(key)
+          with_zip do |zip|
+            entry = zip.find_entry(inner)
+            raise NotFoundError, "no entry #{key.inspect} in #{::File.basename(@path)}" unless entry
+
+            entry.get_input_stream.read
+          end
+        end
+
+        def manifest_raw
+          with_zip do |zip|
+            entry = zip.find_entry("manifest.json")
+            raise NotFoundError, "no manifest.json in #{::File.basename(@path)}" unless entry
+
+            entry.get_input_stream.read
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/store/source.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Store
+    # Read-only views over a LutaML data repository.
+    #
+    # A source answers four questions about a remote or local collection of
+    # LutaML records: does a key exist, what are its bytes, which keys exist,
+    # and what does the repository's manifest declare. Sources never write.
+    #
+    # Selection is explicit: `Source.for(type, options)` raises
+    # `ConfigurationError` for a missing option — there is no discovery,
+    # no environment guessing and no fallback between sources. Consumers
+    # compose sources with {Repository} for caching policies.
+    module Source
+      autoload :Base, "lutaml/store/source/base"
+      autoload :Directory, "lutaml/store/source/directory"
+      autoload :Zip, "lutaml/store/source/zip"
+      autoload :Https, "lutaml/store/source/https"
+      autoload :Rest, "lutaml/store/source/rest"
+
+      TYPES = {
+        directory: "Directory",
+        zip: "Zip",
+        https: "Https",
+        rest: "Rest"
+      }.freeze
+
+      class << self
+        # Builds an explicitly configured source.
+        #
+        # @param type [Symbol] one of {TYPES}
+        # @param options [Hash] passed to the source class
+        # @return [Source::Base]
+        def for(type, **options)
+          name = TYPES[type.to_sym]
+          raise ConfigurationError, "unknown source type: #{type.inspect}" unless name
+
+          Source.const_get(name).new(**options)
+        end
+
+        # A key is percent-encoded into exactly one path segment, so storage
+        # keys like "RFC 3986" or "ISO/IEC DIR 1" map to one file each on
+        # every platform. The manifest keeps the real key.
+        def encode_key(key)
+          CGI.escape(key.to_s)
+        end
+
+        def decode_key(segment)
+          CGI.unescape(segment.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/store/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Store
-    VERSION = "0.2.4"
+    VERSION = "0.3.1"
   end
 end

data/lib/lutaml/store.rb

@@ -5,6 +5,7 @@ module Lutaml
     class Error < StandardError; end
     class ConfigurationError < Error; end
     class BackendError < Error; end
+    class NotFoundError < Error; end
     class ModelNotRegisteredError < Error; end
     class InvalidKeyError < Error; end
     class PolymorphicUpdateError < Error; end
@@ -39,6 +40,10 @@ module Lutaml
     autoload :HttpCacheConfig, "lutaml/store/http_cache_config"
     autoload :HttpCacheEntry, "lutaml/store/http_cache_entry"
     autoload :HttpHeaderProcessor, "lutaml/store/http_header_processor"
+    autoload :Manifest, "lutaml/store/manifest"
+    autoload :Mirror, "lutaml/store/mirror"
+    autoload :Repository, "lutaml/store/repository"
+    autoload :Source, "lutaml/store/source"
 
     def self.new(adapter:, models: [], **options)
       DatabaseStore.new(adapter: adapter, models: models, **options)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-store
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.1
 platform: ruby
 authors:
 - Ronald Tse
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-17 00:00:00.000000000 Z
+date: 2026-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lutaml-model
@@ -61,6 +61,24 @@ files:
 - CODE_OF_CONDUCT.md
 - README.adoc
 - Rakefile
+- docs/astro.config.mjs
+- docs/package-lock.json
+- docs/package.json
+- docs/public/favicon.svg
+- docs/public/lutaml-logo_logo-full-dark.svg
+- docs/public/lutaml-logo_logo-full-light.svg
+- docs/src/layouts/Base.astro
+- docs/src/layouts/Docs.astro
+- docs/src/pages/adapters.md
+- docs/src/pages/architecture.md
+- docs/src/pages/cloud-contract.md
+- docs/src/pages/formats.md
+- docs/src/pages/http-cache.md
+- docs/src/pages/index.md
+- docs/src/pages/quick-start.md
+- docs/src/pages/sources.md
+- docs/src/pages/stores.md
+- docs/src/styles/global.css
 - lib/lutaml/store.rb
 - lib/lutaml/store/adapter.rb
 - lib/lutaml/store/adapter/base.rb
@@ -90,6 +108,8 @@ files:
 - lib/lutaml/store/http_cache_entry.rb
 - lib/lutaml/store/http_header_processor.rb
 - lib/lutaml/store/integrity.rb
+- lib/lutaml/store/manifest.rb
+- lib/lutaml/store/mirror.rb
 - lib/lutaml/store/model_registration.rb
 - lib/lutaml/store/model_registry.rb
 - lib/lutaml/store/model_serializer.rb
@@ -102,6 +122,13 @@ files:
 - lib/lutaml/store/package_transport/zip_transport.rb
 - lib/lutaml/store/predicate.rb
 - lib/lutaml/store/query.rb
+- lib/lutaml/store/repository.rb
+- lib/lutaml/store/source.rb
+- lib/lutaml/store/source/base.rb
+- lib/lutaml/store/source/directory.rb
+- lib/lutaml/store/source/https.rb
+- lib/lutaml/store/source/rest.rb
+- lib/lutaml/store/source/zip.rb
 - lib/lutaml/store/storage_key.rb
 - lib/lutaml/store/version.rb
 - sig/lutaml/store.rbs