evil-client 0.3.3 → 1.0.0

data/docs/helpers/body.md

@@ -0,0 +1,93 @@
+Use helpers `body` and `format` to define content of http message, and how it should be formatted.
+
+We support several formats, namely: `:json` (default), `:text`, `:form`, `:yaml`, and `:multipart`.
+
+## Plain Formats
+
+With default `:json` format, the body should be a hash:
+
+```ruby
+class CatsAPI < Evil::Client
+  format { :json }
+  # ...
+  scope :cats do
+    # ...
+    operation :create do
+      option :species
+      option :name
+
+      body { { species: species, name: name } }
+    end
+  end
+end
+```
+
+Before sending to the stack of [middleware], it will be dumped:
+
+```ruby
+CatsAPI.cats.create species: "Acinonyx jubatus", name: "Cheetah"
+# sends a request with a body: '{"species":"Acinonyx jubatus","name":"Cheetah"}'
+# and a header "Content-Type": "application/json"
+```
+
+The same content, but formatted as `:yaml` will send another body and header:
+
+```ruby
+class CatsAPI < Evil::Client
+  format { :yaml }
+end
+
+CatsAPI.cats.create species: "Acinonyx jubatus", name: "Cheetah"
+# sends a request with a body: "---\n:species: Acinonyx jubatus\n:name: Cheetah\n'
+# and a header "Content-Type": "application/yaml"
+```
+
+The `:form` format will make body url encoded:
+
+```ruby
+class CatsAPI < Evil::Client
+  format { :form }
+end
+
+CatsAPI.cats.create species: "Acinonyx jubatus", name: "Cheetah"
+# sends a request with a body: "species=Acinonyx jubatus&name=Cheetah"
+# and a header "Content-Type": "application/x-www-form-urlencoded"
+```
+
+The `:text` just stringifies it as is:
+
+```ruby
+class CatsAPI < Evil::Client
+  format { :text }
+end
+
+CatsAPI.cats.create species: "Acinonyx jubatus", name: "Cheetah"
+# sends a request with a body: '{:species=>"Acionyx jubatus",:name=>"Cheetah"}'
+# and a header "Content-Type": "text/plain"
+```
+
+This format doesn't require the body to be hash. It can be anything.
+
+## Multipart Formats
+
+When you need sending files you should select the `:multipart` format. This time the whole body is formatted as `form/multipart`.
+Depending on its type (hash, file, StringIO), the content will be formatted correspondingly. Arrays are treated as several parts of the body. All other objects will be stringified.
+
+```ruby
+class CatsAPI < Evil::Client
+  # ...
+  scope :cats do
+    # ...
+    operation :upload do
+      option :files, method(:Array)
+
+      format { :multipart }
+      body   { files }
+    end
+  end
+end
+
+CatsAPI.cats.upload files: [StringIO.new("Cheetah"), StrinIO.new("Lion")]
+```
+
+[middleware]:

data/docs/helpers/connection.md

@@ -0,0 +1,19 @@
+By default, Evil Client uses [Net::HTTP][net-http]-based connection to send requests.
+
+If you need another user agent, change it to you client via connection writer. The connection can be an object with method `#call` that takes [rack environment][rack-env] (from stack of middleware) and returns [rack response][rack-response] back.
+
+```ruby
+conn = Object.new do
+  def self.call(env)
+    [200, {"Content-Type"=>"application/json"}, ['{"age":7}']]
+  end
+end
+
+class CatsClient < Evil::Client
+  connection = conn
+end
+```
+
+[net-http]: http://ruby-doc.org/stdlib-2.4.1/libdoc/net/http/rdoc/Net/HTTP.html
+[rack-env]: http://www.rubydoc.info/github/rack/rack/file/SPEC#The_Environment
+[rack-response]: http://www.rubydoc.info/github/rack/rack/file/SPEC#The_Response

data/docs/helpers/headers.md

@@ -0,0 +1,72 @@
+Use method `headers` to add several headers to a request
+
+```ruby
+class CatsClient < Evil::Client
+  operation :fetch do
+    option :id
+    option :language
+
+    headers { { "Accept-Language" => language } }
+    # ...
+  end
+end
+```
+
+Remember that you can define header values as a flat array instead of the string. Inside an array all the values are counted as srings.
+
+```ruby
+headers { "Language" => ["ru_RU", "charset=utf-8"] }
+```
+
+You can define headers bit-by-bit starting from a root scope:
+
+```ruby
+class CatsClient < Evil::Client
+  option  :charset, default: -> { "utf-8" }
+  headers { { "Accept-Charset" => charset } }
+
+  operation :fetch do
+    option :id
+    option :language
+
+    headers { { "Accept-Language" => language } }
+    # ...
+  end
+end
+
+CatsClient.new(charset: "ascii-1251").fetch(id: 3, language: "en_US")
+# This would send a request with the headers:
+# { "Accept-Charset" => "ascii-1251", "Accept-Language" => "en_US" }
+```
+
+When you redefine some of root options, this redefinition can affects headers:
+
+```ruby
+CatsClient.new(charset: "ascii-1251")
+          .fetch(id: 3, language: "en_US", charset: "utf-16")
+
+# This would send a request with the headers:
+# { "Accept-Charset" => "utf-16", "Accept-Language" => "en_US" }
+```
+
+As a rule, you shouldn't define authorization headers in this way. Use [the security helper][security] instead.
+
+**Remember** that eventual collection of request headers is also affected by [security][security] (sets `Authentication`), and [format][format] (sets `Content-Type`) helpers. You can add request headers via [middleware] as well. Finally, the [connection] adds some headers (like `User-Agent`) by its own.
+
+When you define both headers 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 parts are defined. Security settings will always be written over the same headers.
+
+```ruby
+class CatsAPI < Evil::Client
+  security { key_auth :Authentication, "Bar" }
+
+  scope :cats do
+    headers  { { Authentication: "Foo" } }
+    # will set "Authentication" => "Bar" (not "Foo")
+  end
+end
+```
+
+[security]:
+[format]: 
+[middleware]: 
+[connection]: 

data/docs/helpers/http_method.md

@@ -0,0 +1,39 @@
+Define [http method] for sending a request using the `http_method` helper.
+
+```ruby
+operation :fetch do
+  http_method :get
+  # ...
+end
+```
+
+As usual, you have access to current options. This can be useful to make the method dependent from either a version, or another variation of API.
+
+```ruby
+operation :fetch do
+  # ...
+  option :version, proc(&:to_i)
+
+  http_method { version > 2 ? :post : :get }
+  # ...
+end
+```
+
+The definition can be reloaded at any level of scoping.
+
+Following [RFC 7231], we support only valid methods (they could be set as case-insensitive stringified object):
+
+- GET
+- POST
+- PUT
+- PATCH
+- DELETE
+- OPTIONS
+- HEAD
+- TRACE
+- CONNECT
+
+Setting http method to another value, or missing it, will cause an exception.
+
+[http method]: 
+[RFC 7231]: https://tools.ietf.org/html/rfc7231

data/docs/helpers/let.md

@@ -0,0 +1,14 @@
+Use `let` helper to add virtial memoized attributes to the scope/operation.
+
+```ruby
+class CatsAPI < Evil::Client
+  option :version, default: proc { 0 }
+  option :release, default: proc { 1 }
+
+  let(:full_version) { [version, release].join(".") } # "0.1" by default
+end
+```
+
+These virtual attributes are available inside all block declarations, including [validations].
+
+[validations]:

data/docs/helpers/logger.md

@@ -0,0 +1,24 @@
+You can assign a logger to any instance of operation/scope.
+
+As a rule you would do this assignment to the initialized client:
+
+```ruby
+client = CatsClient.new(token: "foobar")
+log    = StringIO.new
+logger = Logger.new log
+```
+
+The client will publish debag messages to the log every time it sets instance of scope/operation schema, or initializes them with some options. Requests and responses are logged at the info level.
+
+Later you can check the log:
+
+```ruby
+client.cats.fetch id: 83
+
+log.string
+# D, [2017-07-30T22:23:50.262734 #23474] DEBUG -- CatsApi.cats: initializing with options {}...
+# D, [2017-07-30T22:23:50.263240 #23474] DEBUG -- #<CatsApi.cats:0x000000034d2710 @token="foobar"> initialized
+# D, [2017-07-30T22:23:50.262734 #23474] DEBUG -- CatsApi.cats.fetch: initializing with options {"token"=>"foobar", id"=>83}...
+# D, [2017-07-30T22:23:50.263240 #23474] DEBUG -- #<CatsApi.cats.fetch:0x000000034d2840 @token="foobar", "id"=83> initialized
+# ...
+```

data/docs/helpers/middleware.md

@@ -0,0 +1,56 @@
+Evil client supports stack of rack-compatible middleware which is specific for every scope and operation.
+
+As usual, every middleware is just an object wrapped around some application. It should:
+
+- initialize with the only parameter `app` for the rest of stack, wrapped around connection,
+- define the only instance method `#call` which takes a [rack environment], and returns a [rack response].
+
+The example of valid middleware which adds the tag "FOO" to the request header:
+
+```ruby
+class Foo
+  def call(env)
+    env["HTTP_Variables"]["Tag"] = "FOO"
+    @app.call env
+  end
+
+  private
+
+  def initialize(app)
+    @app = app
+  end
+end
+```
+
+Use the `middleware` helper method to add a specific class to a stack. You can do this at any level of nesting:
+
+```ruby
+class CatsAPI < Evil::Client
+  # ...
+  middleware Foo
+
+  scope :cats do
+    option :version, proc(&:to_i)
+    # ...
+    middleware { version < 2 ? Bar : [Bar, Baz] }
+
+    operation :fetch do
+      middleware { Qux }
+      # ...
+    end
+  end
+end
+
+# Depending on version, this will send rack request to either
+# [Foo, Bar, Qux, Evil::Client::Connection]      (versions 1-)
+# [Foo, Bar, Baz, Qux, Evil::Client::Connection] (versions 2+)
+#
+# The response will be processed in the reverse order
+```
+
+You can place the same class to the stack several times.
+
+The order of definitions is important. The request is processed by middleware in the order from root to operation, and the response will be processed in reverse order -- from operation to the root.
+
+[rack environment]: http://www.rubydoc.info/github/rack/rack/file/SPEC#The_Environment
+[rack response]: http://www.rubydoc.info/github/rack/rack/file/SPEC#The_Response

data/docs/helpers/operation.md

@@ -0,0 +1,103 @@
+Operation defines a specific request to a remote API with some helpers to process its responses.
+
+To specify an operation, you should define the following parts:
+
+- [options] of the request sender
+- http(s) [path] to the remote server
+- [http method] for sending requests
+- [security] definitions describing what credentials the request should carry
+- http [headers] to include into the request (along with security-related ones)
+- request [query] to be added to the request path (along with security-related)
+- a [content][body] of the request and a [format][body] describing the content should be formatted
+- a set of [middleware] that should be added to the remote [connection]
+- a set of expected [responses] with corresponding handlers
+
+An operation is specified with a unique name inside the corresponding [scope].
+
+You can add it to the root of the client, or to any subscope:
+
+```ruby
+class CatsClient < Evil::Client
+  # Returns current information about the client
+  operation :info do
+    # ...
+  end
+
+  scope :cats do
+    # ...
+
+    # Fetches information about a specific cat
+    operation :fetch do
+      # ...
+    end
+  end
+end
+```
+
+Operation-specific definitions should be made inside the block. They will affect only this operation:
+
+```ruby
+class CatsClient < Evil::Client
+  # ...
+  scope :cats do
+    # ...
+    operation :fetch do
+      option :id
+
+      path { id }
+      http_method :get
+      response 200
+      response(400, 422) { |(status, *)| raise "#{status}: Wrong request" }
+      response(404) { raise "404: Not found" }
+    end
+  end
+end
+```
+
+Besides operation-specific settings, you can add same definitions for a scope. This definitions are shared by all operations of the scope and its sub-scopes on any level of nesting. Any sub-scope or operation can reload this shared definitions, or update it with those of its own.
+
+```ruby
+class CatsClient < Evil::Client
+  # ...
+  scope :cats do
+    path { "cats" } # relative to root scope
+    http_method :get
+    response 200
+    response(400, 422) { |(status, *)| raise "#{status}: Wrong request" }
+    response(404) { raise "404: Not found" }
+
+    operation :fetch do
+      option :id
+      path { id } # relative to upper scope
+    end
+  end
+end
+```
+
+The user of custom client sends a request by invoking some operation by name on a corresponding scope.
+
+```ruby
+client = CatsClient.new
+cats   = client.cats # scope for the `fetch` operaton
+
+cats.fetch id: 44 # sends request and returns a processed response
+```
+
+Alternatively you can initialize the operation first, and call it later:
+
+```ruby
+operation = cats.operations[:fetch].new(id: 44)
+operation.call
+```
+
+[options]: 
+[path]: 
+[http method]: 
+[security]: 
+[headers]: 
+[query]: 
+[body]: 
+[middleware]: 
+[connection]: 
+[responses]: 
+[scope]: 

data/docs/helpers/option.md

@@ -0,0 +1,50 @@
+Use the `option` helper to add options to some scope or operation.
+
+```ruby
+class CatsClient < Evil::Client
+  # Define options for the client's initializer
+  option :domain,   proc(&:to_s)
+  option :user,     proc(&:to_s)
+  option :password, proc(&:to_s), optional: true
+  option :token,    proc(&:to_s), optional: true
+  # ...
+
+  scope :cats do
+    # Scope-specific options
+    option :version, default: proc { 1 }
+ 
+    # Operation-specific options
+    operation :fetch do
+      option :id, proc(&:to_i)
+    end
+  end
+end
+```
+
+The helper is taken from [dry-initializer] gem, so you can see [the gem's documentation][dry-initializer-docs] for the details of its syntax. Notice, that evil-client doesn't support positional arguments (aka `param`-s).
+
+All declarations made at a root scope, or any ancestor scope, are available at the nested levels.
+Options assigned during client/scope/operation instantiation are accumulated:
+
+```ruby
+client = CatsClient.new domain: "wild", user: "andy"
+client.options # => { domain: "wild", user: "andy" }
+client.domain  # => "wild"
+client.user    # => "andy"
+
+cats = client.cats(version: 3)
+cats.options  # => { domain: "wild", user: "andy", version: 3 }
+
+fetch = cats.operations[:fetch].new(id: 7)
+fetch.options # => { domain: "wild", user: "andy", version: 3, id: 7 }
+```
+
+You can define any assigned option at any level of nesting:
+
+```ruby
+fetch = cats.operations[:fetch].new(id: 7, domain: "domestic")
+fetch.options # => { domain: "domestic", user: "andy", version: 3, id: 7 }
+```
+
+[dry-initializer] https://github.com/dry-rb/dry-initializer
+[dry-initializer-docs]: http://dry-rb.org/gems/dry-initializer/