evil-client 0.3.3 → 1.0.0

data/docs/helpers/path.md

@@ -0,0 +1,37 @@
+Use `path` helpers to define operation's path for every operation.
+
+As a rule, you should start from defining root path at the very root of your client, and then complement it at any level of scoping:
+
+```ruby
+class CatsClient < Evil::Client
+  # ...
+  option :domain
+  path { "https://#{domain}.example.com" }
+  # ...
+
+  scope :cats do
+    path "cats" # relative to the root's one
+
+    operation :fetch do
+      option :id # relative to the cats' one
+      path { id }
+      # ...
+    end
+  end
+end
+```
+
+Above declaration will send fetch requests to "https://{domain}.example.com/cats/{id}", for example:
+
+```ruby
+CatsClient.new(domain: "domestic").cats.fetch(37)
+# "https://domestic.example.com/cats/37"
+```
+
+In practice it is the structure of API paths that will "dictate" the structure of your client's scopes.
+
+The path should be defined for every operation, otherwise calling it will cause an exception.
+
+**Notice**. You havent include query to the path. Use [query] helper method instead to define it.
+
+[query]:

data/docs/helpers/query.md

@@ -0,0 +1,59 @@
+Use `query` helper to add some data to the request query. The helper should provide a hash, either nested or not.
+
+```ruby
+class CatsClient < Evil::Client
+  # ...
+  operation :cats do
+    # ...
+    operation :fetch do
+      option :language, default: proc { "en_US" }
+      # ...
+      query { { language: language } }
+    end
+  end
+end
+
+# Later at the runtime it will include query to the fetch request "..?language=en_US"
+CatsClient.new.cats.fetch
+```
+
+When you add query in nested scopes/operations, it updates upper-level definitions, using deep merge when possible (both queries should have compatible structures):
+
+```ruby
+class CatsClient < Evil::Client
+  option :language, default: proc { "en_US" }
+  query { { accept: { language: language } } }
+
+  operation :cats do
+    option :charset, default: proc { "utf-8" }
+    query { { accept: { charset: charset } } }
+    # ...
+    operation :fetch do
+      # ...
+    end
+  end
+end
+
+# Later at the runtime it will include query to any cats operation:
+# ...?accept[language]=en_US&accept[charset]=utf-8
+CatsClient.new.cats.fetch
+```
+
+**Remember** that like [headers], the final query affected by [security][security] (for example, it can define `basic_auth`) settings. 
+
+When you define both query and security settings at the same time, the priority will be given to security. This isn't depend on where (root scope or its sub-scopes) security and query parts are defined. Security settings will always be written over the same query.
+
+```ruby
+class CatsAPI < Evil::Client
+  security { key_auth :basic_auth, "Bar" }
+
+  cats do
+    query { { basic_auth: "Foo" } }
+    # will send requests to ...?basic_auth=Bar
+  end
+end
+```
+
+[rfc-3986]: https://tools.ietf.org/html/rfc3986
+[security]:
+[headers]:

data/docs/helpers/response.md

@@ -0,0 +1,40 @@
+For every operation you have to describe all expected responses and how they should be processed.
+
+Use the `response` method with expected http response status(es):
+
+```ruby
+class CatsAPI < Evil::Client
+  response 200, 201, 404, 422, 500
+end
+```
+
+These definitions are inherited by all subscopes/operations. You can reload them later for every separate status. The definition tells a client to accept responses with given statuses, and to return [rack-compatible response][rack response] as is.
+
+Using a block, you can handle the response in a way you need. For example, the following code will extract and parse json body only.
+
+```ruby
+response 200 do |(_status, _headers, *body)|
+  JSON.parse(body.first) if body.any?
+end
+```
+
+**Remember** that in rack responses body is always wrapped to array (enumerable structure).
+
+Do you best to either wrap a response to your domain model, or raise a specific exception:
+
+```ruby
+response 200 do |(_status, _headers, *body)|
+  Cat.new(JSON.parse(body.first)) if body.any?
+end
+
+response 400, 422 do |_status, *|
+  raise "#{status}: Record invalid"
+end
+```
+
+When you use client-specific [middleware], the `response` block will receive the result already processed by the whole middleware stack. The helper will serve a final step of its handling. Its result wouldn't be processed further in any way.
+
+If a remote API will respond with a status, not defined for the operation, the `Evil::Client::ResponseError` will be risen. The exception carries both the response, and all its parts (status, headers, and body).
+
+[rack response]: http://www.rubydoc.info/github/rack/rack/master/file/SPEC#The_Response
+[middleware]:

data/docs/helpers/scope.md

@@ -0,0 +1,121 @@
+Evil clients use nested scopes to collect definitions and [options], used by single [operations].
+
+## Root Scope
+
+Options and definitions for a root scope should be made in a body of client class:
+
+```ruby
+class CatsClient < Evil::Client
+  option :user,      proc(&:to_s)
+  option :password,  proc(&:to_s)
+  option :subdomain, proc(&:to_s)
+
+  validate(:valid_subdomain) { %w[wild domestic].include? subdomain }
+
+  path { "https://#{subdomain}.example.com/" }
+  http_method "get"
+  security { basic_auth(user, password) }
+end
+```
+
+These options should be assigned to client instance (all undefined ones will be ignored by the initializer).
+
+```ruby
+client = CatsClient.new user: "andy", password: "foo", subdomain: "wild"
+client.options # => { user: "andy", password: "foo", subdomain: "wild" }
+```
+
+You're free to made definitions on the root level, or leave them to subscopes and concrete operations. The only recommendation is to define base [path] here for all subscopes to share it. It's well worth it to define [security] settings at the root level as well.
+
+## Subscopes
+
+Then you can define named subscope with additional options and definitions. The root options, validators and definitions are inherited by subscopes:
+
+```ruby
+class CatsClient < Evil::Client
+  # ...
+
+  scope :cats do
+    # scope-specific options
+    option :version, proc(&:to_i)
+
+    validate(:supported_version) { version < 5 }
+
+    # scope-specific redefinition of the root settings
+    http_method { version.zero? ? :get : :post }
+    path { "cats/v#{version}" }
+  end
+end
+```
+
+```ruby
+cats = client.cats(version: 3)
+cats.options # => { user: "andy", password: "foo", subdomain: "wild", version: 3 }
+```
+
+You can define any number of subscopes at any level of nesting. Every next level will inherit a previous one. There is no difference in DSL for various labels (with a single exclusion for [connection] -- you can assign it to client as a whole, not to a nested scope).
+
+```ruby
+class CatsClient < Evil::Client
+  # ...
+  scope :cats do
+    # ...
+
+    scope :video do
+      # ...
+    end
+
+    scope :books do
+      # ...
+    end
+  end
+end
+```
+
+Inside a scope you can define the operation -- endpoints to remote API. Any operation belongs to the containing scope and inherits its options, validators and shared definitions (and can reload any).
+
+```ruby
+class CatsClient < Evil::Client
+  # ...
+  scope :cats do
+    # ...
+    operation :fetch do
+      # ...
+    end
+  end
+end
+```
+
+## Instantiation
+
+There're several ways to instantiate the scope with options.
+
+A verbose (explicit) style:
+
+```ruby
+client.scopes[:cats].new(version: 3)
+```
+
+...and a bit shorter version (`call` is an alias for `new`):
+
+```ruby
+client.scopes[:cats].(version: 3)
+```
+
+...and even shorter (`[]` is an alias for `new` as well):
+
+```ruby
+client.scopes[:cats][version: 3]
+```
+
+Or just use the name of the scope as a method:
+
+```ruby
+client.cats(version: 3)
+```
+
+[operations]:
+[connection]:
+[path]:
+[security]:
+[options]:

data/docs/helpers/security.md

@@ -0,0 +1,102 @@
+Use `security` declaration for the authorization schema.
+
+Whether you use a block or not, the result should be hash with keys `:query` or/and `:headers`.
+
+```ruby
+class CatsAPI < Evil::Client
+  option :token
+
+  security { { headers: { Authentication: token } } }
+end
+```
+
+Inside the block we support 3 helper methods as well:
+
+* `basic_auth`
+* `token_auth`
+* `key_auth`
+
+## Basic Authentication
+
+Use `basic_auth(login, password)` to define [basic authentication following RFC-7617][basic_auth]:
+
+```ruby
+class CatsAPI < Evil::Client
+  option :login
+  option :password
+
+  security { basic_auth(login, password) }
+end
+```
+
+This declaration with add a header `"Authentication" => "Basic {encoded token}"` to every request. The header is added independenlty of declaration for other [headers][headers].
+
+## Token Authentication
+
+The command `token_auth(token, **options)` allows you to insert a customizable token to any part of the request. Unlike `basic_auth`, you need to provide the token (build, encrypt etc.) by hand.
+
+```ruby
+class CatsAPI < Evil::Client
+  option :token
+
+  security { token_auth(token) }
+  # ...
+end
+```
+
+By default the token is added to `"Authentication" => {token}` header of the request. You can prepend it with a necessary prefix. For example, you can define a [Bearer token authentication following RFC-6750][bearer]:
+
+```ruby
+class CatsAPI < Evil::Client
+  option :token
+
+  security { token_auth(token, prefix: "Bearer") }
+  # ...
+end
+```
+
+Instead of headers, you can send a token in a query. In this case the token will be sent under `access_key` without any prefix:
+
+```ruby
+class CatsAPI < Evil::Client
+  option :token
+
+  security { token_auth(token, inside: :query) }
+  # ...
+end
+
+# will send a request to a path "..?access_key={token}"
+```
+
+## Authentication Using Arbitrary Key
+
+Another option is to authenticate requests with an arbitrary key. This time key-value pair will be added to the selected part (either `headers` or `query`) of the request:
+
+```ruby
+class CatsAPI < Evil::Client
+  option :token
+
+  security { key_auth :Authentication, token }
+  # ...
+end
+```
+
+When a root setting is reloaded inside a subscope or operation, it totally reload previous declaration. If you need to combine root-level settings with operation-level ones, use either [headers] or a [query].
+
+**Important**: When you define both headers/query, and security settings at the same time, the priority will be given to security. This isn't depend on where (root scope or its sub-scopes) security and headers/query parts are defined. Security settings will always be written over the same headers/query.
+
+```ruby
+class CatsAPI < Evil::Client
+  security { key_auth :Authentication, "Bar" }
+
+  scope :cats do
+    headers  { { Authentication: "Foo" } }
+    # will set "Authentication" => "Bar" (not "Foo")
+  end
+end
+```
+
+[basic_auth]: https://tools.ietf.org/html/rfc7617
+[bearer]: https://tools.ietf.org/html/rfc6750
+[headers]:
+[query]:

data/docs/helpers/validate.md

@@ -0,0 +1,68 @@
+Use `validate` helper to check interconnection between several options.
+
+The helper takes name (unique for a current scope) and a block. Validation fails when a block returns falsey value.
+
+```ruby
+class CatsAPI < Evil::Client
+  option :token,    optional: true
+  option :user,     optional: true
+  option :password, optional: true
+
+  # All requests should be made with either token or user/password
+  # This is required by any request
+  validate(:valid_credentials) { token ^ password }
+  validate(:password_given)    { user ^ !password }
+
+  scope :cats do
+    option :version, proc(&:to_i)
+
+    # Check that operation of cats scope include token after API v1
+    # This doesn't affect other subscopes of CatsAPI root scope
+    validate(:token_based) { token || version.zero? }
+  end
+
+  # ...
+end
+
+CatsAPI.new password: "foo" # raises Evil::Client::ValidationError
+```
+
+The error message is translated using i18n gem. You should provide translations for a corresponding scope:
+
+```yaml
+# config/locales/evil-client.en.yml
+---
+en:
+  evil:
+    client:
+      errors:
+        cats_api:
+          valid_credentials: "Provide either a token or a password"
+          password_given:    "User and password should accompany one another"
+          cats:
+            token_based: "The token is required for operations with cats in API v1+"
+```
+
+The root scope for error messages is `{locale}.evil.client.errors.{class_name}` as shown above.
+
+Remember, that you can initialize client with some valid options, and then reload that options in a nested subscope/operation. All validations defined from the root of the client will be used for any set of options. See the example:
+
+```ruby
+client = CatsAPI.new token: "foo"
+# valid
+
+cats = client.cats(version: 0)
+# valid
+
+cats.fetch id: 3
+# valid
+
+cats.fetch id: 3, token: nil
+# fails due to 'valid_credentials' is broken
+
+cats.fetch id: 3, token: nil, user: "andy", password: "qux"
+# valid
+
+cats.fetch id: 3, token: nil, user: "andy", password: "qux", version: 1
+# fails due to 'cats.token_based' is broken
+```

data/docs/index.md

@@ -1,18 +1,19 @@
 Human-friendly DSL for writing HTTP(s) clients in Ruby
 
-[![Logo][evilmartians-logo]][evilmartians]
+<a href="https://evilmartians.com/">
+<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
 
-# About
+[![Gem Version][gem-badger]][gem]
+[![Build Status][travis-badger]][travis]
+[![Dependency Status][gemnasium-badger]][gemnasium]
+[![Code Climate][codeclimate-badger]][codeclimate]
+[![Inline docs][inch-badger]][inch]
 
-The gem allows writing http(s) clients in a way close to [Swagger][swagger] specifications. Like in Swagger, you describe models and operations in domain-specific terms. In addition, the gem supports [settings][settings] and [scopes][scopes] for instantiating clients and sending requests in idiomatic Ruby.
+## Intro
 
-The gem stands away from mutable states and monkey patching when possible. To support multithreading, all instances are immutable (though not frozen to avoid performance loss). The gem's DSL is built on top of [dry-initializer][dry-initializer] gem, and supposes heavy usage of [dry-types][dry-types] system of contracts.
+The gem allows writing http(s) clients in a way inspired by [Swagger][swagger] specifications. It stands away from mutable states and monkey patching when possible. To support multithreading all instances are immutable (though not frozen to avoid performance loss).
 
-For now the top-level DSL supports clients to **json** and **form data** APIs. Because of high variance of XML-based APIs, building their clients require more efforts on a middleware level, which is discussed in the [corresponding topic][xml].
-
-The gem requires ruby 2.2+ and was tested under MRI and JRuby 9+.
-
-# Installation
+## Installation
 
 Add this line to your application's Gemfile:
 
@@ -32,96 +33,87 @@ Or install it yourself as:
 $ gem install evil-client
 ```
 
-# Example
+## Synopsis
 
-The following example gives an idea of how a client to remote API looks like when written on top of `Evil::Client` using [dry-types][dry-types]-based contracts.
+The following example gives an idea of how a client to remote API looks like when written on top of `Evil::Client`.
 
 ```ruby
 require "evil-client"
-require "dry-types"
 
 class CatsClient < Evil::Client
-  # describe a client-specific model of cat (the furry pinnacle of evolution)
-  class Cat < Evil::Struct
-    attribute :name,  type: Dry::Types["strict.string"], optional: true
-    attribute :color, type: Dry::Types["strict.string"]
-    attribute :age,   type: Dry::Types["coercible.int"], default: proc { 0 }
-  end
-
-  # Define settings the client initialized with
-  # The settings parameterizes operations when necessary
-  settings do
-    param  :domain,   type: Dry::Types["strict.string"] # required!
-    option :version,  type: Dry::Types["coercible.int"], default: proc { 0 }
-    option :user,     type: Dry::Types["strict.string"] # required!
-    option :password, type: Dry::Types["strict.string"] # required!
-  end
-
-  # Define a base url using settings
-  base_url do |settings|
-    "https://#{settings.domain}.example.com/api/v#{settings.version}/"
-  end
+  # Define options for the client's initializer
+  option :domain,   proc(&:to_s)
+  option :user,     proc(&:to_s)
+  option :password, proc(&:to_s)
 
   # Definitions shared by all operations
-  operation do |settings|
-    security { basic_auth settings.user, settings.password }
-  end
-
-  # Operation-specific definition to update a cat by id
-  # This provides low-level DSL `operations[:update_cat].call`
-  operation :update_cat do |settings|
-    http_method :patch
-    path { |id:, **| "cats/#{id}" } # id will be taken from request parameters
-
-    body format: "json" do
-      attribute :name,  optional: true
-      attribute :color, optional: true
-      attribute :age,   optional: true
-    end
+  path     { "https://#{domain}.example.com/api" }
+  security { basic_auth settings.user, settings.password }
 
-    response 200 do |body:, **|
-      Cat.new JSON.parse(body) # define that the body should be wrapped to cat
-    end
-
-    response 422, raise: true do |body:, **|
-      JSON.parse(body) # expect 422 to return json data
-    end
-  end
-
-  # Add top-level DSL
   scope :cats do
-    scope do |id|
-      def find(**data)
-        operations[:update_cat].call(id: id, **data)
+    # Scope-specific definitions
+    option :version,  default: proc { 1 }
+    path { "v#{version}" } # subpath added to root path
+
+    # Operation-specific definitions to update a cat by id
+    operation :update do
+      option :id,    proc(&:to_i)
+      option :name,  optional: true
+      option :color, optional: true
+      option :age,   optional: true
+
+      let(:data) { options.select { |key, _| %i(name color age).include? key } }
+      validate(:data_present) { !data.empty? }
+
+      path        { "cats/#{id}" } # added to root path
+      http_method :patch # you can use plain syntax instead of a block
+      format      "json"
+      body        { options.reject { |key, _val| key == :id } }
+
+      # Parses json response and wraps it into Cat instance with additional
+      # parameter
+      response 200 do |(status, headers, body)|
+        # Suppose you define a model for cats
+        Cat.new JSON.parse(body)
       end
+
+      # Parses json response, wraps it into model with [#error] and raises
+      # an exception where [ResponseError#response] contains the model istance
+      response(400, 422) { |(status, *)| raise "#{status}: Record invalid" }
     end
   end
 end
 
-# Instantiate a client with concrete settings
-cat_client = CatClient.new "awesome-cats", # domain
-                           version: 1,
-                           user: "cat_lover",
+# Instantiate a client with a concrete settings
+cat_client = CatClient.new domain:   "awesome-cats",
+                           user:     "cat_lover",
                            password: "purr"
 
-# Use low-level DSL to send requests
-cat_client.operations[:update_cat].call id:    4,
-                                        age:   10,
-                                        name:  "Agamemnon",
-                                        color: "tabby"
+# Use verbose low-level DSL to send requests
+cat_client.scopes[:cats].new(version: 2)
+          .operations[:update].new(id: 4, age: 10, color: "tabby")
+          .call # sends request
 
 # Use top-level DSL for the same request
-cat_client.cats[4].call(age: 10, name: "Agamemnon", color: "tabby")
+cat_client.cats(version: 2).update(id: 4, age: 10, color: "tabby")
 
-# Both the methods send `PATCH https://awesom-cats.example.com/api/v1/cats/7`
+# Both the methods send `PATCH https://awesome-cats.example.com/api/v2/cats/4`
 # with a specified body and headers (authorization via basic_auth)
 ```
 
-[swagger]: http://swagger.io
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+[codeclimate-badger]: https://img.shields.io/codeclimate/github/evilmartians/evil-client.svg?style=flat
+[codeclimate]: https://codeclimate.com/github/evilmartians/evil-client
 [dry-initializer]: http://dry-rb.org/gems/dry-initializer
-[dry-types]: http://dry-rb.org/gems/dry-types
-[evilmartians]: https://evilmartians.com
-[evilmartians-logo]: https://evilmartians.com/badges/sponsored-by-evil-martians.svg
-[settings]:
-[scopes]:
-[xml]:
+[gem-badger]: https://img.shields.io/gem/v/evil-client.svg?style=flat
+[gem]: https://rubygems.org/gems/evil-client
+[gemnasium-badger]: https://img.shields.io/gemnasium/evilmartians/evil-client.svg?style=flat
+[gemnasium]: https://gemnasium.com/evilmartians/evil-client
+[inch-badger]: http://inch-ci.org/github/evilmartians/evil-client.svg
+[inch]: https://inch-ci.org/github/evilmartians/evil-client
+[swagger]: http://swagger.io
+[travis-badger]: https://img.shields.io/travis/evilmartians/evil-client/master.svg?style=flat
+[travis]: https://travis-ci.org/evilmartians/evil-client