atlas_rb 1.14.0 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 683f9aa507f7cfa025781f231f839bdb39bb44f566e074e8ca304200da86e426
-  data.tar.gz: e12684f3de4d03e69e1024ab43765a4912f2f550c2ff01e72bc5953da5d55089
+  metadata.gz: 8a32e3df39d1a5f9648e47a42b88be5deff1b28dc696f9575a073baac4b9fa58
+  data.tar.gz: cb224b216444752165a39f242120e478cbe03c4a2613e36b19665d1897ec59b8
 SHA512:
-  metadata.gz: 9b34332d51540262c758c6e40e1c8eab538b3601e22fdde3639e60897e75b6c0cc9483b8a79eed1165f179f07bc2012ee9fd96d218e5dcf589f1d8c0734bd8ab
-  data.tar.gz: b56c2e3c5cadff71fb0ec53765c3160c27d6d695a0458d0e0e8cb09b65aaf7da483d3d436735cda2d41f82b8dc6227a0a3c262c4a2fc9696d39c9247f5c1e139
+  metadata.gz: 43cf01a77168ae4ae78de02bf26403e9c116b63f18d685adc7bf82275124aaa498129ea1a8dad9c4867330b455c236f68f20b05763743be8b4db97ceef0b8324
+  data.tar.gz: 6fb09278babb33a465f090e32b0616649bddd4fb043337cbeace8c6c0b7f83ff0cde6710f01eecec69e91d8c65db2d58c67683a7c55496078f090312d7f77317

data/.version

@@ -1 +1 @@
-1.14.0
+1.15.0

data/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 1.15.0
+
+### Changed — the transport reuses connections instead of opening one per request
+
+`FaradayHelper` built a fresh `Faraday.new` for every call, and Faraday's
+default `net_http` adapter wraps each request in its own `Net::HTTP#start`
+block and closes the socket after it. So every Atlas call paid a TCP handshake,
+and under TLS a full TLS handshake on top of that.
+
+The three builders now hand back an `AtlasRb::Transport::Proxy` over a shared,
+pooled connection — one per shape (`:json`, `:multipart`, `:system`) and base
+URL — using the `net_http_persistent` adapter. The proxy answers `get`, `post`,
+`patch`, `put` and `delete` like a `Faraday::Connection` and forwards a block to
+the request, so no call site changes.
+
+Measured on loopback inside the container, 100 requests per run, self-signed
+ECDSA P-256:
+
+| transport | before | after |
+|---|---|---|
+| plain HTTP | 1.21ms/req | 0.75ms/req |
+| TLS | 3.07ms/req | 0.31ms/req |
+
+Add a round trip each for TCP and TLS over a real network. The largest win is
+a sequential migration script, where the saving is elapsed time and nothing
+hides it; it also removes the `TIME_WAIT` pressure of a socket per request.
+
+Per-request state — the signed assertion, the `Idempotency-Key`, query params —
+now rides on the request rather than being baked into the connection, which is
+what makes a connection safe to share. The pool is process-wide, not
+thread-local, so a fan-out on short-lived threads reuses it.
+
+Two knobs, both optional:
+
+```ruby
+AtlasRb.configure do |config|
+  config.connection_pool_size    = 16  # sockets per Atlas host
+  config.connection_max_requests = nil # cap only if a proxy in front caps it
+end
+```
+
+`AtlasRb::Transport.reset_connections!` closes every pooled socket and drops the
+cached connections. A suite that boots and tears down a real server should call
+it between examples.
+
+### Fixed — the signing key is parsed once, not per request
+
+`assertion_signing_key` is configured as a callable returning a PEM, and
+`OpenSSL::PKey.read` ran on every request: 0.367ms against the 0.072ms ES256
+signature it exists to produce. The parse is now cached and re-run only when the
+PEM changes.
+
 ## 1.14.0
 
 ### Added — `Blob.find_many_versions`, the batch version-history read

data/Gemfile.lock

@@ -1,10 +1,11 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.14.0)
+    atlas_rb (1.15.0)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)
+      faraday-net_http_persistent (~> 2.3)
       hashie (~> 5.0)
       jwt (~> 2.7)
 
@@ -12,6 +13,7 @@ GEM
   remote: https://rubygems.org/
   specs:
     base64 (0.3.0)
+    connection_pool (2.5.5)
     diff-lcs (1.6.1)
     faraday (2.14.3)
       faraday-net_http (>= 2.0, < 3.5)
@@ -23,6 +25,9 @@ GEM
       multipart-post (~> 2.0)
     faraday-net_http (3.4.4)
       net-http (~> 0.5)
+    faraday-net_http_persistent (2.3.1)
+      faraday (~> 2.5)
+      net-http-persistent (>= 4.0.4, < 5)
     hashie (5.1.0)
       logger
     json (2.21.2)
@@ -32,6 +37,8 @@ GEM
     multipart-post (2.4.1)
     net-http (0.9.1)
       uri (>= 0.11.1)
+    net-http-persistent (4.0.8)
+      connection_pool (>= 2.2.4, < 4)
     rake (13.2.1)
     rspec (3.13.0)
       rspec-core (~> 3.13.0)

data/README.md

@@ -156,6 +156,42 @@ atlas_system_token: <token-Atlas-side-recognises-as-:system>
 The system NUID itself is hardcoded as `AtlasRb::System::NUID =
 "000000000"`, matching Atlas's seeded `:system` fixture row.
 
+### Connection reuse
+
+The gem keeps one pooled connection per shape (`:json`, `:multipart`,
+`:system`) and base URL, so a run of Atlas calls reuses its sockets rather than
+opening one per request. Over plain HTTP that saves a TCP handshake per call;
+under TLS it saves the TLS handshake too, which is where the cost actually
+sits — on loopback, 3.07ms per request against 0.31ms. Over a real network add
+a round trip each for TCP and TLS.
+
+Nothing is required to get this. The pool is process-wide rather than
+thread-local, so a host that fans requests out on short-lived threads reuses it
+as well.
+
+Two knobs, both optional:
+
+```ruby
+AtlasRb.configure do |config|
+  # Sockets kept open per Atlas host. Size it to your own concurrency — a host
+  # that fans out four reads per request thread wants four times its thread
+  # count, plus headroom. Defaults to 16.
+  config.connection_pool_size = 16
+
+  # Requests to send on one socket before replacing it. Leave nil against Puma.
+  # Set it when something between you and Puma caps requests per connection,
+  # because the request after the cap fails with ECONNRESET.
+  config.connection_max_requests = nil
+end
+```
+
+A test suite that boots and tears down a real Atlas server should close the
+pool between examples, or a socket from one example stays open into the next:
+
+```ruby
+config.after(:each, :atlas_rb_server) { AtlasRb::Transport.reset_connections! }
+```
+
 ## Resource hierarchy
 
 ```

data/lib/atlas_rb/configuration.rb

@@ -76,5 +76,28 @@ module AtlasRb
     #   Atlas selects the matching public key. Value or callable. Required when
     #   {#assertion_signing_key} is set.
     attr_accessor :assertion_signing_kid
+
+    # Sockets the transport keeps open per Atlas host. Size it to the host's
+    # own concurrency — a consumer that fans out N reads per request thread
+    # wants N times its thread count, plus headroom — rather than to the
+    # `net-http-persistent` default of 256, which is a file-descriptor budget
+    # rather than a considered number. `nil` takes
+    # {AtlasRb::Transport::DEFAULT_POOL_SIZE}.
+    #
+    # Read when a connection is first built, so set it before the first Atlas
+    # call; changing it later has no effect until
+    # {AtlasRb::Transport.reset_connections!}.
+    #
+    # @return [Integer, nil]
+    attr_accessor :connection_pool_size
+
+    # Requests to send on one pooled socket before replacing it. `nil` (the
+    # default) means no cap, which is what a direct connection to Puma wants.
+    # Set it when something between the client and Puma caps requests per
+    # connection, because the request after that cap fails with `ECONNRESET`
+    # rather than reconnecting.
+    #
+    # @return [Integer, nil]
+    attr_accessor :connection_max_requests
   end
 end

data/lib/atlas_rb/faraday_helper.rb

@@ -51,6 +51,16 @@ module AtlasRb
   # attached the emit degrades to a listener lookup + `yield`, so it is safe to
   # leave in the stack permanently — opt-in lives entirely on the consumer side.
   #
+  # ## Connection reuse
+  #
+  # The three builders do not return a `Faraday::Connection`. They return an
+  # {AtlasRb::Transport::Proxy} over a shared, cached connection, so Atlas calls
+  # reuse sockets instead of paying a TCP — and under TLS a full TLS —
+  # handshake each time. The proxy answers the same verbs and forwards a block,
+  # so call sites are unchanged. See {AtlasRb::Transport} for why the
+  # connection has to be cached for keep-alive to happen at all, and
+  # {AtlasRb::Transport.reset_connections!} for the test-suite teardown hook.
+  #
   # The module is mixed in via `extend`, so its methods become class methods on
   # the host (e.g. `AtlasRb::Work.connection({})`).
   module FaradayHelper
@@ -91,8 +101,10 @@ module AtlasRb
     #   signs when it can but sends no `Authorization` header otherwise, for the
     #   handful of endpoints Atlas serves with auth skipped (currently only
     #   `GET /reset`).
-    # @return [Faraday::Connection] a connection that follows redirects and
-    #   uses Faraday's default adapter.
+    # @return [AtlasRb::Transport::Proxy] a per-request view onto the shared
+    #   JSON connection, which follows redirects and pools its sockets. It
+    #   answers `get` / `post` / `patch` / `put` / `delete` like a
+    #   `Faraday::Connection` and forwards a block to the request.
     #
     # @example Fetching a community
     #   AtlasRb::Community.connection({}).get('/communities/abc123')
@@ -101,22 +113,23 @@ module AtlasRb
                 .merge("Content-Type" => "application/json")
       headers["Idempotency-Key"] = idempotency_key if idempotency_key
 
-      Faraday.new(
-        url: ENV.fetch("ATLAS_URL", nil),
-        params: params,
-        headers: headers
-      ) do |f|
-        instrument(f)
-        f.use AtlasRb::Middleware::RaiseOnStaleResource
-        f.use AtlasRb::Middleware::RaiseOnResourceError
-        # Path-independent, unlike the pair above: a maintenance window refuses
-        # writes on EVERY path, and a 503 reaches neither of them. Registered on
-        # all three connection builders — a write that slips past it silently
-        # unwraps nil and reports success.
-        f.use AtlasRb::Middleware::RaiseOnReadOnlyMode
-        f.response :follow_redirects
-        f.adapter Faraday.default_adapter
+      url  = ENV.fetch("ATLAS_URL", nil)
+      conn = AtlasRb::Transport.connection_for([:json, url]) do
+        Faraday.new(url: url) do |f|
+          instrument(f)
+          f.use AtlasRb::Middleware::RaiseOnStaleResource
+          f.use AtlasRb::Middleware::RaiseOnResourceError
+          # Path-independent, unlike the pair above: a maintenance window refuses
+          # writes on EVERY path, and a 503 reaches neither of them. Registered on
+          # all three connection builders — a write that slips past it silently
+          # unwraps nil and reports success.
+          f.use AtlasRb::Middleware::RaiseOnReadOnlyMode
+          f.response :follow_redirects
+          persistent_adapter(f)
+        end
       end
+
+      AtlasRb::Transport::Proxy.new(conn, headers, params)
     end
 
     # Build a multipart Faraday connection used for binary and XML uploads.
@@ -134,7 +147,8 @@ module AtlasRb
     # @param idempotency_key [String, nil] optional UUID to send in the
     #   `Idempotency-Key` header. See {#connection} for semantics; the
     #   `POST /files` (Blob) create flow uses this transport.
-    # @return [Faraday::Connection] a multipart-aware connection.
+    # @return [AtlasRb::Transport::Proxy] a per-request view onto the shared
+    #   multipart connection.
     #
     # @example Posting a binary blob
     #   payload = {
@@ -148,24 +162,27 @@ module AtlasRb
       headers = auth_headers(nuid, on_behalf_of, account: account)
       headers["Idempotency-Key"] = idempotency_key if idempotency_key
 
-      Faraday.new(
-        url: ENV.fetch("ATLAS_URL", nil),
-        headers: headers
-      ) do |f|
-        instrument(f)
-        f.use AtlasRb::Middleware::RaiseOnStaleResource
-        # Translate Atlas's verify-on-ingest 422 (fixity_mismatch /
-        # unsupported_digest_algorithm) into a typed FixityMismatchError —
-        # the JSON-connection path already carries this; uploads need it too.
-        f.use AtlasRb::Middleware::RaiseOnResourceError
-        # Path-independent, unlike the pair above: a maintenance window refuses
-        # writes on EVERY path, and a 503 reaches neither of them. Registered on
-        # all three connection builders — a write that slips past it silently
-        # unwraps nil and reports success.
-        f.use AtlasRb::Middleware::RaiseOnReadOnlyMode
-        f.request :multipart
-        f.request :url_encoded
+      url  = ENV.fetch("ATLAS_URL", nil)
+      conn = AtlasRb::Transport.connection_for([:multipart, url]) do
+        Faraday.new(url: url) do |f|
+          instrument(f)
+          f.use AtlasRb::Middleware::RaiseOnStaleResource
+          # Translate Atlas's verify-on-ingest 422 (fixity_mismatch /
+          # unsupported_digest_algorithm) into a typed FixityMismatchError —
+          # the JSON-connection path already carries this; uploads need it too.
+          f.use AtlasRb::Middleware::RaiseOnResourceError
+          # Path-independent, unlike the pair above: a maintenance window refuses
+          # writes on EVERY path, and a 503 reaches neither of them. Registered on
+          # all three connection builders — a write that slips past it silently
+          # unwraps nil and reports success.
+          f.use AtlasRb::Middleware::RaiseOnReadOnlyMode
+          f.request :multipart
+          f.request :url_encoded
+          persistent_adapter(f)
+        end
       end
+
+      AtlasRb::Transport::Proxy.new(conn, headers)
     end
 
     # Build a streaming multipart FilePart for `blob_path`, run the request
@@ -176,10 +193,12 @@ module AtlasRb
     # exhausts FDs across a TB migration of millions of files.
     #
     # Streaming/memory: faraday-multipart wraps the part in a streaming
-    # CompositeReadIO and the default net_http adapter sends it via
+    # CompositeReadIO and the pinned net_http_persistent adapter sends it via
     # `request.body_stream` (Content-Length known), so a multi-GB file uploads
-    # without being buffered into a String in memory. (Swapping the host app's
-    # default Faraday adapter to a buffering one would regress this.)
+    # without being buffered into a String in memory. The adapter is pinned by
+    # {#persistent_adapter} rather than read from `Faraday.default_adapter`, so
+    # a host app's own default cannot swap a buffering adapter in underneath
+    # this.
     #
     # @param blob_path [String] path to the binary on disk.
     # @yieldparam part [Faraday::Multipart::FilePart] the streaming part.
@@ -208,7 +227,8 @@ module AtlasRb
     # @param params [Hash] query-string / body params.
     # @param on_behalf_of [String, nil] optional NUID sent as a plain (not
     #   signed) `On-Behalf-Of` header — this path is already backend-only.
-    # @return [Faraday::Connection] a system-authenticated connection.
+    # @return [AtlasRb::Transport::Proxy] a per-request view onto the shared
+    #   system-authenticated connection.
     # @raise [RuntimeError] if the credential is not configured.
     # @raise [NameError] if `Rails` is not loaded (the gem assumes a
     #   Rails host for system-path calls).
@@ -223,28 +243,42 @@ module AtlasRb
       }
       headers["On-Behalf-Of"] = "NUID #{on_behalf_of}" if on_behalf_of
 
-      Faraday.new(
-        url: ENV.fetch("ATLAS_URL", nil),
-        params: params,
-        headers: headers
-      ) do |f|
-        instrument(f)
-        # Narrowly path-scoped (see each class) — a no-op for System::User /
-        # System::Token, and gives System::Work the same typed errors as #connection.
-        f.use AtlasRb::Middleware::RaiseOnStaleResource
-        f.use AtlasRb::Middleware::RaiseOnResourceError
-        # Path-independent, unlike the pair above: a maintenance window refuses
-        # writes on EVERY path, and a 503 reaches neither of them. Registered on
-        # all three connection builders — a write that slips past it silently
-        # unwraps nil and reports success.
-        f.use AtlasRb::Middleware::RaiseOnReadOnlyMode
-        f.response :follow_redirects
-        f.adapter Faraday.default_adapter
+      url  = ENV.fetch("ATLAS_URL", nil)
+      conn = AtlasRb::Transport.connection_for([:system, url]) do
+        Faraday.new(url: url) do |f|
+          instrument(f)
+          # Narrowly path-scoped (see each class) — a no-op for System::User /
+          # System::Token, and gives System::Work the same typed errors as #connection.
+          f.use AtlasRb::Middleware::RaiseOnStaleResource
+          f.use AtlasRb::Middleware::RaiseOnResourceError
+          # Path-independent, unlike the pair above: a maintenance window refuses
+          # writes on EVERY path, and a 503 reaches neither of them. Registered on
+          # all three connection builders — a write that slips past it silently
+          # unwraps nil and reports success.
+          f.use AtlasRb::Middleware::RaiseOnReadOnlyMode
+          f.response :follow_redirects
+          persistent_adapter(f)
+        end
       end
+
+      AtlasRb::Transport::Proxy.new(conn, headers, params)
     end
 
     private
 
+    # Pin the pooling adapter on every builder. Pinned rather than taking
+    # `Faraday.default_adapter`, because the saving depends on which adapter is
+    # in use: the default `net_http` wraps each request in its own
+    # `Net::HTTP#start` block and closes the socket after it, by design, so no
+    # amount of connection caching reuses anything under it. Pinning also means
+    # the streaming upload path no longer depends on what the host app happens
+    # to have set as its Faraday default.
+    def persistent_adapter(builder)
+      builder.adapter :net_http_persistent, pool_size: AtlasRb::Transport.pool_size do |http|
+        AtlasRb::Transport.configure_persistent(http)
+      end
+    end
+
     # Register Faraday's instrumentation middleware as the OUTERMOST handler so
     # each logical call emits exactly one {INSTRUMENTATION_EVENT} — a redirect
     # hop (e.g. the `/resources/:noid` resolver) is bracketed with the request
@@ -318,12 +352,16 @@ module AtlasRb
 
     # Resolve the configured signing key to an OpenSSL::PKey, or nil if signing
     # is not configured. Accepts a callable (resolved per request), a PEM
-    # string (parsed), or an already-built key.
+    # string, or an already-built key. A PEM is parsed through
+    # {AtlasRb::Transport.parsed_key}, because parsing costs several times the
+    # signature it exists to produce and the key rarely changes.
     def assertion_signing_key
       raw = config_value(AtlasRb.config.assertion_signing_key)
       return nil if raw.nil?
 
-      raw.is_a?(OpenSSL::PKey::PKey) ? raw : OpenSSL::PKey.read(raw)
+      return raw if raw.is_a?(OpenSSL::PKey::PKey)
+
+      AtlasRb::Transport.parsed_key(raw)
     end
 
     def assertion_signing_kid

data/lib/atlas_rb/transport.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  # Process-wide cache of Faraday connections, so Atlas calls reuse sockets
+  # instead of paying a TCP (and, under TLS, a full TLS) handshake per request.
+  #
+  # ## Why a cache is needed at all
+  #
+  # Keep-alive is what saves the handshake, and keep-alive needs two things
+  # that a per-request `Faraday.new` cannot give it. The pool lives on the
+  # adapter instance, and Faraday builds a new adapter for every connection —
+  # so a connection built per request gets a fresh, empty pool and reuses
+  # nothing. The socket has to outlive the request, which means the connection
+  # holding it has to as well.
+  #
+  # The cache is keyed on connection *shape* (`:json`, `:multipart`,
+  # `:system`) and base URL, because those are the only things that vary at
+  # build time now — per-request state (the signed assertion, the
+  # `Idempotency-Key`, the query params) rides on {Proxy} instead.
+  #
+  # ## Why not a connection per thread
+  #
+  # A thread-local connection is the obvious cheap version and it is wrong for
+  # this consumer: Cerberus fans out its page reads on short-lived threads, so
+  # a thread-local pool dies with the thread that built it and the fan-out —
+  # the calls that most want reuse — reuses nothing. `net-http-persistent`
+  # keeps a shared `ConnectionPool` and uses `Thread.current` only to track
+  # re-entrant checkouts, so a socket checked in by a dying thread goes back to
+  # the shared stack.
+  #
+  # ## Thread safety
+  #
+  # A Faraday connection is safe for concurrent requests as long as nothing
+  # mutates it after it is built. Everything here respects that: the cached
+  # connection is built once under {MUTEX} (with its middleware stack forced
+  # so two threads cannot race to build two adapters, and therefore two pools),
+  # and per-request headers and params are set on the request, never assigned
+  # onto the shared connection.
+  module Transport
+    # Sockets kept per host. Sized for the consumer's shape rather than left at
+    # the `net-http-persistent` default (256, or a quarter of the open-file
+    # limit): Cerberus draws up to four concurrent reads per Puma thread, so
+    # the useful number is that fan-out times the thread count, plus headroom.
+    DEFAULT_POOL_SIZE = 16
+
+    MUTEX = Mutex.new
+    # Separate from MUTEX so the key cache can never deadlock against a
+    # connection build that needs a signed header.
+    KEY_MUTEX = Mutex.new
+    private_constant :MUTEX, :KEY_MUTEX
+
+    # Per-request view onto a shared, cached Faraday connection.
+    #
+    # It exists because the state a request needs — the signed assertion (30s
+    # TTL), the `Idempotency-Key`, the query params — used to be baked into the
+    # connection at build time, and a connection that outlives the request
+    # cannot carry any of it. The proxy holds that state and applies it to each
+    # request instead.
+    #
+    # The caller-supplied block is forwarded, not swallowed: call sites that
+    # need per-request control already use Faraday's block form (a `Range`
+    # header, an `on_data` streaming handler), and those must keep working.
+    # The block runs last so a call site can override anything set here.
+    class Proxy
+      # Per-request headers and params, exposed so a caller (and the gem's own
+      # transport specs) can read what a request will send without making one.
+      attr_reader :headers, :params
+
+      # The shared connection behind this proxy, for reading its middleware
+      # stack or adapter. Do not mutate it — it is shared across every request
+      # of this shape, including ones in flight on other threads.
+      attr_reader :connection
+
+      # @param connection [Faraday::Connection] the shared, cached connection.
+      # @param headers [Hash] per-request headers (auth, content type,
+      #   idempotency key).
+      # @param params [Hash] per-request query/body params.
+      def initialize(connection, headers, params = {})
+        @connection = connection
+        @headers    = headers
+        @params     = params || {}
+      end
+
+      # @!method get(path, params = nil, headers = nil, &block)
+      # @!method delete(path, params = nil, headers = nil, &block)
+      # Bodyless verbs — a second positional argument is query params, matching
+      # `Faraday::Connection`.
+      %i[get delete].each do |verb|
+        define_method(verb) do |path, params = nil, headers = nil, &block|
+          run(verb, path, nil, headers, params, &block)
+        end
+      end
+
+      # @!method post(path, body = nil, headers = nil, &block)
+      # @!method patch(path, body = nil, headers = nil, &block)
+      # @!method put(path, body = nil, headers = nil, &block)
+      # Body-carrying verbs — a second positional argument is the body,
+      # matching `Faraday::Connection`.
+      %i[post patch put].each do |verb|
+        define_method(verb) do |path, body = nil, headers = nil, &block|
+          run(verb, path, body, headers, nil, &block)
+        end
+      end
+
+      # Escape hatch for a verb the five above don't cover, with the same
+      # per-request header/param application.
+      #
+      # @return [Faraday::Response]
+      def run_request(method, path, body, headers, &block)
+        run(method, path, body, headers, nil, &block)
+      end
+
+      private
+
+      def run(method, path, body, headers, params, &block)
+        @connection.run_request(method, path, body, headers) do |req|
+          req.params.update(@params) unless @params.empty?
+          req.params.update(params) if params
+          req.headers.update(@headers)
+          block&.call(req)
+        end
+      end
+    end
+
+    class << self
+      # Fetch the cached connection for `key`, building it from the block on
+      # first use.
+      #
+      # @param key [Array] connection shape and base URL.
+      # @yieldreturn [Faraday::Connection] a freshly built connection.
+      # @return [Faraday::Connection] the shared connection for `key`.
+      def connection_for(key)
+        MUTEX.synchronize do
+          connections[key] ||= begin
+            conn = yield
+            # Force the middleware stack (and with it the adapter, and with it
+            # the pool) while still holding the lock. Faraday memoizes the app
+            # lazily on first request, and two threads racing that memoization
+            # would each build an adapter — two pools, no reuse.
+            conn.builder.app
+            conn
+          end
+        end
+      end
+
+      # Apply the pool settings a host has configured to a
+      # `Net::HTTP::Persistent`. Called by the adapter's config block on every
+      # request, so it must stay assignment-only and cheap.
+      #
+      # `max_retries` is restored to 1 here because the adapter zeroes it, and
+      # zero is the wrong default for a pooled socket: a server that closed an
+      # idle connection produces an error on the next write, and one retry is
+      # what turns that into a reconnect instead of a caller-visible failure.
+      # `Net::HTTP` gates its retry on `IDEMPOTENT_METHODS_`, so the retry-safe
+      # creates (`POST /works`, `/file_sets`, `/files`) are never replayed.
+      #
+      # @param http [Net::HTTP::Persistent]
+      # @return [void]
+      def configure_persistent(http)
+        http.max_retries  = 1
+        http.max_requests = AtlasRb.config.connection_max_requests
+      end
+
+      # Pool size for a newly built adapter.
+      #
+      # @return [Integer]
+      def pool_size
+        AtlasRb.config.connection_pool_size || DEFAULT_POOL_SIZE
+      end
+
+      # Parse a PEM into an `OpenSSL::PKey`, reusing the last parse.
+      #
+      # Parsing the key costs roughly five times the ES256 signature it exists
+      # to produce, and the signing key is configured as a callable returning a
+      # PEM, so it was being reparsed on every request. One entry is enough —
+      # the cache is a rotation check, not a store, so a rotated key parses
+      # once and the old one is dropped rather than accumulating.
+      #
+      # @param pem [String] the PEM-encoded key.
+      # @return [OpenSSL::PKey::PKey]
+      def parsed_key(pem)
+        KEY_MUTEX.synchronize do
+          if @parsed_pem != pem
+            @parsed_pem = pem
+            @parsed_key = OpenSSL::PKey.read(pem)
+          end
+          @parsed_key
+        end
+      end
+
+      # Close every pooled socket and drop the cached connections.
+      #
+      # Pooled sockets outliving a test example are a new source of
+      # cross-example coupling, so a suite that boots and tears down a real
+      # server (Atlas's `:atlas_rb_server` layer) should call this in its
+      # teardown. Shutting a `net-http-persistent` pool down makes it refuse
+      # later checkouts, which is why the cached connections are dropped in the
+      # same breath — the next call rebuilds both.
+      #
+      # @return [void]
+      def reset_connections!
+        MUTEX.synchronize do
+          connections.each_value do |conn|
+            conn.close
+          rescue StandardError
+            # A pool already shut down, or a socket already gone, has nothing
+            # left to release. The connection is being discarded either way.
+            nil
+          end
+          connections.clear
+        end
+      end
+
+      private
+
+      def connections
+        @connections ||= {}
+      end
+    end
+  end
+end

data/lib/atlas_rb.rb

@@ -3,12 +3,16 @@
 require "faraday"
 require "faraday/multipart"
 require "faraday/follow_redirects"
+# Pooling adapter. Required here, not lazily, because the transport pins it on
+# every connection — see AtlasRb::FaradayHelper#persistent_adapter.
+require "faraday/net_http_persistent"
 require "jwt"
 require "openssl"
 require "securerandom"
 require_relative "atlas_rb/version"
 require_relative "atlas_rb/errors"
 require_relative "atlas_rb/configuration"
+require_relative "atlas_rb/transport"
 require_relative "atlas_rb/middleware/raise_on_stale_resource"
 require_relative "atlas_rb/middleware/raise_on_resource_error"
 require_relative "atlas_rb/middleware/raise_on_read_only_mode"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.14.0
+  version: 1.15.0
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-26 00:00:00.000000000 Z
+date: 2026-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.3.0
+- !ruby/object:Gem::Dependency
+  name: faraday-net_http_persistent
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: hashie
   requirement: !ruby/object:Gem::Requirement
@@ -155,6 +169,7 @@ files:
 - lib/atlas_rb/system/token.rb
 - lib/atlas_rb/system/user.rb
 - lib/atlas_rb/system/work.rb
+- lib/atlas_rb/transport.rb
 - lib/atlas_rb/user.rb
 - lib/atlas_rb/version.rb
 - lib/atlas_rb/work.rb