lutaml-hal 0.2.3 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b352439d0153969cc07791e9e8e471b99fd364f20028c28b49f9b97ee35bfd1b
-  data.tar.gz: 4f20e2db09645e6ff127bc5c22e9ba96d8391a4b5158777b5e7224fe741572ab
+  metadata.gz: 59361d090cefb4d2158d64a1bef3f644d29de1d84c577f6744e0dd415c734be1
+  data.tar.gz: 4240bf652f5de8fd2a173406ecd7bd3fd139efffacc6d4e49fddcce37f3a2d24
 SHA512:
-  metadata.gz: 6856e9d221dfdff0fa1df27953848db6983056391a90a146909ac692905cb225b95f780f46923b475df1b92aa8daf26d1e27fff7eadf6f9c6bb772ca7bc01647
-  data.tar.gz: f52e887598db0c96c8060d643b4763873cb226a3c540e5018e6fe2537fc9d0b79886fef5c04edf9146b878c78f95c19fdd6bcc70d054f6369c86177c26ebce02
+  metadata.gz: 92335a8f9826cc136d92611184bc1e562728eb48039c09f29c1ebaa5adfb01963520c544137e666a9c5a7d8e38a125a93728f16b4fec96eca8331ae9c69c31cb
+  data.tar.gz: fca046d05353c72e7d10e667028183f20fb5ce6dc3e6f705b0905efe2b2ff9bae3860a87d35eda8e563aeef1465237a9d8732828635098ea1c006c346093d0d5

data/lib/lutaml/hal/client.rb

@@ -8,7 +8,12 @@ require 'rainbow'
 module Lutaml
   module Hal
     class Client
-      attr_reader :last_response, :api_url, :connection, :rate_limiter
+      # Thread-variable (not Thread#[], which is fiber-local) holding this
+      # thread's most recent [client, response] pair. One fixed key, one entry
+      # per thread: nothing accumulates as clients come and go.
+      LAST_RESPONSE_KEY = :lutaml_hal_last_response
+
+      attr_reader :api_url, :connection, :rate_limiter
 
       def initialize(options = {})
         @api_url = options[:api_url] || raise(ArgumentError, 'api_url is required')
@@ -19,6 +24,24 @@ module Lutaml
         @api_url = strip_api_url(@api_url)
       end
 
+      # The raw Faraday response from the most recent request issued by *this*
+      # thread, or nil if this thread has issued none through this client.
+      # Instance-wide state would be unsafe: a single Client is routinely shared
+      # across threads, and one thread must never observe another's response.
+      #
+      # Scoped to the thread's single most recent request rather than kept
+      # per-client, so a thread retains exactly one response no matter how many
+      # clients it uses. A thread that then issues a request through a different
+      # client reports nil here.
+      #
+      # Note that under SingleFlight coalescing, follower threads issue no
+      # request of their own, so their last_response is unchanged by the
+      # coalesced fetch.
+      def last_response
+        client, response = Thread.current.thread_variable_get(LAST_RESPONSE_KEY)
+        response if client.equal?(self)
+      end
+
       def strip_api_url(url)
         url.sub(%r{/\Z}, '')
       end
@@ -34,27 +57,28 @@ module Lutaml
       end
 
       def get(url, params = {})
-        @rate_limiter.with_rate_limiting do
-          @last_response = @connection.get(url, params)
-          handle_response(@last_response, url)
+        with_faraday_errors do
+          @rate_limiter.with_rate_limiting do
+            handle_response(record_response(@connection.get(url, params)), url)
+          end
         end
-      rescue Faraday::ConnectionFailed => e
-        raise ConnectionError, "Connection failed: #{e.message}"
-      rescue Faraday::TimeoutError => e
-        raise TimeoutError, "Request timed out: #{e.message}"
-      rescue Faraday::ParsingError => e
-        raise ParsingError, "Response parsing error: #{e.message}"
-      rescue Faraday::Adapter::Test::Stubs::NotFound => e
-        raise LinkResolutionError, "Resource not found: #{e.message}"
       end
 
       def get_with_headers(url, headers = {})
-        @rate_limiter.with_rate_limiting do
-          @last_response = @connection.get(url) do |req|
-            headers.each { |key, value| req.headers[key] = value }
+        with_faraday_errors do
+          @rate_limiter.with_rate_limiting do
+            response = @connection.get(url) do |req|
+              headers.each { |key, value| req.headers[key] = value }
+            end
+            handle_response(record_response(response), url)
           end
-          handle_response(@last_response, url)
         end
+      end
+
+      private
+
+      def with_faraday_errors
+        yield
       rescue Faraday::ConnectionFailed => e
         raise ConnectionError, "Connection failed: #{e.message}"
       rescue Faraday::TimeoutError => e
@@ -65,7 +89,13 @@ module Lutaml
         raise LinkResolutionError, "Resource not found: #{e.message}"
       end
 
-      private
+      # Publish the response on #last_response and return it, so callers keep
+      # working with their own local reference rather than re-reading shared
+      # state that another thread may already have replaced.
+      def record_response(response)
+        Thread.current.thread_variable_set(LAST_RESPONSE_KEY, [self, response])
+        response
+      end
 
       def create_connection
         Faraday.new(url: @api_url) do |conn|
@@ -86,23 +116,25 @@ module Lutaml
           raise BadRequestError, response_message(response)
         when 401
           raise UnauthorizedError, response_message(response)
+        when 403
+          raise ForbiddenError.new(response_message(response), response: response_context(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
+          raise TooManyRequestsError.new(response_message(response), response: response_context(response))
         when 500..599
-          ServerError.new(response_message(response)).tap do |error|
-            error.define_singleton_method(:response) { { status: response.status, headers: response.headers } }
-            raise error
-          end
+          raise ServerError.new(response_message(response), response: response_context(response))
         else
           raise Error, response_message(response)
         end
       end
 
+      # HTTP context attached to retryable errors so callers (and RateLimiter)
+      # can read Retry-After without holding on to the Faraday response.
+      def response_context(response)
+        { status: response.status, headers: response.headers }
+      end
+
       def debug_api_log(response, url)
         if defined?(Rainbow)
           puts Rainbow("\n===== Lutaml::Hal DEBUG: HAL API REQUEST =====").blue

data/lib/lutaml/hal/errors.rb

@@ -2,10 +2,21 @@
 
 module Lutaml
   module Hal
-    class Error < StandardError; end
+    class Error < StandardError
+      # HTTP context for errors mapped from a response status, as
+      # `{ status: Integer, headers: Hash }`. Nil for locally raised errors.
+      attr_reader :response
+
+      def initialize(message = nil, response: nil)
+        message.nil? ? super() : super(message)
+        @response = response
+      end
+    end
+
     class NotFoundError < Error; end
     class UnauthorizedError < Error; end
     class BadRequestError < Error; end
+    class ForbiddenError < Error; end
     class ServerError < Error; end
     class LinkResolutionError < Error; end
     class ParsingError < Error; end

data/lib/lutaml/hal/rate_limiter.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'time' # Time.parse, used by #extract_retry_after for HTTP-date values
+
 module Lutaml
   module Hal
     class RateLimiter
@@ -7,15 +9,25 @@ module Lutaml
       DEFAULT_BASE_DELAY = 0.05
       DEFAULT_MAX_DELAY = 5.0
       DEFAULT_BACKOFF_FACTOR = 1.5
+      # Separate, far larger cap for server-instructed waits. max_delay bounds
+      # our own guesswork; when the server states how long to wait, honouring it
+      # is the point -- capping a `Retry-After: 60` at a 5s backoff cap would
+      # hammer an API that explicitly asked us to back off. This cap exists only
+      # to stop an absurd value (`Retry-After: 3600`) parking a worker thread.
+      DEFAULT_MAX_RETRY_AFTER = 300.0
 
-      attr_reader :max_retries, :base_delay, :max_delay, :backoff_factor
+      attr_reader :max_retries, :base_delay, :max_delay, :backoff_factor, :max_retry_after
 
       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
+        @max_retry_after = options[:max_retry_after] || DEFAULT_MAX_RETRY_AFTER
         @enabled = options[:enabled] != false
+        # Off by default: 403 usually means "not allowed", not "slow down".
+        # Some APIs (historically the W3C API) use it as a rate-limit signal.
+        @retry_on_forbidden = options[:retry_on_forbidden] ? true : false
       end
 
       def with_rate_limiting
@@ -25,7 +37,7 @@ module Lutaml
         begin
           attempt += 1
           yield
-        rescue TooManyRequestsError, ServerError => e
+        rescue TooManyRequestsError, ServerError, ForbiddenError => e
           raise unless should_retry?(e, attempt)
 
           delay = calculate_delay(attempt, e)
@@ -36,12 +48,22 @@ module Lutaml
 
       def should_retry?(error, attempt)
         return false if attempt > @max_retries
+        return @retry_on_forbidden if error.is_a?(ForbiddenError)
 
         error.is_a?(TooManyRequestsError) || error.is_a?(ServerError)
       end
 
+      def retry_on_forbidden?
+        @retry_on_forbidden
+      end
+
       def calculate_delay(attempt, error = nil)
-        return retry_after_from_error(error) if error.is_a?(TooManyRequestsError) && retry_after_from_error(error)
+        # Retry-After is bounded at both ends: capped at max_retry_after so an
+        # absurd value can't park the thread, floored at base_delay because a
+        # `Retry-After: 0` (or a date already in the past) would otherwise
+        # sleep(0) and burn the whole retry budget in a busy loop.
+        retry_after = retry_after_from_error(error)
+        return retry_after.clamp(@base_delay, @max_retry_after) if retry_after
 
         delay = @base_delay * (@backoff_factor**(attempt - 1))
         [delay, @max_delay].min
@@ -79,7 +101,7 @@ module Lutaml
       private
 
       def retry_after_from_error(error)
-        return nil unless error.is_a?(TooManyRequestsError)
+        return nil unless error.is_a?(TooManyRequestsError) || error.is_a?(ForbiddenError)
         return nil unless error.response
 
         extract_retry_after(error.response)

data/lib/lutaml/hal/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Hal
-    VERSION = '0.2.3'
+    VERSION = '0.2.5'
   end
 end

data/lib/lutaml/hal.rb

@@ -16,6 +16,7 @@ module Lutaml
     autoload :NotFoundError, 'lutaml/hal/errors'
     autoload :UnauthorizedError, 'lutaml/hal/errors'
     autoload :BadRequestError, 'lutaml/hal/errors'
+    autoload :ForbiddenError, 'lutaml/hal/errors'
     autoload :ServerError, 'lutaml/hal/errors'
     autoload :LinkResolutionError, 'lutaml/hal/errors'
     autoload :ParsingError, 'lutaml/hal/errors'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-hal
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.5
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-08 00:00:00.000000000 Z
+date: 2026-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.1
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.1
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: rainbow
   requirement: !ruby/object:Gem::Requirement