Extract request building into HTTP::Request::Builder

Decouple request construction from Client by moving build logic into a
standalone Request::Builder class. This eliminates the awkward pattern
of creating a Client just to build a request (e.g. session.build_request
delegating to make_client(...).build_request), and makes the builder
usable independently without any connection state.

The builder exposes two public methods:
* #build(verb, uri) — constructs a Request with feature wrapping
* #wrap(request) — applies feature middleware (used for redirects)

Author: sferik

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **BREAKING** Extract request building into `HTTP::Request::Builder`. The
+  `build_request` method has been removed from `Client`, `Session`, and the
+  top-level `HTTP` module. Use `HTTP::Request::Builder.new(options).build(verb, uri)`
+  to construct requests without executing them.
+
 ### Added
 
 - `Feature#on_request` and `Feature#around_request` lifecycle hooks, called

lib/http/chainable.rb

@@ -23,18 +23,6 @@ def request(verb, uri, opts = {})
       make_client(default_options).request(verb, uri, opts)
     end
 
-    # Prepare an HTTP request with the given verb
-    #
-    # @example
-    #   HTTP.build_request(:get, "http://example.com")
-    #
-    # @param (see Client#build_request)
-    # @return [HTTP::Request]
-    # @api public
-    def build_request(verb, uri, opts = {})
-      make_client(default_options).build_request(verb, uri, opts)
-    end
-
     # Set timeout on the request
     #
     # @example

lib/http/client.rb

@@ -2,25 +2,21 @@
 
 require "forwardable"
 
-require "http/client/request_builder"
 require "http/form_data"
 require "http/retriable/performer"
 require "http/options"
 require "http/feature"
 require "http/headers"
 require "http/connection"
 require "http/redirector"
+require "http/request/builder"
 require "http/uri"
 
 module HTTP
   # Clients make requests and receive responses
   class Client
     extend Forwardable
     include Chainable
-    include RequestBuilder
-
-    # Pattern matching HTTP or HTTPS URI schemes
-    HTTP_OR_HTTPS_RE = %r{^https?://}i
 
     # Initialize a new HTTP Client
     #
@@ -48,44 +44,17 @@ def initialize(default_options = nil, **)
     # @return [HTTP::Response] the response
     # @api public
     def request(verb, uri, opts = {})
-      opts = @default_options.merge(opts)
-      req = build_request(verb, uri, opts)
-      res = perform(req, opts)
+      opts    = @default_options.merge(opts)
+      builder = Request::Builder.new(opts)
+      req     = builder.build(verb, uri)
+      res     = perform(req, opts)
       return res unless opts.follow
 
       Redirector.new(opts.follow).perform(req, res) do |request|
-        perform(wrap_request(request, opts), opts)
+        perform(builder.wrap(request), opts)
       end
     end
 
-    # Prepare an HTTP request
-    #
-    # @example
-    #   client.build_request(:get, "https://example.com")
-    #
-    # @param verb [Symbol] the HTTP method
-    # @param uri [#to_s] the URI to request
-    # @param opts [Hash] request options
-    # @return [HTTP::Request] the built request object
-    # @api public
-    def build_request(verb, uri, opts = {})
-      opts    = @default_options.merge(opts)
-      uri     = make_request_uri(uri, opts)
-      headers = make_request_headers(opts)
-      body    = make_request_body(opts, headers)
-
-      req = HTTP::Request.new({
-        verb:           verb,
-        uri:            uri,
-        uri_normalizer: opts.feature(:normalize_uri)&.normalizer,
-        proxy:          opts.proxy,
-        headers:        headers,
-        body:           body
-      })
-
-      wrap_request(req, opts)
-    end
-
     # @!method persistent?
     #   Indicate whether the client has persistent connections
     #
@@ -215,15 +184,6 @@ def around_request(request, options, &block)
       end.call(request)
     end
 
-    # Wrap request through feature middleware
-    # @return [HTTP::Request] the wrapped request
-    # @api private
-    def wrap_request(req, opts)
-      opts.features.inject(req) do |request, (_name, feature)|
-        feature.wrap_request(request)
-      end
-    end
-
     # Build a response from the current connection
     # @return [HTTP::Response] the built response
     # @api private

lib/http/client/request_builder.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "http/form_data"
+require "http/headers"
+require "http/connection"
+require "http/uri"
+
+module HTTP
+  class Request
+    # Builds HTTP::Request objects from resolved options
+    #
+    # @example Build a request from options
+    #   options = HTTP::Options.new(headers: {"Accept" => "application/json"})
+    #   builder = HTTP::Request::Builder.new(options)
+    #   request = builder.build(:get, "https://example.com")
+    #
+    # @see Options
+    class Builder
+      # Pattern matching HTTP or HTTPS URI schemes
+      HTTP_OR_HTTPS_RE = %r{^https?://}i
+
+      # Initialize a new Request Builder
+      #
+      # @example
+      #   HTTP::Request::Builder.new(HTTP::Options.new)
+      #
+      # @param options [HTTP::Options] resolved request options
+      # @return [HTTP::Request::Builder]
+      # @api public
+      def initialize(options)
+        @options = options
+      end
+
+      # Build an HTTP request
+      #
+      # @example
+      #   builder.build(:get, "https://example.com")
+      #
+      # @param verb [Symbol] the HTTP method
+      # @param uri [#to_s] the URI to request
+      # @return [HTTP::Request] the built request object
+      # @api public
+      def build(verb, uri)
+        uri     = make_request_uri(uri)
+        headers = make_request_headers
+        body    = make_request_body(headers)
+
+        req = HTTP::Request.new(
+          verb:           verb,
+          uri:            uri,
+          uri_normalizer: @options.feature(:normalize_uri)&.normalizer,
+          proxy:          @options.proxy,
+          headers:        headers,
+          body:           body
+        )
+
+        wrap(req)
+      end
+
+      # Wrap a request through feature middleware
+      #
+      # @example
+      #   builder.wrap(redirect_request)
+      #
+      # @param request [HTTP::Request] the request to wrap
+      # @return [HTTP::Request] the wrapped request
+      # @api public
+      def wrap(request)
+        @options.features.inject(request) do |req, (_name, feature)|
+          feature.wrap_request(req)
+        end
+      end
+
+      private
+
+      # Merges query params if needed
+      #
+      # @param uri [#to_s] the URI to process
+      # @return [HTTP::URI] the constructed URI
+      # @api private
+      def make_request_uri(uri)
+        uri = uri.to_s
+
+        uri = "#{@options.persistent}#{uri}" if @options.persistent? && uri !~ HTTP_OR_HTTPS_RE
+
+        uri = HTTP::URI.parse uri
+
+        merge_query_params!(uri)
+
+        # Some proxies (seen on WEBrick) fail if URL has
+        # empty path (e.g. `http://example.com`) while it's RFC-compliant:
+        # http://tools.ietf.org/html/rfc1738#section-3.1
+        uri.path = "/" if uri.path.empty?
+
+        uri
+      end
+
+      # Merge query parameters into URI
+      #
+      # @return [void]
+      # @api private
+      def merge_query_params!(uri)
+        return unless @options.params && !@options.params.empty?
+
+        uri.query_values = uri.query_values(Array).to_a.concat(@options.params.to_a)
+      end
+
+      # Creates request headers
+      #
+      # @return [HTTP::Headers] the constructed headers
+      # @api private
+      def make_request_headers
+        headers = @options.headers
+
+        # Tell the server to keep the conn open
+        headers[Headers::CONNECTION] = @options.persistent? ? Connection::KEEP_ALIVE : Connection::CLOSE
+
+        headers
+      end
+
+      # Create the request body object to send
+      #
+      # @return [String, HTTP::FormData, nil] the request body
+      # @api private
+      def make_request_body(headers)
+        if @options.body
+          @options.body
+        elsif @options.form
+          form = make_form_data(@options.form)
+          headers[Headers::CONTENT_TYPE] ||= form.content_type
+          form
+        elsif @options.json
+          make_json_body(@options.json, headers)
+        end
+      end
+
+      # Encode JSON body and set content type header
+      # @return [String] the encoded JSON body
+      # @api private
+      def make_json_body(data, headers)
+        body = MimeType[:json].encode data
+        headers[Headers::CONTENT_TYPE] ||= "application/json; charset=#{body.encoding.name.downcase}"
+        body
+      end
+
+      # Coerce form data into an HTTP::FormData object
+      # @return [HTTP::FormData::Multipart, HTTP::FormData::Urlencoded] form data
+      # @api private
+      def make_form_data(form)
+        return form if form.is_a? HTTP::FormData::Multipart
+        return form if form.is_a? HTTP::FormData::Urlencoded
+
+        HTTP::FormData.create(form)
+      end
+    end
+  end
+end

lib/http/request/builder.rb

@@ -6,6 +6,7 @@
 require "openssl"
 
 module HTTP
+  # Retry logic for failed HTTP requests
   module Retriable
     # Request performing watchdog.
     # @api private