philiprehberger-http_client 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc47cd54c2873fe7bf5dacad5d62bb028b4ccd9b36e028182e7700cbfeb589de
-  data.tar.gz: 26739ada42f419275cada8b35136f0b35fe1c4c2744067466f5e20fc851c4a58
+  metadata.gz: 94b2fd66c1f84f7184ca9767b09e05a4f9872106bec895519d409142d798a552
+  data.tar.gz: 460680dc0188632f403f45261ed505dc095d45cbaceaba50a0301abd721788d1
 SHA512:
-  metadata.gz: d4a8181bf4925a8314d54cbe34db75dd19a79af46d5c7f432bb33172df6c89d1c6b6e0bede1cdbdada2613f8291c1c15a7dee6559ddbf73d432437891ae67531
-  data.tar.gz: 48a8ca6c36e77ca87950da44209d7e39eecfe23ee7ed7d9bebf6c63f717c849fb021e69a7aada4a81d52996be7a206c5bff5c53099283abf9cb467f1709907bb
+  metadata.gz: 3e3add0cf7a23e8e852224ab9428469e7d603166307e9aa4702c85e15df3c8fadf5a0e756d558f2bb89b3c606b4eba63e26d26bd3063a7c665fd15587cf12316
+  data.tar.gz: 197ef15006f59be6093cfcb982bd507784c128c47125415f19dc86d63e35570a346bb3bfbb5c014a270d6921724e1603ba3d5f9ddf6dc19ae93f428ee1042eeb

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.4.0
+
+### Added
+
+- Custom error hierarchy: `Error`, `TimeoutError`, `NetworkError`, `HttpError` for structured error handling
+- Streaming responses via block parameter — yield body chunks instead of buffering entire response
+- Multipart form data support via `multipart:` parameter for file uploads
+- Per-phase timeouts: `open_timeout:`, `read_timeout:`, `write_timeout:` on constructor and per-request
+- Response validation via `expect:` option — auto-raises `HttpError` if status not in expected list
+
+### Changed
+
+- Network errors (`Errno::ECONNREFUSED`, `Errno::ECONNRESET`, etc.) now raise `NetworkError` instead of raw system errors
+- Timeout errors (`Net::OpenTimeout`, `Net::ReadTimeout`) now raise `TimeoutError` instead of raw Net errors
+
+## 0.3.3
+
+- Fix CI: version test and rubocop compliance
+
+## 0.3.2
+
+- Add License badge to README
+- Add bug_tracker_uri to gemspec
+- Add Development section to README
+- Add Requirements section to README
+
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),

data/README.md

@@ -2,9 +2,14 @@
 
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-http_client.svg)](https://badge.fury.io/rb/philiprehberger-http_client)
 [![CI](https://github.com/philiprehberger/rb-http-client/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-http-client/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-http-client)](LICENSE)
 
 Lightweight HTTP client wrapper with retries and interceptors. Zero dependencies — built on Ruby's stdlib `net/http`.
 
+## Requirements
+
+- Ruby >= 3.1
+
 ## Installation
 
 Add to your Gemfile:
@@ -83,6 +88,41 @@ response = client.post("/login", form: { username: "alice", password: "secret" }
 # Content-Type: application/x-www-form-urlencoded is set automatically
 ```
 
+### File uploads (multipart)
+
+Upload files using multipart/form-data:
+
+```ruby
+response = client.post("/upload", multipart: {
+  file: File.open("photo.jpg"),
+  name: "vacation"
+})
+# Content-Type: multipart/form-data is set automatically with boundary
+```
+
+Both `File` objects and string values are supported. Files are sent with their filename and `application/octet-stream` content type.
+
+### Streaming responses
+
+Stream large responses without buffering the entire body in memory:
+
+```ruby
+File.open("download.bin", "wb") do |file|
+  client.get("/large-file") do |chunk|
+    file.write(chunk)
+  end
+end
+# Returns a Response with body: nil and streaming?: true
+```
+
+Streaming works with all HTTP methods that accept a block:
+
+```ruby
+client.post("/export", json: { format: "csv" }) do |chunk|
+  output.write(chunk)
+end
+```
+
 ### Authentication helpers
 
 ```ruby
@@ -95,6 +135,61 @@ client.basic_auth("username", "password")
 client.get("/protected")  # Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
 ```
 
+### Error handling
+
+All errors inherit from `Philiprehberger::HttpClient::Error`:
+
+```ruby
+begin
+  client.get("/api/data")
+rescue Philiprehberger::HttpClient::TimeoutError => e
+  puts "Request timed out: #{e.message}"
+rescue Philiprehberger::HttpClient::NetworkError => e
+  puts "Network error: #{e.message}"
+rescue Philiprehberger::HttpClient::HttpError => e
+  puts "HTTP error: #{e.response.status}"
+rescue Philiprehberger::HttpClient::Error => e
+  puts "Client error: #{e.message}"
+end
+```
+
+- `TimeoutError` — raised on `Net::OpenTimeout` and `Net::ReadTimeout`
+- `NetworkError` — raised on connection refused, reset, host unreachable, etc.
+- `HttpError` — raised when response status doesn't match `expect:` list (includes `.response`)
+
+### Response validation
+
+Auto-raise `HttpError` if the response status doesn't match expected values:
+
+```ruby
+# Raises HttpError if status is not 200
+response = client.get("/api/users", expect: [200])
+
+# Accept multiple status codes
+response = client.post("/api/users", json: data, expect: [200, 201])
+```
+
+### Timeouts
+
+Set a general timeout or per-phase timeouts:
+
+```ruby
+# General timeout (applies to open, read, and write)
+client = Philiprehberger::HttpClient.new(base_url: "https://api.example.com", timeout: 30)
+
+# Per-phase timeouts (override general timeout)
+client = Philiprehberger::HttpClient.new(
+  base_url: "https://api.example.com",
+  open_timeout: 5,
+  read_timeout: 30,
+  write_timeout: 10
+)
+
+# Per-request timeout overrides
+response = client.get("/slow-endpoint", read_timeout: 120)
+response = client.post("/upload", body: data, write_timeout: 60)
+```
+
 ### Retries
 
 Automatically retry on network errors (connection refused, timeouts, etc.):
@@ -134,12 +229,6 @@ client = Philiprehberger::HttpClient.new(
 # Delay sequence: 1s, 2s, 4s
 ```
 
-### Per-request timeout
-
-```ruby
-response = client.get("/slow-endpoint", timeout: 60)
-```
-
 ### All HTTP methods
 
 ```ruby
@@ -159,7 +248,10 @@ client.head("/resource")
 |---------------|---------|---------|--------------------------------------|
 | `base_url`    | String  | —       | Base URL for all requests (required) |
 | `headers`     | Hash    | `{}`    | Default headers for every request    |
-| `timeout`     | Integer | `30`    | Read/open timeout in seconds         |
+| `timeout`     | Integer | `30`    | General timeout in seconds           |
+| `open_timeout` | Integer | `nil`  | TCP connection timeout (overrides `timeout`) |
+| `read_timeout` | Integer | `nil`  | Response read timeout (overrides `timeout`)  |
+| `write_timeout` | Integer | `nil` | Request write timeout (overrides `timeout`)  |
 | `retries`     | Integer | `0`     | Retry attempts on network errors     |
 | `retry_delay` | Numeric | `1`     | Seconds between retries              |
 | `retry_backoff` | Symbol | `:fixed` | Backoff strategy — `:fixed` or `:exponential` |
@@ -169,25 +261,60 @@ client.head("/resource")
 
 | Method | Description |
 |--------|-------------|
-| `get(path, **opts)` | Send GET request |
-| `post(path, **opts)` | Send POST request |
-| `put(path, **opts)` | Send PUT request |
-| `patch(path, **opts)` | Send PATCH request |
+| `get(path, **opts, &block)` | Send GET request (block enables streaming) |
+| `post(path, **opts, &block)` | Send POST request |
+| `put(path, **opts, &block)` | Send PUT request |
+| `patch(path, **opts, &block)` | Send PATCH request |
 | `delete(path, **opts)` | Send DELETE request |
 | `head(path, **opts)` | Send HEAD request |
 | `request_count` | Total number of requests made by this client |
 | `bearer_token(token)` | Set Bearer token auth for all subsequent requests |
 | `basic_auth(user, pass)` | Set Basic auth for all subsequent requests |
 
+### Per-request options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `params` | Hash | Query parameters (GET, HEAD) |
+| `json` | Hash/Array | JSON body (POST, PUT, PATCH) |
+| `form` | Hash | Form-urlencoded body (POST, PUT, PATCH) |
+| `multipart` | Hash | Multipart form data with file support (POST, PUT, PATCH) |
+| `body` | String | Raw body string (POST, PUT, PATCH) |
+| `headers` | Hash | Per-request headers |
+| `timeout` | Integer | General per-request timeout |
+| `open_timeout` | Integer | Per-request open timeout |
+| `read_timeout` | Integer | Per-request read timeout |
+| `write_timeout` | Integer | Per-request write timeout |
+| `expect` | Array | Expected status codes — raises `HttpError` otherwise |
+
 ### `Response`
 
 | Method    | Returns | Description                     |
 |-----------|---------|---------------------------------|
 | `status`  | Integer | HTTP status code                |
-| `body`    | String  | Raw response body               |
+| `body`    | String  | Raw response body (`nil` if streamed) |
 | `headers` | Hash    | Response headers                |
 | `ok?`     | Boolean | `true` if status is 200-299     |
 | `json`    | Hash    | Parsed JSON body                |
+| `streaming?` | Boolean | `true` if response was streamed |
+
+### Errors
+
+| Class | Description |
+|-------|-------------|
+| `Error` | Base error class (inherits `StandardError`) |
+| `TimeoutError` | Connection or read timeout |
+| `NetworkError` | Connection refused, reset, unreachable |
+| `HttpError` | Response status mismatch (has `.response` accessor) |
+
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
 
 ## License
 

data/lib/philiprehberger/http_client/body_encoder.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module HttpClient
+    # Handles encoding request bodies (JSON, form, multipart, raw).
+    module BodyEncoder
+      private
+
+      def apply_body(request, opts, headers)
+        set_json_body(request, opts[:json], headers) ||
+          set_form_body(request, opts[:form], headers) ||
+          set_multipart_body(request, opts[:multipart], headers) ||
+          set_raw_body(request, opts[:body])
+      end
+
+      def set_json_body(request, json_body, headers)
+        return unless json_body
+
+        request.body = JSON.generate(json_body)
+        headers["content-type"] ||= "application/json"
+      end
+
+      def set_form_body(request, form_body, headers)
+        return unless form_body
+
+        request.body = URI.encode_www_form(form_body)
+        headers["content-type"] ||= "application/x-www-form-urlencoded"
+      end
+
+      def set_multipart_body(request, multipart_body, headers)
+        return unless multipart_body
+
+        built_body, content_type = Multipart.build(multipart_body)
+        request.body = built_body
+        headers["content-type"] = content_type
+      end
+
+      def set_raw_body(request, body)
+        request.body = body if body
+      end
+    end
+  end
+end

data/lib/philiprehberger/http_client/client.rb

@@ -12,18 +12,19 @@ module Philiprehberger
 
       # @param base_url [String] Base URL for all requests
       # @param headers [Hash] Default headers applied to every request
-      # @param timeout [Integer] Read/open timeout in seconds
+      # @param timeout [Integer] General read/open timeout in seconds
+      # @param open_timeout [Integer, nil] TCP connection timeout (overrides timeout)
+      # @param read_timeout [Integer, nil] Response read timeout (overrides timeout)
+      # @param write_timeout [Integer, nil] Request write timeout (overrides timeout)
       # @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)
-      def initialize(base_url:, headers: {}, timeout: 30, **retry_options)
+      def initialize(base_url:, headers: {}, timeout: 30, **opts)
         @base_url = base_url.chomp("/")
         @default_headers = headers
         @timeout = timeout
-        @retries = retry_options.fetch(:retries, 0)
-        @retry_delay = retry_options.fetch(:retry_delay, 1)
-        @retry_backoff = retry_options.fetch(:retry_backoff, :fixed)
-        @retry_on_status = retry_options[:retry_on_status]
+        assign_timeout_opts(opts)
+        assign_retry_opts(opts)
         @interceptors = []
         @request_count = 0
       end
@@ -52,11 +53,16 @@ module Philiprehberger
       # @param params [Hash] Query parameters
       # @param headers [Hash] Additional headers for this request
       # @param timeout [Integer, nil] Optional per-request timeout override
+      # @param open_timeout [Integer, nil] Optional per-request open timeout
+      # @param read_timeout [Integer, nil] Optional per-request read timeout
+      # @param write_timeout [Integer, nil] Optional per-request write timeout
+      # @param expect [Array<Integer>, nil] Expected status codes (raises HttpError otherwise)
+      # @yield [String] response body chunks when streaming
       # @return [Response]
-      def get(path, params: {}, headers: {}, timeout: nil)
+      def get(path, params: {}, headers: {}, expect: nil, **timeout_opts, &block)
         uri = build_uri(path, params)
         request = Net::HTTP::Get.new(uri)
-        execute(uri, request, headers, timeout: timeout)
+        execute(uri, request, headers, expect: expect, **timeout_opts, &block)
       end
 
       # Perform a HEAD request.
@@ -65,11 +71,15 @@ module Philiprehberger
       # @param params [Hash] Query parameters
       # @param headers [Hash] Additional headers for this request
       # @param timeout [Integer, nil] Optional per-request timeout override
+      # @param open_timeout [Integer, nil] Optional per-request open timeout
+      # @param read_timeout [Integer, nil] Optional per-request read timeout
+      # @param write_timeout [Integer, nil] Optional per-request write timeout
+      # @param expect [Array<Integer>, nil] Expected status codes
       # @return [Response]
-      def head(path, params: {}, headers: {}, timeout: nil)
+      def head(path, params: {}, headers: {}, expect: nil, **timeout_opts)
         uri = build_uri(path, params)
         request = Net::HTTP::Head.new(uri)
-        execute(uri, request, headers, timeout: timeout)
+        execute(uri, request, headers, expect: expect, **timeout_opts)
       end
 
       # Perform a POST request.
@@ -78,10 +88,12 @@ module Philiprehberger
       # @param body [String, nil] Raw body string
       # @param json [Hash, Array, nil] JSON-serializable body (sets Content-Type automatically)
       # @param form [Hash, nil] Form-urlencoded body (sets Content-Type automatically)
+      # @param multipart [Hash, nil] Multipart form data (sets Content-Type automatically)
       # @param headers [Hash] Additional headers
+      # @param expect [Array<Integer>, nil] Expected status codes
       # @return [Response]
-      def post(path, **opts)
-        request_with_body(Net::HTTP::Post, path, **opts)
+      def post(path, ...)
+        request_with_body(Net::HTTP::Post, path, ...)
       end
 
       # Perform a PUT request.
@@ -90,10 +102,12 @@ module Philiprehberger
       # @param body [String, nil] Raw body string
       # @param json [Hash, Array, nil] JSON-serializable body
       # @param form [Hash, nil] Form-urlencoded body
+      # @param multipart [Hash, nil] Multipart form data
       # @param headers [Hash] Additional headers
+      # @param expect [Array<Integer>, nil] Expected status codes
       # @return [Response]
-      def put(path, **opts)
-        request_with_body(Net::HTTP::Put, path, **opts)
+      def put(path, ...)
+        request_with_body(Net::HTTP::Put, path, ...)
       end
 
       # Perform a PATCH request.
@@ -102,21 +116,28 @@ module Philiprehberger
       # @param body [String, nil] Raw body string
       # @param json [Hash, Array, nil] JSON-serializable body
       # @param form [Hash, nil] Form-urlencoded body
+      # @param multipart [Hash, nil] Multipart form data
       # @param headers [Hash] Additional headers
+      # @param expect [Array<Integer>, nil] Expected status codes
       # @return [Response]
-      def patch(path, **opts)
-        request_with_body(Net::HTTP::Patch, path, **opts)
+      def patch(path, ...)
+        request_with_body(Net::HTTP::Patch, path, ...)
       end
 
       # Perform a DELETE request.
       #
       # @param path [String] Request path
       # @param headers [Hash] Additional headers
+      # @param timeout [Integer, nil] Optional per-request timeout override
+      # @param open_timeout [Integer, nil] Optional per-request open timeout
+      # @param read_timeout [Integer, nil] Optional per-request read timeout
+      # @param write_timeout [Integer, nil] Optional per-request write timeout
+      # @param expect [Array<Integer>, nil] Expected status codes
       # @return [Response]
-      def delete(path, headers: {}, timeout: nil)
+      def delete(path, headers: {}, expect: nil, **timeout_opts)
         uri = build_uri(path)
         request = Net::HTTP::Delete.new(uri)
-        execute(uri, request, headers, timeout: timeout)
+        execute(uri, request, headers, expect: expect, **timeout_opts)
       end
 
       # Set a Bearer token for all subsequent requests.
@@ -138,6 +159,21 @@ module Philiprehberger
         @default_headers["authorization"] = "Basic #{encoded}"
         self
       end
+
+      private
+
+      def assign_timeout_opts(opts)
+        @open_timeout = opts[:open_timeout]
+        @read_timeout = opts[:read_timeout]
+        @write_timeout = opts[:write_timeout]
+      end
+
+      def assign_retry_opts(opts)
+        @retries = opts.fetch(:retries, 0)
+        @retry_delay = opts.fetch(:retry_delay, 1)
+        @retry_backoff = opts.fetch(:retry_backoff, :fixed)
+        @retry_on_status = opts[:retry_on_status]
+      end
     end
   end
 end

data/lib/philiprehberger/http_client/connection.rb

@@ -5,19 +5,30 @@ module Philiprehberger
     # Internal helpers for building URIs, HTTP connections, executing requests,
     # and constructing Response objects. Mixed into Client to keep it concise.
     module Connection
-      RETRYABLE_ERRORS = [
+      TIMEOUT_ERRORS = [
+        Net::OpenTimeout, Net::ReadTimeout
+      ].freeze
+
+      NETWORK_ERRORS = [
         Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::ETIMEDOUT,
-        Net::OpenTimeout, Net::ReadTimeout, SocketError
+        Errno::EHOSTUNREACH, Errno::ENETUNREACH, SocketError
       ].freeze
 
+      RETRYABLE_ERRORS = (TIMEOUT_ERRORS + NETWORK_ERRORS).freeze
+
+      include Retries
+      include BodyEncoder
+
       private
 
-      def request_with_body(http_class, path, **opts)
+      def request_with_body(http_class, path, **opts, &)
         headers = opts.fetch(:headers, {})
         uri = build_uri(path)
         request = http_class.new(uri)
-        set_body(request, opts[:body], opts[:json], opts[:form], headers)
-        execute(uri, request, headers, timeout: opts[:timeout])
+        apply_body(request, opts, headers)
+        execute(uri, request, headers, timeout: opts[:timeout], open_timeout: opts[:open_timeout],
+                                       read_timeout: opts[:read_timeout], write_timeout: opts[:write_timeout],
+                                       expect: opts[:expect], &)
       end
 
       def build_uri(path, params = {})
@@ -30,87 +41,79 @@ module Philiprehberger
         uri
       end
 
-      def set_body(request, body, json_body, form_body, headers)
-        if json_body
-          request.body = JSON.generate(json_body)
-          headers["content-type"] ||= "application/json"
-        elsif form_body
-          request.body = URI.encode_www_form(form_body)
-          headers["content-type"] ||= "application/x-www-form-urlencoded"
-        elsif body
-          request.body = body
-        end
-      end
-
       def apply_headers(request, extra_headers)
         merged = @default_headers.merge(extra_headers)
         merged.each { |key, value| request[key] = value }
       end
 
-      def execute(uri, request, extra_headers, timeout: nil)
+      def execute(uri, request, extra_headers, expect: nil, **timeout_opts, &block)
         apply_headers(request, extra_headers)
         @request_count += 1
+        run_execute_pipeline(uri, request, expect, **timeout_opts, &block)
+      end
 
+      def run_execute_pipeline(uri, request, expect, **timeout_opts, &)
         context = { request: { uri: uri, method: request.method, headers: request.to_hash } }
         run_interceptors(context)
-
-        response = perform_with_retries(uri, request, timeout: timeout)
+        response = perform_with_retries(uri, request, **timeout_opts, &)
         context[:response] = response
         run_interceptors(context)
-
+        validate_response!(response, expect) if expect
         response
       end
 
-      def perform_with_retries(uri, request, timeout: nil)
-        attempts = 0
-        loop do
-          response = perform_request(uri, request, timeout: timeout)
-          return response unless retry_on_status?(response.status, attempts)
-
-          wait_and_retry(attempts += 1)
-        rescue *RETRYABLE_ERRORS => e
-          raise e unless (attempts += 1) <= @retries
+      def perform_request(uri, request, **timeout_opts, &block)
+        http = build_http(uri, **timeout_opts)
 
-          sleep(retry_delay_for(attempts))
+        if block
+          perform_streaming_request(http, request, &block)
+        else
+          raw = http.request(request)
+          build_response(raw)
         end
       end
 
-      def retry_on_status?(status, attempts)
-        @retry_on_status&.include?(status) && attempts < @retries
-      end
-
-      def wait_and_retry(attempt)
-        sleep(retry_delay_for(attempt))
-      end
+      def perform_streaming_request(http, request, &block)
+        response_headers = {}
+        status = nil
 
-      def retry_delay_for(attempt)
-        @retry_backoff == :exponential ? @retry_delay * (2**(attempt - 1)) : @retry_delay
-      end
+        http.request(request) do |raw|
+          status = raw.code.to_i
+          raw.each_header { |k, v| response_headers[k] = v }
+          raw.read_body(&block)
+        end
 
-      def perform_request(uri, request, timeout: nil)
-        http = build_http(uri, timeout: timeout)
-        raw = http.request(request)
-        build_response(raw)
+        Response.new(status: status, body: nil, headers: response_headers, streaming: true)
       end
 
-      def build_http(uri, timeout: nil)
-        effective_timeout = timeout || @timeout
+      def build_http(uri, **timeout_opts)
         http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = uri.scheme == "https"
-        http.open_timeout = effective_timeout
-        http.read_timeout = effective_timeout
+        apply_timeouts(http, timeout_opts)
         http
       end
 
+      def apply_timeouts(http, timeout_opts)
+        effective = timeout_opts[:timeout] || @timeout
+        http.open_timeout = resolve_timeout(:open_timeout, timeout_opts, effective)
+        http.read_timeout = resolve_timeout(:read_timeout, timeout_opts, effective)
+        http.write_timeout = resolve_timeout(:write_timeout, timeout_opts, effective)
+      end
+
+      def resolve_timeout(key, timeout_opts, fallback)
+        timeout_opts[key] || instance_variable_get(:"@#{key}") || fallback
+      end
+
       def build_response(raw)
         response_headers = {}
         raw.each_header { |k, v| response_headers[k] = v }
+        Response.new(status: raw.code.to_i, body: raw.body || "", headers: response_headers)
+      end
+
+      def validate_response!(response, expected_statuses)
+        return if expected_statuses.include?(response.status)
 
-        Response.new(
-          status: raw.code.to_i,
-          body: raw.body || "",
-          headers: response_headers
-        )
+        raise HttpError, response
       end
 
       def run_interceptors(context)

data/lib/philiprehberger/http_client/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module HttpClient
+    # Base error class for all HTTP client errors.
+    class Error < StandardError; end
+
+    # Raised when a connection or read timeout occurs.
+    class TimeoutError < Error; end
+
+    # Raised when a network-level error occurs (connection refused, reset, etc.).
+    class NetworkError < Error; end
+
+    # Raised when a response status does not match expected values.
+    class HttpError < Error
+      attr_reader :response
+
+      # @param response [Response] the HTTP response that triggered the error
+      def initialize(response)
+        @response = response
+        super("HTTP #{response.status}: #{response.body.to_s[0..200]}")
+      end
+    end
+  end
+end

data/lib/philiprehberger/http_client/multipart.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Philiprehberger
+  module HttpClient
+    # Builds multipart/form-data request bodies from a hash of fields.
+    # Supports both string values and File/IO objects.
+    module Multipart
+      CRLF = "\r\n"
+
+      # Build a multipart/form-data body and content-type header.
+      #
+      # @param fields [Hash] field name => value pairs (String or File/IO)
+      # @return [Array(String, String)] the body string and content-type header value
+      def self.build(fields)
+        boundary = generate_boundary
+        body = build_body(fields, boundary)
+        content_type = "multipart/form-data; boundary=#{boundary}"
+        [body, content_type]
+      end
+
+      # @api private
+      def self.generate_boundary
+        "----RubyFormBoundary#{SecureRandom.hex(16)}"
+      end
+
+      # @api private
+      def self.build_body(fields, boundary)
+        parts = fields.map { |name, value| build_part(name, value, boundary) }
+        parts.join + "--#{boundary}--#{CRLF}"
+      end
+
+      # @api private
+      def self.build_part(name, value, boundary)
+        if value.respond_to?(:read)
+          build_file_part(name, value, boundary)
+        else
+          build_field_part(name, value, boundary)
+        end
+      end
+
+      # @api private
+      def self.build_file_part(name, file, boundary)
+        filename = file.respond_to?(:path) ? File.basename(file.path) : "upload"
+        content = read_file_content(file)
+        disposition = "Content-Disposition: form-data; name=\"#{name}\"; filename=\"#{filename}\"#{CRLF}"
+        "--#{boundary}#{CRLF}#{disposition}Content-Type: application/octet-stream#{CRLF}#{CRLF}#{content}#{CRLF}"
+      end
+
+      def self.read_file_content(file)
+        content = file.read
+        file.rewind if file.respond_to?(:rewind)
+        content
+      end
+
+      # @api private
+      def self.build_field_part(name, value, boundary)
+        "".dup.tap do |part|
+          part << "--#{boundary}#{CRLF}"
+          part << "Content-Disposition: form-data; name=\"#{name}\"#{CRLF}"
+          part << CRLF
+          part << value.to_s
+          part << CRLF
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/http_client/response.rb

@@ -8,12 +8,14 @@ module Philiprehberger
       attr_reader :status, :body, :headers
 
       # @param status [Integer] HTTP status code
-      # @param body [String] Response body
+      # @param body [String, nil] Response body
       # @param headers [Hash] Response headers
-      def initialize(status:, body:, headers: {})
+      # @param streaming [Boolean] Whether the response was streamed
+      def initialize(status:, body:, headers: {}, streaming: false)
         @status = status
         @body = body
         @headers = headers
+        @streaming = streaming
       end
 
       # Returns true if the status code is in the 2xx range.
@@ -23,6 +25,13 @@ module Philiprehberger
         status >= 200 && status < 300
       end
 
+      # Returns true if the response was streamed.
+      #
+      # @return [Boolean]
+      def streaming?
+        @streaming
+      end
+
       # Parses the response body as JSON.
       #
       # @return [Hash, Array] Parsed JSON

data/lib/philiprehberger/http_client/retries.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module HttpClient
+    # Retry logic extracted from Connection to keep module length manageable.
+    module Retries
+      private
+
+      def perform_with_retries(uri, request, **timeout_opts, &block)
+        attempts = 0
+        loop do
+          response = perform_request(uri, request, **timeout_opts, &block)
+          return response unless retry_on_status?(response.status, attempts)
+
+          wait_and_retry(attempts += 1)
+        rescue *Connection::TIMEOUT_ERRORS => e
+          handle_retry_error(attempts += 1, TimeoutError, e.message)
+        rescue *Connection::NETWORK_ERRORS => e
+          handle_retry_error(attempts += 1, NetworkError, e.message)
+        end
+      end
+
+      def handle_retry_error(attempts, error_class, message)
+        raise error_class, message unless attempts <= @retries
+
+        sleep(retry_delay_for(attempts))
+      end
+
+      def retry_on_status?(status, attempts)
+        @retry_on_status&.include?(status) && attempts < @retries
+      end
+
+      def wait_and_retry(attempt)
+        sleep(retry_delay_for(attempt))
+      end
+
+      def retry_delay_for(attempt)
+        @retry_backoff == :exponential ? @retry_delay * (2**(attempt - 1)) : @retry_delay
+      end
+    end
+  end
+end

data/lib/philiprehberger/http_client/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module HttpClient
-    VERSION = "0.3.1"
+    VERSION = "0.4.0"
   end
 end

data/lib/philiprehberger/http_client.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "http_client/version"
+require_relative "http_client/errors"
 require_relative "http_client/response"
+require_relative "http_client/multipart"
+require_relative "http_client/retries"
+require_relative "http_client/body_encoder"
 require_relative "http_client/connection"
 require_relative "http_client/client"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-http_client
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-13 00:00:00.000000000 Z
+date: 2026-03-17 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.
@@ -22,9 +22,13 @@ files:
 - LICENSE
 - README.md
 - lib/philiprehberger/http_client.rb
+- lib/philiprehberger/http_client/body_encoder.rb
 - lib/philiprehberger/http_client/client.rb
 - lib/philiprehberger/http_client/connection.rb
+- lib/philiprehberger/http_client/errors.rb
+- lib/philiprehberger/http_client/multipart.rb
 - lib/philiprehberger/http_client/response.rb
+- lib/philiprehberger/http_client/retries.rb
 - lib/philiprehberger/http_client/version.rb
 homepage: https://github.com/philiprehberger/rb-http-client
 licenses: