NAME

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

VERSION

version 2.02

DESCRIPTION

Search::Elasticsearch::Role::Cxn::HTTP provides common functionality to the Cxn implementations which use the HTTP protocol. 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
    );

deflate

This client can request compressed responses from Elasticsearch by enabling the http.compression config setting in Elasticsearch and setting deflate to true:

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

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.

AUTHOR

Clinton Gormley <drtech@cpan.org>

COPYRIGHT AND LICENSE

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

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004

cpanm Search::Elasticsearch

perl -MCPAN -e shell
install Search::Elasticsearch