view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

- `max_size`

    Integer. Set the size limit for response content. If the response content exceeds the value set here, the request will be aborted and a `Client-Aborted` header will be added to the response object returned. Default value is `undef`, i.e. no limit...

    See also the `threshold` option.

- `medium`

    This can be either `file`, `mmap` or `memory`. This will be passed on to [Promise::Me](https://metacpan.org/pod/Promise%3A%3AMe) as `result_shared_mem_size` to store resulting data between processes. See [Promise::Me](https://metacpan.org/pod/Pro...

    It defaults to `$Promise::Me::SHARE_MEDIUM`

- `no_proxy`

    Array reference. Do not proxy requests to the given domains.

- `proxy`

    The url of the proxy to use for the HTTP requests.

- `requests_redirectable`

    Array reference. This sets the list of http methods that are allowed to be redirected. Default to empty, which means that all methods can be redirected.

- `serialiser`

    String. Specify the serialiser to use for [Promise::Me](https://metacpan.org/pod/Promise%3A%3AMe). Possible values are: [cbor](https://metacpan.org/pod/CBOR%3A%3AXS), [sereal](https://metacpan.org/pod/Sereal) or [storable](https://metacpan.org/po...

    By default it uses the value set in the global variable `$SERIALISER`, which is a copy of the `$SERIALISER` in [Promise::Me](https://metacpan.org/pod/Promise%3A%3AMe), which should be by default `storable`

- `shared_mem_size`

    Integer. This will be passed on to [Promise::Me](https://metacpan.org/pod/Promise%3A%3AMe). See [Promise::Me](https://metacpan.org/pod/Promise%3A%3AMe) for more details.

    It defaults to `$Promise::Me::RESULT_MEMORY_SIZE`

- `ssl_opts`

    Hash reference. Sets an hash reference of ssl options. The default values are set as follows:

    - 1. `verify_hostname`

        When enabled, this ensures it connects to servers that have a valid certificate matching the expected hostname.

        - 1.1. If environment variable `PERL_LWP_SSL_VERIFY_HOSTNAME` is set, the ssl option property `verify_hostname` takes its value.
        - 1.2. If environment variable `HTTPS_CA_FILE` or `HTTPS_CA_DIR` are set to a true value, then the ssl option property `verify_hostname` is set to `0` and option property `SSL_verify_mode` is set to `1`
        - 1.3 If none of the above applies, it defaults `verify_hostname` to `1`

    - 2. `SSL_ca_file`

        This is the path to a file containing the Certificate Authority certificates.

        If environment variable `PERL_LWP_SSL_CA_FILE` or `HTTPS_CA_FILE` is set, then the ssl option property `SSL_ca_file` takes its value.

    - 3. `SSL_ca_path`

        This is the path to a directory of files containing Certificate Authority certificates.

        If environment variable `PERL_LWP_SSL_CA_PATH` or `HTTPS_CA_DIR` is set, then the ssl option property `SSL_ca_path` takes its value.

    Other options can be set and are processed directly by the SSL Socket implementation in use. See [IO::Socket::SSL](https://metacpan.org/pod/IO%3A%3ASocket%3A%3ASSL) or [Net::SSL](https://metacpan.org/pod/Net%3A%3ASSL) for details.

- `threshold`

    Integer. Sets the content length threshold beyond which, the response content will be stored to a locale file. It can then be fetch with ["file"](#file). Default to global variable `$CONTENT_SIZE_THRESHOLD`, which is `undef` by default.

    See also the `max_size` option.

- `timeout`

    Integer. Sets the timeout value. Defaults to 180 seconds, i.e. 3 minutes.

- `use_content_file`

    Boolean. Enables the use of a temporary local file to store the response content, no matter the size o the response content.

- `use_promise`

    Boolean. When true, this will have [HTTP::Promise](https://metacpan.org/pod/HTTP%3A%3APromise) HTTP methods return a [HTTP::Promise](https://metacpan.org/pod/promise), and when false, it returns directly the [HTTP::Promise::Response](https://meta...

# METHODS

The following methods are available. This interface provides similar interface as [LWP::UserAgent](https://metacpan.org/pod/LWP%3A%3AUserAgent) while providing more granular control.

## accept\_encoding

String. Sets or gets whether we should accept compressed data.

You can set it to `none` to disable it. By default, this is `auto`, and it will set the `Accept-Encoding` `HTTP` header to all the supported encoding based on the availability of associated modules.

You can also set this to a comma-separated list of known encoding, typically: `bzip2,deflate,gzip,rawdeflate,brotli`

See [HTTP::Promise::Stream](https://metacpan.org/pod/HTTP%3A%3APromise%3A%3AStream) for more details.

Returns a [scalar object](https://metacpan.org/pod/Module%3A%3AGeneric%3A%3AScalar) of the current value.

## accept\_language

An array of acceptable language. This will be used to set the `Accept-Language` header.

See also [HTTP::Promise::Headers::AcceptLanguage](https://metacpan.org/pod/HTTP%3A%3APromise%3A%3AHeaders%3A%3AAcceptLanguage)

## agent

This is a string.

Sets or gets the agent id used to identify when making the server connection.

It defaults to `HTTP-Promise/v0.1.0`

    my $p = HTTP::Promise->new( agent => 'MyBot/1.0' );
    $p->agent( 'Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:99.0) Gecko/20100101 Firefox/99.0' );

The `User-Agent` header field is only set to this provided value if it is not already set.

## accept\_language

Sets or gets an array of acceptable response content languages.

For example:

README.md  view on Meta::CPAN

    my $p = HTTP::Promise->new( send_te => 1 );
    $p->send_te(1);
    my $bool = $p->send_te;

## serialiser

String. Sets or gets the serialiser to use for [Promise::Me](https://metacpan.org/pod/Promise%3A%3AMe). Possible values are: [cbor](https://metacpan.org/pod/CBOR%3A%3AXS), [sereal](https://metacpan.org/pod/Sereal) or [storable](https://metacpan.org/p...

By default, the value is set to the global variable `$SERIALISER`, which is a copy of the `$SERIALISER` in [Promise::Me](https://metacpan.org/pod/Promise%3A%3AMe), which should be by default `storable`

## simple\_request

This method takes the same parameters as ["request"](#request) and differs in that it will not try to handle redirects or authentication.

It returns a [promise object](https://metacpan.org/pod/Promise%3A%3AMe) just like other methods.

For example:

    use HTTP::Promise::Request;
    my $req = HTTP::Promise::Request->new( get => 'https://example.com' );
    my $p = HTTP::Promise->new;
    my $prom = $p->simple_request( $req )->then(sub
    {
        my( $resolve, $reject ) = @$_;
        # Get the HTTP::Promise::Response object
        my $resp = shift( @_ );
        # Do something with the response object
    })->catch(sub
    {
        # Get a HTTP::Promise::Exception object
        my $ex = shift( @_ );
        say "Got an error code ", $ex->code, " with message: ", $ex->message;
    });

However, if ["use\_promise"](#use_promise) is set to false, this will return an [HTTP::Promise::Response](https://metacpan.org/pod/HTTP%3A%3APromise%3A%3AResponse) object directly.

## ssl\_opts

[Hash reference object](https://metacpan.org/pod/Module%3A%3AGeneric%3A%3AHash). Sets or gets the ssl options properties used when making requests over ssl. The default values are set as follows:

- 1. `verify_hostname`

    When enabled, this ensures it connects to servers that have a valid certificate matching the expected hostname.

    - 1.1. If environment variable `PERL_LWP_SSL_VERIFY_HOSTNAME` is set, the ssl option property `verify_hostname` takes its value.
    - 1.2. If environment variable `HTTPS_CA_FILE` or `HTTPS_CA_DIR` are set to a true value, then the ssl option property `verify_hostname` is set to `0` and option property `SSL_verify_mode` is set to `1`
    - 1.3 If none of the above applies, it defaults `verify_hostname` to `1`

- 2. `SSL_ca_file`

    This is the path to a file containing the Certificate Authority certificates.

    If environment variable `PERL_LWP_SSL_CA_FILE` or `HTTPS_CA_FILE` is set, then the ssl option property `SSL_ca_file` takes its value.

- 3. `SSL_ca_path`

    This is the path to a directory of files containing Certificate Authority certificates.

    If environment variable `PERL_LWP_SSL_CA_PATH` or `HTTPS_CA_DIR` is set, then the ssl option property `SSL_ca_path` takes its value.

Other options can be set and are processed directly by the SSL Socket implementation in use. See [IO::Socket::SSL](https://metacpan.org/pod/IO%3A%3ASocket%3A%3ASSL) or [Net::SSL](https://metacpan.org/pod/Net%3A%3ASSL) for details.

## stop\_if

Sets or gets a callback code reference (reference to a perl subroutine or an anonymous subroutine) that will be used to determine if we  should keep trying upon reading data from the filehandle and an `EINTR` error occurs.

If the callback returns true, further attempts will stop and return an error. The default is to continue trying.

## threshold

Integer. Sets the content length threshold beyond which, the response content will be stored to a locale file. It can then be fetch with ["file"](#file). Default to global variable `$CONTENT_SIZE_THRESHOLD`, which is `undef` by default.

See also the ["max\_size"](#max_size) option.

    my $p = HTTP::Promise->new( threshold => 512000 );
    $p->threshold(512000);
    my $limit = $p->threshold;

## timeout

Integer. Sets the timeout value. Defaults to 180 seconds, i.e. 3 minutes.

The request is aborted if no activity on the connection to the server is observed for `timeout` seconds. When a request times out, a [response object](https://metacpan.org/pod/HTTP%3A%3APromise%3A%3AResponse) is still returned.  The response object w...

Returns a [number object](https://metacpan.org/pod/Module%3A%3AGeneric%3A%3ANumber)

    my $p = HTTP::Promise->new( timeout => 10 );
    $p->timeout(10);
    my $timeout = $p->timeout;

## upgrade\_insecure\_requests

This is an alias for ["auto\_switch\_https"](#auto_switch_https)

## uri\_escape

URI-escape the given string using ["uri\_escape" in URI::Escape::XS](https://metacpan.org/pod/URI%3A%3AEscape%3A%3AXS#uri_escape)

## uri\_unescape

URI-unescape the given string using ["uri\_unescape" in URI::Escape::XS](https://metacpan.org/pod/URI%3A%3AEscape%3A%3AXS#uri_unescape)

## use\_content\_file

Boolean. Enables or disables the use of a temporary file to store the response content. Defaults to false.

When true, the response content will be stored into a temporary file, whose object is a [Module::Generic::File](https://metacpan.org/pod/Module%3A%3AGeneric%3A%3AFile) object and can be retrieved with ["file"](#file).

## use\_promise

Boolean. When true, this will have [HTTP::Promise](https://metacpan.org/pod/HTTP%3A%3APromise) HTTP methods return a [HTTP::Promise](https://metacpan.org/pod/promise), and when false, it returns directly the [HTTP::Promise::Response](https://metacpan...

# CLASS FUNCTIONS

## fetch

This method can be exported, such as:

    use HTTP::Promise qw( fetch );
    my $prom = fetch( 'http://example.com/something.json' );
    # or