1Search::Elasticsearch::URsoelre:C:oCnxtnr(i3b)uted PerlSDeoacrucmhe:n:tEaltaisotnicsearch::Role::Cxn(3)
2
3
4

NAME

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

VERSION

10       version 7.715
11

DESCRIPTION

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

CONFIGURATION

19       The configuration options are as follows:
20
21   "node"
22       A single "node" is passed to "new()" by the
23       Search::Elasticsearch::Cxn::Factory class.  It can either be a URI or a
24       hash containing each part.  For instance:
25
26           node => 'localhost';                    # equiv of 'http://localhost:80'
27           node => 'localhost:9200';               # equiv of 'http://localhost:9200'
28           node => 'http://localhost:9200';
29
30           node => 'https://localhost';            # equiv of 'https://localhost:443'
31           node => 'localhost/path';               # equiv of 'http://localhost:80/path'
32
33
34           node => 'http://user:pass@localhost';   # equiv of 'http://localhost:80'
35                                                   # with userinfo => 'user:pass'
36
37       Alternatively, a "node" can be specified as a hash:
38
39           {
40               scheme      => 'http',
41               host        => 'search.domain.com',
42               port        => '9200',
43               path        => '/path',
44               userinfo    => 'user:pass'
45           }
46
47       Similarly, default values can be specified with "port", "path_prefix",
48       "userinfo" and "use_https":
49
50           $e = Search::Elasticsearch->new(
51               port        => 9201,
52               path_prefix => '/path',
53               userinfo    => 'user:pass',
54               use_https   => 1,
55               nodes       => [ 'search1', 'search2' ]
56           )
57
58   "ssl_options"
59       By default, all backends that support HTTPS disable verification of the
60       host they are connecting to.  Use "ssl_options" to configure the type
61       of verification that you would like the client to perform, or to
62       configure the client to present its own certificate.
63
64       The values accepted by "ssl_options" depend on the "Cxn" class.  See
65       the documentation for the "Cxn" class that you are using.
66
67   "max_content_length"
68       By default, Elasticsearch nodes accept a maximum post body of 100MB or
69       "104_857_600" bytes. This client enforces that limit.  The limit can be
70       customised with the "max_content_length" parameter (specified in
71       bytes).
72
73       If you're using the Search::Elasticsearch::CxnPool::Sniff module, then
74       the "max_content_length" will be automatically retrieved from the live
75       cluster, unless you specify a custom "max_content_length":
76
77           # max_content_length retrieved from cluster
78           $e = Search::Elasticsearch->new(
79               cxn_pool => 'Sniff'
80           );
81
82           # max_content_length fixed at 10,000 bytes
83           $e = Search::Elasticsearch->new(
84               cxn_pool           => 'Sniff',
85               max_content_length => 10_000
86           );
87
88   "gzip"
89       Enable Gzip compression of requests to and responses from Elasticsearch
90       as follows:
91
92           $e = Search::Elasticsearch->new(
93               gzip => 1
94           );
95
96   "deflate"
97       Enable Inflate/Deflate compression of requests to and responses from
98       Elasticsearch as follows:
99
100           $e = Search::Elasticsearch->new(
101               deflate => 1
102           );
103
104       IMPORTANT: The "request_timeout", "ping_timeout", "sniff_timeout", and
105       "sniff_request_timeout" parameters default to values that allow this
106       module to function with low powered hardware and slow networks.  When
107       you use Elasticsearch in production, you will probably want to reduce
108       these timeout parameters to values that suit your environment.
109
110       The configuration parameters are as follows:
111
112   "request_timeout"
113           $e = Search::Elasticsearch->new(
114               request_timeout => 30
115           );
116
117       How long a normal request (ie not a ping or sniff request) should wait
118       before throwing a "Timeout" error.  Defaults to 30 seconds.
119
120       Note: In production, no CRUD or search request should take 30 seconds
121       to run, although admin tasks like "upgrade()", "optimize()", or
122       snapshot "create()" may take much longer. A more reasonable value for
123       production would be 10 seconds or lower.
124
125   "ping_timeout"
126           $e = Search::Elasticsearch->new(
127               ping_timeout => 2
128           );
129
130       How long a ping request should wait before throwing a "Timeout" error.
131       Defaults to 2 seconds. The Search::Elasticsearch::CxnPool::Static
132       module pings nodes on first use, after any failure, and periodically to
133       ensure that nodes are healthy. The "ping_timeout" should be long enough
134       to allow nodes respond in time, but not so long that sick nodes cause
135       delays.  A reasonable value for use in production on reasonable
136       hardware would be 0.3-1 seconds.
137
138   "dead_timeout"
139           $e = Search::Elasticsearch->new(
140               dead_timeout => 60
141           );
142
143       How long a Cxn should be considered to be dead (not used to serve
144       requests), before it is retried.  The default is 60 seconds.  This
145       value is increased by powers of 2 for each time a request fails.  In
146       other words, the delay after each failure is as follows:
147
148           Failure     Delay
149           1           60 * 1  = 60 seconds
150           2           60 * 2  = 120 seconds
151           3           60 * 4  = 240 seconds
152           4           60 * 8  = 480 seconds
153           5           60 * 16 = 960 seconds
154
155   "max_dead_timeout"
156           $e = Search::Elasticsearch->new(
157               max_dead_timeout => 3600
158           );
159
160       The maximum delay that should be applied to a failed node. If the
161       "dead_timeout" calculation results in a delay greater than
162       "max_dead_timeout" (default "3,600" seconds) then the
163       "max_dead_timeout" is used instead.  In other words, dead nodes will be
164       retried at least once every hour by default.
165
166   "sniff_request_timeout"
167           $e = Search::Elasticsearch->new(
168               sniff_request_timeout => 2
169           );
170
171       How long a sniff request should wait before throwing a "Timeout" error.
172       Defaults to 2 seconds. A reasonable value for production would be 0.5-2
173       seconds.
174
175   "sniff_timeout"
176           $e = Search::Elasticsearch->new(
177               sniff_timeout => 1
178           );
179
180       How long the node being sniffed should wait for responses from other
181       nodes before responding to the client.  Defaults to 1 second. A
182       reasonable value in production would be 0.3-1 seconds.
183
184       Note: The "sniff_timeout" is distinct from the "sniff_request_timeout".
185       For example, let's say you have a cluster with 5 nodes, 2 of which are
186       unhealthy (taking a long time to respond):
187
188       •   If you sniff an unhealthy node, the request will throw a "Timeout"
189           error after "sniff_request_timeout" seconds.
190
191       •   If you sniff a healthy node, it will gather responses from the
192           other nodes, and give up after "sniff_timeout" seconds, returning
193           just the information it has managed to gather from the healthy
194           nodes.
195
196       NOTE: The "sniff_request_timeout" must be longer than the
197       "sniff_timeout" to ensure that you get information about healthy nodes
198       from the cluster.
199
200   "handle_args"
201       Any default arguments which should be passed when creating a new
202       instance of the class which handles the network transport, eg
203       HTTP::Tiny.
204
205   "default_qs_params"
206           $e = Search::Elasticsearch->new(
207               default_qs_params => {
208                   session_key => 'my_session_key'
209               }
210           );
211
212       Any values passed to "default_qs_params" will be added to the query
213       string of every request. Also see "default_headers()" in
214       Search::Elasticsearch::Role::Cxn::HTTP.
215

METHODS

217       None of the methods listed below are useful to the user. They are
218       documented for those who are writing alternative implementations only.
219
220   "scheme()"
221           $scheme = $cxn->scheme;
222
223       Returns the scheme of the connection, ie "http" or "https".
224
225   "is_https()"
226           $bool = $cxn->is_https;
227
228       Returns "true" or "false" depending on whether the "/scheme()" is
229       "https" or not.
230
231   "userinfo()"
232           $userinfo = $cxn->userinfo
233
234       Returns the username and password of the cxn, if any, eg "user:pass".
235       If "userinfo" is provided, then a Basic Authorization header is added
236       to each request.
237
238   "default_headers()"
239           $headers = $cxn->default_headers
240
241       The default headers that are passed with each request.  This includes
242       the "Accept-Encoding" header if "/deflate" is true, and the
243       "Authorization" header if "/userinfo" has a value.  Also see
244       "default_qs_params" in Search::Elasticsearch::Role::Cxn.
245
246   "max_content_length()"
247           $int = $cxn->max_content_length;
248
249       Returns the maximum length in bytes that the HTTP body can have.
250
251   "build_uri()"
252           $uri = $cxn->build_uri({ path => '/_search', qs => { size => 10 }});
253
254       Returns the HTTP URI to use for a particular request, combining the
255       passed in "path" parameter with any defined "path_prefix", and adding
256       the query-string parameters.
257

METHODS

259       None of the methods listed below are useful to the user. They are
260       documented for those who are writing alternative implementations only.
261
262   "host()"
263           $host = $cxn->host;
264
265       The value of the "host" parameter, eg "search.domain.com".
266
267   "port()"
268           $port = $cxn->port;
269
270       The value of the "port" parameter, eg 9200.
271
272   "uri()"
273           $uri = $cxn->uri;
274
275       A URI object representing the node, eg
276       "https://search.domain.com:9200/path".
277
278   "is_dead()"
279           $bool = $cxn->is_dead
280
281       Is the current node marked as dead.
282
283   "is_live()"
284           $bool = $cxn->is_live
285
286       Is the current node marked as live.
287
288   "next_ping()"
289           $time = $cxn->next_ping($time)
290
291       Get/set the time for the next scheduled ping.  If zero, no ping is
292       scheduled and the cxn is considered to be alive.  If -1, a ping is
293       scheduled before the next use.
294
295   "ping_failures()"
296           $num = $cxn->ping_failures($num)
297
298       The number of times that a cxn has been marked as dead.
299
300   "mark_dead()"
301           $cxn->mark_dead
302
303       Mark the cxn as dead, set "next_ping()" and increment
304       "ping_failures()".
305
306   "mark_live()"
307       Mark the cxn as live, set "next_ping()" and "ping_failures()" to zero.
308
309   "force_ping()"
310       Set "next_ping()" to -1 (ie before next use) and "ping_failures()" to
311       zero.
312
313   "pings_ok()"
314           $bool = $cxn->pings_ok
315
316       Try to ping the node and call "mark_live()" or "mark_dead()" depending
317       on the success or failure of the ping.
318
319   "sniff()"
320           $response = $cxn->sniff;
321
322       Send a sniff request to the node and return the response.
323
324   "process_response()"
325           ($code,$result) = $cxn->process_response($params, $code, $msg, $body );
326
327       Processes the response received from an Elasticsearch node and either
328       returns the HTTP status code and the response body (deserialized from
329       JSON) or throws an error of the appropriate type.
330
331       The $params are the original params passed to "perform_request()" in
332       Search::Elasticsearch::Transport, the $code is the HTTP status code,
333       the $msg is the error message returned by the backend library and the
334       $body is the HTTP response body returned by Elasticsearch.
335

AUTHOR

337       Enrico Zimuel <enrico.zimuel@elastic.co>
338
340       This software is Copyright (c) 2021 by Elasticsearch BV.
341
342       This is free software, licensed under:
343
344         The Apache License, Version 2.0, January 2004
345
346
347
348perl v5.34.0                      2022-01-21Search::Elasticsearch::Role::Cxn(3)
Impressum