evil-client 0.3.3 → 1.0.0

data/lib/evil/client/schema/scope.rb

@@ -0,0 +1,73 @@
+require_relative "operation"
+
+class Evil::Client
+  #
+  # Mutable container of definitions for sub-scopes and operations
+  # with DSL to configure those definitions.
+  #
+  class Schema::Scope < Schema::Operation
+    # Tells that this is a schema for a scope (not the final operation)
+    #
+    # @return [false]
+    #
+    def leaf?
+      false
+    end
+
+    # The collection of named sub-scope schemas
+    #
+    # Every sub-scope schema refers to the current one as a [#parent]
+    #
+    # @return [Hash<Symbol, Class>]
+    #
+    def scopes
+      @__children__.reject { |_, child| child.leaf? }
+    end
+
+    # The collection of named operation schemas
+    #
+    # @return [Hash<[Symbol, nil], Class>]
+    #
+    def operations
+      @__children__.select { |_, child| child.leaf? }
+    end
+
+    # Creates or updates sub-scope definition
+    #
+    # @param  [#to_sym] name The unique name of subscope inside current scope
+    # @param  [Proc] block The block containing definition for the subscope
+    # @return [self]
+    #
+    def scope(name, &block)
+      key = NameError.check!(name, RESERVED)
+      TypeError.check! self, key, :scope
+      @__children__[key] ||= self.class.new(self, key)
+      @__children__[key].instance_exec(&block)
+      self
+    end
+
+    # Creates or updates operation definition
+    #
+    # @param  [#to_sym] name The unique name of operation inside the scope
+    # @param  [Proc] block The block containing definition for the operation
+    # @return [self]
+    #
+    def operation(name, &block)
+      key = NameError.check!(name, RESERVED)
+      TypeError.check! self, key, :operation
+      @__children__[key] ||= self.class.superclass.new(self, key)
+      @__children__[key].instance_exec(&block)
+      self
+    end
+
+    private
+
+    def initialize(*)
+      super
+      @__children__ = {}
+    end
+
+    RESERVED = \
+      %i[operations scopes scope options schema settings inspect logger].freeze
+  end
+end

data/lib/evil/client/settings.rb

@@ -0,0 +1,172 @@
+class Evil::Client
+  #
+  # Container for settings assigned to some operation or scope.
+  #
+  class Settings
+    require_relative "settings/validator"
+
+    extend Dry::Initializer
+
+    class << self
+      # The schema klass settings belongs to
+      #
+      # @return [Class]
+      #
+      attr_reader :schema
+
+      # Only options can be defined for the settings container
+      # @private
+      def param(*args)
+        option(*args)
+      end
+
+      # Creates or updates the settings' initializer
+      #
+      # @see [http://dry-rb.org/gems/dry-initializer]
+      #
+      # @param       [#to_sym] key       Symbolic name of the option
+      # @param       [#call]   type      Type coercer for the option
+      # @option opts [#call]   :type     Another way to assign type coercer
+      # @option opts [#call]   :default  Proc containing default value
+      # @option opts [Boolean] :optional Whether it can be missed
+      # @option opts [#to_sym] :as       The name of settings variable
+      # @option opts [false, :private, :protected] :reader Reader method type
+      # @return      [self]
+      #
+      def option(key, type = nil, as: key.to_sym, **opts)
+        NameError.check!(as, RESERVED)
+        super
+        self
+      end
+
+      # Creates or reloads memoized attribute
+      #
+      # @param [#to_sym] key The name of the attribute
+      # @param [Proc] block  The body of new attribute
+      # @return [self]
+      #
+      def let(key, &block)
+        NameError.check!(key, RESERVED)
+        define_method(key) do
+          instance_variable_get(:"@#{key}") ||
+            instance_variable_set(:"@#{key}", instance_exec(&block))
+        end
+        self
+      end
+
+      # Define validator for the attribute
+      #
+      # @param [#to_sym] key The name of the attribute
+      # @param [Proc] block  The body of new attribute
+      # @return [self]
+      #
+      def validate(key, &block)
+        validators[key] = Validator.new(@schema, key, &block)
+        self
+      end
+
+      # Collection of validators to check initialized settings
+      #
+      # @return [Hash<Symbol, Evil::Client::Validator>]
+      #
+      def validators
+        @validators ||= {}
+      end
+
+      # Human-friendly representation of settings class
+      #
+      # @return [String]
+      #
+      def name
+        super || @schema.to_s
+      end
+      alias_method :to_s,    :name
+      alias_method :to_str,  :name
+      alias_method :inspect, :name
+
+      # Builds settings with options
+      #
+      # @param  [Logger, nil] logger
+      # @param  [Hash<#to_sym, Object>, nil] opts
+      # @return [Evil::Client::Settings]
+      #
+      def new(logger, opts = {})
+        logger&.debug(self) { "initializing with options #{opts}..." }
+        opts = Hash(opts).each_with_object({}) { |(k, v), o| o[k.to_sym] = v }
+        super logger, opts
+      rescue => error
+        raise ValidationError, error.message
+      end
+
+      # @private
+      RESERVED = \
+        %i[options datetime scope logger basic_auth key_auth token_auth].freeze
+    end
+
+    # The processed hash of options contained by the instance of settings
+    #
+    # @return [Hash<Symbol, Object>]
+    #
+    def options
+      @__options__
+    end
+
+    # @!attribute logger
+    # @return [Logger, nil] The logger attached to current settings
+    attr_accessor :logger
+
+    # DSL helper to format datetimes following RFC7231/RFC2822
+    #
+    # @see https://tools.ietf.org/html/rfc7231#section-7.1.1.1
+    #
+    # @param  [Date, String, nil] value Value to be formatted
+    # @return [String, nil]
+    #
+    def datetime(value)
+      return unless value
+
+      value = DateTime.parse(value) if value.is_a? String
+      value = value.to_datetime     if value.respond_to? :to_datetime
+      raise "Cannot convert #{value} to DateTime" unless value.is_a?(DateTime)
+
+      value.rfc2822
+    end
+
+    # Human-readable representation of settings instance
+    #
+    # @return [String]
+    #
+    def inspect
+      number = super.match(/\>\:([^ ]+) /)[1]
+      params = options.map { |k, v| "@#{k}=#{v}" }.join(", ")
+      number ? "#<#{self.class}:#{number} #{params}>" : super
+    end
+    alias_method :to_str, :inspect
+    alias_method :to_s,   :inspect
+
+    private
+
+    def initialize(logger, **options)
+      @logger = logger
+      super(options)
+
+      logger&.debug(self) { "initialized" }
+      __validate__!
+    end
+
+    def __validate__!
+      __validators__.reverse.each { |validator| validator.call(self) }
+    end
+
+    def __validators__
+      klass = self.class
+      [].tap do |list|
+        loop do
+          list.concat klass.validators.values
+          klass = klass.superclass
+          break if klass == Evil::Client::Settings
+        end
+      end
+    end
+  end
+end

data/lib/evil/client/settings/validator.rb

@@ -0,0 +1,64 @@
+class Evil::Client
+  #
+  # Validator to be called in context of initialized settings
+  #
+  class Settings::Validator
+    # Performs validation of initialized settings
+    #
+    # @param [Evil::Client::Settings]
+    # @return true
+    # @raise [Evil::Client::ValidationError] when a validation fails
+    #
+    def call(settings)
+      if validate!(settings, @block)
+        settings&.logger&.debug(self) { "passed for #{settings}" }
+        true
+      else
+        settings&.logger&.error(self) { "failed for #{settings}" }
+        raise ValidationError.new(@key, @schema, settings.options)
+      end
+    end
+
+    # Human-friendly representation of current validator
+    #
+    # @return [String]
+    #
+    def to_s
+      "#{@schema}.validator[:#{@key}]"
+    end
+    alias_method :to_str,  :to_s
+    alias_method :inspect, :to_s
+
+    private
+
+    def initialize(schema, key, &block)
+      check_key!   key
+      check_block! block
+
+      @schema = schema
+      @key    = key.to_sym
+      @block  = block
+    end
+
+    def check_key!(key)
+      message = if !key.respond_to? :to_sym
+                  "Validator should have a symbolic name"
+                elsif key.empty?
+                  "Validator name should not be empty"
+                end
+
+      raise ArgumentError.new(message) if message
+    end
+
+    def check_block!(block)
+      raise ArgumentError, "You should set block for validation" unless block
+    end
+
+    def validate!(settings, block)
+      settings.instance_eval(&block) && true
+    rescue => error
+      settings&.logger&.error(self) { "broken for #{settings} with #{error}" }
+      raise
+    end
+  end
+end

data/mkdocs.yml

@@ -1,21 +1,27 @@
+# The structure of documentation at readthedocs.com
 ---
 site_name: Evil::Client
-site_description: Human-friendly DSL for building HTTP(s) clients in Ruby
+site_description: Human-friendly DSL for building HTTP(s) clients to remote API
 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'
+  Synopsis: index.md
+  Helpers:
+    scope:             helpers/scope.md
+    operation:         helpers/operation.md
+    option:            helpers/option.md
+    let:               helpers/let.md
+    validate:          helpers/validate.md
+    path:              helpers/path.md
+    http_method:       helpers/http_method.md
+    security:          helpers/security.md
+    headers:           helpers/headers.md
+    query:             helpers/query.md
+    'body and format': helpers/body.md
+    response:          helpers/response.md
+    middleware:        helpers/middleware.md
+    connection:        helpers/connection.md
+    logger:            helpers/logger.md
+  'RSpec matcher':     rspec.md
+  License: license.md

data/spec/features/custom_connection_spec.rb

@@ -0,0 +1,17 @@
+RSpec.describe "custom connection" do
+  let(:conn)     { double call: response }
+  let(:response) { [200, { "Foo" => "Bar" }, ["Hello!"]] }
+  let(:params)   { { subdomain: "europe", user: "andy", token: "foo" } }
+  let(:users)    { Test::Client.new(params).crm(version: 4).users }
+
+  before do
+    load "spec/fixtures/test_client.rb"
+    Test::Client.connection = conn
+  end
+
+  subject { users.fetch id: 2 }
+
+  it "uses new connection" do
+    expect(subject).to eq response
+  end
+end

data/spec/features/operation/middleware_spec.rb

@@ -0,0 +1,50 @@
+RSpec.describe "operation request" do
+  before do
+    # Adds header tag to request/response
+    class Test::Middleware
+      extend Dry::Initializer
+      param :app
+
+      def call(env)
+        env["HTTP_Variables"].update tags
+        status, headers, body = app.call(env)
+        [status, headers.merge(tags), body]
+      end
+    end
+
+    class Foo < Test::Middleware
+      def tags; { "Tag" => "Foo" }; end
+    end
+
+    class Bar < Test::Middleware
+      def tags; { "Tag" => "Bar" }; end
+    end
+
+    load "spec/fixtures/test_client.rb"
+    class Test::Client < Evil::Client
+      middleware { Foo }
+
+      scope :crm do
+        middleware { Bar }
+      end
+    end
+
+    stub_request(:any, //).to_return(status: 200, body: [], headers: {})
+  end
+
+  subject do
+    Test::Client.new(subdomain: "europe", user: "andy", password: "foo")
+                .crm(version: 4)
+                .users
+                .fetch(id: 1)
+  end
+
+  it "applies middleware in a proper order" do
+    expected_request = \
+      a_request(:get, "https://europe.example.com/crm/v4/users/1")
+      .with headers: { "Tag" => "Bar" }
+
+    expect(subject).to eq [200, { "Tag" => "Foo" }, []]
+    expect(expected_request).to have_been_made
+  end
+end

data/spec/features/operation/options_spec.rb

@@ -0,0 +1,71 @@
+RSpec.describe "operation options" do
+  before { load "spec/fixtures/test_client.rb" }
+
+  let(:params) { { subdomain: "europe", user: "andy", token: "foo", foo: 0 } }
+  let(:users)  { Test::Client.new(params).crm(version: 4).users }
+
+  shared_examples :valid_client do |details = "properly"|
+    it "[assigns operation options #{details}]" do
+      expect(subject.options).to eq options
+    end
+  end
+
+  it_behaves_like :valid_client, "with defined options" do
+    subject { users.operations[:fetch].new(id: 9, baz: :QUX) }
+    let(:options) do
+      { subdomain: "europe", user: "andy", token: "foo", version: 4, id: 9 }
+    end
+  end
+
+  it_behaves_like :valid_client, "with reloaded scope options" do
+    subject { users.operations[:fetch].new(id: 9, version: 8) }
+    let(:options) do
+      { subdomain: "europe", user: "andy", token: "foo", version: 8, id: 9 }
+    end
+  end
+
+  it_behaves_like :valid_client, "with reloaded root options" do
+    subject { users.operations[:fetch].new(id: 9, user: "leo") }
+    let(:options) do
+      { subdomain: "europe", user: "leo", token: "foo", version: 4, id: 9 }
+    end
+  end
+
+  it_behaves_like :valid_client, "with operation-specific options" do
+    subject { users.operations[:create].new(name: "Joe", language: "en") }
+    let(:options) do
+      {
+        subdomain: "europe",
+        user: "andy",
+        token: "foo",
+        version: 4,
+        name: "Joe",
+        language: "en"
+      }
+    end
+  end
+
+  context "when required options missed" do
+    subject { users.operations[:create].new(language: "it") }
+
+    it "raises Evil::Client::ValidationError" do
+      expect { subject }.to raise_error Evil::Client::ValidationError, /name/
+    end
+  end
+
+  context "when operation validation failed" do
+    subject { users.operations[:filter].new }
+
+    it "raises Evil::Client::ValidationError" do
+      expect { subject }.to raise_error Evil::Client::ValidationError, /id/
+    end
+  end
+
+  context "when scope validation failed" do
+    subject { users.operations[:fetch].new id: 8, token: nil }
+
+    it "raises Evil::Client::ValidationError" do
+      expect { subject }.to raise_error Evil::Client::ValidationError, /token/
+    end
+  end
+end