resteze 0.4.0 → 1.0.0

data/lib/resteze/action.rb

@@ -0,0 +1,99 @@
+module Resteze
+  # A resolved action on a resource class: the HTTP method, route and return
+  # type for one named operation such as :retrieve or :track.
+  class Action
+    OPTIONS   = %i[method on path id id_param returns as].freeze
+    RESERVED  = %i[retrieve list create update].freeze
+    ON_VALUES = %i[collection member].freeze
+    ID_VALUES = %i[path param].freeze
+    BUILT_IN = {
+      retrieve: { method: :get, on: :member, path: nil, id: :path },
+      list: { method: :get, on: :collection, path: nil },
+      create: { method: :post, on: :collection, path: nil },
+      update: { method: :put, on: :member, path: nil, id: :path }
+    }.freeze
+
+    attr_reader :name, :owner, :on, :path, :id, :returns, :as
+
+    # Declaration-time checks shared by the resource DSL and the module-level
+    # DSL: option keys, enumerated values, and the fixed scope of built-ins.
+    def self.validate_options!(name, options, allowed: OPTIONS)
+      unknown = options.keys - allowed
+      raise ArgumentError, "Unknown action option(s): #{unknown.join(', ')}" if unknown.any?
+
+      validate_option_value!(name, options, :on, ON_VALUES)
+      validate_option_value!(name, options, :id, ID_VALUES)
+      return unless RESERVED.include?(name) && options.key?(:on)
+
+      raise ArgumentError, "on: cannot be changed for the built-in action :#{name}"
+    end
+
+    def self.validate_option_value!(name, options, key, values)
+      return unless options.key?(key) && !values.include?(options[key])
+
+      raise ArgumentError, "#{key}: must be one of #{values.inspect} (action :#{name})"
+    end
+
+    def initialize(name, owner, options = {})
+      @name    = name.to_sym
+      @owner   = owner
+      @options = options.slice(*OPTIONS)
+      @on      = @options[:on] || BUILT_IN.dig(@name, :on) || :collection
+      @options = @options.except(:id, :id_param) if collection?
+      @path    = @options.fetch(:path) { reserved? ? nil : @name.to_s }
+      @id      = member? ? @options.fetch(:id, :path) : nil
+      @returns = @options[:returns]
+      @as      = @options[:as]
+    end
+
+    def reserved?
+      RESERVED.include?(name)
+    end
+
+    # True when a built-in action still has its 0.4.0 REST route, so callers
+    # can keep honoring an instance-level resource_path override.
+    def rest_default?
+      reserved? && path.nil? && (collection? || id == :path)
+    end
+
+    def member?
+      on == :member
+    end
+
+    def collection?
+      !member?
+    end
+
+    def generated_name
+      (as || name).to_sym
+    end
+
+    def http_method
+      @options[:method] or raise ArgumentError,
+                                 "Action :#{name} on #{owner} has no HTTP method; " \
+                                 "declare it with method: on the resource or at module level"
+    end
+
+    def id_param
+      @options[:id_param] ||
+        (owner.id_param if owner.respond_to?(:id_param)) ||
+        owner.api_module.default_id_param(owner)
+    end
+
+    def path_segments
+      path.to_s.split("/").reject(&:blank?).map { |part| CGI.escape(part) }
+    end
+
+    def path_for(id = nil)
+      base = member? && self.id == :path ? owner.resource_path(id) : owner.resource_path
+      [base, *path_segments].join("/").squeeze("/")
+    end
+
+    def to_h
+      {
+        name:, method: @options[:method], on:, path:, id:,
+        id_param: (id_param if member?), returns:, as: generated_name
+      }
+    end
+  end
+end

data/lib/resteze/actions/validation.rb

@@ -0,0 +1,56 @@
+module Resteze
+  module Actions
+    # Declaration-time checks for the action DSL. The declaration is resolved
+    # through the lookup chain (without being stored) so scope and generated
+    # name reflect inherited and module-level options, not just the options
+    # given on this line.
+    module Validation
+      private
+
+      # Returns the resolved candidate action, or raises ArgumentError.
+      def validate_action!(name, options)
+        Resteze::Action.validate_options!(name, options)
+        candidate = resolve_action(name, options)
+        validate_id_options!(candidate, options)
+        validate_returns!(candidate, options)
+        check_action_collision!(candidate) unless candidate.reserved?
+        candidate
+      end
+
+      def validate_id_options!(candidate, options)
+        return unless candidate.collection?
+        return unless options.key?(:id) || options.key?(:id_param)
+
+        raise ArgumentError, "id: and id_param: only apply to member actions (action :#{candidate.name})"
+      end
+
+      def validate_returns!(candidate, options)
+        return unless options[:returns] == :list && !(self <= Resteze::List)
+
+        raise ArgumentError, "returns: :list requires #{self} to include List (action :#{candidate.name})"
+      end
+
+      def check_action_collision!(candidate)
+        method_name = candidate.generated_name
+        return if inherited_action_method?(candidate)
+
+        clash = respond_to?(method_name, true) ||
+                (candidate.member? && (method_defined?(method_name) || private_method_defined?(method_name)))
+        return unless clash
+
+        raise ArgumentError, "action :#{candidate.name} would define #{self}.#{method_name}, which already exists; " \
+                             "pass as: to choose another method name"
+      end
+
+      # True when the method this declaration would define is the one an
+      # ancestor's declaration of the same action already generated, so
+      # redefining it is an override, not a collision.
+      def inherited_action_method?(candidate)
+        action_ancestors.drop(1).any? do |klass|
+          klass.declared_actions.key?(candidate.name) &&
+            klass.actions[candidate.name].generated_name == candidate.generated_name
+        end
+      end
+    end
+  end
+end

data/lib/resteze/actions.rb

@@ -0,0 +1,117 @@
+module Resteze
+  # The action routing DSL for resources. Each class stores only its own
+  # declarations; resolution walks the chain lazily on every lookup:
+  # REST built-ins, module action_defaults, module declarations, ancestor
+  # classes (farthest first), then this class.
+  module Actions
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      include Resteze::Actions::Validation
+
+      def action(name, **options)
+        name = name.to_sym
+        candidate = validate_action!(name, options)
+        declared_actions[name] = options
+        define_action_methods(candidate) unless candidate.reserved?
+        nil
+      end
+
+      def declared_actions
+        @declared_actions ||= {}
+      end
+
+      def actions
+        action_names.to_h { |name| [name, resolve_action(name)] }.freeze
+      end
+
+      # Resolves one action by name. The built-ins and generated methods go
+      # through this rather than #actions, so a consumer who already defines
+      # a class method named `actions` is unaffected.
+      def action_for(name)
+        name = name.to_sym
+        raise KeyError, "#{self} has no action :#{name}" unless action_names.include?(name)
+
+        resolve_action(name)
+      end
+
+      # Override to transform params before an action request is sent.
+      def action_params(_name, params)
+        params
+      end
+
+      # Override to supply headers for an action request.
+      def action_headers(_name, _params)
+        {}
+      end
+
+      def invoke_action(name, params = {}, id: nil)
+        action = action_for(name)
+        raise_invalid_action_id!(id) if action.member? && id.blank?
+
+        params = action_params(name, params)
+        params = { action.id_param => id }.merge(params) if action.member? && action.id == :param
+        response = request(action.http_method, action.path_for(id), params:, headers: action_headers(name, params))
+        build_action_result(action, response)
+      end
+
+      private
+
+      def action_names
+        (Resteze::Action::RESERVED + action_ancestors.flat_map { |klass| klass.declared_actions.keys }).uniq
+      end
+
+      # Classes in the ancestry that hold declarations, nearest first.
+      def action_ancestors
+        ancestors.select { |ancestor| ancestor.is_a?(Class) && ancestor.respond_to?(:declared_actions) }
+      end
+
+      # Resolves one action through the full chain. `own` stands in for this
+      # class's stored declaration, so a declaration can be resolved before it
+      # is stored.
+      def resolve_action(name, own = declared_actions.fetch(name, {}))
+        options = Resteze::Action::BUILT_IN.fetch(name, {}).merge(api_module.action_defaults)
+        options.merge!(api_module.action_declarations.fetch(name, {}))
+        action_ancestors.drop(1).reverse_each { |klass| options.merge!(klass.declared_actions.fetch(name, {})) }
+        Resteze::Action.new(name, self, options.merge(own))
+      end
+
+      def raise_invalid_action_id!(id)
+        raise api_module::InvalidRequestError.new(
+          "Could not determine which PATH to request: #{self} instance has invalid ID: #{id.inspect}", "id"
+        )
+      end
+
+      def build_action_result(action, response)
+        case action.returns
+        when nil   then api_module::Result.from_response(response)
+        when :self then convert_action_data(response.data, self)
+        when :list then construct_list_from(response.data)
+        when Class then convert_action_data(response.data, action.returns)
+        else raise ArgumentError, "Unsupported returns: #{action.returns.inspect} (action :#{action.name})"
+        end
+      end
+
+      # A Hash is an envelope (object_key is unwrapped, as in #refresh); an
+      # Array holds bare items (each is wrapped, as in ListObject).
+      def convert_action_data(data, klass)
+        case data
+        when Hash  then klass.construct_from(data)
+        when Array then util.convert_to_object(data, klass)
+        else data
+        end
+      end
+
+      def define_action_methods(action)
+        name = action.name
+        method_name = action.generated_name
+        if action.member?
+          define_method(method_name) { |**params| self.class.invoke_action(name, params, id:) }
+          define_singleton_method(method_name) { |id, **params| new(id).public_send(method_name, **params) }
+        else
+          define_singleton_method(method_name) { |**params| invoke_action(name, params) }
+        end
+      end
+    end
+  end
+end

data/lib/resteze/api_module.rb

@@ -6,11 +6,17 @@ module Resteze
 
     module ClassMethods
       def api_module
-        @api_module ||=
-          begin
-            parents = name.scan("::").inject([name]) { |mods, _n| mods << mods.last.deconstantize }
-            parents.map(&:constantize).detect { |mod| mod == Resteze || mod.include?(Resteze) }
-          end
+        @api_module ||= name.nil? ? inherited_api_module : named_api_module
+      end
+
+      # An anonymous subclass belongs where its parent does.
+      def inherited_api_module
+        superclass.api_module if respond_to?(:superclass) && superclass.respond_to?(:api_module)
+      end
+
+      def named_api_module
+        parents = name.scan("::").inject([name]) { |mods, _n| mods << mods.last.deconstantize }
+        parents.map(&:constantize).detect { |mod| mod == Resteze || mod.include?(Resteze) }
       end
 
       def logger

data/lib/resteze/api_resource.rb

@@ -2,6 +2,7 @@ module Resteze
   module ApiResource
     extend ActiveSupport::Concern
     include Resteze::Request
+    include Resteze::Actions
 
     def initialize(id = nil, values: {})
       super(values)
@@ -18,12 +19,30 @@ module Resteze
       self.class.resource_path(id)
     end
 
+    # The path #refresh requests: the routed :retrieve action. Unlike
+    # #resource_path, this follows re-routing (e.g. /campaigns/details). While
+    # :retrieve keeps its REST default, an instance-level resource_path
+    # override is honored exactly as in 0.4.0.
+    def retrieve_resource_path
+      return resource_path if retrieve_action.rest_default?
+
+      unless id.present?
+        raise api_module::InvalidRequestError.new("Could not determine which PATH to request: #{self.class} instance has " \
+                                                  "invalid ID: #{id.inspect}", "id")
+      end
+
+      retrieve_action.path_for(id)
+    end
+
     def retrieve_method
-      :get
+      retrieve_action.http_method
     end
 
     def retrieve_params
-      @retrieve_params || {}
+      params = @retrieve_params || {}
+      return params unless retrieve_action.id == :param
+
+      { retrieve_action.id_param => id }.merge(params)
     end
 
     def retrieve_headers
@@ -33,7 +52,7 @@ module Resteze
     def refresh
       resp = request(
         retrieve_method,
-        resource_path,
+        retrieve_resource_path,
         params: retrieve_params,
         headers: retrieve_headers
       )
@@ -66,5 +85,11 @@ module Resteze
         new(id).refresh
       end
     end
+
+    private
+
+    def retrieve_action
+      self.class.action_for(:retrieve)
+    end
   end
 end

data/lib/resteze/authenticating.rb

@@ -0,0 +1,28 @@
+module Resteze
+  # Drives the API module's Authenticator through the request lifecycle
+  # (see Resteze::Authenticator). Prepended on Client inside RateLimiting
+  # and outside Instrumentation, so a retry with a renewed credential is
+  # one attempt to the limiter and two events to instrumentation.
+  module Authenticating
+    def execute_request(method, path, **options)
+      authenticator = api_module.authenticator
+      attempt = 0
+      begin
+        request = Authenticator::Request.new(http_method: method, path:, **mutable_copies(options))
+        authenticator.apply(request)
+        super(method, path, **options, headers: request.headers, params: request.params, query: request.query)
+      rescue api_module::AuthenticationError => e
+        raise unless authenticator.refresh?(e, attempt += 1)
+
+        retry
+      end
+    end
+
+    private
+
+    # The strategies get copies to add to, so the caller's hashes survive.
+    def mutable_copies(options)
+      %i[headers params query].to_h { |key| [key, options.fetch(key, {}).dup] }
+    end
+  end
+end

data/lib/resteze/authenticator/api_key.rb

@@ -0,0 +1,45 @@
+module Resteze
+  class Authenticator
+    # An API key sent in a header (default X-Api-Key) or, with `query:`, as
+    # a query-string parameter on every request regardless of HTTP method.
+    # The key is `MyApi.api_key` unless `value:` names another setting.
+    #
+    #   authenticate_with :api_key                           # X-Api-Key: <MyApi.api_key>
+    #   authenticate_with :api_key, header: "X-Partner-Key", value: :partner_key
+    #   authenticate_with :api_key, query: "api_key"
+    #   authenticate_with :api_key, header: "Authorization", value: -> { "Token #{MyApi.api_key}" }
+    class ApiKey < Strategy
+      DEFAULTS = { value: :api_key }.freeze
+
+      attr_reader :header, :query
+
+      def initialize(value: DEFAULTS[:value], header: nil, query: nil)
+        super()
+        raise ArgumentError, "api_key takes header: or query:, not both" if header && query
+
+        @value  = required!(:value, value)
+        @query  = query
+        @header = query ? nil : (header || "X-Api-Key")
+      end
+
+      def credential_options
+        { value: @value }
+      end
+
+      def sensitive_keys
+        query ? { query: [query] } : { headers: [header] }
+      end
+
+      def apply(request, _state)
+        key = resolve!(:value, @value).to_s
+        if query
+          request.query[query] = key
+        else
+          request.headers[header] = key
+        end
+      end
+
+      Strategy.register(:api_key, self)
+    end
+  end
+end

data/lib/resteze/authenticator/basic.rb

@@ -0,0 +1,40 @@
+module Resteze
+  class Authenticator
+    # HTTP Basic: an Authorization header carrying the base64 of
+    # "username:password", read from `MyApi.username` and `MyApi.password`
+    # unless told otherwise.
+    #
+    #   authenticate_with :basic
+    #   authenticate_with :basic, username: :api_user, password: :api_secret
+    class Basic < Strategy
+      DEFAULTS = { username: :username, password: :password }.freeze
+
+      def initialize(username: DEFAULTS[:username], password: DEFAULTS[:password])
+        super()
+        @username = required!(:username, username)
+        @password = required!(:password, password)
+      end
+
+      def credential_options
+        { username: @username, password: @password }
+      end
+
+      def sensitive_keys
+        { headers: ["Authorization"] }
+      end
+
+      # A username cannot contain a colon (RFC 7617): the server splits on
+      # the first one, so "acme:ops" would log in as "acme" and fail with a
+      # bare 401. Better to say so here.
+      def apply(request, _state)
+        username = resolve!(:username, @username).to_s
+        raise ArgumentError, "the basic authentication username #{username.inspect} contains ':'" if username.include?(":")
+
+        credentials = "#{username}:#{resolve!(:password, @password)}"
+        request.headers["Authorization"] = "Basic #{[credentials].pack('m0')}"
+      end
+
+      Strategy.register(:basic, self)
+    end
+  end
+end

data/lib/resteze/authenticator/bearer.rb

@@ -0,0 +1,37 @@
+module Resteze
+  class Authenticator
+    # A token in the Authorization header, "Bearer <token>" by default,
+    # read from `MyApi.api_key` unless `token:` names another setting. Use
+    # `scheme:` for APIs that want another prefix, such as "Token". A token
+    # the application obtained some other way fits here through a callable.
+    #
+    #   authenticate_with :bearer                                   # Bearer <MyApi.api_key>
+    #   authenticate_with :bearer, token: :access_token, scheme: "Token"
+    #   authenticate_with :bearer, token: -> { TokenStore.current }
+    class Bearer < Strategy
+      DEFAULTS = { token: :api_key }.freeze
+
+      attr_reader :scheme
+
+      def initialize(token: DEFAULTS[:token], scheme: "Bearer")
+        super()
+        @token  = required!(:token, token)
+        @scheme = required!(:scheme, scheme)
+      end
+
+      def credential_options
+        { token: @token }
+      end
+
+      def sensitive_keys
+        { headers: ["Authorization"] }
+      end
+
+      def apply(request, _state)
+        request.headers["Authorization"] = "#{scheme} #{resolve!(:token, @token)}"
+      end
+
+      Strategy.register(:bearer, self)
+    end
+  end
+end

data/lib/resteze/authenticator/mtls.rb

@@ -0,0 +1,73 @@
+require "openssl"
+
+module Resteze
+  class Authenticator
+    # Mutual TLS: the client presents a certificate when the connection is
+    # made. The certificate and key are `MyApi.client_cert` and
+    # `MyApi.client_key` unless told otherwise, each a PEM string or a path
+    # to a PEM file; `MyApi.client_key_passphrase` decrypts an encrypted
+    # key and `MyApi.ca_file` names a CA bundle that verifies the server
+    # when the system store is not enough. Both are optional. Paths are
+    # read as given when the connection is first built, so a relative one
+    # resolves against the process's working directory at that moment; use
+    # absolute paths (Rails.root.join, File.expand_path) or supply PEM
+    # text. Nothing is added to requests; the credential lives in the
+    # connection, so a client that overrides `default_connection` must
+    # pass `connection_options` to Faraday itself.
+    #
+    # `verify: false` turns server verification off, which defeats the
+    # trust mutual TLS is for; it is logged every time the connection is
+    # built so it does not survive from a development initializer unseen.
+    #
+    #   authenticate_with :mtls                      # MyApi.client_cert and MyApi.client_key
+    #   authenticate_with :mtls, cert: Rails.root.join("config/certs/client.pem"),
+    #                            key:  Rails.root.join("config/certs/client-key.pem")
+    class Mtls < Strategy
+      DEFAULTS = { cert: :client_cert, key: :client_key, passphrase: :client_key_passphrase, ca_file: :ca_file }.freeze
+      OPTIONAL = %i[passphrase ca_file].freeze
+
+      def initialize(cert: DEFAULTS[:cert], key: DEFAULTS[:key], passphrase: DEFAULTS[:passphrase],
+                     ca_file: DEFAULTS[:ca_file], verify: true)
+        super()
+        @cert       = required!(:cert, cert)
+        @key        = required!(:key, key)
+        @passphrase = passphrase
+        @ca_file    = ca_file
+        @verify     = verify
+      end
+
+      def credential_options
+        { cert: @cert, key: @key, passphrase: @passphrase, ca_file: @ca_file }
+      end
+
+      def connection_options
+        warn_unverified unless @verify
+
+        { ssl: { client_cert: certificate, client_key: private_key, ca_file: resolve(@ca_file), verify: @verify }.compact }
+      end
+
+      def certificate
+        OpenSSL::X509::Certificate.new(pem(resolve!(:cert, @cert)))
+      end
+
+      def private_key
+        OpenSSL::PKey.read(pem(resolve!(:key, @key)), resolve(@passphrase))
+      end
+
+      Strategy.register(:mtls, self)
+
+      private
+
+      def pem(value)
+        value = value.to_s
+        value.include?("-----BEGIN") ? value : File.read(value)
+      end
+
+      def warn_unverified
+        message = "#{api_module || 'This API'} uses mTLS with verify: false, so the server's certificate is not checked"
+        logger  = api_module.try(:logger)
+        logger ? logger.warn(message) : warn(message)
+      end
+    end
+  end
+end