lutaml-hal 0.1.10 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f3ce9deb2f8607008c4b5d6950dd281a79bcba5856b03769c0a764dd0c95228
-  data.tar.gz: 0d8bd9e4a6f78dd18ce1c58288276d8e0334a48e4858fcbbfb694fd68dc5deb1
+  metadata.gz: 5860a26a1d8b235f8138e37fe835c3f0de0d4cc065f99b33da9ed17c0cb0a8cf
+  data.tar.gz: e558941f569c2d8d55ac62c66924a06a7445438281c261e060471bdf2d8c9f5f
 SHA512:
-  metadata.gz: d29f19722b4aa33f3404cd084394573cfa7dc5af3811fb0d42a5cd78319de4e1ff8e8e71b6de59eb23441b39ff0588a36c02ae35156eee99aa845e90929691b6
-  data.tar.gz: 4d00fc04f030bda2eec1558ea616f1c3533b8e7109c3224678a96de41b374f4ddadae7a9cf2fd6cbe807633e77a185e8ab893e944b98dc4433898b1cbb1571cc
+  metadata.gz: a3cda001e3ebb066cf62e8aa54fbec2a41ae93a173a056919da2151cf8f28fcba143352ad2dc287d478c7365fa3e087abc1757770264acc05a4be925378072d7
+  data.tar.gz: d34fd6af3af5e78d1b223f04fa9f1e9e71ff524b2ac9425935d6bd5e07e4d8fa10a2c255c063c70026388d5f2406a05a41cde1492482cd66a911fb1fe80fb623

data/lib/lutaml/hal/cache/cache_configuration.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Lutaml
+  module Hal
+    module Cache
+      # Represents cache configuration with validation and defaults
+      class CacheConfiguration < Lutaml::Model::Serializable
+        attribute :adapter_type, :string
+        attribute :adapter_config, :hash
+        attribute :ttl, :integer
+        attribute :max_size, :integer
+        attribute :http_aware, :boolean
+        attribute :respect_http_headers, :boolean
+        attribute :enable_conditional_requests, :boolean
+        attribute :ignore_query_params, :string
+
+        # Default configuration values
+        DEFAULT_TTL = 3600
+        DEFAULT_MAX_SIZE = 1000
+        DEFAULT_ADAPTER_TYPE = 'memory'
+
+        # Create configuration from hash or symbol
+        def self.from_config(config)
+          return new if config.nil?
+
+          case config
+          when Hash
+            from_hash(config)
+          when Symbol, String
+            from_simple_config(config)
+          else
+            raise ArgumentError, "Invalid cache configuration: #{config.inspect}"
+          end
+        end
+
+        # Validate the configuration
+        def validate!
+          validate_adapter_type!
+          validate_ttl!
+          validate_max_size!
+          validate_adapter_config!
+        end
+
+        # Check if HTTP-aware caching should be used
+        #
+        # HTTP-aware caching (conditional requests backed by a response cache)
+        # is opt-in: it only applies when explicitly enabled and the
+        # lutaml-store HTTP cache backend is available. By default the register
+        # uses the basic object cache, which stores realized models directly.
+        def http_aware?
+          http_aware == true && http_cache_available?
+        end
+
+        # Check if basic caching should be used
+        def basic_cache?
+          !http_aware?
+        end
+
+        # Get the effective TTL (with fallback to default)
+        def effective_ttl
+          ttl || DEFAULT_TTL
+        end
+
+        # Get the effective max size (with fallback to default)
+        def effective_max_size
+          max_size || DEFAULT_MAX_SIZE
+        end
+
+        # Get the effective adapter type (with fallback to default)
+        def effective_adapter_type
+          adapter_type || DEFAULT_ADAPTER_TYPE
+        end
+
+        # Get HTTP cache configuration hash
+        def http_cache_config
+          {
+            adapter_type: effective_adapter_type.to_sym,
+            default_ttl: effective_ttl,
+            max_entries: effective_max_size,
+            respect_http_headers: respect_http_headers != false,
+            enable_conditional_requests: enable_conditional_requests != false,
+            ignore_query_params: parse_ignore_query_params
+          }.merge(adapter_config || {})
+        end
+
+        # Get basic cache configuration hash
+        def basic_cache_config
+          {
+            adapter: adapter_config || { type: effective_adapter_type.to_sym },
+            default_ttl: effective_ttl,
+            max_size: effective_max_size
+          }
+        end
+
+        private
+
+        def self.from_hash(config)
+          adapter_info = config[:adapter] || config['adapter'] || {}
+
+          # Handle direct adapter_type specification
+          adapter_type = config[:adapter_type] || config['adapter_type'] || extract_adapter_type(adapter_info)
+
+          new(
+            adapter_type: adapter_type,
+            adapter_config: adapter_info.is_a?(Hash) ? adapter_info : nil,
+            ttl: config[:ttl] || config['ttl'],
+            max_size: config[:max_size] || config['max_size'],
+            http_aware: config.key?(:http_aware) ? config[:http_aware] : config['http_aware'],
+            respect_http_headers: config.key?(:respect_http_headers) ? config[:respect_http_headers] : config['respect_http_headers'],
+            enable_conditional_requests: config.key?(:enable_conditional_requests) ? config[:enable_conditional_requests] : config['enable_conditional_requests'],
+            ignore_query_params: config[:ignore_query_params] || config['ignore_query_params']
+          )
+        end
+
+        def self.from_simple_config(config)
+          new(adapter_type: config.to_s)
+        end
+
+        def self.extract_adapter_type(adapter_info)
+          case adapter_info
+          when Hash
+            type = adapter_info[:type] || adapter_info['type']
+            type&.to_s
+          when Symbol, String
+            adapter_info.to_s
+          end
+        end
+
+        def validate_adapter_type!
+          valid_types = %w[memory filesystem sqlite]
+          return if valid_types.include?(effective_adapter_type)
+
+          raise ArgumentError, "Invalid adapter type: #{effective_adapter_type}. Valid types: #{valid_types.join(', ')}"
+        end
+
+        def validate_ttl!
+          return unless ttl
+          return if ttl.is_a?(Integer) && ttl > 0
+
+          raise ArgumentError, "TTL must be a positive integer, got: #{ttl.inspect}"
+        end
+
+        def validate_max_size!
+          return unless max_size
+          return if max_size.is_a?(Integer) && max_size > 0
+
+          raise ArgumentError, "Max size must be a positive integer, got: #{max_size.inspect}"
+        end
+
+        def validate_adapter_config!
+          return unless adapter_config
+          return if adapter_config.is_a?(Hash)
+
+          raise ArgumentError, "Adapter config must be a hash, got: #{adapter_config.class}"
+        end
+
+        # Override the setter to validate before assignment
+        def adapter_config=(value)
+          raise ArgumentError, "Adapter config must be a hash, got: #{value.class}" if value && !value.is_a?(Hash)
+
+          super(value)
+        end
+
+        def http_cache_available?
+          defined?(::Lutaml::Store::HttpCache)
+        end
+
+        def parse_ignore_query_params
+          return [] unless ignore_query_params
+
+          case ignore_query_params
+          when String
+            ignore_query_params.split(',').map(&:strip)
+          when Array
+            ignore_query_params
+          else
+            []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/hal/cache/cache_entry.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'cache_metadata'
+
+module Lutaml
+  module Hal
+    module Cache
+      # Represents a complete cached entry with metadata and HAL resource
+      class CacheEntry
+        attr_accessor :url, :cached_at, :metadata, :hal_resource
+
+        def initialize(url: nil, cached_at: nil, metadata: nil, hal_resource: nil)
+          @url = url
+          @cached_at = cached_at
+          @metadata = metadata
+          @hal_resource = hal_resource
+        end
+
+        # Plain-hash representation suitable for JSON persistence. The HAL
+        # resource and its class are recorded so the model can be rebuilt; the
+        # metadata is kept as its own JSON document.
+        def to_storage_h
+          {
+            'url' => url,
+            'cached_at' => cached_at,
+            'metadata' => metadata&.to_json,
+            'model_class' => hal_resource&.class&.name,
+            'model' => hal_resource&.to_json
+          }
+        end
+
+        # Called by lutaml-store's CacheStore when serializing a persisted entry.
+        def to_json(*_args)
+          JSON.generate(to_storage_h)
+        end
+
+        # True if the given hash looks like a to_storage_h document (as opposed
+        # to a legacy in-memory cache hash holding a live :realized_model).
+        def self.storage_format?(hash)
+          hash.key?('model') || hash.key?(:model) ||
+            hash.key?('model_class') || hash.key?(:model_class)
+        end
+
+        # Rebuild a CacheEntry from a to_storage_h document. Tolerates string or
+        # symbol keys, since lutaml-store parses persisted JSON with
+        # symbolize_names.
+        def self.from_storage_h(hash)
+          h = hash.transform_keys(&:to_s)
+          new(
+            url: h['url'],
+            cached_at: h['cached_at'],
+            metadata: h['metadata'] ? CacheMetadata.from_json(h['metadata']) : nil,
+            hal_resource: rebuild_model(h['model_class'], h['model'])
+          )
+        end
+
+        def self.rebuild_model(class_name, model_json)
+          return nil unless class_name && model_json
+
+          Object.const_get(class_name).from_json(model_json)
+        rescue NameError
+          nil
+        end
+
+        # Create a cache entry from a URL, response, and realized HAL resource
+        def self.create(url, response, hal_resource)
+          new(
+            url: url,
+            cached_at: Time.now.to_s,
+            metadata: CacheMetadata.from_response(response),
+            hal_resource: hal_resource
+          )
+        end
+
+        # Check if the cache entry is still valid based on TTL
+        def valid?(default_ttl)
+          return false unless cached_at
+
+          cached_time = cached_at.is_a?(String) ? Time.parse(cached_at) : cached_at
+          age = Time.now - cached_time
+          ttl = metadata&.max_age || default_ttl
+
+          age < ttl
+        end
+
+        # Check if the entry is expired and needs revalidation
+        def expired?(default_ttl)
+          !valid?(default_ttl)
+        end
+
+        # Check if the entry can be revalidated with conditional requests
+        def revalidatable?
+          return false unless metadata
+
+          !!(metadata.etag || metadata.last_modified)
+        end
+
+        # Get conditional headers for revalidation
+        def conditional_headers
+          metadata&.conditional_headers || {}
+        end
+
+        # Check if the response is cacheable based on metadata
+        def cacheable?
+          metadata&.cacheable? != false
+        end
+
+        # Update the cache entry with fresh metadata (for 304 responses)
+        def refresh_metadata(response)
+          self.cached_at = Time.now.to_s
+          self.metadata = CacheMetadata.from_response(response)
+        end
+
+        # Get cache age in seconds
+        def age
+          return 0 unless cached_at
+
+          cached_time = cached_at.is_a?(String) ? Time.parse(cached_at) : cached_at
+          Time.now - cached_time
+        end
+
+        # Check if entry should be served stale (useful for error scenarios)
+        def serve_stale?(max_stale = nil)
+          return false unless max_stale
+          return false if valid?(Float::INFINITY) # Still fresh
+
+          cached_time = cached_at.is_a?(String) ? Time.parse(cached_at) : cached_at
+          current_age = Time.now - cached_time
+          ttl = metadata&.max_age || 0
+
+          # Entry is stale if current_age > ttl
+          # But we can serve it if the staleness is within the max_stale window
+          staleness = current_age - ttl
+          current_age > ttl && staleness < max_stale
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/hal/cache/cache_manager.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+require_relative 'cache_configuration'
+require_relative 'cache_entry'
+require_relative 'cache_metadata'
+require_relative 'simple_cache_store'
+
+# Try to require lutaml-store. Requiring the entry point (rather than the
+# individual files) sets up the autoloads it relies on internally, e.g.
+# Lutaml::Store::HttpCacheConfig referenced from HttpCache#initialize.
+begin
+  require 'lutaml/store'
+  CACHE_STORE_AVAILABLE = true
+rescue LoadError
+  CACHE_STORE_AVAILABLE = false
+end
+
+module Lutaml
+  module Hal
+    module Cache
+      # Manages all cache operations with a clean, unified interface
+      class CacheManager
+        attr_reader :configuration, :cache_store
+
+        # @param config cache configuration (see CacheConfiguration.from_config)
+        # @param client [Lutaml::Hal::Client, nil] used to canonicalize relative
+        #   URLs so that a resource fetched by endpoint path and the same
+        #   resource realized from an absolute link href share a cache entry.
+        def initialize(config = nil, client: nil)
+          @client = client
+          @configuration = CacheConfiguration.from_config(config)
+          begin
+            @configuration.validate!
+          rescue ArgumentError => e
+            raise ArgumentError, "Invalid cache configuration: #{e.message}"
+          end
+          @cache_store = create_cache_store
+        end
+
+        # Get a cache entry by URL
+        def get(url)
+          return nil unless cache_store
+
+          key = cache_key(url)
+
+          if http_aware_cache?
+            get_from_http_cache(url, key)
+          else
+            get_from_basic_cache(key)
+          end
+        end
+
+        # Store a cache entry
+        def set(url, response, hal_resource)
+          return unless cache_store
+
+          entry = CacheEntry.create(url, response, hal_resource)
+          return unless entry.cacheable?
+
+          key = cache_key(url)
+
+          if http_aware_cache?
+            set_in_http_cache(key, entry, response)
+          else
+            set_in_basic_cache(key, entry)
+          end
+
+          entry
+        end
+
+        # Make a conditional request using cached metadata
+        def conditional_request_headers(url)
+          entry = get(url)
+          return {} unless entry&.revalidatable?
+
+          entry.conditional_headers
+        end
+
+        # Update cache entry after a 304 Not Modified response
+        def refresh_entry(url, response)
+          entry = get(url)
+          return unless entry
+
+          entry.refresh_metadata(response)
+          set_refreshed_entry(url, entry)
+        end
+
+        # Remove a specific cache entry
+        def invalidate(url)
+          return unless cache_store
+
+          key = cache_key(url)
+          cache_store.delete(key)
+        end
+
+        # Clear all cache entries
+        def clear
+          return unless cache_store
+
+          cache_store.clear
+        end
+
+        # Get cache statistics
+        def stats
+          return {} unless cache_store
+
+          if cache_store.respond_to?(:cache_info)
+            cache_store.cache_info
+          elsif cache_store.respond_to?(:stats)
+            cache_store.stats
+          else
+            {}
+          end
+        end
+
+        # Get cache information
+        def info
+          return nil unless cache_store
+
+          {
+            adapter_type: cache_store.class.name,
+            configuration: configuration,
+            current_size: cache_store.respond_to?(:size) ? cache_store.size : 'unknown',
+            stats: stats
+          }
+        end
+
+        # Check if cache is available and configured
+        def available?
+          !cache_store.nil?
+        end
+
+        # Check if using HTTP-aware cache
+        def http_aware_cache?
+          configuration.http_aware? && cache_store.respond_to?(:fetch)
+        end
+
+        private
+
+        def create_cache_store
+          # A persistent adapter (filesystem / sqlite) uses lutaml-store's
+          # CacheStore, which serializes each entry to JSON; CacheEntry knows how
+          # to round-trip itself (and rebuild its HAL model) for that path.
+          #
+          # The default in-memory adapter uses SimpleCacheStore, which keeps live
+          # CacheEntry objects so cache hits avoid any serialization cost.
+          #
+          # NOTE: Backing the HTTP-aware mode with lutaml-store's HttpCache
+          # response cache is deferred until realized models can be
+          # reconstructed from a cached response (requires the resource class);
+          # the create_http_cache / *_http_cache helpers remain as scaffolding.
+          if CACHE_STORE_AVAILABLE && persistent_adapter?
+            create_basic_cache
+          else
+            create_simple_cache
+          end
+        rescue StandardError => e
+          Lutaml::Hal.debug_log("Failed to create cache store: #{e.message}")
+          create_simple_cache
+        end
+
+        # Whether the configured adapter persists beyond the process.
+        def persistent_adapter?
+          %w[filesystem sqlite].include?(configuration.effective_adapter_type)
+        end
+
+        def create_http_cache
+          return nil unless defined?(::Lutaml::Store::HttpCache)
+
+          ::Lutaml::Store::HttpCache.new(configuration.http_cache_config)
+        end
+
+        def create_basic_cache
+          return nil unless defined?(::Lutaml::Store::CacheStore)
+
+          ::Lutaml::Store::CacheStore.new(configuration.basic_cache_config)
+        end
+
+        def create_simple_cache
+          SimpleCacheStore.new(configuration.effective_max_size)
+        end
+
+        def cache_key(url)
+          "hal_resource:#{canonical_url(url)}"
+        end
+
+        # Normalize a URL to an absolute form so that the same resource is
+        # cached under one key regardless of whether it was reached by a
+        # relative endpoint path (fetch) or an absolute link href (realize).
+        def canonical_url(url)
+          url = url.to_s
+          return url if url.start_with?('http')
+          return url unless @client&.api_url
+
+          "#{@client.api_url}#{url}"
+        end
+
+        def get_from_http_cache(url, key)
+          # HTTP cache handles conditional requests internally
+          cached_response = cache_store.get(key)
+          return nil unless cached_response
+
+          # Convert HTTP cache response back to CacheEntry
+          convert_http_response_to_entry(url, cached_response)
+        end
+
+        def get_from_basic_cache(key)
+          cached_data = cache_store.get(key)
+          return nil unless cached_data
+
+          # In-memory stores keep a live CacheEntry; persistent stores return a
+          # plain hash that we rebuild (with its HAL model) here.
+          case cached_data
+          when CacheEntry
+            cached_data.valid?(configuration.effective_ttl) ? cached_data : nil
+          when Hash
+            if CacheEntry.storage_format?(cached_data)
+              entry = CacheEntry.from_storage_h(cached_data)
+              entry&.valid?(configuration.effective_ttl) ? entry : nil
+            else
+              # Legacy in-memory hash format support
+              convert_legacy_cache_data(cached_data)
+            end
+          end
+        end
+
+        def set_in_http_cache(key, entry, response)
+          # Convert CacheEntry to HTTP cache format
+          http_response = convert_entry_to_http_response(entry, response)
+          cache_store.set(key, http_response)
+        end
+
+        def set_in_basic_cache(key, entry)
+          cache_store.set(key, entry)
+        end
+
+        def set_refreshed_entry(url, entry)
+          key = cache_key(url)
+
+          if http_aware_cache?
+            # For HTTP cache, we need to update the stored response
+            http_response = convert_entry_to_http_response(entry, nil)
+            cache_store.set(key, http_response)
+          else
+            cache_store.set(key, entry)
+          end
+        end
+
+        def convert_http_response_to_entry(url, http_response)
+          # Extract HAL resource and metadata from HTTP cache response
+          body = http_response[:body] || http_response['body']
+          headers = http_response[:headers] || http_response['headers'] || {}
+
+          # Parse the body back to get the HAL resource
+          # Note: This is a simplified conversion - in practice, we might need
+          # to store the HAL resource separately or use serialization
+          hal_resource = parse_hal_resource_from_body(body)
+
+          CacheEntry.new(
+            url: url,
+            cached_at: Time.now, # HTTP cache manages its own timestamps
+            metadata: CacheMetadata.from_response(headers),
+            hal_resource: hal_resource
+          )
+        end
+
+        def convert_entry_to_http_response(entry, _original_response)
+          {
+            status_code: entry.metadata&.status_code || 200,
+            headers: extract_headers_from_metadata(entry.metadata),
+            body: serialize_hal_resource(entry.hal_resource)
+          }
+        end
+
+        def convert_legacy_cache_data(cached_data)
+          # Support for legacy cache format
+          return nil unless cached_data[:realized_model] && cached_data[:cached_at]
+
+          CacheEntry.new(
+            url: cached_data[:url],
+            cached_at: cached_data[:cached_at],
+            metadata: create_metadata_from_legacy(cached_data),
+            hal_resource: cached_data[:realized_model]
+          )
+        end
+
+        def create_metadata_from_legacy(cached_data)
+          CacheMetadata.new(
+            etag: cached_data[:etag],
+            last_modified: cached_data[:last_modified],
+            status_code: 200
+          )
+        end
+
+        def extract_headers_from_metadata(metadata)
+          return {} unless metadata
+
+          {
+            'etag' => metadata.etag,
+            'last-modified' => metadata.last_modified,
+            'cache-control' => metadata.cache_control,
+            'expires' => metadata.expires,
+            'content-type' => metadata.content_type,
+            'date' => metadata.date,
+            'vary' => metadata.vary
+          }.compact
+        end
+
+        def parse_hal_resource_from_body(body)
+          # This is a placeholder - in practice, we might need to store
+          # the HAL resource class information to properly deserialize
+          case body
+          when String
+            JSON.parse(body)
+          else
+            body
+          end
+        rescue JSON::ParserError
+          body
+        end
+
+        def serialize_hal_resource(hal_resource)
+          # Serialize HAL resource for storage
+          case hal_resource
+          when ->(r) { r.respond_to?(:to_json) }
+            hal_resource.to_json
+          else
+            hal_resource.to_s
+          end
+        end
+      end
+    end
+  end
+end