wrappi 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08d106729153dd903d35de0503fb9534c2ed44b2c1ecce9dbb466a7bb7b50681'
-  data.tar.gz: b46480380433093b90d10c1f35121ef342439acd0a7379dbdb2037feee254828
+  metadata.gz: d76d08b4ea48473c331491f345bf3349020d2939038abab2df92c6b2ee39a159
+  data.tar.gz: c17875fe3958e459610c7996f285e493f50b589e053703a5a14aefd54c1061d7
 SHA512:
-  metadata.gz: fa76a8e7296b86b92960609923faff2187e2f368574e71ce054538facd2e999138d6c744b7f2f6e98b7688360ec2973952c590c7171237a70b5cf94cd994f964
-  data.tar.gz: 4dcc8da672cc92e2fc7dbe013752acad62a2c5f9eb8fdafc39ffe22ead09d9a3ff9a638b770907d9ff595dbc6d36c3467fe9714368d186126e61584f74b2d44e
+  metadata.gz: '03181ab50cbfeb1e55b408bf5d8fd11e919b9e6f6528ff0c4670b1296cac684fc67a0a29b376b292772cde316ed9cfe9a0e50475278c2a5da05946728afed817'
+  data.tar.gz: 289a464e32f98a82c0098e5372e96935377a8ec2c9da5c9f8d3f7c3e55bbc7d33542e51f7fe7c4b565b70fae787a1ee7186b1c95084ef6bb94bef31348f7f1e4

data/.travis.yml

@@ -7,11 +7,16 @@ rvm:
   - 2.4.4
   - 2.5.1
   - ruby-head
+matrix:
+  allow_failures:
+    - rvm: 2.3.7
+    - rvm: ruby-head
+  fast_finish: true
 before_install:
   - docker build -t dummy -f spec/dummy/Dockerfile .
-  - docker run -d -p 127.0.0.1:9873:9873 dummy
+  - docker run -d -p 127.0.0.1:9873:9873 dummy /bin/sh -c "bin/rails server -b 0.0.0.0 -p 9873"
   - docker ps -a
-  - gem install bundler -v 1.17.3
+  - gem install bundler
 script:
   - bundle exec rspec
 # Code climate test reporter

data/README.md

@@ -3,10 +3,12 @@
 [![Test Coverage](https://api.codeclimate.com/v1/badges/8751a0b6523a52b5e23e/test_coverage)](https://codeclimate.com/github/arturictus/wrappi/test_coverage)
 
 # Wrappi
+Making APIs fun again!
 
-Framework to create API clients.
-The intention is to bring the best practices and standarize the mess it's currently happening with the API clients.
-It allows to create API clients in a declarative way improving readability and unifying the behavior.
+Wrappi is a Framework to create API clients. The intention is to bring the best practices and standardize how API clients behave.
+It allows to create API clients in a declarative way improving readability and unifying the behavior. It abstracts complex operations like caching, retries background requests and error handling.
+
+Enjoy!
 
 ## Installation
 
@@ -29,7 +31,7 @@ Or install it yourself as:
 __Github example:__
 
 ```ruby
-module Github
+module GithubAPI
   class Client < Wrappi::Client
     setup do |config|
       config.domain = 'https://api.github.com'
@@ -49,13 +51,191 @@ end
 ```
 
 ```ruby
-user = Github::User.new(username: 'arturictus')
+user = GithubAPI::User.new(username: 'arturictus')
 user.success? # => true
 user.error? # => false
 user.status_code # => 200
 user.body # => {"login"=>"arturictus", "id"=>1930175, ...}
 ```
 
+#### Async
+Wrappi comes with a background Job out of the box. If you are in a Rails app the `#async`
+method will queue a new job (`< ActiveJob::Base`) that will make the request and trigger the async callback
+after the request is made.
+
+example:
+
+```ruby
+class User < Wrappi::Endpoint
+  client Client
+  verb :get
+  path "users/:username"
+  async_callback do |opts|
+    # this will be called in background after the request is made
+    if success?
+      if opts[:create]
+        CreateUserService.call(body)
+      elsif opts[:update]
+        UpdateUserService.call(body)
+      end
+    end
+  end
+end
+# This will execute the request in a background job
+Github::User.new(username: 'arturictus').async(create: true)
+```
+
+If you need to send options to your Job (the `::set` method) you can pass the key `set`
+to the options.
+
+```ruby
+Github::User.new(username: 'arturictus').async(create: true, set: { wait: 10.minutes })
+```
+
+#### Cache
+You can enable cache per endpoint.
+
+Set the cache Handler in your client.
+It must behave like `Rails.cache` and respond to:
+  - `read([key])`
+  - `write([key, value, options])`
+
+```ruby
+class Client < Wrappi::Client
+  setup do |config|
+    config.domain = 'https://api.github.com'
+    config.cache = Rails.cache
+  end
+end
+```
+
+Enable cache in your endpoint.
+```ruby
+class User < Wrappi::Endpoint
+  cache true # enable for endpoint
+  client Client
+  verb :get
+  path "users/:username"
+end
+
+user = User.new(username: 'arturictus')
+user.response.class # => Wrappi::Response
+user.flush
+user.response.class # => Wrappi::CachedResponse
+user.success? # => true
+user.body # => {"login"=>"arturictus", "id"=>1930175, ...}
+```
+
+When cached the response will be a `Wrappi::CachedResponse`. `Wrappi::CachedResponse` behaves
+like `Wrappi::Response` that means you can use the endpoint in the same way as it was a non cached.
+See `cache_options` to fine tune your cache with expiration and other cache options.
+
+You can use options to cache a single request.
+
+```ruby
+class User < Wrappi::Endpoint
+  client Client
+  verb :get
+  path "users/:username"
+end
+User.new({username: 'arturictus'}, cache: true)
+user.response.class # => Wrappi::Response
+user.flush
+user.response.class # => Wrappi::CachedResponse
+user.success? # => true
+user.body # => {"login"=>"arturictus", "id"=>1930175, ...}
+```
+
+#### Retry
+Sometimes you want to retry if certain conditions affected your request.
+
+This will retry if status code is not `200`
+
+```ruby
+  class User < Wrappi::Endpoint
+    client Client
+    verb :get
+    path "users/:username"
+    retry_if do |response, endpoint|
+      endpoint.status_code != 200
+    end
+  end
+```
+
+Check more configuration options and examples for `retry_if` and `retry_options` below.
+
+#### Flexibility
+
+__options:__
+
+Pass a second argument with options.
+```ruby
+params = { username: 'arturictus' }
+options = { options_in_my_instance: "yeah!" }
+
+User.new(params, options)
+```
+
+__Dynamic configurations:__
+
+All the configs in `Endpoint` are evaluated at instance level except: `around_request` and `retry_if` because of their nature.
+That allows you to fine tune the configuration at a instance level.
+
+example:
+
+Right now the default for `cache` config is: `proc { options[:cache] }`.
+
+```ruby
+  class User < Wrappi::Endpoint
+    client Client
+    verb :get
+    path "users/:username"
+    cache do
+      if input_params[:username] == 'arturictus'
+        false
+      else
+        options[:cache]          
+      end
+    end
+  end
+```
+
+
+
+__endpoint is a ruby class:__ :open_mouth:
+
+```ruby
+  class User < Wrappi::Endpoint
+    client Client
+    verb :get
+    path "users/:username"
+    cache do
+      cache?
+    end
+
+    def cache?
+      if input_params[:username] == 'arturictus'
+        false
+      else
+        options[:cache]          
+      end
+    end
+
+    def parsed_response
+      @parsed_response ||= MyParser.new(body)
+    end
+  end
+```
+
+__inheritance:__
+All the configs will be inherited
+
+```ruby
+class UserDetail < User
+  path "users/:username/detail"
+end
+```
+
 ### Configurations
 
 #### Client
@@ -64,28 +244,32 @@ user.body # => {"login"=>"arturictus", "id"=>1930175, ...}
 |-----------------|--------------------------|--------------------------------------------------------------------------|----------|
 | domain          | String                   |                                                                          | *        |
 | params          | Hash                     |                                                                          |          |
-| logger          | Logger                   | Logger.new(STDOUT)                                                       |          |
 | headers         | Hash                     | { 'Content-Type' => 'application/json', 'Accept' => 'application/json' } |          |
-| ssl_context     | OpenSSL::SSL::SSLContext |                                                                          |          |
+| async_handler   | const                    | Wrappi::AsyncHandler                                                     |          |
+| cache           | const                    |                                                                          |          |
+| logger          | Logger                   | Logger.new(STDOUT)                                                       |          |
+| timeout         | Hash                     | { write: 9, connect: 9, read: 9 }                                        |          |
 | use_ssl_context | Boolean                  | false                                                                    |          |
+| ssl_context     | OpenSSL::SSL::SSLContext |                                                                          |          |
 
 #### Endpoint
 
-| Name             | Type                                     | Default                 | Required |
-|------------------|------------------------------------------|-------------------------|----------|
-| client           | Wrappi::Client                           |                         | *        |
-| path             | String                                   |                         | *        |
-| verb             | Symbol                                   | :get                    | *        |
-| default_params   | Hash || block -> Hash                    | {}                      |          |
-| headers          | Hash || block -> Hash                    | proc { client.headers } |          |
-| basic_auth       | Hash (keys: user, pass) || block -> Hash |                         |          |
-| follow_redirects | Boolean || block -> Boolean              | true                    |          |
-| body_type        | Symbol, one of: :json,:form,:body        | :json                   |          |
-| cache            | Boolean || block -> Boolean              | false                   |          |
-| cache_options    | Hash || block -> Hash                    | {}                      |          |
-| retry_if         | block                                    |                         |          |
-| retry_options    | Hash || block -> Hash                    | {}                      |          |
-| around_request   | block                                    |                         |          |
+| Name             | Type                                       | Default                 | Required |
+|------------------|--------------------------------------------|-------------------------|----------|
+| client           | Wrappi::Client                             |                         | *        |
+| path             | String                                     |                         | *        |
+| verb             | Symbol                                     | :get                    | *        |
+| default_params   | Hash `or` block -> Hash                    | {}                      |          |
+| headers          | Hash `or` block -> Hash                    | proc { client.headers } |          |
+| basic_auth       | Hash (keys: user, pass) `or` block -> Hash |                         |          |
+| follow_redirects | Boolean `or` block -> Boolean              | true                    |          |
+| body_type        | Symbol, one of: :json,:form,:body          | :json                   |          |
+| cache            | Boolean `or` block -> Boolean              | proc { options[:cache] }|          |
+| cache_options    | Hash `or` block -> Hash                    |                         |          |
+| retry_if         | block                                      |                         |          |
+| retry_options    | Hash `or` block -> Hash                    |                         |          |
+| around_request   | block                                      |                         |          |
+| async_callback   | block                                      |                         |          |
 
 ### Client
 
@@ -129,6 +313,42 @@ It holds the common configuration for all the endpoints (`Wrappi::Endpoint`).
       "Auth-Token" => "verysecret"
     }
     ```
+  - __async_handler:__ If you are not in Rails app or you have another background mechanism in place
+    you can configure here how the requests will be send to the background.
+    When `#async` is called on an Endpoint instance the `async_handler` const will be called with:
+    current endpoint instance (`self`) and the options passed to the async method.
+    ```ruby
+    class MyAsyncHandler
+      def self.call(endpoint, opts)
+        # send to background
+      end
+    end
+    class Client < Wrappi::Client
+      setup do |config|
+        config.domain = 'https://api.github.com'
+        config.async_handler = MyAsyncHandler
+      end
+    end
+    endpoint_inst.async(this_opts_are_for_the_handler: true)
+    ```
+
+  - __timeout:__ Set your specific timout. When you set timeout it will be merged with defaults.
+
+    default: `{ write: 9, connect: 9, read: 9 }`
+
+    ```ruby
+      class Client < Wrappi::Client
+        setup do |config|
+          config.domain = 'https://api.github.com'
+          config.timeout = { read: 3 }
+        end
+      end
+      Client.timeout # => { write: 9, connect: 9, read: 3 }
+    ```
+
+  - __use_ssl_context:__ It has to be set to `true` for using the `ssl_context`
+
+     default: `false`
 
   - __ssl_context:__ If you need to set an ssl_context.
 
@@ -139,10 +359,6 @@ It holds the common configuration for all the endpoints (`Wrappi::Endpoint`).
                           end
      ```
 
-  - __use_ssl_context:__ It has to be set to `true` for using the `ssl_context`
-
-     default: `false`
-
 ### Endpoint
 
 #### Required:
@@ -224,7 +440,7 @@ It holds the common configuration for all the endpoints (`Wrappi::Endpoint`).
       end
     ```
 
-  - __follow_redirects:__ If first request responds a redirect it will follow them.
+  - __follow_redirects:__ If the request responds with a redirection it will follow them.
 
     default: `true`
 
@@ -236,6 +452,21 @@ It holds the common configuration for all the endpoints (`Wrappi::Endpoint`).
     - :form
     - :body (Binary data)
 
+  - __async_callback:__ When request is executed in the background with `#async(opts = {})` this
+    callback will be called with this opts as and argument in the block.
+    The block is executed in the endpoint instance. You can access to all the methods in Endpoint.
+
+    default: `proc {}`
+
+    ```ruby
+    async_callback do |opts|
+      if success?
+        MyCreationService.call(body) if opts[:create]
+      end
+    end
+    MyEndpoint.new().async(create: true)
+    ```
+
 #### Flow Control:
 
   This configs allows you fine tune your request adding middleware, retries and cache.
@@ -249,7 +480,7 @@ It holds the common configuration for all the endpoints (`Wrappi::Endpoint`).
 
   - __cache:__ Cache the request if successful.
 
-    default: `false`
+    default: `proc { options[:cache] }`
   - __cache_options:__ Options for the `cache` to receive on `write`
    ```ruby
      cache_options expires_in: 12, another_opt: true
@@ -300,11 +531,10 @@ It holds the common configuration for all the endpoints (`Wrappi::Endpoint`).
 
 After checking out the repo, run `bin/setup` to install dependencies.
 
-Run test:
 ```
 bin/dev_server
 ```
-This will run a rails server. The test are running agains it.
+This will run a rails server. The test are running against it.
 
 ```
 bundle exec rspec

data/lib/wrappi.rb

@@ -7,8 +7,11 @@ require 'retryable'
 module Wrappi
   class TimeoutError < StandardError; end
   class NotAuthorizedAccessError < StandardError; end
+  class JsonParseError < StandardError; end
 end
 
+require 'wrappi/async_job'
+require 'wrappi/async_handler'
 require 'wrappi/client'
 require 'wrappi/executer'
 require 'wrappi/endpoint'

data/lib/wrappi/async_handler.rb

@@ -0,0 +1,17 @@
+module Wrappi
+  class AsyncHandler
+    def self.call(*args)
+      new(*args).call
+    end
+    attr_reader :endpoint, :options
+    def initialize(endpoint, options)
+      @endpoint = endpoint
+      @options = options
+    end
+
+    def call
+      AsyncJob.set((options[:set] || {}))
+           .perform_later(endpoint.class.to_s, { params: endpoint.input_params, options: endpoint.options }, options)
+    end
+  end
+end

data/lib/wrappi/async_job.rb

@@ -0,0 +1,51 @@
+module Wrappi
+  module AsyncConcern
+    def wrappi_perform(endpoint_class, args, options)
+      @endpoint_class = endpoint_class
+      @args = parse(args)
+      @options = parse(options)
+      return unless endpoint_const
+      inst = endpoint_const.new(@args[:params], @args[:options])
+      inst.perform_async_callback(@options)
+    end
+
+    private
+
+    def parse(data)
+      return ia(data) if data.is_a?(Hash)
+      ia(JSON.parse(data)) rescue {}
+    rescue
+      data
+    end
+
+    def ia(data)
+      Fusu::HashWithIndifferentAccess.new(data)
+    end
+
+    def endpoint_const
+      Class.const_get(@endpoint_class)
+    rescue
+      puts "[Wrappi] Unable to find const #{@endpoint_class} for async"
+      false
+    end
+  end
+if defined?(ActiveJob)
+  class Async < ActiveJob::Base
+    include AsyncConcern
+    def perform(*args)
+      wrappi_perform(*args)
+    end
+  end
+else
+  class AsyncJob
+    include AsyncConcern
+    def self.set(options = {})
+      self
+    end
+    def self.perform_later(*args)
+      puts "Unable to perform async ActiveJob is not installed"
+      new().wrappi_perform(*args)
+    end
+  end
+end
+end

data/lib/wrappi/client.rb

@@ -2,10 +2,6 @@ require 'logger'
 module Wrappi
   # This class is expected to handle all the configurations for your main module
   class Client
-    class TimeoutError < StandardError; end
-    class JsonParseError < StandardError; end
-    class NotAuthorizedAccessError < StandardError; end
-
     include Fusu::Configurable
 
     # Not verify example
@@ -21,6 +17,7 @@ module Wrappi
     end
     config_accessor(:params) { {} }
     config_accessor(:cache)
+    config_accessor(:async_handler) { AsyncHandler }
 
     def self.setup
       yield(self)

data/lib/wrappi/endpoint.rb

@@ -4,6 +4,7 @@ module Wrappi
     :verb, :client, :path, :default_params,
     :headers, :follow_redirects, :basic_auth,
     :body_type, :retry_options, :cache, :cache_options,
+    :async_callback,
     default_config: {
       verb: :get,
       client: proc { raise 'client not set' }, # TODO: add proper error
@@ -12,8 +13,9 @@ module Wrappi
       headers: proc { client.headers },
       follow_redirects: true,
       body_type: :json,
-      cache: false,
-      cache_options: {}
+      cache: proc { options[:cache] },
+      cache_options: {},
+      async_callback: proc {}
     }
   )
     attr_reader :input_params, :options
@@ -26,18 +28,19 @@ module Wrappi
       new(*args).call
     end
 
-    def url
-      _url.to_s
+    def response
+      @response ||= Executer.call(self)
     end
+    alias_method :call, :response
 
-    def url_with_params
-      if verb == :get
-        _url.tap do |u|
-          u.query = URI.encode_www_form(consummated_params) if consummated_params.any?
-        end.to_s
-      else
-        url
-      end
+    def body; response.body end
+    def success?; response.success? end
+    def status; response.status end
+    def error?; !success? end
+    def flush; @response = nil end
+
+    def async(async_options = {})
+      async_handler.call(self, async_options)
     end
 
     # overridable
@@ -45,42 +48,62 @@ module Wrappi
       params
     end
 
-    def response
-      @response ||= Executer.call(self)
+    def url
+      _url.to_s
     end
-    alias_method :call, :response
 
-    def body; response.body end
-    def success?; response.success? end
-    def status; response.status end
+    def url_with_params
+      return url unless verb == :get
+      _url.tap do |u|
+        u.query = URI.encode_www_form(consummated_params) if consummated_params.any?
+      end.to_s
+    end
+
+
+    def self.async_callback(&block)
+      @async_callback = block
+    end
 
-    # AROUND REQUEST
     def self.around_request(&block)
       @around_request = block
     end
-    def around_request
-      self.class.instance_variable_get(:@around_request)
-    end
 
-    # RETRY
     def self.retry_if(&block)
       @retry_if = block
     end
-    def retry_if
-      self.class.instance_variable_get(:@retry_if)
+
+    def perform_async_callback(async_options = {})
+      instance_exec(async_options, &async_callback)
     end
 
-    # Cache
     def cache_key
       # TODO: think headers have to be in the key as well
       @cache_key ||= "[#{verb.to_s.upcase}]##{url}#{params_cache_key}"
     end
 
+    def around_request
+      self.class.instance_variable_get(:@around_request)
+    end
+
+    def retry_if
+      self.class.instance_variable_get(:@retry_if)
+    end
+
+    private
+
+    def async_callback
+      self.class.instance_variable_get(:@async_callback) || proc {}
+    end
+
+
     def logger
       client.logger
     end
 
-    private
+    # Overridable
+    def async_handler
+      client.async_handler
+    end
 
     def params_cache_key
       return if params.empty?

data/lib/wrappi/version.rb

@@ -1,3 +1,3 @@
 module Wrappi
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

data/wrappi.gemspec

@@ -9,8 +9,13 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Artur Pañach"]
   spec.email         = ["arturictus@gmail.com"]
 
-  spec.summary       = %q{Framework to create HTTP API clients}
-  spec.description   = %q{Framework to create HTTP API clients. The aim is to abstract the best practices using a declarative interface.}
+  spec.summary       = %q{Making APIs fun again!}
+  spec.description   = %q{Wrappi is a Framework to create API clients.
+The intention is to bring the best practices and standardize how API clients behave.
+It allows to create API clients in a declarative way improving readability and unifying the behavior.
+It abstracts complex operations like caching, retries, background request and error handling.
+
+Enjoy!}
   spec.homepage      = "https://github.com/arturictus/wrappi"
   spec.license       = "MIT"
 
@@ -19,7 +24,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.12"
+  spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "sinatra"

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: wrappi
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Artur Pañach
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-01-30 00:00:00.000000000 Z
+date: 2019-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -122,8 +122,13 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Framework to create HTTP API clients. The aim is to abstract the best
-  practices using a declarative interface.
+description: |-
+  Wrappi is a Framework to create API clients.
+  The intention is to bring the best practices and standardize how API clients behave.
+  It allows to create API clients in a declarative way improving readability and unifying the behavior.
+  It abstracts complex operations like caching, retries, background request and error handling.
+
+  Enjoy!
 email:
 - arturictus@gmail.com
 executables: []
@@ -142,6 +147,8 @@ files:
 - bin/dev_server
 - bin/setup
 - lib/wrappi.rb
+- lib/wrappi/async_handler.rb
+- lib/wrappi/async_job.rb
 - lib/wrappi/cached_response.rb
 - lib/wrappi/client.rb
 - lib/wrappi/endpoint.rb
@@ -180,5 +187,5 @@ rubyforge_project:
 rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
-summary: Framework to create HTTP API clients
+summary: Making APIs fun again!
 test_files: []