<html>
<head>
<title></title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
<link rel='stylesheet' href='https://metacpan.org/_asset/288683e3285b02987a848283f0f92207' type='text/css'>
<script type='text/javascript' src='https://metacpan.org/_asset/12b19d083bf773523c065d4d729f0327'></script>
</head>
<body>
<div class="pod">
<ul id="index">
<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
<li><a href="#CONFIGURATION">CONFIGURATION</a>
<ul>
<li><a href="#request_timeout"><code>request_timeout</code></a></li>
<li><a href="#ping_timeout"><code>ping_timeout</code></a></li>
<li><a href="#dead_timeout"><code>dead_timeout</code></a></li>
<li><a href="#max_dead_timeout"><code>max_dead_timeout</code></a></li>
<li><a href="#sniff_request_timeout"><code>sniff_request_timeout</code></a></li>
<li><a href="#sniff_timeout"><code>sniff_timeout</code></a></li>
<li><a href="#handle_args"><code>handle_args</code></a></li>
</ul>
</li>
<li><a href="#METHODS">METHODS</a>
<ul>
<li><a href="#host-"><code>host()</code></a></li>
<li><a href="#port-"><code>port()</code></a></li>
<li><a href="#uri-"><code>uri()</code></a></li>
<li><a href="#is_dead-"><code>is_dead()</code></a></li>
<li><a href="#is_live-"><code>is_live()</code></a></li>
<li><a href="#next_ping-"><code>next_ping()</code></a></li>
<li><a href="#ping_failures-"><code>ping_failures()</code></a></li>
<li><a href="#mark_dead-"><code>mark_dead()</code></a></li>
<li><a href="#mark_live-"><code>mark_live()</code></a></li>
<li><a href="#force_ping-"><code>force_ping()</code></a></li>
<li><a href="#pings_ok-"><code>pings_ok()</code></a></li>
<li><a href="#sniff-"><code>sniff()</code></a></li>
<li><a href="#process_response-"><code>process_response()</code></a></li>
</ul>
</li>
</ul>
<h1 id="DESCRIPTION">DESCRIPTION</h1>
<p><a href="./Elasticsearch::Role::Cxn">Elasticsearch::Role::Cxn</a> provides common functionality to the Cxn implementations. Cxn instances are created by a <a href="./Elasticsearch::Role::CxnPool">Elasticsearch::Role::CxnPool</a> implentation, using the <a href="./Elasticsearch::Cxn::Factory">Elasticsearch::Cxn::Factory</a> class.</p>
<h1 id="CONFIGURATION">CONFIGURATION</h1>
<p>The configuration parameters are as follows:</p>
<h2 id="request_timeout"><code>request_timeout</code></h2>
<pre class="brush: pl; class-name: 'highlight'; toolbar: false; gutter: false"> $e = Elasticsearch->new(
request_timeout => 10
);</pre>
<p>How long a normal request (ie not a ping or sniff request) should wait before throwing a <code>Timeout</code> error. Defaults to <code>10</code> seconds.</p>
<h2 id="ping_timeout"><code>ping_timeout</code></h2>
<pre class="brush: pl; class-name: 'highlight'; toolbar: false; gutter: false"> $e = Elasticsearch->new(
request_timeout => 0.3
);</pre>
<p>How long a ping request should wait before throwing a <code>Timeout</code> error. Defaults to <code>0.3</code> seconds. You may want to increase this if you are using the <a href="./Elasticsearch::CxnPool::Static">Elasticsearch::CxnPool::Static</a> connection pool with a slow network.</p>
<h2 id="dead_timeout"><code>dead_timeout</code></h2>
<p>How long a Cxn should be considered to be <i>dead</i> (not used to serve requests), before it is retried. The default is <code>60</code> 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:</p>
<pre class="brush: pl; class-name: 'highlight'; toolbar: false; gutter: false"> 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</pre>
<h2 id="max_dead_timeout"><code>max_dead_timeout</code></h2>
<p>The maximum delay that should be applied to a failed node. If the <a href="#dead_timeout">"dead_timeout"</a> calculation results in a delay greater than <code>max_dead_timeout</code> (default <code>3,600</code> seconds) then the <code>max_dead_timeout</code> is used instead. In other words, dead nodes will be retried at least once every hour by default.</p>
<h2 id="sniff_request_timeout"><code>sniff_request_timeout</code></h2>
<p>How long a sniff request should wait before throwing a <code>Timeout</code> error. Defaults to <code>0.3</code> seconds. You may want to increase this if you are using the <a href="./Elasticsearch::CxnPool::Sniff">Elasticsearch::CxnPool::Sniff</a> connection pool with a slow network.</p>
<h2 id="sniff_timeout"><code>sniff_timeout</code></h2>
<p>How long the node being sniffed should wait for responses from other nodes before responding to the client. <b>Note:</b> this is distinct from the <a href="#sniff_request_timeout">"sniff_request_timeout"</a>. For example, let's say you have a cluster with 5 nodes, 2 of which are unhealthy (taking a long time to respond):</p>
<ul>
<li><p>If you sniff an unhealthy node, the request will throw a <code>Timeout</code> error after <code>sniff_request_timeout</code> seconds.</p>
</li>
<li><p>If you sniff a healthy node, it will gather responses from the other nodes, and give up after <code>sniff_timeout</code> seconds, returning just the information it has managed to gather from the healthy nodes.</p>
</li>
</ul>
<p><b>NOTE:</b> The <code>sniff_request_timeout</code> must be longer than the <code>sniff_timeout</code> to ensure that you get information about healthy nodes from the cluster.</p>
<p>For CxnPool's which implement sniffing (see <a href="./Elasticsearch::CxnPool::Sniff">Elasticsearch::CxnPool::Sniff</a>), the <code>sniff_timeout</code> is the amount of time that the node being sniffed will wait to receive responses from other nodes, before returning a list of healthy nodes.</p>
<h2 id="handle_args"><code>handle_args</code></h2>
<p>Any default arguments which should be passed when creating a new instance of the class which handles the network transport, eg <a href="./HTTP::Tiny">HTTP::Tiny</a>.</p>
<h1 id="METHODS">METHODS</h1>
<p>None of the methods listed below are useful to the user. They are documented for those who are writing alternative implementations only.</p>
<h2 id="host-"><code>host()</code></h2>
<pre class="brush: pl; class-name: 'highlight'; toolbar: false; gutter: false"> $host = $cxn->host;</pre>
<p>The value of the <code>host</code> parameter, eg <code>search.domain.com</code>.</p>
<h2 id="port-"><code>port()</code></h2>
<pre class="brush: pl; class-name: 'highlight'; toolbar: false; gutter: false"> $port = $cxn->port;</pre>
<p>The value of the <code>port</code> parameter, eg <code>9200</code>.</p>
<h2 id="uri-"><code>uri()</code></h2>
<pre class="brush: pl; class-name: 'highlight'; toolbar: false; gutter: false"> $uri = $cxn->uri;</pre>
<p>A <a href="./URI">URI</a> object representing the node, eg <code>https://search.domain.com:9200/path</code>.</p>
<h2 id="is_dead-"><code>is_dead()</code></h2>
<pre class="brush: pl; class-name: 'highlight'; toolbar: false; gutter: false"> $bool = $cxn->is_dead</pre>
<p>Is the current node marked as <i>dead</i>.</p>
<h2 id="is_live-"><code>is_live()</code></h2>
<pre class="brush: pl; class-name: 'highlight'; toolbar: false; gutter: false"> $bool = $cxn->is_live</pre>
<p>Is the current node marked as <i>live</i>.</p>
<h2 id="next_ping-"><code>next_ping()</code></h2>
<pre class="brush: pl; class-name: 'highlight'; toolbar: false; gutter: false"> $time = $cxn->next_ping($time)</pre>
<p>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.</p>
<h2 id="ping_failures-"><code>ping_failures()</code></h2>
<pre class="brush: pl; class-name: 'highlight'; toolbar: false; gutter: false"> $num = $cxn->ping_failures($num)</pre>
<p>The number of times that a cxn has been marked as dead.</p>
<h2 id="mark_dead-"><code>mark_dead()</code></h2>
<pre class="brush: pl; class-name: 'highlight'; toolbar: false; gutter: false"> $cxn->mark_dead</pre>
<p>Mark the cxn as <i>dead</i>, set <a href="#next_ping-">"next_ping()"</a> and increment <a href="#ping_failures-">"ping_failures()"</a>.</p>
<h2 id="mark_live-"><code>mark_live()</code></h2>
<p>Mark the cxn as <i>live</i>, set <a href="#next_ping-">"next_ping()"</a> and <a href="#ping_failures-">"ping_failures()"</a> to zero.</p>
<h2 id="force_ping-"><code>force_ping()</code></h2>
<p>Set <a href="#next_ping-">"next_ping()"</a> to -1 (ie before next use) and <a href="#ping_failures-">"ping_failures()"</a> to zero.</p>
<h2 id="pings_ok-"><code>pings_ok()</code></h2>
<pre class="brush: pl; class-name: 'highlight'; toolbar: false; gutter: false"> $bool = $cxn->pings_ok</pre>
<p>Try to ping the node and call <a href="#mark_live-">"mark_live()"</a> or <a href="#mark_dead-">"mark_dead()"</a> depending on the success or failure of the ping.</p>
<h2 id="sniff-"><code>sniff()</code></h2>
<pre class="brush: pl; class-name: 'highlight'; toolbar: false; gutter: false"> $response = $cxn->sniff;</pre>
<p>Send a sniff request to the node and return the response.</p>
<h2 id="process_response-"><code>process_response()</code></h2>
<pre class="brush: pl; class-name: 'highlight'; toolbar: false; gutter: false"> ($code,$result) = $cxn->process_response($params, $code, $msg, $body );</pre>
<p>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.</p>
<p>The <code>$params</code> are the original params passed to <a href="./Elasticsearch::Transport#perform_request-">"perform_request()" in Elasticsearch::Transport</a>, the <code>$code</code> is the HTTP status code, the <code>$msg</code> is the error message returned by the backend library and the <code>$body</code> is the HTTP response body returned by Elasticsearch.</p>
</div>
</body>
</html>