Provided by: libsearch-elasticsearch-perl_8.00-1_all bug

NAME

       Search::Elasticsearch::Role::Cxn - Provides common functionality to HTTP Cxn
       implementations

VERSION

       version 8.00

DESCRIPTION

       Search::Elasticsearch::Role::Cxn provides common functionality to Cxn implementations. Cxn
       instances are created by a Search::Elasticsearch::Role::CxnPool implementation, using the
       Search::Elasticsearch::Cxn::Factory class.

CONFIGURATION

       The configuration options are as follows:

   "node"
       A single "node" is passed to "new()" by the Search::Elasticsearch::Cxn::Factory class.  It
       can either be a URI or a hash containing each part.  For instance:

           node => 'localhost';                    # equiv of 'http://localhost:80'
           node => 'localhost:9200';               # equiv of 'http://localhost:9200'
           node => 'http://localhost:9200';

           node => 'https://localhost';            # equiv of 'https://localhost:443'
           node => 'localhost/path';               # equiv of 'http://localhost:80/path'

           node => 'http://user:pass@localhost';   # equiv of 'http://localhost:80'
                                                   # with userinfo => 'user:pass'

       Alternatively, a "node" can be specified as a hash:

           {
               scheme      => 'http',
               host        => 'search.domain.com',
               port        => '9200',
               path        => '/path',
               userinfo    => 'user:pass'
           }

       Similarly, default values can be specified with "port", "path_prefix", "userinfo" and
       "use_https":

           $e = Search::Elasticsearch->new(
               port        => 9201,
               path_prefix => '/path',
               userinfo    => 'user:pass',
               use_https   => 1,
               nodes       => [ 'search1', 'search2' ]
           )

   "ssl_options"
       By default, all backends that support HTTPS disable verification of the host they are
       connecting to.  Use "ssl_options" to configure the type of verification that you would
       like the client to perform, or to configure the client to present its own certificate.

       The values accepted by "ssl_options" depend on the "Cxn" class.  See the documentation for
       the "Cxn" class that you are using.

   "max_content_length"
       By default, Elasticsearch nodes accept a maximum post body of 100MB or "104_857_600"
       bytes. This client enforces that limit.  The limit can be customised with the
       "max_content_length" parameter (specified in bytes).

       If you're using the Search::Elasticsearch::CxnPool::Sniff module, then the
       "max_content_length" will be automatically retrieved from the live cluster, unless you
       specify a custom "max_content_length":

           # max_content_length retrieved from cluster
           $e = Search::Elasticsearch->new(
               cxn_pool => 'Sniff'
           );

           # max_content_length fixed at 10,000 bytes
           $e = Search::Elasticsearch->new(
               cxn_pool           => 'Sniff',
               max_content_length => 10_000
           );

   "gzip"
       Enable Gzip compression of requests to and responses from Elasticsearch as follows:

           $e = Search::Elasticsearch->new(
               gzip => 1
           );

   "deflate"
       Enable Inflate/Deflate compression of requests to and responses from Elasticsearch as
       follows:

           $e = Search::Elasticsearch->new(
               deflate => 1
           );

       IMPORTANT: The "request_timeout", "ping_timeout", "sniff_timeout", and
       "sniff_request_timeout" parameters default to values that allow this module to function
       with low powered hardware and slow networks.  When you use Elasticsearch in production,
       you will probably want to reduce these timeout parameters to values that suit your
       environment.

       The configuration parameters are as follows:

   "request_timeout"
           $e = Search::Elasticsearch->new(
               request_timeout => 30
           );

       How long a normal request (ie not a ping or sniff request) should wait before throwing a
       "Timeout" error.  Defaults to 30 seconds.

       Note: In production, no CRUD or search request should take 30 seconds to run, although
       admin tasks like "upgrade()", "optimize()", or snapshot "create()" may take much longer. A
       more reasonable value for production would be 10 seconds or lower.

   "ping_timeout"
           $e = Search::Elasticsearch->new(
               ping_timeout => 2
           );

       How long a ping request should wait before throwing a "Timeout" error.  Defaults to 2
       seconds. The Search::Elasticsearch::CxnPool::Static module pings nodes on first use, after
       any failure, and periodically to ensure that nodes are healthy. The "ping_timeout" should
       be long enough to allow nodes respond in time, but not so long that sick nodes cause
       delays.  A reasonable value for use in production on reasonable hardware would be 0.3-1
       seconds.

   "dead_timeout"
           $e = Search::Elasticsearch->new(
               dead_timeout => 60
           );

       How long a Cxn should be considered to be dead (not used to serve requests), before it is
       retried.  The default is 60 seconds.  This value is increased by powers of 2 for each time
       a request fails.  In other words, the delay after each failure is as follows:

           Failure     Delay
           1           60 * 1  = 60 seconds
           2           60 * 2  = 120 seconds
           3           60 * 4  = 240 seconds
           4           60 * 8  = 480 seconds
           5           60 * 16 = 960 seconds

   "max_dead_timeout"
           $e = Search::Elasticsearch->new(
               max_dead_timeout => 3600
           );

       The maximum delay that should be applied to a failed node. If the "dead_timeout"
       calculation results in a delay greater than "max_dead_timeout" (default "3,600" seconds)
       then the "max_dead_timeout" is used instead.  In other words, dead nodes will be retried
       at least once every hour by default.

   "sniff_request_timeout"
           $e = Search::Elasticsearch->new(
               sniff_request_timeout => 2
           );

       How long a sniff request should wait before throwing a "Timeout" error.  Defaults to 2
       seconds. A reasonable value for production would be 0.5-2 seconds.

   "sniff_timeout"
           $e = Search::Elasticsearch->new(
               sniff_timeout => 1
           );

       How long the node being sniffed should wait for responses from other nodes before
       responding to the client.  Defaults to 1 second. A reasonable value in production would be
       0.3-1 seconds.

       Note: The "sniff_timeout" is distinct from the "sniff_request_timeout".  For example,
       let's say you have a cluster with 5 nodes, 2 of which are unhealthy (taking a long time to
       respond):

       •   If you sniff an unhealthy node, the request will throw a "Timeout" error after
           "sniff_request_timeout" seconds.

       •   If you sniff a healthy node, it will gather responses from the other nodes, and give
           up after "sniff_timeout" seconds, returning just the information it has managed to
           gather from the healthy nodes.

       NOTE: The "sniff_request_timeout" must be longer than the "sniff_timeout" to ensure that
       you get information about healthy nodes from the cluster.

   "handle_args"
       Any default arguments which should be passed when creating a new instance of the class
       which handles the network transport, eg HTTP::Tiny.

   "default_qs_params"
           $e = Search::Elasticsearch->new(
               default_qs_params => {
                   session_key => 'my_session_key'
               }
           );

       Any values passed to "default_qs_params" will be added to the query string of every
       request. Also see "default_headers()" in Search::Elasticsearch::Role::Cxn::HTTP.

METHODS

       None of the methods listed below are useful to the user. They are documented for those who
       are writing alternative implementations only.

   "scheme()"
           $scheme = $cxn->scheme;

       Returns the scheme of the connection, ie "http" or "https".

   "is_https()"
           $bool = $cxn->is_https;

       Returns "true" or "false" depending on whether the "/scheme()" is "https" or not.

   "userinfo()"
           $userinfo = $cxn->userinfo

       Returns the username and password of the cxn, if any, eg "user:pass".  If "userinfo" is
       provided, then a Basic Authorization header is added to each request.

   "default_headers()"
           $headers = $cxn->default_headers

       The default headers that are passed with each request.  This includes the
       "Accept-Encoding" header if "/deflate" is true, and the "Authorization" header if
       "/userinfo" has a value.  Also see "default_qs_params" in
       Search::Elasticsearch::Role::Cxn.

   "max_content_length()"
           $int = $cxn->max_content_length;

       Returns the maximum length in bytes that the HTTP body can have.

   "build_uri()"
           $uri = $cxn->build_uri({ path => '/_search', qs => { size => 10 }});

       Returns the HTTP URI to use for a particular request, combining the passed in "path"
       parameter with any defined "path_prefix", and adding the query-string parameters.

METHODS

       None of the methods listed below are useful to the user. They are documented for those who
       are writing alternative implementations only.

   "host()"
           $host = $cxn->host;

       The value of the "host" parameter, eg "search.domain.com".

   "port()"
           $port = $cxn->port;

       The value of the "port" parameter, eg 9200.

   "uri()"
           $uri = $cxn->uri;

       A URI object representing the node, eg "https://search.domain.com:9200/path".

   "is_dead()"
           $bool = $cxn->is_dead

       Is the current node marked as dead.

   "is_live()"
           $bool = $cxn->is_live

       Is the current node marked as live.

   "next_ping()"
           $time = $cxn->next_ping($time)

       Get/set the time for the next scheduled ping.  If zero, no ping is scheduled and the cxn
       is considered to be alive.  If -1, a ping is scheduled before the next use.

   "ping_failures()"
           $num = $cxn->ping_failures($num)

       The number of times that a cxn has been marked as dead.

   "mark_dead()"
           $cxn->mark_dead

       Mark the cxn as dead, set "next_ping()" and increment "ping_failures()".

   "mark_live()"
       Mark the cxn as live, set "next_ping()" and "ping_failures()" to zero.

   "force_ping()"
       Set "next_ping()" to -1 (ie before next use) and "ping_failures()" to zero.

   "pings_ok()"
           $bool = $cxn->pings_ok

       Try to ping the node and call "mark_live()" or "mark_dead()" depending on the success or
       failure of the ping.

   "sniff()"
           $response = $cxn->sniff;

       Send a sniff request to the node and return the response.

   "process_response()"
           ($code,$result) = $cxn->process_response($params, $code, $msg, $body );

       Processes the response received from an Elasticsearch node and either returns the HTTP
       status code and the response body (deserialized from JSON) or throws an error of the
       appropriate type.

       The $params are the original params passed to "perform_request()" in
       Search::Elasticsearch::Transport, the $code is the HTTP status code, the $msg is the error
       message returned by the backend library and the $body is the HTTP response body returned
       by Elasticsearch.

AUTHOR

       Enrico Zimuel <enrico.zimuel@elastic.co>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2022 by Elasticsearch BV.

       This is free software, licensed under:

         The Apache License, Version 2.0, January 2004