Refactor retriable from separate class hierarchy to session option

Make retriable a first-class option on HTTP::Options (like `follow`),
eliminating the need for Retriable::Client and Retriable::Session.
Client#perform now checks options.retriable and delegates to
Retriable::Performer when set, keeping retry as a per-request concern
that flows naturally through the options system.

Author: sferik

CHANGELOG.md

@@ -40,8 +40,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   calls HTTP verb methods (`.get`, `.post`, etc.) or accesses `.default_options`
   is unaffected. Code that checks `is_a?(HTTP::Client)` on the return value of
   chainable methods will need to be updated to check for `HTTP::Session`
-- **BREAKING** `.retriable` now returns `HTTP::Retriable::Session` instead of
-  `HTTP::Retriable::Client`
+- **BREAKING** `.retriable` now returns `HTTP::Session` instead of
+  `HTTP::Retriable::Client`. Retry is a session-level option: it flows through
+  `HTTP::Options` into `HTTP::Client#perform`, eliminating the need for
+  separate `Retriable::Client` and `Retriable::Session` classes
 - Improved error message when request body size cannot be determined to suggest
   setting `Content-Length` explicitly or using chunked `Transfer-Encoding` (#560)
 - **BREAKING** `Connection#readpartial` now raises `EOFError` instead of

lib/http.rb

@@ -7,8 +7,6 @@
 require "http/chainable"
 require "http/session"
 require "http/client"
-require "http/retriable/client"
-require "http/retriable/session"
 require "http/connection"
 require "http/options"
 require "http/feature"

lib/http/chainable.rb

@@ -289,10 +289,10 @@ def use(*features)
     #   HTTP.retriable(tries: 3, delay: proc { |i| 1 + i*i }).get(url)
     #
     # @param (see Performer#initialize)
-    # @return [HTTP::Retriable::Session]
+    # @return [HTTP::Session]
     # @api public
     def retriable(**options)
-      Retriable::Session.new(Retriable::Performer.new(options), default_options)
+      branch default_options.with_retriable(options.empty? || options)
     end
 
     private

lib/http/client.rb

@@ -4,6 +4,7 @@
 
 require "http/client/request_builder"
 require "http/form_data"
+require "http/retriable/performer"
 require "http/options"
 require "http/feature"
 require "http/headers"
@@ -105,6 +106,35 @@ def build_request(verb, uri, opts = {})
     # @return [HTTP::Response] the response
     # @api public
     def perform(req, options)
+      if options.retriable
+        perform_with_retry(req, options)
+      else
+        perform_once(req, options)
+      end
+    end
+
+    # Close the connection and reset state
+    #
+    # @example
+    #   client.close
+    #
+    # @return [void]
+    # @api public
+    def close
+      @connection&.close
+      @connection = nil
+      @state = :clean
+    end
+
+    private
+
+    # Execute a single HTTP request without retry logic
+    #
+    # @param req [HTTP::Request] the request to perform
+    # @param options [HTTP::Options] request options
+    # @return [HTTP::Response] the response
+    # @api private
+    def perform_once(req, options)
       verify_connection!(req.uri)
 
       @state = :dirty
@@ -121,21 +151,18 @@ def perform(req, options)
       raise
     end
 
-    # Close the connection and reset state
-    #
-    # @example
-    #   client.close
+    # Execute a request with retry logic
     #
-    # @return [void]
-    # @api public
-    def close
-      @connection&.close
-      @connection = nil
-      @state = :clean
+    # @param req [HTTP::Request] the request to perform
+    # @param options [HTTP::Options] request options
+    # @return [HTTP::Response] the response
+    # @api private
+    def perform_with_retry(req, options)
+      Retriable::Performer.new(options.retriable).perform(self, req) do
+        perform_once(req, options)
+      end
     end
 
-    private
-
     # Send request over the connection, handling proxy and errors
     # @return [void]
     # @api private

lib/http/options/definitions.rb

@@ -81,6 +81,22 @@ def follow=(value)
         end
     end
 
+    def_option :retriable, reader_only: true
+
+    # Sets retriable options
+    #
+    # @param [Boolean, Hash, nil] value
+    # @api private
+    # @return [Hash, nil]
+    def retriable=(value)
+      @retriable =
+        if    !value                    then nil
+        elsif true == value             then Hash[]
+        elsif value.respond_to?(:fetch) then value
+        else argument_error! "Unsupported retriable options: #{value}"
+        end
+    end
+
     def_option :persistent, reader_only: true
 
     # Sets persistent connection origin

lib/http/retriable/client.rb

@@ -52,7 +52,7 @@ module HTTP
     def default_options=: (untyped opts) -> Options
     def nodelay: () -> Session
     def use: (*untyped features) -> Session
-    def retriable: (**untyped options) -> Retriable::Session
+    def retriable: (**untyped options) -> Session
 
     private
 
@@ -83,6 +83,8 @@ module HTTP
 
     private
 
+    def perform_once: (Request req, Options options) -> Response
+    def perform_with_retry: (Request req, Options options) -> Response
     def wrap_request: (Request req, Options opts) -> Request
     def build_response: (Request req, Options options) -> Response
     def build_wrapped_response: (Request req, Options options) -> Response
@@ -428,6 +430,7 @@ module HTTP
     attr_reader features: Hash[Symbol, Feature]
 
     def follow=: (untyped value) -> untyped
+    def retriable=: (untyped value) -> untyped
     def persistent=: (untyped value) -> String?
     def persistent?: () -> bool
     def merge: (untyped other) -> Options
@@ -454,13 +457,15 @@ module HTTP
     attr_accessor cookies: Hash[untyped, untyped]
     attr_accessor encoding: Encoding?
     attr_reader follow: Hash[untyped, untyped]?
+    attr_reader retriable: Hash[untyped, untyped]?
     attr_reader persistent: String?
 
     def with_headers: (untyped value) -> Options
     def with_cookies: (untyped value) -> Options
     def with_encoding: (untyped value) -> Options
     def with_features: (untyped value) -> Options
     def with_follow: (untyped value) -> Options
+    def with_retriable: (untyped value) -> Options
     def with_persistent: (untyped value) -> Options
     def with_proxy: (untyped value) -> Options
     def with_params: (untyped value) -> Options
@@ -1059,29 +1064,6 @@ module HTTP
   end
 
   module Retriable
-    class Session < HTTP::Session
-      @performer: untyped
-
-      def initialize: (untyped performer, untyped options) -> void
-
-      private
-
-      def branch: (Options options) -> Retriable::Session
-      def make_client: (Options options) -> Retriable::Client
-    end
-
-    class Client < HTTP::Client
-      @performer: untyped
-
-      def initialize: (untyped performer, untyped options) -> void
-      def perform: (Request req, Options options) -> Response
-
-      private
-
-      def branch: (Options options) -> Retriable::Session
-      def make_client: (Options options) -> Retriable::Client
-    end
-
     class Performer
       RETRIABLE_ERRORS: Array[untyped]
 

lib/http/retriable/session.rb

@@ -62,6 +62,7 @@
         headers:            { "Foo" => "foo", "Accept" => "xml", "Bar" => "bar" },
         proxy:              { proxy_address: "127.0.0.1", proxy_port: 8080 },
         follow:             nil,
+        retriable:          nil,
         socket_class:       HTTP::Options.default_socket_class,
         nodelay:            false,
         ssl_socket_class:   HTTP::Options.default_ssl_socket_class,

sig/http.rbs

@@ -29,6 +29,13 @@
     end
   end
 
+  describe "#with_retriable" do
+    it "raises error for unsupported retriable options" do
+      err = assert_raises(HTTP::Error) { subject_under_test.with_retriable(42) }
+      assert_match(/Unsupported retriable/, err.message)
+    end
+  end
+
   describe "#dup" do
     it "returns a duplicate without a block" do
       dupped = subject_under_test.dup