lutaml-hal 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5860a26a1d8b235f8138e37fe835c3f0de0d4cc065f99b33da9ed17c0cb0a8cf
-  data.tar.gz: e558941f569c2d8d55ac62c66924a06a7445438281c261e060471bdf2d8c9f5f
+  metadata.gz: b352439d0153969cc07791e9e8e471b99fd364f20028c28b49f9b97ee35bfd1b
+  data.tar.gz: 4f20e2db09645e6ff127bc5c22e9ba96d8391a4b5158777b5e7224fe741572ab
 SHA512:
-  metadata.gz: a3cda001e3ebb066cf62e8aa54fbec2a41ae93a173a056919da2151cf8f28fcba143352ad2dc287d478c7365fa3e087abc1757770264acc05a4be925378072d7
-  data.tar.gz: d34fd6af3af5e78d1b223f04fa9f1e9e71ff524b2ac9425935d6bd5e07e4d8fa10a2c255c063c70026388d5f2406a05a41cde1492482cd66a911fb1fe80fb623
+  metadata.gz: 6856e9d221dfdff0fa1df27953848db6983056391a90a146909ac692905cb225b95f780f46923b475df1b92aa8daf26d1e27fff7eadf6f9c6bb772ca7bc01647
+  data.tar.gz: f52e887598db0c96c8060d643b4763873cb226a3c540e5018e6fe2537fc9d0b79886fef5c04edf9146b878c78f95c19fdd6bcc70d054f6369c86177c26ebce02

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

@@ -5,23 +5,16 @@ 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?
 
@@ -35,7 +28,6 @@ module Lutaml
           end
         end
 
-        # Validate the configuration
         def validate!
           validate_adapter_type!
           validate_ttl!
@@ -43,80 +35,48 @@ module Lutaml
           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 },
+        def to_cache_store_config
+          base = {
+            adapter: { type: effective_adapter_type.to_sym },
             default_ttl: effective_ttl,
             max_size: effective_max_size
           }
+          options = adapter_config&.dig(:options) || adapter_config&.dig('options')
+          base[:adapter_options] = options if options
+          base
         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)
+          adapter_type = config_value(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']
+            ttl: config_value(config, :ttl),
+            max_size: config_value(config, :max_size)
           )
         end
+        private_class_method :from_hash
 
         def self.from_simple_config(config)
           new(adapter_type: config.to_s)
         end
+        private_class_method :from_simple_config
 
         def self.extract_adapter_type(adapter_info)
           case adapter_info
@@ -127,6 +87,12 @@ module Lutaml
             adapter_info.to_s
           end
         end
+        private_class_method :extract_adapter_type
+
+        def self.config_value(config, key)
+          config[key] || config[key.to_s]
+        end
+        private_class_method :config_value
 
         def validate_adapter_type!
           valid_types = %w[memory filesystem sqlite]
@@ -155,30 +121,6 @@ module Lutaml
 
           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

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

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 
 require 'json'
-require_relative 'cache_metadata'
+require 'time'
 
 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
 
@@ -17,9 +16,6 @@ module Lutaml
           @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,
@@ -30,21 +26,15 @@ module Lutaml
           }
         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(
@@ -63,7 +53,6 @@ module Lutaml
           nil
         end
 
-        # Create a cache entry from a URL, response, and realized HAL resource
         def self.create(url, response, hal_resource)
           new(
             url: url,
@@ -73,7 +62,6 @@ module Lutaml
           )
         end
 
-        # Check if the cache entry is still valid based on TTL
         def valid?(default_ttl)
           return false unless cached_at
 
@@ -84,35 +72,29 @@ module Lutaml
           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
 
@@ -120,17 +102,14 @@ module Lutaml
           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
+          return false if valid?(Float::INFINITY)
 
           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

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

@@ -1,31 +1,13 @@
 # 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
+require 'lutaml/store'
 
 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)
@@ -37,20 +19,16 @@ module Lutaml
           @cache_store = create_cache_store
         end
 
-        # Get a cache entry by URL
         def get(url)
           return nil unless cache_store
 
           key = cache_key(url)
+          raw = cache_store.get(key)
+          return nil unless raw
 
-          if http_aware_cache?
-            get_from_http_cache(url, key)
-          else
-            get_from_basic_cache(key)
-          end
+          deserialize_entry(raw)
         end
 
-        # Store a cache entry
         def set(url, response, hal_resource)
           return unless cache_store
 
@@ -58,17 +36,10 @@ module Lutaml
           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
-
+          cache_store.set(key, entry.to_storage_h)
           entry
         end
 
-        # Make a conditional request using cached metadata
         def conditional_request_headers(url)
           entry = get(url)
           return {} unless entry&.revalidatable?
@@ -76,16 +47,15 @@ module Lutaml
           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)
+          key = cache_key(url)
+          cache_store.set(key, entry.to_storage_h)
         end
 
-        # Remove a specific cache entry
         def invalidate(url)
           return unless cache_store
 
@@ -93,100 +63,47 @@ module Lutaml
           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
+          cache_store.cache_info
         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',
+            current_size: cache_store.size,
             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
+          store_config = @configuration.to_cache_store_config
+          ::Lutaml::Store::CacheStore.new(store_config)
         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)
+          Hal.debug_log("Failed to create cache store: #{e.message}")
+          nil
         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')
@@ -195,137 +112,12 @@ module Lutaml
           "#{@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
+        def deserialize_entry(raw)
+          case raw
           when CacheEntry
-            cached_data.valid?(configuration.effective_ttl) ? cached_data : nil
+            raw
           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
+            CacheEntry.from_storage_h(raw) if CacheEntry.storage_format?(raw)
           end
         end
       end