Search...e::Cxn(3pm)

📦
version 8.12 · 5 versions
, in debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ Search::Elasticsearch::Role::Cxn 💅

okay bestie, so this is Search::Elasticsearch::Role::Cxn from the 3pm manual — it's giving deep internals, the kind of page you only read if you're building stuff, not just using it. Pull up a chair 🫶

🌸 VERSION 🌸

version 8.12 — that's the one, no cap.

💖 DESCRIPTION 💖

Search::Elasticsearch::Role::Cxn hands out the shared, common functionality to all the Cxn implementations. Like, the whole squad of them.

And where do Cxn instances come from? Not from you, bestie. They're created by a Search::Elasticsearch::Role::CxnPool implementation, using the Search::Elasticsearch::Cxn::Factory class. Factory-made, iconic behavior 👑

🎀 CONFIGURATION 🎀

okay so here are the config options, and yes we're going through every single one because that's just how we do it:

🦋 node

A single node gets passed to new() by the Search::Elasticsearch::Cxn::Factory class. It can be either a URI or a hash holding each little piece. Like so:

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'

Or, plot twist, a node can be a hash:

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

Same energy, you can also set default values 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

Default behavior, real talk: all backends that support HTTPS disable verification of the host they're connecting to. 😭 Use ssl_options to configure the type of verification you want the client to perform, or to make the client present its own certificate.

The values ssl_options accepts depend on the Cxn class. So go read the docs for the Cxn class you're actually using, bestie — that's where the tea is.

📏 max_content_length

By default, Elasticsearch nodes accept a maximum post body of 100MB, aka 104_857_600 bytes. This client enforces that limit. You can customise it with the max_content_length parameter (specified in bytes).

And if you're using the Search::Elasticsearch::CxnPool::Sniff module, the max_content_length gets 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, like this:

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

🎈 deflate

Enable Inflate/Deflate compression of requests to and responses from Elasticsearch, like this:

$e = Search::Elasticsearch->new(
    deflate => 1
);
IMPORTANT: the request_timeout, ping_timeout, sniff_timeout, and sniff_request_timeout parameters default to values that let this module function on low powered hardware and slow networks. When you use Elasticsearch in production, you're probably gonna 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. fr fr.

🏓 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 make sure nodes are healthy. The ping_timeout should be long enough to let nodes respond in time, but not so long that sick nodes cause delays. A reasonable value for 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 dead (not used to serve requests) before it gets retried. The default is 60 seconds. This value increases by powers of 2 each time a request fails. In other words, the delay after each failure goes like:

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

the way that math just keeps doubling… exponential era 🫶

🧊 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 max_dead_timeout is used instead. In other words, dead nodes get retried at least once every hour by default. periodt.

👃 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. Example time — 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 💜

okay so, heads up: none of the methods listed below are useful to the user. They are documented for those who are writing alternative implementations only. iykyk 🧚

🧵 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 🌈

yes bestie, another METHODS section — and same disclaimer as before: 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.

...and that's part 1, bestie — there's more coming so don't go anywhere 💖

💖 AUTHOR 💖

Okay so the actual human genius behind this whole masterpiece is Enrico Zimuel, and if you ever need to be like "bestie your module ate fr fr", the email is right here:

  • Enrico Zimuel <enrico.zimuel@elastic.co>

That's it. That's the author. Give him his flowers 💐👑

The legal tea, no cap:

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

And the best part? It's free software, bestie. Licensed under:

The Apache License, Version 2.0, January 2004

So yeah, you can use it, you just gotta respect the license. That's the deal 🤝✨

And that's a wrap on the whole page, babes! This was Search...e::Cxn(3pm) — yep, that long glorious truncated name is literally what the page calls itself, iconic behavior honestly 💅 — as documented in perl v5.38.2, dated 2024-02-04. Screenshot it, bookmark it, tattoo it on your forearm, whatever you gotta do. Go forth and make your connections slay 🦋🌸💜
📦 where this page comes from