recurly 4.80.0 → 4.81.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0e6c839c677863f0df569868d3aea1a97574cc249b3f0dfdfb6f71f4029b592
-  data.tar.gz: f766e6760fb8c96a976b89d3c4a6e62536a0eae21fa3b36996da0400f9a700f9
+  metadata.gz: 3fcb6e038e5c1315ddf4ea11a1de626cac3eff0f6116309902a13fe2dd4d7d8a
+  data.tar.gz: 593fca5091812565ae93b3f592fc07b30014d97c45aab72af066887d1183c7ef
 SHA512:
-  metadata.gz: 8edd7d42e45fd761b8620c37a32dec83c8a90b3cf14cabd2b6dc6b5f45dc436f002da5967cf4ea4ce6299275aec863a5e0c0ae691b82bd933cecae9cc53cb1ee
-  data.tar.gz: 9acd5bcd20f19574e54bb8484954cf0d1d420d67197209b823d918aa6ba1b2a7962b1dd2ded9e45ef88ba37574bc9315dc4bec1afe8ad13b69ff5726d1ac2111
+  metadata.gz: 0710a16b6de8151e608d13c410fd0aa11dcce94e29f32a255133b5b8f07a6823810f1cba9c72cee2a6fe49638f8377ae665b3c4e2bc26697995eb04be5fea245
+  data.tar.gz: 55750c7429a93977fecc70e63f440d2932e340eedc55738cde3ba231110208517cac63f38e6bc774ae1d2e57516cef64f4d2782723b2e5074988381893df6c99

data/.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 4.80.0
+current_version = 4.81.0
 parse = (?P<major>\d+)
 	\.(?P<minor>\d+)
 	\.(?P<patch>\d+)

data/.github/workflows/ci.yml

@@ -1,7 +1,9 @@
 name: CI
-on: [push]
-concurrency: 
-  group: ${{ github.ref }}
+on:
+  push:
+  pull_request:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 jobs:
   build:

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [4.81.0](https://github.com/recurly/recurly-client-ruby/tree/4.81.0) (2026-09-09)
+
+[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/4.80.0...4.81.0)
+
+
+**Merged Pull Requests**
+
+- Generated Latest Changes for v2021-02-25 [#968](https://github.com/recurly/recurly-client-ruby/pull/968) ([recurly-integrations](https://github.com/recurly-integrations))
+- Relax base64 dependency to allow 0.3.x [#965](https://github.com/recurly/recurly-client-ruby/pull/965) ([romanoff](https://github.com/romanoff))
+
+
+
 ## [4.80.0](https://github.com/recurly/recurly-client-ruby/tree/4.80.0) (2026-07-02)
 
 [Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/4.79.0...4.80.0)

data/GETTING_STARTED.md

@@ -5,7 +5,7 @@ This repository houses the official ruby client for Recurly's V3 API.
 In your Gemfile, add `recurly` as a dependency.
 
 ```ruby
-gem 'recurly', '~> 4.80'
+gem 'recurly', '~> 4.81'
 ```
 
 > *Note*: We try to follow [semantic versioning](https://semver.org/) and will only apply breaking changes to major versions.

data/README.md

@@ -12,6 +12,33 @@ This repository houses the official ruby client for Recurly's V3 API.
 
 Getting Started Guide and reference documentation can be found on [Github Pages](https://recurly.github.io/recurly-client-ruby/).
 
+## Custom HTTP Adapter
+
+The client ships with a default `Net::HTTP`-backed transport, but you can inject
+your own HTTP layer (for observability, proxy/TLS control, or transport mocking)
+by passing an adapter that responds to `#call`:
+
+```ruby
+client = Recurly::Client.new(api_key: API_KEY, http_adapter: MyAdapter.new)
+```
+
+An adapter must implement:
+
+```ruby
+# @return [Recurly::HTTP::AdapterResponse]
+# @raise  [Recurly::Errors::TransportError] on transport-level failure only
+def call(method, url, headers, body, open_timeout: nil, read_timeout: nil)
+end
+```
+
+- `method` is a `Recurly::HTTP::HttpMethod` string (`"GET"`, `"POST"`, ...).
+- `url` is an **absolute** URL (scheme + host + path + query).
+- `headers` is a plain `Hash` of app-level headers (the SDK owns `Authorization`,
+  `Idempotency-Key`, `Content-Type`, etc.).
+- `body` is a serialized `String` or `nil`.
+- HTTP `4xx`/`5xx` responses must be **returned** as an `AdapterResponse`, never
+  raised. Only genuine transport failures raise `Recurly::Errors::TransportError`.
+
 ## Contributing
 
 Please see our [Contributing Guide](CONTRIBUTING.md).

data/lib/recurly/client.rb

@@ -24,6 +24,22 @@ module Recurly
     MAX_RETRIES = 3
     LOG_LEVELS = %i(debug info warn error fatal).freeze
     BASE36_ALPHABET = (("0".."9").to_a + ("a".."z").to_a).freeze
+
+    # Vendored HTTP status → reason-phrase table. Used to synthesize a
+    # reason_phrase when a (custom) adapter did not surface one. On the default
+    # path the adapter provides Net::HTTP's reason phrase, so this is not
+    # consulted and behavior is byte-identical. Phrases are bare (no status code
+    # prefix) since callers build "#{code}: #{phrase}".
+    HTTP_STATUS_MESSAGES = {
+      200 => "OK", 201 => "Created", 202 => "Accepted", 204 => "No Content",
+      301 => "Moved Permanently", 302 => "Found", 304 => "Not Modified",
+      400 => "Bad Request", 401 => "Unauthorized", 402 => "Payment Required",
+      403 => "Forbidden", 404 => "Not Found", 406 => "Not Acceptable",
+      409 => "Conflict", 412 => "Precondition Failed", 422 => "Unprocessable Entity",
+      429 => "Too Many Requests", 500 => "Internal Server Error", 502 => "Bad Gateway",
+      503 => "Service Unavailable", 504 => "Gateway Timeout",
+    }.freeze
+
     ALLOWED_OPTIONS = [
       :site_id,
       :open_timeout,
@@ -61,7 +77,7 @@ module Recurly
     # @param ca_file [String] The CA bundle to use when connecting to the API. Defaults to "data/ca-certificates.crt"
     # @param api_key [String] The private API key
     # @param logger [Logger] A logger to use. Defaults to creating a new STDOUT logger with level WARN.
-    def initialize(region: REGION, base_url: API_HOSTS[:us], ca_file: CA_FILE, api_key:, logger: nil, keep_alive_timeout: 600)
+    def initialize(region: REGION, base_url: API_HOSTS[:us], ca_file: CA_FILE, api_key:, logger: nil, keep_alive_timeout: 600, http_adapter: nil)
       raise ArgumentError, "'api_key' must be set to a non-nil value" if api_key.nil?
 
       raise ArgumentError, "Invalid region type. Expected one of: #{API_HOSTS.keys.join(", ")}" if !API_HOSTS.key?(region)
@@ -92,6 +108,12 @@ module Recurly
         log_warn("SECURITY_WARNING", message: msg)
       end
 
+      @http_adapter = http_adapter || HTTP::DefaultHttpAdapter.new(
+        connection_pool: self.class.connection_pool,
+        keep_alive_timeout: @keep_alive_timeout,
+        ca_file: @ca_file,
+      )
+
       # execute block with this client if given
       yield(self) if block_given?
     end
@@ -111,55 +133,57 @@ module Recurly
 
     def head(path, **options)
       validate_options!(**options)
-      request = Net::HTTP::Head.new build_url(path, options)
-      set_headers(request, options[:headers])
-      http_response = run_request(request, options)
-      handle_response! request, http_response
+      relative_path = build_url(path, options)
+      headers = build_headers(HTTP::HttpMethod::HEAD, options[:headers])
+      request = HTTP::Request.new(HTTP::HttpMethod::HEAD, relative_path, nil)
+      response = run_request(request, headers, options)
+      handle_response! request, response
     end
 
     def get(path, **options)
       validate_options!(**options)
-
-      request = Net::HTTP::Get.new build_url(path, options)
-
-      set_headers(request, options[:headers])
-      http_response = run_request(request, options)
-      handle_response! request, http_response
+      relative_path = build_url(path, options)
+      headers = build_headers(HTTP::HttpMethod::GET, options[:headers])
+      request = HTTP::Request.new(HTTP::HttpMethod::GET, relative_path, nil)
+      response = run_request(request, headers, options)
+      handle_response! request, response
     end
 
     def post(path, request_data = nil, request_class = nil, **options)
       validate_options!(**options)
-      request = Net::HTTP::Post.new build_url(path, options)
-      request.set_content_type(JSON_CONTENT_TYPE)
-      set_headers(request, options[:headers])
+      relative_path = build_url(path, options)
+      headers = build_headers(HTTP::HttpMethod::POST, options[:headers])
+      body = nil
       if request_data
         request_class.new(request_data).validate!
-        request.body = JSON.dump(request_data)
+        body = JSON.dump(request_data)
       end
-      http_response = run_request(request, options)
-      handle_response! request, http_response
+      request = HTTP::Request.new(HTTP::HttpMethod::POST, relative_path, body)
+      response = run_request(request, headers, options)
+      handle_response! request, response
     end
 
     def put(path, request_data = nil, request_class = nil, **options)
       validate_options!(**options)
-      request = Net::HTTP::Put.new build_url(path, options)
-      request.set_content_type(JSON_CONTENT_TYPE)
-      set_headers(request, options[:headers])
+      relative_path = build_url(path, options)
+      headers = build_headers(HTTP::HttpMethod::PUT, options[:headers])
+      body = nil
       if request_data
         request_class.new(request_data).validate!
-        json_body = JSON.dump(request_data)
-        request.body = json_body
+        body = JSON.dump(request_data)
       end
-      http_response = run_request(request, options)
-      handle_response! request, http_response
+      request = HTTP::Request.new(HTTP::HttpMethod::PUT, relative_path, body)
+      response = run_request(request, headers, options)
+      handle_response! request, response
     end
 
     def delete(path, **options)
       validate_options!(**options)
-      request = Net::HTTP::Delete.new build_url(path, options)
-      set_headers(request, options[:headers])
-      http_response = run_request(request, options)
-      handle_response! request, http_response
+      relative_path = build_url(path, options)
+      headers = build_headers(HTTP::HttpMethod::DELETE, options[:headers])
+      request = HTTP::Request.new(HTTP::HttpMethod::DELETE, relative_path, nil)
+      response = run_request(request, headers, options)
+      handle_response! request, response
     end
 
     private
@@ -171,80 +195,110 @@ module Recurly
       attr_accessor :connection_pool
     end
 
-    def run_request(request, options = {})
-      self.class.connection_pool.with_connection(uri: @base_uri, keep_alive_timeout: @keep_alive_timeout, ca_file: @ca_file) do |http|
-        set_http_options(http, options)
+    def run_request(request, headers, options = {})
+      method = request.method
+      body = request.body
+      url = request_url(request.path)
+      open_timeout = options[:open_timeout]
+      read_timeout = options[:read_timeout]
 
-        retries = 0
+      retries = 0
 
-        begin
-          http.start unless http.started?
-
-          log_attrs = {
-            method: request.method,
-            path: request.path,
-          }
-          if @logger.level < Logger::INFO
-            log_attrs[:request_body] = request.body
-            # No need to log the authorization header
-            headers = request.to_hash.reject { |k, _| k&.downcase == "authorization" }
-            log_attrs[:request_headers] = headers
-          end
+      log_attrs = {
+        method: method,
+        path: request.path,
+      }
+      if @logger.level < Logger::INFO
+        log_attrs[:request_body] = body
+        # No need to log the authorization header
+        loggable_headers = headers.reject { |k, _| k&.downcase == "authorization" }
+        log_attrs[:request_headers] = loggable_headers
+      end
 
-          log_info("Request", **log_attrs)
-          start = Time.now
-          response = http.request(request)
-          elapsed = Time.now - start
+      begin
+        log_info("Request", **log_attrs)
+        start = Time.now
+        response = @http_adapter.call(method, url, headers, body, open_timeout: open_timeout, read_timeout: read_timeout)
+        elapsed = Time.now - start
 
-          # GETs are safe to retry after a server error, requests with an Idempotency-Key will return the prior response
-          if response.kind_of?(Net::HTTPServerError) && request.is_a?(Net::HTTP::Get)
-            retries += 1
+        # GETs are safe to retry after a server error, requests with an Idempotency-Key will return the prior response.
+        # This is a SINGLE inline re-issue (not a loop) that shares the same `retries` counter as the transport rescue.
+        if response.status_code >= 500 && method == HTTP::HttpMethod::GET
+          retries += 1
+          if retries < MAX_RETRIES
             log_info("Retrying", retries: retries, **log_attrs)
             start = Time.now
-            response = http.request(request) if retries < MAX_RETRIES
+            response = @http_adapter.call(method, url, headers, body, open_timeout: open_timeout, read_timeout: read_timeout)
             elapsed = Time.now - start
           end
+        end
 
-          if @logger.level < Logger::INFO
-            log_attrs[:response_body] = response.body
-            log_attrs[:response_headers] = response.to_hash
-          end
-          log_info("Response", time_ms: (elapsed * 1_000).floor, status: response.code, **log_attrs)
-
-          response
-        rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ECONNABORTED,
-               Errno::EPIPE, Errno::ETIMEDOUT, Net::OpenTimeout, EOFError, SocketError => ex
-          retries += 1
-          if retries < MAX_RETRIES
-            retry
-          end
+        if @logger.level < Logger::INFO
+          log_attrs[:response_body] = response.body
+          log_attrs[:response_headers] = response.headers
+        end
+        log_info("Response", time_ms: (elapsed * 1_000).floor, status: response.status_code, **log_attrs)
 
-          if ex.kind_of?(Net::OpenTimeout) || ex.kind_of?(Errno::ETIMEDOUT)
-            raise Recurly::Errors::TimeoutError, "Request timed out"
-          end
+        response
+      rescue Recurly::Errors::TransportError => ex
+        retries += 1
+        if retries < MAX_RETRIES
+          retry
+        end
 
-          raise Recurly::Errors::ConnectionFailedError, "Failed to connect to Recurly: #{ex.message}"
-        rescue Timeout::Error
+        case ex.kind
+        when :timeout
           raise Recurly::Errors::TimeoutError, "Request timed out"
-        rescue OpenSSL::SSL::SSLError => ex
+        when :ssl
           raise Recurly::Errors::SSLError, ex.message
-        rescue StandardError => ex
+        when :connection
+          raise Recurly::Errors::ConnectionFailedError, ex.message
+        else
           raise Recurly::Errors::NetworkError, ex.message
         end
       end
     end
 
-    def set_headers(request, additional_headers = {})
+    # Builds the app-level request headers as a plain Hash. Header names are
+    # compared case-insensitively so a caller-supplied header (any case)
+    # overrides the SDK default instead of producing a duplicate.
+    def build_headers(method, additional_headers = {})
+      headers = {}
+
+      # Content-Type must be applied FIRST for bodied verbs, so caller headers
+      # can override it (parity with the old set_content_type-then-set_headers order).
+      if method == HTTP::HttpMethod::POST || method == HTTP::HttpMethod::PUT
+        headers["Content-Type"] = JSON_CONTENT_TYPE
+      end
+
       # TODO this is undocumented until we finalize it
-      additional_headers.each { |header, v| request[header] = v } if additional_headers
+      if additional_headers
+        additional_headers.each { |header, v| set_header(headers, header, v) }
+      end
 
-      request["Accept"] = "application/vnd.recurly.#{api_version}".chomp # got this method from operations.rb
-      request["Authorization"] = "Basic #{Base64.encode64(@api_key)}".chomp
-      request["User-Agent"] = "Recurly/#{VERSION}; #{RUBY_DESCRIPTION}"
+      set_header(headers, "Accept", "application/vnd.recurly.#{api_version}".chomp) # got this method from operations.rb
+      set_header(headers, "Authorization", "Basic #{Base64.encode64(@api_key)}".chomp)
+      set_header(headers, "User-Agent", "Recurly/#{VERSION}; #{RUBY_DESCRIPTION}")
 
-      unless request.is_a?(Net::HTTP::Get) || request.is_a?(Net::HTTP::Head)
-        request["Idempotency-Key"] ||= generate_idempotency_key
+      unless method == HTTP::HttpMethod::GET || method == HTTP::HttpMethod::HEAD
+        # Only generate an Idempotency-Key if the caller did not supply one (any case).
+        set_header(headers, "Idempotency-Key", generate_idempotency_key) unless header_key?(headers, "Idempotency-Key")
       end
+
+      headers
+    end
+
+    # Sets a header, replacing any existing entry whose name matches
+    # case-insensitively (so we never emit two headers differing only in case).
+    def set_header(headers, name, value)
+      existing = headers.keys.find { |k| k.to_s.downcase == name.to_s.downcase }
+      headers.delete(existing) if existing
+      headers[name] = value
+    end
+
+    # @return [Boolean] whether a header (case-insensitive) is already present
+    def header_key?(headers, name)
+      headers.keys.any? { |k| k.to_s.downcase == name.to_s.downcase }
     end
 
     # from https://github.com/rails/rails/blob/6-0-stable/activesupport/lib/active_support/core_ext/securerandom.rb
@@ -256,21 +310,16 @@ module Recurly
       end.join
     end
 
-    def set_http_options(http, options)
-      http.open_timeout = options[:open_timeout] || 20
-      http.read_timeout = options[:read_timeout] || 60
-    end
-
-    def handle_response!(request, http_response)
-      response = HTTP::Response.new(http_response, request)
-      raise_api_error!(http_response, response) unless http_response.kind_of?(Net::HTTPSuccess)
+    def handle_response!(request, adapter_response)
+      response = HTTP::Response.new(adapter_response, request)
+      raise_api_error!(adapter_response, response) unless adapter_response.status_code.between?(200, 299)
       resource = if response.body
-          if http_response.content_type&.include?(JSON_CONTENT_TYPE)
+          if response.content_type&.include?(JSON_CONTENT_TYPE)
             JSONParser.parse(self, response.body)
-          elsif BINARY_TYPES.include?(http_response.content_type)
+          elsif BINARY_TYPES.include?(response.content_type)
             FileParser.parse(response.body)
           else
-            raise Recurly::Errors::InvalidContentTypeError, "Unexpected content type: #{http_response.content_type}"
+            raise Recurly::Errors::InvalidContentTypeError, "Unexpected content type: #{response.content_type}"
           end
         else
           Resources::Empty.new
@@ -280,28 +329,37 @@ module Recurly
       resource
     end
 
-    def raise_api_error!(http_response, response)
-      if response.content_type.include?(JSON_CONTENT_TYPE)
+    def raise_api_error!(adapter_response, response)
+      if response.content_type&.include?(JSON_CONTENT_TYPE) && response.body
         error = JSONParser.parse(self, response.body)
         begin
           error_class = Errors::APIError.error_class(error.type)
           raise error_class.new(error.message, response, error)
         rescue NameError
-          error_class = Errors::APIError.from_response(http_response)
+          error_class = Errors::APIError.from_response(adapter_response)
           raise error_class.new("Unknown Error", response, error)
         end
       end
 
-      error_class = Errors::APIError.from_response(http_response)
+      error_class = Errors::APIError.from_response(adapter_response)
+      status_line = status_line_for(adapter_response)
 
       if error_class <= Recurly::Errors::APIError
-        error = Recurly::Resources::Error.new(message: "#{http_response.code}: #{http_response.message}")
+        error = Recurly::Resources::Error.new(message: status_line)
         raise error_class.new(error.message, response, error)
       else
-        raise error_class, "#{http_response.code}: #{http_response.message}"
+        raise error_class, status_line
       end
     end
 
+    # Builds a "<code>: <phrase>" status line, falling back to the vendored
+    # reason-phrase table and omitting the trailing ": " entirely when no
+    # phrase can be found (e.g. a custom adapter on an uncommon status code).
+    def status_line_for(adapter_response)
+      phrase = adapter_response.reason_phrase || HTTP_STATUS_MESSAGES[adapter_response.status_code]
+      phrase ? "#{adapter_response.status_code}: #{phrase}" : adapter_response.status_code.to_s
+    end
+
     def read_headers(response)
       if !@_ignore_deprecation_warning && response.headers["Recurly-Deprecated"]&.upcase == "TRUE"
         log_warn("DEPRECTATION WARNING", message: "Your current API version \"#{api_version}\" is deprecated and will be sunset on #{response.headers["Recurly-Sunset-Date"]}")
@@ -359,6 +417,15 @@ module Recurly
       @keep_alive_timeout = keep_alive_timeout
     end
 
+    # Absolute URL for the adapter: base_url ORIGIN (scheme, host, port) + the
+    # relative path. Any path/trailing-slash on base_url is ignored, matching the
+    # pre-adapter behavior of opening by host:port and sending the path alone.
+    def request_url(relative_path)
+      origin = "#{@base_uri.scheme}://#{@base_uri.host}"
+      origin += ":#{@base_uri.port}" unless @base_uri.port == @base_uri.default_port
+      origin + relative_path
+    end
+
     def build_url(path, options)
       path = scope_by_site(path, options)
       query_params = map_array_params(options.fetch(:params, {}))

data/lib/recurly/errors/network_errors.rb

@@ -3,5 +3,30 @@ module Recurly
     class NetworkError < APIError; end
     class ConnectionFailedError < NetworkError; end
     class SSLError < NetworkError; end
+
+    # Neutral transport error raised by HTTP adapters for ALL transport-level
+    # failures (timeouts, connection failures, SSL errors, generic network
+    # errors). This is the single error class the client's retry loop rescues.
+    #
+    # The +kind+ symbol (+:timeout+, +:connection+, +:ssl+, +:network+) lets the
+    # client reproduce its historical typed-error mapping after retries are
+    # exhausted, without needing to know about adapter-specific exception classes.
+    # Custom adapters that only set +:network+ degrade gracefully to +NetworkError+.
+    class TransportError < NetworkError
+      # @return [Symbol] one of +:timeout+, +:connection+, +:ssl+, +:network+
+      attr_reader :kind
+
+      # @return [Exception, nil] the underlying transport exception, if any.
+      #   Named distinctly from Ruby's built-in +Exception#cause+ (which is
+      #   auto-populated on +raise+ inside a +rescue+ and read by Sentry,
+      #   logging frameworks, and +pp+) so we don't shadow it.
+      attr_reader :original_exception
+
+      def initialize(message, kind: :network, cause: nil)
+        super(message)
+        @kind = kind
+        @original_exception = cause
+      end
+    end
   end
 end

data/lib/recurly/http/adapter.rb

@@ -0,0 +1,22 @@
+module Recurly
+  module HTTP
+    # Base class documenting the HTTP adapter contract. Custom adapters should
+    # subclass this (or simply respond to +#call+) and implement +#call+.
+    #
+    # Contract:
+    # - +#call(method, url, headers, body, open_timeout: nil, read_timeout: nil)+
+    #   performs the HTTP request. +method+ is a {HttpMethod} string, +url+ is an
+    #   ABSOLUTE url (scheme+host+path+query), +headers+ is a plain Hash of
+    #   app-level headers, and +body+ is a serialized String or nil.
+    # - On success (including HTTP 4xx and 5xx) it MUST return a
+    #   {Recurly::HTTP::AdapterResponse}. 4xx/5xx are RETURNED, never raised.
+    # - On a transport-level failure (timeout, connection refused, SSL error,
+    #   etc.) it MUST raise {Recurly::Errors::TransportError}, ideally carrying a
+    #   +kind+ so the client can reproduce its typed-error mapping.
+    class Adapter
+      def call(method, url, headers, body, open_timeout: nil, read_timeout: nil)
+        raise NotImplementedError, "#{self.class} must implement #call"
+      end
+    end
+  end
+end

data/lib/recurly/http/default_http_adapter.rb

@@ -0,0 +1,107 @@
+require "net/https"
+
+module Recurly
+  module HTTP
+    # The default transport adapter, backed by +Net::HTTP+. It uses the shared
+    # connection pool passed in at construction (it does NOT own a private pool)
+    # and preserves the byte-identical behavior the client had before the adapter
+    # seam was introduced.
+    class DefaultHttpAdapter < Adapter
+      # @param connection_pool [Recurly::ConnectionPool] the shared, class-level pool
+      # @param keep_alive_timeout [Integer] seconds; forwarded to the pool
+      # @param ca_file [String, nil] CA bundle path; forwarded to the pool
+      # @param read_timeout [Numeric] default read timeout in SECONDS (default 60).
+      #   Same unit as the per-request `read_timeout:` override accepted by {#call}.
+      # @param open_timeout [Numeric] default open timeout in SECONDS (default 20).
+      #   Same unit as the per-request `open_timeout:` override accepted by {#call}.
+      def initialize(connection_pool:, keep_alive_timeout:, ca_file: nil, read_timeout: 60, open_timeout: 20)
+        @connection_pool = connection_pool
+        @keep_alive_timeout = keep_alive_timeout
+        @ca_file = ca_file
+        @read_timeout = read_timeout
+        @open_timeout = open_timeout
+      end
+
+      # @param method [String] a {HttpMethod} constant
+      # @param url [String] the ABSOLUTE request url (scheme+host+path+query)
+      # @param headers [Hash] app-level request headers
+      # @param body [String, nil] serialized request body
+      # @param open_timeout [Numeric, nil] per-request open timeout override, in SECONDS
+      # @param read_timeout [Numeric, nil] per-request read timeout override, in SECONDS
+      # @return [Recurly::HTTP::AdapterResponse]
+      # @raise [Recurly::Errors::TransportError] on any transport-level failure
+      def call(method, url, headers, body, open_timeout: nil, read_timeout: nil)
+        # Parse/build outside the transport rescue: a bad URL or unsupported verb
+        # is a programming error and must raise immediately, not be wrapped in a
+        # (retried) TransportError.
+        uri = parse_url(url)
+        request = build_request(method, uri, headers, body)
+
+        net_response = begin
+            @connection_pool.with_connection(uri: uri, keep_alive_timeout: @keep_alive_timeout, ca_file: @ca_file) do |http|
+              http.open_timeout = open_timeout || @open_timeout
+              http.read_timeout = read_timeout || @read_timeout
+              http.start unless http.started?
+              http.request(request)
+            end
+          rescue Net::OpenTimeout, Errno::ETIMEDOUT => ex
+            raise Recurly::Errors::TransportError.new("Request timed out", kind: :timeout, cause: ex)
+          rescue Timeout::Error => ex
+            # Net::ReadTimeout < Timeout::Error. This clause MUST precede the
+            # StandardError clause so read timeouts map to :timeout (invariant A).
+            raise Recurly::Errors::TransportError.new("Request timed out", kind: :timeout, cause: ex)
+          rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ECONNABORTED,
+                 Errno::EPIPE, EOFError, SocketError => ex
+            raise Recurly::Errors::TransportError.new("Failed to connect to Recurly: #{ex.message}", kind: :connection, cause: ex)
+          rescue OpenSSL::SSL::SSLError => ex
+            raise Recurly::Errors::TransportError.new(ex.message, kind: :ssl, cause: ex)
+          rescue StandardError => ex
+            raise Recurly::Errors::TransportError.new(ex.message, kind: :network, cause: ex)
+          end
+
+        to_adapter_response(net_response)
+      end
+
+      private
+
+      # Raises ArgumentError (not a retried TransportError) on a malformed URL,
+      # so a programming error fails fast instead of looking like a network blip.
+      def parse_url(url)
+        URI.parse(url)
+      rescue URI::InvalidURIError => ex
+        raise ArgumentError, "Invalid request URL #{url.inspect}: #{ex.message}"
+      end
+
+      NET_VERBS = {
+        HttpMethod::GET => Net::HTTP::Get,
+        HttpMethod::HEAD => Net::HTTP::Head,
+        HttpMethod::POST => Net::HTTP::Post,
+        HttpMethod::PUT => Net::HTTP::Put,
+        HttpMethod::DELETE => Net::HTTP::Delete,
+      }.freeze
+
+      def build_request(method, uri, headers, body)
+        verb = NET_VERBS.fetch(method) do
+          raise ArgumentError, "Unsupported HTTP method: #{method.inspect}"
+        end
+        # Net verbs take a path (+ query), NOT an absolute url.
+        request = verb.new(uri.request_uri)
+        request.body = body unless body.nil?
+        (headers || {}).each { |k, v| request[k] = v }
+        request
+      end
+
+      def to_adapter_response(net_response)
+        response_headers = {}
+        net_response.each_header { |k, v| response_headers[k.downcase] = v }
+
+        AdapterResponse.new(
+          status_code: net_response.code.to_i,
+          headers: response_headers,
+          body: net_response.body,
+          reason_phrase: net_response.message,
+        )
+      end
+    end
+  end
+end

data/lib/recurly/http/http_method.rb

@@ -0,0 +1,13 @@
+module Recurly
+  module HTTP
+    # String constants for the HTTP methods the client issues. Used as the
+    # +method+ argument crossing the adapter seam (`#call(method, ...)`).
+    module HttpMethod
+      GET = "GET".freeze
+      POST = "POST".freeze
+      PUT = "PUT".freeze
+      DELETE = "DELETE".freeze
+      HEAD = "HEAD".freeze
+    end
+  end
+end