lutaml-hal 0.1.9 → 0.2.0

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Hal
+    # Rate limiter to handle API rate limiting with exponential backoff
+    class RateLimiter
+      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
+
+      def initialize(options = {})
+        @max_retries = options[:max_retries] || DEFAULT_MAX_RETRIES
+        @base_delay = options[:base_delay] || DEFAULT_BASE_DELAY
+        @max_delay = options[:max_delay] || DEFAULT_MAX_DELAY
+        @backoff_factor = options[:backoff_factor] || DEFAULT_BACKOFF_FACTOR
+        @enabled = options[:enabled] != false # Default to enabled unless explicitly disabled
+      end
+
+      # Execute a block with rate limiting and retry logic
+      def with_rate_limiting
+        return yield unless @enabled
+
+        attempt = 0
+        begin
+          attempt += 1
+          yield
+        rescue TooManyRequestsError, ServerError => e
+          raise unless should_retry?(e, attempt)
+
+          delay = calculate_delay(attempt, e)
+          sleep(delay)
+          retry
+        end
+      end
+
+      # Check if we should retry based on the error and attempt count
+      def should_retry?(error, attempt)
+        return false if attempt > @max_retries
+
+        case error
+        when TooManyRequestsError
+          true
+        when ServerError
+          # Always retry on server errors
+          true
+        else
+          false
+        end
+      end
+
+      # Calculate delay with exponential backoff
+      def calculate_delay(attempt, error = nil)
+        # Check for Retry-After header if it's a rate limit error
+        if error.is_a?(TooManyRequestsError) && error.respond_to?(:response) && error.response
+          retry_after = extract_retry_after(error.response)
+          return retry_after if retry_after
+        end
+
+        # Exponential backoff: base_delay * (backoff_factor ^ (attempt - 1))
+        delay = @base_delay * (@backoff_factor**(attempt - 1))
+
+        # Cap at max_delay
+        [delay, @max_delay].min
+      end
+
+      # Extract Retry-After header value
+      def extract_retry_after(response)
+        headers = response[:headers] || {}
+        retry_after = headers['retry-after'] || headers['Retry-After']
+        return nil unless retry_after
+
+        # Retry-After can be in seconds (integer) or HTTP date
+        if retry_after.match?(/^\d+$/)
+          retry_after.to_i
+        else
+          # Parse HTTP date and calculate seconds from now
+          begin
+            retry_time = Time.parse(retry_after)
+            [retry_time - Time.now, 0].max
+          rescue ArgumentError
+            nil
+          end
+        end
+      end
+
+      # Enable rate limiting
+      def enable!
+        @enabled = true
+      end
+
+      # Disable rate limiting
+      def disable!
+        @enabled = false
+      end
+
+      # Check if rate limiting is enabled
+      def enabled?
+        @enabled
+      end
+    end
+  end
+end

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.9'
+    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
@@ -15,6 +14,7 @@ end
 
 require_relative 'hal/version'
 require_relative 'hal/errors'
+require_relative 'hal/rate_limiter'
 require_relative 'hal/endpoint_parameter'
 require_relative 'hal/link'
 require_relative 'hal/link_set'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-hal
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.2.0
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-08 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
@@ -89,6 +108,7 @@ files:
 - lib/lutaml/hal/link_set_class_factory.rb
 - lib/lutaml/hal/model_register.rb
 - lib/lutaml/hal/page.rb
+- lib/lutaml/hal/rate_limiter.rb
 - lib/lutaml/hal/resource.rb
 - lib/lutaml/hal/type_resolver.rb
 - lib/lutaml/hal/version.rb