- DESCRIPTION
- CONFIGURATION
  - `node`
  - `max_content_length`
  - `deflate`
- METHODS
  - `scheme()`
  - `is_https()`
  - `userinfo()`
  - `default_headers()`
  - `max_content_length()`
  - `build_uri()`

# DESCRIPTION

Elasticsearch::Role::Cxn::HTTP provides common functionality to the Cxn implementations which use the HTTP protocol. Cxn instances are created by a Elasticsearch::Role::CxnPool implentation, using the Elasticsearch::Cxn::Factory class.

This class does Elasticsearch::Role::Cxn.

# CONFIGURATION

The configuration options are as follows:

## `node`

A single `node` is passed to `new()` by the 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 = Elasticsearch->new(
            port        => 9201,
            path_prefix => '/path',
            userinfo    => 'user:pass',
            use_https   => 1,
            nodes       => [ 'search1', 'search2' ]
        )

## `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 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 = Elasticsearch->new(
            cxn_pool => 'Sniff'
        );

        # max_content_length fixed at 10,000 bytes
        $e = 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 = 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.

## `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.