lutaml-hal 0.1.9 → 0.2.0

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

@@ -5,20 +5,20 @@ require 'faraday/follow_redirects'
 require 'json'
 require 'rainbow'
 require_relative 'errors'
+require_relative 'rate_limiter'
 
 module Lutaml
   module Hal
     # HAL Client for making HTTP requests to HAL APIs
     class Client
-      attr_reader :last_response, :api_url, :connection
+      attr_reader :last_response, :api_url, :connection, :rate_limiter
 
       def initialize(options = {})
         @api_url = options[:api_url] || raise(ArgumentError, 'api_url is required')
         @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)
       end
@@ -35,50 +35,45 @@ 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)
-
-        @last_response = @connection.get(url, params)
-
-        response = handle_response(@last_response, url)
-
-        @cache[cache_key] = response if @cache_enabled
-        response
+        @rate_limiter.with_rate_limiting do
+          @last_response = @connection.get(url, params)
+          handle_response(@last_response, url)
+        end
       rescue Faraday::ConnectionFailed => e
-        raise ConnectionError, "Connection failed: #{e.message}"
+        raise Lutaml::Hal::ConnectionError, "Connection failed: #{e.message}"
       rescue Faraday::TimeoutError => e
-        raise TimeoutError, "Request timed out: #{e.message}"
+        raise Lutaml::Hal::TimeoutError, "Request timed out: #{e.message}"
       rescue Faraday::ParsingError => e
-        raise ParsingError, "Response parsing error: #{e.message}"
+        raise Lutaml::Hal::ParsingError, "Response parsing error: #{e.message}"
       rescue Faraday::Adapter::Test::Stubs::NotFound => e
-        raise LinkResolutionError, "Resource not found: #{e.message}"
+        raise Lutaml::Hal::LinkResolutionError, "Resource not found: #{e.message}"
       end
 
       # 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)
-
-        @last_response = @connection.get(url) do |req|
-          headers.each { |key, value| req.headers[key] = value }
+        @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
-
-        response = handle_response(@last_response, url)
-
-        @cache[cache_key] = response if @cache_enabled
-        response
       rescue Faraday::ConnectionFailed => e
-        raise ConnectionError, "Connection failed: #{e.message}"
+        raise Lutaml::Hal::ConnectionError, "Connection failed: #{e.message}"
       rescue Faraday::TimeoutError => e
-        raise TimeoutError, "Request timed out: #{e.message}"
+        raise Lutaml::Hal::TimeoutError, "Request timed out: #{e.message}"
       rescue Faraday::ParsingError => e
-        raise ParsingError, "Response parsing error: #{e.message}"
+        raise Lutaml::Hal::ParsingError, "Response parsing error: #{e.message}"
       rescue Faraday::Adapter::Test::Stubs::NotFound => e
-        raise LinkResolutionError, "Resource not found: #{e.message}"
+        raise Lutaml::Hal::LinkResolutionError, "Resource not found: #{e.message}"
       end
 
       private
@@ -104,8 +99,16 @@ module Lutaml
           raise UnauthorizedError, response_message(response)
         when 404
           raise NotFoundError, response_message(response)
+        when 429
+          TooManyRequestsError.new(response_message(response)).tap do |error|
+            error.define_singleton_method(:response) { { status: response.status, headers: response.headers } }
+            raise error
+          end
         when 500..599
-          raise ServerError, response_message(response)
+          ServerError.new(response_message(response)).tap do |error|
+            error.define_singleton_method(:response) { { status: response.status, headers: response.headers } }
+            raise error
+          end
         else
           raise Error, response_message(response)
         end

data/lib/lutaml/hal/errors.rb

@@ -9,5 +9,8 @@ module Lutaml
     class ServerError < Error; end
     class LinkResolutionError < Error; end
     class ParsingError < Error; end
+    class ConnectionError < Error; end
+    class TimeoutError < Error; end
+    class TooManyRequestsError < Error; end
   end
 end

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