evil-client 0.3.3 → 1.0.0

data/lib/evil/client/resolver/response.rb

@@ -0,0 +1,26 @@
+class Evil::Client
+  #
+  # Resolves rack-compatible response from schema for given settings
+  # @private
+  #
+  class Resolver::Response < Resolver
+    private
+
+    def initialize(schema, settings, response)
+      @__response__ = Array response
+      super schema, settings, :responses, @__response__.first.to_i
+    end
+
+    def __call__
+      super do
+        __check_status__
+        instance_exec(*@__response__, &__blocks__.last)
+      end
+    end
+
+    def __check_status__
+      return if __blocks__.any?
+      raise ResponseError.new(@__schema__, @__settings__, @__response__)
+    end
+  end
+end

data/lib/evil/client/resolver/security.rb

@@ -0,0 +1,113 @@
+class Evil::Client
+  #
+  # Resolves security definitions from operation settings and schema.
+  # Defines helpers for different methods of the authentication.
+  # @private
+  #
+  class Resolver::Security < Resolver
+    # DSL method to provide basic authentication schema
+    # by user name and password
+    #
+    # It provides base64-encoded "user:password" token and adds it
+    # to the "Authorization" header with a "Basic" prefix.
+    #
+    # @example
+    #   operation do
+    #     option :user
+    #     option :password
+    #
+    #     security { basic_auth user, password }
+    #   end
+    #
+    # @param [#to_s] user User name
+    # @param [#to_s] password Password
+    # @return [Hash<:headers, Hash<Symbol, String>>]
+    #
+    def basic_auth(user, password)
+      token = Base64.encode64("#{user}:#{password}").delete("\n")
+      token_auth(token, prefix: "Basic")
+    end
+
+    # DSL method to provide token-based authentication schema
+    #
+    # It places the token under either standard "Authorization" header,
+    # or standard "access_token" parameter of body or query.
+    # If you need custom key use [#key_auth] schema instead.
+    #
+    # @example
+    #   operation do
+    #     option :token
+    #     security { token_auth token, prefix: "Bearer" }
+    #   end
+    #
+    # @param  [#to_s] token User secret token
+    # @option [#to_s, nil] :prefix The standard prefix to be added before token
+    # @option [:headers, :query] :inside (:headers)
+    #   The part of the request for the token
+    # @return [Hash<Symbol, Hash<Symbol, String>>]
+    #
+    def token_auth(token, inside: :headers, prefix: nil)
+      if inside == :headers
+        prefixed_token = [prefix&.to_s&.capitalize, token].compact.join(" ")
+        key_auth("Authorization", prefixed_token, inside: :headers)
+      else
+        key_auth("access_token", token, inside: inside)
+      end
+    end
+
+    # DSL method to provide the key-based authentication schema
+    #
+    # @example
+    #   operation do
+    #     option :key
+    #     security { key_auth "Authorize", key }
+    #   end
+    #
+    # @param [#to_s] key   Name of the parameter
+    # @param [#to_s] value Value of the parameter
+    # @option [:headers, :query] :inside (:headers)
+    #   The part of the request for the key-value pair
+    # @return [Hash<Symbol, Hash<Symbol, String>>]
+    #
+    def key_auth(key, value, inside: :headers)
+      { inside => { key.to_s => value.to_s } }
+    end
+
+    private
+
+    def initialize(schema, settings)
+      super schema, settings, :security
+    end
+
+    def __call__
+      super do
+        value = __blocks__.any? ? Hash(instance_exec(&__blocks__.last)) : {}
+        raise __wrong_format_error__(value) unless value.is_a? Hash
+
+        __symbolize_keys__(value).tap do |val|
+          __check_format__(val)
+          __check_values__(val)
+        end
+      end
+    end
+
+    def __check_format__(value)
+      data = value.keys - %i[headers query]
+      return if data.empty?
+
+      raise __definition_error__ "#{value.inspect} is not a hash"
+    end
+
+    def __check_values__(value)
+      data = value.reject { |_, val| val.is_a? Hash }
+      return if data.empty?
+
+      message = "inacceptable parts :#{data} of the request"
+      raise __definition_error__(message)
+    end
+
+    def __wrong_value_error__(data)
+      __definition_error__ "inacceptable security settings #{data}"
+    end
+  end
+end

data/lib/evil/client/resolver/uri.rb

@@ -0,0 +1,35 @@
+class Evil::Client
+  #
+  # Resolves request URI from operation settings and schema
+  # @private
+  #
+  class Resolver::Uri < Resolver
+    private
+
+    def initialize(schema, settings)
+      super schema, settings, :path
+    end
+
+    def __call__
+      super do
+        parts = __blocks__.map { |block| instance_exec(&block)&.to_s }
+        path  = File.join(parts)
+        __uri__(path).tap { |uri| __check__(uri) }
+      end
+    end
+
+    def __uri__(path)
+      URI path
+    rescue => error
+      raise __definition_error__(error.message)
+    end
+
+    def __check__(uri)
+      scheme = uri.scheme
+      details = "base url should be defined" unless scheme
+      details ||= "base url should use HTTP(S). '#{scheme}' used instead"
+
+      raise __definition_error__(details) unless scheme&.match(/^https?$/)
+    end
+  end
+end

data/lib/evil/client/rspec.rb

@@ -0,0 +1,127 @@
+#
+# Checks that an operation has been performed with given options
+#
+# @example
+#   subject do
+#     MyClient.new(token: "foo").users(version: 3).fetch(token: "bar", id: 42)
+#   end
+#
+#   # call only matcher
+#   expect { subject }.to perform_operation("MyClient.users.fetch")
+#
+#   # exact matcher
+#   expect { subject }
+#     .to perform_operation("MyClient.users.fetch")
+#     .with_exactly(token: "bar", version: 3, id: 42)
+#
+#   # partial matcher
+#   expect { subject }
+#     .to perform_operation("MyClient.users.fetch")
+#     .with(token: "bar", version: 3)
+#
+#   # absence matcher
+#   expect { subject }
+#     .to perform_operation("MyClient.users.fetch")
+#     .without(:user, :password)
+#
+#   # block syntax
+#   expect { subject }
+#     .to perform_operation("MyClient.users.fetch")
+#     .with { |token:, **| expect(token).to eq "bar" }
+#
+# @param [String] name The full name of the operation
+#
+RSpec::Matchers.define :perform_operation do |name|
+  supports_block_expectations
+
+  description { "perform operation #{name} " }
+
+  chain :with do |**options|
+    @some_options = options
+  end
+
+  chain :with_exactly do |**options|
+    @exact_options = options
+  end
+
+  chain :without do |*options|
+    @no_options = options.flatten.map(&:to_sym)
+  end
+
+  def full_signature(name)
+    name.dup.tap do |text|
+      text << " with options #{@exact_options}"              if @exact_options
+      text << " with options including #{@some_options}"     if @some_options
+      text << " without options :#{@no_options.join(', :')}" if @no_options
+    end
+  end
+
+  # rubocop: disable Metrics/CyclomaticComplexity
+  # rubocop: disable Style/InverseMethods
+  def expected_options?(options, check)
+    return if @exact_options && options != @exact_options
+    return if @some_options  && !(options >= @some_options)
+    return if (options.keys & @no_options.to_a).any?
+    check.nil? || check.call(options)
+  end
+  # rubocop: enable Metrics/CyclomaticComplexity
+  # rubocop: enable Style/InverseMethods
+
+  def stub_resolver
+    resolver = Evil::Client::Resolver::Request
+
+    allow(resolver).to receive(:call) do |schema, settings|
+      register(schema, settings)
+      resolver.new(schema, settings).send(:__call__)
+    end
+  end
+
+  def actual_operations
+    @actual_operations ||= []
+  end
+
+  def register(schema, settings)
+    actual_operations << [schema.to_s, settings.options]
+  end
+
+  def performed(name, check)
+    @performed ||= actual_operations.find do |(key, options)|
+      (key == name) && expected_options?(options, check)
+    end
+  end
+
+  match do |block|
+    stub_resolver
+    block.call
+    !performed(name, block_arg).nil?
+  end
+
+  match_when_negated do |block|
+    stub_resolver
+    block.call
+    performed(name, block_arg).nil?
+  end
+
+  def describe_expectations(name, perform)
+    "It was expected the operation #{full_signature(name)}" \
+    " #{'NOT ' unless perform}to be performed.\n" \
+    "The following operations has been actually performed:"
+  end
+
+  failure_message do
+    text = describe_expectations(name, true)
+    actual_operations.each.with_index(1) do |(key, opts), index|
+      text << format("\n   %02d) #{key} with #{opts}", index)
+    end
+    text
+  end
+
+  failure_message_when_negated do
+    text = describe_expectations(name, false)
+    actual_operations.each.with_index(1) do |(key, opts), index|
+      marker = performed(name, block_arg) == [key, opts] ? "->" : "  "
+      text << format("\n#{marker} % 2d) #{key} with #{opts}", index)
+    end
+    text
+  end
+end

data/lib/evil/client/schema.rb

@@ -0,0 +1,105 @@
+class Evil::Client
+  #
+  # @abstract
+  # Base class for mutable containers of client-specific definitions
+  # of nested scopes and operations along with a corresponding [#settings] class
+  # subclassing [Evil::Client::Settings]
+  #
+  # Every concrete container defines its only DSL for scope/operation
+  # definitions.
+  #
+  class Schema
+    # Loads concrete implementations of the abstract schema
+    require_relative "schema/operation"
+    require_relative "schema/scope"
+
+    # The name of current schema which is unique for the existing [#parent],
+    # or equals to client class name without any [#parent] (root scope name).
+    #
+    # @return [String]
+    #
+    attr_reader :name
+
+    # Scope schema the operation belongs to
+    #
+    # Only the root schema has no parents.
+    # Its definitions are shared by all operations
+    #
+    # @return [Evil::Client::Schema::Scope, nil]
+    #
+    attr_reader :parent
+
+    # Back reference to client the schema belongs to
+    #
+    # @return [Evil::Client]
+    #
+    attr_reader :client # TODO: add spec
+
+    # The human-friendly representation of the schema
+    #
+    # @example
+    #   "MyClient.users.fetch" # custom operation's schema
+    #
+    # @return [String]
+    #
+    def to_s
+      [parent, name].compact.join(".")
+    end
+    alias_method :to_str,  :to_s
+    alias_method :inspect, :to_s
+
+    # The settings class inherited from the [#parent]'s one
+    #
+    # @return [Class]
+    #
+    def settings
+      @settings ||= Class.new(parent&.settings || Settings).tap do |klass|
+        klass.send(:instance_variable_set, :@schema, self)
+      end
+    end
+
+    # Adds an option to the [#settings] class
+    #
+    # @param  (see Evil::Client::Settings.option)
+    # @option (see Evil::Client::Settings.option)
+    # @return [self]
+    #
+    def option(key, type = nil, **opts)
+      settings.option(key, type, **opts)
+      self
+    end
+
+    # Adds a memoized method to the [#settings] class
+    #
+    # @param  (see Evil::Client::Settings.let)
+    # @return [self]
+    #
+    def let(key, &block)
+      settings.let(key, &block)
+      self
+    end
+
+    # Adds validator to the [#settings] class
+    #
+    # @param  (see Evil::Client::Settings.validate)
+    # @return [self]
+    #
+    def validate(key, &block)
+      settings.validate(key, &block)
+      self
+    end
+
+    private
+
+    def initialize(parent, name = nil)
+      if parent.is_a? self.class
+        @parent = parent
+        @client = parent&.client
+        @name   = name
+      else
+        @client = parent
+        @name   = parent.name
+      end
+    end
+  end
+end

data/lib/evil/client/schema/operation.rb

@@ -0,0 +1,177 @@
+class Evil::Client
+  #
+  # Mutable container of operation definitions
+  # with DSL to configure both settings and parts of request/response.
+  #
+  class Schema::Operation < Schema
+    # Tells that this is a schema for end route (operation)
+    #
+    # @return [true]
+    #
+    def leaf?
+      true
+    end
+
+    # Definitions for the current operation
+    #
+    # @return [Hash<Symbol, [Proc, Hash<Integer, Proc>]>]
+    #
+    def definitions
+      @definitions ||= { responses: {} }
+    end
+
+    # Adds path definition to the schema
+    #
+    # Root path should be a valid URL for HTTP(S) protocol
+    #
+    # @param  [#to_s, nil] value
+    # @param  [Proc] block
+    # @return [self]
+    #
+    def path(value = nil, &block)
+      __define__(:path, value, block)
+    end
+
+    # Adds http method definition to the schema
+    #
+    # @see https://tools.ietf.org/html/rfc7231#section-4
+    # @see https://tools.ietf.org/html/rfc5789#section-2
+    #
+    # @param  [#to_s, nil] value Acceptable http_method
+    # @param  [Proc] block
+    # @return [self]
+    #
+    def http_method(value = nil, &block)
+      __define__(:http_method, value, block)
+    end
+
+    # Adds format for request body
+    #
+    # @param  [:json, :form, :text, :multipart, nil] value (:json)
+    # @param  [Proc] block
+    # @return [self]
+    #
+    def format(value = nil, &block)
+      __define__(:format, value, block)
+    end
+
+    # Adds security definition to the schema
+    #
+    # The definition should be nested hash with a root keys :headers, or :query.
+    #
+    # @example
+    #   security { { headers: { "idempotent-token" => "foobar" } } }
+    #
+    # Inside the block we provide several helpers for standard authentication
+    # schemas, namely `basic_auth`, `token_auth`, and `key_auth`. Those are
+    # preferred ways to define a security schema:
+    #
+    # @example
+    #   security { token_auth token, prefix: "Bearer" }
+    #
+    # @param  [Hash<[:headers, :query], Hash>, nil]
+    # @param  [Proc] block
+    # @return [self]
+    #
+    def security(value = nil, &block)
+      __define__(:security, value, block)
+    end
+
+    # Adds request headers definition to the schema
+    #
+    # Headers should be hash of header-value pairs.
+    # Values should be either stringified values or array of stringified values.
+    #
+    # Nested definition will be merged to the root one(s),
+    # so that you can add headers step-by-step from root of the client
+    # to its scopes and operations.
+    #
+    # To reset previous settings you can either set all headers to `nil`,
+    # or assign nil to custom headers. All headers with empty values
+    # will be ignored.
+    #
+    # @param  [Hash<#to_s, [#to_s, Array<#to_s>]>, nil] value
+    # @param  [Proc] block
+    # @return [self]
+    #
+    def headers(value = nil, &block)
+      __define__(:headers, value, block)
+    end
+
+    # Adds query definition to the schema
+    #
+    # Query should be a nested hash.
+    # Wnen subscope or operation reloads previously defined query,
+    # new definition are merged deeply to older one. You can populate
+    # a query step-by-step from client root to an operation.
+    #
+    # @param  [Hash, nil] value
+    # @param  [Proc] block
+    # @return [self]
+    #
+    def query(value = nil, &block)
+      __define__(:query, value, block)
+    end
+
+    # Adds body definition to the schema
+    #
+    # It is expected the body to correspond to [#format].
+    #
+    # When a format is :json,      the body should be convertable to json
+    # When a format is :text,      the body should be stringified
+    # When a format is :form,      the body should be a hash
+    # When a format is :multipart, the body can be object or array of objects
+    #
+    # Unlike queries, previous body definitions aren't inherited.
+    # The body defined for root scope can be fully reloaded
+    # at subscope/operation level without any merging.
+    #
+    # @param  [Object] value
+    # @param  [Proc] block
+    # @return [self]
+    #
+    def body(value = nil, &block)
+      __define__(:body, value, block)
+    end
+
+    # Adds list of middleware to the schema
+    #
+    # New middleware are added to previously defined (by root).
+    # This means the operation-specific middleware will handle the request
+    # after a root-specific one, and will handle the response before
+    # a roog-specific middleware.
+    #
+    # Values should be either a Rack middleware class, or array of
+    # Rack middleware classes.
+    #
+    # @param  [Rack::Middleware, <Array<Rack::Middleware>>] value
+    # @param  [Proc] block
+    # @return [self]
+    #
+    def middleware(value = nil, &block)
+      __define__(:middleware, value, block)
+    end
+
+    # Adds response handler definition to the schema
+    #
+    # @param  [Integer, Array<Integer>] codes List of response codes
+    # @param  [Proc] block
+    # @return [self]
+    #
+    def response(*codes, &block)
+      codes.flatten.map(&:to_i).each do |code|
+        definitions[:responses][code] = block || proc { |*response| response }
+      end
+      self
+    end
+    alias_method :responses, :response
+
+    private
+
+    # @private Method to add definitions to the schema
+    def __define__(key, value, block)
+      definitions[key] = block || proc { value }
+      self
+    end
+  end
+end