x-core 1.0.0

data/lib/x/core/connection_request.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "zlib"
+require_relative "request_builder"
+
+module X
+  module Core
+    # How a connection sends one request, and what it counts as a failure of the network, included into Connection
+    # @api private
+    module ConnectionRequest
+      # Network errors that should be wrapped in NetworkError
+      #
+      # IOError covers EOFError, and a read from a socket closed under it. SystemCallError covers every error the
+      # operating system reports for a socket, such as a refused, reset, or aborted connection, a network that is down
+      # or has no route, or a write refused with EPIPE. The open, read, and write timeouts are those of Net::HTTP, and
+      # no other Timeout::Error, such as one Timeout.timeout raises around a request, which is raised as it is, so that
+      # a rescue of it still catches it, and no handler sends the request again for it. A connection cut off
+      # mid-response can leave Net::HTTP a status line it cannot parse, or a compressed body that Zlib cannot inflate,
+      # and a proxy that refuses to open a tunnel, such as with 407 Proxy Authentication Required, raises a
+      # Net::ProtocolError. A response whose Content-Length or Content-Range Net::HTTP cannot read raises a
+      # Net::HTTPHeaderSyntaxError.
+      NETWORK_ERRORS = [
+        IOError,
+        Net::HTTPBadResponse,
+        Net::HTTPHeaderSyntaxError,
+        Net::ProtocolError,
+        OpenSSL::SSL::SSLError,
+        SocketError,
+        SystemCallError,
+        Net::OpenTimeout,
+        Net::ReadTimeout,
+        Net::WriteTimeout,
+        Zlib::Error
+      ].freeze
+
+      # Errors that say a connection kept open had been closed by the time a request was sent on it
+      #
+      # EOFError is read from a socket the peer closed, and a write to one it closed or reset is refused with EPIPE,
+      # ECONNRESET, or ECONNABORTED. A timeout is not among them: a request that timed out waiting for its response
+      # may have reached the API, which may have acted on it. Nor is any of them once the response has begun: a body
+      # cut off as it is read is one the API sent.
+      STALE_CONNECTION_ERRORS = [EOFError, Errno::ECONNABORTED, Errno::ECONNRESET, Errno::EPIPE].freeze
+      private_constant :NETWORK_ERRORS, :STALE_CONNECTION_ERRORS
+
+      private
+
+      # Send a request, once more on a new connection when a kept one had gone stale
+      #
+      # X, or a proxy between, can close a connection that is being kept open for the next request, and the request
+      # that takes it then fails as it is written or its response is first read, as one of STALE_CONNECTION_ERRORS.
+      # That request never reached the API, so an idempotent one is sent again, on a connection opened for it rather
+      # than taken from the pool, where another connection may have gone stale too. A request that failed any other
+      # way, such as by timing out, or on a connection opened for it, is not sent again: nothing about it says the API
+      # did not act on it. Nor is one whose response had begun, which Net::HTTP says by passing it to the block of
+      # the request once its status and headers are read: a connection that drops as the body is read was not stale,
+      # and the API answered the request, so it raises as a read that timed out does. Net::HTTP would send a request
+      # again of its own, after a timeout as well, with the OAuth 1.0a nonce and signature of the attempt that failed,
+      # which is why its retries are turned off and the request the caller built is sent again here.
+      #
+      # @api private
+      # @param request [Net::HTTPRequest] the HTTP request to send
+      # @param key [Array] the scheme, host, and port to connect to
+      # @param open [Proc] builds a connection to the host
+      # @return [Net::HTTPResponse] the HTTP response
+      # @raise [StandardError] whatever the request raised, once it may not be sent again
+      def send_request(request, key, open)
+        stale = false
+        begin
+          @pool.with(key, open) do |http_client, from_pool|
+            stale = from_pool
+            http_client.request(request) { stale = false }
+          end
+        rescue *STALE_CONNECTION_ERRORS
+          raise unless stale && idempotent?(request)
+
+          @pool.with(key, open, fresh: true) { |http_client, _| http_client.request(request) }
+        end
+      end
+
+      # Check whether sending a request again has the same effect as sending it once
+      # @api private
+      # @param request [Net::HTTPRequest] the HTTP request
+      # @return [Boolean] true for a GET, PUT, or DELETE
+      def idempotent?(request) = RequestBuilder.idempotent?(request.method.downcase.to_sym)
+    end
+    private_constant :ConnectionRequest
+  end
+end

data/lib/x/core/credential_holder.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module X
+  module Core
+    # Refuses Marshal, YAML, and JSON for what holds credentials, included into a client and its internals, an
+    # authenticator, and an authorization
+    #
+    # Marshal and YAML would write the credentials such an object holds, in the clear, wherever what they write is
+    # kept, such as a cache, where a client in a Hash that is cached would carry them without a word, or the arguments
+    # of a job a queue writes as YAML. Where Marshal would not raise TypeError, for a lock the object holds, it would
+    # write them silently, and YAML writes every instance variable, a lock or not, so each refuses alike, with the
+    # TypeError Marshal raises for what it cannot write, such as a Proc, so that code that rescues it around
+    # Marshal.dump, as a cache or a deep copy does, rescues this too. JSON is refused alike, since ActiveSupport's
+    # Object#as_json reads every instance variable as YAML does, so that rendering a client, or a Hash that holds one,
+    # as JSON would write its credentials into a response or a log.
+    #
+    # Internal to x-core: the methods it gives these classes, marshal_dump, encode_with, as_json, and to_json, are
+    # public API, but the module is only how they are shared, and which classes include it can change within 1.x.
+    # They call raise and format on Kernel, so that a module included into X::Client after it, as x-resources and
+    # x-uploads are, cannot change what they raise, whatever the module defines.
+    #
+    # @api private
+    module CredentialHolder
+      # The message of the error raised for Marshal, YAML, or JSON, which names the class refused and what refused it
+      REFUSAL_MESSAGE = "%s holds credentials, which %s would write in the clear wherever it is kept; keep the " \
+        "credentials in a secret store, and the X::OAuth2Tokens save_tokens is passed, and build it again from them"
+      private_constant :REFUSAL_MESSAGE
+
+      # Refuse to be written with Marshal, which would write the credentials
+      #
+      # @api public
+      # @return [void]
+      # @raise [TypeError] always
+      # @example Store the tokens a refresh issued, rather than the client
+      #   X::Client.new(**credentials, save_tokens: ->(tokens) { store.save(**tokens.to_h) })
+      def marshal_dump = Kernel.raise(TypeError, Kernel.format(REFUSAL_MESSAGE, self.class, "Marshal"))
+
+      # Refuse to be written as YAML, which would write the credentials
+      #
+      # YAML reads no marshal_dump, and writes every instance variable of an object that does not say how it is
+      # written, credentials and all, so it is refused as Marshal is.
+      #
+      # @api public
+      # @param _coder [Psych::Coder] the coder YAML would write the object with
+      # @return [void]
+      # @raise [TypeError] always
+      # @example Enqueue the identifier of a user, rather than a client, for a job its queue writes as YAML
+      #   PostJob.perform_later(user_id: client.authenticator.user_id)
+      def encode_with(_coder) = Kernel.raise(TypeError, Kernel.format(REFUSAL_MESSAGE, self.class, "YAML"))
+
+      # Refuse to be read as JSON, which would write the credentials
+      #
+      # ActiveSupport's Object#as_json reads every instance variable of an object that does not say how it is read,
+      # credentials and all, so it is refused as YAML is.
+      #
+      # @api public
+      # @return [void]
+      # @raise [TypeError] always
+      # @example Render the user a client acts for, rather than the client
+      #   render json: {user_id: client.authenticator.user_id}
+      def as_json(*) = Kernel.raise(TypeError, Kernel.format(REFUSAL_MESSAGE, self.class, "JSON"))
+
+      # Refuse to be written as JSON, which would write the credentials
+      #
+      # It raises as {#as_json} does, for the reason that says, so that JSON.generate refuses a client within what it
+      # writes as well.
+      #
+      # @api public
+      # @param _state [JSON::State, nil] the state JSON would write the object with
+      # @return [void]
+      # @raise [TypeError] always
+      # @example Log the user a client acts for, rather than the client
+      #   logger.info(JSON.generate(user_id: client.authenticator.user_id))
+      def to_json(_state = nil) = Kernel.raise(TypeError, Kernel.format(REFUSAL_MESSAGE, self.class, "JSON"))
+    end
+    private_constant :CredentialHolder
+  end
+end

data/lib/x/core/credential_validator.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+require_relative "authenticator"
+
+module X
+  module Core
+    # Checks that the credentials of a new client form complete sets
+    #
+    # A client authenticates with the first complete set of credentials it has, and ignores the rest. Credentials that
+    # form no set would send requests without credentials, an access token without the rest of its set would
+    # authenticate as the app, or with a bearer token, rather than as the user it belongs to, and any other credential
+    # of a set that is not complete, such as a client ID beside a bearer token, is a mistake that a client would
+    # otherwise hide. So every credential must belong to a complete set. A client may hold several, such as the
+    # bearer token of an app beside its API key and secret, but not OAuth 2.0 credentials beside OAuth 1.0a ones, which
+    # share the access token, and which it authenticates with first, so that the OAuth 2.0 credentials would go unused.
+    # A client never changes the credentials it was built with, so this runs once, when the client is built.
+    #
+    # @api private
+    module CredentialValidator
+      extend self
+
+      # The message of the error raised for credentials that do not form a complete set
+      INCOMPLETE_CREDENTIALS = "The credentials given do not form a complete set. Pass api_key, api_key_secret, " \
+        "access_token, and access_token_secret for OAuth 1.0a; client_id and access_token, with the refresh_token " \
+        "that refreshes it and the client_secret of a confidential client, for OAuth 2.0; bearer_token for the app's " \
+        "bearer token; or api_key and api_key_secret to authenticate as the app. Leave out any credential of a set " \
+        "that is not complete"
+      private_constant :INCOMPLETE_CREDENTIALS
+
+      # The credentials of each set: OAuth 1.0a, OAuth 2.0 for a confidential and for a public client, with a refresh
+      # token and without one, as an authorization without offline.access issues them, a bearer token, and the app's
+      # API key and secret
+      CREDENTIAL_SETS = [
+        %i[api_key api_key_secret access_token access_token_secret],
+        %i[client_id client_secret access_token refresh_token],
+        %i[client_id access_token refresh_token],
+        %i[client_id client_secret access_token],
+        %i[client_id access_token],
+        %i[bearer_token],
+        %i[api_key api_key_secret]
+      ].freeze
+
+      # The credentials a client authenticates with before OAuth 2.0 credentials, when it holds both
+      OAUTH1_CREDENTIALS = CREDENTIAL_SETS.first
+      # The credentials of the least set of OAuth 2.0, which an expiration time is the expiration time of the token of
+      OAUTH2_CREDENTIALS = CREDENTIAL_SETS.fetch(4)
+      # The credentials of OAuth 2.0 that no other set holds, which a client that authenticates with OAuth 1.0a ignores
+      OAUTH2_ONLY_CREDENTIALS = %i[client_id client_secret refresh_token].freeze
+      private_constant :OAUTH1_CREDENTIALS, :OAUTH2_CREDENTIALS, :OAUTH2_ONLY_CREDENTIALS
+
+      # The message of the error raised for OAuth 2.0 credentials the client would leave unused
+      UNUSED_OAUTH2_CREDENTIALS = "%s are OAuth 2.0 credentials, which a client given OAuth 1.0a credentials would " \
+        "leave unused, since it authenticates with those, and the access_token they share is the OAuth 1.0a one. Pass " \
+        "the credentials of one or the other"
+      private_constant :UNUSED_OAUTH2_CREDENTIALS
+
+      # The message of the error raised for an expiration time the client would leave unused
+      UNUSED_EXPIRES_AT = "expires_at is the time an OAuth 2.0 access token expires, so it is given beside the " \
+        "client_id and access_token the client authenticates with, rather than beside OAuth 1.0a credentials, a " \
+        "bearer_token, an api_key and api_key_secret, or none, which would leave it unused. Leave it out"
+      private_constant :UNUSED_EXPIRES_AT
+
+      # The message of the error raised for an expiration time that is not a Time
+      INVALID_EXPIRES_AT = "expires_at must be a Time, such as Time.at(seconds) for a time stored as seconds since the " \
+        "epoch, or nil if it is not known"
+      private_constant :INVALID_EXPIRES_AT
+
+      # The message of the error raised for scopes the client would leave unused
+      UNUSED_SCOPES = "scopes are the scopes X granted an OAuth 2.0 access token, so they are given beside the " \
+        "client_id and access_token the client authenticates with, rather than beside OAuth 1.0a credentials, a " \
+        "bearer_token, an api_key and api_key_secret, or none, which would leave them unused. Leave them out"
+      private_constant :UNUSED_SCOPES
+
+      # The message of the error raised for scopes that are not an Array of scopes
+      INVALID_SCOPES = "scopes must be an Array of Strings that each name a scope, such as %w[tweet.read users.read], " \
+        "or nil if they are not known"
+      private_constant :INVALID_SCOPES
+
+      # A scope, which OAuth 2.0 names with printable characters other than a space, a quote, and a backslash
+      SCOPE = /\A[\x21\x23-\x5B\x5D-\x7E]+\z/
+      private_constant :SCOPE
+
+      # The message of the error raised for a credential that is an empty String
+      EMPTY_CREDENTIAL = "%s is empty. Pass the credential, or leave it out, since an empty one authenticates nothing"
+      private_constant :EMPTY_CREDENTIAL
+
+      # The message of the error raised for a credential that is not a String
+      NOT_A_STRING = "%s must be a String, not a %s"
+      private_constant :NOT_A_STRING
+
+      # The message raised for a credential an authenticator requires that is nil or empty
+      MISSING_CREDENTIAL = "%s is nil or empty. Pass the credential, which the authenticator cannot authenticate without"
+      private_constant :MISSING_CREDENTIAL
+
+      # The message of the error raised for an authenticator that is not one
+      NOT_AN_AUTHENTICATOR = "authenticator must be an X::Authenticator, such as an X::OAuth2Authenticator, or nil, " \
+        "not a %s"
+      private_constant :NOT_AN_AUTHENTICATOR
+
+      # The message of the error raised for an authenticator given beside credentials
+      AUTHENTICATOR_AND_CREDENTIALS = "An authenticator holds the credentials it authenticates with, so it cannot be " \
+        "given beside %s. Pass the authenticator, or the credentials, and leave out the other"
+      private_constant :AUTHENTICATOR_AND_CREDENTIALS
+
+      # Raise for a credential not a String or empty, or an expiration time not a Time
+      #
+      # An environment variable that is not set is often read as an empty String, as ENV.fetch("X_BEARER_TOKEN", "")
+      # reads it, which would send an Authorization header that authenticates nothing, for the API to refuse. A
+      # credential that is not a String, such as the Integer of a client ID read from YAML, would be signed with as the
+      # String it converts to, if it converts to one at all, so it is refused rather than sent as something else.
+      #
+      # @api private
+      # @param credentials [Hash{Symbol => String, Time, nil}] the credentials, as Client#initialize accepts them
+      # @return [void]
+      # @raise [ArgumentError] if a credential is neither a String nor nil, is an empty String, or one of whitespace
+      #   alone, if the expiration time is neither a Time nor nil, or if the scopes are neither an Array of scopes nor
+      #   nil
+      # @example Check the credentials of a client
+      #   X::Core::CredentialValidator.validate_values!(bearer_token: "", expires_at: nil)
+      def validate_values!(credentials)
+        credentials.except(:expires_at, :scopes).each do |name, value|
+          next if value.nil?
+          raise ArgumentError, format(NOT_A_STRING, name, value.class) unless String === value
+          raise ArgumentError, format(EMPTY_CREDENTIAL, name) unless value.match?(/\S/)
+        end
+        validate_expires_at!(credentials[:expires_at])
+        validate_scopes!(credentials[:scopes])
+      end
+
+      # Raise for a credential an authenticator requires that is nil or empty
+      #
+      # An authenticator is given the credentials it authenticates with, so each is required, and one given as nil,
+      # as ENV[] reads a variable that is not set, or as an empty String, would authenticate nothing. They, and those it
+      # takes beside them, are checked as {#validate_values!} checks those of a client.
+      #
+      # @api private
+      # @param required [Hash{Symbol => String, nil}] the credentials the authenticator requires, by the names it
+      #   takes them by
+      # @param others [Hash{Symbol => String, Time, nil}] the credentials and expiration time it takes beside them
+      # @return [void]
+      # @raise [ArgumentError] if a credential required is nil, an empty String, or one of whitespace alone
+      # @raise [ArgumentError] if a credential is neither a String nor nil, another credential is empty, or the
+      #   expiration time is neither a Time nor nil
+      # @example Check the credential of a bearer token authenticator
+      #   X::Core::CredentialValidator.validate_required!({bearer_token: ENV["X_BEARER_TOKEN"]})
+      def validate_required!(required, others = {})
+        required.each { |name, value| raise ArgumentError, format(MISSING_CREDENTIAL, name) unless value.to_s.match?(/\S/) }
+        validate_values!(required.merge(others))
+      end
+
+      # Raise for an expiration time that is not a Time
+      #
+      # A token refresh compares the expiration time with the current time before every request, which fails for a time
+      # stored as a number or a String.
+      #
+      # @api private
+      # @param expires_at [Object] the expiration time
+      # @return [void]
+      # @raise [ArgumentError] if the expiration time is neither a Time nor nil
+      # @example Check an expiration time
+      #   X::Core::CredentialValidator.validate_expires_at!(Time.now + 7200)
+      def validate_expires_at!(expires_at)
+        raise ArgumentError, INVALID_EXPIRES_AT unless expires_at.nil? || expires_at.is_a?(Time)
+      end
+
+      # Raise for scopes that are not an Array of scopes
+      #
+      # @api private
+      # @param scopes [Object] the scopes
+      # @return [void]
+      # @raise [ArgumentError] if the scopes are neither an Array of Strings that each name a scope nor nil
+      # @example Check scopes
+      #   X::Core::CredentialValidator.validate_scopes!(%w[tweet.read users.read])
+      def validate_scopes!(scopes)
+        raise ArgumentError, INVALID_SCOPES unless scopes.nil? || scopes?(scopes)
+      end
+
+      # Check whether scopes are an Array of Strings that each name a scope
+      #
+      # @api private
+      # @param scopes [Object] the scopes
+      # @return [Boolean] true if the scopes are an Array of Strings that each name a scope
+      # @example Check scopes
+      #   X::Core::CredentialValidator.scopes?(%w[tweet.read users.read]) # => true
+      def scopes?(scopes) = scopes.is_a?(Array) && scopes.all? { |scope| scope.is_a?(String) && SCOPE.match?(scope) }
+
+      # The scopes as the tokens, an authenticator, or a client holds them
+      #
+      # They are frozen, the Array and each String, apart from those given, so that the caller that gave them can
+      # change neither what the client holds nor what save_tokens is passed.
+      #
+      # @api private
+      # @param scopes [Array<String>, nil] the scopes, which validate_scopes! accepted
+      # @return [Array<String>, nil] the scopes, frozen, or nil for none
+      # @example Hold scopes
+      #   X::Core::CredentialValidator.frozen_scopes(%w[tweet.read]) # => ["tweet.read"]
+      def frozen_scopes(scopes) = scopes&.map { |scope| -scope }.freeze
+
+      # Raise for an authenticator that is not one, or that is given beside credentials
+      #
+      # A client given an authenticator authenticates with it alone, so a credential given beside it, the expiration
+      # time of an OAuth 2.0 access token included, which an OAuth2Authenticator is built with, would go unused. The
+      # error names the class of something that is not an authenticator, rather than inspect it, since a Hash of
+      # credentials passed in its place would show them.
+      #
+      # @api private
+      # @param authenticator [Object] the authenticator, or nil for none
+      # @param credentials [Hash{Symbol => String, Time, nil}] the credentials, as Client#initialize accepts them
+      # @return [void]
+      # @raise [ArgumentError] if the authenticator is neither an Authenticator nor nil, or is given beside a
+      #   credential
+      # @example Check the authenticator of a client
+      #   X::Core::CredentialValidator.validate_authenticator!(authenticator, bearer_token: nil)
+      def validate_authenticator!(authenticator, credentials)
+        return if authenticator.nil?
+        raise ArgumentError, format(NOT_AN_AUTHENTICATOR, authenticator.class) unless authenticator.is_a?(Authenticator)
+
+        given = credentials.compact.keys
+        raise ArgumentError, format(AUTHENTICATOR_AND_CREDENTIALS, given.join(", ")) unless given.empty?
+      end
+
+      # Raise for incomplete credentials, or ones that leave others unused
+      #
+      # A client given OAuth 1.0a credentials authenticates with them, so OAuth 2.0 credentials given beside them, which
+      # would share their access token, raise. An expiration time and scopes are those of an OAuth 2.0 access token,
+      # which a client reads only when it authenticates with OAuth 2.0 credentials, so either given to a client that
+      # authenticates otherwise raises, as it does beside an authenticator.
+      #
+      # @api private
+      # @param credentials [Hash{Symbol => String, Time, Array<String>, nil}] the credentials, as Client#initialize
+      #   accepts them
+      # @return [void]
+      # @raise [ArgumentError] if a credential belongs to no complete set, OAuth 2.0 credentials are given beside
+      #   OAuth 1.0a ones, or an expiration time or scopes are given to a client that does not authenticate with OAuth
+      #   2.0 credentials
+      # @example Check the credentials of a client
+      #   X::Core::CredentialValidator.validate!(api_key: "key")
+      def validate!(credentials)
+        raise ArgumentError, INCOMPLETE_CREDENTIALS if incomplete?(credentials)
+
+        unused = unused_oauth2_credentials(credentials)
+        raise ArgumentError, format(UNUSED_OAUTH2_CREDENTIALS, unused.join(", ")) unless unused.empty?
+        raise ArgumentError, UNUSED_EXPIRES_AT if unused?(credentials, :expires_at)
+        raise ArgumentError, UNUSED_SCOPES if unused?(credentials, :scopes)
+      end
+
+      private
+
+      # Check whether a credential was given that belongs to no complete set
+      #
+      # The expiration time and scopes are no credentials, so they belong to no set, and unused? checks them.
+      #
+      # @api private
+      # @param credentials [Hash{Symbol => String, Time, Array<String>, nil}] the credentials
+      # @return [Boolean] true if the credentials do not form complete sets
+      def incomplete?(credentials)
+        given = credentials.except(:expires_at, :scopes).compact.keys
+        complete = CREDENTIAL_SETS.select { |set| (set - given).empty? }
+        (given - complete.flatten).any?
+      end
+
+      # The OAuth 2.0 credentials given beside OAuth 1.0a ones, which would go unused
+      #
+      # @api private
+      # @param credentials [Hash{Symbol => String, Time, Array<String>, nil}] the credentials
+      # @return [Array<Symbol>] the names of the OAuth 2.0 credentials given, or none when OAuth 1.0a ones are not
+      def unused_oauth2_credentials(credentials)
+        given = credentials.compact.keys
+        (OAUTH1_CREDENTIALS - given).empty? ? OAUTH2_ONLY_CREDENTIALS & given : []
+      end
+
+      # Check whether expires_at or scopes were given that the client would leave unused
+      #
+      # @api private
+      # @param credentials [Hash{Symbol => String, Time, Array<String>, nil}] the credentials
+      # @param name [Symbol] the name of what was given of the access token, expires_at or scopes
+      # @return [Boolean] true if it was given, and the client holds no OAuth 2.0 credentials, which validate! refuses
+      #   beside OAuth 1.0a ones before it checks this
+      def unused?(credentials, name)
+        given = credentials.compact.keys
+        given.include?(name) && !(OAUTH2_CREDENTIALS - given).empty?
+      end
+    end
+    private_constant :CredentialValidator
+  end
+end

data/lib/x/core/errors/authorization_denied.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module X
+  # Error raised when the redirect back from X reports that the app was not authorized
+  #
+  # X redirects the user back to the app with an error, rather than a code, when the user declines to authorize the
+  # app, or when X cannot ask them, and the redirect is refused when its state does not match the one the app sent,
+  # or when it is not a valid URL. The redirect is a request of the user's browser, not a response of X, so the error
+  # holds no response, and descends from Error directly; a refusal of X to exchange the code raises
+  # AuthorizationError, a ClientError that holds the response of X.
+  #
+  # @api public
+  class AuthorizationDenied < Error
+    # The OAuth 2.0 error code the redirect reported, such as access_denied
+    # @api public
+    # @return [String, nil] the error code, or nil for a redirect that reported none, as one whose state does not
+    #   match reports none
+    # @example Tell a user who declined from a failure
+    #   rescue X::AuthorizationDenied => e
+    #     redirect_to root_path if e.error_code.eql?("access_denied")
+    attr_reader :error_code
+
+    # Build the error of a redirect that simple_oauth refused
+    #
+    # Internal to x-core: it takes an error of simple_oauth, whose type may change within 1.x, and is private, so
+    # OAuth2Authorization calls it with __send__.
+    #
+    # @api private
+    # @param error [SimpleOAuth::OAuth2::Error] the failure
+    # @param default_message [String] the message when the redirect describes no reason
+    # @return [AuthorizationDenied] a new instance
+    # @example Raise the error of a redirect that reported a user who declined
+    #   raise X::AuthorizationDenied.__send__(:from, error, "Authorization failed")
+    def self.from(error, default_message) = new(error.description || error.code || default_message, error_code: error.code)
+    private_class_method :from
+
+    # Initialize a new AuthorizationDenied
+    #
+    # @api public
+    # @param message [String, nil] the reason the app was not authorized, or nil for the name of the class, as an
+    #   exception raised with no message is named
+    # @param error_code [String, nil] the OAuth 2.0 error code, or nil for none
+    # @return [AuthorizationDenied] a new instance
+    # @example Create an error
+    #   X::AuthorizationDenied.new("The user denied the request", error_code: "access_denied")
+    # @example Raise the error with no message, as a test stub may
+    #   raise X::AuthorizationDenied
+    def initialize(message = nil, error_code: nil)
+      super(message)
+      @error_code = error_code
+    end
+  end
+end

data/lib/x/core/errors/authorization_error.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "client_error"
+
+module X
+  # Error raised when X refuses to issue a token
+  #
+  # X refuses a token when it declines an authorization code, a refresh token, such as one that was revoked or already
+  # used, or an app's API key and secret. It answers with a response of 4xx, which the error holds, as any other
+  # ClientError holds the response that raised it, and the error code of the response tells the refusals apart. A
+  # token endpoint that fails to answer, with 429 Too Many Requests, a server error, a redirect, or a page that is not
+  # JSON, such as that of a proxy, firewall, or captive portal, refuses nothing, so it raises the HTTPError, such as
+  # the TooManyRequests or ServerError a client retries, or the InvalidResponse, a response of the API raises, rather
+  # than this error.
+  #
+  # It is a ClientError, so code that rescues the failures of a response, as rescue X::HTTPError does around the
+  # requests of a client, catches the refresh that X refuses in the middle of one. A client that refreshes an OAuth 2.0
+  # token the API rejected raises it when X refuses the refresh, with the Unauthorized that rejected the token as its
+  # cause, so rescue both to ask the user to authorize the app again: Unauthorized for credentials the API rejects,
+  # and this error for a refresh token X no longer accepts. The redirect back from X that reports a user who declined,
+  # or a state that does not match, carries no response of X, so it raises AuthorizationDenied instead.
+  #
+  # @api public
+  class AuthorizationError < ClientError
+    # The OAuth 2.0 error code X reported, such as invalid_grant or invalid_request
+    #
+    # It is read from the JSON of the body, whatever the content type of the response says, as OAuth 2.0 reads it.
+    #
+    # @api public
+    # @return [String, nil] the error code, or nil if X reported none
+    # @example Forget the tokens of a user whose refresh token X no longer accepts
+    #   rescue X::AuthorizationError => e
+    #     store.forget(user) if e.error_code.eql?("invalid_request")
+    def error_code
+      String.try_convert(Hash.try_convert(JSON.parse(body.to_s))&.[]("error"))
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/x/core/errors/bad_gateway.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "server_error"
+
+module X
+  # Raised for a 502 Bad Gateway response, which the API sends when it cannot reach the service behind it
+  # @api public
+  class BadGateway < ServerError; end
+end

data/lib/x/core/errors/bad_request.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module X
+  # Raised for a 400 Bad Request response, which the API sends for a request it cannot read, such as one whose
+  # parameters or body it does not take
+  # @api public
+  class BadRequest < ClientError; end
+end

data/lib/x/core/errors/callback_error.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module X
+  module Core
+    # Stands in for an error a callback raised, so that what runs it does not take it for an error of its own
+    #
+    # A request runs the client's on_response hook, the block it was passed, and whatever an object_class builds its
+    # objects with, inside the handlers that send it again, wait out a rate limit, and refresh a rejected token, where
+    # an X::ServerError, an X::TooManyRequests, or an X::Unauthorized a callback raised, such as one of a request it
+    # made itself, would otherwise send the request again, reading what the API billed again, or spend a refresh
+    # token. The block of Client#get_stream runs inside the request that reads its body, where an X::Unauthorized it
+    # raised would otherwise refresh a token, and the stream be opened again.
+    #
+    # Internal to x-core: Client#perform, ResponseParser, and the stream Client#get_stream opens tag the errors of a
+    # callback with it, and Client raises the error it holds in its place, noted as a callback's, so that
+    # Client#with_retries, which runs outside the request, does not send it again for that error either.
+    #
+    # @api private
+    class CallbackError < StandardError
+      # The errors of callbacks raised in place of the CallbackError that tagged them, each held as its own key for as
+      # long as anything else holds it
+      UNTAGGED = ObjectSpace::WeakMap.new
+      private_constant :UNTAGGED
+
+      # The error the callback raised
+      # @api private
+      # @return [StandardError] the error the callback raised
+      # @example Raise the error a callback raised
+      #   raise error.error
+      attr_reader :error
+
+      # Run a callback, tagging the error it raises
+      #
+      # An error already tagged, by a callback that runs within another, is raised as it is.
+      #
+      # @api private
+      # @yield [] runs the callback
+      # @return [Object] what the callback returned
+      # @raise [CallbackError] if the callback raised
+      # @example Run the hook of a response
+      #   X::Core::CallbackError.tagging { on_response.call(summary) }
+      def self.tagging
+        yield
+      rescue CallbackError
+        raise
+      rescue => e
+        raise new(e)
+      end
+
+      # The error a CallbackError holds, noted as a callback's, to raise in its place
+      #
+      # @api private
+      # @param tagged [CallbackError] the CallbackError that tagged the error
+      # @return [StandardError] the error the callback raised
+      # @example Raise the error a callback raised once the request is left
+      #   raise X::Core::CallbackError.untag(e)
+      def self.untag(tagged)
+        UNTAGGED[tagged.error] = tagged.error
+      end
+
+      # Check whether an error is one a callback raised, which a request raised untagged
+      #
+      # A request raises it in place of the CallbackError that tagged it, once its handlers are left.
+      #
+      # @api private
+      # @param error [StandardError] the error a request raised
+      # @return [Boolean] true if a callback raised it
+      # @example Check whether an error is a callback's
+      #   X::Core::CallbackError.untagged?(error) # => false
+      def self.untagged?(error) = UNTAGGED[error].equal?(error)
+
+      # Initialize a new CallbackError
+      #
+      # It takes the message of the error it stands in for, which is read only if it escapes what runs the callback.
+      #
+      # @api private
+      # @param error [StandardError] the error the callback raised
+      # @return [CallbackError] a new instance
+      # @example Tag the error a callback raised
+      #   raise X::Core::CallbackError, error
+      def initialize(error)
+        super
+        @error = error
+      end
+    end
+    private_constant :CallbackError
+  end
+end