x-core 1.0.0

data/lib/x/core/client_app_only.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "monitor"
+require_relative "app_only_authenticator"
+require_relative "errors/unsupported_operation"
+
+module X
+  module Core
+    # The app-only copy of a client, for the endpoints that refuse OAuth 1.0a, included into ClientInternals
+    # @api private
+    module ClientAppOnly
+      # The message of the error raised for a client that holds no credentials of the app to authenticate with
+      NO_APP_CREDENTIALS = "A client that authenticates with OAuth 2.0 as a user, and holds neither the app's bearer " \
+        "token nor its API key and secret, cannot authenticate as the app. Pass the client one of them, beside the " \
+        "OAuth 2.0 credentials rather than an OAuth2Authenticator, which is given alone"
+      private_constant :NO_APP_CREDENTIALS
+
+      # A client that authenticates as the app, which Client#app_only returns
+      #
+      # A client that authenticates as a user returns a copy that authenticates with the app's bearer token, built
+      # once; any other returns itself; see {Client#app_only}.
+      #
+      # @api private
+      # @param client [Client] the client these are the internals of
+      # @return [Client] a copy that authenticates with the bearer token, or the client itself
+      # @raise [UnsupportedOperation] if the client authenticates with OAuth 2.0 as a user and holds no credentials of
+      #   the app
+      def app_only(client)
+        case authenticator
+        when OAuth1Authenticator, OAuth2Authenticator
+          raise UnsupportedOperation, NO_APP_CREDENTIALS unless bearer_token || app_credentials
+
+          app_only_copy(client)
+        else client
+        end
+      end
+
+      private
+
+      # The app-only copy of the client, built once
+      #
+      # The credentials and settings of a client never change, so the copy is built once and returned from then on.
+      # It is built under a lock, so that threads which ask for it together build one copy and fetch one token.
+      #
+      # @api private
+      # @param client [Client] the client these are the internals of
+      # @return [Client] the copy
+      def app_only_copy(client)
+        @app_only_monitor.synchronize { @app_only ||= build_app_only(client) }
+      end
+
+      # Build a copy that holds the app's credentials and bearer token
+      # @api private
+      # @param client [Client] the client these are the internals of
+      # @return [Client] the copy
+      def build_app_only(client)
+        key, secret = app_credentials
+        with(client, {**credentials.to_h { |name, _| [name, nil] }, api_key: key, api_key_secret: secret, bearer_token: app_bearer_token})
+      end
+
+      # The app-only bearer token, the client's own or one it fetches
+      # @api private
+      # @return [String] the bearer token
+      def app_bearer_token = bearer_token || app_token.__send__(:bearer_token)
+
+      # The authenticator that fetches the app-only bearer token, shared with copies
+      #
+      # It is built once, and fetches the token when it is first asked for it, and holds it from then on, so the client,
+      # and each copy of it that {#share_app_token} gave it to, fetch it once between them.
+      #
+      # @api private
+      # @return [AppOnlyAuthenticator] the authenticator
+      def app_token
+        @app_only_monitor.synchronize do
+          @app_token ||= begin
+            key, secret = app_credentials #: [String, String]
+            AppOnlyAuthenticator.new(api_key: key, api_key_secret: secret).__send__(:token_requests_over, @connection, base_url, headers)
+          end
+        end
+      end
+
+      # Share the app-only bearer token of the client this one was copied from
+      #
+      # A copy that holds the same credentials of the app, and the same base URL, would fetch the same token, from an
+      # endpoint X limits the rate of, so it takes the authenticator that fetches the token of the client it was
+      # copied from, rather than fetch one of its own for each copy, as a copy made for each request would. The
+      # internals of the client copied call it on those of the copy with __send__, since it is private.
+      #
+      # @api private
+      # @param other [ClientInternals] the internals of the client this one was copied from
+      # @return [void]
+      def share_app_token(other)
+        credentials = app_credentials or return
+        @app_token = other.__send__(:app_token) if credentials.eql?(other.__send__(:app_credentials)) && base_url.eql?(other.base_url)
+      end
+
+      # The API key and secret of the app
+      #
+      # They are the ones an OAuth1Authenticator signs with, which a client given one holds no copy of, or else the
+      # client's own, of which it holds both or neither, since a credential outside a complete set is refused.
+      #
+      # @api private
+      # @return [Array(String, String), nil] the API key and secret, or nil for a client that holds neither
+      def app_credentials
+        current = authenticator
+        return [current.api_key, current.__send__(:api_key_secret)] if current.is_a?(OAuth1Authenticator)
+
+        key = api_key
+        secret = api_key_secret #: String
+        [key, secret] if key
+      end
+    end
+    private_constant :ClientAppOnly
+  end
+end

data/lib/x/core/client_credentials.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module X
+  module Core
+    # The authentication credentials of a client, which it reads but never changes, included into ClientInternals
+    #
+    # A client is built with the credentials it keeps for as long as it lives. {Client#with} derives a client whose
+    # credentials differ, rather than replacing the ones a client holds, so that a request never signs with a mix of
+    # old and new credentials.
+    #
+    # @api private
+    module ClientCredentials
+      # The API key for OAuth 1.0a authentication, as the client was given it
+      #
+      # It is nil for a client given an authenticator in place of credentials; see {#api_key_in_use}.
+      #
+      # @api private
+      # @return [String, nil] the API key for OAuth 1.0a authentication
+      attr_reader :api_key
+
+      # The OAuth 2.0 client ID, as the client was given it
+      #
+      # It is nil for a client given an authenticator in place of credentials; see {#client_id_in_use}.
+      #
+      # @api private
+      # @return [String, nil] the OAuth 2.0 client ID
+      attr_reader :client_id
+
+      # The API key of the client, or of the authenticator it was given
+      #
+      # An OAuth1Authenticator or AppOnlyAuthenticator given in place of credentials holds the API key of the client.
+      # {Client#api_key} returns it.
+      #
+      # @api private
+      # @return [String, nil] the API key, or nil if neither holds one
+      def api_key_in_use
+        case (given = @given_authenticator)
+        when OAuth1Authenticator, AppOnlyAuthenticator then given.api_key
+        else api_key
+        end
+      end
+
+      # The OAuth 2.0 client ID of the client, or of the authenticator it was given
+      #
+      # An OAuth2Authenticator given in place of credentials holds the client ID of the client.
+      # {Client#client_id} returns it.
+      #
+      # @api private
+      # @return [String, nil] the client ID, or nil if neither holds one
+      def client_id_in_use
+        given = @given_authenticator
+        given.is_a?(OAuth2Authenticator) ? given.client_id : client_id
+      end
+
+      private
+
+      # The API key secret for OAuth 1.0a authentication
+      #
+      # It is private, as {Client#inspect} hides it, and the client holds it here rather than in a reader of its own,
+      # so that code that reflects over a client never reads a secret out of it. {Client#with} carries it to a copy
+      # without revealing it, and the authenticator of a client holds the credentials it signs with.
+      #
+      # @api private
+      # @return [String, nil] the API key secret for OAuth 1.0a authentication
+      attr_reader :api_key_secret
+
+      # The access token secret for OAuth 1.0a authentication
+      #
+      # It is private for the reason {#api_key_secret} is.
+      #
+      # @api private
+      # @return [String, nil] the access token secret for OAuth 1.0a authentication
+      attr_reader :access_token_secret
+
+      # The bearer token for authentication
+      #
+      # It is private for the reason {#api_key_secret} is.
+      #
+      # @api private
+      # @return [String, nil] the bearer token for authentication
+      attr_reader :bearer_token
+
+      # The OAuth 2.0 client secret
+      #
+      # It is private for the reason {#api_key_secret} is.
+      #
+      # @api private
+      # @return [String, nil] the OAuth 2.0 client secret
+      attr_reader :client_secret
+
+      # The credentials, as initialize accepts them
+      # @api private
+      # @return [Hash{Symbol => String, Time, Array<String>, nil}] the credentials
+      def credentials = {api_key:, api_key_secret:, access_token:, access_token_secret:, bearer_token:, client_id:, client_secret:, refresh_token:, expires_at:, scopes:}
+
+      # Initialize credential instance variables
+      # @api private
+      # @return [void]
+      def initialize_credentials(api_key:, api_key_secret:, access_token:, access_token_secret:, bearer_token:,
+        client_id:, client_secret:, refresh_token:, expires_at:, scopes:)
+        CredentialValidator.validate_values!(api_key:, api_key_secret:, access_token:, access_token_secret:, bearer_token:, client_id:, client_secret:, refresh_token:, expires_at:, scopes:)
+        @api_key, @api_key_secret = SettingValidator.frozen(api_key), SettingValidator.frozen(api_key_secret)
+        @access_token, @access_token_secret = SettingValidator.frozen(access_token), SettingValidator.frozen(access_token_secret)
+        @bearer_token = SettingValidator.frozen(bearer_token)
+        @client_id, @client_secret, @refresh_token = SettingValidator.frozen(client_id), SettingValidator.frozen(client_secret), SettingValidator.frozen(refresh_token)
+        @expires_at, @scopes = expires_at, scopes
+      end
+
+      # Refuse an authenticator beside credentials, and credentials of no complete set
+      # @api private
+      # @param authenticator [Authenticator, nil] the authenticator the client was given, or nil
+      # @return [void]
+      # @raise [ArgumentError] if the authenticator is not an Authenticator, or is given beside credentials
+      # @raise [ArgumentError] if the credentials do not form complete sets
+      def validate_credentials!(authenticator)
+        CredentialValidator.validate_authenticator!(authenticator, credentials)
+        CredentialValidator.validate!(credentials)
+      end
+
+      # Take the authenticator the client was given, or build one of its credentials
+      #
+      # The authenticator built is the one of the first complete set of credentials held, and a client that holds no
+      # complete set sends its requests without credentials. Taking an authenticator binds it to the connection of the
+      # client and reports its refreshes to the client, so the client checks the authenticator, and every other
+      # option, before it takes it, and a client that raises leaves the authenticator as it was.
+      #
+      # @api private
+      # @param client [Client] the client these are the internals of
+      # @param given [Authenticator, nil] the authenticator the client was given, or nil to build one
+      # @return [void]
+      def initialize_authenticator(client, given)
+        @given_authenticator = given
+        @authenticator = given ? take(client, given) : built_authenticator(client)
+      end
+
+      # Build the authenticator of the first complete set of credentials held
+      # @api private
+      # @param client [Client] the client these are the internals of
+      # @return [Authenticator] the authenticator, which sends no credentials when no set is complete
+      def built_authenticator(client)
+        oauth1_authenticator || oauth2_authenticator(client) || app_only_authenticator || bearer_authenticator || Authenticator.new
+      end
+
+      # The options of a copy of the client, beside the credentials it is built with
+      #
+      # An authenticator given to the copy replaces the credentials of the client, a credential given to it replaces
+      # the authenticator the client was given, and a copy given neither shares that authenticator. An expiration
+      # time and scopes are no credentials, and are refused beside an authenticator, as they are when a client is built.
+      #
+      # @api private
+      # @param options [Hash{Symbol => Object}] the options the copy is given
+      # @return [Hash{Symbol => Object}] the options, beside the credentials or the authenticator the copy shares
+      def with_credentials(options)
+        given = @given_authenticator
+        return {authenticator: given, **options} if given && !options.keys.intersect?(credentials.except(:expires_at, :scopes).keys)
+
+        options[:authenticator] ? options : {**credentials, **options}
+      end
+
+      # Build an OAuth 1.0a authenticator if credentials are available
+      # @api private
+      # @return [OAuth1Authenticator, nil] the OAuth 1.0a authenticator or nil
+      def oauth1_authenticator
+        access_token = @access_token
+        return unless api_key && api_key_secret && access_token && access_token_secret
+
+        OAuth1Authenticator.new(api_key:, api_key_secret:, access_token:, access_token_secret:)
+      end
+
+      # Build an app-only authenticator on the client's connection, given API keys
+      #
+      # A bearer token given beside them is sent until the API rejects it, and one is fetched with them in its place.
+      #
+      # @api private
+      # @return [AppOnlyAuthenticator, nil] the app-only authenticator or nil
+      def app_only_authenticator
+        return unless api_key && api_key_secret
+
+        AppOnlyAuthenticator.new(api_key:, api_key_secret:, bearer_token:).__send__(:token_requests_over, @connection, base_url, headers)
+      end
+
+      # Build a bearer token authenticator if credentials are available
+      # @api private
+      # @return [BearerTokenAuthenticator, nil] the bearer token authenticator or nil
+      def bearer_authenticator
+        return unless bearer_token
+
+        BearerTokenAuthenticator.new(bearer_token:)
+      end
+    end
+    private_constant :ClientCredentials
+  end
+end

data/lib/x/core/client_internals.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+require "monitor"
+require "uri"
+require_relative "app_only_authenticator"
+require_relative "authenticator"
+require_relative "bearer_token_authenticator"
+require_relative "client_app_only"
+require_relative "client_credentials"
+require_relative "client_memo"
+require_relative "client_settings"
+require_relative "client_token_refresh"
+require_relative "connection"
+require_relative "credential_holder"
+require_relative "credential_validator"
+require_relative "errors/callback_error"
+require_relative "oauth1_authenticator"
+require_relative "oauth2_authenticator"
+require_relative "origin"
+require_relative "proxy_setting"
+require_relative "request_builder"
+require_relative "request_encoding"
+require_relative "response_parser"
+require_relative "setting_validator"
+require_relative "stream_body"
+require_relative "stream_response"
+
+module X
+  module Core
+    # The credentials, settings, connection, handlers, and authenticator of a client, and the methods that send its
+    # requests with them
+    #
+    # X::Client is the class that x-resources and x-uploads include their methods into, and each is released apart
+    # from x-core, so a later version of either may name a method as it likes. A method of theirs would take the
+    # place of a private method of the client of the same name, and a client whose own methods called that one would
+    # call theirs in its place. So a client holds its state here and calls on this object, whose methods none of
+    # theirs can take the place of, and has no methods of its own but those of its public API and initialize.
+    #
+    # A client holds one of these for as long as it lives, and passes itself to a method that needs it, such as one
+    # that parses a response for it, rather than this holding the client, so that a copy of the client made with dup,
+    # which holds the same internals, as it held the same state before, passes itself in turn.
+    #
+    # @api private
+    class ClientInternals
+      # The headers a stream is opened with unless its own or the client's replace them, which ask for a body that is
+      # not compressed, so that each line reaches the stream as it arrives
+      STREAM_HEADERS = {"Accept-Encoding" => "identity"}.freeze
+      private_constant :STREAM_HEADERS
+
+      include ClientAppOnly
+      include ClientCredentials
+      include ClientMemo
+      include ClientSettings
+      include CredentialHolder
+      include ClientTokenRefresh
+      include ProxySetting
+
+      # Content type of a form-encoded request body
+      FORM_CONTENT_TYPE = "application/x-www-form-urlencoded; charset=utf-8"
+      private_constant :FORM_CONTENT_TYPE
+
+      # The authenticator for API requests
+      #
+      # {Client#authenticator} returns it.
+      #
+      # @api private
+      # @return [Authenticator] the authenticator instance
+      attr_reader :authenticator
+
+      # The callable passed the OAuth2Tokens of each refresh
+      #
+      # {Client#save_tokens} returns it.
+      #
+      # @api private
+      # @return [#call, nil] the callable, or nil for none
+      attr_reader :save_tokens
+
+      # The callable a refresh reads the stored OAuth2Tokens with
+      #
+      # {Client#load_tokens} returns it.
+      #
+      # @api private
+      # @return [#call, nil] the callable, or nil for none
+      attr_reader :load_tokens
+
+      # The internals of a client
+      #
+      # A copy of a client, which {#with} builds, reads the internals of the client it copies with this.
+      #
+      # @api private
+      # @param client [Client] the client
+      # @return [ClientInternals] the internals of the client
+      def self.of(client) = client.instance_variable_get(:@internals)
+
+      # Initialize the internals of a client, with the options its initialize was given
+      #
+      # The authenticator is taken last, since a client that raised must leave an authenticator it was given alone.
+      #
+      # @api private
+      # @param client [Client] the client these are the internals of
+      # @return [ClientInternals] a new instance
+      # @raise [ArgumentError] if an option is refused, as {Client#initialize} states
+      def initialize(client, api_key:, api_key_secret:, access_token:, access_token_secret:, bearer_token:, client_id:,
+        client_secret:, refresh_token:, expires_at:, scopes:, authenticator:, base_url:, open_timeout:, read_timeout:,
+        write_timeout:, keep_alive_timeout:, debug_output:, proxy_url:, default_array_class:, default_object_class:,
+        headers:, max_redirects:, max_rate_limit_retries:, max_rate_limit_wait:, max_retries:, on_response:,
+        save_tokens:, load_tokens:)
+        @connection = Connection.new(open_timeout:, read_timeout:, write_timeout:, keep_alive_timeout:, debug_output:, proxy_url:)
+        @proxy_url = @connection.__send__(:proxy_url)
+        initialize_state
+        initialize_credentials(api_key:, api_key_secret:, access_token:, access_token_secret:, bearer_token:, client_id:, client_secret:, refresh_token:, expires_at:, scopes:)
+        validate_credentials!(authenticator)
+        initialize_settings(base_url:, default_array_class:, default_object_class:, headers:, on_response:, max_redirects:, max_rate_limit_retries:, max_rate_limit_wait:, max_retries:)
+        initialize_token_hooks(save_tokens:, load_tokens:)
+        initialize_authenticator(client, authenticator)
+      end
+
+      # Summarize the internals of a client without revealing credentials
+      #
+      # They hold the credentials of the client, so they are summarized as {Client#inspect} summarizes the client.
+      #
+      # @api private
+      # @return [String] the class name, base URL, and authenticator
+      def inspect = "#<#{self.class} base_url=#{base_url.inspect} authenticator=#{authenticator.inspect}>"
+
+      # Copy a client with some of its options changed
+      #
+      # It is what {Client#with} does. The internals of the copy share the authenticator and the connections of these
+      # as that states.
+      #
+      # @api private
+      # @param client [Client] the client these are the internals of
+      # @param options [Hash{Symbol => Object}] the options to change, as accepted by initialize
+      # @return [Client] a new client with the same credentials and settings, apart from the options given
+      def with(client, options)
+        client.class.new(**without_tokens_of_client({**settings, **with_credentials(options)}, options)).tap do |copy|
+          internals = ClientInternals.of(copy)
+          internals.__send__(:share_authenticator, copy, authenticator, options)
+          internals.__send__(:share_app_token, self)
+          internals.__send__(:share_connection, @connection)
+        end
+      end
+
+      # Close the connections the client keeps open between requests
+      #
+      # It is what {Client#close} does.
+      #
+      # @api private
+      # @return [void]
+      def close = @connection.close
+
+      # Execute an HTTP request to the X API
+      #
+      # An error a callback raised, which the request tags as a CallbackError so that no handler sends the request
+      # again, waits out a rate limit, or refreshes a token for it, is raised as it was, once the handlers are left,
+      # noted as a callback's, so that Client#with_retries does not send the request again for it either.
+      #
+      # @api private
+      # @param client [Client] the client these are the internals of, which a response is parsed for
+      # @return [Object, nil] the parsed response body, or what an object_class that responds to from_response builds
+      def execute_request(client, http_method, endpoint, params:, headers:, array_class:, object_class:, body: nil, form: nil, &block)
+        SettingValidator.parsing_classes!(array_class:, object_class:)
+        headers = SettingValidator.headers!(headers)
+        uri = RequestEncoding.uri_for(base_url, endpoint, params)
+        headers = headers_for(form.nil? ? headers : RequestBuilder.merge_headers({"Content-Type" => FORM_CONTENT_TYPE}, headers))
+        retrying(http_method) { refreshing_rejected_token(client) { perform(client, http_method, uri, body: RequestEncoding.encode_body(body, form), headers:, array_class:, object_class:, &block) } }
+      rescue CallbackError => e
+        raise CallbackError.untag(e)
+      end
+
+      # Run a request, again after a server error or a rate limit, as the client allows
+      #
+      # The retries for a rate limit are counted across the attempts a server error sends again, so that
+      # max_rate_limit_retries bounds the retries of the request.
+      #
+      # @api private
+      # @param http_method [Symbol] the HTTP method of the request, which says whether it is sent again after a failure
+      # @yield runs the request
+      # @return [Object] what the block returns
+      def retrying(http_method, &)
+        @rate_limit_handler.counting do
+          @retry_handler.handle(idempotent: RequestBuilder.idempotent?(http_method)) { @rate_limit_handler.handle(&) }
+        end
+      end
+
+      # Open a GET request whose body the block reads as it arrives
+      #
+      # It is what {Client#get_stream} does. An error the block raises, but for the NetworkError its read_body raises
+      # for an error of the socket, is tagged as a CallbackError, so that no rejected token is refreshed for it, and
+      # raised as it was once the request is left. A stream is counted as a request of its own, so that a request its block sends counts
+      # its rate limit retries afresh, even inside with_retries.
+      #
+      # @api private
+      # @param client [Client] the client these are the internals of
+      # @param endpoint [String] the endpoint, relative to the base URL
+      # @param params [Hash, nil] query parameters appended to the endpoint
+      # @param headers [Hash] additional headers for the request
+      # @yieldparam response [StreamResponse] the successful response, whose body is not yet read
+      # @return [Object] what the block returns
+      def execute_stream(client, endpoint, params:, headers:, &)
+        uri = RequestEncoding.uri_for(base_url, endpoint, params)
+        headers = headers_for(SettingValidator.headers!(headers))
+        @rate_limit_handler.counting { refreshing_rejected_token(client) { perform_stream(uri, headers:, &) } }
+      rescue CallbackError => e
+        raise CallbackError.untag(e)
+      end
+
+      private
+
+      # Build what the client keeps beside its options
+      #
+      # They are the helpers that build its requests and parse its responses, and the locks of what it builds once
+      # and keeps: its app-only copy, and the values of its memo.
+      #
+      # @api private
+      # @return [void]
+      def initialize_state
+        @app_only_monitor = Monitor.new
+        @request_builder = RequestBuilder.new
+        @response_parser = ResponseParser.new
+        initialize_memo
+      end
+
+      # Open a GET request once, and pass its response to the block if it succeeded
+      #
+      # A request to another origin than the base URL carries none of the client's credentials, as any other does. It
+      # asks for a body that is not compressed, unless its headers or the client's name an Accept-Encoding of their
+      # own, since Net::HTTP inflates a compressed body in blocks of many kilobytes, and would hold back each line of a
+      # stream until enough of them had arrived to fill one.
+      #
+      # @api private
+      # @param uri [URI::Generic] the URI of the request
+      # @param headers [Hash] the headers of the request, beside those of the client
+      # @yieldparam response [StreamResponse] the successful response
+      # @return [Object] what the block returns
+      # @raise [HTTPError] if the response is not successful
+      # @raise [NetworkError] if the request cannot be sent, or read_body raises it for an error of the socket
+      # @raise [CallbackError] if on_response raises, or the block raises an error that read_body did not raise for
+      #   the socket
+      def perform_stream(uri, headers:)
+        authenticator, headers = Origin.credentials_for(from: URI(base_url), to: uri, authenticator: self.authenticator, headers:)
+        request = @request_builder.build(http_method: :get, uri:, headers: RequestBuilder.merge_headers(STREAM_HEADERS, headers), authenticator:)
+        @connection.perform_stream(request:) do |response|
+          stream_failed(uri, response, request) unless response.is_a?(Net::HTTPSuccess)
+          stream = StreamResponse.__send__(:new, http_response: response, uri:)
+          reading(stream) { yield stream }
+        end
+      end
+
+      # Raise the error of a stream that failed
+      #
+      # Its body is read whole, tagged UTF-8 as the body of {Connection#perform} is, before the block of the request
+      # ends, so that on_response and the error can read it however long after it was raised.
+      #
+      # @api private
+      # @param uri [URI::Generic] the URI of the request
+      # @param response [Net::HTTPResponse] the failed response, whose body is not yet read
+      # @param request [Net::HTTPRequest] the request the response answers
+      # @return [void]
+      # @raise [HTTPError] the error of the response
+      # @raise [CallbackError] if on_response raises
+      def stream_failed(uri, response, request)
+        response.body_encoding = Encoding::UTF_8
+        response.body
+        CallbackError.tagging { report(:get, uri, response) }
+        raise @response_parser.error(response, request)
+      end
+
+      # Run the block of a stream, tagging its errors but those of its socket
+      #
+      # The errors of the socket are the NetworkErrors StreamResponse#read_body raised for it, as StreamBody notes
+      # them, which are raised as they are, rather than wrapped in another, and any other error is the block's own,
+      # whatever its class, which is raised as it was, as is the error of a socket the block raised of its own, such
+      # as the IOError of a file it wrote to, or one read from the response of the transport. However the block ends,
+      # the response is told that it has, so that it raises for a body read once the connection is closed, rather
+      # than read from it.
+      #
+      # @api private
+      # @param response [StreamResponse] the response the block is passed
+      # @yield runs the block of the stream, passing it the response
+      # @return [Object] what the block returns
+      # @raise [NetworkError] if read_body raised it for an error of the socket
+      # @raise [CallbackError] if the block raises an error that read_body did not raise for the socket
+      def reading(response)
+        yield
+      rescue => e
+        raise if StreamBody.socket_error?(e)
+
+        raise CallbackError, e
+      ensure
+        response.__send__(:leave)
+      end
+
+      # Perform a request once, following redirects and parsing the response
+      #
+      # A request to another origin than the base URL carries none of the client's credentials, as a redirect to one
+      # carries none of them. The error on_response or the block of the request raises, as the error from_response
+      # raises, is tagged as a CallbackError, so that it is not taken for an error of the response. The response is
+      # reported, and its error named, for the request it answers, which a redirect may have sent to another URI with
+      # another method than the request was made with.
+      #
+      # @api private
+      # @param client [Client] the client these are the internals of, which a response is parsed for
+      # @return [Object, nil] the parsed response body, or what an object_class that responds to from_response builds
+      def perform(client, http_method, uri, body:, headers:, array_class:, object_class:, &)
+        authenticator, headers = Origin.credentials_for(from: URI(base_url), to: uri, authenticator: self.authenticator, headers:)
+        request = @request_builder.build(http_method:, uri:, body:, headers:, authenticator:)
+        response, request = @redirect_handler.follow(response: @connection.perform(request:), request:, headers:, authenticator:)
+        CallbackError.tagging { report(request.method, request.uri, response, &) }
+        @response_parser.parse(response:, array_class:, object_class:, client:, request:)
+      end
+    end
+    private_constant :ClientInternals
+  end
+end

data/lib/x/core/client_memo.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module X
+  module Core
+    # What the gems that extend a client keep on it, for as long as it authenticates as it does, included into
+    # ClientInternals
+    #
+    # x-resources keeps the identifier of the user a lookup found for the credentials of a client here, so that it looks
+    # the user up once. A value is kept with the authenticator of the client when it was kept, and read only while the
+    # client authenticates with that authenticator, since what it says may be true of those credentials alone. It is
+    # kept under a lock, so that threads that share a client read and keep values together.
+    #
+    # The memo is held by the internals of a client, as the app-only copy of a client is, rather than by the client,
+    # so a frozen client keeps values as well, and a copy made with dup or clone, which holds the same internals and
+    # authenticator, shares them. A copy made with {Client#with} holds internals of its own, and keeps its own values.
+    #
+    # @api private
+    module ClientMemo
+      # The value kept under a key for the authenticator the client holds
+      #
+      # It is what {Client#memoized} does.
+      #
+      # @api private
+      # @param key [Symbol] the key, which names the gem that keeps it
+      # @return [Object, nil] the value, or nil if none is kept for the authenticator of the client
+      def memoized(key)
+        @memo_lock.synchronize do
+          owner, value = @memo[key]
+          value if owner.equal?(authenticator)
+        end
+      end
+
+      # Keep a value under a key, for the authenticator of the client
+      #
+      # It is what {Client#memoize} does.
+      #
+      # @api private
+      # @param key [Symbol] the key, which names the gem that keeps it
+      # @param value [Object] the value
+      # @return [Object] the value
+      def memoize(key, value)
+        @memo_lock.synchronize { @memo[key] = [authenticator, value] }
+        value
+      end
+
+      private
+
+      # Start with nothing kept
+      # @api private
+      # @return [void]
+      def initialize_memo
+        @memo = {}
+        @memo_lock = Mutex.new
+      end
+    end
+    private_constant :ClientMemo
+  end
+end