lutaml-hal 0.1.10 → 0.2.1

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,83 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Hal
+    module Cache
+      # Simple in-memory cache store for testing and fallback scenarios.
+      #
+      # Thread-safe: a single mutex guards the cache and its LRU bookkeeping so
+      # it can back the register cache when consumers realize links from many
+      # threads (e.g. a parallel fetcher).
+      class SimpleCacheStore
+        attr_reader :max_size
+
+        def initialize(max_size = 100)
+          @max_size = max_size
+          @cache = {}
+          @access_order = []
+          @mutex = Mutex.new
+        end
+
+        def get(key)
+          @mutex.synchronize do
+            return nil unless @cache.key?(key)
+
+            # Update access order for LRU
+            @access_order.delete(key)
+            @access_order.push(key)
+
+            @cache[key]
+          end
+        end
+
+        def set(key, value)
+          @mutex.synchronize do
+            # 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
+        end
+
+        def delete(key)
+          @mutex.synchronize do
+            @access_order.delete(key)
+            @cache.delete(key)
+          end
+        end
+
+        def clear
+          @mutex.synchronize do
+            @cache.clear
+            @access_order.clear
+          end
+        end
+
+        def size
+          @mutex.synchronize { @cache.size }
+        end
+
+        def stats
+          @mutex.synchronize do
+            {
+              size: @cache.size,
+              max_size: @max_size,
+              keys: @cache.keys
+            }
+          end
+        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.1'
   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