philiprehberger-http_client 0.7.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d0ec8636cc91257698783cc3876cb93be649c33ad70c91317c6738b145a2ab1
-  data.tar.gz: 778941d598bfb51d3ec2e1291e8ab4231ac43137385659b17795bdebf8f14c21
+  metadata.gz: 8c45ebe7d84b21537896e6e973ed05aa04a2d582f51e3ffe84f75be8896aba31
+  data.tar.gz: 3113777f92b0047542c4498885e259fcf87823ccbecb0bc993aa0de99f0c9b54
 SHA512:
-  metadata.gz: a86d3da1c7d89b7bbf1341cb0efe062f99e12a025909f28307bfc163f24435f1706a2b1d2a025439b2ba8d59060c9b06c04fe97b213895a5587ba0ecd1c9da4b
-  data.tar.gz: 46e39334ae5e243f378ca80e31313180f980bf819fcce88760d3c3b8a2628fc0cd23b99219da31e56d520364dfca0fd9f643ab9cbf0a0c907780e85f6c017494
+  metadata.gz: 8ad3b396d9ab5ad1c004a3363b57108f51709318171a848fb31f167faab95ebbb1ca5827510d86248ffa3b6e1aa37a10024eeb7678ac8a4b553548db7f7612bd
+  data.tar.gz: 733c04bde42f3ff1a987c77b4221a236c595cd07447be80fb195626f029ddf08d822b1f6868a18bd414bf45755b36ebf6f00d80bad6e997175a0f114889d24cd

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.8.1] - 2026-04-07
+
+### Added
+- `ConfigurationError` raised at initialization for invalid `timeout`, `open_timeout`, `read_timeout`, `write_timeout`, `retries`, `retry_delay`, `retry_backoff`, or `retry_on_status` values — fail fast instead of producing confusing runtime errors
+
+## [0.8.0] - 2026-04-05
+
+### Added
+- `Client#close` method to explicitly drain the connection pool
+- `Client.open(**opts, &block)` block form with automatic cleanup
+
+### Fixed
+- Response objects now properly initialize `metrics` and `redirects` attributes
+- 307 and 308 redirects now preserve the original HTTP method instead of converting to GET
+- Clarified that `dns_time`, `connect_time`, and `tls_time` metrics are unavailable from Net::HTTP
+
 ## [0.7.0] - 2026-04-04
 
 ### Added

data/README.md

@@ -299,6 +299,8 @@ metrics.first_byte_time  # => 0.180
 metrics.to_h             # => { dns_time: 0.0, connect_time: 0.0, ... }
 ```
 
+> **Note:** `dns_time`, `connect_time`, and `tls_time` are not available from Ruby's stdlib `Net::HTTP` and will always be `0.0`. Only `total_time` and `first_byte_time` are populated.
+
 ### Connection pooling
 
 Reuse TCP connections to the same host for better performance:
@@ -317,6 +319,23 @@ client = Philiprehberger::HttpClient.new(
 client.pool.drain
 ```
 
+### Client lifecycle
+
+Use `Client.open` for automatic cleanup, or call `close` manually to drain the connection pool:
+
+```ruby
+# Block form — pool is drained automatically
+Philiprehberger::HttpClient.open(base_url: "https://api.example.com", pool: true) do |client|
+  client.get("/data")
+  client.post("/submit", json: { key: "value" })
+end
+
+# Manual form
+client = Philiprehberger::HttpClient.new(base_url: "https://api.example.com", pool: true)
+client.get("/data")
+client.close  # drains the connection pool
+```
+
 ### Request ID tracking
 
 Every request is assigned a unique `X-Request-ID` header automatically:
@@ -428,6 +447,8 @@ client.head("/resource")
 | `bearer_token(token)` | Set Bearer token auth for all subsequent requests |
 | `basic_auth(user, pass)` | Set Basic auth for all subsequent requests |
 | `clear_cache!` | Flush the response cache |
+| `close` | Drain the connection pool (no-op if pooling disabled) |
+| `self.open(**opts, &block)` | Block form — creates client, yields it, ensures `close` is called |
 | `pool` | Returns the `Pool` instance (nil if pooling disabled) |
 | `cache` | Returns the `Cache` instance (nil if caching disabled) |
 
@@ -468,6 +489,7 @@ client.head("/resource")
 | Class | Description |
 |-------|-------------|
 | `Error` | Base error class (inherits `StandardError`) |
+| `ConfigurationError` | Invalid client option (negative timeout, bad retry config, etc.) |
 | `TimeoutError` | Connection or read timeout |
 | `NetworkError` | Connection refused, reset, unreachable |
 | `HttpError` | Response status mismatch (has `.response` accessor) |

data/lib/philiprehberger/http_client/client.rb

@@ -32,8 +32,10 @@ module Philiprehberger
         @base_url = base_url.chomp('/')
         @default_headers = headers
         @timeout = timeout
+        validate_timeout!(:timeout, timeout)
         assign_timeout_opts(opts)
         assign_retry_opts(opts)
+        validate_config!
         assign_cookie_opts(opts)
         assign_proxy_opts(opts)
         assign_redirect_opts(opts)
@@ -204,12 +206,56 @@ module Philiprehberger
         @cache&.clear!
       end
 
+      # Drain the connection pool. No-op if pooling is disabled.
+      #
+      # @return [void]
+      def close
+        @pool&.drain
+      end
+
+      # Create a client, yield it to the block, and ensure it is closed afterward.
+      #
+      # @param opts [Hash] Options forwarded to {#initialize}
+      # @yield [Client] the client instance
+      # @return [Object] the return value of the block
+      def self.open(**opts)
+        client = new(**opts)
+        yield client
+      ensure
+        client&.close
+      end
+
       private
 
       def assign_timeout_opts(opts)
         @open_timeout = opts[:open_timeout]
         @read_timeout = opts[:read_timeout]
         @write_timeout = opts[:write_timeout]
+        validate_timeout!(:open_timeout, @open_timeout)
+        validate_timeout!(:read_timeout, @read_timeout)
+        validate_timeout!(:write_timeout, @write_timeout)
+      end
+
+      def validate_timeout!(name, value)
+        return if value.nil?
+        raise ConfigurationError, "#{name} must be Numeric, got #{value.class}" unless value.is_a?(Numeric)
+        raise ConfigurationError, "#{name} must be non-negative, got #{value}" if value.negative?
+      end
+
+      def validate_config!
+        unless @retries.is_a?(Integer) && !@retries.negative?
+          raise ConfigurationError, "retries must be a non-negative Integer, got #{@retries.inspect}"
+        end
+        unless @retry_delay.is_a?(Numeric) && !@retry_delay.negative?
+          raise ConfigurationError, "retry_delay must be a non-negative Numeric, got #{@retry_delay.inspect}"
+        end
+        unless %i[fixed exponential].include?(@retry_backoff)
+          raise ConfigurationError, "retry_backoff must be :fixed or :exponential, got #{@retry_backoff.inspect}"
+        end
+        return if @retry_on_status.nil?
+        return if @retry_on_status.respond_to?(:include?)
+
+        raise ConfigurationError, 'retry_on_status must be an Array of status codes'
       end
 
       def assign_retry_opts(opts)

data/lib/philiprehberger/http_client/connection.rb

@@ -185,6 +185,15 @@ module Philiprehberger
         @follow_redirects && REDIRECT_CODES.include?(response.status)
       end
 
+      METHOD_CLASS_MAP = {
+        'GET' => Net::HTTP::Get,
+        'POST' => Net::HTTP::Post,
+        'PUT' => Net::HTTP::Put,
+        'PATCH' => Net::HTTP::Patch,
+        'DELETE' => Net::HTTP::Delete,
+        'HEAD' => Net::HTTP::Head
+      }.freeze
+
       def follow_redirect_chain(response, original_request, **timeout_opts)
         redirect_count = 0
         redirects = []
@@ -199,7 +208,12 @@ module Philiprehberger
           redirect_uri = URI.parse(location)
           redirect_uri = URI.join("#{original_request.uri.scheme}://#{original_request.uri.host}", location) unless redirect_uri.host
 
-          redirect_request = Net::HTTP::Get.new(redirect_uri)
+          redirect_class = if [307, 308].include?(current_response.status)
+                             METHOD_CLASS_MAP.fetch(original_request.method, Net::HTTP::Get)
+                           else
+                             Net::HTTP::Get
+                           end
+          redirect_request = redirect_class.new(redirect_uri)
           @default_headers.each { |key, value| redirect_request[key] = value }
           redirect_request['accept-encoding'] ||= 'gzip, deflate'
           apply_cookie_header(redirect_request)

data/lib/philiprehberger/http_client/errors.rb

@@ -5,6 +5,9 @@ module Philiprehberger
     # Base error class for all HTTP client errors.
     class Error < StandardError; end
 
+    # Raised when client configuration is invalid (e.g. negative timeout).
+    class ConfigurationError < Error; end
+
     # Raised when a connection or read timeout occurs.
     class TimeoutError < Error; end
 

data/lib/philiprehberger/http_client/response.rb

@@ -18,6 +18,8 @@ module Philiprehberger
         @headers = headers
         @streaming = streaming
         @request_id = request_id
+        @metrics = nil
+        @redirects = []
       end
 
       # Returns true if the status code is in the 2xx range.
@@ -50,9 +52,7 @@ module Philiprehberger
       # Returns the redirect chain (empty if no redirects occurred).
       #
       # @return [Array<String>]
-      def redirects
-        @redirects || []
-      end
+      attr_reader :redirects
 
       # Returns true if the response was redirected.
       #

data/lib/philiprehberger/http_client/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module HttpClient
-    VERSION = '0.7.0'
+    VERSION = '0.8.1'
   end
 end

data/lib/philiprehberger/http_client.rb

@@ -22,5 +22,14 @@ module Philiprehberger
     def self.new(**options)
       Client.new(**options)
     end
+
+    # Block form — creates a client, yields it, and ensures cleanup.
+    #
+    # @param options [Hash] Forwarded to {Client#initialize}
+    # @yield [Client]
+    # @return [Object] the return value of the block
+    def self.open(...)
+      Client.open(...)
+    end
   end
 end

metadata

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