x-core 1.0.0

data/lib/x/core/redirect_handler.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require_relative "authenticator"
+require_relative "connection"
+require_relative "errors/too_many_redirects"
+require_relative "origin"
+require_relative "request_context"
+require_relative "request_builder"
+require_relative "setting_validator"
+
+module X
+  module Core
+    # Handles HTTP redirects for API requests
+    #
+    # Internal to x-core: Client follows redirects with it, and max_redirects is set on the client.
+    #
+    # @api private
+    class RedirectHandler
+      # Default maximum number of redirects to follow
+      DEFAULT_MAX_REDIRECTS = 10
+      # The redirects that keep the method and the body of the request, whatever the method
+      METHOD_PRESERVING_CODES = [307, 308].freeze
+      # The redirects that keep the method and the body of a request other than a POST, which is followed with a GET
+      MOVED_CODES = [301, 302].freeze
+      # The redirects that are followed: those that move the request, and 303 See Other, which is followed with a GET
+      FOLLOWED_CODES = [*MOVED_CODES, 303, *METHOD_PRESERVING_CODES].freeze
+      private_constant :METHOD_PRESERVING_CODES, :MOVED_CODES, :FOLLOWED_CODES
+
+      # The maximum number of redirects to follow
+      # @api private
+      # @return [Integer] the maximum number of redirects to follow
+      # @example Get or set the maximum redirects
+      #   handler.max_redirects = 5
+      attr_reader :max_redirects
+
+      # The connection for making requests
+      # @api private
+      # @return [Connection] the connection for making requests
+      # @example Get the connection
+      #   handler.connection
+      attr_reader :connection
+
+      # The request builder for creating requests
+      # @api private
+      # @return [RequestBuilder] the request builder for creating requests
+      # @example Get the request builder
+      #   handler.request_builder
+      attr_reader :request_builder
+
+      # Initialize a new RedirectHandler
+      #
+      # @api private
+      # @param connection [Connection] the connection for making requests
+      # @param request_builder [RequestBuilder] the request builder for creating requests
+      # @param max_redirects [Integer] the maximum number of redirects to follow
+      # @return [RedirectHandler] a new instance
+      # @raise [ArgumentError] if the maximum number of redirects is not an Integer of at least 0
+      # @example Create a redirect handler
+      #   handler = X::Core::RedirectHandler.new(connection: conn, request_builder: builder)
+      def initialize(connection: Connection.new, request_builder: RequestBuilder.new,
+        max_redirects: DEFAULT_MAX_REDIRECTS)
+        @connection = connection
+        @request_builder = request_builder
+        @max_redirects = SettingValidator.count!(:max_redirects, max_redirects)
+      end
+
+      # Handle redirects for an HTTP response
+      #
+      # A redirect to another scheme, host, or port drops the credentials, the authenticator's and any Authorization,
+      # Cookie, or Proxy-Authorization header among the headers, as Origin decides; see {Origin}. A 307 or 308 keeps
+      # the method and the body of the request, so a request whose body holds something private replays it to the
+      # host it is redirected to, whatever its origin. A 301 or 302 keeps them too, as RFC 9110 Section 15.4 has it,
+      # but for a POST, which it lets a client follow with a GET, so a PUT or a DELETE is not answered by a GET that
+      # reads as its success. A 303 See Other is followed with a GET, which sends no body, so it sends no Content-Type
+      # either, such as the form type of a request given form:.
+      #
+      # A redirect that cannot be followed, a 300 Multiple Choices, 304 Not Modified, or 305 Use Proxy whatever its
+      # Location, or one whose location is missing, is not a valid URL, or is not an HTTP or HTTPS URL, is returned as
+      # it is, so that the client raises an HTTPError for it, however many redirects were followed before it. A
+      # redirect that can be followed once max_redirects have been raises TooManyRedirects, which names the request
+      # that redirect answered, so a max_redirects of 0 follows none, and raises for every one that could be.
+      #
+      # @api private
+      # @param response [Net::HTTPResponse] the HTTP response to handle
+      # @param request [Net::HTTPRequest] the request the response answers, built from a URI
+      # @param headers [Hash] additional headers to send with redirected requests
+      # @param authenticator [Authenticator] the authenticator for requests
+      # @param redirect_count [Integer] the current redirect count
+      # @return [Net::HTTPResponse] the final HTTP response after following redirects
+      # @raise [TooManyRedirects] if the maximum number of redirects is exceeded
+      # @example Handle a response
+      #   response = handler.handle(response: resp, request: req)
+      def handle(response:, request:, headers: {}, authenticator: Authenticator.new, redirect_count: 0)
+        follow(response:, request:, headers:, authenticator:, redirect_count:).first
+      end
+
+      # Follow redirects, and return the final response with the request it answers
+      #
+      # Redirects are followed as handle follows them. The final response answers the last request that was sent, which a redirect may have sent to another URI
+      # with another method, so the response is reported, and its error named, for that request rather than the
+      # first.
+      #
+      # @api private
+      # @param response [Net::HTTPResponse] the HTTP response to handle
+      # @param request [Net::HTTPRequest] the request the response answers, built from a URI
+      # @param headers [Hash] additional headers to send with redirected requests
+      # @param authenticator [Authenticator] the authenticator for requests
+      # @param redirect_count [Integer] the current redirect count
+      # @return [Array(Net::HTTPResponse, Net::HTTPRequest)] the final HTTP response and the request it answers
+      # @raise [TooManyRedirects] if the maximum number of redirects is exceeded
+      # @example Follow a response
+      #   response, request = handler.follow(response: resp, request: req)
+      def follow(response:, request:, headers: {}, authenticator: Authenticator.new, redirect_count: 0)
+        return [response, request] unless followed?(response)
+
+        uri = request.uri #: URI::Generic
+        new_uri = build_new_uri(response, uri)
+        return [response, request] if new_uri.nil?
+        check_redirect_count(request, redirect_count)
+
+        preserve = preserves_method?(request, Integer(response.code))
+        authenticator, headers = Origin.credentials_for(from: uri, to: new_uri, authenticator:, headers: headers_for(preserve, headers))
+        new_request = build_request(request, new_uri, preserve, headers, authenticator)
+        follow(response: connection.perform(request: new_request), request: new_request, headers:, authenticator:,
+          redirect_count: redirect_count + 1)
+      end
+
+      private
+
+      # Whether a response is a redirect that is followed, given a location that can be
+      # @api private
+      # @param response [Net::HTTPResponse] the response
+      # @return [Boolean] whether the status of the response is one that is followed
+      def followed?(response) = FOLLOWED_CODES.include?(Integer(response.code))
+
+      # Raise for a redirect that would be one more than max_redirects allows
+      # @api private
+      # @param request [Net::HTTPRequest] the request the redirect answered, which the error names
+      # @param redirect_count [Integer] the redirects followed so far
+      # @return [void]
+      # @raise [TooManyRedirects] if max_redirects have been followed
+      def check_redirect_count(request, redirect_count)
+        raise TooManyRedirects.new("Too many redirects", **RequestContext.of(request)) if redirect_count >= max_redirects
+      end
+
+      # Build a new URI from the redirect response
+      #
+      # A relative location is relative to the request that was redirected, as RFC 9110 Section 10.2.2 requires,
+      # which need not share the base URL: a request can name a URL of its own. An HTTP or HTTPS URL that names no
+      # host, such as https:///users or http:, is not one a request can be sent to, as RFC 9110 Section 4.2.1 says.
+      #
+      # @api private
+      # @param response [Net::HTTPResponse] the redirect response
+      # @param uri [URI::Generic] the URI of the request that was redirected
+      # @return [URI::HTTP, nil] the new URI, or nil if the location is missing, invalid, or not an HTTP or HTTPS URL
+      #   of a host
+      def build_new_uri(response, uri)
+        location = response["location"] or return
+        new_uri = URI.join(uri, location)
+        new_uri if new_uri.is_a?(URI::HTTP) && !new_uri.host.to_s.empty?
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      # Whether a redirect keeps the method and the body of the request it answers
+      # @api private
+      # @param request [Net::HTTPRequest] the request that was redirected
+      # @param response_code [Integer] the status code of the redirect
+      # @return [Boolean] true for a 307 or 308, and for a 301 or 302 of any method but POST
+      def preserves_method?(request, response_code)
+        METHOD_PRESERVING_CODES.include?(response_code) ||
+          (MOVED_CODES.include?(response_code) && !request.method.eql?("POST"))
+      end
+
+      # The headers of a redirected request, without a Content-Type a GET does not send
+      # @api private
+      # @param preserve [Boolean] whether the redirected request keeps the method and the body
+      # @param headers [Hash] the headers of the request that was redirected
+      # @return [Hash] the headers to send with the redirected request
+      def headers_for(preserve, headers)
+        return headers if preserve
+
+        headers.reject { |name, _| name.casecmp?("Content-Type") }
+      end
+
+      # Build a new request for the redirect
+      # @api private
+      # @param request [Net::HTTPRequest] the original request
+      # @param uri [URI] the new URI
+      # @param preserve [Boolean] whether the new request keeps the method and the body, or is a GET
+      # @param headers [Hash] additional headers for the request
+      # @param authenticator [Authenticator] the authenticator
+      # @return [Net::HTTPRequest] the new request
+      def build_request(request, uri, preserve, headers, authenticator)
+        http_method = :get
+        if preserve
+          http_method = request.method.downcase.to_sym
+          body = request.body
+        end
+
+        request_builder.build(http_method:, uri:, body:, headers:, authenticator:)
+      end
+    end
+    private_constant :RedirectHandler
+  end
+end

data/lib/x/core/refresh_reporter.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "monitor"
+require_relative "errors/token_report_failed"
+
+module X
+  module Core
+    # Reports the refreshes of an OAuth 2.0 authenticator to the callables that store their tokens
+    #
+    # The refreshes are reported one at a time, in the order they were made, and a refresh another has replaced by
+    # the time it is reported is not reported at all: a callable that stores the tokens of a refresh as another
+    # stores the tokens that replaced them would otherwise overwrite them with a refresh token X no longer accepts.
+    # A callable that raises keeps none of the others from being passed the tokens, and once every one has been,
+    # TokenReportFailed is raised, which holds the tokens, since the refresh token they replaced is spent, with the
+    # first error as its cause. A Timeout::Error is a failure of a callable too, even one Timeout.timeout raises with
+    # its class around the request, since the error that holds the tokens is the only place left to find them; one it
+    # raises without a class is not a StandardError until it leaves the block, so it is raised as it is.
+    #
+    # The lock it reports under is reentrant, so a callable can make a request of its own, such as looking up the
+    # user whose tokens it stores, which may refresh and report again on the same thread.
+    #
+    # @api private
+    class RefreshReporter
+      # The message of the error raised when a callable raised for the tokens of a refresh
+      REPORT_FAILED = "The tokens were refreshed, but save_tokens raised for them"
+      # The fiber-local key of a callable that a gem extending a client sets, which the callables are run inside
+      #
+      # x-streams sets it while a stream runs, and x-uploads in each thread of a chunked upload, so that a stop of
+      # the stream, or of the upload, waits for save_tokens to store the tokens of a refresh, rather than cutting it
+      # short and leaving the store with a refresh token X no longer accepts. The callable is passed a block, which it
+      # runs and whose result it returns.
+      GUARD = :x_core_refresh_report_guard
+
+      # Initialize a reporter with no refresh to report
+      # @api private
+      # @return [RefreshReporter] a new reporter
+      def initialize
+        @monitor = Monitor.new
+      end
+
+      # Record the tokens of a refresh as the latest, while the refresh holds its lock
+      # @api private
+      # @param tokens [OAuth2Tokens] the tokens the refresh issued
+      # @return [OAuth2Tokens] the tokens
+      def issued(tokens) = (@latest = tokens)
+
+      # Pass each refresh to the callables another reads
+      # @api private
+      # @param hooks [#call] a callable that returns the callables to pass each refresh, read at each refresh
+      # @return [#call] the callable
+      def to(hooks) = (@hooks = hooks)
+
+      # Pass the tokens of a refresh to the callables, unless a later one replaced them
+      # @api private
+      # @param tokens [OAuth2Tokens] the tokens the refresh issued
+      # @param client [Client, nil] the client whose request refreshed, which the error holds, or nil for none
+      # @return [void]
+      # @raise [TokenReportFailed] if a callable raises, with the tokens and client, once every one has been passed them
+      def report(tokens, client)
+        @monitor.synchronize { guarded { pass(tokens, client) } if tokens.equal?(@latest) }
+      end
+
+      private
+
+      # Run a block inside the guard of the fiber, if a gem extending the client set one
+      # @api private
+      # @yield passes the tokens to the callables
+      # @return [void]
+      def guarded(&) = (guard = Thread.current[GUARD]) ? guard.call(&) : yield
+
+      # Pass tokens to each callable, raising for the first error once all have run
+      # @api private
+      # @param tokens [OAuth2Tokens] the tokens the refresh issued
+      # @param client [Client, nil] the client whose request refreshed, or nil for none
+      # @return [void]
+      # @raise [TokenReportFailed] if a callable raises, with the tokens and client, and the first error as its cause
+      def pass(tokens, client)
+        hooks = @hooks
+        return unless hooks
+
+        errors = hooks.call.filter_map do |hook|
+          hook.call(tokens)
+          nil
+        rescue => e
+          e
+        end
+        raise TokenReportFailed.new(REPORT_FAILED, client:, tokens:), cause: errors.first unless errors.empty?
+      end
+    end
+    private_constant :RefreshReporter
+  end
+end

data/lib/x/core/request_builder.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require_relative "authenticator"
+require_relative "authenticator_request"
+require_relative "version"
+
+module X
+  module Core
+    # Builds HTTP requests for the X API
+    #
+    # Internal to x-core: Client builds its requests with it.
+    #
+    # @api private
+    class RequestBuilder
+      # Default headers for API requests
+      DEFAULT_HEADERS = {
+        "User-Agent" => "x-ruby/#{Core::VERSION} #{RUBY_ENGINE}/#{RUBY_VERSION} (#{RUBY_PLATFORM})"
+      }.freeze
+      # The headers of a request that carries a body, which one without a body does not send, since it has no body
+      # for a content type to describe
+      BODY_HEADERS = {"Content-Type" => "application/json; charset=utf-8"}.freeze
+      # Mapping of HTTP method symbols to Net::HTTP classes
+      HTTP_METHODS = {
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+        put: Net::HTTP::Put,
+        delete: Net::HTTP::Delete
+      }.freeze
+      # The HTTP methods a request may be sent again with, since sending one again asks the API for what sending it
+      # once did, where a second POST would post a second time
+      IDEMPOTENT_METHODS = %i[get put delete].freeze
+
+      # Check whether sending a request again has the same effect as sending it once
+      #
+      # @api private
+      # @param http_method [Symbol] the HTTP method (:get, :post, :put, :delete)
+      # @return [Boolean] true for a GET, PUT, or DELETE
+      # @example Check whether a post may be sent again
+      #   X::Core::RequestBuilder.idempotent?(:post) # => false
+      def self.idempotent?(http_method) = IDEMPOTENT_METHODS.include?(http_method)
+
+      # Merge headers over others, as HTTP names them, without regard to case
+      #
+      # A header of overrides is sent in place of one of headers whose name differs from it in case alone, as
+      # "user-agent" is sent in place of "User-Agent", where Hash#merge would keep both and send whichever came last.
+      #
+      # @api private
+      # @param headers [Hash{String => String}] the headers overridden
+      # @param overrides [Hash{String => String}] the headers sent in place of those of the same name
+      # @return [Hash{String => String}] the headers of both, those of overrides in place of the others
+      # @example Replace the User-Agent of a client with one named in lowercase
+      #   X::Core::RequestBuilder.merge_headers({"User-Agent" => "a"}, {"user-agent" => "b"}) # => {"user-agent" => "b"}
+      def self.merge_headers(headers, overrides)
+        headers.reject { |name, _| overrides.any? { |override, _| override.casecmp?(name) } }.merge(overrides)
+      end
+
+      # Build an HTTP request
+      #
+      # @api private
+      # @param http_method [Symbol] the HTTP method (:get, :post, :put, :delete)
+      # @param uri [URI] the request URI
+      # @param body [String, nil] the request body
+      # @param headers [Hash] additional headers for the request
+      # @param authenticator [Authenticator] the authenticator for the request
+      # @return [Net::HTTPRequest] the built HTTP request
+      # @raise [ArgumentError] if the HTTP method is not supported
+      # @example Build a GET request
+      #   builder.build(http_method: :get, uri: URI("https://api.x.com/2/users/me"))
+      def build(http_method:, uri:, body: nil, headers: {}, authenticator: Authenticator.new)
+        request = create_request(http_method:, uri:, body:)
+        add_headers(request:, headers:, body:)
+        add_authentication(request:, authenticator:)
+        request
+      end
+
+      private
+
+      # Create an HTTP request
+      # @api private
+      # @param http_method [Symbol] the HTTP method
+      # @param uri [URI] the request URI
+      # @param body [String, nil] the request body
+      # @return [Net::HTTPRequest] the created request
+      def create_request(http_method:, uri:, body:)
+        http_method_class = HTTP_METHODS[http_method]
+
+        raise ArgumentError, "Unsupported HTTP method: #{http_method}" unless http_method_class
+
+        escaped_uri = escape_query_params(uri)
+        request = http_method_class.new(escaped_uri)
+        request.body = body
+        request
+      end
+
+      # Add authentication to a request
+      # @api private
+      # @param request [Net::HTTPRequest] the request
+      # @param authenticator [Authenticator] the authenticator
+      # @return [void]
+      def add_authentication(request:, authenticator:)
+        authenticator.headers(AuthenticatorRequest.new(request)).each do |key, value|
+          request[key] = value
+        end
+      end
+
+      # Add headers to a request
+      #
+      # A request that carries a body is given the JSON content type the API takes, which a header of the caller, such
+      # as the form content type of a request given form fields, replaces. A request without a body, such as a GET or a
+      # DELETE, is given no content type at all, rather than one for a body it does not send.
+      #
+      # @api private
+      # @param request [Net::HTTPRequest] the request
+      # @param headers [Hash] additional headers
+      # @param body [String, nil] the request body, which decides whether a content type is sent
+      # @return [void]
+      def add_headers(request:, headers:, body:)
+        defaults = body.nil? ? DEFAULT_HEADERS : DEFAULT_HEADERS.merge(BODY_HEADERS)
+        RequestBuilder.merge_headers(defaults, headers).each do |key, value|
+          request[key] = value
+        end
+      end
+
+      # Escape query parameters in a URI
+      #
+      # A parameter without a value, as the flag of "?flag" is, is sent without one, rather than with the empty value
+      # of "?flag=", which an endpoint may read otherwise.
+      #
+      # @api private
+      # @param uri [URI] the URI
+      # @return [URI] the URI with escaped query parameters
+      def escape_query_params(uri)
+        URI(uri).tap do |u|
+          u.query = URI.encode_www_form(query_pairs(u.query)).gsub("%2C", ",") if u.query
+        end
+      end
+
+      # Decode the name and value of each parameter of a query
+      #
+      # A parameter without a value is given nil for one.
+      # @api private
+      # @param query [String] the query
+      # @return [Array<Array(String, String), Array(String, nil)>] the name and value of each parameter
+      def query_pairs(query)
+        query.split("&").map do |pair|
+          name, value = pair.split("=", 2)
+          [URI.decode_www_form_component(name.to_s), value&.then { |escaped| URI.decode_www_form_component(escaped) }]
+        end
+      end
+    end
+    private_constant :RequestBuilder
+  end
+end

data/lib/x/core/request_context.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module X
+  module Core
+    # The request an error names: the method it was sent with and the URI it was sent to
+    #
+    # An error says what went wrong, and code that makes many requests needs to know which request it went wrong
+    # for. The errors a request raises are built with it, so each of them reads the method and URI of that request,
+    # and names it in its message, as "GET /2/users/1: Could not find user" does.
+    #
+    # A request that names another host is not followed there with the credentials of the API, so the URI is the
+    # one the request was sent to, whole, rather than a path read against a base URL.
+    #
+    # Internal to x-core: the errors of a request include it, and the parsers and the connection build those
+    # errors with the request that raised them.
+    #
+    # @api private
+    module RequestContext
+      # The HTTP method the request was sent with
+      #
+      # @api public
+      # @return [Symbol, nil] the method, as :get, :post, :put, or :delete, or nil for an error built without one,
+      #   such as one a test built from a response alone
+      # @example Tell a read that failed from a write
+      #   writes_failed += 1 unless error.http_method.eql?(:get)
+      attr_reader :http_method
+
+      # The URI the request was sent to
+      #
+      # @api public
+      # @return [URI::Generic, nil] the URI, or nil for an error built without one
+      # @example Count the failures of each endpoint
+      #   failures[error.uri.path] += 1
+      attr_reader :uri
+
+      # The method and URI of a request, as the keywords of an error that names it
+      #
+      # The errors take the method and URI of a request rather than the Net::HTTP request itself, so that code that
+      # builds one, as a test does, depends on neither Net::HTTP nor the way x-core sends a request.
+      #
+      # @api private
+      # @param request [Net::HTTPRequest, nil] the request that failed, or nil for none
+      # @return [Hash{Symbol => Object}, nil] the http_method and uri of the request, or nil, which splats no keywords,
+      #   for none
+      # @example The keywords of a request
+      #   RequestContext.of(request) # => {http_method: "GET", uri: #<URI::HTTPS https://api.x.com/2/users/me>}
+      def self.of(request) = request && {http_method: request.method, uri: request.uri}
+
+      private
+
+      # Read the method, URI, and line of the request an error names
+      #
+      # The line is the method and the path the request was sent for, which Net::HTTP reads off the URI, so that a
+      # URI naming a host and nothing else is named as the request for its root that it was sent as.
+      #
+      # @api private
+      # @param http_method [Symbol, String, nil] the method the request was sent with, in any case, or nil for none
+      # @param uri [URI::Generic, nil] the URI the request was sent to, or nil for none
+      # @return [void]
+      def name_request(http_method, uri)
+        @http_method = http_method&.downcase&.to_sym
+        @uri = uri
+        return unless http_method && uri
+
+        path = uri.path #: String
+        @request_line = "#{http_method.upcase} #{path.empty? ? "/" : path}"
+      end
+
+      # The message of an error, behind the request it names
+      #
+      # The query is left out, since the object layer asks for every field of a resource, which makes a query
+      # longer than the rest of the message.
+      #
+      # @api private
+      # @param message [String] what went wrong
+      # @return [String] the message, behind the method and path of the request an error names, or as it is for an
+      #   error that names none
+      def message_naming_request(message)
+        line = @request_line
+        line.nil? ? message : "#{line}: #{message}"
+      end
+    end
+    private_constant :RequestContext
+  end
+end

data/lib/x/core/request_encoding.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module X
+  module Core
+    # Encodes the query strings and bodies of requests
+    #
+    # Internal to x-core: a client resolves the endpoint of each request, and of each stream it opens, and encodes
+    # the body of a request, with it.
+    #
+    # @api private
+    module RequestEncoding
+      extend self
+
+      # The slashes that begin an endpoint, which would resolve against the host of the base URL rather than its path
+      LEADING_SLASHES = %r{\A/+}
+      private_constant :LEADING_SLASHES
+
+      # The message of the error raised for a request given both a body and form fields
+      BODY_AND_FORM = "Pass a body or form fields, not both, since a request sends one body"
+      private_constant :BODY_AND_FORM
+
+      # The message of the error raised for an endpoint that does not resolve to a URL a request can be sent to
+      INVALID_ENDPOINT = "Invalid endpoint %s: %s"
+      private_constant :INVALID_ENDPOINT
+
+      # The message of the error raised for an endpoint that is not a String
+      ENDPOINT_NOT_A_STRING = "endpoint must be a String, such as \"users/me\", not a %s"
+      private_constant :ENDPOINT_NOT_A_STRING
+
+      # The message of the error raised for a body that is not a String, a Hash, or an Array
+      BODY_NOT_ENCODABLE = "body must be a String, a Hash, or an Array, not a %s; read an IO, or call to_h, to give what it holds"
+      private_constant :BODY_NOT_ENCODABLE
+
+      # Resolve an endpoint and its query parameters against a base URL
+      #
+      # An endpoint that is not a String, such as a Symbol or a URI, raises ArgumentError naming its class, rather than
+      # the NoMethodError of a String method it does not have. An endpoint that is not a valid URL reference, such as one that holds a space or a malformed percent escape,
+      # or that resolves to anything but an http or https URL with a host, such as "foo:bar", raises ArgumentError
+      # naming it, before any request is built, rather than the URI::InvalidURIError or the ArgumentError of Net::HTTP
+      # it would raise as the request was built.
+      #
+      # @api private
+      # @param base_url [String] the base URL the endpoint is relative to
+      # @param endpoint [String] the endpoint, with or without a leading slash or a query string
+      # @param params [Hash, nil] the query parameters
+      # @return [URI::HTTP] the URL of the request
+      # @raise [ArgumentError] if the endpoint is not a String, or does not resolve to an http or https URL with a host
+      def uri_for(base_url, endpoint, params)
+        uri = URI.join(base_url, endpoint_with(endpoint, params))
+        return uri if uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+
+        raise ArgumentError, format(INVALID_ENDPOINT, endpoint.inspect, "it does not name an http or https URL")
+      rescue URI::InvalidURIError
+        raise ArgumentError, format(INVALID_ENDPOINT, endpoint.inspect, "it is not a valid URL; escape what a URL may not hold, such as a space")
+      end
+
+      # Encode a form as form fields, and a Hash or an Array body as JSON
+      #
+      # A String body is given back as it is.
+      #
+      # Form fields are encoded as query parameters are, so a field of nil is dropped, an Array is joined with commas,
+      # and a Time is given in UTC in the ISO 8601 form the API takes. A Hash or an Array is encoded as JSON, since
+      # Net::HTTP sends nothing but a String. A body of any other class, such as an IO or a Symbol, raises
+      # ArgumentError naming its class, before any request is built, rather than be sent as the JSON of its to_s,
+      # which is the name of the object rather than what it holds.
+      #
+      # @api private
+      # @param body [String, Hash, Array, nil] the request body
+      # @param form [Hash, nil] the form fields
+      # @return [String, nil] the encoded body
+      # @raise [ArgumentError] if both a body and form fields are given, which would send one and drop the other
+      # @raise [ArgumentError] if the body is not a String, a Hash, an Array, or nil
+      def encode_body(body, form)
+        raise ArgumentError, BODY_AND_FORM if body && form
+        return encode_fields(form) unless form.nil?
+
+        case body
+        when nil, String then body
+        when Hash, Array then JSON.generate(body)
+        else raise ArgumentError, format(BODY_NOT_ENCODABLE, body.class)
+        end
+      end
+
+      private
+
+      # Append query parameters to an endpoint, relative to the base URL
+      #
+      # An endpoint resolves against the base URL, which would drop the path of the base URL, such as the /2/ of the
+      # API version, for an endpoint that begins with a slash, so leading slashes are removed.
+      #
+      # @api private
+      # @param endpoint [String] the endpoint, with or without a leading slash or a query string
+      # @param params [Hash, nil] the query parameters
+      # @return [String] the endpoint, without leading slashes, with the parameters in its query string
+      # @raise [ArgumentError] if the endpoint is not a String
+      def endpoint_with(endpoint, params)
+        raise ArgumentError, format(ENDPOINT_NOT_A_STRING, endpoint.class) unless endpoint.is_a?(String)
+
+        endpoint = endpoint.sub(LEADING_SLASHES, "")
+        query = encode_fields(params.to_h)
+        return endpoint if query.empty?
+
+        "#{endpoint}#{endpoint.include?("?") ? "&" : "?"}#{query}"
+      end
+
+      # Encode query parameters or form fields
+      #
+      # A field of nil is dropped, and the others are encoded with query_value.
+      #
+      # @api private
+      # @param fields [Hash] the parameters or fields
+      # @return [String] the encoded fields
+      def encode_fields(fields) = URI.encode_www_form(fields.compact.transform_values { |value| query_value(value) })
+
+      # Encode a query parameter or form field value
+      #
+      # An Array is joined with commas, and a Time is given in UTC in the ISO 8601 form the API takes.
+      #
+      # @api private
+      # @param value [Object] the value
+      # @return [Object] the encoded value
+      def query_value(value)
+        case value
+        when Array then value.join(",")
+        when Time then value.getutc.iso8601
+        else value
+        end
+      end
+    end
+    private_constant :RequestEncoding
+  end
+end