elasticsearch-transport-pixlee 1.0.13

data/Rakefile

@@ -0,0 +1,80 @@
+require "bundler/gem_tasks"
+
+desc "Run unit tests"
+task :default => 'test:unit'
+task :test    => 'test:unit'
+
+# ----- Test tasks ------------------------------------------------------------
+
+require 'rake/testtask'
+namespace :test do
+  task :ci_reporter do
+    ENV['CI_REPORTS'] ||= 'tmp/reports'
+    if defined?(RUBY_VERSION) && RUBY_VERSION < '1.9'
+      require 'ci/reporter/rake/test_unit'
+      Rake::Task['ci:setup:testunit'].invoke
+    else
+      require 'ci/reporter/rake/minitest'
+      Rake::Task['ci:setup:minitest'].invoke
+    end
+  end
+
+  Rake::TestTask.new(:unit) do |test|
+    Rake::Task['test:ci_reporter'].invoke if ENV['CI']
+    test.libs << 'lib' << 'test'
+    test.test_files = FileList["test/unit/**/*_test.rb"]
+    # test.verbose = true
+    # test.warning = true
+  end
+
+  Rake::TestTask.new(:integration) do |test|
+    Rake::Task['test:ci_reporter'].invoke if ENV['CI']
+    test.libs << 'lib' << 'test'
+    test.test_files = FileList["test/integration/**/*_test.rb"]
+  end
+
+  Rake::TestTask.new(:all) do |test|
+    Rake::Task['test:ci_reporter'].invoke if ENV['CI']
+    test.libs << 'lib' << 'test'
+    test.test_files = FileList["test/unit/**/*_test.rb", "test/integration/**/*_test.rb"]
+  end
+
+  Rake::TestTask.new(:profile) do |test|
+    Rake::Task['test:ci_reporter'].invoke if ENV['CI']
+    test.libs << 'lib' << 'test'
+    test.test_files = FileList["test/profile/**/*_test.rb"]
+  end
+
+  namespace :cluster do
+    desc "Start Elasticsearch nodes for tests"
+    task :start do
+      $LOAD_PATH << File.expand_path('../lib', __FILE__) << File.expand_path('../test', __FILE__)
+      require 'elasticsearch/extensions/test/cluster'
+      Elasticsearch::Extensions::Test::Cluster.start
+    end
+
+    desc "Stop Elasticsearch nodes for tests"
+    task :stop do
+      $LOAD_PATH << File.expand_path('../lib', __FILE__) << File.expand_path('../test', __FILE__)
+      require 'elasticsearch/extensions/test/cluster'
+      Elasticsearch::Extensions::Test::Cluster.stop
+    end
+  end
+end
+
+# ----- Documentation tasks ---------------------------------------------------
+
+require 'yard'
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.options = %w| --embed-mixins --markup=markdown |
+end
+
+# ----- Code analysis tasks ---------------------------------------------------
+
+if defined?(RUBY_VERSION) && RUBY_VERSION > '1.9'
+  require 'cane/rake_task'
+  Cane::RakeTask.new(:quality) do |cane|
+    cane.abc_max = 15
+    cane.no_style = true
+  end
+end

data/elasticsearch-transport.gemspec

@@ -0,0 +1,74 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'elasticsearch/transport/version'
+
+Gem::Specification.new do |s|
+  s.name          = "elasticsearch-transport-pixlee"
+  s.version       = Elasticsearch::Transport::VERSION
+  s.authors       = ["Karel Minarik"]
+  s.email         = ["karel.minarik@elasticsearch.org"]
+  s.summary       = "Ruby client for Elasticsearch."
+  s.homepage      = "https://github.com/elasticsearch/elasticsearch-ruby/tree/master/elasticsearch-transport"
+  s.license       = "Apache 2"
+
+  s.files         = `git ls-files`.split($/)
+  s.executables   = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  s.test_files    = s.files.grep(%r{^(test|spec|features)/})
+  s.require_paths = ["lib"]
+
+  s.extra_rdoc_files  = [ "README.md", "LICENSE.txt" ]
+  s.rdoc_options      = [ "--charset=UTF-8" ]
+
+  s.add_dependency "multi_json"
+  s.add_dependency "faraday"
+
+  if defined?(RUBY_VERSION) && RUBY_VERSION < '1.9'
+    s.add_dependency "system_timer"
+  end
+
+  s.add_development_dependency "bundler", "> 1"
+  s.add_development_dependency "rake"
+
+  if defined?(RUBY_VERSION) && RUBY_VERSION > '1.9'
+    s.add_development_dependency "elasticsearch-extensions"
+  end
+
+  s.add_development_dependency "ansi"
+  s.add_development_dependency "shoulda-context"
+  s.add_development_dependency "mocha"
+  s.add_development_dependency "turn"
+  s.add_development_dependency "yard"
+  s.add_development_dependency "pry"
+  s.add_development_dependency "ci_reporter", "~> 1.9"
+
+  # Gems for testing integrations
+  s.add_development_dependency "curb"   unless defined? JRUBY_VERSION
+  s.add_development_dependency "patron" unless defined? JRUBY_VERSION
+  s.add_development_dependency "typhoeus", '~> 0.6'
+  s.add_development_dependency "manticore", '~> 0.3.5' if defined? JRUBY_VERSION
+  s.add_development_dependency "hashie"
+
+  # Prevent unit test failures on Ruby 1.8
+  if defined?(RUBY_VERSION) && RUBY_VERSION < '1.9'
+    s.add_development_dependency "test-unit", '~> 2'
+    s.add_development_dependency "json"
+  end
+
+  if defined?(RUBY_VERSION) && RUBY_VERSION > '1.9'
+    s.add_development_dependency "minitest", "~> 4.0"
+    s.add_development_dependency "ruby-prof"    unless defined?(JRUBY_VERSION) || defined?(Rubinius)
+    s.add_development_dependency "require-prof" unless defined?(JRUBY_VERSION) || defined?(Rubinius)
+    s.add_development_dependency "simplecov"
+    s.add_development_dependency "simplecov-rcov"
+    s.add_development_dependency "cane"
+  end
+
+  if defined?(RUBY_VERSION) && RUBY_VERSION > '2.2'
+    s.add_development_dependency "test-unit", '~> 2'
+  end
+
+  s.description = <<-DESC.gsub(/^    /, '')
+    Ruby client for Elasticsearch. See the `elasticsearch` gem for full integration.
+  DESC
+end

data/lib/elasticsearch-transport.rb

@@ -0,0 +1 @@
+require 'elasticsearch/transport'

data/lib/elasticsearch/transport.rb

@@ -0,0 +1,30 @@
+require "uri"
+require "time"
+require "timeout"
+require "multi_json"
+require "faraday"
+
+require "elasticsearch/transport/transport/serializer/multi_json"
+require "elasticsearch/transport/transport/sniffer"
+require "elasticsearch/transport/transport/response"
+require "elasticsearch/transport/transport/errors"
+require "elasticsearch/transport/transport/base"
+require "elasticsearch/transport/transport/connections/selector"
+require "elasticsearch/transport/transport/connections/connection"
+require "elasticsearch/transport/transport/connections/collection"
+require "elasticsearch/transport/transport/http/faraday"
+require "elasticsearch/transport/client"
+
+require "elasticsearch/transport/version"
+
+module Elasticsearch
+  module Client
+
+    # A convenience wrapper for {::Elasticsearch::Transport::Client#initialize}.
+    #
+    def new(arguments={})
+      Elasticsearch::Transport::Client.new(arguments)
+    end
+    extend self
+  end
+end

data/lib/elasticsearch/transport/client.rb

@@ -0,0 +1,195 @@
+module Elasticsearch
+  module Transport
+
+    # Handles communication with an Elasticsearch cluster.
+    #
+    # See {file:README.md README} for usage and code examples.
+    #
+    class Client
+      DEFAULT_TRANSPORT_CLASS  = Transport::HTTP::Faraday
+
+      DEFAULT_LOGGER = lambda do
+        require 'logger'
+        logger = Logger.new(STDERR)
+        logger.progname = 'elasticsearch'
+        logger.formatter = proc { |severity, datetime, progname, msg| "#{datetime}: #{msg}\n" }
+        logger
+      end
+
+      DEFAULT_TRACER = lambda do
+        require 'logger'
+        logger = Logger.new(STDERR)
+        logger.progname = 'elasticsearch.tracer'
+        logger.formatter = proc { |severity, datetime, progname, msg| "#{msg}\n" }
+        logger
+      end
+
+      # Returns the transport object.
+      #
+      # @see Elasticsearch::Transport::Transport::Base
+      # @see Elasticsearch::Transport::Transport::HTTP::Faraday
+      #
+      attr_accessor :transport
+
+      # Create a client connected to an Elasticsearch cluster.
+      #
+      # Specify the URL via arguments or set the `ELASTICSEARCH_URL` environment variable.
+      #
+      # @option arguments [String,Array] :hosts Single host passed as a String or Hash, or multiple hosts
+      #                                         passed as an Array; `host` or `url` keys are also valid
+      #
+      # @option arguments [Boolean] :log   Use the default logger (disabled by default)
+      #
+      # @option arguments [Boolean] :trace Use the default tracer (disabled by default)
+      #
+      # @option arguments [Object] :logger An instance of a Logger-compatible object
+      #
+      # @option arguments [Object] :tracer An instance of a Logger-compatible object
+      #
+      # @option arguments [Number] :resurrect_after After how many seconds a dead connection should be tried again
+      #
+      # @option arguments [Boolean,Number] :reload_connections Reload connections after X requests (false by default)
+      #
+      # @option arguments [Boolean] :randomize_hosts   Shuffle connections on initialization and reload (false by default)
+      #
+      # @option arguments [Integer] :sniffer_timeout   Timeout for reloading connections in seconds (1 by default)
+      #
+      # @option arguments [Boolean,Number] :retry_on_failure   Retry X times when request fails before raising and
+      #                                                        exception (false by default)
+      #
+      # @option arguments [Boolean] :reload_on_failure Reload connections after failure (false by default)
+      #
+      # @option arguments [Integer] :request_timeout The request timeout to be passed to transport in options
+      #
+      # @option arguments [Symbol] :adapter A specific adapter for Faraday (e.g. `:patron`)
+      #
+      # @option arguments [Hash] :transport_options Options to be passed to the `Faraday::Connection` constructor
+      #
+      # @option arguments [Constant] :transport_class  A specific transport class to use, will be initialized by
+      #                                                the client and passed hosts and all arguments
+      #
+      # @option arguments [Object] :transport A specific transport instance
+      #
+      # @option arguments [Constant] :serializer_class A specific serializer class to use, will be initialized by
+      #                                               the transport and passed the transport instance
+      #
+      # @option arguments [Constant] :selector An instance of selector strategy implemented with
+      #                                        {Elasticsearch::Transport::Transport::Connections::Selector::Base}.
+      #
+      # @option arguments [String] :send_get_body_as Specify the HTTP method to use for GET requests with a body.
+      #                                              (Default: GET)
+      #
+      def initialize(arguments={})
+        hosts = arguments[:hosts] || \
+                arguments[:host]  || \
+                arguments[:url]   || \
+                arguments[:urls]  || \
+                ENV.fetch('ELASTICSEARCH_URL', 'localhost:9200')
+
+        arguments[:logger] ||= arguments[:log]   ? DEFAULT_LOGGER.call() : nil
+        arguments[:tracer] ||= arguments[:trace] ? DEFAULT_TRACER.call() : nil
+        arguments[:reload_connections] ||= false
+        arguments[:retry_on_failure]   ||= false
+        arguments[:reload_on_failure]  ||= false
+        arguments[:randomize_hosts]    ||= false
+        arguments[:transport_options]  ||= {}
+
+        arguments[:transport_options].update(:request => { :timeout => arguments[:request_timeout] } ) if arguments[:request_timeout]
+
+        @send_get_body_as = arguments[:send_get_body_as] || 'GET'
+
+        transport_class  = arguments[:transport_class] || DEFAULT_TRANSPORT_CLASS
+
+        @transport       = arguments[:transport] || begin
+          if transport_class == Transport::HTTP::Faraday
+            transport_class.new(:hosts => __extract_hosts(hosts, arguments), :options => arguments) do |faraday|
+              faraday.adapter(arguments[:adapter] || __auto_detect_adapter)
+            end
+          else
+            transport_class.new(:hosts => __extract_hosts(hosts, arguments), :options => arguments)
+          end
+        end
+      end
+
+      # Performs a request through delegation to {#transport}.
+      #
+      def perform_request(method, path, params={}, body=nil)
+        method = @send_get_body_as if 'GET' == method && body
+
+        transport.perform_request method, path, params, body
+      end
+
+      # Normalizes and returns hosts configuration.
+      #
+      # Arrayifies the `hosts_config` argument and extracts `host` and `port` info from strings.
+      # Performs shuffling when the `randomize_hosts` option is set.
+      #
+      # TODO: Refactor, so it's available in Elasticsearch::Transport::Base as well
+      #
+      # @return [Array<Hash>]
+      # @raise  [ArgumentError]
+      #
+      # @api private
+      #
+      def __extract_hosts(hosts_config, options={})
+        if hosts_config.is_a?(Hash)
+          hosts = [ hosts_config ]
+        else
+          if hosts_config.is_a?(String) && hosts_config.include?(',')
+            hosts = hosts_config.split(/\s*,\s*/)
+          else
+            hosts = Array(hosts_config)
+          end
+        end
+
+        result = hosts.map do |host|
+          host_parts = case host
+            when String
+              if host =~ /^[a-z]+\:\/\//
+                uri = URI.parse(host)
+                { :scheme => uri.scheme, :user => uri.user, :password => uri.password, :host => uri.host, :path => uri.path, :port => uri.port }
+              else
+                host, port = host.split(':')
+                { :host => host, :port => port }
+              end
+            when URI
+              { :scheme => host.scheme, :user => host.user, :password => host.password, :host => host.host, :path => host.path, :port => host.port }
+            when Hash
+              host
+            else
+              raise ArgumentError, "Please pass host as a String, URI or Hash -- #{host.class} given."
+            end
+
+          host_parts[:port] = host_parts[:port].to_i unless host_parts[:port].nil?
+          host_parts
+        end
+
+        result.shuffle! if options[:randomize_hosts]
+        result
+      end
+
+      # Auto-detect the best adapter (HTTP "driver") available, based on libraries
+      # loaded by the user, preferring those with persistent connections
+      # ("keep-alive") by default
+      #
+      # @return [Symbol]
+      #
+      # @api private
+      #
+      def __auto_detect_adapter
+        case
+        when defined?(::Patron)
+          :patron
+        when defined?(::Typhoeus)
+          :typhoeus
+        when defined?(::HTTPClient)
+          :httpclient
+        when defined?(::Net::HTTP::Persistent)
+          :net_http_persistent
+        else
+          ::Faraday.default_adapter
+        end
+      end
+    end
+  end
+end

data/lib/elasticsearch/transport/transport/base.rb

@@ -0,0 +1,261 @@
+module Elasticsearch
+  module Transport
+    module Transport
+
+      # @abstract Module with common functionality for transport implementations.
+      #
+      module Base
+        DEFAULT_PORT             = 9200
+        DEFAULT_PROTOCOL         = 'http'
+        DEFAULT_RELOAD_AFTER     = 10_000 # Requests
+        DEFAULT_RESURRECT_AFTER  = 60     # Seconds
+        DEFAULT_MAX_RETRIES      = 3      # Requests
+        DEFAULT_SERIALIZER_CLASS = Serializer::MultiJson
+
+        attr_reader   :hosts, :options, :connections, :counter, :last_request_at, :protocol
+        attr_accessor :serializer, :sniffer, :logger, :tracer,
+                      :reload_connections, :reload_after,
+                      :resurrect_after, :max_retries
+
+        # Creates a new transport object.
+        #
+        # @param arguments [Hash] Settings and options for the transport
+        # @param block     [Proc] Lambda or Proc which can be evaluated in the context of the "session" object
+        #
+        # @option arguments [Array] :hosts   An Array of normalized hosts information
+        # @option arguments [Array] :options A Hash with options (usually passed by {Client})
+        #
+        # @see Client#initialize
+        #
+        def initialize(arguments={}, &block)
+          @hosts       = arguments[:hosts]   || []
+          @options     = arguments[:options] || {}
+          @block       = block
+          @connections = __build_connections
+
+          @serializer  = options[:serializer] || ( options[:serializer_class] ? options[:serializer_class].new(self) : DEFAULT_SERIALIZER_CLASS.new(self) )
+          @protocol    = options[:protocol] || DEFAULT_PROTOCOL
+
+          @logger      = options[:logger]
+          @tracer      = options[:tracer]
+
+          @sniffer     = options[:sniffer_class] ? options[:sniffer_class].new(self) : Sniffer.new(self)
+          @counter     = 0
+          @last_request_at = Time.now
+          @reload_connections = options[:reload_connections]
+          @reload_after    = options[:reload_connections].is_a?(Fixnum) ? options[:reload_connections] : DEFAULT_RELOAD_AFTER
+          @resurrect_after = options[:resurrect_after] || DEFAULT_RESURRECT_AFTER
+          @max_retries     = options[:retry_on_failure].is_a?(Fixnum)   ? options[:retry_on_failure]   : DEFAULT_MAX_RETRIES
+        end
+
+        # Returns a connection from the connection pool by delegating to {Connections::Collection#get_connection}.
+        #
+        # Resurrects dead connection if the `resurrect_after` timeout has passed.
+        # Increments the counter and performs connection reloading if the `reload_connections` option is set.
+        #
+        # @return [Connections::Connection]
+        # @see    Connections::Collection#get_connection
+        #
+        def get_connection(options={})
+          resurrect_dead_connections! if Time.now > @last_request_at + @resurrect_after
+
+          connection = connections.get_connection(options)
+          @counter  += 1
+
+          reload_connections!         if reload_connections && counter % reload_after == 0
+          connection
+        end
+
+        # Reloads and replaces the connection collection based on cluster information.
+        #
+        # @see Sniffer#hosts
+        #
+        def reload_connections!
+          hosts = sniffer.hosts
+          __rebuild_connections :hosts => hosts, :options => options
+          self
+        rescue SnifferTimeoutError
+          logger.error "[SnifferTimeoutError] Timeout when reloading connections." if logger
+          self
+        end
+
+        # Tries to "resurrect" all eligible dead connections.
+        #
+        # @see Connections::Connection#resurrect!
+        #
+        def resurrect_dead_connections!
+          connections.dead.each { |c| c.resurrect! }
+        end
+
+        # Replaces the connections collection.
+        #
+        # @api private
+        #
+        def __rebuild_connections(arguments={})
+          @hosts       = arguments[:hosts]    || []
+          @options     = arguments[:options]  || {}
+          @connections = __build_connections
+        end
+
+        # Log request and response information.
+        #
+        # @api private
+        #
+        def __log(method, path, params, body, url, response, json, took, duration)
+          logger.info  "#{method.to_s.upcase} #{url} " +
+                       "[status:#{response.status}, request:#{sprintf('%.3fs', duration)}, query:#{took}]"
+          logger.debug "> #{__convert_to_json(body)}" if body
+          logger.debug "< #{response.body}"
+        end
+
+        # Log failed request.
+        #
+        # @api private
+        def __log_failed(response)
+          logger.fatal "[#{response.status}] #{response.body}"
+        end
+
+        # Trace the request in the `curl` format.
+        #
+        # @api private
+        def __trace(method, path, params, body, url, response, json, took, duration)
+          trace_url  = "http://localhost:9200/#{path}?pretty" +
+                       ( params.empty? ? '' : "&#{::Faraday::Utils::ParamsHash[params].to_query}" )
+          trace_body = body ? " -d '#{__convert_to_json(body, :pretty => true)}'" : ''
+          tracer.info  "curl -X #{method.to_s.upcase} '#{trace_url}'#{trace_body}\n"
+          tracer.debug "# #{Time.now.iso8601} [#{response.status}] (#{format('%.3f', duration)}s)\n#"
+          tracer.debug json ? serializer.dump(json, :pretty => true).gsub(/^/, '# ').sub(/\}$/, "\n# }")+"\n" : "# #{response.body}\n"
+        end
+
+        # Raise error specific for the HTTP response status or a generic server error
+        #
+        # @api private
+        def __raise_transport_error(response)
+          error = ERRORS[response.status] || ServerError
+          raise error.new "[#{response.status}] #{response.body}"
+        end
+
+        # Converts any non-String object to JSON
+        #
+        # @api private
+        def __convert_to_json(o=nil, options={})
+          o = o.is_a?(String) ? o : serializer.dump(o, options)
+        end
+
+        # Returns a full URL based on information from host
+        #
+        # @param host [Hash] Host configuration passed in from {Client}
+        #
+        # @api private
+        def __full_url(host)
+          url  = "#{host[:protocol]}://"
+          url += "#{host[:user]}:#{host[:password]}@" if host[:user]
+          url += "#{host[:host]}:#{host[:port]}"
+          url += "#{host[:path]}" if host[:path]
+          url
+        end
+
+        # Performs a request to Elasticsearch, while handling logging, tracing, marking dead connections,
+        # retrying the request and reloading the connections.
+        #
+        # @abstract The transport implementation has to implement this method either in full,
+        #           or by invoking this method with a block. See {HTTP::Faraday#perform_request} for an example.
+        #
+        # @param method [String] Request method
+        # @param path   [String] The API endpoint
+        # @param params [Hash]   Request parameters (will be serialized by {Connections::Connection#full_url})
+        # @param body   [Hash]   Request body (will be serialized by the {#serializer})
+        # @param block  [Proc]   Code block to evaluate, passed from the implementation
+        #
+        # @return [Response]
+        # @raise  [NoMethodError] If no block is passed
+        # @raise  [ServerError]   If request failed on server
+        # @raise  [Error]         If no connection is available
+        #
+        def perform_request(method, path, params={}, body=nil, &block)
+          raise NoMethodError, "Implement this method in your transport class" unless block_given?
+          start = Time.now if logger || tracer
+          tries = 0
+
+          begin
+            tries     += 1
+            connection = get_connection or raise Error.new("Cannot get new connection from pool.")
+
+            if connection.connection.respond_to?(:params) && connection.connection.params.respond_to?(:to_hash)
+              params = connection.connection.params.merge(params.to_hash)
+            end
+
+            url        = connection.full_url(path, params)
+
+            response   = block.call(connection, url)
+
+            connection.healthy! if connection.failures > 0
+
+          rescue *host_unreachable_exceptions => e
+            logger.error "[#{e.class}] #{e.message} #{connection.host.inspect}" if logger
+
+            connection.dead!
+
+            if @options[:reload_on_failure] and tries < connections.all.size
+              logger.warn "[#{e.class}] Reloading connections (attempt #{tries} of #{connections.all.size})" if logger
+              reload_connections! and retry
+            end
+
+            if @options[:retry_on_failure]
+              logger.warn "[#{e.class}] Attempt #{tries} connecting to #{connection.host.inspect}" if logger
+              if tries <= max_retries
+                retry
+              else
+                logger.fatal "[#{e.class}] Cannot connect to #{connection.host.inspect} after #{tries} tries" if logger
+                raise e
+              end
+            else
+              raise e
+            end
+
+          rescue Exception => e
+            logger.fatal "[#{e.class}] #{e.message} (#{connection.host.inspect if connection})" if logger
+            raise e
+          end
+
+          duration = Time.now-start if logger || tracer
+
+          if response.status.to_i >= 300
+            __log    method, path, params, body, url, response, nil, 'N/A', duration if logger
+            __trace  method, path, params, body, url, response, nil, 'N/A', duration if tracer
+            __log_failed response if logger
+            __raise_transport_error response
+          end
+
+          json     = serializer.load(response.body) if response.headers && response.headers["content-type"] =~ /json/
+          took     = (json['took'] ? sprintf('%.3fs', json['took']/1000.0) : 'n/a') rescue 'n/a' if logger || tracer
+
+          __log   method, path, params, body, url, response, json, took, duration if logger
+          __trace method, path, params, body, url, response, json, took, duration if tracer
+
+          Response.new response.status, json || response.body, response.headers
+        ensure
+          @last_request_at = Time.now
+        end
+
+        # @abstract Returns an Array of connection errors specific to the transport implementation.
+        #           See {HTTP::Faraday#host_unreachable_exceptions} for an example.
+        #
+        # @return [Array]
+        #
+        def host_unreachable_exceptions
+          [Errno::ECONNREFUSED, Elasticsearch::Transport::Transport::Errors::BadGateway]
+        end
+
+        # @abstract A transport implementation must implement this method.
+        #           See {HTTP::Faraday#__build_connections} for an example.
+        #
+        # @return [Connections::Collection]
+        # @api    private
+        def __build_connections
+          raise NoMethodError, "Implement this method in your class"
+        end
+      end
+    end
+  end
+end