x-core 1.0.0

data/lib/x/core/connection.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+require "zlib"
+require_relative "connection_pool"
+require_relative "connection_proxy"
+require_relative "connection_request"
+require_relative "proxy_setting"
+require_relative "request_context"
+require_relative "setting_validator"
+require_relative "errors/network_error"
+require_relative "errors/callback_error"
+
+module X
+  module Core
+    # Manages HTTP connections to the X API
+    #
+    # Internal to x-core: Client, and the authenticators and authorization that fetch tokens send
+    # their requests with it, so that it can change within 1.x. Configure it through the settings of Client, such as
+    # proxy_url and the timeouts.
+    #
+    # Requests keep their connections open for the next request to the same host, which saves opening a TCP and
+    # TLS connection each time. A stream opens a connection of its own, which it holds for as long as it reads.
+    #
+    # A connection keeps the settings it was built with for as long as it lives, as {Client} does, so a request never
+    # opens a connection under a setting another thread is halfway through changing. Build another connection to
+    # reach the API differently.
+    #
+    # @api private
+    class Connection
+      include ConnectionProxy
+      include ConnectionRequest
+      include ProxySetting
+
+      # Default timeout for opening connections in seconds; opening a connection is a TCP handshake and a TLS one,
+      # which a reachable host finishes in well under a second, so a host that takes longer is one a request waits
+      # on rather than reaches, and it is given less time than reading a response, which an endpoint may be slow to
+      # send
+      DEFAULT_OPEN_TIMEOUT = 10 # seconds
+      # Default timeout for reading responses in seconds
+      DEFAULT_READ_TIMEOUT = 60 # seconds
+      # Default timeout for writing requests in seconds
+      DEFAULT_WRITE_TIMEOUT = 60 # seconds
+      # Default time to keep a connection open for the next request to the same host, in seconds; X holds an idle
+      # connection open for more than five minutes, so a connection closed within this time was closed by a proxy
+      DEFAULT_KEEP_ALIVE_TIMEOUT = 30 # seconds
+      # The settings a connection is opened under that are values, which a connection that shares the pool of another
+      # holds equal ones of; the debug output is an object that is written to, so it is the same one, rather than an
+      # equal one, as an empty Array is to another
+      SETTINGS = %i[open_timeout read_timeout write_timeout keep_alive_timeout proxy_url].freeze
+      private_constant :SETTINGS
+      # The timeout for opening connections in seconds
+      # @api private
+      # @return [Integer, Float, nil] the timeout for opening connections in seconds, or nil for none
+      # @example Get the open timeout
+      #   connection.open_timeout # => 10
+      attr_reader :open_timeout
+
+      # The timeout for reading responses in seconds
+      # @api private
+      # @return [Integer, Float, nil] the timeout for reading responses in seconds, or nil for none
+      # @example Get the read timeout
+      #   connection.read_timeout # => 60
+      attr_reader :read_timeout
+
+      # The timeout for writing requests in seconds
+      # @api private
+      # @return [Integer, Float, nil] the timeout for writing requests in seconds, or nil for none
+      # @example Get the write timeout
+      #   connection.write_timeout # => 60
+      attr_reader :write_timeout
+
+      # The IO object for debug output
+      # @api private
+      # @return [IO, #<<, nil] the IO object for debug output, or anything else that takes a String with <<, such as
+      #   a Logger, or nil for none
+      # @example Get the debug output
+      #   connection.debug_output
+      attr_reader :debug_output
+
+      # The time to keep a connection open for the next request, in seconds
+      # @api private
+      # @return [Integer, Float] the time in seconds
+      # @example Get the keep-alive timeout
+      #   connection.keep_alive_timeout # => 30
+      attr_reader :keep_alive_timeout
+
+      # Initialize a new connection
+      #
+      # @api private
+      # @param open_timeout [Integer, Float, nil] the timeout for opening connections in seconds, or nil for none
+      # @param read_timeout [Integer, Float, nil] the timeout for reading responses in seconds, or nil for none
+      # @param write_timeout [Integer, Float, nil] the timeout for writing requests in seconds, or nil for none
+      # @param keep_alive_timeout [Integer, Float] the time to keep a connection open for the next request to the same
+      #   host, in seconds, which a proxy that closes idle connections sooner than X does may need lowered
+      # @param debug_output [IO, #<<, nil] the IO object for debug output, or anything else that takes a String with <<,
+      #   such as a StringIO or a Logger
+      # @param proxy_url [String, URI::Generic, nil] the proxy URL for requests
+      # @return [Connection] a new connection instance
+      # @raise [ArgumentError] if a timeout is neither a finite number of seconds of at least 0 nor, for any but
+      #   keep_alive_timeout, nil
+      # @raise [ArgumentError] if debug_output is a String, or is neither nil nor takes a String with <<
+      # @example Create a connection with default settings
+      #   connection = X::Core::Connection.new
+      # @example Create a connection with custom timeouts
+      #   connection = X::Core::Connection.new(open_timeout: 30, read_timeout: 30)
+      def initialize(open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT,
+        write_timeout: DEFAULT_WRITE_TIMEOUT, keep_alive_timeout: DEFAULT_KEEP_ALIVE_TIMEOUT, debug_output: nil, proxy_url: nil)
+        @open_timeout = SettingValidator.timeout!(:open_timeout, open_timeout)
+        @read_timeout = SettingValidator.timeout!(:read_timeout, read_timeout)
+        @write_timeout = SettingValidator.timeout!(:write_timeout, write_timeout)
+        @keep_alive_timeout = SettingValidator.finite_seconds!(:keep_alive_timeout, keep_alive_timeout)
+        @debug_output = SettingValidator.debug_output!(debug_output)
+        @pool = ConnectionPool.new
+        initialize_proxy(proxy_url)
+      end
+
+      # Summarize the connection for the console without revealing proxy credentials
+      #
+      # @api private
+      # @return [String] the class name, proxy URL, and timeouts
+      # @example Inspect a connection
+      #   connection.inspect # => #<X::Core::Connection proxy_url="http://proxy.example.com:8080" open_timeout=10 ...>
+      def inspect
+        "#<#{self.class} proxy_url=#{redacted_proxy_url.inspect} open_timeout=#{open_timeout} " \
+          "read_timeout=#{read_timeout} write_timeout=#{write_timeout}>"
+      end
+
+      # Perform an HTTP request
+      #
+      # Internal to x-core: Client, its redirects, and token requests send their requests with it, so that it can change
+      # within 1.x, as the Net::HTTP requests it takes may.
+      #
+      # The body of the response is tagged UTF-8, the encoding of the JSON the API sends, rather than the binary that
+      # Net::HTTP reads it as, so that it can be searched and joined with other Strings. A body that is not valid
+      # UTF-8, such as the page of a proxy in another encoding, keeps its bytes, and valid_encoding? tells it apart.
+      #
+      # @api private
+      # @param request [Net::HTTPRequest] the HTTP request to perform
+      # @return [Net::HTTPResponse] the HTTP response, whose body is tagged UTF-8
+      # @raise [NetworkError] if a network error occurs, or Net::HTTP cannot read the response, as one whose header
+      #   holds a bare CR, for which it raises ArgumentError
+      # @raise [ArgumentError] if the connection was given no proxy and the proxy the environment names for the request
+      #   cannot be parsed, or is not an HTTP or HTTPS URL that names a host, with a message that names the variables
+      #   read for its scheme and leaves out the value, and with no cause
+      # @example Perform a request
+      #   response = connection.perform(request: request)
+      def perform(request:)
+        uri = request.uri
+        hostname, port = host_and_port(uri)
+        use_ssl = uri.scheme.eql?("https")
+        send_request(request, [use_ssl, hostname, port], -> { open_http_client(uri, use_ssl) })
+      rescue InvalidEnvironmentProxy
+        raise environment_proxy_error(request.uri), cause: nil
+      rescue *NETWORK_ERRORS, ArgumentError => e
+        raise NetworkError.new("Network error: #{e}", **RequestContext.of(request))
+      end
+
+      # Perform a streaming HTTP request
+      #
+      # Internal to x-core: Client#get_stream opens its requests with it.
+      #
+      # The connection is opened for this request and closed once the block returns, rather than taken from the
+      # connections kept open and given back, since a stream holds its connection for as long as it reads. Once the
+      # block returns, the connection is closed with what is left of the body unread, rather than read to its end, as
+      # Net::HTTP would otherwise read it, which a stream never reaches.
+      #
+      # An error the block raises, which the client tags as a CallbackError, is raised tagged, rather than reported as
+      # a network error: the block of a stream runs inside the request that reads it. The NetworkError the read_body
+      # of a StreamResponse raises for an error of the socket, which the client leaves untagged, is raised as it is,
+      # rather than wrapped in another.
+      #
+      # The body is not tagged UTF-8 here, as the body of {#perform} is: Net::HTTP tags a body it reads whole, and
+      # raises for one it passes to a block a chunk at a time, as a stream is read.
+      #
+      # @api private
+      # @param request [Net::HTTPRequest] the HTTP request to perform
+      # @yield [Net::HTTPResponse] the HTTP response for streaming
+      # @return [Object] what the block returns
+      # @raise [NetworkError] if a network error occurs, or Net::HTTP cannot read the response, as one whose header
+      #   holds a bare CR, for which it raises ArgumentError
+      # @raise [ArgumentError] if the connection was given no proxy and the proxy the environment names for the request
+      #   cannot be parsed, or is not an HTTP or HTTPS URL that names a host, with a message that names the variables
+      #   read for its scheme and leaves out the value, and with no cause
+      # @raise [CallbackError] if the block raises an error the client tagged
+      # @example Perform a streaming request
+      #   connection.perform_stream(request: request) { |response| response.read_body { |chunk| } }
+      def perform_stream(request:)
+        http_client = build_http_client(request.uri)
+        http_client.use_ssl = request.uri.scheme.eql?("https")
+        catch { |done| http_client.request(request) { |response| throw done, yield(response) } }
+      rescue InvalidEnvironmentProxy
+        raise environment_proxy_error(request.uri), cause: nil
+      rescue *NETWORK_ERRORS, ArgumentError => e
+        raise NetworkError.new("Network error: #{e}", **RequestContext.of(request))
+      end
+
+      # Check whether an error is one a request raises as a NetworkError
+      #
+      # @api private
+      # @param error [Exception] the error
+      # @return [Boolean] true if the error is one of a socket
+      # @example Check an error a stream raised
+      #   X::Core::Connection.network_error?(IOError.new) # => true
+      def self.network_error?(error) = NETWORK_ERRORS.any? { |network_error| error.is_a?(network_error) }
+
+      # Close the connections kept open between requests
+      #
+      # A later request opens a connection again. Nothing else closes them: the sockets of a connection that is
+      # dropped rather than closed are shut as the garbage collector reclaims them, at a time the process does not
+      # choose and without the shutdown this performs.
+      #
+      # @api private
+      # @return [void]
+      # @example Close the connections before a long pause
+      #   connection.close
+      def close
+        @pool.clear
+      end
+
+      # Take connections from the pool of another connection that opens them alike
+      #
+      # Internal to x-core: Client#with gives a copy the connections of the client it was copied from with it. The
+      # two then take their connections from one pool, and close them together, so a copy made for each request opens
+      # none of its own. A connection whose timeouts, keep-alive timeout, debug output, or proxy differ keeps a pool
+      # of its own, since a connection is opened under those. The debug output differs unless it is the same object,
+      # since a connection writes to the one it was opened under: an Array is equal to another that holds the same,
+      # and a request written to the wrong one is lost to the one it was meant for.
+      #
+      # @api private
+      # @param other [Connection] the connection whose pool to share
+      # @return [void]
+      # @example Share the connections of another connection
+      #   connection.share_pool_of(other)
+      def share_pool_of(other)
+        output = debug_output #: untyped
+        @pool = other.__send__(:pool) if output.equal?(other.debug_output) && SETTINGS.all? { |name| __send__(name) == other.__send__(name) }
+      end
+
+      private
+
+      # The connections kept open between requests
+      # @api private
+      # @return [ConnectionPool] the pool
+      attr_reader :pool
+
+      # The host and port to connect to for a URI
+      #
+      # The URI of a request is an HTTP or HTTPS URL, since Net::HTTP builds a request from no other, so it names both.
+      #
+      # @api private
+      # @param uri [URI::Generic] the URI of the request
+      # @return [Array(String, Integer)] the host and the port to connect to
+      def host_and_port(uri)
+        hostname = uri.hostname #: String
+        port = uri.port #: Integer
+        [hostname, port]
+      end
+
+      # Open an HTTP client for requests read whole, which tags each body UTF-8
+      #
+      # @api private
+      # @param uri [URI::Generic] the URI of the request
+      # @param use_ssl [Boolean] whether to connect over TLS
+      # @return [Net::HTTP] the HTTP client
+      def open_http_client(uri, use_ssl)
+        build_http_client(uri).tap do |http_client|
+          http_client.use_ssl = use_ssl
+          http_client.response_body_encoding = Encoding::UTF_8
+        end
+      end
+
+      # Build an HTTP client for the host of a URI
+      #
+      # The client connects to an HTTPS proxy over TLS. A client that reaches its host directly is given no proxy to
+      # resolve, rather than the :ENV of Net::HTTP, which reads http_proxy for a request of any scheme: the proxy of a
+      # request is resolved from the scheme of its own URI, by ConnectionProxy.
+      #
+      # @api private
+      # @param uri [URI::Generic] the URI of the request
+      # @return [Net::HTTP] the HTTP client
+      def build_http_client(uri)
+        host, port = host_and_port(uri)
+        proxy = proxy_for(uri)
+        http_client = if proxy
+          Net::HTTP.new(host, port, proxy.hostname, proxy.port, decode(proxy.user), decode(proxy.password), nil, proxy.instance_of?(URI::HTTPS))
+        else
+          Net::HTTP.new(host, port, nil)
+        end
+        configure_http_client(http_client)
+      end
+
+      # Configure a new HTTP client with the timeouts and debug output of the connection
+      #
+      # The settings of a connection never change, so they are applied as each client is opened, rather than before
+      # each request one makes.
+      #
+      # Net::HTTP sends a GET, PUT, or DELETE request again by itself after a timeout or a dropped connection, with the
+      # same OAuth 1.0a nonce and signature, which the API may bill twice, so its retries are turned off: a request
+      # that fails raises NetworkError, and the caller decides whether to send it again.
+      #
+      # Net::HTTP keeps a connection for two seconds by default, which reuses it within a burst of requests alone, so
+      # it keeps one for keep_alive_timeout instead.
+      #
+      # Net::HTTP returns a body that ends before the length its Content-Length gives as though it were whole, which
+      # would be parsed as JSON cut short, so ignore_eof is turned off: a connection that closes before the body is
+      # read raises EOFError, which a request raises as a NetworkError.
+      #
+      # @api private
+      # @param http_client [Net::HTTP] the HTTP client to configure
+      # @return [Net::HTTP] the configured HTTP client
+      def configure_http_client(http_client)
+        http_client.tap do |c|
+          c.open_timeout = open_timeout
+          c.read_timeout = read_timeout
+          c.write_timeout = write_timeout
+          c.max_retries = 0
+          c.ignore_eof = false
+          c.keep_alive_timeout = keep_alive_timeout
+          c.set_debug_output(debug_output)
+        end
+      end
+    end
+    private_constant :Connection
+  end
+end

data/lib/x/core/connection_pool.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "net/http"
+
+module X
+  module Core
+    # The open HTTP connections of a Connection, kept to be used again by the next request to the same host
+    #
+    # A connection is used by one request at a time: a request takes an idle connection, or opens one, and gives
+    # it back once it has read the response. A request that fails closes its connection instead, and so does one
+    # that finishes after clear. A forked process opens
+    # connections of its own rather than share its parent's.
+    #
+    # @api private
+    class ConnectionPool
+      # Most idle connections kept open to each host, as many as the chunks x-uploads sends at once at most, so that
+      # each sender of an upload keeps its connection from one chunk to the next
+      MAX_IDLE = 16
+
+      # Initialize an empty pool
+      #
+      # @api private
+      # @return [ConnectionPool] a new pool
+      def initialize
+        @lock = Mutex.new
+      end
+
+      # Run a block with an open connection, keeping it for later if the block returns
+      #
+      # The block is told whether the connection was one the pool had kept open, since a connection the peer closed
+      # while it was idle fails the request that takes it, where one opened for the request did not go stale.
+      #
+      # @api private
+      # @param key [Array] the scheme, host, and port the connection is to
+      # @param open [Proc] builds a connection to the host, when none is idle
+      # @param fresh [Boolean] whether to open a connection even when one is idle
+      # @yield [Net::HTTP, Boolean] the started connection, and whether it came from the pool
+      # @return [Object] what the block returns
+      def with(key, open, fresh: false)
+        pool, http_client, pooled = checkout(key, open, fresh)
+        kept = nil
+        begin
+          result = yield http_client, pooled
+          kept = checkin(key, http_client, pool)
+          result
+        ensure
+          close(http_client) unless kept
+        end
+      end
+
+      # Close every idle connection, and each one in use once its request finishes
+      #
+      # A forked process leaves the connections its parent opened alone, since closing one would end the parent's
+      # TLS session over the socket they share.
+      #
+      # @api private
+      # @return [void]
+      def clear
+        idle = @lock.synchronize do
+          forget_after_fork
+          @idle.values.flatten.tap { @idle = {} }
+        end
+        idle.each { |http_client| close(http_client) }
+      end
+
+      private
+
+      # Take an idle connection to a host, or open one
+      # @api private
+      # @param key [Array] the scheme, host, and port
+      # @param open [Proc] builds a connection to the host
+      # @param fresh [Boolean] whether to open a connection even when one is idle
+      # @return [Array(Hash, Net::HTTP, bool)] the idle connections the connection returns to, the started
+      #   connection, and whether it was idle rather than opened for this request
+      def checkout(key, open, fresh)
+        pool, idle = @lock.synchronize do
+          forget_after_fork
+          [@idle, (@idle[key]&.pop unless fresh)]
+        end
+        http_client = idle || open.call
+        http_client.start unless http_client.started?
+        [pool, http_client, !idle.nil?]
+      end
+
+      # Keep a connection for later, unless the pool was cleared or is full
+      # @api private
+      # @param key [Array] the scheme, host, and port
+      # @param http_client [Net::HTTP] the connection
+      # @param pool [Hash] the idle connections when the connection was taken, which clear replaces
+      # @return [Array<Net::HTTP>, nil] the idle connections to the host, or nil if the connection was not kept
+      def checkin(key, http_client, pool)
+        @lock.synchronize do
+          idle = @idle[key] ||= []
+          idle.push(http_client) if pool.equal?(@idle) && idle.size < MAX_IDLE
+        end
+      end
+
+      # Drop the connections a parent process opened, which a fork must not share
+      #
+      # The first call in a process, which is the first in a new pool, starts the pool with no connections.
+      #
+      # @api private
+      # @return [void]
+      def forget_after_fork
+        return if @pid.eql?(Process.pid)
+
+        @idle = {}
+        @pid = Process.pid
+      end
+
+      # Close a connection, unless it is closed already
+      # @api private
+      # @param http_client [Net::HTTP] the connection
+      # @return [void]
+      def close(http_client)
+        http_client.finish
+      rescue IOError
+        nil
+      end
+    end
+    private_constant :ConnectionPool
+  end
+end

data/lib/x/core/connection_proxy.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module X
+  module Core
+    # The proxy of a connection, parsed from its URL, included into Connection
+    #
+    # A proxy URL can hold the user and password of the proxy, so a connection reveals neither its URL nor anything
+    # parsed from it, and its inspect leaves out the user and password; see {ProxySetting}.
+    #
+    # A connection given no proxy URL takes the proxy the environment names for each request, and sends a request to
+    # a host that no_proxy names without a proxy. Set no_proxy to reach every host directly from a process whose
+    # environment names a proxy. A proxy of the environment that cannot be parsed, or that is not an HTTP or HTTPS
+    # URL that names a host, such as proxy.example.com:8080, which has no scheme, is refused as a proxy URL given is,
+    # with an ArgumentError that names the variables it is read from and leaves out its value, which can hold a
+    # password, though by the request that reads it, since the environment is read for each request that opens a
+    # connection, rather than where the client is built. A variable that is empty names no proxy, as it names none
+    # to Ruby.
+    #
+    # Most HTTP clients take the proxy the environment names, and Net::HTTP reads http_proxy alone, whatever the scheme of the request, which would leave the HTTPS requests
+    # these gems make unproxied for anyone who sets https_proxy, and proxied through whatever http_proxy names for
+    # anyone who sets that instead. So the proxy of a request is resolved here, from the scheme of its own URI, and
+    # passed to Net::HTTP, which is given no proxy of its own to resolve.
+    #
+    # @api private
+    module ConnectionProxy
+      # The message of the error an HTTPS request raises for a proxy of the environment that is no proxy URL, which
+      # names the variables URI::Generic#find_proxy reads for one, in the order it reads them, and leaves out the value
+      INVALID_HTTPS_PROXY = "Invalid proxy URL in the environment, in https_proxy or HTTPS_PROXY"
+      # The message of the error an HTTP request raises for a proxy of the environment that is no proxy URL, which
+      # names the variables URI::Generic#find_proxy reads for one, and leaves out the value: http_proxy, and else
+      # HTTP_PROXY, or, in a CGI process, which REQUEST_METHOD is set in, CGI_HTTP_PROXY in place of HTTP_PROXY
+      INVALID_HTTP_PROXY = "Invalid proxy URL in the environment, in http_proxy, HTTP_PROXY, or CGI_HTTP_PROXY"
+      private_constant :INVALID_HTTPS_PROXY, :INVALID_HTTP_PROXY
+
+      # Raised for a proxy of the environment that cannot be parsed, or is not an HTTP or HTTPS URL that names a host,
+      # inside a request, which raises an ArgumentError for it in turn, rather than the NetworkError it raises for an
+      # ArgumentError of Net::HTTP
+      #
+      # @api private
+      class InvalidEnvironmentProxy < StandardError; end
+      private_constant :InvalidEnvironmentProxy
+
+      private
+
+      # The parsed proxy URI
+      # @api private
+      # @return [URI::Generic, nil] the parsed proxy URI, or nil to take the proxy the environment names
+      attr_reader :proxy_uri
+
+      # Read the proxy URL a connection is built with
+      #
+      # A connection keeps it for as long as it lives, as it keeps every setting. The message of an invalid URL
+      # leaves out its user and password.
+      #
+      # @api private
+      # @param proxy_url [String, URI::Generic, nil] the proxy URL, or nil to take the proxy from the environment
+      # @return [void]
+      # @raise [ArgumentError] if the proxy URL is invalid
+      def initialize_proxy(proxy_url)
+        @proxy_uri = proxy_url&.then { |url| parse_proxy_url(url) }
+        @proxy_url = @proxy_uri&.then { |uri| String(uri) }
+      end
+
+      # The proxy of a request, the one given or the one the environment names
+      #
+      # The proxy the connection was given stands for every request. Otherwise the URI of the request is asked for
+      # the proxy of its own scheme, which is held to what a proxy URL given is: URI::Generic#find_proxy parses a
+      # value without a scheme, such as proxy.example.com:8080, into a URI that names no host, which Net::HTTP would
+      # take for no proxy at all, and send the request around the proxy its environment names. A variable that is
+      # empty, and a host that no_proxy names, have no proxy to check. The error of a proxy of the environment that
+      # cannot be parsed has no cause, since the message of the URI::InvalidURIError holds the value of the variable
+      # whole, with the password a proxy URL can hold.
+      #
+      # @api private
+      # @param uri [URI::Generic] the URI of the request
+      # @return [URI::Generic, nil] the proxy of the request, or nil to reach the host directly
+      # @raise [InvalidEnvironmentProxy] if the proxy the environment names cannot be parsed, or is not an HTTP or
+      #   HTTPS URL that names a host
+      def proxy_for(uri)
+        proxy_uri || uri.find_proxy&.tap { |proxy| raise InvalidEnvironmentProxy unless proxy_server?(proxy) }
+      rescue URI::InvalidURIError
+        raise InvalidEnvironmentProxy, cause: nil
+      end
+
+      # The error a request raises for a proxy of the environment that is no proxy URL
+      #
+      # The variable the proxy was read from is not looked up again, which would repeat the lookup of
+      # URI::Generic#find_proxy, so the message names each variable that is read for the scheme of the request, in
+      # either case, and is true whichever of them was set.
+      #
+      # @api private
+      # @param uri [URI::Generic] the URI of the request, whose scheme names the variables the proxy was read from
+      # @return [ArgumentError] the error, whose message names the variables and leaves out the value
+      def environment_proxy_error(uri) = ArgumentError.new(uri.scheme.eql?("https") ? INVALID_HTTPS_PROXY : INVALID_HTTP_PROXY)
+
+      # A percent-encoded component of a proxy URL, decoded
+      #
+      # @api private
+      # @param component [String, nil] the component, or nil for none
+      # @return [String, nil] the decoded component, or nil for none
+      def decode(component) = component&.then { |value| URI.decode_uri_component(value) }
+
+      # The proxy URL without its user and password
+      # @api private
+      # @return [String, nil] the proxy URL, without its user and password
+      def redacted_proxy_url = proxy_url&.then { |url| redact(url) }
+
+      # Parse a proxy URL, which must be an HTTP or HTTPS URL that names a host
+      #
+      # A URL that names no host, such as http:proxy:8080, is refused, since Net::HTTP would take its missing host for
+      # no proxy at all and send each request around the proxy. The URL is parsed anew, so that a URI the caller
+      # changes later does not change the proxy.
+      #
+      # @api private
+      # @param proxy_url [String, URI::Generic] the proxy URL
+      # @return [URI::HTTP] the parsed proxy URL
+      # @raise [ArgumentError] if the proxy URL is invalid
+      def parse_proxy_url(proxy_url)
+        proxy_uri = URI(String(proxy_url))
+        raise ArgumentError, "Invalid proxy URL: #{redact(proxy_url)}" unless proxy_server?(proxy_uri)
+
+        proxy_uri
+      rescue URI::InvalidURIError
+        raise ArgumentError, "Invalid proxy URL: #{redact(proxy_url)}", cause: nil
+      end
+
+      # Check whether a URI names a proxy, as an HTTP or HTTPS URL with a host does
+      #
+      # A proxy URL given and the proxy of the environment are held to it alike. A user, a password, a port, and a
+      # path are each allowed, and the path is not read.
+      #
+      # @api private
+      # @param uri [URI::Generic] the parsed proxy URL
+      # @return [Boolean] true if the URI is an HTTP or HTTPS URL that names a host
+      def proxy_server?(uri) = uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+
+      # A proxy URL without its user and password
+      #
+      # A password written into a URL unescaped can hold any character, an @ or a / among them, so everything
+      # between the scheme and the last @ is left out, and everything before the last @ of a URL without a scheme.
+      #
+      # @api private
+      # @param proxy_url [String, URI::Generic] the proxy URL
+      # @return [String] the URL, without the user and password
+      def redact(proxy_url) = String(proxy_url).sub(%r{([^/]*//)?.*@}m, "\\1")
+    end
+    private_constant :ConnectionProxy
+  end
+end