ezclient 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a33b8998ea8d1bc9064fe5756119e298e054e27fc521cac42a0d9260e59b924
-  data.tar.gz: b18b2ea63f170e11753e516615834775facfac462084c689f3ec1d7d3467da5c
+  metadata.gz: 6d9f110bfae1ffb37a3ed9bdeb162487717a243178175822b9e0152df2533288
+  data.tar.gz: 7f1380b423969a1101648fa5017f3e70c3ffbff774156068337fb839cab5854d
 SHA512:
-  metadata.gz: 8357a3071ed41858d52f27639fb6c72c90915d5fe46a10da91ec59bd711ef577f8b2e2970d2e6d364276321c1502f6b768ad557bd8a2f1ff52e283ce323e9c6d
-  data.tar.gz: dd8116c2553ee074b89b9a18d3595899f3e54a4adaf8e65dec8384a011a2b8de3a783277eb066dd5ccdb5059786e2cfaa580c9269374006f8b6fe0b79f2fbde4
+  metadata.gz: d2bf1f8d239320d4bc4b8a57b0d23208ec3700922eb4b2fe00cac386efb69ecc0961da46695697f2b9fc3aaa642f3f8fe47992f9cfa545a4aa971db4253b69d4
+  data.tar.gz: 49fb747c452aff9168492439f94324f911e8389ead521037f54e9480971394aeeca8ef90867542e8ee448ec6289c896be2bcd22b2a33ab0f332916b8eb795d8c

data/.travis.yml

@@ -3,9 +3,9 @@ language: ruby
 sudo: false
 
 rvm:
-  - 2.3.5
-  - 2.4.2
-  - 2.5.0
+  - 2.3
+  - 2.4
+  - 2.5
   - ruby-head
 
 before_install: gem install bundler
@@ -18,10 +18,9 @@ matrix:
   fast_finish: true
   # Only run RuboCop on the latest Ruby
   include:
-    - rvm: 2.5.0
+    - rvm: 2.5
       env: SUITE="rubocop"
   allow_failures:
     - rvm: ruby-head
-    - rvm: jruby-head
 
 cache: bundler

data/README.md

@@ -1,45 +1,124 @@
-# EzClient
-
+# EzClient   [![Gem Version](https://badge.fury.io/rb/ezclient.svg)](https://badge.fury.io/rb/ezclient) [![Build Status](https://travis-ci.org/umbrellio/ezclient.svg?branch=master)](https://travis-ci.org/umbrellio/ezclient) [![Coverage Status](https://coveralls.io/repos/github/umbrellio/ezclient/badge.svg?branch=master)](https://coveralls.io/github/umbrellio/ezclient?branch=master)
 EzClient is [HTTP gem](https://github.com/httprb/http) wrapper for easy persistent connections and more.
 
 ## Installation
-
-Add this line to your application's Gemfile:
+Add this lines to your application's Gemfile:
 
 ```ruby
 gem "ezclient"
-gem "http", github: "httprb/http"
+gem "http", github: "httprb/http" # version 3 is not supported for now
 ```
 
 ## Usage
 ```ruby
-client = EzClient.new(client_options)
-client.perform!(:get, "https://example.com", params: { a: 1 })
+url = "http://example.com"
+
+client_options = { timeout: 10 }
+client = EzClient.new(client_options) # => EzClient::Client object
+
+request_options = { params: { a: 1 } }
+request = client.request(:get, url, request_options) # => EzClient::Request object
+
 # Performs a GET request to https://example.com/?a=1
+response = request.perform # => EzClient::Response object
+
+# Same request but will raise EzClient::ResponseStatusError in case of 4xx or 5xx response code
+response = request.perform!
+
+# Alternatively, you can just do:
+response = client.perform!(:get, url, request_options) # => EzClient::Response object
 ```
 
 Valid client options are:
 - `api_auth` – arguments for `ApiAuth.sign!`
-- `keep_alive` – timeout for persitent connection
-- `max_retries` – max number of retries in case of errors
+- `basic_auth` – arguments for basic authentication (either a hash with `:user` and `:pass` keys or a two-element array)
+- `headers` – a hash of headers for requests
+- `keep_alive` – timeout for persistent connection in seconds
+- `max_retries` – maximum number of retries in case `retry_exceptions` option is provided
 - `on_complete` – callback called on request completion
 - `on_error` – callback called on request exception
-- `retry_exceptions` – exception classes to retry
-- `ssl_context` – ssl context for requests
-- `timeout` – timeout for requests
+- `on_retry` – callback called on request retry
+- `retry_exceptions` – an array of exception classes to retry
+- `ssl_context` – ssl context for requests (an `OpenSSL::SSL::SSLContext` instance)
+- `timeout` – timeout for requests in seconds
+
+All these options are passed to each request made by this client but can be overriden on per-request basis.
 
-Extra request options are:
+Extra per-request only options are:
+- `body` – raw request body
+- `form` – hash for urlencoded body
+- `json` – data for json (also adds `application/json` content-type header)
+- `metadata` – metadata for request (passed in callbacks)
 - `params` – becomes `query` for GET and `form` for other requests
 - `query` – hash for uri query
-- `form` – hash for urlencoded body
-- `body` – raw body
-- `json` – data for json
-- `headers` – headers for request
 
-## Contributing
+## Persistent connections
+If you provide `keep_alive` option to the client or particular request, the connection will be stored in the client and then
+reused for all following requests to the same origin within specified amount of time.
+
+Note that, as of now, EzClient will
+automatically retry the request on any `HTTP::ConnectionError` exception in this case which may possibly result in two requests
+received by a server (see https://github.com/httprb/http/issues/459).
+
+## Callbacks and retrying
+You can provide `on_complete`, `on_error` and `on_retry` callbacks like this:
+
+```ruby
+on_complete = -> (request, response, metadata) { ... }
+on_error = -> (request, error, metadata) { ... }
+on_retry = -> (request, error, metadata) { ... }
 
+client = EzClient.new(
+  on_complete: on_complete,
+  on_error: on_error,
+  on_retry: on_retry,
+  retry_exceptions: [StandardError],
+  max_retries: 2,
+)
+
+response = client.perform!(:get, url, metadata: :hello)
+```
+
+The arguments passed into callbacks are:
+- `request` – an `EzClient::Request` instance
+- `response` – an `EzClient::Response` instance
+- `error` – an exception instance
+- `metadata` - the `metadata` option passed into a request
+
+## Request object
+```ruby
+request = client.request(:post, "http://example.com", json: { a: 1 }, timeout: 15)
+
+request.verb # => "POST"
+request.url # => "http://example.com"
+request.body # => '{"a": 1}'
+request.headers # => { "Content-Type" => "application/json; charset=UTF-8", ... }
+```
+
+## Response object
+```ruby
+response = request.perform(...)
+
+response.body # => String
+response.headers # => Hash
+response.code # => Integer
+
+response.ok? # Returns if request was 2xx status
+response.redirect? # Returns if request was 3xx status
+response.client_error? # Returns if request was 4xx status
+response.server_error? # Returns if request was 5xx status
+response.error? # Returns if request was 4xx or 5xx status
+```
+
+## Contributing
 Bug reports and pull requests are welcome on GitHub at https://github.com/umbrellio/ezclient.
 
 ## License
+Released under MIT License.
+
+## Authors
+Created by Yuri Smirnov.
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+<a href="https://github.com/umbrellio/">
+<img style="float: left;" src="https://umbrellio.github.io/Umbrellio/supported_by_umbrellio.svg" alt="Supported by Umbrellio" width="439" height="72">
+</a>

data/lib/ezclient/check_options.rb

@@ -2,8 +2,10 @@
 
 module EzClient::CheckOptions
   def self.call(options, allowed_keys)
-    if (options.keys - allowed_keys).any?
-      raise ArgumentError, "Unrecognized options: #{options.keys.map(&:inspect).join(", ")}"
+    unknown_keys = options.keys - allowed_keys
+
+    if unknown_keys.any?
+      raise ArgumentError, "Unrecognized options: #{unknown_keys.map(&:inspect).join(", ")}"
     end
 
     options

data/lib/ezclient/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EzClient
-  VERSION = "0.10.0"
+  VERSION = "0.11.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ezclient
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Yuri Smirnov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-21 00:00:00.000000000 Z
+date: 2018-02-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http