lutaml-hal 0.2.1 → 0.2.3

data/lib/lutaml/hal/model_register.rb

@@ -1,37 +1,29 @@
 # frozen_string_literal: true
 
 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, :cache_manager
 
       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
+        @single_flight = SingleFlight.new
       end
 
-      # Register a model with its URL pattern and parameters
       def add_endpoint(id:, type:, url:, model:, parameters: [])
         @models ||= {}
 
         raise "Model with ID #{id} already registered" if @models[id]
 
-        # Validate all parameters
         parameters.each(&:validate!)
 
-        # Ensure path parameters in URL have corresponding parameter definitions
         validate_path_parameters(url, parameters)
 
-        # Check for duplicate endpoints
         if @models.values.any? do |m|
           m[:url] == url && m[:type] == type && parameters_match?(m[:parameters], parameters)
         end
@@ -47,7 +39,6 @@ module Lutaml
         }
       end
 
-      # Register an endpoint using block configuration syntax
       def register_endpoint(id, model, type: :index)
         config = EndpointConfiguration.new
         yield(config) if block_given?
@@ -63,149 +54,55 @@ module Lutaml
         )
       end
 
-      # Resolve and cast data to the appropriate model based on URL
       def fetch(endpoint_id, **params)
         endpoint = @models[endpoint_id] || raise("Unknown endpoint: #{endpoint_id}")
         raise 'Client not configured' unless client
 
-        # Process parameters through EndpointParameter objects
         processed_params = process_parameters(endpoint[:parameters], params)
 
-        # Build URL with path parameters
         url = build_url_with_path_params(endpoint[:url], processed_params[:path])
-
-        # 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 request_headers.any?
-                     client.get_with_headers(final_url, request_headers)
-                   else
-                     client.get(final_url)
-                   end
-
-        # 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)
+        cached = cached_endpoint_model(final_url)
+        return cached if cached
 
-          # Cache the realized model with metadata
-          @cache_manager&.set(final_url, response, realized_model)
+        coalesce(final_url) do
+          cached_endpoint_model(final_url) ||
+            fetch_uncached(endpoint, final_url, processed_params[:headers])
         end
-
-        # Store embedded data for later resolution
-        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
 
-        # 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
+        cached = cached_resolved_model(href)
+        return cached if cached
 
         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
+        coalesce(href) do
+          cached_resolved_model(href) || resolve_and_cast_uncached(href)
         end
-
-        # TODO: Merge full Link content into the resource?
-        response_with_link_details = response.to_h.merge({ 'href' => href })
-
-        href_path = href.sub(client.api_url, '')
-
-        model_class = find_matching_model_class(href_path)
-        raise LinkResolutionError, "Unregistered URL pattern: #{href}" unless model_class
-
-        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
 
-      # Recursively mark all models in the link with the register name
-      # This is used to ensure that all links in the model are registered
-      # with the same register name for consistent resolution
       def mark_model_links_with_register(inspecting_model)
         return unless inspecting_model.is_a?(Lutaml::Model::Serializable)
 
         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|
           attr_type = config.type
           next unless attr_type < Lutaml::Hal::Resource ||
                       attr_type < Lutaml::Hal::Link ||
                       attr_type < Lutaml::Hal::LinkSet
 
-          value = inspecting_model.send(key)
+          value = inspecting_model.public_send(key)
           next if value.nil?
 
-          # Handle both array and single values with the same logic
           values = value.is_a?(Array) ? value : [value]
           values.each do |item|
             mark_model_links_with_register(item)
 
-            # If this is a Link, set the parent resource for automatic embedded content detection
             item.parent_resource = inspecting_model if item.is_a?(Lutaml::Hal::Link)
           end
         end
@@ -213,7 +110,6 @@ module Lutaml
         inspecting_model
       end
 
-      # Cache management methods
       def cache_stats
         @cache_manager&.stats || {}
       end
@@ -226,17 +122,13 @@ module Lutaml
         @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]
@@ -245,7 +137,92 @@ module Lutaml
       private
 
       def debug_log(message)
-        puts "[Lutaml::Hal] DEBUG: #{message}" if ENV['DEBUG_API']
+        Hal.debug_log(message)
+      end
+
+      def coalesce(key, &block)
+        return block.call unless @cache_manager&.available?
+
+        @single_flight.run(key, &block)
+      end
+
+      def cached_endpoint_model(url)
+        return nil unless @cache_manager&.available?
+
+        entry = @cache_manager.get(url)
+        return nil unless entry
+
+        debug_log("Cache hit for fetch: #{url}")
+        model = entry.hal_resource
+        mark_model_links_with_register(model)
+        model
+      end
+
+      def fetch_uncached(endpoint, final_url, headers)
+        request_headers = headers.dup
+        if @cache_manager&.available?
+          conditional_headers = @cache_manager.conditional_request_headers(final_url)
+          request_headers.merge!(conditional_headers) if conditional_headers
+        end
+
+        response = if request_headers.any?
+                     client.get_with_headers(final_url, request_headers)
+                   else
+                     client.get(final_url)
+                   end
+
+        realized_model = build_model_from_response(response, final_url, endpoint[:model])
+
+        realized_model.embedded_data = response['_embedded'] if realized_model && response && response['_embedded']
+        mark_model_links_with_register(realized_model)
+        realized_model
+      end
+
+      def cached_resolved_model(href)
+        return nil unless @cache_manager&.available?
+
+        entry = @cache_manager.get(href)
+        return nil unless entry
+
+        debug_log("Cache hit for: #{href}")
+        model = entry.hal_resource
+        mark_model_links_with_register(model)
+        model
+      end
+
+      def resolve_and_cast_uncached(href)
+        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
+
+        href_path = href.sub(client.api_url, '')
+
+        model_class = find_matching_model_class(href_path)
+        raise LinkResolutionError, "Unregistered URL pattern: #{href}" unless model_class
+
+        debug_log("resolve_and_cast: resolved to model_class #{model_class}")
+
+        response_with_link_details = response.to_h.merge({ 'href' => href })
+        model = model_class.from_json(response_with_link_details.to_json)
+        mark_model_links_with_register(model)
+        @cache_manager&.set(href, response, model)
+        model
+      end
+
+      def build_model_from_response(response, url, model_class)
+        if response.is_a?(Hash) && response['status'] == 304
+          @cache_manager&.refresh_entry(url, response)
+          cached_entry = @cache_manager.get(url)
+          return cached_entry&.hal_resource
+        end
+
+        realized_model = model_class.from_json(response.to_json)
+        @cache_manager&.set(url, response, realized_model)
+        realized_model
       end
 
       def process_parameters(parameter_definitions, provided_params)
@@ -255,23 +232,18 @@ module Lutaml
           param_name = param_def.name.to_sym
           provided_value = provided_params[param_name]
 
-          # Check required parameters
           if param_def.required && provided_value.nil?
             raise ArgumentError, "Required parameter '#{param_def.name}' is missing"
           end
 
-          # Use default value if not provided
           value = provided_value || param_def.default_value
 
-          # Skip if still nil and not required
           next if value.nil?
 
-          # Validate parameter value
           unless param_def.validate_value(value)
             raise ArgumentError, "Invalid value for parameter '#{param_def.name}': #{value}"
           end
 
-          # Store in appropriate category
           case param_def.location
           when :path
             result[:path][param_def.name] = value
@@ -288,19 +260,15 @@ module Lutaml
       end
 
       def validate_path_parameters(url, parameters)
-        # Extract path parameter names from URL template
         url_params = url.scan(/\{([^}]+)\}/).flatten
 
-        # Find path parameters in parameter definitions
         path_params = parameters.select(&:path_parameter?).map(&:name)
 
-        # Check that all URL parameters have definitions
         missing_params = url_params - path_params
         unless missing_params.empty?
           raise ArgumentError, "URL contains undefined path parameters: #{missing_params.join(', ')}"
         end
 
-        # Check that all path parameter definitions are used in URL
         unused_params = path_params - url_params
         return if unused_params.empty?
 
@@ -324,12 +292,9 @@ module Lutaml
       end
 
       def build_url_with_query_params(base_url, query_params, params = nil)
-        # Handle both 2-argument and 3-argument calls for backward compatibility
         if params.nil?
-          # 2-argument call: query_params is the final query parameters
           final_query_params = query_params
         else
-          # 3-argument call: query_params is template, params contains values
           final_query_params = {}
           query_params.each do |key, template_value|
             if template_value.is_a?(String) && template_value.match?(/\{(\w+)\}/)
@@ -347,7 +312,6 @@ module Lutaml
         "#{base_url}?#{query_string}"
       end
 
-      # Interpolate path parameters in a URL template
       def interpolate_url(url_template, params)
         params.reduce(url_template) do |url, (key, value)|
           url.gsub("{#{key}}", value.to_s)
@@ -366,7 +330,6 @@ module Lutaml
         path_match_result = path_matches?(pattern_path, uri.path)
         return false unless path_match_result
 
-        # Check query parameters if any are defined
         query_params = parameters.select(&:query_parameter?)
         return true if query_params.empty?
 
@@ -388,21 +351,17 @@ module Lutaml
       end
 
       def query_params_match?(expected_params, actual_params)
-        # Query parameters should be optional unless marked as required
         expected_params.all? do |param_def|
           actual_value = actual_params[param_def.name]
 
-          # Required parameters must be present
           if param_def.required
             return false if actual_value.nil?
 
             return param_def.validate_value(actual_value)
           end
 
-          # Optional parameters are always considered matching if not present
           return true if actual_value.nil?
 
-          # If present, they must be valid
           param_def.validate_value(actual_value)
         end
       end
@@ -416,14 +375,10 @@ module Lutaml
         end
       end
 
-      # Match URL pattern (supports {param} templates)
       def pattern_match?(pattern, url)
         return false unless pattern && url
 
-        # Convert {param} to wildcards for matching
         pattern_with_wildcards = pattern.gsub(/\{[^}]+\}/, '*')
-        # Convert * wildcards to regex pattern - use [^/]+ to match path segments, not across slashes
-        # This ensures that {param} only matches a single path segment
         regex = Regexp.new("^#{pattern_with_wildcards.gsub('*', '[^/]+')}$")
 
         debug_log("pattern_match?: regex: #{regex.inspect}")

data/lib/lutaml/hal/page.rb

@@ -1,12 +1,7 @@
 # frozen_string_literal: true
 
-require_relative 'resource'
-
 module Lutaml
   module Hal
-    # Models the pagination of a collection of resources
-    # This class is used to represent the pagination information
-    # for a collection of resources in the HAL format.
     class Page < Resource
       attribute :page, :integer
       attribute :limit, :integer
@@ -23,153 +18,100 @@ module Lutaml
       def self.inherited(subclass)
         super
 
-        # Skip automatic link creation for anonymous classes (used in tests)
         return unless subclass.name
 
         page_links_symbols = %i[self next prev first last up]
         subclass_name = subclass.name
         subclass.class_eval do
-          # Define common page links
           page_links_symbols.each do |link_symbol|
             hal_link link_symbol, key: link_symbol.to_s, realize_class: subclass_name
           end
         end
       end
 
-      # Returns the next page of results, or nil if on the last page
-      #
-      # @return [Object, nil] The next page instance or nil
       def next
         return nil unless links.next
 
         links.next.realize
       end
 
-      # Returns the previous page of results, or nil if on the first page
-      #
-      # @return [Object, nil] The previous page instance or nil
       def prev
-        # If the API provides a prev link, use it
         return links.prev.realize if links.prev
 
-        # If we're on page 1, there's no previous page
         return nil if page <= 1
 
-        # Construct the previous page URL manually
         prev_page_url = construct_page_url(page - 1)
         return nil unless prev_page_url
 
-        # Use the HAL register to fetch the previous page
         register_name = _global_register_id
         return nil unless register_name
 
-        hal_register = Lutaml::Hal::GlobalRegister.instance.get(register_name)
+        hal_register = GlobalRegister.instance.get(register_name)
         return nil unless hal_register
 
         hal_register.resolve_and_cast(nil, prev_page_url)
       end
 
-      # Returns the first page of results
-      #
-      # @return [Object, nil] The first page instance or nil
       def first
         return nil unless links.first
 
         links.first.realize
       end
 
-      # Returns the last page of results
-      #
-      # @return [Object, nil] The last page instance or nil
       def last
         return nil unless links.last
 
         links.last.realize
       end
 
-      # Returns the total number of pages
-      #
-      # @return [Integer] The total number of pages
       def total_pages
         pages
       end
 
-      # Checks if there is a next page available
-      #
-      # @return [Boolean] true if next page exists, false otherwise
       def next?
         !links.next.nil?
       end
 
-      # Checks if there is a previous page available
-      #
-      # @return [Boolean] true if previous page exists, false otherwise
       def prev?
         !links.prev.nil?
       end
 
-      # Checks if there is a first page link available
-      #
-      # @return [Boolean] true if first page link exists, false otherwise
       def first?
         !links.first.nil?
       end
 
-      # Checks if there is a last page link available
-      #
-      # @return [Boolean] true if last page link exists, false otherwise
       def last?
         !links.last.nil?
       end
 
-      # Returns the next page link, or nil if on the last page
-      #
-      # @return [Object, nil] The next page link or nil
       def next_page
         links.next
       end
 
-      # Returns the previous page link, or nil if on the first page
-      #
-      # @return [Object, nil] The previous page link or nil
       def prev_page
         links.prev
       end
 
-      # Returns the first page link
-      #
-      # @return [Object, nil] The first page link or nil
       def first_page
         links.first
       end
 
-      # Returns the last page link
-      #
-      # @return [Object, nil] The last page link or nil
       def last_page
         links.last
       end
 
       private
 
-      # Constructs a URL for a specific page based on the current page's URL pattern
-      #
-      # @param target_page [Integer] The page number to construct URL for
-      # @return [String, nil] The constructed URL or nil if unable to construct
       def construct_page_url(target_page)
-        # Try to get a reference URL from next, first, or last links
         reference_url = links.next&.href || links.first&.href || links.last&.href
         return nil unless reference_url
 
-        # Parse the reference URL and modify the page parameter
         uri = URI.parse(reference_url)
         query_params = URI.decode_www_form(uri.query || '')
 
-        # Update the page parameter
         query_params = query_params.reject { |key, _| key == 'page' }
         query_params << ['page', target_page.to_s]
 
-        # Reconstruct the URL
         uri.query = URI.encode_www_form(query_params)
         uri.to_s
       end

data/lib/lutaml/hal/rate_limiter.rb

@@ -2,7 +2,6 @@
 
 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
@@ -16,10 +15,9 @@ module Lutaml
         @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
+        @enabled = options[:enabled] != false
       end
 
-      # Execute a block with rate limiting and retry logic
       def with_rate_limiting
         return yield unless @enabled
 
@@ -36,47 +34,27 @@ module Lutaml
         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
+        error.is_a?(TooManyRequestsError) || error.is_a?(ServerError)
       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
+        return retry_after_from_error(error) if error.is_a?(TooManyRequestsError) && retry_after_from_error(error)
 
-        # 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
@@ -86,20 +64,26 @@ module Lutaml
         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
+
+      private
+
+      def retry_after_from_error(error)
+        return nil unless error.is_a?(TooManyRequestsError)
+        return nil unless error.response
+
+        extract_retry_after(error.response)
+      end
     end
   end
 end