Share persistent connection pool across chained sessions

Child sessions created by chaining now share the same pool, so
connection reuse works regardless of whether options are baked-in up
front or chained per-request.

Closes #372.

Author: sferik

CHANGELOG.md

@@ -43,6 +43,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `HTTP::Client` per origin, so redirects to a different domain transparently
   open (and reuse) a separate persistent connection. Cookie management is
   preserved across all hops. ([#557])
+- Chaining configuration methods (`.headers`, `.auth`, `.cookies`, etc.) on a
+  persistent session no longer breaks connection reuse. Child sessions created
+  by chaining now share the parent's connection pool, so
+  `HTTP.persistent(host).headers(...).get(path)` reuses the same underlying
+  TCP connection across calls. ([#372])
 
 ### Changed
 
@@ -221,6 +226,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#223]: https://github.com/httprb/http/issues/223
 [#358]: https://github.com/httprb/http/issues/358
 [#371]: https://github.com/httprb/http/issues/371
+[#372]: https://github.com/httprb/http/issues/372
 [#447]: https://github.com/httprb/http/issues/447
 [#448]: https://github.com/httprb/http/issues/448
 [#449]: https://github.com/httprb/http/issues/449

lib/http/session.rb

@@ -56,12 +56,13 @@ class Session
     #   session = HTTP::Session.new(headers: {"Accept" => "application/json"})
     #
     # @param default_options [HTTP::Options, nil] existing options instance
+    # @param clients [Hash, nil] shared connection pool (internal use)
     # @param options [Hash] keyword options (see HTTP::Options#initialize)
     # @return [HTTP::Session] a new session instance
     # @api public
-    def initialize(default_options = nil, **)
+    def initialize(default_options = nil, clients: nil, **)
       @default_options = HTTP::Options.new(default_options, **)
-      @clients = {}
+      @clients = clients || {}
     end
 
     # Close all persistent connections held by this session
@@ -130,6 +131,23 @@ def request(verb, uri,
 
     private
 
+    # Create a new session with the given options
+    #
+    # When the current session is persistent, the child session shares the
+    # same connection pool so that chaining methods like {Chainable#headers}
+    # or {Chainable#auth} do not break connection reuse.
+    #
+    # @param options [HTTP::Options] options for the new session
+    # @return [HTTP::Session]
+    # @api private
+    def branch(options)
+      if persistent?
+        self.class.new(options, clients: @clients)
+      else
+        self.class.new(options)
+      end
+    end
+
     # Execute a request with cookie management
     #
     # @param client [HTTP::Client, nil] the client (nil when persistent; looked up from pool)

sig/http.rbs

@@ -182,7 +182,7 @@ module HTTP
     @default_options: Options
     @clients: Hash[String, Client]
 
-    def initialize: (?Options? default_options, **untyped) -> void
+    def initialize: (?Options? default_options, ?clients: Hash[String, Client]?, **untyped) -> void
     def close: () -> void
     def request: (
       verb verb,
@@ -238,6 +238,7 @@ module HTTP
 
     private
 
+    def branch: (Options options) -> Session
     def perform_request: (Client? client, verb verb, untyped uri, Options merged) -> Response
     def perform_redirects: (CookieJar jar, Client client, Request req, Response res, Options opts) -> Response
     def redirect_client: (Client client, Request request) -> Client

test/http/session_test.rb

@@ -277,6 +277,49 @@
     end
   end
 
+  describe "persistent connection reuse with chaining" do
+    it "reuses connections when chaining headers on a persistent session" do
+      session = HTTP.persistent(dummy.endpoint)
+
+      sock1 = session.headers("Accept" => "application/json").get("#{dummy.endpoint}/socket/1").to_s
+      sock2 = session.headers("Accept" => "text/html").get("#{dummy.endpoint}/socket/2").to_s
+
+      refute_equal "", sock1
+      assert_equal sock1, sock2
+    ensure
+      session&.close
+    end
+
+    it "reuses connections when chaining auth on a persistent session" do
+      session = HTTP.persistent(dummy.endpoint)
+
+      sock1 = session.auth("Bearer token").get("#{dummy.endpoint}/socket/1").to_s
+      sock2 = session.auth("Bearer token").get("#{dummy.endpoint}/socket/2").to_s
+
+      refute_equal "", sock1
+      assert_equal sock1, sock2
+    ensure
+      session&.close
+    end
+
+    it "shares the connection pool across chained sessions" do
+      session = HTTP.persistent(dummy.endpoint)
+      chained = session.headers("Accept" => "application/json")
+
+      assert_same session.instance_variable_get(:@clients),
+                  chained.instance_variable_get(:@clients)
+    ensure
+      session&.close
+    end
+
+    it "does not share pool for non-persistent sessions" do
+      chained = session.headers("Accept" => "application/json")
+
+      refute_same session.instance_variable_get(:@clients),
+                  chained.instance_variable_get(:@clients)
+    end
+  end
+
   describe "base_uri" do
     it "returns a Session from base_uri" do
       chained = session.base_uri(dummy.endpoint)