x-core 1.0.0

data/lib/x/core/client_settings.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require_relative "rate_limit_handler"
+require_relative "redirect_handler"
+require_relative "response"
+require_relative "retry_handler"
+require_relative "setting_validator"
+
+module X
+  module Core
+    # The settings of a client other than its credentials: its base URL, parsing classes, hook, and the settings of
+    # its connection and handlers, included into ClientInternals
+    #
+    # A client is built with the settings it keeps for as long as it lives. {Client#with} derives a client whose
+    # settings differ, rather than replacing the ones a client holds, so that a request never runs under a setting
+    # another thread is halfway through changing.
+    #
+    # @api private
+    module ClientSettings
+      extend Forwardable
+
+      # The base URL for API requests
+      #
+      # {Client#base_url} returns it.
+      #
+      # @api private
+      # @return [String] the base URL for API requests, which ends with a slash
+      attr_reader :base_url
+
+      # The default class for parsing JSON arrays
+      #
+      # {Client#default_array_class} returns it.
+      #
+      # @api private
+      # @return [Class] the default class for parsing JSON arrays
+      attr_reader :default_array_class
+
+      # The default class for parsing JSON objects
+      #
+      # {Client#default_object_class} returns it.
+      #
+      # @api private
+      # @return [Class, #from_response] the default class for parsing JSON objects
+      attr_reader :default_object_class
+
+      # The callable passed an X::Response after each request and streamed object
+      #
+      # {Client#on_response} returns it.
+      #
+      # @api private
+      # @return [#call, nil] the callable, or nil for none
+      attr_reader :on_response
+
+      # The headers sent with every request the client makes
+      #
+      # {Client#headers} returns it.
+      #
+      # @api private
+      # @return [Hash{String => String}] the headers, frozen
+      attr_reader :headers
+
+      def_delegators :@connection, :open_timeout, :read_timeout, :write_timeout, :keep_alive_timeout, :debug_output
+      def_delegators :@redirect_handler, :max_redirects
+      def_delegators :@rate_limit_handler, :max_rate_limit_retries, :max_rate_limit_wait
+      def_delegators :@retry_handler, :max_retries
+
+      # Send a request that is safe to send twice again after a failure
+      #
+      # It is what Client#with_retries does.
+      #
+      # @api private
+      # @yield sends the request
+      # @return [Object] what the block returns
+      def with_retries(&) = @rate_limit_handler.handing_down { @retry_handler.handle(idempotent: true, resend_unanswered: true, &) }
+
+      private
+
+      # Share the connections kept open by the client this one was copied from
+      #
+      # They are shared when this client opens its connections as that one does; see Connection#share_pool_of.
+      # A copy that differs only in what it sends, such as its headers, base URL, or credentials, would otherwise
+      # open connections of its own, with a TCP and TLS handshake for each, and keep them open, idle, until it is
+      # collected, so a copy made for each request would leave connections to each host behind it.
+      #
+      # The internals of the client copied call it on those of the copy with __send__, since it is private.
+      #
+      # @api private
+      # @param connection [Connection] the connection of the client this one was copied from
+      # @return [void]
+      def share_connection(connection) = @connection.share_pool_of(connection)
+
+      # The settings, as initialize accepts them
+      # @api private
+      # @return [Hash{Symbol => Object}] the settings
+      def settings
+        {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:}
+      end
+
+      # Initialize the settings, and the handlers of redirects, rate limits, and retries
+      #
+      # An endpoint is resolved against the base URL, which drops the last segment of a path that does not end with a
+      # slash, so a slash is added to a base URL without one. The headers are copied and frozen, so that changing the
+      # Hash a client was built with never changes what it sends.
+      #
+      # @api private
+      # @param base_url [String] the base URL for API requests
+      # @param default_array_class [Class] the default class for parsing JSON arrays
+      # @param default_object_class [Class, #from_response] the default class for parsing JSON objects
+      # @param headers [Hash{String, Symbol => String}] the headers sent with every request
+      # @param on_response [#call, nil] the callable passed an X::Response after every request and streamed object
+      # @param max_redirects [Integer] the maximum number of redirects to follow
+      # @param max_rate_limit_retries [Integer] the maximum number of times to retry a request refused for a rate limit
+      # @param max_rate_limit_wait [Integer, Float] the maximum number of seconds to wait for a rate limit to reset
+      # @param max_retries [Integer] the maximum number of times to send an idempotent request again after a failure
+      # @return [void]
+      # @raise [ArgumentError] if on_response is neither nil nor responds to call
+      # @raise [ArgumentError] if default_array_class is not a Class, or default_object_class is neither a Class nor
+      #   responds to from_response
+      def 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:)
+        base_url = SettingValidator.base_url!(base_url)
+        @base_url = (base_url.end_with?("/") ? base_url : "#{base_url}/").freeze
+        @default_array_class = SettingValidator.array_class!(:default_array_class, default_array_class)
+        @default_object_class = SettingValidator.object_class!(:default_object_class, default_object_class)
+        @headers = SettingValidator.headers!(headers).freeze
+        @on_response = SettingValidator.callable!(:on_response, on_response)
+        @redirect_handler = RedirectHandler.new(connection: @connection, request_builder: @request_builder, max_redirects:)
+        @rate_limit_handler = RateLimitHandler.new(max_rate_limit_retries:, max_rate_limit_wait:)
+        @retry_handler = RetryHandler.new(max_retries:)
+      end
+
+      # The headers of a request, the client's under the request's own
+      #
+      # A header of the request is sent in place of one of the client whose name differs from it in case alone.
+      #
+      # @api private
+      # @param request_headers [Hash{String => String}] the headers passed to the request
+      # @return [Hash{String => String}] the headers to send
+      def headers_for(request_headers) = RequestBuilder.merge_headers(headers, request_headers)
+
+      # Pass a response to on_response and to the block of the request
+      #
+      # Both receive the one summary, the client's hook first, so that a hook which counts every request and a block
+      # which reads the response of one see the same object. Neither is built a summary when there is nothing to
+      # pass it to.
+      #
+      # @api private
+      # @param http_method [Symbol, String] the HTTP method of the request, in any case
+      # @param uri [URI::Generic] the URI of the request
+      # @param response [Net::HTTPResponse] the HTTP response
+      # @yieldparam response [Response] the summary of the response
+      # @return [void]
+      def report(http_method, uri, response, &block)
+        return unless on_response || block
+
+        summary = Response.new(http_response: response, http_method:, uri:)
+        on_response&.call(summary)
+        block&.call(summary)
+      end
+    end
+    private_constant :ClientSettings
+  end
+end

data/lib/x/core/client_token_refresh.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+require_relative "app_only_authenticator"
+require_relative "oauth2_authenticator"
+require_relative "setting_validator"
+
+module X
+  module Core
+    # The OAuth 2.0 authenticator of a client, which its copies share, and the tokens it last refreshed, included into
+    # ClientInternals
+    # @api private
+    module ClientTokenRefresh
+      # The message of the error raised for a copy given an expiration time or scopes for the access token it shares
+      SHARED_EXPIRATION = "A copy that shares the access token of the client shares its expiration time and scopes, " \
+        "so it cannot be given %s. Pass it beside the access token and refresh token it belongs to"
+      private_constant :SHARED_EXPIRATION
+      # The options that belong to the tokens of the client, which a copy that does not keep the client's
+      # authenticator holds only when it is given them
+      TOKEN_OPTIONS = %i[refresh_token expires_at scopes save_tokens load_tokens].freeze
+      # The options that are credentials, any of which a copy that authenticates as the client is not given
+      CREDENTIAL_OPTIONS = %i[api_key api_key_secret access_token access_token_secret bearer_token client_id client_secret refresh_token].freeze
+      private_constant :TOKEN_OPTIONS, :CREDENTIAL_OPTIONS
+
+      # The time the OAuth 2.0 access token expires, as last refreshed
+      #
+      # {Client#expires_at} returns it.
+      #
+      # @api private
+      # @return [Time, nil] the expiration time, or nil if it is not known
+      def expires_at
+        current = oauth2_authenticator_in_use
+        current ? current.expires_at : @expires_at
+      end
+
+      # The scopes X granted the OAuth 2.0 access token, as last refreshed
+      #
+      # {Client#scopes} returns it.
+      #
+      # @api private
+      # @return [Array<String>, nil] the scopes, or nil if they are not known
+      def scopes
+        current = oauth2_authenticator_in_use
+        current ? current.scopes : @scopes
+      end
+
+      private
+
+      # Initialize the callables that store and load the tokens of a refresh
+      # @api private
+      # @param save_tokens [#call, nil] the callable passed the OAuth2Tokens of each refresh
+      # @param load_tokens [#call, nil] the callable that returns the OAuth2Tokens in the store
+      # @return [void]
+      # @raise [ArgumentError] if save_tokens or load_tokens is neither nil nor responds to call
+      def initialize_token_hooks(save_tokens:, load_tokens:)
+        @save_tokens = SettingValidator.callable!(:save_tokens, save_tokens)
+        @load_tokens = SettingValidator.callable!(:load_tokens, load_tokens)
+      end
+
+      # Share the authenticator of the client this one was copied from
+      #
+      # A copy that holds the credentials of the client shares its OAuth 2.0 or app-only authenticator, so that the
+      # copy refreshes the tokens of the client, or sends the bearer token it fetched, rather than hold tokens of its
+      # own. A copy given an authenticator of its own keeps it. The internals of the client copied call it on those of
+      # the copy with __send__, since it is private.
+      #
+      # @api private
+      # @param copy [Client] the copy these are the internals of
+      # @param other [Authenticator] the authenticator of the client this one was copied from
+      # @param options [Hash] the options the copy was given in place of the client's
+      # @return [void]
+      def share_authenticator(copy, other, options)
+        return if options[:authenticator]
+
+        case other
+        when AppOnlyAuthenticator then share_app_only(other, options)
+        when OAuth2Authenticator then share_oauth2(copy, other, options)
+        end
+      end
+
+      # Share the OAuth 2.0 authenticator of the client this one was copied from
+      #
+      # A refresh by either client then reaches both. X accepts a refresh token once, so a copy that refreshed with
+      # an authenticator of its own would leave the original client with a refresh token that no longer works.
+      #
+      # Whether the two share it is decided by the options the copy was given, not by the tokens it was built with:
+      # a refresh on another thread may replace them while it is built, and a copy that held on to the ones replaced
+      # could never refresh again. The expiration time and scopes are facts about the access token the two hold, so a
+      # copy that shares it is refused either, rather than set it for the client it was copied from.
+      #
+      # @api private
+      # @param copy [Client] the copy these are the internals of
+      # @param other [OAuth2Authenticator] the authenticator of the client this one was copied from
+      # @param options [Hash] the options the copy was given in place of the client's
+      # @return [void]
+      # @raise [ArgumentError] if the copy shares the authenticator and was given an expiration time or scopes
+      def share_oauth2(copy, other, options)
+        return unless oauth2_authenticator_in_use && other.__send__(:holds?, options)
+
+        given = options.keys & %i[expires_at scopes]
+        raise ArgumentError, format(SHARED_EXPIRATION, given.join(" or ")) unless given.empty?
+
+        @authenticator = join(copy, other)
+      end
+
+      # The options of a copy, without the tokens of a client it does not share
+      #
+      # A copy that authenticates otherwise than the client authenticates with tokens that may be another user's. It
+      # holds the refresh token, expiration time, scopes, save_tokens, and load_tokens of the client only when it is
+      # given them: a refresh of the copy would otherwise spend the refresh token the client holds, which X accepts
+      # once, read the store of the client with its load_tokens and take the client's tokens in place of its own, or
+      # pass its tokens to the save_tokens of the client, which would store them in place of the client's.
+      #
+      # @api private
+      # @param copied [Hash{Symbol => Object}] the options the copy is built with
+      # @param options [Hash{Symbol => Object}] the options the copy was given
+      # @return [Hash{Symbol => Object}] the options, without those of the tokens of the client the copy was not given
+      def without_tokens_of_client(copied, options)
+        keeps_authenticator?(copied, options) ? copied : copied.except(*(TOKEN_OPTIONS - options.keys))
+      end
+
+      # Check whether a copy keeps the authenticator of the client
+      #
+      # A copy of a client given its authenticator keeps it unless given a credential or an authenticator, which
+      # replaces it. A copy of a client built from credentials keeps its OAuth 2.0 authenticator unless given an
+      # authenticator, or a client ID, client secret, access token, or refresh token the authenticator does not hold,
+      # and keeps any other authenticator unless given an authenticator or any credential.
+      #
+      # @api private
+      # @param copied [Hash{Symbol => Object}] the options the copy is built with
+      # @param options [Hash{Symbol => Object}] the options the copy was given
+      # @return [Boolean] whether the copy authenticates as the client does
+      def keeps_authenticator?(copied, options)
+        return copied[:authenticator].equal?(@authenticator) if @given_authenticator
+        return false if options[:authenticator]
+
+        current = oauth2_authenticator_in_use
+        current ? current.__send__(:holds?, options) : !options.keys.intersect?(CREDENTIAL_OPTIONS)
+      end
+
+      # Share the app-only authenticator of the client this one was copied from
+      #
+      # It is shared by a copy that authenticates as the app with the API key and secret the authenticator holds, at
+      # the origin it fetches the bearer token at, and was given no bearer token of its own, so the bearer token the
+      # client fetched, or fetches, is fetched once, and is sent to no other origin than the one that issued it.
+      #
+      # @api private
+      # @param other [AppOnlyAuthenticator] the authenticator of the client this one was copied from
+      # @param options [Hash] the options the copy was given in place of the client's
+      # @return [void]
+      def share_app_only(other, options)
+        return unless AppOnlyAuthenticator === @authenticator && other.__send__(:holds?, options)
+
+        @authenticator = other if other.__send__(:fetched_for?, base_url)
+      end
+
+      # Take an authenticator the client was given, as it would one it built
+      #
+      # The token requests of an authenticator that makes them are sent over the connection of the first client
+      # given it, and the refreshes of an OAuth 2.0 one reach the save_tokens of each client that shares it.
+      #
+      # @api private
+      # @param client [Client] the client these are the internals of
+      # @param authenticator [Authenticator] the authenticator
+      # @return [Authenticator] the authenticator
+      def take(client, authenticator)
+        case authenticator
+        when OAuth2Authenticator then join(client, authenticator.__send__(:token_requests_over, @connection, base_url, headers))
+        when AppOnlyAuthenticator then authenticator.__send__(:token_requests_over, @connection, base_url, headers)
+        else authenticator
+        end
+      end
+
+      # Join the clients whose save_tokens an OAuth 2.0 authenticator reports to
+      # @api private
+      # @param client [Client] the client these are the internals of
+      # @param authenticator [OAuth2Authenticator] the authenticator
+      # @return [OAuth2Authenticator] the authenticator
+      def join(client, authenticator)
+        clients = authenticator.__send__(:clients)
+        clients[client] = true
+        authenticator.__send__(:report_refreshes_to, -> { clients.keys.filter_map(&:save_tokens).uniq })
+        authenticator
+      end
+
+      # The OAuth 2.0 authenticator, if the client authenticates with one
+      # @api private
+      # @return [OAuth2Authenticator, nil] the authenticator or nil
+      def oauth2_authenticator_in_use
+        current = @authenticator
+        current if current.is_a?(OAuth2Authenticator)
+      end
+
+      # The OAuth 2.0 authenticator of the client's credentials, if they form a set
+      #
+      # A copy of a client shares the authenticator of the client it was copied from, rather than the one this
+      # builds, when the two hold the same credentials; see share_authenticator. A client ID and access token without
+      # a refresh token, as an authorization without offline.access issues them, build an authenticator that acts
+      # for the user and cannot refresh.
+      #
+      # @api private
+      # @param client [Client] the client these are the internals of
+      # @return [OAuth2Authenticator, nil] the OAuth 2.0 authenticator or nil
+      def oauth2_authenticator(client)
+        client_id = @client_id
+        access_token = @access_token
+        return unless client_id && access_token
+
+        new_oauth2_authenticator(client, client_id:, access_token:, refresh_token: @refresh_token)
+      end
+
+      # The OAuth 2.0 authenticator of the client's credentials, as last refreshed
+      #
+      # It is the one the client built of them, or shares with the client it was copied from. A client given its
+      # authenticator holds no credentials, so the tokens of that authenticator are none of its credentials, which a
+      # copy would be built with beside it.
+      #
+      # @api private
+      # @return [OAuth2Authenticator, nil] the authenticator, or nil for a client that holds no OAuth 2.0 credentials
+      def oauth2_credentials_in_use = (oauth2_authenticator_in_use unless @given_authenticator)
+
+      # The access token for OAuth authentication, as last refreshed
+      #
+      # It is private, as {ClientCredentials#api_key_secret} is, and as the access token of the authenticator is. A
+      # hook given to save_tokens is passed the OAuth2Tokens of the refresh it reports.
+      #
+      # @api private
+      # @return [String, nil] the access token for OAuth authentication
+      def access_token
+        current = oauth2_credentials_in_use
+        current ? current.__send__(:access_token) : @access_token
+      end
+
+      # The OAuth 2.0 refresh token, as last refreshed
+      #
+      # It is private for the reason {#access_token} is.
+      #
+      # @api private
+      # @return [String, nil] the OAuth 2.0 refresh token
+      def refresh_token
+        current = oauth2_credentials_in_use
+        current ? current.__send__(:refresh_token) : @refresh_token
+      end
+
+      # Build an OAuth 2.0 authenticator whose refreshes reach the clients that share it
+      #
+      # It sends its token requests over the client's connection. A public client has no client secret, and refreshes
+      # its tokens with its client ID alone.
+      #
+      # @api private
+      # @param client [Client] the client these are the internals of
+      # @param client_id [String] the OAuth 2.0 client ID
+      # @param access_token [String] the OAuth 2.0 access token
+      # @param refresh_token [String, nil] the OAuth 2.0 refresh token, or nil for an access token that is not refreshed
+      # @return [OAuth2Authenticator] the OAuth 2.0 authenticator
+      def new_oauth2_authenticator(client, client_id:, access_token:, refresh_token:)
+        authenticator = OAuth2Authenticator.new(client_id:, client_secret: @client_secret, access_token:, refresh_token:, expires_at: @expires_at, scopes: @scopes)
+        join(client, authenticator.__send__(:token_requests_over, @connection, base_url, headers))
+      end
+
+      # Run a request, again if a refresh replaces an OAuth 2.0 token the API rejects
+      #
+      # Only a rejection by the origin of the base URL, which the token is sent to, refreshes it; see {Origin}. An
+      # app-only bearer token the API rejects is fetched again the same way; see {AppOnlyAuthenticator}. A stream
+      # that Client#get_stream opens runs through it too.
+      #
+      # @api private
+      # @param client [Client] the client these are the internals of, which a refresh that fails to report is raised
+      #   with
+      # @yield runs the request
+      # @return [Object] what the block returns
+      def refreshing_rejected_token(client, &)
+        case (current = @authenticator)
+        when OAuth2Authenticator then current.__send__(:retrying_rejected_token, URI(base_url), @connection, client, &)
+        when AppOnlyAuthenticator then current.__send__(:retrying_rejected_token, URI(base_url), &)
+        else yield
+        end
+      end
+    end
+    private_constant :ClientTokenRefresh
+  end
+end