x-core 1.0.0

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module X
+  # Raised for a 404 Not Found response
+  #
+  # The API sends one for an endpoint it does not serve. It answers a lookup of a resource that does not exist with
+  # 200 OK and no data, or with a 404 that reports the resource as not found, and a request of x-core raises that
+  # 404 as this error too. The finders of x-resources read either answer as a missing resource; see
+  # X::MissingResource.
+  #
+  # @api public
+  class NotFound < ClientError; end
+end

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module X
+  # Raised for a 413 Payload Too Large response, which the API sends for a body larger than the endpoint takes, such
+  # as a media chunk above the size it accepts
+  # @api public
+  class PayloadTooLarge < ClientError; end
+end

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module X
+  # Raised for a 402 Payment Required response, which the API sends for a request the account that pays for the app
+  # has no credit left to pay for, and which is refused again until credit is added
+  # @api public
+  class PaymentRequired < ClientError; end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module X
+  # Raised for a 408 Request Timeout response, which the API sends when it gave up waiting for the rest of a request
+  # @api public
+  class RequestTimeout < ClientError; end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "http_error"
+
+module X
+  # The base class of the errors of a 5xx response, which the API failed to answer
+  #
+  # The request is not the reason it failed, so the same request may pass later. A client given a max_retries above
+  # zero sends an idempotent request again after one, waiting a little longer before each attempt.
+  #
+  # @api public
+  # @example Retry a request the API failed to answer
+  #   client = X::Client.new(bearer_token: token, max_retries: 2)
+  class ServerError < HTTPError; end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "server_error"
+
+module X
+  # Raised for a 503 Service Unavailable response, which the API sends when it is overloaded or down for maintenance
+  # @api public
+  class ServiceUnavailable < ServerError; end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module X
+  # Error raised when save_tokens raised for the tokens of an exchange of a code or of a refresh
+  #
+  # An authorization code works once, and so does a refresh token, so the tokens X issues for either are held in
+  # memory alone until save_tokens stores them: the first refresh token of X::OAuth2Authorization#client by the
+  # client it builds, and the one a refresh issued by the authenticator that refreshed, since the one it replaced is
+  # spent. They are not lost to a failure to store them, such as a database that is briefly down: the error holds
+  # them, so they can be stored again, and the client, which the exchange builds, or whose request refreshed. The
+  # error save_tokens raised is the cause, whose message the message ends with.
+  #
+  # @api public
+  class TokenReportFailed < Error
+    # The client the authorization built, or whose request refreshed the tokens
+    # @api public
+    # @return [Client, nil] the client, or nil for a refresh made by an authenticator alone, as its refresh! makes one
+    # @example Act for the user once the tokens are stored
+    #   rescue X::TokenReportFailed => e
+    #     store(e.tokens.refresh_token)
+    #     e.client.get("users/me")
+    attr_reader :client
+
+    # The tokens of the exchange or the refresh, which save_tokens raised for
+    # @api public
+    # @return [OAuth2Tokens, nil] the tokens, or nil if none were given
+    # @example Store the tokens again
+    #   rescue X::TokenReportFailed => e
+    #     store(e.tokens.refresh_token)
+    attr_reader :tokens
+
+    # Initialize the error with the client and the tokens it failed to report
+    #
+    # @api public
+    # @param message [String, nil] the message, or nil for one that says the tokens of an exchange were not stored
+    # @param client [Client, nil] the client the authorization built, or whose request refreshed the tokens
+    # @param tokens [OAuth2Tokens, nil] the tokens of the exchange or the refresh
+    # @return [TokenReportFailed] a new error
+    # @example Raise the error for tokens save_tokens raised for
+    #   raise X::TokenReportFailed.new(client:, tokens:)
+    def initialize(message = nil, client: nil, tokens: nil)
+      @client = client
+      @tokens = tokens
+      super(message || "The code was exchanged for tokens, but save_tokens raised for them")
+    end
+
+    # The message, ending with why save_tokens raised
+    #
+    # It ends with the message of the error save_tokens raised, which is the cause, if there is one.
+    #
+    # @api public
+    # @return [String] the message
+    # @example Read why the tokens were not stored
+    #   error.message # => "The code was exchanged for tokens, but save_tokens raised for them: connection refused"
+    def to_s = [super, cause&.message].compact.join(": ")
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "../request_context"
+
+module X
+  module Core
+    # Raised for a response that redirected more times than the client's max_redirects allows
+    #
+    # The message names the request whose redirect was one too many, and {#http_method} and {#uri} read it: the
+    # request that redirect answered, which is the one a client sent last, rather than the one it was first asked for.
+    #
+    # @api public
+    # @example Tell an endpoint that redirects in a loop from the others
+    #   rescue X::TooManyRedirects => e
+    #     logger.warn("#{e.uri} keeps redirecting")
+    class ::X::TooManyRedirects < Error
+      include RequestContext
+
+      # @!method http_method
+      #   The HTTP method the request whose redirect was one too many was sent with
+      #   @api public
+      #   @return [Symbol, nil] the method, as :get, :post, :put, or :delete, or nil for an error built without one
+      #   @example Tell a read that redirected in a loop from a write
+      #     writes_failed += 1 unless error.http_method.eql?(:get)
+      # @!method uri
+      #   The URI the request whose redirect was one too many was sent to
+      #   @api public
+      #   @return [URI::Generic, nil] the URI, or nil for an error built without one
+      #   @example Get the path that keeps redirecting
+      #     error.uri.path # => "/2/users/me"
+
+      # Initialize a new TooManyRedirects
+      #
+      # Public, so that code that rescues a TooManyRedirects can be tested with one built by hand, as RedirectHandler
+      # builds one, or raised with no message, as any exception is. The error names the request, when given its method
+      # and URI, as x-core names the request whose redirect was one too many.
+      #
+      # @api public
+      # @param message [String, nil] what went wrong, or nil for the name of the class, as an exception raised with no
+      #   message is named, which names no request
+      # @param http_method [Symbol, String, nil] the method of the request whose redirect was one too many, in any case
+      # @param uri [URI::Generic, nil] the URI of the request whose redirect was one too many
+      # @return [TooManyRedirects] a new instance
+      # @example Create an error
+      #   error = X::TooManyRedirects.new("Too many redirects", http_method: :get, uri: URI("https://api.x.com/2/users/me"))
+      def initialize(message = nil, http_method: nil, uri: nil)
+        name_request(http_method, uri)
+        super(message && message_naming_request(message))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+require_relative "../rate_limit"
+
+module X
+  # Error raised when rate limit is exceeded (HTTP 429)
+  # @api public
+  class TooManyRequests < ClientError
+    # The rate limits the response reports in its headers, as X::Response reports them
+    #
+    # They are read once and frozen, since the other readers of the error, and the wait before a request is sent
+    # again, read them too, so that a caller changing them changes none of those.
+    #
+    # @api public
+    # @return [Array<RateLimit>] the 15-minute limit, and the 24-hour app and user limits when reported, frozen
+    # @example Print how many requests remain in each window
+    #   error.rate_limits.each { |limit| puts "#{limit.type}: #{limit.remaining}" }
+    def rate_limits
+      @rate_limits ||= RateLimit.__send__(:all_from, http_response).freeze
+    end
+
+    # The 15-minute rate limit of the endpoint, which nearly every response reports
+    #
+    # @api public
+    # @return [RateLimit, nil] the rate limit, or nil if the response reports none
+    # @example Read how many of the 15-minute requests are left
+    #   error.rate_limit&.remaining # => 3
+    def rate_limit = rate_limits.find { |limit| limit.type.eql?(RateLimit::RATE_LIMIT_TYPE) }
+
+    # The rate limits with no requests left, one of which refused the request
+    #
+    # @api public
+    # @return [Array<RateLimit>] the reported limits that are exhausted
+    # @example Name the windows that are used up
+    #   error.exhausted_rate_limits.map(&:type) # => ["app-limit-24hour"]
+    def exhausted_rate_limits = rate_limits.select(&:exhausted?)
+
+    # The exhausted rate limit that resets last, which a request waits for
+    #
+    # @api public
+    # @return [RateLimit, nil] the limit, or nil if the response reports none as exhausted
+    # @example Name the window that refused the request
+    #   error.limiting_rate_limit&.type # => "app-limit-24hour"
+    def limiting_rate_limit = exhausted_rate_limits.max_by(&:reset_at)
+
+    # Get the time when the rate limit resets
+    #
+    # @api public
+    # @return [Time, nil] the reset time, or nil if the response does not say when the limit resets
+    # @example Get the reset time
+    #   error.reset_at
+    def reset_at
+      limiting_rate_limit&.reset_at
+    end
+
+    # Get the seconds until the rate limit resets
+    #
+    # @api public
+    # @return [Integer, nil] the seconds until reset, or nil if the response does not say when the limit resets
+    # @example Get the time until reset
+    #   error.reset_in
+    def reset_in
+      limiting_rate_limit&.reset_in
+    end
+
+    # The seconds to wait before retrying, as the response asks
+    #
+    # A Retry-After header counts the seconds from when the response was sent, so it says the same thing however
+    # far this machine's clock is from the API's, where reset_in is off by the difference between the two. The
+    # header is preferred for that reason, and the limit that refused the request answers for a response that
+    # carries none. X recommends waiting a minute, doubling the wait for each retry after, when it says neither.
+    #
+    # @api public
+    # @return [Integer, nil] the seconds to wait before retrying, or nil if the response does not say
+    # @example Wait before retrying
+    #   sleep(error.retry_after || 60)
+    def retry_after = super || reset_in
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module X
+  # Raised for a 401 Unauthorized response, which the API sends for credentials it does not accept, such as a token
+  # that has expired or been revoked, or a request that carries none
+  #
+  # A client that authenticates with OAuth 2.0 refreshes a token the API rejects and sends the request again, so it
+  # raises this error for a token that is rejected once refreshed, and an AuthorizationError, whose cause is this
+  # error, for a refresh X refuses.
+  #
+  # @api public
+  class Unauthorized < ClientError; end
+end

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module X
+  # Raised for a 451 Unavailable For Legal Reasons response, which the API sends for a resource withheld in the
+  # country the request came from
+  # @api public
+  class UnavailableForLegalReasons < ClientError; end
+end

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module X
+  # Raised for a 422 Unprocessable Entity response, which the API sends for a request it can read but will not act
+  # on, such as a stream rule it rejects
+  # @api public
+  class UnprocessableEntity < ClientError; end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module X
+  # Raised when Marshal, YAML, or JSON reads what was written in a format this release does not read
+  #
+  # What the X gems write with Marshal or YAML, such as a resource, a page, or a problem, and the JSON of the tokens
+  # of OAuth 2.0, is plain data led by the number of
+  # its format, which every release of 1.x writes, each adding only what an earlier one ignores, so that a cache
+  # written by one release of 1.x is read by every other, and one written in another format, as a later major
+  # version may write, fails where it is read, rather than read as something it is not. Such a cache is written again.
+  #
+  # @api public
+  # @example Read a cached user again when it was written in another format
+  #   begin
+  #     Marshal.load(cached)
+  #   rescue X::UnsupportedFormat
+  #     Rails.cache.delete("user")
+  #   end
+  class UnsupportedFormat < Error; end
+end

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module X
+  # Raised for a 415 Unsupported Media Type response, which the API sends for a body in a format the endpoint does
+  # not take, such as a form where it takes JSON
+  # @api public
+  class UnsupportedMediaType < ClientError; end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module X
+  # Raised when there is no way to do what was asked with what the client holds
+  #
+  # The API may offer none, as it offers no lookup of lists in a batch, or the credentials a client holds may not
+  # reach it: a client that authenticates with OAuth 2.0 as a user, and holds no credentials of the app, has no
+  # app-only client for Client#app_only to return, and an OAuth 2.0 authenticator that holds no refresh token, as an
+  # authorization without the offline.access scope issues none, cannot refresh its access token. Either is raised
+  # before any request. A request the API refuses the credentials of a client for raises the error of its response
+  # instead, as a stream, or the count of the full archive, of a client with no app-only client raises the
+  # X::Forbidden of the 403 the API answers it with.
+  #
+  # @api public
+  class UnsupportedOperation < Error; end
+end

data/lib/x/core/oauth1_authenticator.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "simple_oauth"
+require "uri"
+require_relative "authenticator"
+require_relative "credential_validator"
+require_relative "setting_validator"
+
+module X
+  module Core
+    # Authenticator for OAuth 1.0a authentication
+    # @api public
+    class ::X::OAuth1Authenticator < Authenticator
+      # The media type whose body OAuth 1.0a signs as request parameters
+      FORM_CONTENT_TYPE = "application/x-www-form-urlencoded"
+      private_constant :FORM_CONTENT_TYPE
+
+      # The API key (consumer key)
+      # @api public
+      # @return [String] the API key (consumer key)
+      # @example Get the API key
+      #   authenticator.api_key
+      attr_reader :api_key
+
+      # Initialize a new OAuth1Authenticator
+      #
+      # @api public
+      # @param api_key [String] the API key (consumer key)
+      # @param api_key_secret [String] the API key secret (consumer secret)
+      # @param access_token [String] the access token
+      # @param access_token_secret [String] the access token secret
+      # @return [OAuth1Authenticator] a new instance
+      # @raise [ArgumentError] if a credential is nil or empty
+      # @example Create an OAuth authenticator
+      #   authenticator = X::OAuth1Authenticator.new(
+      #     api_key: "key",
+      #     api_key_secret: "secret",
+      #     access_token: "token",
+      #     access_token_secret: "token_secret"
+      #   )
+      def initialize(api_key:, api_key_secret:, access_token:, access_token_secret:)
+        CredentialValidator.validate_required!({api_key:, api_key_secret:, access_token:, access_token_secret:})
+        @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)
+      end
+
+      # The identifier of the user the access token acts for
+      #
+      # An OAuth 1.0a access token begins with the identifier of the user who authorized it, so a client that signs
+      # with one knows the user it acts for without asking the API.
+      #
+      # @api public
+      # @return [Integer, nil] the identifier, or nil for a token that begins with none
+      # @example Read the user a client acts for without a request
+      #   client.authenticator.user_id # => 7505382
+      def user_id
+        prefix = access_token[/\A(\d+)-/, 1]
+        Integer(prefix, 10) if prefix
+      end
+
+      # Generate the OAuth authentication headers for a request
+      #
+      # The signature covers the HTTP method, the URL, its query parameters, and a
+      # form-encoded body. Bodies of any other media type, such as the JSON and multipart
+      # bodies the X API takes, are not signed.
+      #
+      # @api public
+      # @param request [#http_method, #uri, #body, #[]] the request, whose method, uri, body, and Content-Type the signature reads
+      # @return [Hash{String => String}] the authentication header with OAuth signature
+      # @example Generate an OAuth authentication header
+      #   authenticator.headers(request)
+      def headers(request)
+        oauth_header = SimpleOAuth::Header.new(request.http_method, request.uri, form_params(request), credentials)
+        {AUTHENTICATION_HEADER => oauth_header.to_s}
+      end
+
+      private
+
+      # The API key secret (consumer secret), which signs a request
+      # @api private
+      # @return [String] the API key secret (consumer secret)
+      # @example Sign with the API key secret
+      #   api_key_secret
+      attr_reader :api_key_secret
+
+      # The access token, which signs each request and names the user it acts for
+      #
+      # It is a credential, so it is private, as the access token of a client is: the user it acts for is read with
+      # {#user_id}.
+      #
+      # @api private
+      # @return [String] the access token
+      # @example Sign with the access token
+      #   access_token
+      attr_reader :access_token
+
+      # The access token secret, which signs a request
+      # @api private
+      # @return [String] the access token secret
+      # @example Sign with the access token secret
+      #   access_token_secret
+      attr_reader :access_token_secret
+
+      # The credentials, under the names simple_oauth gives them
+      # @api private
+      # @return [Hash{Symbol => String}] the credentials for signing
+      def credentials
+        {consumer_key: api_key, consumer_secret: api_key_secret, token: access_token,
+         token_secret: access_token_secret}
+      end
+
+      # The parameters a form-encoded body contributes to the signature
+      #
+      # A parameter that repeats is signed once per value, as RFC 5849 Section 3.4.1.3.2 requires,
+      # which the key-value pairs preserve.
+      #
+      # @api private
+      # @param request [#http_method, #uri, #body, #[]] the request
+      # @return [Array<Array(String, String)>] the body parameters, empty unless the body is form-encoded
+      def form_params(request)
+        URI.decode_www_form(form_body(request))
+      end
+
+      # The body whose parameters take part in the signature
+      #
+      # @api private
+      # @param request [#http_method, #uri, #body, #[]] the request
+      # @return [String] the body, or an empty String when it is not form-encoded
+      def form_body(request)
+        form_encoded?(request) ? request.body.to_s : ""
+      end
+
+      # Check whether a request carries a form-encoded body
+      # @api private
+      # @param request [#http_method, #uri, #body, #[]] the request
+      # @return [Boolean] true if the body is form-encoded
+      def form_encoded?(request)
+        request["Content-Type"].to_s.split(";").first.to_s.strip.downcase.eql?(FORM_CONTENT_TYPE)
+      end
+    end
+  end
+end