lutaml-hal 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 754c6e7a5a61e4b96398c511a8e5f0e7dd721dab154272b5de4ce580fc204f71
-  data.tar.gz: fa3c07d2deed3ddf2605da05a375412eb2222273c46c7f3338982b5b99e1fefb
+  metadata.gz: 4f3ce9deb2f8607008c4b5d6950dd281a79bcba5856b03769c0a764dd0c95228
+  data.tar.gz: 0d8bd9e4a6f78dd18ce1c58288276d8e0334a48e4858fcbbfb694fd68dc5deb1
 SHA512:
-  metadata.gz: 6aff2792a51f0467f5dd470de4656f8630046bbbe741120dbf54b75cf3120b57c8771a1e300b2790be2cc5bca53beebdda86a28085c3b2e8025c993d49ffc3ea
-  data.tar.gz: 62886f1267ac6119302234a750258882d9a4e4fce0ad24ad9b6c1b2a7ea89876df8cffe33def528aed4a95d33a69f9e0157f8b84c45c23eff36b5f4a47942a01
+  metadata.gz: d29f19722b4aa33f3404cd084394573cfa7dc5af3811fb0d42a5cd78319de4e1ff8e8e71b6de59eb23441b39ff0588a36c02ae35156eee99aa845e90929691b6
+  data.tar.gz: 4d00fc04f030bda2eec1558ea616f1c3533b8e7109c3224678a96de41b374f4ddadae7a9cf2fd6cbe807633e77a185e8ab893e944b98dc4433898b1cbb1571cc

data/README.adoc

@@ -31,6 +31,7 @@ APIs.
 * Integration with the `lutaml-model` serialization framework
 * Error handling and response validation for API interactions
 * Comprehensive embed support for reducing HTTP requests and improving performance
+* Built-in rate limiting with exponential backoff and retry logic
 
 == Installation
 
@@ -103,30 +104,36 @@ puts category.name
 
 == Documentation
 
-=== Comprehensive guides
+=== Detailed topics
 
-For detailed documentation, see these comprehensive guides:
+For detailed documentation, see these topics:
 
-* **link:docs/getting-started-guide.adoc[Getting started guide]** - Step-by-step
-  tutorial for your first HAL API client (15 minutes)
+link:docs/getting-started.adoc[Getting started]::
+Get started with your HAL API client (15 minutes)
 
-* **link:docs/data-definition-guide.adoc[Data definition guide]** - Complete
-  reference for defining HAL resources, model registers, and API endpoints
+link:docs/data-definition.adoc[Data definition]::
+Full reference to define HAL resources, model registers, and API endpoints
 
-* **link:docs/runtime-usage-guide.adoc[Runtime usage guide]** - Patterns for
-  fetching resources, navigating links, and handling pagination
+link:docs/runtime-usage.adoc[Runtime usage]::
+Patterns to fetch resources, navigate links, and handle pagination
 
-* **link:docs/hal-links-reference.adoc[HAL links reference]** - Advanced
-  configuration and customization of HAL links
+link:docs/hal-links-reference.adoc[HAL links reference]::
+Advanced configuration of HAL links
 
-* **link:docs/pagination-guide.adoc[Pagination guide]** - Working with
-  paginated APIs and large datasets
+link:docs/pagination.adoc[Pagination]::
+Working with paginated APIs and large datasets
 
-* **link:docs/complex-path-patterns.adoc[Complex path patterns]** - Advanced
-  URL patterns and path matching examples
+link:docs/complex-path-patterns.adoc[Complex path patterns]::
+Advanced URL patterns and path matching examples
 
-* **link:docs/embedded-resources.adoc[Embedded resources]** - Implementing and
-using embedded resources in HAL APIs
+link:docs/embedded-resources.adoc[Embedded resources]::
+Implementing and using embedded resources in HAL APIs with automatic link realization
+
+link:docs/rate-limiting.adoc[Rate limiting]::
+Configuring and using built-in rate limiting functionality
+
+link:docs/error-handling.adoc[Error handling]::
+Understanding and handling different types of errors when working with HAL APIs
 
 
 === Architecture overview
@@ -213,20 +220,6 @@ register.add_endpoint(
 For complex path pattern examples, see
 link:docs/complex-path-patterns.adoc[Complex Path Patterns].
 
-== Error handling
-
-The library provides structured error handling:
-
-[source,ruby]
-----
-begin
-  product = register.fetch(:product_resource, id: '123')
-rescue Lutaml::Hal::Errors::NotFoundError => e
-  puts "Product not found: #{e.message}"
-rescue Lutaml::Hal::Errors::ApiError => e
-  puts "API Error: #{e.message}"
-end
-----
 
 == Contributing
 

data/lib/lutaml/hal/client.rb

@@ -5,12 +5,13 @@ 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')
@@ -19,6 +20,7 @@ module Lutaml
         @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
@@ -41,20 +43,21 @@ module Lutaml
 
         return @cache[cache_key] if @cache_enabled && @cache.key?(cache_key)
 
-        @last_response = @connection.get(url, params)
-
-        response = handle_response(@last_response, url)
+        response = @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 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
@@ -63,22 +66,23 @@ module Lutaml
 
         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 }
+        response = @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 +108,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/link.rb

@@ -11,6 +11,9 @@ module Lutaml
       # will be used to resolve unless overriden in resource#realize()
       attr_accessor Hal::REGISTER_ID_ATTR_NAME.to_sym
 
+      # Store reference to parent resource for automatic embedded content detection
+      attr_accessor :parent_resource
+
       attribute :href, :string
       attribute :title, :string
       attribute :name, :string
@@ -25,8 +28,11 @@ module Lutaml
       # 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)
+        # 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 parent_resource && (embedded_content = check_embedded_content(parent_resource, register))
+        if effective_parent && (embedded_content = check_embedded_content(effective_parent, register))
           return embedded_content
         end
 

data/lib/lutaml/hal/model_register.rb

@@ -134,7 +134,12 @@ module Lutaml
 
           # Handle both array and single values with the same logic
           values = value.is_a?(Array) ? value : [value]
-          values.each { |item| mark_model_links_with_register(item) }
+          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
 
         inspecting_model

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 = 3
+      DEFAULT_BASE_DELAY = 1.0
+      DEFAULT_MAX_DELAY = 60.0
+      DEFAULT_BACKOFF_FACTOR = 2.0
+
+      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/version.rb

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

data/lib/lutaml/hal.rb

@@ -15,6 +15,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.8
+  version: 0.1.10
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-08 00:00:00.000000000 Z
+date: 2025-07-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -89,6 +89,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