evil-client 0.3.3 → 1.0.0

data/docs/base_url.md

@@ -1,38 +0,0 @@
-Use `base_url` to define a base url, [operation paths][path] are relative to.
-
-You can use [`settings`][settings] as the only argument of the declaration block.
-
-```ruby
-require "evil-client"
-require "dry-types"
-
-class CatsClient < Evil::Client
-  settings do
-    option :version, type: Dry::Types["coercible.int"], default: proc { 1 }
-  end
-  
-  base_url do |settings|
-    "https://cats.example.com/v#{settings.version}"
-  end
-  
-  operation :find_cats do |_settings|
-    http_method :get
-    path { "cats" }
-  end
-end
-```
-
-After a client's instantiation...
-
-```ruby
-client = CatsClient.new version: 3
-```
-
-...the following call will send a request `GET https://example.com/v3/cats`.
-
-```ruby
-client.operations[:find_cat].call
-```
-
-[settings]:
-[path]:

data/docs/documentation.md

@@ -1,9 +0,0 @@
-Use the `documentation` to provide reference to online docs for the current operation.
-
-```ruby
-operation :find_cat do |settings| # remember that you have access to settings
-  documentation "https://cats.example.com/v#{settings.version}/docs/find_cats"
-end
-```
-
-The link will be shown in exceptions risen when either request or response mismatches type constraints.

data/docs/headers.md

@@ -1,59 +0,0 @@
-Use method `headers` to add several headers to a request. The declaration should have a block with several `attributes` describing corresponding headers.
-
-```ruby
-operation :find_cat do |settings|
-  headers do
-    attribute :token if settings.version > 1
-    attribute :id
-  end
-end
-```
-
-The syntax of the attribute declaration is exactly the same as of [Evil::Struct][model]. Type constraints and default values are available.
-
-All values for the headers will be taken from a request options:
-
-```ruby
-# Sends a request with headers { "id" => 43 }
-client.options[:find_cat].call id: 43
-```
-
-As a rule, you shouldn't define authorization headers in this way. Use [the security method][security] instead.
-
-Default headers can be declared for every request via anonymous operation. **Notice** that a default headers can be reloaded for specific operation as a whole. New declaration will overwrite all the default set headers instead of merging to them.
-
-```ruby
-operation do
-  headers do
-    attribute :id
-  end
-end
-
-operation :find_cat do
-  headers do
-    attribute :cat_id
-  end
-end
-
-# later at the runtime the following call
-# will send request with { "cat_id" => 4 } header only
-client.operations[:find_cat].call id: 1, cat_id: 4
-```
-
-According to [RFC-2616][rfc-2616], headers are case-insensitive. Inside [middleware][middleware] they are forced to lower case.
-
-For example, while the following declaration is valid by itself, only value from `Foo` option will be sent to remote server:
-
-```ruby
-operation do
-  headers do
-    attribute :foo
-    attribute :Foo
-  end
-end
-```
-
-[rfc-2616]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2
-[security]:
-[model]:
-[middleware]:

data/docs/http_method.md

@@ -1,31 +0,0 @@
-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/model.md

@@ -1,173 +0,0 @@
-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::Struct` and define its attributes.
-
-```ruby
-class Cat < Evil::Struct
-  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::Struct
-  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::Struct` 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::Struct
-  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

@@ -1,48 +0,0 @@
-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

@@ -1,99 +0,0 @@
-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::Struct
-  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]: