philiprehberger-http_client 0.11.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5438d46ef6a929e6272a230dc19c64a50ff6c183b96cbec03b6379f1dec476df
-  data.tar.gz: 256673e0413568cfaafc4a4fbbba15d0fbdffe60c0aca1d22090909c2db24a16
+  metadata.gz: a22fdf41ff535b768c6ac9783ad358b8367cf7aa9f666368cd098c30ef36231c
+  data.tar.gz: 62bb80048febfa5be44bfef001cd082bf447866a2a4d5afe76717e2e829e9423
 SHA512:
-  metadata.gz: fb20cd1a0bd5020afc0e519d6b02ae078fa19266ae829f201baf607b8b4b8dce1e1bdd73d80110739dbd04b2d8bcdc9e235b64ad9ed528be0efcecb9a8e52e54
-  data.tar.gz: 81e1cdcef88ee36d4a585bd8ae6f190e61641ae0f7575b416dca40abbe389aadc4bdd7cf4a632a3778bb580333422cdbf7338f1afb268a225ee8c26767609f8e
+  metadata.gz: 75d9a2a474f77b8358ea76fb131acdcb2f11c9fdc31b46d4dc65ec6364139de9e6fd66b085f65b294afde442b0e9b12a73c1775cbc5c7ad2f3275544bb5d58ae
+  data.tar.gz: f728d0e5d12a7642e098c75fca3af7ef75aff526329982678e224c4917cd921164170319db294ad33ba1ca3bd923f39b442082bbb17f8a1fd8140873125325ce

data/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-10-30
+
+### Added
+- `Response#raise_for_status!` — returns `self` on 2xx/3xx responses and raises `HttpError` (with `.response`) on 4xx/5xx, enabling chained calls like `client.get(path).raise_for_status!.json`
+- `Response#content_type` — media type from the `Content-Type` header without parameters (e.g. `"application/json"`), `nil` if absent
+- `Response#content_length` — `Content-Length` header as an Integer, `nil` if absent or invalid
+
+### Changed
+- Aligned `.gitignore` with the standard gem template
+- Aligned CI workflow with the standard template (`ruby` matrix key, glob gemspec in build/push)
+
+## [0.12.0] - 2026-07-15
+
+### Added
+- `Retry-After` response header support on retryable status codes — honors both delta-seconds and HTTP-date forms as the retry delay, clamped to a 300s ceiling (falls back to the configured backoff when absent)
+- `retry_jitter:` option (default `false`) — spreads retries with full jitter over the computed delay
+- `retry_max_delay:` option (default `30.0`) — caps any single backoff delay so exponential growth cannot run away
+- `cache_max_entries:` option (default `1000`) and `Cache#refresh` — the response cache is now bounded with least-recently-used eviction, preventing unbounded growth in long-lived clients
+
+### Fixed
+- 304 Not Modified revalidation now returns the stored response (with body) and refreshes its freshness/ETag/Last-Modified, instead of returning the empty-body 304 and dropping the cached content
+
 ## [0.11.1] - 2026-06-14
 
 ### Changed
@@ -200,7 +222,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Response wrapper with `ok?` and `json` convenience methods
 - Zero dependencies — built on Ruby stdlib `net/http`
 
-[Unreleased]: https://github.com/philiprehberger/rb-http-client/compare/v0.11.1...HEAD
+[Unreleased]: https://github.com/philiprehberger/rb-http-client/compare/v0.13.0...HEAD
+[0.13.0]: https://github.com/philiprehberger/rb-http-client/compare/v0.12.0...v0.13.0
+[0.12.0]: https://github.com/philiprehberger/rb-http-client/compare/v0.11.1...v0.12.0
 [0.11.1]: https://github.com/philiprehberger/rb-http-client/compare/v0.11.0...v0.11.1
 [0.11.0]: https://github.com/philiprehberger/rb-http-client/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/philiprehberger/rb-http-client/compare/v0.9.1...v0.10.0

data/README.md

@@ -202,6 +202,12 @@ client = Philiprehberger::HttpClient.new(
 )
 ```
 
+When retrying on a status code, a `Retry-After` response header is honored as the
+delay before the next attempt. Both delta-seconds (`Retry-After: 120`) and HTTP-date
+(`Retry-After: Wed, 21 Oct 2026 07:28:00 GMT`) forms are supported. The value is
+clamped to a sane ceiling (300s) to guard against hostile headers, and the configured
+backoff is used whenever the header is absent.
+
 ### Exponential backoff
 
 ```ruby
@@ -214,6 +220,22 @@ client = Philiprehberger::HttpClient.new(
 # Delay sequence: 1s, 2s, 4s
 ```
 
+Computed delays are capped at `retry_max_delay` (default 30s) so exponential growth
+never runs away. Enable `retry_jitter` to spread retries with full jitter — each delay
+becomes a random value between `0` and the capped delay, which helps avoid thundering-herd
+retries against a recovering server:
+
+```ruby
+client = Philiprehberger::HttpClient.new(
+  base_url: "https://api.example.com",
+  retries: 5,
+  retry_delay: 1,
+  retry_backoff: :exponential,
+  retry_jitter: true,   # randomize each delay (default: false)
+  retry_max_delay: 20    # cap any single delay at 20s (default: 30.0)
+)
+```
+
 ### Cookie jar
 
 Enable automatic cookie handling across requests:
@@ -372,12 +394,25 @@ response = client.get("/data")
 response = client.get("/data")
 
 # Conditional requests: sends If-None-Match / If-Modified-Since
-# when cache entry has ETag or Last-Modified
+# when cache entry has ETag or Last-Modified. A 304 Not Modified
+# refreshes the stored entry and returns its body (not the empty 304).
 
 # Flush the cache
 client.clear_cache!
 ```
 
+The cache is bounded — once it holds `cache_max_entries` responses (default 1000),
+the least recently used entry is evicted on the next insert, so a long-lived client
+cannot grow the cache without limit:
+
+```ruby
+client = Philiprehberger::HttpClient.new(
+  base_url: "https://api.example.com",
+  cache: true,
+  cache_max_entries: 500   # LRU eviction beyond 500 entries (default: 1000)
+)
+```
+
 ### Request logging callback
 
 Add an `on_request` callback for observability — it receives the HTTP method, URI, response status, and duration (in seconds) after each request completes:
@@ -432,6 +467,25 @@ response.header("etag")           # works for any casing
 response.header("X-Missing")      # => nil
 ```
 
+### Content metadata and status checks
+
+`Response#content_type` returns the media type without parameters, `Response#content_length` parses the `Content-Length` header, and `Response#raise_for_status!` raises `HttpError` on 4xx/5xx while returning the response otherwise:
+
+```ruby
+response = client.get("/report")
+
+response.content_type    # => "application/json" (from "application/json; charset=utf-8")
+response.content_length  # => 2048, or nil if the header is absent
+
+data = client.get("/users").raise_for_status!.json
+
+begin
+  client.get("/missing").raise_for_status!
+rescue Philiprehberger::HttpClient::HttpError => e
+  e.response.status  # => 404
+end
+```
+
 ## API
 
 ### `Philiprehberger::HttpClient.new(**options)`
@@ -447,7 +501,9 @@ response.header("X-Missing")      # => nil
 | `retries`     | Integer | `0`     | Retry attempts on network errors     |
 | `retry_delay` | Numeric | `1`     | Seconds between retries              |
 | `retry_backoff` | Symbol | `:fixed` | Backoff strategy — `:fixed` or `:exponential` |
-| `retry_on_status` | Array | `nil` | HTTP status codes to retry on (e.g., `[429, 503]`) |
+| `retry_jitter` | Boolean | `false` | Randomize each backoff delay with full jitter |
+| `retry_max_delay` | Numeric | `30.0` | Upper bound (seconds) on any computed backoff delay |
+| `retry_on_status` | Array | `nil` | HTTP status codes to retry on (e.g., `[429, 503]`); honors `Retry-After` |
 | `cookies` | Boolean | `false` | Enable cookie jar for automatic cookie handling |
 | `proxy` | String | `nil` | Proxy URL (also reads `HTTP_PROXY`/`HTTPS_PROXY` env vars) |
 | `follow_redirects` | Boolean | `true` | Follow 3xx redirects automatically |
@@ -455,6 +511,7 @@ response.header("X-Missing")      # => nil
 | `pool` | Boolean | `false` | Enable connection pooling |
 | `pool_size` | Integer | `5` | Maximum connections per host:port |
 | `cache` | Boolean | `false` | Enable in-memory GET response caching |
+| `cache_max_entries` | Integer | `1000` | Maximum cached entries before least-recently-used eviction |
 | `on_request` | Proc | `nil` | Callback invoked after each request with `(method, uri, status, duration)` |
 
 ### Methods
@@ -507,6 +564,9 @@ response.header("X-Missing")      # => nil
 | `server_error?` | Boolean | Returns true for 5xx status codes |
 | `json`    | Hash    | Parsed JSON body                |
 | `json?`   | Boolean | `true` if `Content-Type` is `application/json` or `+json` suffix |
+| `content_type` | String | Media type without parameters (e.g. `"application/json"`), `nil` if absent |
+| `content_length` | Integer | `Content-Length` header as an Integer, `nil` if absent or invalid |
+| `raise_for_status!` | Response | Returns `self` on 1xx-3xx, raises `HttpError` (with `.response`) on 4xx/5xx |
 | `streaming?` | Boolean | `true` if response was streamed |
 | `metrics` | Metrics | Request timing breakdown (total_time, first_byte_time, etc.) |
 | `redirects` | Array | Redirect chain URLs (empty if no redirects) |

data/lib/philiprehberger/http_client/cache.rb

@@ -8,21 +8,41 @@ module Philiprehberger
     # Respects Cache-Control headers (max-age, no-cache, no-store) and supports
     # conditional requests via ETag and Last-Modified headers.
     #
+    # The store is bounded: once it holds +max_entries+ entries, the least
+    # recently used entry is evicted on the next insert. Both {#lookup} hits
+    # and {#refresh} mark an entry as recently used.
+    #
     # @example
-    #   cache = Cache.new
+    #   cache = Cache.new(max_entries: 500)
     #   cache.store(uri, response)
     #   cached = cache.lookup(uri)
     class Cache
       # A cached entry with metadata for expiration and conditional requests.
       CacheEntry = Struct.new(:response, :stored_at, :max_age, :etag, :last_modified, keyword_init: true)
 
-      def initialize
+      # Default upper bound on the number of cached entries.
+      DEFAULT_MAX_ENTRIES = 1000
+
+      # @param max_entries [Integer] maximum number of entries retained before
+      #   least-recently-used eviction kicks in (default: 1000)
+      def initialize(max_entries: DEFAULT_MAX_ENTRIES)
+        unless max_entries.is_a?(Integer) && max_entries.positive?
+          raise ArgumentError, "max_entries must be a positive Integer, got #{max_entries.inspect}"
+        end
+
         @monitor = Monitor.new
         @store = {}
+        @max_entries = max_entries
       end
 
+      # Maximum number of entries retained before LRU eviction.
+      #
+      # @return [Integer]
+      attr_reader :max_entries
+
       # Look up a cached response for the given URI.
-      # Returns nil if not cached or expired.
+      # Returns nil if not cached or expired. A hit marks the entry as the most
+      # recently used.
       #
       # @param uri [URI] the request URI
       # @return [Response, nil] the cached response or nil
@@ -37,6 +57,7 @@ module Philiprehberger
             @store.delete(key) unless entry.etag || entry.last_modified
             nil
           else
+            touch(key, entry)
             entry.response
           end
         end
@@ -53,7 +74,8 @@ module Philiprehberger
       end
 
       # Store a response in the cache.
-      # Respects Cache-Control: no-store (does not cache).
+      # Respects Cache-Control: no-store (does not cache). Evicts the least
+      # recently used entry when the store exceeds +max_entries+.
       #
       # @param uri [URI] the request URI
       # @param response [Response] the response to cache
@@ -72,7 +94,39 @@ module Philiprehberger
           last_modified: response.headers['last-modified']
         )
 
-        @monitor.synchronize { @store[key] = entry }
+        @monitor.synchronize do
+          @store.delete(key)
+          @store[key] = entry
+          evict_lru
+        end
+      end
+
+      # Refresh a stored entry after a 304 Not Modified revalidation.
+      #
+      # Resets +stored_at+ and applies any fresh +max-age+, +ETag+, or
+      # +Last-Modified+ carried by the 304 response, then returns the stored
+      # response (with its body) so the caller can serve cached content.
+      # Marks the entry as most recently used. Returns nil when no entry exists
+      # for the URI.
+      #
+      # @param uri [URI] the request URI
+      # @param response [Response] the 304 Not Modified response
+      # @return [Response, nil] the stored response, or nil if not cached
+      def refresh(uri, response)
+        key = cache_key(uri)
+        cc = parse_cache_control(response)
+
+        @monitor.synchronize do
+          entry = @store[key]
+          return nil unless entry
+
+          entry.stored_at = now
+          entry.max_age = cc[:max_age] if cc[:max_age]
+          entry.etag = response.headers['etag'] if response.headers['etag']
+          entry.last_modified = response.headers['last-modified'] if response.headers['last-modified']
+          touch(key, entry)
+          entry.response
+        end
       end
 
       # Remove all entries from the cache.
@@ -95,6 +149,19 @@ module Philiprehberger
         uri.to_s
       end
 
+      # Move an existing key to the end of the insertion order, marking it as
+      # the most recently used. Must be called while holding the monitor.
+      def touch(key, entry)
+        @store.delete(key)
+        @store[key] = entry
+      end
+
+      # Evict least-recently-used entries (front of the insertion order) until
+      # the store is within +max_entries+. Must be called while holding the monitor.
+      def evict_lru
+        @store.shift while @store.size > @max_entries
+      end
+
       def expired?(entry)
         return false unless entry.max_age
 

data/lib/philiprehberger/http_client/client.rb

@@ -20,6 +20,8 @@ module Philiprehberger
       # @param retries [Integer] Number of retry attempts on network errors
       # @param retry_delay [Numeric] Seconds to wait between retries
       # @param retry_backoff [Symbol] Backoff strategy (:fixed or :exponential)
+      # @param retry_jitter [Boolean] Randomize backoff delay with full jitter (default: false)
+      # @param retry_max_delay [Numeric] Upper bound (seconds) on any computed backoff delay (default: 30.0)
       # @param cookies [Boolean] Enable cookie jar for automatic cookie handling
       # @param proxy [String, nil] Proxy URL (e.g., "http://proxy:8080"), also reads HTTP_PROXY/HTTPS_PROXY
       # @param follow_redirects [Boolean] Follow 3xx redirects (default: true)
@@ -27,6 +29,7 @@ module Philiprehberger
       # @param pool [Boolean, nil] Enable connection pooling (default: false)
       # @param pool_size [Integer, nil] Maximum connections per host:port (default: 5)
       # @param cache [Boolean, nil] Enable response caching for GET requests (default: false)
+      # @param cache_max_entries [Integer, nil] Maximum cached entries before LRU eviction (default: 1000)
       # @param on_request [Proc, nil] Callback invoked after each request with (method, uri, status, duration)
       def initialize(base_url:, headers: {}, timeout: 30, **opts)
         @base_url = base_url.chomp('/')
@@ -252,6 +255,12 @@ module Philiprehberger
         unless %i[fixed exponential].include?(@retry_backoff)
           raise ConfigurationError, "retry_backoff must be :fixed or :exponential, got #{@retry_backoff.inspect}"
         end
+        unless [true, false].include?(@retry_jitter)
+          raise ConfigurationError, "retry_jitter must be true or false, got #{@retry_jitter.inspect}"
+        end
+        unless @retry_max_delay.is_a?(Numeric) && !@retry_max_delay.negative?
+          raise ConfigurationError, "retry_max_delay must be a non-negative Numeric, got #{@retry_max_delay.inspect}"
+        end
         return if @retry_on_status.nil?
         return if @retry_on_status.respond_to?(:include?)
 
@@ -262,6 +271,8 @@ module Philiprehberger
         @retries = opts.fetch(:retries, 0)
         @retry_delay = opts.fetch(:retry_delay, 1)
         @retry_backoff = opts.fetch(:retry_backoff, :fixed)
+        @retry_jitter = opts.fetch(:retry_jitter, false)
+        @retry_max_delay = opts.fetch(:retry_max_delay, 30.0)
         @retry_on_status = opts[:retry_on_status]
       end
 
@@ -285,7 +296,17 @@ module Philiprehberger
       end
 
       def assign_cache_opts(opts)
-        @cache = opts[:cache] ? Cache.new : nil
+        unless opts[:cache]
+          @cache = nil
+          return
+        end
+
+        max_entries = opts.fetch(:cache_max_entries, Cache::DEFAULT_MAX_ENTRIES)
+        unless max_entries.is_a?(Integer) && max_entries.positive?
+          raise ConfigurationError, "cache_max_entries must be a positive Integer, got #{max_entries.inspect}"
+        end
+
+        @cache = Cache.new(max_entries: max_entries)
       end
 
       def lookup_cache(uri, extra_headers)

data/lib/philiprehberger/http_client/connection.rb

@@ -75,8 +75,8 @@ module Philiprehberger
         run_interceptors(context)
         response = perform_with_retries(uri, request, **timeout_opts, &)
         response = follow_redirect_chain(response, request, **timeout_opts) if should_follow_redirect?(response)
+        response = handle_cacheable_get(uri, request, response)
         response.instance_variable_set(:@request_id, request_id)
-        cache_response(uri, response) if @cache && request.is_a?(Net::HTTP::Get)
         context[:response] = response
         run_interceptors(context)
         notify_on_request(context[:request][:method], uri, response)
@@ -242,6 +242,24 @@ module Philiprehberger
         @pool.checkin(uri, http)
       end
 
+      # Cache-aware post-processing for GET responses. On a 304 Not Modified
+      # for a URI we hold a cache entry for, the stored (bodied) response is
+      # refreshed and returned in place of the bodyless 304; otherwise the
+      # response is stored (when cacheable) and returned unchanged.
+      def handle_cacheable_get(uri, request, response)
+        return response unless @cache && request.is_a?(Net::HTTP::Get)
+
+        if response.status == 304
+          refreshed = @cache.refresh(uri, response)
+          return refreshed if refreshed
+
+          return response
+        end
+
+        cache_response(uri, response)
+        response
+      end
+
       def cache_response(uri, response)
         return unless response.ok?
         return if response.streaming?

data/lib/philiprehberger/http_client/response.rb

@@ -83,6 +83,45 @@ module Philiprehberger
         primary == 'application/json' || primary.end_with?('+json')
       end
 
+      # Returns the media type from the `Content-Type` header without any
+      # parameters (e.g. `"application/json"` for
+      # `"application/json; charset=utf-8"`). The value is downcased.
+      #
+      # @return [String, nil] the media type, or `nil` if the header is absent or blank
+      def content_type
+        value = header('content-type')
+        return nil if value.nil?
+
+        media_type = value.to_s.split(';').first.to_s.strip.downcase
+        media_type.empty? ? nil : media_type
+      end
+
+      # Returns the `Content-Length` header as an Integer.
+      #
+      # @return [Integer, nil] the declared body length, or `nil` if the header
+      #   is absent or not a valid non-negative integer
+      def content_length
+        value = header('content-length')
+        return nil if value.nil?
+
+        length = Integer(value.to_s.strip, 10, exception: false)
+        length&.negative? ? nil : length
+      end
+
+      # Raises {HttpError} if the response has a 4xx or 5xx status code.
+      # Returns `self` otherwise so the call can be chained.
+      #
+      # @example
+      #   data = client.get('/users').raise_for_status!.json
+      #
+      # @return [self]
+      # @raise [HttpError] if the status code is 400 or greater
+      def raise_for_status!
+        raise HttpError, self if status >= 400
+
+        self
+      end
+
       # Returns request timing metrics (nil if not available).
       #
       # @return [Metrics, nil]

data/lib/philiprehberger/http_client/retries.rb

@@ -1,9 +1,15 @@
 # frozen_string_literal: true
 
+require 'time'
+
 module Philiprehberger
   module HttpClient
     # Retry logic extracted from Connection to keep module length manageable.
     module Retries
+      # Absolute ceiling (seconds) applied to a server-supplied Retry-After
+      # value, guarding against pathological or hostile headers.
+      RETRY_AFTER_CEILING = 300.0
+
       private
 
       def perform_with_retries(uri, request, **timeout_opts, &block)
@@ -12,7 +18,7 @@ module Philiprehberger
           response = perform_request(uri, request, **timeout_opts, &block)
           return response unless retry_on_status?(response.status, attempts)
 
-          wait_and_retry(attempts += 1)
+          wait_and_retry(attempts += 1, response)
         rescue *Connection::TIMEOUT_ERRORS => e
           handle_retry_error(attempts += 1, TimeoutError, e.message)
         rescue *Connection::NETWORK_ERRORS => e
@@ -30,13 +36,66 @@ module Philiprehberger
         @retry_on_status&.include?(status) && attempts < @retries
       end
 
-      def wait_and_retry(attempt)
-        sleep(retry_delay_for(attempt))
+      def wait_and_retry(attempt, response = nil)
+        sleep(retry_delay_for(attempt, response))
+      end
+
+      # Compute the delay before the next retry. A server-supplied Retry-After
+      # header (delta-seconds or HTTP-date) takes precedence and is clamped to
+      # {RETRY_AFTER_CEILING}; otherwise the configured backoff is used, capped
+      # at +retry_max_delay+ and optionally randomized with full jitter.
+      def retry_delay_for(attempt, response = nil)
+        retry_after = response ? retry_after_delay(response) : nil
+        return [retry_after, RETRY_AFTER_CEILING].min if retry_after
+
+        apply_jitter(cap_delay(backoff_delay(attempt)))
       end
 
-      def retry_delay_for(attempt)
+      def backoff_delay(attempt)
         @retry_backoff == :exponential ? @retry_delay * (2**(attempt - 1)) : @retry_delay
       end
+
+      def cap_delay(delay)
+        @retry_max_delay ? [delay, @retry_max_delay].min : delay
+      end
+
+      def apply_jitter(delay)
+        return delay unless @retry_jitter
+
+        jitter_rand * delay
+      end
+
+      # Random float in the half-open range [0.0, 1.0) used for full-jitter
+      # backoff. Extracted so it can be stubbed in tests.
+      #
+      # @return [Float]
+      def jitter_rand
+        rand
+      end
+
+      # Parse a Retry-After response header into a delay in seconds.
+      # Supports both delta-seconds (e.g. "120") and HTTP-date
+      # (e.g. "Wed, 21 Oct 2026 07:28:00 GMT") forms. Returns nil when the
+      # header is absent or unparseable.
+      #
+      # @param response [Response]
+      # @return [Float, Integer, nil]
+      def retry_after_delay(response)
+        value = response.headers['retry-after']
+        return nil unless value
+
+        value = value.to_s.strip
+        return value.to_i if value.match?(/\A\d+\z/)
+
+        http_date_delay(value)
+      end
+
+      def http_date_delay(value)
+        delay = Time.httpdate(value) - Time.now
+        delay.negative? ? 0.0 : delay
+      rescue ArgumentError
+        nil
+      end
     end
   end
 end

data/lib/philiprehberger/http_client/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module HttpClient
-    VERSION = '0.11.1'
+    VERSION = '0.13.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-http_client
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.13.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-15 00:00:00.000000000 Z
+date: 2026-10-30 00:00:00.000000000 Z
 dependencies: []
 description: A zero-dependency HTTP client built on Ruby's net/http with automatic
   retries, request/response interceptors, and a clean API for JSON services.