chimera_http_client 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ad28c45175797378cfcab81479167a9d76538f1f438a82c5f79cedd48bb90dc
-  data.tar.gz: f6aa79792c873c5ba537ff8d3a0885871a3040471b4aae93a6c7f29156aece1a
+  metadata.gz: b13d3c092d285089ec23e09429db2129e3095c398ed1e829800bbcd0574e5c49
+  data.tar.gz: 8a646ce583338f381130879c86801349af06de6f2b32e19ab0a6a5d6677d8303
 SHA512:
-  metadata.gz: 8cec762f1ff0088d978d9c6b1eae68157ea8fd6058e14192ff2b2fe3d07d54e0d9573f89f6a64f4860380a2fb61232f550f3e782869274a6d36ba47ce0579eac
-  data.tar.gz: 843ff440917c8af2bdf1b7c662d39b4ef481f736ee7be6776d2bc958de1c36f1d591ab81c7cd206eaf269e0d28354b84962dbf5264b5323bac357d0fb691ecc2
+  metadata.gz: b2813b2933fa8488973c345392fe879ac64b827180fa1d01dc872f83e13e23ebd4b9e95d9e3d7c17e457a9b73f293812d582a0fa9e22168a36abbb09439715cd
+  data.tar.gz: 5ec92f4d71bc1925f2e8b3db89b50ec237b554f7ff4d3ac65edc13dd6fd6200aa56ed1aba060e85afd325512eadfeb81fcdb83471995ca015010bbdcea8356b6

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,18 +17,21 @@ 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
 
@@ -38,36 +41,37 @@ Setting the environment variable `ENV['CHIMERA_HTTP_CLIENT_LOG_REQUESTS']` to `t
 
 <!-- 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)
+        - [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 -->
 
@@ -98,6 +102,8 @@ The optional parameters are:
 * `deserializers` - custom methods to deserialize the response body, 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`
 * `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
@@ -171,6 +177,8 @@ 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
 * `monitoring_context` - pass additional information you want to collect with your instrumentation `monitor`
 
 Example:
@@ -197,6 +205,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.
@@ -434,8 +460,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

@@ -105,15 +105,13 @@ _none known_
 * [x] ~~hook up Travis-CI~~
 * [x] ~~ensure it runs with Ruby 2.4 and newer~~
 
-### 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
+### ~~Retry Requests~~
+
+* [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

@@ -10,11 +10,11 @@ module ChimeraHttpClient
       @logger = options[:logger]
       @monitor = options[:monitor]
       @timeout = options[:timeout]
-
-      Typhoeus::Config.cache = options[:cache]
-      Typhoeus::Config.memoize = false # hydra setting, prevents a possible memory leak
-      Typhoeus::Config.user_agent = options.fetch(:user_agent, USER_AGENT)
-      Typhoeus::Config.verbose = options.fetch(:verbose, false)
+      @cache = options[:cache]
+      @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 +22,10 @@ module ChimeraHttpClient
     # Add default values to call options
     def augmented_options(options)
       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
@@ -41,7 +45,7 @@ module ChimeraHttpClient
     end
 
     def default_headers
-      { "Content-Type" => "application/json" }
+      { "Content-Type" => "application/json", "User-Agent" => @user_agent }
     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
 
@@ -25,6 +44,7 @@ module ChimeraHttpClient
         timeout:         options[:timeout] || TIMEOUT_SECONDS,
         accept_encoding: "gzip",
         cache:           options[:cache],
+        verbose:         options[:verbose],
       }
 
       # Basic-auth support:
@@ -52,11 +72,25 @@ module ChimeraHttpClient
             url: url,
             code: response.code,
             runtime: runtime,
-            user_agent: Typhoeus::Config.user_agent,
+            user_agent: headers["User-Agent"],
           }
         )
 
-        @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(
@@ -66,7 +100,7 @@ module ChimeraHttpClient
           url: url,
           code: nil,
           runtime: 0,
-          user_agent: Typhoeus::Config.user_agent,
+          user_agent: headers["User-Agent"],
         }
       )
 
@@ -75,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/version.rb

@@ -1,3 +1,3 @@
 module ChimeraHttpClient
-  VERSION = "1.7.0".freeze
+  VERSION = "1.8.0".freeze
 end

data/lib/chimera_http_client.rb

@@ -8,4 +8,6 @@ module ChimeraHttpClient
 
   # as Zeitwerk can't handle innner classes properly :-/
   require_relative "chimera_http_client/error"
+
+  Typhoeus::Config.memoize = false # hydra setting, prevents a possible memory leak
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chimera_http_client
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.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
@@ -312,7 +312,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.16
 specification_version: 4
 summary: General http client functionality to quickly connect to JSON REST API endpoints
   and any others