http.rb 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 114eef76572ba0ee1ef7efbb61fe704870a80c9bdc7d45cd5fca467de12658f6
-  data.tar.gz: bc249e876babf5aa7a4369272675e6194fc25f1816d474ef8080ad107fa1c60c
+  metadata.gz: f8926fd82491288941f05e4ff3d38c0c000e31f214bd35f55462befa0ece73a3
+  data.tar.gz: ad696135489b778872649c052fb1f23eb05e151e7a04c29237510e997dba7d71
 SHA512:
-  metadata.gz: 516e828dced10204ba4b850904d7c195c027166b1dc0dcd575e09403ef5b26da936b925ab7fdfd4c0fb3c7a3e3cf8c44585a562ac647ffbf4451804b35aa9b9a
-  data.tar.gz: f3c7dc2350bd17d98abdfe9c2deb98b0923def00ea790fffbc8919280399cb5c3d5e65eaed530abb86850a54e2e790591a1c1e9f6a91a03ff2c90611c08d2760
+  metadata.gz: eb7f2d8945396de4151166fb3a2fc62a0bb47ac2636a9f157b04c67318f0c9c20d302aba00b8a0db21278fbeed559230b236fea674cb2cf4de3880fe22b09dce
+  data.tar.gz: bea5d01ffdab8e4a8fd876ec1b7353776b933d5e1259ea8c57aa4cbf4a8a6b3ba35950fa7bdc907b18bff84e5e7cbc972abbd1cc71398f37934834f176e9d86c

data/CHANGELOG

@@ -1,5 +1,15 @@
 # CHANGELOG
 
+# 20260522
+# 0.20.0: Add opt-in retry logic with exponential backoff.
+1. + lib/HTTP/RETRY.rb: Retry helpers (with_retries, backoff_delay, retry_after) and constants (HTTP::RETRY::EXCEPTIONS, STATUS_CODES, VERBS).
+2. ~ HTTP.request: Retry on transient network exceptions and retry-worthy HTTP status codes (429, 502, 503, 504) when enabled. Exponential backoff with jitter. Honours Retry-After when present. Disabled by default; opt in via the retries option. Configurable via new options: retries (default 0), retry_delay (default 1.0), retry_status_codes, retry_exceptions, retry_verbs. Only idempotent verbs (get, head, options, put, delete, trace) retry by default; opt in to POST/PATCH retries via retry_verbs.
+3. + spec/HTTP/RETRY_spec.rb: Specs for retry behaviour and the helpers.
+4. ~ README.md: + Retries section.
+5. ~ TODO: Annotate "Add retry logic to HTTP.request" as (Done as of 0.20.0); also annotate three previously-completed items as (Done as of 0.18.2), (Done as of 0.18.3), and (Done as of 0.19.0).
+6. ~ HTTP::VERSION: /0.19.0/0.20.0/
+7. ~ CHANGELOG: + 0.20.0 entry
+
 # 20260522
 # 0.19.0: Change default verify_mode to VERIFY_PEER.
 1. ~ HTTP.request: Default verify_mode changed from OpenSSL::SSL::VERIFY_NONE to OpenSSL::SSL::VERIFY_PEER. Callers needing the old behaviour can pass verify_mode: OpenSSL::SSL::VERIFY_NONE explicitly through the options hash.

data/README.md

@@ -84,6 +84,34 @@ HTTP.get('http://example.com', {}, {}, {no_redirect: true})
 # => #<Net::HTTPResponse @code=3xx>
 ```
 
+### Retries
+
+Retries are disabled by default. Enable them by passing `retries:` in the options hash.
+
+```ruby
+HTTP.get('http://example.com', {}, {}, {retries: 3})
+```
+
+When enabled, transient network exceptions and retry-worthy HTTP status codes (429, 502, 503, 504) are retried with exponential backoff and jitter. If the response carries a `Retry-After` header, it is honoured in place of the calculated delay.
+
+Only idempotent verbs (`get`, `head`, `options`, `put`, `delete`, `trace`) are retried by default. POST and PATCH are not — retrying a non-idempotent write can create duplicate resources against APIs that don't deduplicate. Opt in per-call via `retry_verbs:`.
+
+```ruby
+HTTP.post('http://example.com', {a: 1}, {}, {retries: 3, retry_verbs: %i{get post}})
+```
+
+Configurable options:
+
+```ruby
+options = {
+  retries: 3,                                   # max retry attempts; 0 disables
+  retry_delay: 1.0,                             # base delay (seconds) for exponential backoff
+  retry_status_codes: [429, 502, 503, 504],     # HTTP status codes to retry
+  retry_exceptions: HTTP::RETRY::EXCEPTIONS,    # exceptions to retry
+  retry_verbs: HTTP::RETRY::VERBS               # verbs that retry by default
+}
+```
+
 ### Response status predicate methods
 
 ```ruby

data/lib/HTTP/RETRY.rb

@@ -0,0 +1,76 @@
+# HTTP/RETRY.rb
+# HTTP::RETRY (retry helpers)
+
+require 'net/http'
+require 'socket'
+require 'time'
+
+module HTTP
+  module RETRY
+    EXCEPTIONS = [
+      Errno::ECONNREFUSED,
+      Errno::ECONNRESET,
+      Errno::ETIMEDOUT,
+      Errno::EHOSTUNREACH,
+      Errno::ENETUNREACH,
+      Net::OpenTimeout,
+      Net::ReadTimeout,
+      SocketError,
+      EOFError
+    ].freeze
+    STATUS_CODES = [429, 502, 503, 504].freeze
+    VERBS = %i{get head options put delete trace}.freeze
+
+    def self.sleep(seconds)
+      Kernel.sleep(seconds)
+    end
+  end
+
+  def retry_config(options)
+    {
+      retries: options.delete(:retries) || 0,
+      delay: options.delete(:retry_delay) || 1.0,
+      status_codes: options.delete(:retry_status_codes) || RETRY::STATUS_CODES,
+      exceptions: options.delete(:retry_exceptions) || RETRY::EXCEPTIONS,
+      verbs: options.delete(:retry_verbs) || RETRY::VERBS
+    }
+  end
+  module_function :retry_config
+
+  def with_retries(http, request_object, config)
+    attempt = 0
+    loop do
+      begin
+        response = http.request(request_object)
+        if config[:status_codes].include?(response.code.to_i) && attempt < config[:retries]
+          attempt += 1
+          RETRY.sleep(retry_after(response) || backoff_delay(config[:delay], attempt))
+          next
+        end
+        return response
+      rescue *config[:exceptions]
+        raise unless attempt < config[:retries]
+        attempt += 1
+        RETRY.sleep(backoff_delay(config[:delay], attempt))
+      end
+    end
+  end
+  module_function :with_retries
+
+  def backoff_delay(base, attempt)
+    base * (2 ** (attempt - 1)) * (1 + (rand - 0.5) * 0.4)
+  end
+  module_function :backoff_delay
+
+  def retry_after(response)
+    header = response['Retry-After']
+    return nil unless header
+    if header =~ /\A\d+\z/
+      header.to_i
+    else
+      # Malformed HTTP-date — fall through to caller's backoff.
+      Time.httpdate(header) - Time.now rescue nil
+    end
+  end
+  module_function :retry_after
+end

data/lib/HTTP/VERSION.rb

@@ -2,5 +2,5 @@
 # HTTP::VERSION
 
 module HTTP
-  VERSION = '0.19.0'
+  VERSION = '0.20.0'
 end

data/lib/HTTP/request.rb

@@ -9,18 +9,27 @@ require_relative '../Net/HTTP/set_options'
 require_relative '../Net/HTTPRequest/set_headers'
 require_relative '../Net/HTTPResponse/StatusPredicates'
 require_relative '../URI/Generic/use_sslQ'
+require_relative './RETRY'
 
 module HTTP
   def request(uri, request_object, headers = {}, options = {}, &block)
     uri = uri.is_a?(URI) ? uri : URI.parse(uri)
     http = Net::HTTP.new(uri.host, uri.port)
     no_redirect = options.delete(:no_redirect)
+    config = retry_config(options)
     options[:use_ssl] ||= uri.use_ssl?
     options[:verify_mode] ||= OpenSSL::SSL::VERIFY_PEER
     http.options = options
     request_object.headers = headers
     request_object.basic_auth(uri.user, uri.password) if uri.user
-    response = http.request(request_object)
+    verb = request_object.method.downcase.to_sym
+    response = (
+      if config[:retries] > 0 && config[:verbs].include?(verb)
+        with_retries(http, request_object, config)
+      else
+        http.request(request_object)
+      end
+    )
     if response.code =~ /^3/
       if block_given? && no_redirect
         yield response
@@ -29,7 +38,6 @@ module HTTP
       end
       redirect_uri = uri.merge(response.header['location'])
       if response.code =~ /^30[78]$/
-        verb = request_object.method.downcase.to_sym
         data = VERBS::WITH_BODY.include?(verb) ? request_object.body : {}
         response = send(verb, redirect_uri.to_s, data, headers, options, &block)
       else

data/spec/HTTP/RETRY_spec.rb

@@ -0,0 +1,251 @@
+# spec/HTTP/RETRY_spec.rb
+
+require_relative '../spec_helper'
+require 'http'
+
+describe "retry behaviour" do
+  let(:uri){'http://example.com/path'}
+
+  before do
+    allow(HTTP::RETRY).to receive(:sleep)
+  end
+
+  describe "defaults" do
+    it "does not retry by default" do
+      stub_request(:get, uri).to_return(status: 503)
+      response = HTTP.get(uri)
+      expect(response.code.to_i).to eq(503)
+      expect(WebMock).to have_requested(:get, uri).times(1)
+    end
+
+    it "does not retry on a transient exception by default" do
+      stub_request(:get, uri).to_raise(Errno::ECONNRESET)
+      expect{HTTP.get(uri)}.to raise_error(Errno::ECONNRESET)
+      expect(WebMock).to have_requested(:get, uri).times(1)
+    end
+  end
+
+  describe "retry on transient exception" do
+    it "retries and succeeds when the failure is transient" do
+      stub_request(:get, uri).
+        to_raise(Errno::ECONNRESET).then.
+        to_raise(Errno::ECONNRESET).then.
+        to_return(status: 200, body: '')
+      response = HTTP.get(uri, {}, {}, {retries: 3})
+      expect(response.success?).to eq(true)
+      expect(WebMock).to have_requested(:get, uri).times(3)
+    end
+
+    it "re-raises the exception after retries are exhausted" do
+      stub_request(:get, uri).to_raise(Errno::ECONNRESET)
+      expect{HTTP.get(uri, {}, {}, {retries: 2})}.to raise_error(Errno::ECONNRESET)
+      expect(WebMock).to have_requested(:get, uri).times(3)
+    end
+
+    it "retries on SocketError (DNS failure)" do
+      stub_request(:get, uri).
+        to_raise(SocketError).then.
+        to_return(status: 200, body: '')
+      response = HTTP.get(uri, {}, {}, {retries: 3})
+      expect(response.success?).to eq(true)
+      expect(WebMock).to have_requested(:get, uri).times(2)
+    end
+
+    it "does not retry on a non-listed exception" do
+      stub_request(:get, uri).to_raise(OpenSSL::SSL::SSLError)
+      expect{HTTP.get(uri, {}, {}, {retries: 3})}.to raise_error(OpenSSL::SSL::SSLError)
+      expect(WebMock).to have_requested(:get, uri).times(1)
+    end
+  end
+
+  describe "retry on status code" do
+    it "retries on 503 then succeeds" do
+      stub_request(:get, uri).
+        to_return({status: 503}, {status: 503}, {status: 200, body: ''})
+      response = HTTP.get(uri, {}, {}, {retries: 3})
+      expect(response.success?).to eq(true)
+      expect(WebMock).to have_requested(:get, uri).times(3)
+    end
+
+    it "retries on 502" do
+      stub_request(:get, uri).to_return({status: 502}, {status: 200, body: ''})
+      response = HTTP.get(uri, {}, {}, {retries: 3})
+      expect(response.success?).to eq(true)
+      expect(WebMock).to have_requested(:get, uri).times(2)
+    end
+
+    it "retries on 504" do
+      stub_request(:get, uri).to_return({status: 504}, {status: 200, body: ''})
+      response = HTTP.get(uri, {}, {}, {retries: 3})
+      expect(response.success?).to eq(true)
+      expect(WebMock).to have_requested(:get, uri).times(2)
+    end
+
+    it "does not retry on 500 by default" do
+      stub_request(:get, uri).to_return(status: 500)
+      response = HTTP.get(uri, {}, {}, {retries: 3})
+      expect(response.code.to_i).to eq(500)
+      expect(WebMock).to have_requested(:get, uri).times(1)
+    end
+
+    it "does not retry on 404" do
+      stub_request(:get, uri).to_return(status: 404)
+      response = HTTP.get(uri, {}, {}, {retries: 3})
+      expect(response.code.to_i).to eq(404)
+      expect(WebMock).to have_requested(:get, uri).times(1)
+    end
+
+    it "returns the last response when retries are exhausted" do
+      stub_request(:get, uri).to_return(status: 503)
+      response = HTTP.get(uri, {}, {}, {retries: 2})
+      expect(response.code.to_i).to eq(503)
+      expect(WebMock).to have_requested(:get, uri).times(3)
+    end
+  end
+
+  describe "Retry-After header" do
+    it "honours integer Retry-After on 429" do
+      stub_request(:get, uri).
+        to_return({status: 429, headers: {'Retry-After' => '2'}}, {status: 200, body: ''})
+      expect(HTTP::RETRY).to receive(:sleep).with(2)
+      response = HTTP.get(uri, {}, {}, {retries: 3})
+      expect(response.success?).to eq(true)
+    end
+
+    it "honours integer Retry-After on 503" do
+      stub_request(:get, uri).
+        to_return({status: 503, headers: {'Retry-After' => '5'}}, {status: 200, body: ''})
+      expect(HTTP::RETRY).to receive(:sleep).with(5)
+      response = HTTP.get(uri, {}, {}, {retries: 3})
+      expect(response.success?).to eq(true)
+    end
+  end
+
+  describe "configuration" do
+    it "treats retries: 0 as no retries" do
+      stub_request(:get, uri).to_return(status: 503)
+      response = HTTP.get(uri, {}, {}, {retries: 0})
+      expect(response.code.to_i).to eq(503)
+      expect(WebMock).to have_requested(:get, uri).times(1)
+    end
+
+    it "respects a custom retry_status_codes list" do
+      stub_request(:get, uri).to_return({status: 500}, {status: 200, body: ''})
+      response = HTTP.get(uri, {}, {}, {retries: 3, retry_status_codes: [500]})
+      expect(response.success?).to eq(true)
+      expect(WebMock).to have_requested(:get, uri).times(2)
+    end
+
+    it "respects a custom retry_exceptions list" do
+      stub_request(:get, uri).
+        to_raise(OpenSSL::SSL::SSLError).then.
+        to_return(status: 200, body: '')
+      response = HTTP.get(uri, {}, {}, {retries: 3, retry_exceptions: [OpenSSL::SSL::SSLError]})
+      expect(response.success?).to eq(true)
+      expect(WebMock).to have_requested(:get, uri).times(2)
+    end
+
+    it "does not pass retry options through to Net::HTTP" do
+      stub_request(:get, uri).to_return(status: 200, body: '')
+      net_http_object = Net::HTTP.new(URI.parse(uri).host, URI.parse(uri).port)
+      allow(Net::HTTP).to receive(:new).and_return(net_http_object)
+      expect(net_http_object).to receive(:options=) do |opts|
+        expect(opts).not_to include(:retries, :retry_delay, :retry_status_codes, :retry_exceptions, :retry_verbs)
+      end
+      HTTP.get(uri, {}, {}, {
+        retries: 3,
+        retry_delay: 0.1,
+        retry_status_codes: [500],
+        retry_exceptions: [Errno::ECONNRESET],
+        retry_verbs: %i{get}
+      })
+    end
+  end
+
+  describe "backoff timing" do
+    it "increases the delay between successive retries" do
+      delays = []
+      allow(HTTP::RETRY).to receive(:sleep){|d| delays << d}
+      stub_request(:get, uri).to_return(status: 503)
+      HTTP.get(uri, {}, {}, {retries: 3, retry_delay: 1.0})
+      expect(delays.length).to eq(3)
+      expect(delays[1]).to be > delays[0] * 0.8
+      expect(delays[2]).to be > delays[1] * 0.8
+    end
+  end
+
+  describe "verb-based retry default" do
+    it "does not retry POST by default even when retries are enabled" do
+      stub_request(:post, uri).to_return(status: 503)
+      HTTP.post(uri, {}, {}, {retries: 3})
+      expect(WebMock).to have_requested(:post, uri).times(1)
+    end
+
+    it "does not retry PATCH by default" do
+      stub_request(:patch, uri).to_return(status: 503)
+      HTTP.patch(uri, {}, {}, {retries: 3})
+      expect(WebMock).to have_requested(:patch, uri).times(1)
+    end
+
+    it "retries PUT by default (idempotent)" do
+      stub_request(:put, uri).to_return({status: 503}, {status: 200, body: ''})
+      response = HTTP.put(uri, {}, {}, {retries: 3})
+      expect(response.success?).to eq(true)
+      expect(WebMock).to have_requested(:put, uri).times(2)
+    end
+
+    it "retries DELETE by default (idempotent)" do
+      stub_request(:delete, uri).to_return({status: 503}, {status: 200, body: ''})
+      response = HTTP.delete(uri, {}, {}, {retries: 3})
+      expect(response.success?).to eq(true)
+      expect(WebMock).to have_requested(:delete, uri).times(2)
+    end
+
+    it "retries POST when opted in via retry_verbs" do
+      stub_request(:post, uri).to_return({status: 503}, {status: 200, body: ''})
+      response = HTTP.post(uri, {}, {}, {retries: 3, retry_verbs: %i{get post}})
+      expect(response.success?).to eq(true)
+      expect(WebMock).to have_requested(:post, uri).times(2)
+    end
+  end
+end
+
+describe HTTP, ".retry_after" do
+  it "returns integer seconds for a delta-seconds Retry-After header" do
+    response = instance_double(Net::HTTPResponse)
+    allow(response).to receive(:[]).with('Retry-After').and_return('5')
+    expect(HTTP.retry_after(response)).to eq(5)
+  end
+
+  it "parses an HTTP-date Retry-After header" do
+    base = Time.utc(2026, 5, 22, 12, 0, 0)
+    retry_at_header = (base + 5).httpdate
+    response = instance_double(Net::HTTPResponse)
+    allow(response).to receive(:[]).with('Retry-After').and_return(retry_at_header)
+    allow(Time).to receive(:now).and_return(base)
+    expect(HTTP.retry_after(response)).to be_within(0.001).of(5.0)
+  end
+
+  it "returns nil when Retry-After is absent" do
+    response = instance_double(Net::HTTPResponse)
+    allow(response).to receive(:[]).with('Retry-After').and_return(nil)
+    expect(HTTP.retry_after(response)).to be_nil
+  end
+
+  it "returns nil when Retry-After is malformed" do
+    response = instance_double(Net::HTTPResponse)
+    allow(response).to receive(:[]).with('Retry-After').and_return('not a date')
+    expect(HTTP.retry_after(response)).to be_nil
+  end
+end
+
+describe HTTP, ".backoff_delay" do
+  it "grows exponentially with attempt number" do
+    base = 1.0
+    delays = (1..4).map{|attempt| HTTP.backoff_delay(base, attempt)}
+    expect(delays[0]).to be_within(0.2).of(1.0)
+    expect(delays[1]).to be_within(0.4).of(2.0)
+    expect(delays[2]).to be_within(0.8).of(4.0)
+    expect(delays[3]).to be_within(1.6).of(8.0)
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: http.rb
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - thoran
@@ -80,6 +80,7 @@ files:
 - Rakefile
 - http.rb.gemspec
 - lib/HTTP.rb
+- lib/HTTP/RETRY.rb
 - lib/HTTP/VERSION.rb
 - lib/HTTP/request.rb
 - lib/HTTP/verbs.rb
@@ -93,6 +94,7 @@ files:
 - lib/Thoran/Array/FirstX/firstX.rb
 - lib/Thoran/String/ToConst/to_const.rb
 - lib/URI/Generic/use_sslQ.rb
+- spec/HTTP/RETRY_spec.rb
 - spec/HTTP/delete_spec.rb
 - spec/HTTP/get_spec.rb
 - spec/HTTP/head_spec.rb