x-core 1.0.0

data/lib/x/core/app_only_authenticator.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "simple_oauth"
+require_relative "authenticator"
+require_relative "connection"
+require_relative "credential_validator"
+require_relative "setting_validator"
+require_relative "errors/authorization_error"
+require_relative "errors/unauthorized"
+require_relative "origin"
+require_relative "token_endpoint"
+
+module X
+  module Core
+    # Authenticates as an app with a bearer token, fetched with the API key and secret when first needed
+    #
+    # A bearer token the API rejects with 401 Unauthorized, as it does one that was invalidated, is dropped, and the
+    # request is sent again with one fetched in its place.
+    #
+    # @api public
+    class ::X::AppOnlyAuthenticator < Authenticator
+      # The endpoint that exchanges an API key and secret for a bearer token, at X, whose path is requested at the
+      # origin of the base URL of the client that takes the authenticator
+      TOKEN_URL = "https://api.x.com/oauth2/token"
+      # The message raised when the token endpoint describes no reason for the failure
+      DEFAULT_ERROR_MESSAGE = "Bearer token request failed"
+      private_constant :TOKEN_URL, :DEFAULT_ERROR_MESSAGE
+
+      # The API key
+      # @api public
+      # @return [String] the API key
+      # @example Get the API key
+      #   authenticator.api_key
+      attr_reader :api_key
+
+      # Initialize a new app-only authenticator
+      #
+      # @api public
+      # @param api_key [String] the API key
+      # @param api_key_secret [String] the API key secret
+      # @param bearer_token [String, nil] a bearer token already fetched with these credentials
+      # @return [AppOnlyAuthenticator] a new authenticator
+      # @raise [ArgumentError] if the API key or secret is nil or empty, or the bearer token is empty
+      # @example Create an app-only authenticator
+      #   X::AppOnlyAuthenticator.new(api_key: "key", api_key_secret: "secret")
+      def initialize(api_key:, api_key_secret:, bearer_token: nil)
+        CredentialValidator.validate_required!({api_key:, api_key_secret:}, {bearer_token:})
+        @api_key, @api_key_secret = SettingValidator.frozen(api_key), SettingValidator.frozen(api_key_secret)
+        @bearer_token = SettingValidator.frozen(bearer_token)
+        @connection, @token_url, @token_headers = Connection.new, TOKEN_URL, {}
+        @mutex = Mutex.new
+      end
+
+      # Generate the authentication headers, fetching the bearer token first if needed
+      #
+      # @api public
+      # @param _request [#http_method, #uri, #body, #[], nil] the request, which app-only authentication does not sign
+      # @return [Hash{String => String}] the authorization header
+      # @raise [AuthorizationError] if X refuses to issue the bearer token
+      # @raise [HTTPError, InvalidResponse] if the token endpoint limits the rate of the request or fails to answer,
+      #   as a server error, a redirect, or the page of a proxy says
+      # @example Generate the header
+      #   authenticator.headers(request) # => {"Authorization" => "Bearer ..."}
+      def headers(_request)
+        {AUTHENTICATION_HEADER => "Bearer #{bearer_token}"}
+      end
+
+      private
+
+      # The bearer token, fetched once with the API key and secret
+      #
+      # It is a secret, so it is private, as the bearer token of a BearerTokenAuthenticator is. Internal to x-core:
+      # a client that authenticates as the app fetches its token through it, and calls it with __send__.
+      #
+      # @api private
+      # @return [String] the bearer token
+      # @raise [AuthorizationError] if X refuses to issue the bearer token
+      # @raise [HTTPError, InvalidResponse] if the token endpoint limits the rate of the request or fails to answer,
+      #   as a server error, a redirect, or the page of a proxy says
+      # @example Get the bearer token
+      #   bearer_token
+      def bearer_token
+        @mutex.synchronize { @bearer_token ||= fetch_bearer_token }
+      end
+
+      # The connection the bearer token is fetched over
+      # @api private
+      # @return [Core::Connection] the connection
+      attr_reader :connection
+
+      # Fetch the bearer token over the connection of the first client that takes it
+      #
+      # The token endpoint is requested at the scheme, host, and port of the base URL of the client, rather than of
+      # TOKEN_URL, so that a client pointed at another host sends the API key and secret there, as it sends its
+      # requests. A client that takes it after the first leaves it fetching over the connection of the first; see
+      # {OAuth2Authenticator}. Internal to x-core: a client fetches the token of the authenticator it builds, or is
+      # given, over its own connection, with its proxy, timeouts, debug output, and headers, and calls it with
+      # __send__, since it is private.
+      #
+      # @api private
+      # @param connection [Core::Connection] the connection to fetch the token over
+      # @param base_url [String] the base URL of the client, at whose origin the token endpoint is requested
+      # @param headers [Hash{String => String}] the headers of the client, which the token request is sent with
+      # @return [AppOnlyAuthenticator] the authenticator
+      def token_requests_over(connection, base_url, headers)
+        @mutex.synchronize do
+          unless @taken
+            @connection = connection
+            @token_url = TokenEndpoint.url_at(base_url, TOKEN_URL)
+            @token_headers = headers
+          end
+          @taken = true
+        end
+        self
+      end
+
+      # The API key secret, which buys the bearer token
+      # @api private
+      # @return [String] the API key secret
+      # @example Buy a bearer token with the API key secret
+      #   api_key_secret
+      attr_reader :api_key_secret
+
+      # Check whether a copy of a client, given these options, holds these credentials
+      #
+      # Internal to x-core: Client shares the authenticator with a copy that holds its API key and secret and was given
+      # no bearer token, and calls it with __send__, since it is private.
+      #
+      # @api private
+      # @param options [Hash] the options the copy was given in place of the client's
+      # @return [Boolean] true if the options name no bearer token, and no API key or secret but the ones held
+      def holds?(options)
+        !options.key?(:bearer_token) && options.slice(:api_key, :api_key_secret) <= {api_key:, api_key_secret:}
+      end
+
+      # Check whether the bearer token is fetched at the origin of a base URL
+      #
+      # A token is fetched at the origin of the client that took the authenticator first, and sent there alone, so a
+      # copy of the client pointed at another origin fetches one of its own, rather than send it the client's.
+      # Internal to x-core: Client shares the authenticator with a copy at the same origin alone, and calls it with
+      # __send__, since it is private.
+      #
+      # @api private
+      # @param base_url [String] the base URL of the copy
+      # @return [Boolean] true if the token endpoint is at the origin of the base URL
+      def fetched_for?(base_url) = Origin.same?(URI(@token_url), URI(base_url))
+
+      # Run a request, again with a bearer token fetched in place of one the API rejects
+      #
+      # Only a rejection by the origin the token is sent to drops it; see {Core::Origin}. A token fetched for the
+      # request itself is not fetched again, since the endpoint that just issued it would issue it again. Internal to
+      # x-core: Client runs each request through it, and calls it with __send__, since it is private.
+      #
+      # @api private
+      # @param origin [URI::Generic] the base URL of the client, the origin the token is sent to
+      # @yield runs the request
+      # @return [Object] what the block returns
+      # @raise [Unauthorized] if the API rejects the token fetched in place of the one it rejected
+      def retrying_rejected_token(origin)
+        token = @bearer_token
+        begin
+          yield
+        rescue Unauthorized => e
+          raise unless token && Origin.answered?(e, origin)
+
+          drop_bearer_token(token)
+          yield
+        end
+      end
+
+      # Drop a bearer token the API rejected, unless another request already replaced it
+      # @api private
+      # @param rejected [String] the bearer token the API rejected
+      # @return [void]
+      def drop_bearer_token(rejected)
+        @mutex.synchronize { @bearer_token = nil if @bearer_token.eql?(rejected) }
+      end
+
+      # Exchange the API key and secret for a bearer token
+      # @api private
+      # @return [String] the bearer token
+      # @raise [AuthorizationError] if the token endpoint rejects the request
+      # @raise [HTTPError, InvalidResponse] if the token endpoint limits the rate of the request or fails to answer,
+      #   as a server error, a redirect, or the page of a proxy says
+      def fetch_bearer_token
+        TokenEndpoint.fetch(token_request, connection:, refusal: DEFAULT_ERROR_MESSAGE, headers: @token_headers).access_token
+      end
+
+      # Build the client credentials request
+      # @api private
+      # @return [SimpleOAuth::OAuth2::Request] the token request
+      def token_request
+        SimpleOAuth::OAuth2::Client.new(client_id: api_key, client_secret: api_key_secret, token_endpoint: @token_url)
+          .client_credentials_request
+      end
+    end
+  end
+end

data/lib/x/core/authenticator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "credential_holder"
+
+# A Ruby client for the X API
+module X
+  module Core
+    # Base class for authentication
+    #
+    # Subclass it to authenticate with a scheme of your own, overriding {#headers}, as the authenticators of x-core do.
+    #
+    # @api public
+    class ::X::Authenticator
+      include CredentialHolder
+
+      # The HTTP header name for authentication
+      AUTHENTICATION_HEADER = "Authorization"
+
+      # Generate the authentication headers for a request, which authenticates as no one
+      #
+      # A client calls it for every request it sends to the origin of its base URL, and every stream it opens there,
+      # once the request is built, just before it is sent, and sends each header it returns, in place of any header of
+      # the same name. Its method, URI, headers, and body are set, so an authenticator of your own can sign any of them:
+      # subclass X::Authenticator and override this method, and give an instance to the authenticator: of
+      # X::Client.new or X::Client#with. A request to another origin, such as one a redirect leads to, is not passed to
+      # it, so its headers never leave the origin they were built for. It is called on the thread that sends the
+      # request, so one a client shares across threads must be thread-safe.
+      #
+      # The request answers four methods alone, which are all the authenticators of x-core read of it: http_method, the
+      # HTTP method as a Symbol, such as :post, as a response and an error name it; uri, the URI::Generic it is sent
+      # to, query included; body, the String it sends, or nil for none; and [], the value of a header by its name, in
+      # any case, or nil for one it does not send. It answers them alone whatever request the client sends, so an
+      # authenticator of your own reads nothing a later version of 1.x could take away.
+      #
+      # A client refreshes the token of none but its own OAuth 2.0 authenticator, so an authenticator of your own that
+      # holds a token that expires refreshes it here. A client given one takes it to authenticate as the app, as it
+      # does an X::Authenticator itself, so app_only returns the client, and a stream is opened with it.
+      #
+      # @api public
+      # @param _request [#http_method, #uri, #body, #[]] the request, which answers http_method, uri, body, and [] alone
+      # @return [Hash{String => String}] the headers that authenticate the request, empty for none
+      # @example Authenticate every request with a token an application keeps
+      #   class VaultAuthenticator < X::Authenticator
+      #     def headers(_request) = {AUTHENTICATION_HEADER => "Bearer #{Vault.read("x/bearer_token")}"}
+      #   end
+      #   client = X::Client.new(authenticator: VaultAuthenticator.new)
+      def headers(_request)
+        {}
+      end
+
+      # The identifier of the user the credentials act for, when they name one
+      #
+      # Only an OAuth 1.0a access token names its user, so every other set of credentials answers nil, and the caller
+      # that wants the user of such a client asks the API for it.
+      #
+      # @api public
+      # @return [Integer, nil] the identifier, or nil for credentials that name no user
+      # @example Read the user a client acts for without a request
+      #   client.authenticator.user_id # => nil
+      def user_id
+      end
+
+      # Summarize the authenticator for the console without revealing credentials
+      #
+      # @api public
+      # @return [String] the class name
+      # @example Inspect an authenticator
+      #   authenticator.inspect # => #<X::BearerTokenAuthenticator>
+      def inspect
+        "#<#{self.class}>"
+      end
+    end
+  end
+end

data/lib/x/core/authenticator_request.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module X
+  module Core
+    # The request an authenticator is passed: what it may read of the request a client is about to send
+    #
+    # It answers the four methods an authenticator is guaranteed, and no more, so that an authenticator of your own
+    # reads nothing of the Net::HTTPRequest a client sends that a later version of 1.x, which may send another, could
+    # take away.
+    #
+    # Internal to x-core: RequestBuilder passes one to the authenticator of each request it builds.
+    #
+    # @api private
+    class AuthenticatorRequest
+      # Initialize the request an authenticator reads
+      # @api private
+      # @param request [Net::HTTPRequest] the request a client is about to send
+      # @return [AuthenticatorRequest] a new instance
+      # @example Pass a request to an authenticator
+      #   authenticator.headers(X::Core::AuthenticatorRequest.new(request))
+      def initialize(request)
+        @request = request
+      end
+
+      # The HTTP method the request is sent with
+      # @api private
+      # @return [Symbol] the method, as :get, :post, :put, or :delete
+      # @example Read the method
+      #   request.http_method # => :post
+      def http_method = @request.method.downcase.to_sym
+
+      # The URI the request is sent to, query included
+      # @api private
+      # @return [URI::Generic] the URI
+      # @example Read the URI
+      #   request.uri # => #<URI::HTTPS https://api.x.com/2/tweets>
+      def uri = @request.uri
+
+      # The body the request sends
+      # @api private
+      # @return [String, nil] the body, or nil for none
+      # @example Read the body
+      #   request.body # => "{\"text\":\"Hello\"}"
+      def body = @request.body
+
+      # The value of a header the request sends
+      # @api private
+      # @param name [String] the name of the header, in any case
+      # @return [String, nil] the value, or nil for a header the request does not send
+      # @example Read the content type
+      #   request["Content-Type"] # => "application/json; charset=utf-8"
+      def [](name) = @request[name]
+    end
+    private_constant :AuthenticatorRequest
+  end
+end

data/lib/x/core/bearer_token_authenticator.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "authenticator"
+require_relative "credential_validator"
+require_relative "setting_validator"
+
+module X
+  module Core
+    # Authenticator for Bearer token authentication
+    # @api public
+    class ::X::BearerTokenAuthenticator < Authenticator
+      # Initialize a new BearerTokenAuthenticator
+      #
+      # @api public
+      # @param bearer_token [String] the bearer token for authentication
+      # @return [BearerTokenAuthenticator] a new instance
+      # @raise [ArgumentError] if the bearer token is nil or empty
+      # @example Create a new bearer token authenticator
+      #   authenticator = X::BearerTokenAuthenticator.new(bearer_token: "token")
+      def initialize(bearer_token:)
+        CredentialValidator.validate_required!({bearer_token:})
+        @bearer_token = SettingValidator.frozen(bearer_token)
+      end
+
+      # Generate the authentication headers for a request
+      #
+      # @api public
+      # @param _request [#http_method, #uri, #body, #[], nil] the request, which a bearer token does not sign
+      # @return [Hash{String => String}] the authentication header with bearer token
+      # @example Generate a bearer authentication header
+      #   authenticator.headers(request)
+      def headers(_request)
+        {AUTHENTICATION_HEADER => "Bearer #{bearer_token}"}
+      end
+
+      private
+
+      # The bearer token, which authenticates a request
+      # @api private
+      # @return [String] the bearer token
+      # @example Authenticate with the bearer token
+      #   bearer_token
+      attr_reader :bearer_token
+    end
+  end
+end

data/lib/x/core/built_response.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "net/http"
+require_relative "setting_validator"
+
+module X
+  module Core
+    # The HTTP response of an error or a summary built by hand, from its status, headers, and body
+    #
+    # Internal to x-core: HTTPError, InvalidResponse, and Response are built from the Net::HTTP response a client
+    # received, or, so that code that rescues one, or an on_response hook, can be tested without building one, from
+    # the status, headers, and body of a response, which this builds the Net::HTTP response of.
+    #
+    # @api private
+    module BuiltResponse
+      extend self
+
+      # The message of the error raised for a status that is not one HTTP defines
+      INVALID_STATUS = "status must be an Integer from 100 to 599, not %s"
+      private_constant :INVALID_STATUS
+      # The message of the error raised for a response given beside what one is built of
+      RESPONSE_AND_STATUS = "Pass the http_response:, or the status:, headers:, and body: one is built of, not both"
+      private_constant :RESPONSE_AND_STATUS
+      # The message of the error raised for neither a response nor a status
+      NO_RESPONSE = "Pass the status: of the response, with its headers: and body: if it has any, or the http_response: itself"
+      private_constant :NO_RESPONSE
+      # The statuses HTTP defines
+      STATUSES = 100..599
+      private_constant :STATUSES
+
+      # The HTTP response given, or the one built of a status, headers, and body
+      #
+      # @api private
+      # @param http_response [Net::HTTPResponse, nil] the HTTP response, or nil to build one
+      # @param status [Integer, nil] the status of the response to build, or nil for the one given
+      # @param headers [Hash{String => String}, nil] the headers of the response to build, or nil for none
+      # @param body [String, nil] the body of the response to build, or nil for none
+      # @return [Net::HTTPResponse] the HTTP response
+      # @raise [ArgumentError] if a response is given beside a status, headers, or a body, or neither a response nor a
+      #   status is given, or the status is not one HTTP defines, or the headers are not a Hash of names to values
+      # @example Build a response the API refused a request with
+      #   X::Core::BuiltResponse.of(nil, status: 404, headers: nil, body: "{}") # => #<Net::HTTPNotFound 404 Not Found>
+      def of(http_response, status:, headers:, body:)
+        return build(status, headers || {}, body) if http_response.nil? && !status.nil?
+        raise ArgumentError, NO_RESPONSE if http_response.nil?
+        raise ArgumentError, RESPONSE_AND_STATUS unless [status, headers, body].none?
+
+        http_response
+      end
+
+      private
+
+      # Build the HTTP response of a status, headers, and body
+      #
+      # Its body is tagged UTF-8, as the body of a response the client reads is.
+      #
+      # @api private
+      # @param status [Integer] the status
+      # @param headers [Hash{String => String}] the headers
+      # @param body [String, nil] the body
+      # @return [Net::HTTPResponse] the HTTP response
+      # @raise [ArgumentError] if the status is not one HTTP defines, or the headers are not a Hash of names to values
+      def build(status, headers, body)
+        response_class = response_class_of(status)
+        response_class.new("1.1", status.to_s, reason_of(response_class)).tap do |response|
+          SettingValidator.headers!(headers).each { |name, value| response[name] = value }
+          response.body = body.dup&.force_encoding(Encoding::UTF_8)
+          response.instance_variable_set(:@read, true)
+        end
+      end
+
+      # The class Net::HTTP reads a response of a status as
+      #
+      # It is the class of the status, such as Net::HTTPNotFound, or, for a status Net::HTTP names no class of, the
+      # class of its kind of status, such as Net::HTTPClientError for a 4xx.
+      #
+      # @api private
+      # @param status [Integer] the status
+      # @return [Class] the class
+      # @raise [ArgumentError] if the status is not one HTTP defines
+      def response_class_of(status)
+        raise ArgumentError, format(INVALID_STATUS, status.inspect) unless status.instance_of?(Integer) && STATUSES.cover?(status)
+
+        code = status.to_s
+        Net::HTTPResponse::CODE_TO_OBJ.fetch(code) { Net::HTTPResponse::CODE_CLASS_TO_OBJ.fetch(code[0]) }
+      end
+
+      # The reason phrase of the status of a Net::HTTP response class
+      #
+      # @api private
+      # @param response_class [Class] the class, such as Net::HTTPNotFound
+      # @return [String] the reason phrase, such as "Not Found"
+      def reason_of(response_class)
+        name = response_class.name #: String
+        name.delete_prefix("Net::HTTP").gsub(/(?<=[a-z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/, " ")
+      end
+    end
+    private_constant :BuiltResponse
+  end
+end