resteze 0.4.0 → 1.0.0

data/lib/resteze/authenticator/strategy.rb

@@ -0,0 +1,133 @@
+module Resteze
+  class Authenticator
+    # An authentication scheme. Strategies hold only their configuration;
+    # anything mutable, such as a cached credential, goes in the `state`
+    # hash the authenticator hands them, already under its lock. Because
+    # that hash is shared by every strategy on the authenticator, prefix
+    # the keys you store with the scheme's name.
+    #
+    # Credential options name module settings. A Symbol such as `:api_key`
+    # reads `MyApi.api_key`, which an initializer fills through
+    # `MyApi.configure`, on every request. Each built-in defaults to the
+    # obvious setting (see its DEFAULTS), and declaring the scheme declares
+    # the setting on the module, so `config.api_key = ...` needs no
+    # `attr_accessor`. A callable or a literal works in place of a Symbol.
+    #
+    # To add a scheme, subclass this, implement `apply`, declare DEFAULTS
+    # for any options that should read settings, and pass the class to
+    # `authenticate_with` with its options.
+    class Strategy
+      # Option defaults; Symbol values are settings read from the module.
+      DEFAULTS = {}.freeze
+
+      # Options the scheme works without (a passphrase for a key that is
+      # not encrypted). Their settings are declared on the module like any
+      # other but never reported by `missing_settings`.
+      OPTIONAL = [].freeze
+
+      attr_accessor :api_module
+
+      # Names a scheme for `authenticate_with :name`. Each built-in registers
+      # itself; a gem providing a scheme can do the same.
+      def self.register(name, klass)
+        registry[name.to_sym] = klass
+      end
+
+      def self.registry
+        @registry ||= {}
+      end
+
+      def self.lookup(name)
+        registry.fetch(name.to_sym) do
+          raise ArgumentError, "unknown authentication strategy #{name.inspect}; known: #{registry.keys.join(', ')}"
+        end
+      end
+
+      # The module settings these options (over the defaults) read.
+      def self.settings(options = {})
+        effective_options(options).values.grep(Symbol)
+      end
+
+      # Those of them the scheme cannot work without.
+      def self.required_settings(options = {})
+        effective_options(options).except(*self::OPTIONAL).values.grep(Symbol)
+      end
+
+      def self.effective_options(options)
+        self::DEFAULTS.merge(options)
+      end
+      private_class_method :effective_options
+
+      # The module settings this instance reads: DEFAULTS as overridden by
+      # the credential options it was built with.
+      def settings
+        self.class.settings(credential_options)
+      end
+
+      def required_settings
+        self.class.required_settings(credential_options)
+      end
+
+      # The credential options as given to the constructor, so `settings`
+      # reflects a renamed setting; schemes implement it.
+      def credential_options
+        {}
+      end
+
+      # Faraday connection options this scheme needs, merged into the
+      # connection when it is built. Most schemes need none.
+      def connection_options
+        {}
+      end
+
+      # Where `apply` puts the credential, so the client's debug log can
+      # mask it there: header names under :headers, query keys under
+      # :query, body keys under :params. Only the logged copy is masked;
+      # the request goes out intact. A scheme that adds a credential and
+      # leaves this empty writes it to the log at DEBUG.
+      def sensitive_keys
+        {}
+      end
+
+      # Add the credential to `request.headers`, `request.params` or
+      # `request.query`.
+      def apply(request, state); end
+
+      # After a MyApi::AuthenticationError: renew the credential and return
+      # true to have the request sent once more, or return false.
+      def refresh?(_error, _attempt, _state)
+        false
+      end
+
+      private
+
+      # For constructors: rejects nil for an option the scheme needs.
+      def required!(name, value)
+        raise ArgumentError, "#{name}: is required" if value.nil?
+
+        value
+      end
+
+      # A Symbol reads the named setting from the module (nil when there is
+      # no module or no such setting), a callable is called, anything else
+      # is used as is.
+      def resolve(value)
+        return value.call if value.respond_to?(:call)
+        return value unless value.is_a?(Symbol)
+
+        api_module.try(value)
+      end
+
+      # As `resolve`, but a nil result is a configuration error that names
+      # what to set.
+      def resolve!(option, value)
+        resolved = resolve(value)
+        return resolved unless resolved.nil?
+
+        where  = value.is_a?(Symbol) ? "#{api_module || 'the API module'}.#{value} is not set" : "#{option}: resolved to nil"
+        scheme = self.class.name&.demodulize&.underscore || "custom"
+        raise ArgumentError, "#{where}; the #{scheme} authentication strategy needs it"
+      end
+    end
+  end
+end

data/lib/resteze/authenticator.rb

@@ -0,0 +1,187 @@
+require "resteze/synchronized_state"
+
+module Resteze
+  # The interface through which a client describes how its API
+  # authenticates requests. Resteze ships no credentials and assumes no
+  # scheme: the default does nothing, and `include Resteze` gives each API
+  # module its own MyApi::Authenticator subclass to fill in. One instance
+  # per module, shared by every thread, is reached as MyApi.authenticator.
+  #
+  # The client calls, for every request:
+  #
+  #   connection_options
+  #     When the per-thread Faraday connection is built. Mutual TLS puts
+  #     its certificate here.
+  #   apply(request)
+  #     Before sending. `request` exposes `headers`, `params` and `query`
+  #     to mutate; header and query-parameter schemes add themselves here.
+  #   refresh?(error, attempt)
+  #     After a MyApi::AuthenticationError (401 or 403). Return true to
+  #     send the request once more, for schemes whose credential can be
+  #     renewed; `attempt` counts failures so far, starting at 1.
+  #   sensitive_keys
+  #     When logging at DEBUG, which prints the whole request. The header,
+  #     query and body keys named here are masked in the logged copy.
+  #
+  # A scheme is chosen with `authenticate_with` on the module (or `strategy`
+  # inside this class), by the name a built-in registered through
+  # Strategy.register or by a Strategy subclass; several may be combined.
+  # Each scheme expects its credential in a module setting named by its
+  # DEFAULTS, which an initializer fills through `configure`, and declaring
+  # the scheme declares the setting:
+  #
+  #   module MyApi
+  #     include Resteze
+  #
+  #     authenticate_with :api_key, header: "X-Api-Key"   # expects MyApi.api_key
+  #   end
+  #
+  #   MyApi.configure { |config| config.api_key = ENV["MY_API_KEY"] }
+  #
+  # Any credential option also takes a Symbol naming another setting, a
+  # callable for a credential that comes from somewhere other than
+  # configuration, or a literal value. `MyApi.authenticator.missing_settings`
+  # lists expected settings still nil, for a boot-time check.
+  #
+  # Every scheme is a subclass of Resteze::Authenticator::Strategy: subclass
+  # it, implement `apply`, declare DEFAULTS, and pass the class to
+  # `authenticate_with`.
+  #
+  # State lives in a mutex-guarded hash (`state`, `update_state`,
+  # `synchronize`) shared by the strategies, so a strategy that caches a
+  # credential need not manage threads; `apply` and `refresh?` run under
+  # the lock, which is what keeps concurrent threads from all renewing a
+  # credential at once.
+  class Authenticator
+    include Resteze::ApiModule
+    include Resteze::SynchronizedState
+
+    # What `apply` receives. `headers`, `params` and `query` are the hashes
+    # the request will be sent with; `query` always goes in the query
+    # string, whatever the HTTP method, unlike `params`.
+    Request = Struct.new(:http_method, :path, :headers, :params, :query, keyword_init: true)
+
+    class << self
+      # Adds a built-in strategy (by name) or a custom Strategy class with
+      # its options. Call it more than once to combine schemes. Without
+      # arguments, returns the [class, options] pairs in effect for this
+      # class, inherited from a superclass when it declares none.
+      def strategy(name = nil, **options)
+        return strategy_specs if name.nil? && options.empty?
+        raise ArgumentError, "strategy needs a name or class before its options" if name.nil?
+
+        klass = name.is_a?(Class) ? name : Strategy.lookup(name)
+        declare_settings(klass.settings(options))
+        own_strategy_specs << [klass, options]
+        nil
+      end
+
+      # The module settings every configured strategy reads, in order.
+      def settings
+        strategy_specs.flat_map { |klass, options| klass.settings(options) }.uniq
+      end
+
+      # Those of them the strategies cannot work without.
+      def required_settings
+        strategy_specs.flat_map { |klass, options| klass.required_settings(options) }.uniq
+      end
+
+      # Declares those settings on the API module (`api_key`, `username`,
+      # ...) so an initializer can set them through `configure` with no
+      # `attr_accessor` of its own. Existing accessors are left alone.
+      def declare_settings(names)
+        mod = api_module
+        return if mod.nil? || mod == Resteze
+
+        names.each { |name| mod.singleton_class.attr_accessor(name) unless mod.respond_to?(name) }
+      end
+
+      def strategy_specs
+        own = own_strategy_specs
+        return own unless own.empty?
+
+        superclass.respond_to?(:strategy_specs) ? superclass.strategy_specs : []
+      end
+
+      def strategy_instances
+        strategy_specs.map { |klass, options| klass.new(**options) }
+      end
+
+      private
+
+      def own_strategy_specs
+        @own_strategy_specs ||= []
+      end
+    end
+
+    attr_reader :strategies
+
+    def initialize(strategies: self.class.strategy_instances)
+      initialize_state
+      @strategies = Array(strategies).freeze
+      self.api_module = self.class.api_module
+    end
+
+    # The module this authenticator serves, and whose settings its
+    # strategies read. Set by MyApi.authenticator=.
+    def api_module
+      @api_module || self.class.api_module
+    end
+
+    def api_module=(mod)
+      @api_module = mod
+      strategies.each { |strategy| strategy.api_module = mod if strategy.respond_to?(:api_module=) }
+    end
+
+    # The module settings this instance's strategies read.
+    def settings
+      strategies.flat_map(&:settings).uniq
+    end
+
+    # Those of them the strategies cannot work without (a strategy's
+    # OPTIONAL settings, such as a key passphrase, are left out).
+    def required_settings
+      strategies.flat_map(&:required_settings).uniq
+    end
+
+    # The required settings that are still nil, for checking configuration
+    # at boot:
+    #
+    #   raise "MyApi needs #{MyApi.authenticator.missing_settings.join(', ')}" if MyApi.authenticator.missing_settings.any?
+    def missing_settings
+      required_settings.select { |name| api_module.try(name).nil? }
+    end
+
+    # Faraday connection options merged from every strategy, such as `ssl:`.
+    def connection_options
+      strategies.map(&:connection_options).reduce({}) { |merged, options| merged.deep_merge(options) }
+    end
+
+    # The request keys the strategies put credentials under, merged, for
+    # the client to mask in its debug log.
+    def sensitive_keys
+      strategies.map(&:sensitive_keys).reduce({}) { |merged, keys| merged.merge(keys) { |_, mine, theirs| mine | theirs } }
+    end
+
+    # Lets every strategy add its credential to the request. Returns it.
+    def apply(request)
+      return request if strategies.empty?
+
+      synchronize { |state| strategies.each { |strategy| strategy.apply(request, state) } }
+      request
+    end
+
+    # True when any strategy renewed its credential and wants one retry.
+    def refresh?(error, attempt)
+      return false if strategies.empty?
+
+      synchronize { |state| strategies.any? { |strategy| strategy.refresh?(error, attempt, state) } }
+    end
+  end
+end
+
+require "resteze/authenticator/strategy"
+require "resteze/authenticator/api_key"
+require "resteze/authenticator/basic"
+require "resteze/authenticator/bearer"
+require "resteze/authenticator/mtls"

data/lib/resteze/client.rb

@@ -1,7 +1,13 @@
+require "resteze/authenticating"
+require "resteze/instrumentation"
+require "resteze/rate_limiting"
+
 module Resteze
   class Client
     include Resteze::ApiModule
     prepend Resteze::Instrumentation
+    prepend Resteze::Authenticating
+    prepend Resteze::RateLimiting
 
     def self.user_agent
       [
@@ -30,18 +36,30 @@ module Resteze
       Thread.current["#{client_name}_default_client"] ||= new(default_connection)
     end
 
+    # The Authenticator's connection options (mutual TLS, say) are applied
+    # here; an override of this method must pass them to Faraday itself.
     def self.default_connection
-      Thread.current["#{client_name}_default_connection"] ||= Faraday.new do |conn|
+      Thread.current["#{client_name}_default_connection"] ||= Faraday.new(connection_options) do |conn|
         conn.use Faraday::Request::UrlEncoded
         conn.use api_module::Middleware::RaiseError
         conn.adapter Faraday.default_adapter
       end
     end
 
+    def self.connection_options
+      api_module.try(:authenticator)&.connection_options || {}
+    end
+
     def self.faraday_adapter
       @faraday_adapter ||= default_connection.builder.adapter.name.demodulize.underscore
     end
 
+    REDACTED = "[REDACTED]".freeze
+
+    # Headers masked in the DEBUG log whatever the authenticator declares,
+    # for a credential added through `request_headers` instead.
+    SENSITIVE_HEADERS = %w[Authorization Proxy-Authorization].freeze
+
     # This can be overriden to customize
     def self.api_url(path = "")
       [api_module.api_base.chomp("/".freeze), path].join
@@ -71,12 +89,14 @@ module Resteze
     end
 
     # TODO: Look at refactoring this if possible to improve the Abc size
-    # rubocop:disable Metrics/AbcSize
-    def execute_request(method, path, headers: {}, params: {})
+    # rubocop:disable-next Metrics/AbcSize
+    # `query:` always goes in the query string, whatever the method, where
+    # `params:` becomes the body for anything but GET, HEAD and DELETE.
+    def execute_request(method, path, headers: {}, params: {}, query: {})
       params = util.objects_to_ids(params)
-      body, query_params = process_params(method, params)
+      body, query_params = process_params(method, params, query)
       headers = request_headers.merge(util.normalize_headers(headers))
-      context = request_log_context(body:, method:, path:, query_params:, headers:)
+      context = request_log_context(body: redacted_body(body, params), method:, path:, query_params:, headers:)
 
       http_resp = execute_request_with_rescues(context) do
         connection.run_request(method, api_url(path), body, headers) do |req|
@@ -91,7 +111,6 @@ module Resteze
         @last_response = response
       end
     end
-    # rubocop:enable Metrics/AbcSize
 
     protected
 
@@ -106,7 +125,7 @@ module Resteze
 
     private
 
-    def process_params(method, params)
+    def process_params(method, params, query)
       body = nil
       query_params = nil
       case method.to_s.downcase.to_sym
@@ -115,6 +134,7 @@ module Resteze
       else
         body = params.to_json
       end
+      query_params = (query_params || {}).merge(util.objects_to_ids(query)) if query.present?
       [body, query_params]
     end
 
@@ -122,16 +142,45 @@ module Resteze
       self.class.default_connection.options.params_encoder || Faraday::Utils.default_params_encoder
     end
 
+    # The DEBUG log prints the whole request, so what goes in here is a
+    # copy with the credentials masked; the request itself is untouched.
     def request_log_context(method: nil, path: nil, query_params: nil, headers: nil, body: nil)
       RequestLogContext.new.tap do |context|
         context.method       = method
         context.path         = path
-        context.query_params = params_encoder.encode(query_params)
-        context.headers      = headers
+        context.query_params = params_encoder.encode(redacted(query_params, :query, :params))
+        context.headers      = redacted(headers, :headers)
         context.body         = body
       end
     end
 
+    # Masks the values under the keys the authenticator's strategies put a
+    # credential in (`parts` are :headers, :query and :params), matched
+    # without regard to case. The query string takes :params keys too,
+    # since params become the query string for GET, HEAD and DELETE.
+    # Returns the hash itself when there is nothing to mask.
+    def redacted(hash, *parts)
+      return hash if hash.nil?
+
+      keys = parts.flat_map { |part| sensitive_keys.fetch(part, []) }.map { |key| key.to_s.downcase }
+      return hash if keys.empty?
+
+      hash.to_h { |key, value| [key, keys.include?(key.to_s.downcase) ? REDACTED : value] }
+    end
+
+    # The body for the log: the serialised one as is, rebuilt from the
+    # masked params only when a strategy put a credential in the body.
+    def redacted_body(body, params)
+      return body if body.nil? || sensitive_keys.fetch(:params, []).empty?
+
+      redacted(params, :params).to_json
+    end
+
+    def sensitive_keys
+      keys = api_module.try(:authenticator)&.sensitive_keys || {}
+      keys.merge(headers: SENSITIVE_HEADERS | keys.fetch(:headers, []))
+    end
+
     def execute_request_with_rescues(context)
       begin
         request_start = Time.now
@@ -202,7 +251,7 @@ module Resteze
     end
 
     # TODO: Look into refactoring to improve Abc Size
-    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable-next Metrics/AbcSize
     def response_details_in_http_syntax(response)
       status  = response.respond_to?(:status)  ? response.status  : response[:status]
       body    = response.respond_to?(:body)    ? response.body    : response[:body]
@@ -215,7 +264,6 @@ module Resteze
         s << "\n"
       end
     end
-    # rubocop:enable Metrics/AbcSize
 
     def request_in_http_syntax(context)
       method = context.method.to_s.upcase

data/lib/resteze/errors.rb

@@ -1,8 +1,54 @@
 module Resteze
   class Error < StandardError
+    include Resteze::ApiModule
+
     attr_accessor :response
     attr_reader   :message, :code, :http_body, :http_headers, :http_status, :json_body
 
+    # Faraday-style readers, for code written against the Faraday-derived
+    # ResourceNotFound, ConflictError and UnprocessableEntityError of 0.4.0.
+    alias response_status  http_status
+    alias response_headers http_headers
+    alias response_body    http_body
+
+    # Builds an error from a Faraday error, carrying over its HTTP response.
+    # The Faraday error becomes `cause` when raised from a rescue block.
+    def self.from_faraday(error, message = error.message)
+      build(message, response_attributes(error)).tap { |e| e.response = error.response }
+    end
+
+    # Builds an error from a Resteze::Response, for APIs that report failures
+    # inside a successful HTTP response (see Response.body_error).
+    def self.from_response(response, message = nil)
+      data = response.data
+      attributes = { http_status: response.http_status, http_body: response.http_body,
+                     http_headers: response.http_headers || {},
+                     json_body: (data if data.is_a?(Hash) || data.is_a?(Array)) }
+
+      build(message, attributes).tap { |e| e.response = response }
+    end
+
+    # Types with a different constructor signature override this.
+    def self.build(message, attributes)
+      new(message, **attributes)
+    end
+
+    def self.response_attributes(error)
+      headers = error.response_headers || {}
+      body    = error.response_body
+
+      { http_status: error.response_status, http_body: body, http_headers: headers,
+        json_body: parsed_body(body, status: error.response_status, headers: headers) }
+    end
+
+    def self.parsed_body(body, status:, headers:)
+      data = Resteze::Response.parse_body(body, status:, headers:)
+      data if data.is_a?(Hash) || data.is_a?(Array)
+    rescue StandardError
+      nil
+    end
+    private_class_method :response_attributes, :parsed_body
+
     # def initialize(message = nil, http_status: nil, http_body: nil, json_body: nil,
     #                http_headers: nil, code: nil)
     def initialize(message = nil, **kwargs)
@@ -19,20 +65,95 @@ module Resteze
       status = "HTTP #{@http_status}:" if @http_status.present?
       [status, message].compact.join(" ")
     end
+
+    # Case-insensitive header lookup; http_headers may be a plain Hash or a
+    # Faraday::Utils::Headers.
+    def header(name)
+      RateLimit.header_value(http_headers, name)
+    end
+
+    # Whatever the module's RateLimiter makes of this error (see
+    # Resteze::RateLimiter#rate_limit), or nil.
+    def rate_limit
+      @rate_limit ||= api_module.try(:rate_limiter)&.rate_limit(self)
+    end
   end
 
-  class InvalidRequestError < Error
+  # Behaviour for the error types that add more than a name. Every API module
+  # gets its own subclasses of its own Error (see Errors.define), so type
+  # behaviour lives in modules that each of those subclasses includes.
+  module InvalidRequest
     attr_accessor :param
 
+    module ClassMethods
+      def build(message, attributes)
+        new(message, nil, **attributes)
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
     def initialize(message, param, **keyword_args)
       super(message, **keyword_args)
       @param = param
     end
   end
 
-  class AuthenticationError < Error; end
+  module RateLimited
+    # `retry_after:` sets the wait outright, for errors raised before a
+    # request is sent (see RateLimiter's on_wait: :raise).
+    def initialize(message = nil, retry_after: nil, **keyword_args)
+      super(message, **keyword_args)
+      @retry_after = retry_after
+    end
+
+    # Seconds to wait before retrying: the value given at construction, else
+    # the HTTP Retry-After header, accepting delay-seconds or an HTTP-date;
+    # nil when absent or unparseable. Redefine on MyApi::RateLimitError for
+    # an API that signals the wait some other way.
+    def retry_after
+      @retry_after || retry_after_header
+    end
+
+    private
 
-  class ApiConnectionError < Error; end
+    def retry_after_header
+      value = header("Retry-After")
+      return if value.blank?
+      return Integer(value) if value.to_s.match?(/\A\d+\z/)
+
+      [(Time.httpdate(value.to_s) - Time.now).ceil, 0].max
+    rescue ArgumentError
+      nil
+    end
+  end
+
+  module Errors
+    # Error type name => behaviour module. Resteze and every API module that
+    # includes it define one subclass of their own Error per entry, so
+    # `rescue MyApi::Error` catches every error the client raises and errors
+    # from one API are never caught by rescue clauses written for another.
+    TYPES = {
+      InvalidRequestError: InvalidRequest,
+      AuthenticationError: nil,
+      ApiConnectionError: nil,
+      ApiError: nil,
+      RateLimitError: RateLimited,
+      ResourceNotFound: nil,
+      ConflictError: nil,
+      UnprocessableEntityError: nil
+    }.freeze
+
+    def self.define(namespace, base)
+      TYPES.each do |name, behaviour|
+        next if namespace.const_defined?(name, false)
+
+        namespace.const_set(name, Class.new(base) { include behaviour if behaviour })
+      end
+    end
+  end
 
-  class ApiError < Error; end
+  Errors.define(self, Error)
 end

data/lib/resteze/instrumentation.rb

@@ -7,7 +7,42 @@ module Resteze
         super.tap do |response|
           payload[:status]     = response.http_status
           payload[:request_id] = response.request_id
+          instrument_rate_limit(payload, response)
         end
+      rescue StandardError => e
+        instrument_error_response(payload, e)
+        raise
+      end
+    end
+
+    private
+
+    # The limiter's view of the quota after this exchange, when it has one,
+    # so subscribers can gauge remaining calls from the events they already
+    # receive.
+    def instrument_rate_limit(payload, response_or_error)
+      return unless response_or_error.respond_to?(:rate_limit)
+
+      view = response_or_error.rate_limit
+      payload[:rate_limit] = view.to_h if !view.nil? && view.respond_to?(:to_h)
+    end
+
+    # An error raised by the middleware stack usually carries the HTTP response
+    # that produced it. Surface its status and request id the same way a
+    # successful response would, so subscribers can bucket by status code.
+    def instrument_error_response(payload, error)
+      instrument_rate_limit(payload, error)
+      status, headers = error_response_details(error)
+      return if status.nil?
+
+      payload[:status]     = status
+      payload[:request_id] = headers&.[]("Request-Id")
+    end
+
+    def error_response_details(error)
+      case error
+      when Faraday::Error then [error.response_status, error.response_headers]
+      when Resteze::Error then [error.http_status, error.http_headers]
       end
     end
   end

data/lib/resteze/list.rb

@@ -28,7 +28,7 @@ module Resteze
       end
 
       def list_resource_path(_params = {})
-        resource_path
+        action_for(:list).path_for
       end
 
       def list_key
@@ -36,7 +36,7 @@ module Resteze
       end
 
       def list_method
-        :get
+        action_for(:list).http_method
       end
     end
   end