philiprehberger-http_client 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e7ebec429195d4e674adf7836c916e2e9fa40938c1fe79209d8c10ad4c0df5d
-  data.tar.gz: 94fd543943abe6573cb5ce9bdc686bc5c7aa79858b312aab251a4851c4f9718f
+  metadata.gz: 211aea712ab77e8a14f5a565d0a235113b1b5a5630e38e13ddcfb2f92c61b141
+  data.tar.gz: d9a7e6996c9ca7cc6ba296c837db466cdc692abb489bb179c24aea3e888e274b
 SHA512:
-  metadata.gz: ba7e2ba9e18a068391353b8164393deb5205faa86367fffb1101b782ca08e72d1db2c8eecf8343621062b61629268c09254c9a597d333da59657979903090882
-  data.tar.gz: 2ab2ebe6ab143e5417e7939905c9b971bce1237cf434f0d4a360f912ab02d37468affa783368297ed11e1de44689847239a55f9fbd7e51864c9ba7ec6be595fa
+  metadata.gz: 9cf88a13252d7b73c94b747a0ce54cc5027dbdb28aceaefeca3cf5c4d5c2818b09d8b7b9c92e7cbda000a8343fda30aff88f9110a0d96eccb0b9cada3e84d67e
+  data.tar.gz: 716b066adc90993966528dc3100dcb1b6d4e9130926673ee1279d2931e2f0089a2f0999e22fcfade122e9afd1a641e2e7a6c566594845efd8864ac9b0683bfdf

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- Added package card image to README
+- Cleaned up Installation section formatting
+
 ## [0.11.0] - 2026-05-13
 
 ### Added
@@ -194,7 +211,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.0...HEAD
+[Unreleased]: https://github.com/philiprehberger/rb-http-client/compare/v0.12.0...HEAD
+[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
 [0.9.1]: https://github.com/philiprehberger/rb-http-client/compare/v0.9.0...v0.9.1

data/README.md

@@ -4,6 +4,8 @@
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-http_client.svg)](https://rubygems.org/gems/philiprehberger-http_client)
 [![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-http-client)](https://github.com/philiprehberger/rb-http-client/commits/main)
 
+![philiprehberger-http_client](https://raw.githubusercontent.com/philiprehberger/rb-http-client/main/package-card.webp)
+
 Lightweight HTTP client wrapper with retries and interceptors
 
 ## Requirements
@@ -18,12 +20,6 @@ Add to your Gemfile:
 gem "philiprehberger-http_client"
 ```
 
-Then run:
-
-```bash
-bundle install
-```
-
 Or install directly:
 
 ```bash
@@ -206,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
@@ -218,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:
@@ -376,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:
@@ -451,7 +482,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 |
@@ -459,6 +492,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

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/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.0'
+    VERSION = '0.12.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-http_client
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-14 00:00:00.000000000 Z
+date: 2026-07-16 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.