evil-client 0.3.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d05eb1654246a3c8ebda837f8e292fa356bca35e
-  data.tar.gz: 9685ee8ea9bf347a54c794ca7c83b612eb206912
+  metadata.gz: 1a0f6860291b235077bd6d9063eb9e1ec47cb9ef
+  data.tar.gz: cbb9aca48a0283cf8e6ec84bec9444ea74bb440c
 SHA512:
-  metadata.gz: '09241951f999f8909d4000e5b7ec81bab248729125bdd040f23d2162ab2f8739eb55d9c4f736fc72fc63750e7ebe48a62b0b13fecc82deaa01ccbdc839c76813'
-  data.tar.gz: eade03b9334d111284a7c08d81a30f0bf5457a24b5ae7bec0a5461fe8f162a6e41fa9ff6833b1fc89db83a5583ab0c3999696e9cdf7cb1f9fb70d539103e93c7
+  metadata.gz: c1d2c2e407c90ef12db1d58c4aed5fef1a4c851934f90e25602ad5461c14278e30dcd3a1dbc7534dc17218797d46dedaa8f023389be46625f66bb046a06791a5
+  data.tar.gz: 433099e8dcebb8e48e0f22f057db11c68eb78556a1660508bdd22a261a40ad2c59407971459716c027d7c5d4b7cf122b2c03fa63d3308b06762e5658f3e7d763

data/.codeclimate.yml

@@ -2,17 +2,6 @@
 engines:
   rubocop:
     enabled: true
-    checks:
-      Rubocop/Style/FrozenStringLiteralComment:
-        enabled: false
-      Rubocop/Style/Documentation:
-        enabled: false
-      Rubocop/Style/ClassAndModuleChildren:
-        enabled: false
-      Rubocop/Style/SpaceInLambdaLiteral:
-        enabled: false
-      Style/SingleLineBlockParams:
-        enabled: false
 ratings:
   paths:
     - "lib/**.rb"

data/.gitignore

@@ -8,3 +8,4 @@
 /spec/reports/
 /tmp/
 /.rubocop.todo.yml
+/.rspec_status

data/.rspec

@@ -1,3 +1,2 @@
 --require spec_helper
---format documentation
 --color

data/.rubocop.yml

@@ -1,41 +1,44 @@
 ---
 AllCops:
-  DisplayCopNames:    true
-  DisplayStyleGuide:  true
-  StyleGuideCopsOnly: true
-  TargetRubyVersion:  2.3
+  DisplayCopNames:   true
+  TargetRubyVersion: 2.3
 
-Style/CaseEquality:
+Lint/AmbiguousBlockAssociation:
   Enabled: false
 
-Style/Documentation:
+Metrics/BlockLength:
   Enabled: false
 
-Style/FileName:
-  Exclude:
-    - lib/evil-client.rb
-
-Style/Lambda:
+Style/Alias:
   Enabled: false
 
-Style/LambdaCall:
+Style/ClassAndModuleChildren:
   Enabled: false
 
-Style/MethodMissing:
-  Enabled: false
-
-Style/MultilineMethodCallIndentation:
+Style/FileName:
   Exclude:
-    - spec/**.rb
+    - lib/evil-client.rb
 
-Style/NumericPredicate:
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/ModuleFunction:
   Enabled: false
 
 Style/RaiseArgs:
   Enabled: false
 
 Style/RescueModifier:
-  Enabled: false
+  Exclude:
+    - '**/*_spec.rb'
+
+Style/Semicolon:
+  Exclude:
+    - '**/*_spec.rb'
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes
+
+Style/SingleLineMethods:
+  Exclude:
+    - '**/*_spec.rb'

data/.travis.yml

@@ -7,6 +7,7 @@ script:
   - bundle exec rubocop
 rvm:
   - '2.3.0'
+  - '2.4.0'
   - ruby-head
   - jruby-9.1.0.0
   - jruby-head

data/CHANGELOG.md

@@ -4,9 +4,254 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog], and this project adheres
 to [Semantic Versioning].
 
-## [0.3.3] - [2017-07-14]
+## [1.0.0] [2017-08-06]
+
+This is a total new reincarnation of the gem. I've changed its
+architecture for consistency and unification reasons. This version is
+backward-incompatible to all the previous ones up to the [0.3.3].
+
+Its DSL was re-written and regularized as well. While the idea of the gem
+remains about the same as before, its implementation has been changed
+drastically in many important details.
+
+### [BREAKING] Changed
+
+- There is no more differencies between "root" DSL, DSL of scope and
+  operation. All scopes use exactly the same methods. All operations
+  uses just the same methods except for `#operation` and `#scope` that
+  provide further nesting.
+
+  Any customization (inside a sub-scope or operation of some scope)
+  re-loads previous definitions in the following order:
+
+  ```text
+  root operation(anonymous)
+    subscope operation(anonymous)
+      # ...
+        custom(named) operation
+  ```
+
+- Unlike previous versions every named operation belongs to some scope
+  (possibly nested into parents ones). Operations/subscopes should
+  have unique names inside its scope only (no more global namespace
+  for all operations).
+
+  Every scope knows the list of its subscopes and operations like:
+
+  ```ruby
+  MyClient.new.scopes[:users].operations[:fetch]
+  ```
+
+- You can describe operations step-by-step. For example, you have
+  to describe `path` of root anonymous operation. Later you can add subpath
+  in the corresponding operation or scope:
+
+  ```ruby
+  class MyClient
+    option :subdomain
+    path { "https://#{subdomain}.foobar.com" } # same as base_path
+
+    scope :users do
+      option :version
+
+      # makes full path "https://{subdomain}.foobar.com/v{version}/users"
+      path { "v#{version}/users" }
+
+      operation :fetch do
+        option :id
+
+        # the final path: "https://{subdomain}.foobar.com/v{version}/users/{id}"
+        path { id }
+      end
+    end
+  end
+  ```
+
+- As a syntax sugar all undefined methods are delegated to subscopes
+  and operations.
+
+  Instead of full syntax:
+
+  ```ruby
+  MyClient.new
+          .scopes[:users][version: "1.1"]
+          .operations[:fetch][id: 7]
+          .call
+  ```
+
+  You can use more natural one:
+
+  ```ruby
+  MyClient.new.users(version: "1.1").fetch(id: 7)
+  ```
+
+- Every scope or operation takes some options.
+  Defined options are inherited and collected from the very root of the client:
+
+  ```ruby
+  client = MyClient.new token: "foo", bar: :baz
+  client.options # => { token: "foo" }
+
+  users = client.users(version: 3)
+  users.options # => { token: "foo", version: 3 }
+
+  fetch = users.operations[:fetch][id: 7]
+  fetch.options # => { token: "foo", version: 3, id: 7 }
+  ```
+
+- You can reload assigned options at any level of nesting
+
+  ```ruby
+  users.options # => { token: "foo", version: 3 }
+  
+  fetch = users.operations[:fetch][id: 7, token: "baz"]
+  fetch.options # => { token: "baz", version: 3, id: 7 }
+  ```
+
+- When adding an option you can define the necessary coercers, default values
+  and requirements using the [dry-initializer] gem API.
+
+  ```ruby
+  class MyClient
+    option :token,     proc(&:to_s)  # required
+    option :subdomain, proc(&:to_s), default: { "europe" }
+  end
+  ```
+
+- In addition you can define validator to check whether options
+  correspond to each other:
+
+  ```ruby
+  class MyClient
+    option :token,    optional: true
+    option :password, optional: true
+
+    validate(:valid_credentials) { token.nil? ^ password.nil? }
+  end
+  ```
+
+  You have to add i18n localization for that errors:
+
+  ```yaml
+  # config/locales/evil-client.en.yml
+  en:
+    evil:
+      client:
+        errors:
+          my_client:
+            valid_credentials: "You should set either token or password"
+  ```
+
+  All validations from root will be applied at every single instance
+  (of subscope or operation). Every time we validate current (reloaded) options.
+
+- The method `let` allows to define custom memoizers:
+
+  ```ruby
+  class MyClient
+    option :first_name, proc(&:to_s)
+    option :last_name,  proc(&:to_s)
+
+    let(:full_name) { [first_name, last_name].join(" ") }
+  end
+  ```
+
+  Such memoizers are available in validators and request/response declarations.
+
+- Definitions of request/response parts can be made ether as a plain values
+
+  ```ruby
+  class MyClient
+    path "https://api.example.com"
+  end
+  ```
 
-On the road to v0.3.3
+  or via blocks:
+
+  ```ruby
+  class MyClient
+    option :subdomain
+
+    path { "https://#{subdomain}.example.com" }
+  end
+  ```
+
+  Inside the block you can access all the current options.
+
+- Some upper-level operation definitions (path, query, and headers)
+  are updated by nested definitions, while the others (http_method, format,
+  security settings, request body, and response handler) will be reloaded.
+
+  For example, you can define some shared headers at the client (root) level,
+  then add some scope/operation-specific headers later. Or you can define
+  security schema by default, and reload it for a specific operation.
+
+- I found customization of underlying client an overkill. That's why
+  all clients will be based on the same old Net::HTTP(S) connection.
+
+  But the client connection is just the object with the only required method
+  `#call` taking rack-compatible env, and returning rack-compatible response.
+
+  You can define your own connection for a client:
+
+  ```ruby
+  my_connection = double call: [200, {}, []]
+
+  class MyClient
+    connection = my_connection
+  end
+  ```
+
+- You can define a middleware for every single operation -- exactly
+  in the same way as other parts of operation specification.
+
+  All middleware will be used in the order of their definition:
+
+  ```ruby
+  class MyClient
+    middleware Foo
+
+    scope :users do
+      middleware { [Bar, Baz] }
+    end
+  end
+  ```
+
+  In the above example rack env will be sent to Foo -> Bar -> Baz -> Connection,
+  and rack response will be processed by Connection -> Baz -> Bar -> Foo.
+
+- I've simplified some definitions in the OperationDSL.
+
+  Now you should define `headers` and `query` as a simple hashes (no helpers).
+  That hashes will be merged to upper-level ones (that's how we customize them).
+
+  You can also define body as either hash, or IO (for files), depending
+  on request format.
+
+  You have to define a format for operation via special `format` helper
+  (:json by default, :form, :text, :multipart are available as well):
+
+  ```
+  operation :upload do
+    option :multipart, default: proc { File.new "Hi!" }
+
+    format { :files } # :json (default), :text, and :form are supported as well
+    body   { [StringIO.new, "Hi!"] }
+  end
+  ```
+
+  Because `format` takes a block, you can customize its value depending
+  on any option(s).
+
+- Response handlers take a block with rack request: [status, headers, [body]]
+
+  There is no dsl for processing that responses (because it can be anything).
+  You don't need to provide models (but you can do it on your own), or
+  validate responses in any special way. Do your best!
+
+- No more dependencies from both the `dry-types` and `evil-struct`.
+
+## [0.3.3] - [2017-07-14]
 
 ### Fixed
 - dependency from 'securerandom' standard library (nepalez)
@@ -16,8 +261,6 @@ On the road to v0.3.3
 
 # [0.3.2] - [2016-11-29]
 
-On the road to v0.4.0
-
 ### Fixed
 - Query and body encoding (nepalez)
 
@@ -36,7 +279,7 @@ On the road to v0.4.0
 
 This version changes the way of processing responses. Instead of dealing
 with raw rake responses, we add opinionated methods to gracefully process
-responses from JSON or plain text.
+responses from JSON or form text.
 
 In the next minor versions processors for both "form" and "file" (multipart)
 formats will be added.
@@ -59,7 +302,7 @@ formats will be added.
 
   This time response handler will try processing a response using various
   definitions (in order of their declaration) until some suits. The hanlder
-  returns `UnexpectedResponseError` in case no definition proves suitable.
+  returns `ResponseError` in case no definition proves suitable.
 
   Names (the first param) are unique. When several definitions use the same name,
   only the last one will be applicable.
@@ -83,8 +326,10 @@ formats will be added.
   response :not_found, 404, format: "json", raise: true
   ```
 
+[1.0.0]: https://github.com/evilmartians/evil-client/compare/v0.3.3...v1.0.0
 [0.3.3]: https://github.com/evilmartians/evil-client/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/evilmartians/evil-client/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/evilmartians/evil-client/compare/v0.3.0...v0.3.1
 [Keep a Changelog]: http://keepachangelog.com/
 [Semantic Versioning]: http://semver.org/
+[dry-initializer]: http://github.com/dry-rb/dry-initalizer

data/LICENSE.txt

@@ -1,6 +1,8 @@
 The MIT License (MIT)
 
-Copyright (c) 2016-2017 Andrew Kozin (nepalez), andrew.kozin@gmail.com
+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/README.md

@@ -13,15 +13,7 @@ Human-friendly DSL for writing HTTP(s) clients in Ruby
 
 ## Intro
 
-The gem allows writing http(s) clients in a way close to [Swagger][swagger] specifications. Like in Swagger, you need to specify models and operations in domain-specific terms. In addition, the gem supports settings and 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). Its DSL is backed on top of [dry-initializer][dry-initializer] gem, and supposes heavy usage of [dry-types][dry-types] system of contracts.
-
-For now the DSL supports clients to **json** and **form data** APIs out of the box. Because of high variance of XML-based APIs, building corresponding clients require more efforts on a middleware level.
-
-[swagger]: http://swagger.io
-[dry-initializer]: http://dry-rb.org/gems/dry-initializer
-[dry-types]: http://dry-rb.org/gems/dry-types
+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).
 
 ## Installation
 
@@ -45,97 +37,69 @@ $ gem install evil-client
 
 ## 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
-  # Prepare client-specific model of cat (the furry pinnacle of evolution)
-  class Cat < Evil::Struct
-    attribute :name,  Dry::Types["strict.string"], optional: true
-    attribute :color, Dry::Types["strict.string"]
-    attribute :age,   Dry::Types["coercible.int"], default: proc { 0 }
-  end
-
-  # Define settings the client initialized with
-  # The settings parameterizes operations when necessary
-  settings do
-    param  :domain,   Dry::Types["strict.string"] # required!
-    option :version,  Dry::Types["coercible.int"], default: proc { 0 }
-    option :user,     Dry::Types["strict.string"] # required!
-    option :password, Dry::Types["strict.string"] # required!
-  end
-
-  # Define a base url using
-  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
-      attributes optional: true do
-        attribute :name
-        attribute :color
-        attribute :age
-      end
-    end
-
-    # Parses json response and wraps it into Cat instance with additional
-    # parameter
-    response 200, format: :json, model: Cat do
-      attribute :success # add response-specific attribute to the cat
-    end
-
-    # Parses json response, wraps it into model with [#error] and raises
-    # an exception where [ResponseError#response] contains the model istance
-    response 422, format: :json, raise: true do
-      attribute :error
-    end
+  path     { "https://#{domain}.example.com/api" }
+  security { basic_auth settings.user, settings.password }
 
-    # Takes raw body and converts it into the hashie
-    response 404, raise: true do |body|
-      Hashie::Mash.new error: body
-    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)
 ```
 
@@ -145,11 +109,13 @@ The gem is available as open source under the terms of the [MIT License](http://
 
 [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
 [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