evil-client 0.2.1

data/docs/responses.md

@@ -0,0 +1,66 @@
+For every operation you have to describe all expected responses and how they should be processed.
+
+Use the `response` method with anexpected http response status(es):
+
+```ruby
+operation :find_cat do
+  # ...
+  response 200, 201
+end
+```
+
+This definition tells a client to accept responses with given statuses, and to return an instance of `Rack::Response`.
+
+```ruby
+client.operations[:find_cat].call
+# => #<Rack::Response @code=200 ...>
+```
+
+## Data Coersion
+
+Instead of returning a raw rack response, you can coerce it using a block. The block will take 3 options, namely the response, its body and headers:
+
+```ruby
+operation :find_cat do |settings| # remember that you have access to settings
+  # ...
+  response 200 do |response:, body:, headers:|
+    JSON.parse(body) if settings.format == "json"
+  end
+end
+
+# later at a runtime
+client.operations[:find_cat].call
+# => { name: "Bastet", age: 10 }
+```
+
+
+
+## Raising Exceptions
+
+When processing responces with error statuses you may need to raise an exception instead of returning values. Do this using option `raise: true` 
+
+```ruby
+operation :find_cat do
+  # ...
+  response 422, raise: true
+end
+```
+
+This time the operation will raise a `Evil::Client::ResponseError` (inherited from the `RuntimeError`). The exception carries a rack response:
+
+```ruby
+begin
+  client.operations[:find_cat].call
+rescue Evil::Client::ResponseError => error
+  error.response
+  # => #<Rack::Response @code=422 ...>
+end
+```
+
+Like before, you can add a block to handle the response. In this case an exception will carry a result of the block.
+
+## Unexpected Responses
+
+In case the server responded with undefined status, the operation raises `Evil::Client::UnexpectedResponseError` (inherited from the `RuntimeError`) that carries a rack response just like the `Evil::Client::ResponseError` before.
+
+Notice that you can declare default responses using anonymous `operation {}` syntax. Only those responces that are declared neither by default, nor for a specific operation, will cause unexpected response behaviour.

data/docs/security.md

@@ -0,0 +1,102 @@
+Use `security` declaration for the authorization schema. Inside the block you have access to 3 methods:
+* `basic_auth`
+* `token_auth`
+* `key_auth`
+
+## Basic Authentication
+
+Use `basic_auth(login, password)` to define [basic authentication following RFC-7617][basic_auth]:
+
+```ruby
+operation :find_cat do |settings|
+  security do
+    basic_auth settings.login, settings.password
+  end
+end
+```
+
+This declaration with add a header `"Authentication" => "Basic {encoded token}"` to every request. The header is added independenlty of declaration for other [headers][headers].
+
+## Token Authentication
+
+The command `token_auth(token, **options)` allows you to insert a customizable token to any part of the request. Unlike `basic_auth`, you need to provide the token (build, encrypt etc.) by hand.
+
+```ruby
+operation :find_cat do |settings|
+  security do
+    token_auth settings.token
+  end
+end
+```
+
+By default the token is added to `"Authentication" => {token}` header of the request. You can prepend it with a necessary prefix. For example, you can define a [Bearer token authentication following RFC-6750][bearer]:
+
+```ruby
+operation :find_cat do |settings|
+  security do
+    token_auth settings.token, prefix: "Bearer"
+  end
+end
+```
+
+Instead of headers, you can send a token in either request body, or a query. In this case the token will be sent under `access_key` ignoring a prefix:
+
+```ruby
+operation :find_cat do |settings|
+  path { "/cats" }
+  security do
+    token_auth settings.token, using: :query
+  end
+end
+
+# will send a request to "../cats?access_key={token}"
+```
+
+## Authentication Using Arbitrary Key
+
+The most customizeable option is to authenticate requests with an arbitrary key. This time key-value pair will be added to the selected part (`headers`, `body`, or `query`) of the request:
+
+```ruby
+operation :find_cat do |settings|
+  path { "/cats" }
+  security do
+    key_auth :accss_key, settings.token, using: :query
+  end
+end
+```
+
+## Authentication Using Several Schemes
+
+You can define several schemes for the same request. All of them will be applied at once:
+
+```ruby
+operation :find_cat do |settings|
+  security do
+    basic_auth settings.login, settings.password
+    token_auth settings.token, using: :query
+  end
+end
+```
+
+Moreover, you can declare shared authentication by default, and either update, or reload it for a specific operation:
+
+```ruby
+operation do |settings|
+  security { basic_auth settings.login, settings.password }
+end
+
+operation :find_cat do |settings|
+  security { token_auth settings.token, using: :query } # added to default security
+end
+
+operation :find_cats do |settings|
+  security { token_auth settings.token } # reloads default "Authentication" header
+end
+```
+
+
+[basic_auth]: https://tools.ietf.org/html/rfc7617
+[bearer]: https://tools.ietf.org/html/rfc6750
+[headers]:
+[body]:
+[query]:

data/docs/settings.md

@@ -0,0 +1,32 @@
+Use `settings` to parameterize an instance of the client.
+
+Inside the block you can define both `param`s and `option`s for a client constructor. See [dry-initializer docs][dry-initializer] for detailed description of the methods' syntax.
+
+```ruby
+require "evil-client"
+require "dry-types"
+
+class CatsClient < Evil::Client
+  settings do
+    param  :roor_url
+    option :version,  type: Dry::Types["coercible.int"], default: proc { 1 }
+    option :login,    type: Dry::Types["strict.string"] # required
+    option :password, type: Dry::Types["strict.string"] # required
+  end
+end
+```
+
+Now you can initialize a client:
+
+```ruby
+client = CatsClient.new "https://cats.example.com",
+                        login: "cats_lover",
+                        password: "purr"
+```
+
+A container with assigned settings will be passed to blocks declaring [base_url][base_url], [connection][connection], and [operations][operation].
+
+[base_url]:
+[connection]:
+[operation]:
+[dry-initializer]: http://dry-rb.org/gems/dry-initializer

data/evil-client.gemspec

@@ -0,0 +1,25 @@
+Gem::Specification.new do |gem|
+  gem.name     = "evil-client"
+  gem.version  = "0.2.1"
+  gem.author   = "Andrew Kozin (nepalez)"
+  gem.email    = "andrew.kozin@gmail.com"
+  gem.homepage = "https://github.com/evilmartians/evil-client"
+  gem.summary  = "Human-friendly DSL for building HTTP(s) clients in Ruby"
+  gem.license  = "MIT"
+
+  gem.files            = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
+  gem.test_files       = gem.files.grep(/^spec/)
+  gem.extra_rdoc_files = Dir["README.md", "LICENSE", "CHANGELOG.md"]
+
+  gem.required_ruby_version = ">= 2.3"
+
+  gem.add_runtime_dependency "dry-initializer", "~> 0.7.0"
+  gem.add_runtime_dependency "mime-types", "~> 3.0"
+  gem.add_runtime_dependency "rack"
+
+  gem.add_development_dependency "dry-types", "~> 0.9"
+  gem.add_development_dependency "rspec", "~> 3.0"
+  gem.add_development_dependency "rake", "~> 11"
+  gem.add_development_dependency "webmock", "~> 2.1"
+  gem.add_development_dependency "rubocop", "~> 0.44"
+end

data/lib/evil/client.rb

@@ -0,0 +1,97 @@
+require "dry-initializer"
+require "mime-types"
+require "rack"
+
+# Absctract base class for clients to remote APIs
+#
+# @abstract
+# @example
+#   class MyClient < Evil::Client
+#     # declare settings for the client's constructor
+#     # the settings parameterize the rest of the client's definitions
+#     settings do
+#       option :version, type: Dry::Types["strict.int"].default(1)
+#       option :user,    type: Dry::Types["strict.string"]
+#       option :token,   type: Dry::Types["strict.string"]
+#     end
+#
+#     # define base url of the server
+#     base_url do |settings|
+#       "https://my_api.com/v#{settings.version}"
+#     end
+#
+#     # define connection and its middleware stack from bottom to top
+#     connection :net_http do |settings|
+#       run AddCustomRequestId
+#       run EncryptToken if settings.token
+#     end
+#
+#     # definitions shared by all operations (can be reloaded later)
+#     operation do |settings|
+#       type     { :json }
+#       security { basic_auth "foo", "bar" }
+#     end
+#
+#     # operation-specific definitions
+#     operation :find_cat do |settings|
+#       http_method :get
+#       path { "#{settings.url}/cats/find/#{id}" }
+#
+#       query do
+#         option :id, type: Dry::Types["coercible.int"].constrained(gt: 0)
+#       end
+#
+#       response 200, model: Cat
+#       response 400, raise: true
+#       response 422, raise: true do |body:|
+#         JSON.parse(body.first)
+#       end
+#     end
+#
+#     # top-level DSL for operation
+#     scope :users do
+#       scope do # named `:[]` by default
+#         param :id, type: Dry::Types["strict.int"]
+#
+#         def get
+#           operations[:find_users].call(id: id)
+#         end
+#       end
+#     end
+#   end
+#
+#   # Initialize a client with a corresponding settings
+#   client = MyClient.new user: "andrew", token: "f982j23"
+#
+#   # Use low-level DSL for searching a user
+#   client.operations[:find_user].call(id: 1)
+#
+#   # Use top-level DSL for the same operation
+#   client.users[1].get
+#
+module Evil
+  class Client
+    require_relative "client/model"
+    require_relative "client/connection"
+    require_relative "client/middleware"
+    require_relative "client/operation"
+    require_relative "client/dsl"
+
+    extend  DSL
+    include Dry::Initializer.define -> { param :operations }
+
+    # Builds a client instance with custom settings
+    def self.new(*settings)
+      super finalize(*settings)
+    end
+
+    private
+
+    def initialize(schema)
+      @operations = \
+        schema[:operations].each_with_object({}) do |(key, val), hash|
+          hash[key] = Operation.new val, schema[:connection]
+        end
+    end
+  end
+end

data/lib/evil/client/connection.rb

@@ -0,0 +1,35 @@
+class Evil::Client
+  # @abstract Base class for a specific connection to remote uri
+  class Connection
+    REGISTRY = { net_http: "NetHTTP" }.freeze
+
+    extend Dry::Initializer::Mixin
+    param :base_uri
+
+    # Envokes a specific connection class
+    #
+    # @param  [#to_sym] key
+    # @return [Class]
+    #
+    def self.[](name = nil)
+      key = (name || REGISTRY.keys.first).to_sym
+
+      klass = REGISTRY.fetch(key) do
+        fail ArgumentError.new "Connection '#{key}' is not registered." \
+                               " Use the following keys: #{REGISTRY.keys}"
+      end
+
+      require_relative "connection/#{key}"
+      const_get klass
+    end
+
+    # @abstract Sends request to the server and returns rack-compatible response
+    #
+    # @param  [Hash] env
+    # @return [Array]
+    #
+    def call(_env)
+      fail NotImplementedError
+    end
+  end
+end

data/lib/evil/client/connection/net_http.rb

@@ -0,0 +1,57 @@
+require "net/http"
+require "net/https"
+
+class Evil::Client
+  class Connection
+    # Net::HTTP based implementation of [Evil::Client::Connection]
+    class NetHTTP < Connection
+      # Sends a request to the remote uri,
+      # and returns rack-compatible response
+      #
+      # @param  [Hash] env Middleware environment with keys:
+      #   :http_method, :path, :query_string, :body_string, :headers
+      # @return [Array] Rack-compatible response [status, body, headers]
+      #
+      def call(env)
+        request = build_request(env)
+        Net::HTTP.start base_uri.host, base_uri.port, opts do |http|
+          handle http.request(request)
+        end
+      end
+
+      private
+
+      def opts
+        @opts ||= {}.tap { |hash| hash[:use_ssl] = base_uri.scheme == "https" }
+      end
+
+      def build_request(env)
+        type, path, query, body, headers = parse_env(env)
+
+        sender = build_sender(type)
+        uri    = build_uri(path, query)
+
+        sender.new(uri).tap do |request|
+          request.body = body
+          headers.each { |key, value| request[key] = value }
+        end
+      end
+
+      def parse_env(env)
+        env.values_at :http_method, :path, :query_string, :body_string, :headers
+      end
+
+      def build_sender(type)
+        Net::HTTP.const_get type.capitalize
+      end
+
+      def build_uri(path, query)
+        base_uri.merge(path).tap { |uri| uri.query = query }
+      end
+
+      def handle(response)
+        [response.code.to_i, Hash(response.header), Array(response.body)]
+      end
+    end
+  end
+end

data/lib/evil/client/dsl.rb

@@ -0,0 +1,110 @@
+class Evil::Client
+  # Defines a DSL to customize class-level settings of the specific client
+  module DSL
+    require_relative "dsl/operations"
+    require_relative "dsl/scope"
+
+    # Stack of default middleware before custom midleware and a connection
+    # This stack cannot be modified
+    DEFAULT_MIDDLEWARE = Middleware.new do
+      run Middleware::MergeSecurity
+      run Middleware::StringifyJson
+      run Middleware::StringifyQuery
+      run Middleware::NormalizeHeaders
+    end
+
+    # Helper to define params and options a for a client's constructor
+    #
+    # @example
+    #   class MyClient < Evil::Client
+    #   end
+    #
+    #   MyClient.new "https://foo.com", user: "bar", token: "baz"
+    #
+    # @param  [Proc] block
+    # @return [self]
+    #
+    def settings(&block)
+      return self unless block
+      schema[:settings] = Class.new { include Dry::Initializer.define(&block) }
+      self
+    end
+
+    # Helper to define base url of the server
+    #
+    # @param [#to_s] value
+    # @return [self]
+    #
+    def base_url(&block)
+      return self unless block
+      schema[:base_url] = block
+      self
+    end
+
+    # Helper specify a connection to be used by a client
+    #
+    # @param  [#to_sym] type (nil)
+    #   The specific type of connection. Uses NetHTTP by default.
+    # @return [self]
+    #
+    def connection(type = nil, &block)
+      schema[:connection] = Connection[type]
+      schema[:middleware] = Middleware.new(&block)
+      self
+    end
+
+    # Helper to declare operation, either default or specific
+    #
+    # @param  [#to_sym] name (nil)
+    # @param  [Proc] block
+    # @return [self]
+    #
+    def operation(name = nil, &block)
+      schema[:operations].register(name, &block)
+      self
+    end
+
+    # Helper to define scopes of the client's top-level DSL
+    #
+    # @param  [#to_sym] name (:[])
+    # @param  [Proc] block
+    # @return [self]
+    #
+    def scope(name = :[], &block)
+      klass = Class.new(Scope, &block)
+      define_method(name) do |*args, **options|
+        klass.new(*args, __scope__: self, **options)
+      end
+      self
+    end
+
+    # Takes constructor arguments and builds a final schema for the instance
+    #
+    # @param  [Object] *args
+    # @return [Hash<Symbol, Object>]
+    #
+    def finalize(*args)
+      settings   = schema[:settings].new(*args)
+      uri        = URI(schema[:base_url].call(settings))
+      client     = schema[:connection].new(uri)
+      middleware = schema[:middleware].finalize(settings)
+      stack = Middleware.prepend.(middleware.(Middleware.append.(client)))
+
+      { connection: stack, operations: schema[:operations].finalize(settings) }
+    end
+
+    private
+
+    BASE_URL = -> (_) { fail NotImplementedError.new "Base url not defined" }
+
+    def schema
+      @schema ||= {
+        settings:   Class.new,
+        base_url:   BASE_URL,
+        connection: Connection[nil],
+        middleware: Middleware.new,
+        operations: Operations.new
+      }
+    end
+  end
+end