evil-client 0.3.3 → 1.0.0

data/docs/license.md

@@ -1,4 +1,8 @@
-Copyright (c) 2016 Andrew Kozin (aka nepalez), andrew.kozin@gmail.com
+# The MIT License (MIT)
+
+Copyright (c) 2015-2017 Andrew Kozin (nepalez),
+                        Ravil Bairamgalin (brainopia),
+                        Evil Martians (evilmartians)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/docs/rspec.md

@@ -0,0 +1,96 @@
+When you provide a client to remote API, you would provide some means for its users to test their operations.
+
+Surely, they could use [webmock] to check the ultimate requests that are sent to the server. But doing this, they would inadvertedly specify not their own code, but your client's code too. What do they actually need is a means to check calls of your client's operations. This way they would back on correctness of your client, and take its interface as an endpoint.
+
+For this reason, we support a special RSpec matcher `perform_operation`. It checks, what operations are called via evil-client, and what options are used in there.
+
+The matcher isn't loaded by default, so you must require it first:
+
+```ruby
+require "evil/client/rspec"
+```
+
+Providing that you defined some client...
+
+```ruby
+class CatsClient < Evil::Client
+  option :token
+  # ...
+  scope :cats do
+    option :version
+    # ...
+    operation :fetch do
+      option :id
+      # ...
+    end
+  end
+end
+```
+
+... lets write a specification:
+
+```ruby
+require "evil/client/rspec"
+
+RSpec.describe CatsClient, "cats.fetch" do
+  let(:client) { CatsClient.new(token: "foo") }
+  let(:scope)  { client.cats(version: 1) }
+
+  it "fetches a cat by id" do
+    expect { scope.fetch(id: 8) }
+      .to perform_operation("CatsClient.client.fetch")
+  end
+end
+```
+
+You can add chaining using one of 3 additional methods: `with`, `with_exactly`, or `without`.
+
+## with
+
+This method checks that the operation **includes some options**:
+
+```ruby
+expect { scope.fetch(id: 8) }
+  .to perform_operation("CatsClient.client.fetch")
+  .with token: "foo"
+```
+
+## with_exactly
+
+This time you can check the full list of options given to operation:
+
+```ruby
+expect { scope.fetch(id: 8) }
+  .to perform_operation("CatsClient.client.fetch")
+  .with_exactly token: "foo", version: 1, id: 8
+```
+
+## without
+
+You can also check that some keys are absent:
+
+```ruby
+expect { scope.fetch(id: 8) }
+  .to perform_operation("CatsClient.client.fetch")
+  .without :name, :email
+```
+
+This can be useful to check a behaviour of the client with optional attributes.
+
+All checks can be negated as well:
+
+```ruby
+expect { scope.fetch(id: 8) }
+  .not_to perform_operation("CatsClient.client.fetch")
+  .with token: "foo"
+```
+
+**Notice**: Under the hood the matcher doesn't stub the request, so its better to stub all requests by hand:
+
+```ruby
+require "webmock/rspec"
+
+before { stub_request :any, // }
+```
+
+[webmock]: https://github.com/bblimke/webmock

data/evil-client.gemspec

@@ -1,8 +1,8 @@
 Gem::Specification.new do |gem|
   gem.name     = "evil-client"
-  gem.version  = "0.3.3"
+  gem.version  = "1.0.0"
   gem.author   = ["Andrew Kozin (nepalez)", "Ravil Bairamgalin (brainopia)"]
-  gem.email    = "andrew.kozin@gmail.com"
+  gem.email    = ["andrew.kozin@gmail.com", "nepalez@evilmartians.com"]
   gem.homepage = "https://github.com/evilmartians/evil-client"
   gem.summary  = "Human-friendly DSL for building HTTP(s) clients in Ruby"
   gem.license  = "MIT"
@@ -13,13 +13,15 @@ Gem::Specification.new do |gem|
 
   gem.required_ruby_version = ">= 2.3"
 
-  gem.add_runtime_dependency "evil-struct", ">= 0.0.2"
-  gem.add_runtime_dependency "mime-types", "> 1"
-  gem.add_runtime_dependency "rack", ">= 1", "< 3"
+  gem.add_runtime_dependency "dry-initializer", "~> 1.4"
+  gem.add_runtime_dependency "i18n", "~> 0.8.6"
+  gem.add_runtime_dependency "mime-types", "~> 3.1"
+  gem.add_runtime_dependency "rack", "~> 1"
 
-  gem.add_development_dependency "dry-types", "~> 0.9"
+  gem.add_development_dependency "rake", ">= 10"
   gem.add_development_dependency "rspec", "~> 3.0"
-  gem.add_development_dependency "rake", "~> 11"
+  gem.add_development_dependency "rspec-its", "~> 1.2"
+  gem.add_development_dependency "rubocop", "~> 0.42"
+  gem.add_development_dependency "timecop", "~> 0.9"
   gem.add_development_dependency "webmock", "~> 2.1"
-  gem.add_development_dependency "rubocop", "~> 0.44"
 end

data/lib/evil/client.rb

@@ -1,83 +1,137 @@
-require "evil-struct"
-require "mime-types"
+require "uri"
+require "logger"
 require "rack"
+require "cgi"
 require "json"
+require "yaml"
+require "i18n"
+require "mime-types"
 require "securerandom"
-
-# Absctract base class for clients to remote APIs
-#
-# @abstract
-# @example
-#   class MyClient < Evil::Client
-#     # declare settings for the client's constructor
-#     # the settings parameterize the rest of the client's definitions
-#     settings do
-#       option :version, type: Dry::Types["strict.int"].default(1)
-#       option :user,    type: Dry::Types["strict.string"]
-#       option :token,   type: Dry::Types["strict.string"]
-#     end
-#
-#     # define base url of the server
-#     base_url do |settings|
-#       "https://my_api.com/v#{settings.version}"
-#     end
-#
-#     # define connection and its middleware stack from bottom to top
-#     connection :net_http do |settings|
-#       run AddCustomRequestId
-#       run EncryptToken if settings.token
-#     end
-#
-#     # definitions shared by all operations (can be reloaded later)
-#     operation do |settings|
-#       type     { :json }
-#       security { basic_auth "foo", "bar" }
-#     end
-#
-#     # operation-specific definitions
-#     operation :find_cat do |settings|
-#       http_method :get
-#       path { "#{settings.url}/cats/find/#{id}" }
+require "dry-initializer"
+require "net/http"
+require "net/https"
 #
-#       query do
-#         option :id, type: Dry::Types["coercible.int"].constrained(gt: 0)
-#       end
-#
-#       response 200, type: Cat
-#       response 400, raise: true
-#       response 422, raise: true do |body:|
-#         JSON.parse(body.first)
-#       end
-#     end
-#
-#     # top-level DSL for operation
-#     scope :users do
-#       scope do # named `:[]` by default
-#         param :id, type: Dry::Types["strict.int"]
-#
-#         def get
-#           operations[:find_users].call(id: id)
-#         end
-#       end
-#     end
-#   end
-#
-#   # Initialize a client with a corresponding settings
-#   client = MyClient.new user: "andrew", token: "f982j23"
-#
-#   # Use low-level DSL for searching a user
-#   client.operations[:find_user].call(id: 1)
-#
-#   # Use top-level DSL for the same operation
-#   client.users[1].get
+# Namespace for gems created by Evil Martians
 #
 module Evil
+  #
+  # Absctract base class for clients to remote APIs
+  #
   class Client
+    require_relative "client/exceptions/definition_error"
+    require_relative "client/exceptions/name_error"
+    require_relative "client/exceptions/response_error"
+    require_relative "client/exceptions/type_error"
+    require_relative "client/exceptions/validation_error"
+
+    require_relative "client/chaining"
+    require_relative "client/settings"
+    require_relative "client/schema"
+    require_relative "client/container"
+    require_relative "client/builder"
     require_relative "client/connection"
-    require_relative "client/middleware"
-    require_relative "client/operation"
-    require_relative "client/dsl"
+    require_relative "client/formatter"
+    require_relative "client/resolver"
+
+    include Chaining
+
+    class << self
+      # Object used as an HTTP(s) connection to remote API
+      #
+      # It is expected to implement the method [#call] which
+      # should take one argument for a rack-compatible request environment,
+      # and return a rack-compatible response.
+      #
+      # By default the connection is set to [Evil::Client::Connection],
+      # but it can be redefined for a custom client.
+      #
+      # @return [#call] connection (Evil::Client::Connection)
+      #
+      def connection
+        @connection ||= Evil::Client::Connection
+      end
+
+      # Sets a custom connection, or resets it to a default one
+      #
+      # @param  [#call, nil] connection
+      # @return [self]
+      #
+      def connection=(connection)
+        @connection = connection
+        self
+      end
+
+      # Schema for the root scope of the client
+      #
+      # @return [Evil::Client::Schema::Scope]
+      #
+      def schema
+        @schema ||= Schema::Scope.new(self)
+      end
+
+      private
+
+      def respond_to_missing?(name, *)
+        schema.respond_to? name
+      end
+
+      def method_missing(*args, &block)
+        respond_to_missing?(*args) ? schema.send(*args, &block) : super
+      end
+    end
+
+    # Initialized root scope container
+    #
+    # @return [Evil::Client::Container::Scope]
+    #
+    attr_reader :scope
+
+    # Logger for the root scope
+    #
+    # @return (see Evil::Client::Settings#logger)
+    #
+    def logger
+      @scope.logger
+    end
+
+    # Sets logger to the client
+    #
+    # @param  [Logger, nil] logger
+    # @return [self]
+    #
+    def logger=(logger)
+      @scope.logger = logger
+      self
+    end
+
+    # Operations defined at the root of the client
+    #
+    # @return (see Evil::Client::Container::Scope#operations)
+    #
+    def operations
+      @scope.operations
+    end
+
+    # Subscopes of client root
+    #
+    # @return (see Evil::Client::Container::Scope#scopes)
+    #
+    def scopes
+      @scope.scopes
+    end
+
+    # Options assigned to the client
+    #
+    # @return (see Evil::Client::Container#options)
+    #
+    def options
+      @scope.options
+    end
+
+    private
 
-    extend DSL
+    def initialize(**options)
+      @scope = Container::Scope.new self.class.send(:schema), options
+    end
   end
 end

data/lib/evil/client/builder.rb

@@ -0,0 +1,47 @@
+class Evil::Client
+  #
+  # @abstract
+  # Base class for scope/operation builders
+  #
+  # Every builder just wraps scope/operation schema along with
+  # preinitialized [#parent] settings of its super-scope.
+  # The instance method [#new] quacks like the lazy constructor
+  # for scope/operation instance whose options reload the [#parent]'s ones.
+  #
+  class Builder
+    # Load concrete implementations for the abstact builder
+    require_relative "builder/scope"
+    require_relative "builder/operation"
+
+    # The schema for an instance to be constructed via [#new]
+    # @return [Evil::Client::Schema]
+    attr_reader :schema
+
+    # The instance of parent scope carrying default settings
+    # @return [Evil::Client::Container::Scope]
+    attr_reader :parent
+
+    # Alias method for [#to_s]
+    #
+    # @return [String]
+    #
+    def to_str
+      to_s
+    end
+
+    # Alias method for [#to_s]
+    #
+    # @return [String]
+    #
+    def inspect
+      to_s
+    end
+
+    private
+
+    def initialize(schema, parent)
+      @schema = schema
+      @parent = parent
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+class Evil::Client
+  #
+  # Lazy container for a [#schema] and [#parent] settings
+  # of a [#new] operation to be initialized with its own options,
+  # that reload the [#parent] ones.
+  #
+  class Builder::Operation < Builder
+    # Human-readable representation of the handler
+    #
+    # @example
+    #   '#<MyClient.scopes[:users] @version="1.1">.operations[:fetch]'
+    #
+    # @return [String]
+    #
+    def to_s
+      "#{parent}.operations[:#{schema.name}]"
+    end
+
+    # @!method new(options)
+    # Builds new operation with options reloading those of its [#parent]
+    #
+    # @param  [Hash<Symbol, Object>] options ({}) Custom options
+    # @return [Evil::Client::Container::Operation]
+    #
+    def new(**options)
+      Container::Operation.new schema, parent.options.merge(options)
+    end
+
+    # @!method call(options)
+    # Builds and calls operation at once
+    #
+    # @param  (see #new)
+    # @return (see Container::Operation#call)
+    #
+    def call(**options)
+      new(**options).call
+    end
+    alias_method :[], :call
+  end
+end

data/lib/evil/client/builder/scope.rb

@@ -0,0 +1,31 @@
+class Evil::Client
+  #
+  # Lazy container for a [#schema] and [#parent] settings
+  # of a [#new] scope to be initialized with its own options,
+  # that reload the [#parent] ones.
+  #
+  class Builder::Scope < Builder
+    # Human-readable representation of the handler
+    #
+    # @example
+    #   '#<MyClient.scopes[:crm] @version="1.1">.scopes[:users]'
+    #
+    # @return [String]
+    #
+    def to_s
+      "#{parent}.scopes[:#{schema.name}]"
+    end
+
+    # @!method new(options)
+    # Builds new scope with options reloading those of its [#parent]
+    #
+    # @param  [Hash<Symbol, Object>] options Custom options
+    # @return [Evil::Client::Container::Scope]
+    #
+    def new(**options)
+      Container::Scope.new schema, parent.options.merge(options)
+    end
+    alias_method :call, :new
+    alias_method :[],   :new
+  end
+end