chimera_http_client 1.7.1 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27502b5b2a10f00e43634863b14ce3d3d7ac3b957a9bcde7f239e0ee73124f55
-  data.tar.gz: bd5697952a9e4a24b54e6fffb32ca6aadef39c28404bdfd60f00d0c1dd611f11
+  metadata.gz: ca5968573054108171952f955ef7974120a4d4725ed1ca34af29e3d40e831c61
+  data.tar.gz: 3f8adfc58275d048326c4cb25c93cc46d637195da9eb042e1c6388d705e3dc54
 SHA512:
-  metadata.gz: 4db5ae181cefef0408b6e2f9586c96f0a311211b7d6b71a9c7ddf3960acb906e7873620b338b8231f42fd3ff999a9c3eeacd98a6f56d2e7345f1704f00bcca93
-  data.tar.gz: 515e85c5020b526c6d9d064987355b9c28652ecd9b628d63de176a6dfffbe7fb273a2b7527ae0a9d4aee8128ea5d4cb8f89426f48c4b1d6e778c7d49481b4af5
+  metadata.gz: b00e1318e81f48ea6897e384062ab4e30b9ca83d1dc4549a22ecf8df9ce1940806c47fd04f8bf2f1109cd58922bee78605622fedc61bc74e5fb15d4be7dc0184
+  data.tar.gz: 494531a305d3bb571e98d9da1f6ad69330b64de19d29ed8d4cd64a3218fdc92bc3c2c499f7b88b829f714abc5f291654b09d364dff7577e83d6ff3080b68c6ae

data/.github/workflows/action-ci.yml

@@ -1,25 +1,68 @@
-name: rubies-ci
+name: Ruby CI
+
 on:
-  pull_request:
   push:
-    branches: [ main ]
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
 jobs:
   test:
+    name: Test on ${{ matrix.os }} / ${{ matrix.ruby }}
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest] # macos-latest
-        ruby: ['3.3', '3.4', 'truffleruby', 'jruby']
-        # add 'truffleruby', 'jruby', for releases - and remember to use quotes due to https://github.com/actions/runner/issues/849
+        os: [ubuntu-latest]
+        ruby: ['3.3', '3.4', '4.0']
+        experimental: [false]
+        # add certain optional combos whose failures won't block merges:
+        include:
+          - os: macos-latest
+            ruby: '4.0'
+            experimental: true
+          - os: ubuntu-latest
+            ruby: 'truffleruby'
+            experimental: true
+          - os: ubuntu-latest
+            ruby: 'jruby'
+            experimental: true
+          - os: windows-latest
+            ruby: '4.0'
+            experimental: true
 
-    runs-on: ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}    
 
     steps:
-    - uses: actions/checkout@v4
-    - uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby }}
-        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
-
-    - name: Run linters and test suite
-      run: bundle exec rake ci
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Set up Java for JRuby
+        if: ${{ matrix.ruby == 'jruby' }}
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '25'
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Print versions
+        run: |
+          ruby -v
+          gem -v
+          bundle -v
+
+      - name: Run linters and test suite
+        continue-on-error: ${{ matrix.experimental }}
+        run: bundle exec rake ci

data/.rubocop.yml

@@ -54,6 +54,11 @@ RSpec/MultipleMemoizedHelpers:
 RSpec/NestedGroups:
   Max: 4
 
+RSpec/Output:
+  Exclude:
+    - spec/server_spec_helper.rb
+    - spec/chimera_http_client/server/connection_options_spec.rb
+
 RSpec/PendingWithoutReason:
    Enabled: false
 

data/.ruby-version

@@ -1 +1 @@
-3.4.4
+4.0.6

data/README.markdown

@@ -17,57 +17,65 @@ The only other runtime dependency is Ruby's latest code loader [**zeitwerk**](ht
 ^
 ### Ruby version
 
-| Chimera version | MRI Ruby version                                    | JRuby | TruffleRuby |
-|:----------------|:----------------------------------------------------|:-----:|:-----------:|
-| >= 1.7          | >= 3.3 (older versions untested, likely still work) |  yes  |     yes     |
-| >= 1.6          | >= 2.7 (all 3.x versions supported)                 |  yes  |     yes     |
-| >= 1.4          | >= 2.5 (3.0 compatibility ensured)                  |  yes  |     no      |
-| >= 1.1          | >= 2.5                                              |   ?   |      ?      |
-| =  1.0          | >= 2.4, <= 3.0                                      |   ?   |      ?      |
-| <= 0.5          | >= 2.1, <= 3.0                                      |   ?   |      ?      |
+| Chimera version | MRI Ruby version                                                     | JRuby | TruffleRuby |
+|:----------------|:---------------------------------------------------------------------|:-----:|:-----------:|
+| >= 1.8          | >= 3.3 (4.0 supported, older versions untested, likely still work)   |  yes  |     yes     |
+| >= 1.7          | >= 3.3 (older versions untested, likely still work)                  |  yes  |     yes     |
+| >= 1.6          | >= 2.7 (all 3.x versions supported)                                  |  yes  |     yes     |
+| >= 1.4          | >= 2.5 (3.0 compatibility ensured)                                   |  yes  |     no      |
+| >= 1.1          | >= 2.5                                                               |   ?   |      ?      |
+| =  1.0          | >= 2.4, <= 3.0                                                       |   ?   |      ?      |
+| <= 0.5          | >= 2.1, <= 3.0                                                       |   ?   |      ?      |
 
 The test suite of v1.4 passes on **MRI Ruby** (2.5, 2.6, 2.7, 3.0) and on **JRuby**, but not on **TruffleRuby**.  
 The test suite of v1.6 passes on **MRI Ruby** (2.7, 3.0, 3.1, 3.2, 3.3) and on **JRuby** and **TruffleRuby**.  
-The non-MRI Rubys are not part of the regular Matrix, as their CI jobs take 3x as long, but included for new releases.
+v1.8 is no longer tested against MRI Rubies older than 3.3 (but they are likely still supported).  
+All information above is given for **Linux**.  
+**MacOS & Windows** were only tested successfully against **MRI Ruby 4.0** (older versions likely work as well).
 
 ### ENV variables
 
 Setting the environment variable `ENV['CHIMERA_HTTP_CLIENT_LOG_REQUESTS']` to `true` (or `'true'`) will provide more detailed error messages for logging and also add additional information to the Error JSON. It is recommended to use this only in development environments.
 
+Setting `ENV['CHIMERA_HTTP_CLIENT_DEFAULT_HEADERS']` to a JSON object string will merge those headers into every `Connection`/`Queue` in the process, e.g. `export CHIMERA_HTTP_CLIENT_DEFAULT_HEADERS='{"X-Service-Name":"orders-api"}'`. This is meant for deployment/ops-level defaults (like identifying which service is calling), set once outside application code. See [Custom headers](#custom-headers) below.
+
 ## Table of Contents
 
 <!-- TOC depthFrom:1 depthTo:4 withLinks:1 updateOnSave:0 orderedList:0 -->
 
-* [ChimeraHttpClient](#chimerahttpclient)
-  * [Dependencies](#dependencies)
-    * [Ruby version](#ruby-version)
-    * [ENV variables](#env-variables)
-  * [Table of Contents](#table-of-contents)
-  * [The Connection class](#the-connection-class)
-    * [Initialization](#initialization)
-      * [Mandatory initialization parameter `base_url`](#mandatory-initialization-parameter-base_url)
-      * [Optional initialization parameters](#optional-initialization-parameters)
-        * [Custom deserializers](#custom-deserializers)
-        * [Monitoring, metrics, instrumentation](#monitoring-metrics-instrumentation)
-    * [Request methods](#request-methods)
-      * [Mandatory request parameter `endpoint`](#mandatory-request-parameter-endpoint)
-      * [Optional request parameters](#optional-request-parameters)
-      * [Basic auth](#basic-auth)
-      * [Timeout duration](#timeout-duration)
-      * [Custom logger](#custom-logger)
-      * [Caching responses](#caching-responses)
-    * [Example usage](#example-usage)
-  * [The Request class](#the-request-class)
-  * [The Response class](#the-response-class)
-  * [Error classes](#error-classes)
-  * [The Queue class](#the-queue-class)
-    * [Queueing requests](#queueing-requests)
-    * [Executing requests in parallel](#executing-requests-in-parallel)
-    * [Empty the queue](#empty-the-queue)
-  * [Installation](#installation)
-  * [Maintainers and Contributors](#maintainers-and-contributors)
-    * [Roadmap](#roadmap)
-  * [Chimera](#chimera)
+- [ChimeraHttpClient](#chimerahttpclient)
+  - [Dependencies](#dependencies)
+    - [Ruby version](#ruby-version)
+    - [ENV variables](#env-variables)
+  - [Table of Contents](#table-of-contents)
+  - [The Connection class](#the-connection-class)
+    - [Initialization](#initialization)
+      - [Mandatory initialization parameter `base_url`](#mandatory-initialization-parameter-base_url)
+      - [Optional initialization parameters](#optional-initialization-parameters)
+        - [Custom deserializers](#custom-deserializers)
+        - [Custom headers](#custom-headers)
+        - [Custom serializer](#custom-serializer)
+        - [Monitoring, metrics, instrumentation](#monitoring-metrics-instrumentation)
+    - [Request methods](#request-methods)
+      - [Mandatory request parameter `endpoint`](#mandatory-request-parameter-endpoint)
+      - [Optional request parameters](#optional-request-parameters)
+      - [Basic auth](#basic-auth)
+      - [Timeout duration](#timeout-duration)
+      - [Retrying requests](#retrying-requests)
+      - [Custom logger](#custom-logger)
+      - [Caching responses](#caching-responses)
+    - [Example usage](#example-usage)
+  - [The Request class](#the-request-class)
+  - [The Response class](#the-response-class)
+  - [Error classes](#error-classes)
+  - [The Queue class](#the-queue-class)
+    - [Queueing requests](#queueing-requests)
+    - [Executing requests in parallel](#executing-requests-in-parallel)
+    - [Empty the queue](#empty-the-queue)
+  - [Installation](#installation)
+  - [Maintainers and Contributors](#maintainers-and-contributors)
+    - [Roadmap](#roadmap)
+  - [Chimera](#chimera)
 
 <!-- /TOC -->
 
@@ -96,8 +104,12 @@ The optional parameters are:
 
 * `cache` - an instance of your cache solution, can be overwritten in any request
 * `deserializers` - custom methods to deserialize the response body, below more details
+* `headers` - override/extend the default request headers (`{ "Content-Type" => "application/json" }`), can be overwritten or merged with per-request headers, below more details
 * `logger` - an instance of a logger class that implements `#info`, `#warn` and `#error` methods
 * `monitor` - to collect metrics about requests, the basis for your instrumentation needs
+* `retries` - the number of times a failed idempotent request is retried, can be overwritten in any request, the default is `0` (no retries)
+* `retry_delay` - the base delay in seconds between retries, can be overwritten in any request, the default is `1`
+* `serializer` - override how a Hash/Array request body is turned into a request, can be overwritten in any request, below more details
 * `timeout` - the timeout for all requests, can be overwritten in any request, the default are 3 seconds
 * `user_agent` - if you would like your calls to identify with a specific user agent
 * `verbose` - the default is `false`, set it to true while debugging issues
@@ -112,7 +124,64 @@ A Deserializer has to be an object on which the method `call` with the parameter
 
     custom_deserializer.call(body)
 
-where `body` is the response body (in the default case a JSON object). The class `Deserializer` contains the default objects that are used. They might help you creating your own. Don't forget to make requests with another header than the default `"Content-Type" => "application/json"`, when the API you connect to does not support JSON.
+where `body` is the response body (in the default case a JSON object). The class `Deserializer` contains the default objects that are used. They might help you creating your own. If the API you connect to does not support JSON, set `headers` (see [Custom headers](#custom-headers) below) once on the `Connection` instead of repeating it on every request - and see [Custom serializer](#custom-serializer) below for the equivalent on the request-body side.
+
+##### Custom headers
+
+Every request sends `{ "Content-Type" => "application/json" }` plus a `User-Agent` by default. Four layers apply on top of each other (each one merges in, overriding only the keys it sets, so you never have to restate headers you're not changing):
+
+1. the built-in default above (also available as `ChimeraHttpClient::Base::DEFAULT_HEADERS`)
+2. `ENV['CHIMERA_HTTP_CLIENT_DEFAULT_HEADERS']`, a JSON object (see [ENV variables](#env-variables) above)
+3. `headers` passed to `Connection.new`/`Queue.new` - the connection's own default
+4. `headers` passed to an individual request - already documented above, unchanged
+
+```ruby
+# connecting to a non-JSON API: override just Content-Type, everything else (User-Agent, ...) still applies
+connection = ChimeraHttpClient::Connection.new(base_url: 'http://localhost:3000/v1', headers: { "Content-Type" => "application/xml" })
+```
+
+A common use for the connection-level `headers` option is a request/correlation id that should be attached to every call made for one unit of work (a background job, one inbound request being served), without every call site needing to know about it:
+
+```ruby
+connection = ChimeraHttpClient::Connection.new(base_url: 'http://localhost:3000/v1', headers: { "X-Request-Id" => job_id })
+```
+
+For something that's the same for every request in the whole process instead - e.g. identifying which of your services is calling, in a service-to-service setting - set it once via `ENV['CHIMERA_HTTP_CLIENT_DEFAULT_HEADERS']` at the deployment level rather than in application code:
+
+```bash
+export CHIMERA_HTTP_CLIENT_DEFAULT_HEADERS='{"X-Service-Name":"orders-api"}'
+```
+
+##### Custom serializer
+
+A `Hash` or `Array` `body` is automatically serialized before the request is sent - by default with `body.to_json`, so this now just works:
+
+```ruby
+connection.post!('users', body: { name: "Andy" }) # no more body.to_json needed
+```
+
+A `String` body (e.g. one you already serialized yourself) is always passed through completely unchanged - so any existing code still doing `body: body.to_json` keeps working exactly as before.
+
+To use a different format, pass `serializer` to `Connection.new`/`Queue.new`, or to an individual request. A Serializer has to be an object on which the method `call` with the parameter `body` can be called:
+
+    custom_serializer.call(body)
+
+```ruby
+# talking to an XML API instead
+connection = ChimeraHttpClient::Connection.new(base_url: 'http://localhost:3000/v1', serializer: ->(body) { body.to_xml })
+```
+
+The serializer normally returns a `String`, but it can also return the `Hash` unconverted - Typhoeus (via Ethon/libcurl) then form-encodes it natively as `application/x-www-form-urlencoded`, or as real multipart if a value looks file-shaped:
+
+```ruby
+# posting a plain form instead of JSON
+connection.post(
+  'login',
+  body: { username: "andy", password: "secret" },
+  serializer: ->(body) { body }, # hand the Hash to Typhoeus/Ethon unconverted
+  headers: { "Content-Type" => "application/x-www-form-urlencoded" }
+)
+```
 
 ##### Monitoring, metrics, instrumentation
 
@@ -171,6 +240,9 @@ All request methods expect a mandatory `endpoint` and an optional hash as parame
 * `password` - used for a BasicAuth login
 * `timeout` - set a custom timeout per request (the default is 3 seconds)
 * `cache` - optionally overwrite the cache store set in `Connection` in any request
+* `retries` - optionally overwrite the number of retries set in `Connection` for this request
+* `retry_delay` - optionally overwrite the retry delay set in `Connection` for this request
+* `serializer` - optionally overwrite the body serializer set in `Connection` for this request
 * `monitoring_context` - pass additional information you want to collect with your instrumentation `monitor`
 
 Example:
@@ -197,6 +269,24 @@ The default timeout duration is **3 seconds**.
 
 If you want to use a different timeout, you can pass the key `timeout` when initializing the `Connection`. You can also overwrite it on every call.
 
+#### Retrying requests
+
+Pass `retries` (and optionally `retry_delay`) to `Connection.new`/`Queue.new`, or to any individual request, to automatically retry on transient failures:
+
+```ruby
+connection = ChimeraHttpClient::Connection.new(base_url: 'http://localhost:3000/v1', retries: 3, retry_delay: 1)
+```
+
+* `retries` - the maximum number of retry attempts. The default is `0` (no retries, fully opt-in).
+* `retry_delay` - the base delay in seconds before the first retry. The default is `1`. Each subsequent retry doubles the previous delay (a fixed 2x backoff, not configurable): with `retry_delay: 1` the delays are `1s, 2s, 4s, ...`.
+
+Retries are automatic and safe by design - they only apply to:
+
+* **idempotent methods**: `get`, `put`, `delete`, `head` - never `post`/`patch`, regardless of the configured `retries`, since retrying a non-idempotent write could duplicate side effects.
+* **transient errors**: `ConnectionError`, `TimeoutError`, `ServerError` (5xx) - never 4xx `ClientError`s, since retrying those can't change the outcome.
+
+> Note for `Queue`: retries are implemented by re-queueing the failed request onto the same `Typhoeus::Hydra` that's already running the batch, so a retry can start as soon as its own request fails rather than waiting for the whole batch. One consequence: the `retry_delay` sleep happens inside that request's completion callback, which briefly pauses progress on *every other* in-flight request in the same queue (libcurl's multi interface is a single-threaded, cooperative event loop). This doesn't affect `Connection`, whose retries run sequentially with nothing else in flight.
+
 #### Custom logger
 
 By default no logging is happening. If you need request logging, you can pass your custom Logger to the key `logger` when initializing the `Connection`. It will write to `logger.info` when starting and when completing a request.
@@ -287,7 +377,7 @@ class Users
   # CREATE a new user by sending attributes in a JSON body and instantiate the new User
   #
   def create(body:)
-    response = connection.post!('users', body: body.to_json) # body.to_json (!!)
+    response = connection.post!('users', body: body) # a Hash body is serialized to JSON automatically
 
     user = response.parsed_body
     User.new(id: user['id'], name: user['name'], email: user['email'])
@@ -322,7 +412,7 @@ To create and fetch a user from a remote service with the `Users` wrapper listed
 
 Usually it does not have to be used directly. It is the class that executes the `Typhoeus::Requests`, raises `Errors` on failing and returns `Response` objects on successful calls.
 
-The `body` which it receives from the `Connection` class has to be in the in the (serialized) form in which the endpoint expects it. Usually this means you have to pass a JSON string to the `body` (it will **not** be serialized automatically).
+By the time `Request` receives `body`, it's already in the (serialized) form the endpoint expects: `Connection`/`Queue` auto-serialize a `Hash`/`Array` body to JSON (or via a custom `serializer`, see [Custom serializer](#custom-serializer)) before it ever reaches `Request`. A `String` body is passed through unchanged.
 
 ## The Response class
 
@@ -434,8 +524,8 @@ After checking out the repo, run `bundle install` and then `bundle execute rake`
 
 > The test suite uses a Sinatra server to make real HTTP requests. It is mounted via Capybara_discoball and running in the same process. It is still running reasonably fast (on my MacBook Air):
 
-    Finished in 2.01 seconds (files took 1.09 seconds to load)
-    824 examples, 0 failures, 7 pending
+    Finished in 1.02 seconds (files took 0.43805 seconds to load)  
+    882 examples, 0 failures, 7 pending
 
 You can also run `rake console` to open an irb session with the `ChimeraHttpClient` pre-loaded that will allow you to experiment.
 

data/TODO.markdown

@@ -22,6 +22,12 @@ _none known_
 * [x] ~~use custom deserializer in #parsed_body instead of default JSON parsing~~
 * [x] ~~add example to README~~
 
+### ~~Custom serializer~~
+
+* [x] ~~allow to pass custom serializer~~
+* [x] ~~use custom serializer with body instead of default JSON serialization ~~
+* [x] ~~add example to README~~
+
 ### Queueing / running in parallel
 
 * [x] ~~allow to queue multiple requests~~
@@ -79,12 +85,12 @@ _none known_
 * [ ] enable to pass on_headers, on_body, on_complete procs
 * [ ] add example to README
 
-### HTTP Headers
+### ~~HTTP Headers~~
 
-* [ ] make Connection#default_headers configurable
-* [ ] allow to set default_headers via ENV vars
-* [ ] give example how to use default_headers (e.g. request_id)
-* [ ] explain in README how to benefit from this gem in a given setting
+* [x] ~~make Connection#default_headers configurable~~
+* [x] ~~allow to set default_headers via ENV vars~~
+* [x] ~~give example how to use default_headers (e.g. request_id)~~
+* [x] ~~explain in README how to benefit from this gem in a given setting~~
 
 ### ~~Caching~~
 
@@ -105,15 +111,13 @@ _none known_
 * [x] ~~hook up Travis-CI~~
 * [x] ~~ensure it runs with Ruby 2.4 and newer~~
 
-### Retry Requests
+### ~~Retry Requests~~
 
-* [ ] either leverage Hydra to retry failed calls
-  * [ ] configure number of retries
-  * [ ] configure delay between retries
-  * [ ] retry idempotent calls GET, PUT, DELETE, HEAD automatically
-* [ ] maybe implement retries with wait and Redis (external dependency!)
-* [ ] or document in README how to build a retry mechanism
-  * [ ] https://gist.github.com/kunalmodi/2939288
+* [x] ~~leverage Hydra to retry failed calls (Queue); Connection uses a sequential retry loop instead~~
+  * [x] ~~configure number of retries~~
+  * [x] ~~configure delay between retries~~
+  * [x] ~~retry idempotent calls GET, PUT, DELETE, HEAD automatically~~
+* [x] ~~add example to README~~
 
 ### Queueing / run requests serialized
 

data/chimera_http_client.gemspec

@@ -40,9 +40,9 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "irb",                ">= 1.15"
   spec.add_development_dependency "rake",               ">= 13.2"
   spec.add_development_dependency "rspec",              "~> 3.13"
-  spec.add_development_dependency "rubocop",            "~> 1.75.7"
-  spec.add_development_dependency "rubocop-rake",       "~> 0.7.1"
-  spec.add_development_dependency "rubocop-rspec",      "~> 3.6.0"
+  spec.add_development_dependency "rubocop",            "~> 1.75"
+  spec.add_development_dependency "rubocop-rake",       "~> 0.7"
+  spec.add_development_dependency "rubocop-rspec",      "~> 3.10"
 
   # only for server specs with real HTTP requests
   spec.add_development_dependency "capybara",           "~> 3.40"

data/lib/chimera_http_client/base.rb

@@ -1,18 +1,24 @@
 module ChimeraHttpClient
   class Base
     USER_AGENT = "ChimeraHttpClient (by mediafinger)".freeze
+    DEFAULT_HEADERS = { "Content-Type" => "application/json" }.freeze
+    DEFAULT_HEADERS_ENV_VAR = "CHIMERA_HTTP_CLIENT_DEFAULT_HEADERS".freeze
 
     def initialize(options = {})
       fail(ChimeraHttpClient::ParameterMissingError, "base_url expected, but not given") if options[:base_url].nil?
 
       @base_url = options.fetch(:base_url)
       @deserializer = default_deserializer.merge(options.fetch(:deserializer, {}))
+      @serializer = options.fetch(:serializer, ::ChimeraHttpClient::Serializer.json)
       @logger = options[:logger]
       @monitor = options[:monitor]
       @timeout = options[:timeout]
       @cache = options[:cache]
+      @headers = DEFAULT_HEADERS.merge(headers_from_env).merge(options[:headers] || {})
       @user_agent = options.fetch(:user_agent, USER_AGENT)
       @verbose = options.fetch(:verbose, false)
+      @retries = options[:retries] || 0
+      @retry_delay = options[:retry_delay] || 1
     end
 
     private
@@ -22,6 +28,8 @@ module ChimeraHttpClient
       options[:timeout] ||= @timeout
       options[:cache] = @cache if options[:cache].nil?
       options[:verbose] = @verbose if options[:verbose].nil?
+      options[:retries] = @retries if options[:retries].nil?
+      options[:retry_delay] = @retry_delay if options[:retry_delay].nil?
 
       options
     end
@@ -29,10 +37,13 @@ module ChimeraHttpClient
     def extract_body(options)
       body = options.delete(:body)
       body_optional = options.delete(:body_optional)
+      serializer = options.delete(:serializer) || @serializer
 
       fail(ChimeraHttpClient::ParameterMissingError, "body expected, but not given") if body.nil? && !body_optional
 
-      body
+      return body unless body.is_a?(Hash) || body.is_a?(Array)
+
+      serializer.call(body)
     end
 
     def extract_headers(options, headers)
@@ -41,7 +52,16 @@ module ChimeraHttpClient
     end
 
     def default_headers
-      { "Content-Type" => "application/json", "User-Agent" => @user_agent }
+      @headers.merge("User-Agent" => @user_agent)
+    end
+
+    def headers_from_env
+      raw = ENV[DEFAULT_HEADERS_ENV_VAR].to_s
+      return {} if raw.strip.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError => e
+      raise(ChimeraHttpClient::ParameterMissingError, "ENV['#{DEFAULT_HEADERS_ENV_VAR}'] is not valid JSON: #{e.message}")
     end
 
     def default_deserializer

data/lib/chimera_http_client/queue.rb

@@ -42,6 +42,7 @@ module ChimeraHttpClient
         deserializer: @deserializer,
         logger: @logger,
         monitor: @monitor,
+        hydra: hydra,
       }
 
       Request.new(instance_options).create(

data/lib/chimera_http_client/request.rb

@@ -2,10 +2,20 @@ module ChimeraHttpClient
   class Request
     TIMEOUT_SECONDS = 3
 
+    # Only idempotent methods are retried automatically, regardless of the configured retries count
+    RETRYABLE_METHODS = %i(get put delete head).freeze
+
+    # Only network failures and 5xx are retried - 4xx client errors can't be fixed by retrying
+    RETRYABLE_ERRORS = [ConnectionError, TimeoutError, ServerError].freeze
+
+    RETRY_BACKOFF_MULTIPLIER = 2
+
     attr_reader :request, :result
 
     def initialize(options = {})
       @options = options
+      @hydra = options[:hydra]
+      @attempt = 0
     end
 
     def run(url:, method:, body: nil, options: {}, headers: {})
@@ -13,6 +23,15 @@ module ChimeraHttpClient
 
       @request.run
 
+      attempt = 0
+      while retryable?(method, @result, options, attempt)
+        attempt += 1
+        sleep(delay_for(attempt, options))
+
+        create(url: url, method: method, body: body, options: options, headers: headers)
+        @request.run
+      end
+
       @result
     end
 
@@ -57,7 +76,21 @@ module ChimeraHttpClient
           }
         )
 
-        @result = on_complete_handler(response)
+        result = on_complete_handler(response)
+
+        # Used for queued requests (Queue): retries are re-queued onto the same Hydra from
+        # inside this callback, per Typhoeus::Hydra::Queueable#queue ("can even be done while
+        # the hydra is running"). Connection-built requests never have a @hydra, so this branch
+        # never triggers for them - their retries are handled by the loop in #run instead.
+        if @hydra && retryable?(method, result, options, @attempt)
+          @attempt += 1
+          sleep(delay_for(@attempt, options))
+
+          create(url: url, method: method, body: body, options: options, headers: headers)
+          @hydra.queue(@request)
+        else
+          @result = result
+        end
       end
 
       @options[:logger]&.info(
@@ -76,6 +109,18 @@ module ChimeraHttpClient
 
     private
 
+    def retryable?(method, result, options, attempt)
+      result.error? &&
+        RETRYABLE_METHODS.include?(method) &&
+        RETRYABLE_ERRORS.any? { |klass| result.is_a?(klass) } &&
+        attempt < options[:retries].to_i
+    end
+
+    # Delay before retry attempt n (1-indexed): retry_delay * RETRY_BACKOFF_MULTIPLIER**(n - 1)
+    def delay_for(attempt, options)
+      options[:retry_delay].to_f * (RETRY_BACKOFF_MULTIPLIER**(attempt - 1))
+    end
+
     def on_complete_handler(response)
       return Response.new(response, @options) if response.success?
 

data/lib/chimera_http_client/serializer.rb

@@ -0,0 +1,23 @@
+# The default JSON serializer for request bodies.
+#
+# To use a custom serializer, pass it as a param to Connection.new or Queue.new:
+# `serializer: your_serializer`
+# or override it for a single request: `connection.post(endpoint, body: {...}, serializer: your_serializer)`
+#
+# A Serializer has to be an object on which the method `call` with the parameter `body` can be called:
+# `custom_serializer.call(body)`
+# It is only ever invoked for a Hash or Array body - anything else (e.g. an already-serialized
+# String) is passed to the request unchanged. It normally returns a String, but may also return
+# a Hash - Typhoeus/Ethon will then form-encode it natively (application/x-www-form-urlencoded,
+# or multipart if a value looks file-shaped), so an identity serializer (`->(body) { body }`) is
+# a valid way to opt into that instead of JSON.
+#
+module ChimeraHttpClient
+  class Serializer
+    class << self
+      def json
+        proc { |body| body.to_json }
+      end
+    end
+  end
+end

data/lib/chimera_http_client/version.rb

@@ -1,3 +1,3 @@
 module ChimeraHttpClient
-  VERSION = "1.7.1".freeze
+  VERSION = "1.9.0".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chimera_http_client
 version: !ruby/object:Gem::Version
-  version: 1.7.1
+  version: 1.9.0
 platform: ruby
 authors:
 - Andreas Finger
@@ -127,42 +127,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.75.7
+        version: '1.75'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.75.7
+        version: '1.75'
 - !ruby/object:Gem::Dependency
   name: rubocop-rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.7.1
+        version: '0.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.7.1
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.6.0
+        version: '3.10'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.6.0
+        version: '3.10'
 - !ruby/object:Gem::Dependency
   name: capybara
   requirement: !ruby/object:Gem::Requirement
@@ -292,6 +292,7 @@ files:
 - lib/chimera_http_client/queue.rb
 - lib/chimera_http_client/request.rb
 - lib/chimera_http_client/response.rb
+- lib/chimera_http_client/serializer.rb
 - lib/chimera_http_client/version.rb
 homepage: https://github.com/mediafinger/chimera_http_client
 licenses:
@@ -312,7 +313,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.16
 specification_version: 4
 summary: General http client functionality to quickly connect to JSON REST API endpoints
   and any others