network-client 2.0.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 69a4eea5e01f0c07a0728a987d1e8722edf1b228
-  data.tar.gz: b1a9d49d2f9e73c9a88eb3bd3956b2a1ebfe7202
+  metadata.gz: 8d744e4ef7f2447c1bcc600b3ce026b2de61fcfe
+  data.tar.gz: c31e62ada023d7b11efc60c709393943fb407141
 SHA512:
-  metadata.gz: ba909db3bb7de0357673b06bd444b107810bdf1796afd2dbf2e8fc3669c072157dbd0f31af601903c0ec895c55419ae83534e7d56710ce147433a724c0479cef
-  data.tar.gz: cd044bc44966fa7292741f9088a9be74ce2409e4099bfba6ec94fcd3582e755a071e09db9ce838f99966cc87612812896efc1174fa54659b1525b195ba4b3ff0
+  metadata.gz: 458e8ff4353c3bf358aadfd25a1ac3ee6dba002b7067e3b373be44d6c33c608b72bb13e7e60d469534056113e7ddbbbdd216ff1424cc2988303cb25891417277
+  data.tar.gz: 474215650614bd145967951af5a3ffc5011c780225137e6e1dc49fb2c4175d595b9d92cf291ef8daa6982f631683fc93cf472ff0be69da8846e1dc6ad4f82ce1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    network-client (2.0.0)
+    network-client (2.0.1)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,5 +1,7 @@
 # Network Client
+
 [![Gem Version](https://badge.fury.io/rb/network-client.svg)](https://rubygems.org/gems/network-client)
+[![Gem](https://img.shields.io/gem/dt/network-client.svg?colorB=8b0000)](https://rubygems.org/gems/network-client)
 [![Build Status](https://travis-ci.org/abarrak/network-client.svg?branch=master)](https://travis-ci.org/abarrak/network-client)
 [![Dependency Status](https://gemnasium.com/badges/github.com/abarrak/network-client.svg)](https://gemnasium.com/github.com/abarrak/network-client)
 [![Test Coverage](https://codeclimate.com/github/abarrak/network-client/badges/coverage.svg)](https://codeclimate.com/github/abarrak/network-client/coverage)
@@ -28,18 +30,204 @@ $ gem install network-client
 
 ## Usage
 
+#### Making JSON requests
+Given this client set up:
 
-For more details refer to [the API docuemntation](http://www.rubydoc.info/gems/network-client/).
+```ruby
+require "network-client"
 
-## Contributing
+client = Network::Client.new(endpoint: 'https://jsonplaceholder.typicode.com')
+```
+
+We can perform the following requests:
+
+  * **GET**
+
+  ```ruby
+  client.get '/todos/10'
+  
+  #=> #<struct Network::Client::Response code=200,
+        body={"userId"=>1, "id"=>10, "title"=>"illo est ...", "completed"=>true}>
+  ```
+
+  * **POST**
+
+  ```ruby
+  client.post '/todos', params: { title: 'foo bar', completed: 'false', userId: 1 }.to_json
+
+  #=> #<struct Network::Client::Response code=201,
+        body={"title"=>"foo bar", "completed"=>false, "userId"=>1, "id"=>201}> 
+  ```
+
+  * **PATCH**
+
+  ```ruby
+  client.patch '/todos/10', params: { title: 'new title' }.to_json
+
+  #=> #<struct Network::Client::Response code=200,
+        body={"userId"=>1, "id"=>10, "title"=>"new title", "completed"=>true}> 
+  ```
+
+  * **PUT**
+
+  ```ruby
+    client.put '/todos/43', params: { completed: false }.to_json
+
+    #=> #<struct Network::Client::Response code=200, body={"completed"=>false, "id"=>43}> 
+  ```
+
+  * **DELETE**
+
+  ```ruby
+  client.delete '/todos/25'
+
+  #=> #<struct Network::Client::Response code=200, body={}>
+  ```
+
+#### Returned Response
+
+As appears in previous examples, the returned value of each successful request is a `Response` struct. 
+It holds the response's HTTP code and body parsed as JSON.
+
+```ruby
+response = client.get '/posts/30'
+response.code #=> 200
+response.body #=> { "userId"=>3, "id"=>30, "title"=>"a quo magni similique perferendis", 
+                    "body"=>"alias dolor cumque ..." }
+```
+
+#### Setting Request Headers
+Since this is mainly JSON web client, `Accept` and `Content-Type` headers are set to json by default.
+
+You can override them and set extra headers during initialization by providing `headers:` argument:
+
+```ruby
+headers = { 'X-SPECIAL-KEY' => '123456' }
+client = Network::Client.new(endpoint: 'https://api.example.com', headers: headers)
+```
+
+Or on request basis with the `headers:` argument too:
+
+```ruby
+client.get 'posts/', headers: { 'X-SPECIAL-KEY' => '123456' }
+```
+
+#### HTTP Authentication
+
+  1. **Basic:**
+  ```ruby
+  # using `username` and `password` named parameters when initialized:
+
+  client = Network::Client.new(endpoint: 'https://api.example.com',
+                               username: 'ABC', 
+                               password: '999')
+  client.username #=> "ABC"
+  client.password #=> "999"
+
+  # or via `#set_basic_auth`:
+
+  client.set_basic_auth('John Doe', '112233')
+  client.username #=> "John Doe"
+  client.password #=> "112233"
+  ```
+
+  2. **OAuth Bearer:**
+  ```ruby
+  client.set_bearer_auth(token: 'e08f7739c3abb78c')
+  client.bearer_token 
+  #=> "e08f7739c3abb78c"
+  ```
 
+  3. **Token Based:**
+  ```ruby
+  client.set_token_auth(header_value: 'Token token=sec_key_aZcNRzoCMpmdMEP4OEeDUQ==')
+  client.auth_token_header
+  #=> "Token token=sec_key_aZcNRzoCMpmdMEP4OEeDUQ=="
+  ```
+
+#### Customizing User Agent
+You can set the user agent header during initialization:
+
+```ruby
+client = Network::Client.new(endpoint: 'https://maps.googleapis.com', user_agent: 'App Service')
+client.user_agent #=> "App Service"
+```
+
+Or later on via `#set_user_agent` method:
+
+```ruby
+client.set_user_agent('Gateway Server')
+client.user_agent #=> "Gateway Server"
+```
+
+The default user agent is `Network Client`.
+
+#### Retry and Error Handling
+Set the `tries:` named argument to define the number of tries when request fails with one of the retryable errors.
+
+```ruby
+client = Network::Client.new(endpoint: 'https://api.foursquare.com', tries: 3)
+client.tries #=> 3
+```
+
+The default `#tries` is 2.
+
+To retrieve or extend the list of triable errors through `#errors_to_recover`:
+
+```ruby
+client.errors_to_recover
+
+#=> [Net::HTTPTooManyRequests, Net::HTTPServerError, Net::ProtocolError,
+     Net::HTTPBadResponse,Net::ReadTimeout, Net::OpenTimeout, Errno::ECONNREFUSED,
+     Errno::ETIMEDOUT, OpenSSL::SSL::SSLError, SocketError]
+
+client.errors_to_recover << Net::HTTPRequestTimeOut
+
+#=> [Net::HTTPTooManyRequests, Net::HTTPServerError, Net::ProtocolError,
+     Net::HTTPBadResponse,Net::ReadTimeout, Net::OpenTimeout, Errno::ECONNREFUSED,
+     Errno::ETIMEDOUT, OpenSSL::SSL::SSLError, SocketError, Net::HTTPRequestTimeOut]
+```
+
+The list of `errors_to_propagate` takes precedence over `errors_to_recover`, and they are not retried.
+
+You can retrieve them for rescue in your application layer, and extend them too.
+
+```ruby
+client.errors_to_propagate
+#=> [Net::HTTPRequestURITooLong, Net::HTTPMethodNotAllowed]
+
+client.errors_to_propagate << Net::HTTPNotAcceptable
+#=> [Net::HTTPRequestURITooLong, Net::HTTPMethodNotAllowed, Net::HTTPNotAcceptable]
+```
+
+*Be careful not to add ancestor error class (higher in the inheritance chain) as it will prevent any of it's descendant classes from getting retried. Unless this is an intended behavior, of course.*
+
+#### Logger
+When `Rails` is in scope, it's logger will be used by default.
+
+If not, then it defaults to a fallback logger that writes to `STDOUT`.
+
+Additionally, you can override with your custom logger by supplying block to `#set_logger` like so:
+
+```ruby
+client = Network::Client.new(endpoint: 'https://api.foursquare.com')
+
+client.set_logger { Logger.new(STDERR) }
+client.logger
+#=> #<Logger:0x007fb3cd136d38 @progname=nil, @level=0, @default_formatter=#<Logger::Formatter:0x007fb3cd136d10 @datetime_format=nil>, @formatter=nil, @logdev=#<Logger::LogDevice:0x007fb3cd136c98 @shift_size=nil, @shift_age=nil, @filename=nil, @dev=#<IO:<STDERR>>, @mon_owner=nil, @mon_count=0, @mon_mutex=#<Thread::Mutex:0x007fb3cd136c70>>>
+```
+
+## Documentation
+For more details, please refer to [the API documentation](http://www.rubydoc.info/gems/network-client/2.0.1/Network/Client).
+
+## Contributing
 Bug reports and pull requests are very much appreciated at [Github](https://github.com/abarrak/network-client).
 
   - Fork The repository.
-  - Create a branch with a clear name.
-  - Make your changes (Please also add/change test, README if applicable).
-  - Push changes to the created branch
-  - Create an Pull Request
+  - Create a branch with the fix or feature name.
+  - Make your changes (with test or README changes/additions if applicable).
+  - Push changes to the created branch.
+  - Create an Pull Request.
   - That's it!
 
 

data/lib/network/client.rb

@@ -1,12 +1,16 @@
+# frozen_string_literal: true
 require 'net/http'
 require 'openssl'
 require 'json'
 require 'logger'
 
 module Network
+  # This class is simple +JSON+ client that is meant to be initialized with a single URI.
+  # Subsequent calls should target endpoints/paths of that URI.
   class Client
-    DEFAULT_HEADERS = { 'accept' => 'application/json',
-                        'Content-Type' => 'application/json' }.freeze
+    DEFAULT_HEADERS = { 'Accept' => 'application/json', 'Content-Type' => 'application/json' }
+
+    ##
     # The success response template.
     #
     # Represents the return of rest-like methods holding two values:
@@ -14,7 +18,7 @@ module Network
     Response = Struct.new(:code, :body)
 
     # Stamp in front of each log written by client +@logger+.
-    LOG_TAG = '[NETWORK CLIENT]:'.freeze
+    LOG_TAG = '[NETWORK CLIENT]:'
 
     attr_reader :username, :password, :default_headers, :logger, :tries, :user_agent,
                 :bearer_token, :auth_token_header
@@ -54,18 +58,18 @@ module Network
     #         ... }
     #
     def initialize(endpoint:, tries: 2, headers: {}, username: nil, password: nil,
-                   user_agent: 'network-client gem')
+                   user_agent: 'Network Client')
       @uri = URI.parse(endpoint)
       @tries = tries
 
       set_http_client
+      define_error_strategies
       set_default_headers(headers)
       set_basic_auth(username, password)
+      set_bearer_auth
+      set_token_auth
       set_logger
-      define_error_strategies
       set_user_agent(headers['User-Agent'] || user_agent)
-      set_bearer_auth
-      set_custom_token_auth
     end
 
     ##
@@ -198,7 +202,7 @@ module Network
     # == Returns:
     # [@auth_token_header] +string+ the newly assigned +@auth_token_header+ value.
     #
-    def set_custom_token_auth(header_value: '')
+    def set_token_auth(header_value: '')
       @auth_token_header = header_value
     end
 
@@ -327,7 +331,7 @@ module Network
 
     def formulate_path(path)
       path = '/'  if path.nil? || path.empty?
-      path.strip! if path.respond_to?(:strip)
+      path = path.strip if path.respond_to?(:strip)
       path.prepend('/') unless path.chars.first == '/'
       path
     end

data/lib/network/version.rb

@@ -1,3 +1,3 @@
 module Network
-  VERSION = "2.0.0"
+  VERSION = "2.0.1"
 end

data/network-client.gemspec

@@ -12,9 +12,9 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Abdullah Barrak (abarrak)"]
   spec.email         = ["abdullah@abarrak.com"]
 
-  spec.summary       = "A thin resilient wrapper around ruby's Net::HTTP."
-  spec.description   = "network-client gem is almost a drop-in thin layer around Net::HTTP classes \
-                        with simple error handling and retry functionality implemented."
+  spec.summary       = "A thin resilient JSON web client built around Net::HTTP"
+  spec.description   = "network-client is a drop-in thin layer on top of Net::HTTP classes for \
+                        JSON web requests with retry functionality and simple error handling"
   spec.homepage      = "https://github.com/abarrak/network-client"
   spec.license       = "MIT"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: network-client
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.0.1
 platform: ruby
 authors:
 - Abdullah Barrak (abarrak)
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-07-01 00:00:00.000000000 Z
+date: 2017-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -108,8 +108,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.2'
-description: network-client gem is almost a drop-in thin layer around Net::HTTP classes                         with
-  simple error handling and retry functionality implemented.
+description: network-client is a drop-in thin layer on top of Net::HTTP classes for                         JSON
+  web requests with retry functionality and simple error handling
 email:
 - abdullah@abarrak.com
 executables: []
@@ -153,5 +153,5 @@ rubyforge_project:
 rubygems_version: 2.6.11
 signing_key: 
 specification_version: 4
-summary: A thin resilient wrapper around ruby's Net::HTTP.
+summary: A thin resilient JSON web client built around Net::HTTP
 test_files: []