evil-client 0.2.1

data/docs/http_method.md

@@ -0,0 +1,31 @@
+Use `http_method` to define it for the current operation.
+
+```ruby
+operation :find_cat do
+  http_method :get
+end
+```
+
+As usual, you have access to current settings. This can be useful to make the method dependent from either a version, or other variation of the api.
+
+```ruby
+operation :find_cat do |settings|
+  http_method settings.version > 2 ? :post : :get
+end
+```
+
+You can also set a default method for all operations. It can be reloaded later:
+
+```ruby
+operation do
+  http_method :get
+end
+
+operation :find_cat do
+  # sends requests via get
+end
+
+operation :update_cat do
+  http_method :patch
+end
+```

data/docs/index.md

@@ -0,0 +1,127 @@
+Human-friendly DSL for writing HTTP(s) clients in Ruby
+
+[![Logo][evilmartians-logo]][evilmartians]
+
+# About
+
+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.
+
+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.
+
+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
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'evil-client'
+```
+
+And then execute:
+
+```shell
+$ bundle
+```
+
+Or install it yourself as:
+
+```shell
+$ gem install evil-client
+```
+
+# Example
+
+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.
+
+```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::Client::Model
+    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
+
+  # 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
+
+    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)
+      end
+    end
+  end
+end
+
+# Instantiate a client with concrete settings
+cat_client = CatClient.new "awesome-cats", # domain
+                           version: 1,
+                           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 top-level DSL for the same request
+cat_client.cats[4].call(age: 10, name: "Agamemnon", color: "tabby")
+
+# Both the methods send `PATCH https://awesom-cats.example.com/api/v1/cats/7`
+# with a specified body and headers (authorization via basic_auth)
+```
+
+[swagger]: http://swagger.io
+[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]:

data/docs/license.md

@@ -0,0 +1,19 @@
+Copyright (c) 2016 Andrew Kozin (aka nepalez), andrew.kozin@gmail.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/docs/model.md

@@ -0,0 +1,173 @@
+Models are simple nested structures, based on [dry-initializer][dry-initializer] and [dry-types][dry-types].
+
+They are needed to prepare and validate nested bodies and queries, as well as wrap and validate responses.
+
+# Model Definition
+
+To define a model create a subclass of `Evil::Client::Model` and define its attributes.
+
+```ruby
+class Cat < Evil::Client::Model
+  attribute :name,  type: Dry::Types["strict.string"], optional: true
+  attribute :age,   type: Dry::Types["coercible.int"], default: proc { 0 }
+  attribute :color, type: Dry::Types["strict.string"]
+end
+```
+
+The method `attribute` is just an alias of [dry-initializer `option`][dry-initializer]. Because model's constructor takes options only, not params, `param` is reloaded as another alias of `option`. You can use any method you like.
+
+To initialize an instance send a hash of options to the constructor:
+
+```ruby
+cat = Cat.new(name: "Navuxodonosor II", age: "15", color: "black")
+cat.name  # => "Navuxodonosor II"
+cat.age   # => 15
+cat.color # => "black"
+```
+
+You can build a model from another one (it just returns the object back):
+
+```ruby
+Cat.new Cat.new(name: "Navuxodonosor II", age: 15, color: "black")
+```
+
+or from a hash with string keys:
+
+```ruby
+Cat.new("name" => "Navuxodonosor II", "age" => 15, "color" => "black")
+```
+
+You can use other (nested) models in type definitions:
+
+```ruby
+class CatPack < Evil::Client::Model
+  attribute :cats, type: Dry::Types["array"].member(Cat)
+end
+
+CatPack.new cats: [{ name: "Navuxodonosor II", age: 15, color: "black" }]
+```
+
+Models can be converted back to hashes with **symbolic** keys:
+
+```ruby
+cat = Cat.new(name: "Navuxodonosor II", age: "15", color: "black")
+cat.to_h # => { name: "Navuxodonosor II", age: "15", color: "black" }
+```
+
+The model ignores all options it doesn't know about, and applies constraints to known ones only.
+
+```ruby
+# Cats don't care about your expectations
+cat = Cat.new(name: "Navuxodonosor II", age: "15", color: "black", expectation: "hunting")
+cat.to_h # => { name: "Navuxodonosor II", age: "15", color: "black" }
+```
+
+If all you need is data filtering, just use a shortcut `.[]`:
+
+```ruby
+Cat[name: "Navuxodonosor II", age: "15", color: "black", expectation: "hunting"]
+# => { name: "Navuxodonosor II", age: "15", color: "black" }
+```
+
+# Model Usage
+
+You can use models in definitions of request [body][body], [query][query], and [headers][headers]...
+
+```ruby
+operation :create_cat do
+  method :post
+  path { "cats" }
+  body model: Cat
+end
+```
+
+...and in [response][response] processing:
+
+```ruby
+operation :create_cat do
+  # ...
+  response 201 do |body:, **|
+    Cat[JSON.parse(body)]
+  end
+end
+```
+
+# Distinction of Models from Dry::Struct
+
+Models are like ~~onions~~ structures, defined in [`dry-struct`][dry-struct]. Both models and structures support hash arguments, type constraints, nested data, and backward hashification via `to_h`. You can check [dry-struct documentation] to make an impression of how it works.
+
+Nethertheless, there is an important difference between the implementations of nested structures.
+
+## Undefined Values vs nils
+
+The main reason to define gem-specific model is the following. In `Dry::Struct` both the `optional` and `default` properties belong to value type constraint. The gem does not draw the line between attributes that are not set, and those that are set to `nil`.
+
+To the contrary, in [dry-initializer][dry-initializer] and `Evil::Client::Model` both `optional` and `default` properties describe not a value type by itself, but its relation to the model. An attribute value can be set to `nil`, or been kept in undefined state.
+
+Let's see the difference on the example of `StructCat` and `ModelCat`:
+
+```ruby
+class StructCat < Dry::Struct
+  attribute :name, type: Dry::Types["strict.string"].optional
+  attribute :age,  type: Dry::Types["coercible.int"].default(0)
+end
+
+class ModelCat < Evil::Client::Model
+  attribute :name, type: Dry::Types["strict.string"], optional: true
+  attribute :age,  type: Dry::Types["coercible.int"], default: proc { 0 }
+end
+
+struct_cat = StructCat.new
+struct_cat.name # => nil
+struct_cat.age  # => 0
+struct_cat.to_h # => { name: nil, age: 0 }
+
+model_cat = ModelCat.new
+model_cat.name # => #<Dry::Initializer::UNDEFINED>
+model_cat.age  # => 0
+model_cat.to_h # => { age: 0 }
+
+model_cat = ModelCat.new name: nil
+model_cat.name # => nil
+model_cat.age  # => 0
+model_cat.to_h # => { name: nil, age: 0 }
+```
+
+Notice that in a model hashification ignores undefined attributes. This is important to filter arguments of a request. In PUT/PATCH requests (update server-side data) there is a difference between values not changed, and those that are explicitly reset to `nil`.
+
+## Tolerance to Unknown Options
+
+A model's constructor ignores unknown options, so you can safely sent any ones:
+
+```ruby
+# Oh, no, this is a cat, not a bat!
+model_cat = ModelCat.new name: "Abraham", flying_distance: "5 miles"
+
+# so we simply ignore flying_distance
+model_cat.to_h # => { name: "Abraham", age: 0 }
+```
+
+This behaviour allows us to slice only necessary arguments for [body][body], [query][query], and [headers][headers] of a request.
+
+## Stringified Keys in Constructor
+
+Ahother difference between structs and models is that models can take hashes with both symbolic and string keys.
+
+This addition is useful when processing [responses][response]:
+
+```ruby
+# This works even though JSON#parse returns a hash with string keys
+ModelCat.new JSON.parse('{"age":4}')
+```
+
+## Equality
+
+Models, whose methods `to_h` returns equal hashes, are counted as equal.
+
+[dry-initializer]: http://dry-rb.org/gems/dry-initializer
+[dry-struct]: http://dry-rb.org/gems/dry-struct
+[dry-types]: http://dry-rb.org/gems/dry-types
+[body]:
+[headers]:
+[query]:
+[response]:

data/docs/path.md

@@ -0,0 +1,48 @@
+Use `path` to define operation's path that is relative to the [base url][base_url].
+
+```ruby
+operation :find_cats do
+  path { "cats" }
+end
+```
+
+Notice that a value should be wrapped into the block. This is necessary to build paths dependent on arguments of the request. The following definition inserts a mandatory id from options:
+
+```ruby
+operation :find_cat do
+  path { |id:, **| "cats/#{id}" }
+end
+
+# later at a runtime
+client.operations[:find_cat].call id: 98 # sends to "/cats/98"
+```
+
+As usual, you have access to current settings. This can be useful to add client tokens to paths when necessary:
+
+```ruby
+operation :find_cats do |settings|
+  path { "cats/#{settings.token}" }
+end
+```
+
+## Default Path
+
+You can set a default path for all operations. Use it to DRY clients whose operations differs not by endpoints, but, for example, by parameters ([query][query], [body][body]) of various requests:
+
+```ruby
+operation do
+  path { "cats" }
+end
+
+operation :find_cats do
+  # sends requests to "/cats"
+end
+
+operation :find_details do
+  path { "cats/details" } # reloads default setting
+end
+```
+
+[base_url]:
+[query]:
+[body]:

data/docs/query.md

@@ -0,0 +1,99 @@
+Use `query` to add some data to the request query. The syntax is pretty the same as for [body][body] and [headers][headers].
+
+```ruby
+operation :find_cat do |settings|
+  # ...
+  path { "cats" }
+  query do
+    attribute :token, default: proc { settings.token }
+    attribute :id
+  end
+end
+
+# Later at the runtime it will send a request to "../cats?id=4&token=foo"
+client.operations[:find_cat].call id: 4, token: "foo"
+```
+
+## Nested Data Representation
+
+Nested data are represented in a query following Rails convention:
+
+```ruby
+client.operations[:find_cat].call id: [{ key: 4 }], token: ["foo"]
+# "/cats?id[][key]=4&token[]=foo"
+```
+
+Non-unicode symbols are encoded as defined in [RFC-3986][rfc-3986]
+
+## Model-Based Queries
+
+Use [models][model] to provide validation of query data:
+
+```ruby
+class Cat < Evil::Client::Model
+  attribute :name,  type: Dry::Types["strict.string"], optional: true
+  attribute :age,   type: Dry::Types["strict.int"],    default:  proc { 0 }
+  attribute :color, type: Dry::Types["strict.string"]
+end
+```
+
+You can either restrict `type` of an attribute:
+
+```ruby
+operation :create_cat do
+  query do
+    attribute :cat, type: Cat
+  end
+end
+
+# Later at runtime will send "...?cat[color]=tabby&cat[age]=0"
+client.operations[:create_cat].call cat: { color: "tabby" }
+```
+
+...or use in for the query as a whole under the `model` key:
+
+```ruby
+operation :create_cat do
+  query model: Cat
+end
+
+# Later at runtime will send "...?color=tabby&age=0"
+client.operations[:create_cat].call color: "tabby"
+```
+
+In the last case you can define additional attributes (this redefinition is local, it don't affect a model by itself):
+
+```ruby
+operation :create_cat do
+  query model: Cat do
+    attribute :mood, default: proc { "sleeping" }
+  end
+end
+
+# Later at runtime will send "...?color=tabby&age=0&mood=sleeping"
+client.operations[:create_cat].call color: "tabby"
+```
+
+**Be careful!** You cannot reload existing attributes (this will cause an exception). 
+
+In operations that update remote data you can skip some attributes (mark them `optional`). If you need to check responses strictly (to require all the necessary attributes), you should provide different models.
+
+```ruby
+# Requires remote server to return consistent beasts
+class Cat
+  attribute :id,   type: Dry::Types["strict.int"].constrained(gt: 0)
+  attribute :age,  type: Dry::Types["strict.int"]
+  attribute :name, type: Dry::Types["strict.string"]
+end
+
+# Allows updating attributes when necessary
+class CatUpdate
+  attribute :age,  type: Dry::Types["coercible.int"],    optional: true
+  attribute :name, type: Dry::Types["coercible.string"], optional: true
+end
+```
+
+[rfc-3986]: https://tools.ietf.org/html/rfc3986
+[body]:
+[headers]:
+[model]: