lutaml-store 0.1.1

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Store
+    module Format
+      class Base
+        def extension
+          raise NotImplementedError
+        end
+
+        def glob_pattern
+          raise NotImplementedError
+        end
+
+        def serialize(model)
+          raise NotImplementedError
+        end
+
+        def deserialize(data, model_class)
+          raise NotImplementedError
+        end
+
+        def serialize_many(models)
+          models.map { |m| serialize(m) }.join
+        end
+
+        def deserialize_many(_data, _model_class)
+          raise NotImplementedError, "#{self.class} does not support multi-document deserialization"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/store/format/json.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Store
+    module Format
+      class Json < Base
+        def extension
+          ".json"
+        end
+
+        def glob_pattern
+          "*.json"
+        end
+
+        def serialize(model)
+          model.to_json
+        end
+
+        def deserialize(data, model_class)
+          model_class.from_json(data)
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/store/format/jsonl.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Store
+    module Format
+      class Jsonl < Base
+        def extension
+          ".jsonl"
+        end
+
+        def glob_pattern
+          "*.jsonl"
+        end
+
+        def serialize(model)
+          model.to_json
+        end
+
+        def serialize_many(models)
+          "#{models.map(&:to_json).join("\n")}\n"
+        end
+
+        def deserialize(data, model_class)
+          model_class.from_json(data)
+        end
+
+        def deserialize_many(data, model_class)
+          data.lines.filter_map do |line|
+            next if line.strip.empty?
+
+            model_class.from_json(line)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/store/format/marshal_format.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Store
+    module Format
+      class MarshalFormat < Base
+        def extension
+          ".bin"
+        end
+
+        def glob_pattern
+          "*.bin"
+        end
+
+        def serialize(model)
+          hash_data = model.to_hash
+          ::Marshal.dump(hash_data)
+        end
+
+        def deserialize(data, model_class)
+          hash_data = ::Marshal.load(data)
+          model_class.from_hash(hash_data)
+        end
+
+        def serialize_many(models)
+          hash_array = models.map(&:to_hash)
+          ::Marshal.dump(hash_array)
+        end
+
+        def deserialize_many(data, model_class)
+          hash_array = ::Marshal.load(data)
+          hash_array.map { |h| model_class.from_hash(h) }
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/store/format/yaml.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Store
+    module Format
+      class Yaml < Base
+        def extension
+          ".yaml"
+        end
+
+        def glob_pattern
+          "*.{yaml,yml}"
+        end
+
+        def serialize(model)
+          model.to_yaml
+        end
+
+        def deserialize(data, model_class)
+          model_class.from_yaml(data)
+        end
+
+        def deserialize_many(data, model_class)
+          model_class.from_yamls(data)
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/store/format/yamls.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Store
+    module Format
+      class Yamls < Base
+        def extension
+          ".yaml"
+        end
+
+        def glob_pattern
+          "*.{yaml,yml}"
+        end
+
+        def serialize(model)
+          model.to_yaml
+        end
+
+        def serialize_many(models)
+          models.map(&:to_yaml).join
+        end
+
+        def deserialize(data, model_class)
+          docs = model_class.from_yamls(data)
+          docs.is_a?(Array) ? docs.first : docs
+        end
+
+        def deserialize_many(data, model_class)
+          result = model_class.from_yamls(data)
+          result.is_a?(Array) ? result : [result]
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/store/format.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Store
+    module Format
+      class Error < Lutaml::Store::Error; end
+      class FormatError < Error; end
+      class UnsupportedFormatError < FormatError; end
+
+      autoload :Base, "lutaml/store/format/base"
+      autoload :Yaml, "lutaml/store/format/yaml"
+      autoload :Yamls, "lutaml/store/format/yamls"
+      autoload :Json, "lutaml/store/format/json"
+      autoload :Jsonl, "lutaml/store/format/jsonl"
+      autoload :MarshalFormat, "lutaml/store/format/marshal_format"
+
+      FORMATS = {
+        yaml: "Yaml",
+        yamls: "Yamls",
+        json: "Json",
+        jsonl: "Jsonl",
+        marshal: "MarshalFormat"
+      }.freeze
+
+      def self.resolve(format)
+        entry = FORMATS[format.to_sym]
+        raise UnsupportedFormatError, "Unknown format: #{format}" unless entry
+
+        const_get(entry).new
+      end
+    end
+  end
+end

data/lib/lutaml/store/http_cache.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Lutaml
+  module Store
+    class HttpCache
+      def initialize(config)
+        @config = config.is_a?(HttpCacheConfig) ? config : HttpCacheConfig.new(config)
+        @config.validate!
+        @adapter = create_adapter
+        @stats = {
+          cache_hits: 0,
+          cache_misses: 0,
+          conditional_requests: 0,
+          not_modified_responses: 0,
+          entries_stored: 0,
+          entries_evicted: 0
+        }
+      end
+
+      # Main cache interface - fetch with block for cache miss
+      def fetch(method, url, headers = {}, &block)
+        raise ArgumentError, "Block required for cache miss handling" unless block_given?
+
+        # Generate cache key considering vary headers
+        vary_headers = extract_request_vary_headers(headers)
+        cache_key = HttpHeaderProcessor.generate_cache_key(
+          method,
+          url,
+          vary_headers,
+          @config.ignore_query_params
+        )
+
+        prefixed_key = @config.cache_key_for(cache_key)
+        entry = get_entry(prefixed_key)
+
+        # Check if entry matches current request (Vary header consideration)
+        if entry && cache_entry_matches?(entry, headers)
+          if entry.fresh?
+            @stats[:cache_hits] += 1
+            return create_response_from_entry(entry)
+          elsif entry.stale? && @config.enable_conditional_requests
+            # Try conditional request
+            @stats[:conditional_requests] += 1
+            return handle_conditional_request(entry, headers, prefixed_key, &block)
+          end
+        end
+
+        # Cache miss or unusable entry - make fresh request
+        @stats[:cache_misses] += 1
+        response = yield(headers)
+        cache_response(prefixed_key, method, url, headers, response)
+      end
+
+      # Get cached entry without making requests
+      def get(method, url, headers = {})
+        vary_headers = extract_request_vary_headers(headers)
+        cache_key = HttpHeaderProcessor.generate_cache_key(
+          method,
+          url,
+          vary_headers,
+          @config.ignore_query_params
+        )
+
+        prefixed_key = @config.cache_key_for(cache_key)
+        entry = get_entry(prefixed_key)
+
+        return nil unless entry
+        return nil unless cache_entry_matches?(entry, headers)
+        return nil unless entry.fresh?
+
+        create_response_from_entry(entry)
+      end
+
+      # Store response in cache
+      def set(method, url, headers, response)
+        return response unless should_cache_response?(response)
+
+        vary_headers = extract_request_vary_headers(headers)
+        cache_key = HttpHeaderProcessor.generate_cache_key(
+          method,
+          url,
+          vary_headers,
+          @config.ignore_query_params
+        )
+
+        prefixed_key = @config.cache_key_for(cache_key)
+        cache_response(prefixed_key, method, url, headers, response)
+      end
+
+      # Delete cached entry
+      def delete(method, url, headers = {})
+        vary_headers = extract_request_vary_headers(headers)
+        cache_key = HttpHeaderProcessor.generate_cache_key(
+          method,
+          url,
+          vary_headers,
+          @config.ignore_query_params
+        )
+
+        prefixed_key = @config.cache_key_for(cache_key)
+        @adapter.delete(prefixed_key)
+      rescue StandardError
+        # Log error but don't fail
+        false
+      end
+
+      # Clear all cache entries
+      def clear
+        @adapter.clear
+      rescue StandardError
+        false
+      end
+
+      # Get cache statistics
+      def stats
+        total_requests = @stats[:cache_hits] + @stats[:cache_misses]
+        hit_ratio = total_requests.positive? ? (@stats[:cache_hits].to_f / total_requests * 100) : 0
+
+        {
+          adapter_type: @config.adapter_type,
+          total_entries: @adapter.size,
+          cache_hits: @stats[:cache_hits],
+          cache_misses: @stats[:cache_misses],
+          conditional_requests: @stats[:conditional_requests],
+          not_modified_responses: @stats[:not_modified_responses],
+          entries_stored: @stats[:entries_stored],
+          entries_evicted: @stats[:entries_evicted],
+          hit_ratio: hit_ratio,
+          total_requests: total_requests,
+          config: {
+            default_ttl: @config.default_ttl,
+            max_entries: @config.max_entries,
+            respect_http_headers: @config.respect_http_headers,
+            enable_conditional_requests: @config.enable_conditional_requests
+          }
+        }
+      end
+
+      # Get all cache entries for inspection
+      def all_entries
+        entries = []
+        @adapter.each_key do |key|
+          data = @adapter.get(key)
+          next unless data
+
+          entry_data = data.is_a?(String) ? JSON.parse(data) : data
+          entry = HttpCacheEntry.from_hash(entry_data)
+          entries << entry
+        rescue StandardError
+          # Skip invalid entries
+        end
+        entries
+      end
+
+      private
+
+      def create_adapter
+        adapter_config = @config.to_adapter_config
+        case adapter_config[:type]
+        when :memory
+          Adapter::Memory.new(adapter_config)
+        when :filesystem
+          Adapter::FileSystem.new(adapter_config)
+        when :sqlite
+          Adapter::Sqlite.new(adapter_config)
+        else
+          raise ArgumentError, "Unknown adapter type: #{adapter_config[:type]}"
+        end
+      end
+
+      def get_entry(cache_key)
+        data = @adapter.get(cache_key)
+        return nil unless data
+
+        # Handle both serialized and hash data
+        entry_data = data.is_a?(String) ? JSON.parse(data) : data
+        HttpCacheEntry.from_hash(entry_data)
+      rescue StandardError
+        # Log error and continue without cache
+        nil
+      end
+
+      def store_entry(cache_key, entry)
+        # Serialize entry for storage
+        data = entry.to_hash
+        @adapter.set(cache_key, data)
+      rescue StandardError
+        # Log error but don't fail the request
+        false
+      end
+
+      def handle_conditional_request(entry, headers, cache_key, &block)
+        # Build conditional headers
+        conditional_headers = HttpHeaderProcessor.build_conditional_headers(entry, headers)
+        response = yield(conditional_headers)
+
+        if response[:status_code] == 304
+          # Not modified - refresh cache timestamp and return cached content
+          entry.cached_at = Time.now
+          store_entry(cache_key, entry)
+          create_response_from_entry(entry)
+        else
+          # Modified - cache new response
+          cache_response(cache_key, entry.method, entry.url, headers, response)
+        end
+      end
+
+      def cache_response(cache_key, method, url, request_headers, response)
+        if should_cache_response?(response)
+          entry = create_cache_entry(cache_key, method, url, request_headers, response)
+          @stats[:entries_stored] += 1 if store_entry(cache_key, entry)
+        end
+
+        response
+      end
+
+      def should_cache_response?(response)
+        return false unless @config.respect_http_headers
+        return false unless response[:status_code]
+
+        HttpHeaderProcessor.should_cache_response?(response[:status_code], response[:headers] || {})
+      end
+
+      def create_cache_entry(cache_key, method, url, request_headers, response)
+        cached_at = Time.now
+        response_headers = response[:headers] || {}
+
+        # Parse cache control and calculate expiry
+        cache_control = HttpHeaderProcessor.parse_cache_control(response_headers["cache-control"])
+        expires_at = HttpHeaderProcessor.calculate_expiry(response_headers, cached_at, @config.default_ttl)
+
+        # Parse vary headers
+        vary_headers = HttpHeaderProcessor.parse_vary_header(response_headers["vary"])
+
+        # Extract vary header values from request
+        request_vary_headers = {}
+        request_vary_headers = HttpHeaderProcessor.extract_vary_headers(request_headers, vary_headers) if vary_headers.any?
+
+        HttpCacheEntry.new(
+          cache_key: cache_key,
+          url: url,
+          method: method,
+          request_headers: request_vary_headers, # Store only vary-relevant headers
+          response_body: response[:body] || "",
+          response_headers: response_headers,
+          status_code: response[:status_code],
+          cached_at: cached_at,
+          etag: response_headers["etag"],
+          last_modified: HttpHeaderProcessor.parse_last_modified(response_headers["last-modified"]),
+          expires_at: expires_at,
+          max_age: cache_control["max-age"],
+          cache_control: cache_control,
+          vary_headers: vary_headers
+        )
+      end
+
+      def create_response_from_entry(entry)
+        {
+          status_code: entry.status_code,
+          headers: entry.response_headers,
+          body: entry.response_body
+        }
+      end
+
+      def extract_request_vary_headers(_headers)
+        # For now, return empty hash - will be populated when we know vary headers
+        {}
+      end
+
+      def cache_entry_matches?(entry, request_headers)
+        return true if entry.vary_headers.empty?
+
+        HttpHeaderProcessor.cache_entry_matches?(entry, request_headers, @config)
+      end
+    end
+  end
+end

data/lib/lutaml/store/http_cache_config.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Lutaml
+  module Store
+    class HttpCacheConfig
+      include Lutaml::Model::Serialize
+
+      attribute :adapter_type, :string, default: "filesystem"
+      attribute :adapter_options, :hash, default: {}
+      attribute :default_ttl, :integer, default: 3600
+      attribute :max_entries, :integer, default: 10_000
+      attribute :respect_http_headers, :boolean, default: true
+      attribute :enable_conditional_requests, :boolean, default: true
+      attribute :enable_compression, :boolean, default: false
+      attribute :cache_private_responses, :boolean, default: false
+      attribute :ignore_query_params, :string, collection: true, default: []
+      attribute :vary_ignore_headers, :string, collection: true, default: []
+      attribute :cache_key_prefix, :string, default: "http_cache"
+
+      def to_adapter_config
+        base_config = {
+          type: adapter_type.to_sym,
+          **adapter_options.transform_keys(&:to_sym)
+        }
+
+        # Add compression if enabled
+        base_config[:compression] = true if enable_compression
+
+        base_config
+      end
+
+      def cache_key_for(key)
+        "#{cache_key_prefix}:#{key}"
+      end
+
+      def should_ignore_query_param?(param)
+        ignore_query_params.include?(param.to_s)
+      end
+
+      def should_ignore_vary_header?(header)
+        vary_ignore_headers.map(&:downcase).include?(header.to_s.downcase)
+      end
+
+      def validate!
+        raise ArgumentError, "default_ttl must be positive" if default_ttl <= 0
+        raise ArgumentError, "max_entries must be positive" if max_entries <= 0
+        raise ArgumentError, "adapter_type cannot be empty" if adapter_type.nil? || adapter_type.empty?
+      end
+    end
+  end
+end

data/lib/lutaml/store/http_cache_entry.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require "time"
+require "digest"
+
+module Lutaml
+  module Store
+    class HttpCacheEntry
+      include Lutaml::Model::Serialize
+
+      attribute :cache_key, :string
+      attribute :url, :string
+      attribute :method, :string, default: "GET"
+      attribute :request_headers, :hash, default: {}
+      attribute :response_body, :string
+      attribute :response_headers, :hash, default: {}
+      attribute :status_code, :integer
+      attribute :cached_at, :time
+      attribute :etag, :string
+      attribute :last_modified, :time
+      attribute :expires_at, :time
+      attribute :max_age, :integer
+      attribute :cache_control, :hash, default: {}
+      attribute :vary_headers, :string, collection: true, default: []
+
+      def fresh?
+        return false if expired?
+        return false if must_revalidate?
+
+        true
+      end
+
+      def expired?
+        return true if expires_at && Time.now > expires_at
+        return true if max_age && (Time.now - cached_at) > max_age
+
+        false
+      end
+
+      def must_revalidate?
+        !!(cache_control["must-revalidate"] || cache_control["no-cache"])
+      end
+
+      def stale?
+        !fresh?
+      end
+
+      def cacheable?
+        return false if status_code < 200 || status_code >= 400
+        return false if cache_control["no-store"]
+        return false if cache_control["private"]
+
+        true
+      end
+
+      def age
+        Time.now - cached_at
+      end
+
+      def remaining_ttl
+        return 0 if expired?
+        return Float::INFINITY unless expires_at
+
+        expires_at - Time.now
+      end
+    end
+  end
+end