lutaml-hal 0.1.10 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f3ce9deb2f8607008c4b5d6950dd281a79bcba5856b03769c0a764dd0c95228
-  data.tar.gz: 0d8bd9e4a6f78dd18ce1c58288276d8e0334a48e4858fcbbfb694fd68dc5deb1
+  metadata.gz: a0879e2f05a3b6cfe0046dc4924ae0ba2bf5ef1925445e4469585c8ed77dd691
+  data.tar.gz: bc6e2d28adb425d5a29eab74c655bf4d721e81693a2109d4f5a61bb942d9cea4
 SHA512:
-  metadata.gz: d29f19722b4aa33f3404cd084394573cfa7dc5af3811fb0d42a5cd78319de4e1ff8e8e71b6de59eb23441b39ff0588a36c02ae35156eee99aa845e90929691b6
-  data.tar.gz: 4d00fc04f030bda2eec1558ea616f1c3533b8e7109c3224678a96de41b374f4ddadae7a9cf2fd6cbe807633e77a185e8ab893e944b98dc4433898b1cbb1571cc
+  metadata.gz: 9498991d51a700e261ccf411121797d88a5e205a1f2210ba8558615e69aacb89c61280fbf5454f579b18207de3ebfe5aedc3f99950f7e5bcd1ba6169770a3d31
+  data.tar.gz: 336e55e9740cef31a1e30f1208c212e41e9c643f8756394844bd14da89b221d34aabc62a4830e0b850d540c30feb31b765a02543a200086f39e417d36efce7ee

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

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Lutaml
+  module Hal
+    module Cache
+      # Represents HTTP response metadata from the request that created the HAL resource
+      class CacheMetadata < Lutaml::Model::Serializable
+        attribute :etag, :string
+        attribute :last_modified, :string
+        attribute :cache_control, :string
+        attribute :expires, :string
+        attribute :status_code, :integer
+        attribute :content_type, :string
+        attribute :date, :string
+        attribute :vary, :string
+
+        # Extract metadata from HTTP response headers
+        def self.from_response(response)
+          headers = extract_headers(response)
+
+          new(
+            etag: headers['etag'],
+            last_modified: headers['last-modified'],
+            cache_control: headers['cache-control'],
+            expires: headers['expires'],
+            status_code: extract_status_code(response),
+            content_type: headers['content-type'],
+            date: headers['date'],
+            vary: headers['vary']
+          )
+        end
+
+        # Generate conditional request headers for cache validation
+        def conditional_headers
+          headers = {}
+          headers['If-None-Match'] = etag if etag
+          headers['If-Modified-Since'] = last_modified if last_modified
+          headers
+        end
+
+        # Check if the metadata indicates the response is cacheable
+        def cacheable?
+          return false if cache_control&.include?('no-cache')
+          return false if cache_control&.include?('no-store')
+          return false if cache_control&.include?('private')
+
+          true
+        end
+
+        # Extract TTL from cache-control header
+        def max_age
+          return nil unless cache_control
+
+          match = cache_control.match(/max-age=(\d+)/)
+          match ? match[1].to_i : nil
+        end
+
+        # Check if the response can be revalidated with conditional requests
+        def revalidatable?
+          !etag.nil? && !etag.empty? || !last_modified.nil? && !last_modified.empty?
+        end
+
+        def self.extract_headers(response)
+          case response
+          when Hash
+            # Response is already a hash, extract headers directly
+            response.select { |k, _| k.is_a?(String) && k.match?(/^[a-z-]+$/) }
+          when ->(r) { r.respond_to?(:headers) }
+            # Response has headers method
+            response.headers.to_h
+          when ->(r) { r.respond_to?(:[]) }
+            # Response is hash-like, try to extract common headers
+            {
+              'etag' => response['etag'],
+              'last-modified' => response['last-modified'],
+              'cache-control' => response['cache-control'],
+              'expires' => response['expires'],
+              'content-type' => response['content-type'],
+              'date' => response['date'],
+              'vary' => response['vary']
+            }.compact
+          else
+            {}
+          end
+        end
+
+        def self.extract_status_code(response)
+          case response
+          when Hash
+            response['status'] || response[:status] || 200
+          when ->(r) { r.respond_to?(:status) }
+            response.status
+          when ->(r) { r.respond_to?(:code) }
+            response.code.to_i
+          else
+            200
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Hal
+    module Cache
+      # Simple in-memory cache store for testing and fallback scenarios
+      class SimpleCacheStore
+        attr_reader :max_size
+
+        def initialize(max_size = 100)
+          @max_size = max_size
+          @cache = {}
+          @access_order = []
+        end
+
+        def get(key)
+          return nil unless @cache.key?(key)
+
+          # Update access order for LRU
+          @access_order.delete(key)
+          @access_order.push(key)
+
+          @cache[key]
+        end
+
+        def set(key, value)
+          # Remove existing entry if present
+          if @cache.key?(key)
+            @access_order.delete(key)
+          elsif @cache.size >= @max_size
+            # Evict least recently used item
+            lru_key = @access_order.shift
+            @cache.delete(lru_key)
+          end
+
+          @cache[key] = value
+          @access_order.push(key)
+        end
+
+        def delete(key)
+          @access_order.delete(key)
+          @cache.delete(key)
+        end
+
+        def clear
+          @cache.clear
+          @access_order.clear
+        end
+
+        def size
+          @cache.size
+        end
+
+        def stats
+          {
+            size: @cache.size,
+            max_size: @max_size,
+            keys: @cache.keys
+          }
+        end
+
+        def cache_info
+          stats
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/hal/client.rb

@@ -18,8 +18,6 @@ module Lutaml
         @connection = options[:connection] || create_connection
         @params_default = options[:params_default] || {}
         @debug = options[:debug] || !ENV['DEBUG_API'].nil?
-        @cache = options[:cache] || {}
-        @cache_enabled = options[:cache_enabled] || false
         @rate_limiter = options[:rate_limiter] || RateLimiter.new(options[:rate_limiting] || {})
 
         @api_url = strip_api_url(@api_url)
@@ -37,19 +35,19 @@ module Lutaml
         get(path, params)
       end
 
+      # Get a resource by its full URL with custom headers (e.g. conditional
+      # request headers for cache revalidation)
+      def get_by_url_with_headers(url, headers = {})
+        path = strip_api_url(url)
+        get_with_headers(path, headers)
+      end
+
       # Make a GET request to the API
       def get(url, params = {})
-        cache_key = "#{url}:#{params.to_json}"
-
-        return @cache[cache_key] if @cache_enabled && @cache.key?(cache_key)
-
-        response = @rate_limiter.with_rate_limiting do
+        @rate_limiter.with_rate_limiting do
           @last_response = @connection.get(url, params)
           handle_response(@last_response, url)
         end
-
-        @cache[cache_key] = response if @cache_enabled
-        response
       rescue Faraday::ConnectionFailed => e
         raise Lutaml::Hal::ConnectionError, "Connection failed: #{e.message}"
       rescue Faraday::TimeoutError => e
@@ -62,19 +60,12 @@ module Lutaml
 
       # Make a GET request with custom headers
       def get_with_headers(url, headers = {})
-        cache_key = "#{url}:#{headers.to_json}"
-
-        return @cache[cache_key] if @cache_enabled && @cache.key?(cache_key)
-
-        response = @rate_limiter.with_rate_limiting do
+        @rate_limiter.with_rate_limiting do
           @last_response = @connection.get(url) do |req|
             headers.each { |key, value| req.headers[key] = value }
           end
           handle_response(@last_response, url)
         end
-
-        @cache[cache_key] = response if @cache_enabled
-        response
       rescue Faraday::ConnectionFailed => e
         raise Lutaml::Hal::ConnectionError, "Connection failed: #{e.message}"
       rescue Faraday::TimeoutError => e

data/lib/lutaml/hal/global_register.rb

@@ -43,6 +43,25 @@ module Lutaml
       def unregister(name)
         delete(name)
       end
+
+      # Cache management methods for all registered model registers
+      def clear_all_caches
+        @model_registers.each_value do |register|
+          register.clear_cache if register.respond_to?(:clear_cache)
+        end
+      end
+
+      def cache_stats
+        stats = {}
+        @model_registers.each do |name, register|
+          stats[name] = register.cache_info if register.respond_to?(:cache_info)
+        end
+        stats
+      end
+
+      def list_registers
+        @model_registers.keys
+      end
     end
   end
 end

data/lib/lutaml/hal/link.rb

@@ -9,7 +9,7 @@ module Lutaml
     class Link < Lutaml::Model::Serializable
       # This is the model register that has fetched the origin of this link, and
       # will be used to resolve unless overriden in resource#realize()
-      attr_accessor Hal::REGISTER_ID_ATTR_NAME.to_sym
+      attr_accessor :_global_register_id
 
       # Store reference to parent resource for automatic embedded content detection
       attr_accessor :parent_resource
@@ -27,17 +27,22 @@ module Lutaml
       # This method will use the global register according to the source of the Link object.
       # If the Link does not have a register, a register needs to be provided explicitly
       # via the `register:` parameter.
-      def realize(register: nil, parent_resource: nil)
+      def realize(register: nil, parent_resource: nil, force_refresh: false)
         # Use provided parent_resource or fall back to stored parent_resource
         effective_parent = parent_resource || @parent_resource
 
-        # First check if embedded content is available
-        if effective_parent && (embedded_content = check_embedded_content(effective_parent, register))
+        register = find_register(register)
+        raise "No register provided for link resolution (class: #{self.class}, href: #{href})" if register.nil?
+
+        # Priority 1: Check embedded content first (unless force_refresh)
+        if !force_refresh && effective_parent && (embedded_content = check_embedded_content(effective_parent, register))
+          # Cache embedded content too, so later lookups by href are served locally
+          register.cache_manager&.set(href, nil, embedded_content)
           return embedded_content
         end
 
-        register = find_register(register)
-        raise "No register provided for link resolution (class: #{self.class}, href: #{href})" if register.nil?
+        # Force refresh bypasses any cached entry for this href
+        register.cache_manager&.invalidate(href) if force_refresh
 
         Hal.debug_log "Resolving link href: #{href} using register"
         register.resolve_and_cast(self, href)
@@ -86,19 +91,19 @@ module Lutaml
 
         # Try to find the model class for this href
         href_path = href.sub(register.client.api_url, '') if register.client
-        model_class = register.send(:find_matching_model_class, href_path)
+        model_class = register.find_matching_model_class(href_path)
         return nil unless model_class
 
         # Create the resource from embedded data
-        resource = model_class.from_embedded(embedded_item, instance_variable_get("@#{Hal::REGISTER_ID_ATTR_NAME}"))
-        register.send(:mark_model_links_with_register, resource)
+        resource = model_class.from_embedded(embedded_item, _global_register_id)
+        register.mark_model_links_with_register(resource)
         resource
       end
 
       def find_register(explicit_register)
         return explicit_register if explicit_register
 
-        register_id = instance_variable_get("@#{Hal::REGISTER_ID_ATTR_NAME}")
+        register_id = _global_register_id
         return nil if register_id.nil?
 
         register = Lutaml::Hal::GlobalRegister.instance.get(register_id)

data/lib/lutaml/hal/link_set.rb

@@ -7,7 +7,7 @@ module Lutaml
   module Hal
     # HAL Link representation with realization capability
     class LinkSet < Lutaml::Model::Serializable
-      attr_accessor Hal::REGISTER_ID_ATTR_NAME.to_sym
+      attr_accessor :_global_register_id
     end
   end
 end

data/lib/lutaml/hal/model_register.rb

@@ -3,18 +3,20 @@
 require 'cgi'
 require_relative 'errors'
 require_relative 'endpoint_configuration'
+require_relative 'cache/cache_manager'
 
 module Lutaml
   module Hal
     # Register to map URL patterns to model classes with EndpointParameter support
     class ModelRegister
-      attr_accessor :models, :client, :register_name
+      attr_accessor :models, :client, :register_name, :cache_manager
 
-      def initialize(name:, client: nil)
+      def initialize(name:, client: nil, cache: nil)
         @register_name = name
         # If `client` is not set, it can be set later
         @client = client
         @models = {}
+        @cache_manager = Cache::CacheManager.new(cache, client: @client) if cache
       end
 
       # Register a model with its URL pattern and parameters
@@ -75,27 +77,89 @@ module Lutaml
         # Add query parameters
         final_url = build_url_with_query_params(url, processed_params[:query])
 
+        realized_model = nil
+
+        # Check cache first
+        if @cache_manager&.available?
+          cached_entry = @cache_manager.get(final_url)
+          if cached_entry
+            debug_log("Cache hit for fetch: #{final_url}")
+            realized_model = cached_entry.hal_resource
+            # Return cached model directly if valid
+            mark_model_links_with_register(realized_model)
+            return realized_model
+          end
+        end
+
+        # Make request if not cached
+        # Add conditional headers if we have cached metadata
+        request_headers = processed_params[:headers].dup
+        if @cache_manager&.available?
+          conditional_headers = @cache_manager.conditional_request_headers(final_url)
+          request_headers.merge!(conditional_headers) if conditional_headers
+        end
+
         # Make request with headers
-        response = if processed_params[:headers].any?
-                     client.get_with_headers(final_url, processed_params[:headers])
+        response = if request_headers.any?
+                     client.get_with_headers(final_url, request_headers)
                    else
                      client.get(final_url)
                    end
 
-        realized_model = endpoint[:model].from_json(response.to_json)
+        # Handle 304 Not Modified
+        if response.respond_to?(:status) && response.status == 304
+          @cache_manager&.refresh_entry(final_url, response)
+          cached_entry = @cache_manager.get(final_url)
+          realized_model = cached_entry.hal_resource if cached_entry
+        else
+          # Create model from response
+          realized_model = endpoint[:model].from_json(response.to_json)
+
+          # Cache the realized model with metadata
+          @cache_manager&.set(final_url, response, realized_model)
+        end
 
         # Store embedded data for later resolution
-        realized_model.instance_variable_set(:@_embedded, response['_embedded']) if response['_embedded']
+        realized_model.embedded_data = response['_embedded'] if realized_model && response && response['_embedded']
 
         mark_model_links_with_register(realized_model)
+
         realized_model
       end
 
       def resolve_and_cast(link, href)
         raise 'Client not configured' unless client
 
-        Hal.debug_log("resolve_and_cast: link #{link}, href #{href}")
-        response = client.get_by_url(href)
+        # Check cache first
+        if @cache_manager&.available?
+          cached_entry = @cache_manager.get(href)
+          if cached_entry
+            debug_log("Cache hit for: #{href}")
+            cached_model = cached_entry.hal_resource
+            # A model rebuilt from a persistent cache needs to be (re)marked so
+            # its links can be realized against this register.
+            mark_model_links_with_register(cached_model)
+            return cached_model
+          end
+        end
+
+        debug_log("resolve_and_cast: link #{link}, href #{href}")
+
+        # Add conditional headers if we have cached metadata
+        conditional_headers = @cache_manager&.conditional_request_headers(href) || {}
+
+        response = if conditional_headers.any?
+                     client.get_by_url_with_headers(href, conditional_headers)
+                   else
+                     client.get_by_url(href)
+                   end
+
+        # Handle 304 Not Modified
+        if response.respond_to?(:status) && response.status == 304
+          @cache_manager&.refresh_entry(href, response)
+          cached_entry = @cache_manager.get(href)
+          return cached_entry.hal_resource if cached_entry
+        end
 
         # TODO: Merge full Link content into the resource?
         response_with_link_details = response.to_h.merge({ 'href' => href })
@@ -105,12 +169,16 @@ module Lutaml
         model_class = find_matching_model_class(href_path)
         raise LinkResolutionError, "Unregistered URL pattern: #{href}" unless model_class
 
-        Hal.debug_log("resolve_and_cast: resolved to model_class #{model_class}")
-        Hal.debug_log("resolve_and_cast: response: #{response.inspect}")
-        Hal.debug_log("resolve_and_cast: amended: #{response_with_link_details}")
+        debug_log("resolve_and_cast: resolved to model_class #{model_class}")
+        debug_log("resolve_and_cast: response: #{response.inspect}")
+        debug_log("resolve_and_cast: amended: #{response_with_link_details}")
 
         model = model_class.from_json(response_with_link_details.to_json)
         mark_model_links_with_register(model)
+
+        # Cache the realized model with metadata
+        @cache_manager&.set(href, response, model)
+
         model
       end
 
@@ -120,7 +188,7 @@ module Lutaml
       def mark_model_links_with_register(inspecting_model)
         return unless inspecting_model.is_a?(Lutaml::Model::Serializable)
 
-        inspecting_model.instance_variable_set("@#{Hal::REGISTER_ID_ATTR_NAME}", @register_name)
+        inspecting_model._global_register_id = @register_name
 
         # Recursively process model attributes to mark links with this register
         inspecting_model.class.attributes.each_pair do |key, config|
@@ -145,8 +213,41 @@ module Lutaml
         inspecting_model
       end
 
+      # Cache management methods
+      def cache_stats
+        @cache_manager&.stats || {}
+      end
+
+      def clear_cache
+        @cache_manager&.clear
+      end
+
+      def cache_info
+        @cache_manager&.info
+      end
+
+      # Find the registered model class whose URL pattern matches the given href.
+      # Public so that Link#realize can resolve embedded resources.
+      def find_matching_model_class(href)
+        # Find all matching patterns and select the most specific one (longest pattern)
+        matching_models = @models.values.select do |model_data|
+          matches_url_with_params?(model_data, href)
+        end
+
+        return nil if matching_models.empty?
+
+        # Sort by pattern length (descending) to get the most specific match first
+        result = matching_models.max_by { |model_data| model_data[:url].length }
+
+        result[:model]
+      end
+
       private
 
+      def debug_log(message)
+        puts "[Lutaml::Hal] DEBUG: #{message}" if ENV['DEBUG_API']
+      end
+
       def process_parameters(parameter_definitions, provided_params)
         result = { path: {}, query: {}, headers: {}, cookies: {} }
 
@@ -253,20 +354,6 @@ module Lutaml
         end
       end
 
-      def find_matching_model_class(href)
-        # Find all matching patterns and select the most specific one (longest pattern)
-        matching_models = @models.values.select do |model_data|
-          matches_url_with_params?(model_data, href)
-        end
-
-        return nil if matching_models.empty?
-
-        # Sort by pattern length (descending) to get the most specific match first
-        result = matching_models.max_by { |model_data| model_data[:url].length }
-
-        result[:model]
-      end
-
       def matches_url_with_params?(model_data, href)
         pattern = model_data[:url]
         parameters = model_data[:parameters]
@@ -339,12 +426,12 @@ module Lutaml
         # This ensures that {param} only matches a single path segment
         regex = Regexp.new("^#{pattern_with_wildcards.gsub('*', '[^/]+')}$")
 
-        Hal.debug_log("pattern_match?: regex: #{regex.inspect}")
-        Hal.debug_log("pattern_match?: href to match #{url}")
-        Hal.debug_log("pattern_match?: pattern to match #{pattern_with_wildcards}")
+        debug_log("pattern_match?: regex: #{regex.inspect}")
+        debug_log("pattern_match?: href to match #{url}")
+        debug_log("pattern_match?: pattern to match #{pattern_with_wildcards}")
 
         matches = regex.match?(url)
-        Hal.debug_log("pattern_match?: matches = #{matches}")
+        debug_log("pattern_match?: matches = #{matches}")
 
         matches
       end

data/lib/lutaml/hal/page.rb

@@ -60,7 +60,7 @@ module Lutaml
         return nil unless prev_page_url
 
         # Use the HAL register to fetch the previous page
-        register_name = instance_variable_get("@#{Lutaml::Hal::REGISTER_ID_ATTR_NAME}")
+        register_name = _global_register_id
         return nil unless register_name
 
         hal_register = Lutaml::Hal::GlobalRegister.instance.get(register_name)

data/lib/lutaml/hal/rate_limiter.rb

@@ -4,10 +4,10 @@ module Lutaml
   module Hal
     # Rate limiter to handle API rate limiting with exponential backoff
     class RateLimiter
-      DEFAULT_MAX_RETRIES = 3
-      DEFAULT_BASE_DELAY = 1.0
-      DEFAULT_MAX_DELAY = 60.0
-      DEFAULT_BACKOFF_FACTOR = 2.0
+      DEFAULT_MAX_RETRIES = 5
+      DEFAULT_BASE_DELAY = 0.05
+      DEFAULT_MAX_DELAY = 5.0
+      DEFAULT_BACKOFF_FACTOR = 1.5
 
       attr_reader :max_retries, :base_delay, :max_delay, :backoff_factor
 

data/lib/lutaml/hal/resource.rb

@@ -11,12 +11,11 @@ module Lutaml
     class Resource < Lutaml::Model::Serializable
       # This is the model register that has fetched this resource, and
       # will be used to resolve links unless overriden in resource#realize()
-      attr_accessor Hal::REGISTER_ID_ATTR_NAME.to_sym
+      attr_accessor :_global_register_id
 
-      # Access embedded data if available
-      def embedded_data
-        @_embedded
-      end
+      # Embedded resources from the HAL `_embedded` section, retained so that
+      # links can be realized from already-fetched content.
+      attr_accessor :embedded_data
 
       # Check if embedded data exists for a given key
       def has_embedded?(key)
@@ -31,7 +30,7 @@ module Lutaml
       # Create a resource instance from embedded JSON data
       def self.from_embedded(json_data, register_name = nil)
         instance = from_json(json_data.to_json)
-        instance.instance_variable_set("@#{Hal::REGISTER_ID_ATTR_NAME}", register_name) if register_name
+        instance._global_register_id = register_name if register_name
         instance
       end
 

data/lib/lutaml/hal/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Hal
-    VERSION = '0.1.10'
+    VERSION = '0.2.0'
   end
 end

data/lib/lutaml/hal.rb

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 
 require 'lutaml/model'
+require 'lutaml/store'
 
 module Lutaml
   # HAL implementation for Lutaml
   module Hal
-    REGISTER_ID_ATTR_NAME = '_global_register_id'
-
     def self.debug_log(message)
       puts "[Lutaml::Hal] DEBUG: #{message}" if ENV['DEBUG_API']
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-hal
 version: !ruby/object:Gem::Version
-  version: 0.1.10
+  version: 0.2.0
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-09 00:00:00.000000000 Z
+date: 2026-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: lutaml-store
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.1
 - !ruby/object:Gem::Dependency
   name: rainbow
   requirement: !ruby/object:Gem::Requirement
@@ -78,6 +92,11 @@ files:
 - README.adoc
 - lib/lutaml-hal.rb
 - lib/lutaml/hal.rb
+- lib/lutaml/hal/cache/cache_configuration.rb
+- lib/lutaml/hal/cache/cache_entry.rb
+- lib/lutaml/hal/cache/cache_manager.rb
+- lib/lutaml/hal/cache/cache_metadata.rb
+- lib/lutaml/hal/cache/simple_cache_store.rb
 - lib/lutaml/hal/client.rb
 - lib/lutaml/hal/endpoint_configuration.rb
 - lib/lutaml/hal/endpoint_parameter.rb