evil-client 0.2.1

data/lib/evil/client/middleware/stringify_json.rb

@@ -0,0 +1,15 @@
+class Evil::Client::Middleware
+  class StringifyJson < Base
+    private
+
+    def build(env)
+      return env unless env[:format] == "json"
+
+      env.dup.tap do |hash|
+        hash[:headers] ||= {}
+        hash[:headers]["content-type"] = "application/json"
+        hash[:body_string] = JSON.generate(env[:body].to_h)
+      end
+    end
+  end
+end

data/lib/evil/client/middleware/stringify_multipart.rb

@@ -0,0 +1,32 @@
+class Evil::Client::Middleware
+  class StringifyMultipart < Base
+    require_relative "stringify_multipart/part"
+
+    private
+
+    def build(env)
+      return env unless env[:format] == "multipart"
+
+      env.dup.tap do |hash|
+        bound = SecureRandom.hex(10)
+        hash[:headers] ||= {}
+        hash[:headers]["content-type"] = \
+          "multipart/form-data; boundary=#{bound}"
+        hash[:body_string] = body_string(hash[:files], bound)
+      end
+    end
+
+    def body_string(list, bound)
+      return if list.empty?
+      [nil, nil, parts(list, bound), "--#{bound}--", nil].join("\r\n")
+    end
+
+    def parts(list, bound)
+      list.map.with_index { |item, index| part(bound, index + 1, item) }
+    end
+
+    def part(bound, index, data)
+      "--#{bound}\r\n#{Part.new(name: "AttachedFile#{index}", **data)}"
+    end
+  end
+end

data/lib/evil/client/middleware/stringify_multipart/part.rb

@@ -0,0 +1,36 @@
+class Evil::Client::Middleware::StringifyMultipart
+  # Takes a file with its options and builds a part of multipart body
+  class Part
+    extend Dry::Initializer::Mixin
+    option :file
+    option :type,     default: proc { MIME::Types["text/plain"].first }
+    option :charset,  default: proc { "utf-8" }
+    option :name,     default: proc { "AttachedFile" }
+    option :filename, default: proc { default_filename }
+
+    def to_s
+      [content_disposition, content_type, nil, content].join("\r\n")
+    end
+
+    private
+
+    def default_filename
+      return Pathname.new(file.path).basename if file.respond_to? :path
+      "#{SecureRandom.hex(10)}.#{type.preferred_extension}"
+    end
+
+    def content_disposition
+      "Content-Disposition: form-data;" \
+      " name=\"#{name}\";" \
+      " filename=\"#{filename}\""
+    end
+
+    def content_type
+      "Content-Type: #{type}; charset=#{charset}"
+    end
+
+    def content
+      file.respond_to?(:read) ? file.read : file
+    end
+  end
+end

data/lib/evil/client/middleware/stringify_query.rb

@@ -0,0 +1,31 @@
+class Evil::Client::Middleware
+  class StringifyQuery < Base
+    private
+
+    def build(env)
+      return env if env&.fetch(:query, nil).to_h.empty?
+      string = env[:query].flat_map { |key, val| normalize(val, key) }
+                          .flat_map { |hash| stringify(hash) }
+                          .join("&")
+
+      env.merge(query_string: string)
+    end
+
+    def stringify(hash)
+      hash.map do |keys, val|
+        "#{keys.first}#{keys[1..-1].map { |key| "[#{key}]" }.join}=#{val}"
+      end
+    end
+
+    def normalize(value, *keys)
+      case value
+      when Hash then
+        value.flat_map { |key, val| normalize(val, *keys, key) }
+      when Array then
+        value.flat_map { |val| normalize(val, *keys, nil) }
+      else
+        [{ keys.map { |key| CGI.escape(key.to_s) } => CGI.escape(value.to_s) }]
+      end
+    end
+  end
+end

data/lib/evil/client/model.rb

@@ -0,0 +1,65 @@
+# Base structure for models describing parts of requests and responses
+#
+# The initializer accepts a hash with symbol/string keys,
+# from which it takes and validates necessary options.
+#
+# The method [#to_h] converts nested data to hash
+# with symbolic keys at any level of nesting.
+#
+class Evil::Client
+  class Model
+    class << self
+      include Dry::Initializer::Mixin
+      alias_method :attribute, :option
+      alias_method :param, :option
+
+      def new(value)
+        return value if value.is_a? self
+        value = value.to_h.each_with_object({}) do |(key, val), obj|
+          obj[key.to_sym] = val
+        end
+        super value
+      end
+
+      def call(value)
+        new(value).to_h
+      end
+      alias_method :[], :call
+    end
+
+    tolerant_to_unknown_options
+
+    def ==(other)
+      return false unless other.respond_to? :to_h
+      to_h == other.to_h
+    end
+
+    def to_h
+      attributes = method(:initialize)
+                   .parameters
+                   .map { |item| item[1] unless item[0] == :keyrest }
+                   .compact
+
+      attributes.each_with_object({}) do |key, hash|
+        val = send(key)
+        hash[key] = hashify(val) unless val == Dry::Initializer::UNDEFINED
+      end
+    end
+    alias_method :[], :send
+
+    private
+
+    def hashify(value)
+      if value.is_a? Evil::Client::Model
+        value.to_h
+      elsif value.respond_to? :to_hash
+        value.to_hash
+             .each_with_object({}) { |(key, val), obj| obj[key] = hashify(val) }
+      elsif value.is_a? Enumerable
+        value.map { |val| hashify(val) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/evil/client/operation.rb

@@ -0,0 +1,34 @@
+class Evil::Client
+  # Carries a final schema for a single operation along with shared connection,
+  # and uses it to send requests to the server
+  class Operation
+    require_relative "operation/request"
+    require_relative "operation/response"
+
+    extend Dry::Initializer::Mixin
+    param :schema
+    param :connection
+
+    # Builds and sends a request and returns a response proccessed by schema
+    #
+    # @param  [IO, nil] file
+    # @param  [Hash<Symbol, Object>] options
+    # @return [Object]
+    #
+    def call(**options)
+      req   = request.build(options)
+      array = connection.call(req)
+      response.handle(array)
+    end
+
+    private
+
+    def request
+      @request ||= Request.new(schema)
+    end
+
+    def response
+      @response ||= Response.new(schema)
+    end
+  end
+end

data/lib/evil/client/operation/request.rb

@@ -0,0 +1,42 @@
+class Evil::Client::Operation
+  # Builds a request env from user options by applying schema validations
+  class Request
+    extend Dry::Initializer::Mixin
+    param :schema
+
+    # Builds an env
+    #
+    # @param  [IO, nil] file (nil)
+    # @param  [Hash<Symbol, Object>] options
+    # @return [Hash]
+    #
+    def build(options)
+      {
+        format:       schema[:format],
+        http_method:  http_method,
+        path:         path.call(options),
+        security:     schema[:security]&.call(options),
+        files:        schema[:files]&.call(options),
+        query:        schema[:query]&.new(options).to_h,
+        body:         schema[:body]&.new(options).to_h,
+        headers:      schema[:headers]&.new(options).to_h
+      }
+    end
+
+    private
+
+    def key
+      @key ||= schema[:key]
+    end
+
+    def http_method
+      return schema[:method] if schema[:method]
+      fail NotImplementedError.new "No method defined for operation '#{key}'"
+    end
+
+    def path
+      return schema[:path] if schema[:path]
+      fail NotImplementedError.new "Path not defined for operation '#{key}'"
+    end
+  end
+end

data/lib/evil/client/operation/response.rb

@@ -0,0 +1,40 @@
+class Evil::Client::Operation
+  require_relative "response_error"
+  require_relative "unexpected_response_error"
+
+  # Processes rack responses using an operation's schema
+  class Response
+    extend Dry::Initializer::Mixin
+    param :schema
+
+    # Processes rack responses returned by [Dry::Cluent::Connection]
+    #
+    # @param  [Array] array Rack-compatible array of response data
+    # @return [Object]
+    # @raise  [Evil::Client::ResponseError] if it is required by the schema
+    #
+    def handle(array)
+      status, header, body = array
+      response = Rack::Response.new(body, status, header)
+
+      handler = response_schema(response)
+      data    = handler[:coercer].call response: response,
+                                       body:     response.body,
+                                       header:   response.header
+
+      handler[:raise] ? fail(ResponseError.new(schema, status, data)) : data
+    end
+
+    private
+
+    def name
+      @name ||= schema[:name]
+    end
+
+    def response_schema(response)
+      schema[:responses].fetch response.status do
+        fail UnexpectedResponseError.new(schema, response)
+      end
+    end
+  end
+end

data/lib/evil/client/operation/response_error.rb

@@ -0,0 +1,12 @@
+class Evil::Client::Operation
+  class ResponseError < RuntimeError
+    attr_reader :response
+
+    private
+
+    def initialize(schema, status, response)
+      @response = response
+      super "Response to operation '#{schema[:key]}' has http status #{status}"
+    end
+  end
+end

data/lib/evil/client/operation/unexpected_response_error.rb

@@ -0,0 +1,16 @@
+class Evil::Client::Operation
+  class UnexpectedResponseError < RuntimeError
+    attr_reader :response
+
+    private
+
+    def initialize(schema, response)
+      @response = response
+
+      message = "Response to operation '#{schema[:key]}'" \
+                " has unexpected http status #{response.status}."
+      message << " See #{schema[:doc]} for details." if schema[:doc]
+      super message
+    end
+  end
+end

data/mkdocs.yml

@@ -0,0 +1,21 @@
+---
+site_name: Evil::Client
+site_description: Human-friendly DSL for building HTTP(s) clients in Ruby
+repo_url: https://github.com/nepalez/evil-client
+site_author: Andrew Kozin
+theme: readthedocs
+pages:
+  - 'Synopsis': 'index.md'
+  - 'Details':
+    - 'Overview': 'overview.md'
+    - 'Model':    'model.md'
+    - 'Settings': 'settings.md'
+    - 'Base URL': 'base_url.md'
+    - 'Operations':
+      - 'HTTP method': 'http_method.md'
+      - 'Path': 'path.md'
+      - 'Security Definitions': 'security.md'
+      - 'Headers': 'headers.md'
+      - 'Query': 'query.md'
+      - 'Responses': 'responses.md'
+      - 'Documentation': 'documentation.md'

data/spec/features/instantiation_spec.rb

@@ -0,0 +1,68 @@
+RSpec.describe "instantiation" do
+  # see Test::Client definition in `/spec/support/test_client.rb`
+  let(:client)    { Test::Client.new subdomain, options }
+  let(:subdomain) { "foo" }
+  let(:options)   { { version: 3, user: "bar", password: "baz", token: "qux" } }
+
+  context "with valid settings:" do
+    it "is accepted" do
+      expect(client).to be_kind_of Test::Client
+    end
+  end
+
+  context "with settings that still conforms to contract:" do
+    let(:options) { { user: "bar" } }
+
+    it "is accepted" do
+      expect(client).to be_kind_of Test::Client
+    end
+  end
+
+  context "with unexpected param settings:" do
+    let(:client) { Test::Client.new(subdomain, subdomain, **options) }
+
+    it "is rejected" do
+      expect { client }.to raise_error(ArgumentError)
+    end
+  end
+
+  context "with missing param settings:" do
+    let(:client) { Test::Client.new(**options) }
+
+    it "is rejected" do
+      expect { client }.to raise_error(ArgumentError)
+    end
+  end
+
+  context "with a broken contract for param:" do
+    let(:subdomain) { 1 }
+
+    it "is rejected" do
+      expect { client }.to raise_error(TypeError)
+    end
+  end
+
+  context "with unexpected option settings:" do
+    before { options[:foo] = "bar" }
+
+    it "is rejected" do
+      expect { client }.to raise_error(ArgumentError)
+    end
+  end
+
+  context "with missing option settings:" do
+    before { options.delete :user }
+
+    it "is rejected" do
+      expect { client }.to raise_error(ArgumentError)
+    end
+  end
+
+  context "with a broken contract for option:" do
+    before { options[:user] = 1 }
+
+    it "is rejected" do
+      expect { client }.to raise_error(TypeError)
+    end
+  end
+end

data/spec/features/middleware_spec.rb

@@ -0,0 +1,75 @@
+RSpec.describe "middleware" do
+  before do
+    class Test::UpdateRequest
+      def initialize(app)
+        @app = app
+      end
+
+      def call(_env)
+        @app.call path: "data/1",
+                  http_method: "get",
+                  format: "form",
+                  headers: { "baz" => "BAZ" },
+                  query: { "bar" => "baz" },
+                  body: { "qux" => 2 }
+      end
+    end
+
+    class Test::UpdateResponse
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        @app.call(env).tap { |rack_response| rack_response[2] = ["Hi!"] }
+      end
+    end
+
+    class Test::Client < Evil::Client
+      connection do |settings|
+        run Test::UpdateRequest
+        run Test::UpdateResponse if settings.version > 2
+      end
+
+      operation :find do
+        path { "some" }
+        http_method :post
+        response 200 do |body:, **|
+          body.first
+        end
+      end
+    end
+
+    stub_request(:any, //)
+  end
+
+  it "updates requests" do
+    request = a_request(:get, "https://foo.example.com/api/v3/data/1?bar=baz")
+      .with do |req|
+        expect(req.body).to eq "qux=2"
+        expect(req.headers).to include "Baz" => "BAZ"
+      end
+
+    Test::Client.new("foo", version: 3, user: "bar").operations[:find].call
+
+    expect(request).to have_been_made
+  end
+
+  it "updates responses" do
+    response = \
+      Test::Client.new("foo", version: 3, user: "bar")
+      .operations[:find]
+      .call
+
+    expect(response).to eq "Hi!"
+  end
+
+  it "depends on settings" do
+    response = \
+      Test::Client.new("foo", version: 1, user: "bar")
+      .operations[:find]
+      .call
+
+    expect(response).to be_nil
+  end
+end