SYNOPSIS

    use HTTP::Promise;
    my $p = HTTP::Promise->new(
        agent => 'MyBot/1.0'
        accept_language => [qw( fr-FR fr en-GB en ja-JP )],
        auto_switch_https => 1,
        # For example, and Cookie::Jar object
        cookie_jar => $cookie_jar,
        dnt => 1,
        # 2Mb. Any data to be sent being bigger than this will trigger a Continue conditional query
        expect_threshold => 2048000,
        # Have the file extension reflect the encoding, if any
        ext_vary => 1,
        # 100Kb. Anything bigger than this will be automatically saved on file rather than memory
        max_body_in_memory_size => 102400,
        # 8Kb
        max_headers_size => 8192,
        max_redirect => 3,
        proxy => 'https://proxy.example.org:8080',
        # Can also be cbor or storable
        serialiser => 'sereal',
        # You can also use decimals with Time::HiRes
        timeout => 15,
        # force the use of files to store the response content
        use_content_file => 1,
        # The serialiser to use for the promise in Promise::Me
        # Defaults to storable, but can also be cbor and sereal
        serialiser => 'sereal',
    );
    my $prom = $p->get( 'https://www.example.org', $hash_of_query_params )->then(sub
    {
        my $resp = shift( @_ ); # get the HTTP::Promise::Response object
    })->catch(sub
    {
        my $ex = shift( @_ ); # get a HTTP::Promise::Exception object
        say "Exception code is: ", $ex->code;
    });
    # or using hash reference of options to prepare the request
    my $req = HTTP::Promise::Request->new( get => 'https://www.example.org' ) ||
        die( HTTP::Promise::Request->error );
    my $prom = $p->request( $req )->then(sub{ #... })->catch(sub{ # ... });

VERSION

    v0.1.4

DESCRIPTION

HTTP::Promise{.perl-module} provides with a fast and powerful yet memory-friendly API to make true asynchronous HTTP requests using fork using Promise::Me{.perl-module}.

It is based on the design of HTTP::Message{.perl-module}, but with a much cleaner interface to make requests and manage HTTP entity bodies.

Here are the key features:

Here is how it is organised in overall:

    +-------------------------+    +--------------------------+    
    |                         |    |                          |    
    | HTTP::Promise::Request  |    | HTTP::Promise::Response  |    
    |                         |    |                          |    
    +------------|------------+    +-------------|------------+    
                 |                               |                 
                 |                               |                 
                 |                               |                 
                 |  +------------------------+   |                 
                 |  |                        |   |                 
                 +--- HTTP::Promise::Message |---+                 
                    |                        |                     
                    +------------|-----------+                     
                                 |                                 
                                 |                                 
                    +------------|-----------+                     
                    |                        |                     
                    | HTTP::Promise::Entity  |                     
                    |                        |                     
                    +------------|-----------+                     
                                 |                                 
                                 |                                 
                    +------------|-----------+                     
                    |                        |                     
                    | HTTP::Promise::Body    |                     
                    |                        |                     
                    +------------------------+                     

It differentiates from other modules by using several XS modules for speed, and has a notion of HTTP entity{.perl-module} and body{.perl-module} stored either on file or in memory.

It also have modules to make it really super easy to create x-www-form-urlencoded requests with HTTP::Promise::Body::Form{.perl-module}, or multipart ones with HTTP::Promise::Body::Form::Data{.perl-module}

Thus, you can either have a fine granularity by creating your own request using HTTP::Promise::Request{.perl-module}, or you can use the high level methods provided by HTTP::Promise{.perl-module}, which are: \"delete\"{.perl-module}, \"get\"{.perl-module}, \"head\"{.perl-module}, \"options\"{.perl-module}, \"patch\"{.perl-module}, \"post\"{.perl-module}, \"put\"{.perl-module} and each will occur asynchronously.

Each of those method returns a promise{.perl-module}, which means you can chain the results using a chainable then{.perl-module} and catch{.perl-module} for errors.

You can also wait for all of them to finish using await{.perl-module}, which is exported by default by HTTP::Promise{.perl-module} and all{.perl-module} or race{.perl-module}.

    my @results = await( $p1, $p2 );
    my @results = HTTP::Promise->all( $p1, $p2 );
    # First promise that is resolved or rejected makes this super promise resolved and
    # return the result
    my @results = HTTP::Promise->race( $p1, $p2 );

You can also share variables using share, such as:

    my $data : shared = {};
    # or
    my( $name, @first_names, %preferences );
    share( $name, @first_names, %preferences );

See Promise::Me{.perl-module} for more information.

It calls resolve{.perl-module} when the request has been completed and sends a HTTP::Promise::Response{.perl-module} object whose API is similar to that of HTTP::Response{.perl-module}.

When an error occurs, it is caught and sent by calling \"reject\" in Promise::XS{.perl-module} with an HTTP::Promise::Exception{.perl-module} object.

Cookies are automatically and transparently managed with Cookie::Jar{.perl-module} which can load and store cookies to a json file you specify. You can create a cookie object{.perl-module} and pass it to the constructor with the cookie_jar option.

CONSTRUCTOR

new

Provided with some optional parameters, and this instantiate a new HTTP::Promise{.perl-module} objects and returns it. If an error occurred, it will return undef and the error can be retrieved using error{.perl-module} method.

It accepts the following parameters. Each of those options have a corresponding method, so you can get or change its value later:

METHODS

The following methods are available. You can also access the same methods implemented in LWP::UserAgent{.perl-module} even if they are not listed here.

accept_language

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

See also HTTP::Promise::Header::AcceptLanguage{.perl-module}

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:

    $http->accept_language( [qw( fr-FR ja-JP en-GB en )] );

Would result into an Accept-Language header set to fr-FR;q=0.9,ja-JP;q=0.8,en-GB;q=0.7,en;q=0.6

The Accept-Language header would only be set if it is not set already.

auto_switch_https

Boolean. If set to a true value, or if left to undef (default value), this will set the Upgrade-Insecure-Requests header field to 1

buffer_size

The size of the buffer to use when reading data from the filehandle or socket.

connection_header

Sets or gets the value for the header Connection. It can be close or keep-alive

If it is let undef, this module will try to guess the proper value based on the \"protocol\" in HTTP::Promise::Request{.perl-module} and \"version\" in HTTP::Promise::Request{.perl-module} used.

For protocol HTTP/1.0, Connection value would be close, but above HTTP/1.1 the connection can be set to keep-alive and thus be re-used.

Sets or gets the Cookie jar class object to use. This is typically Cookie::Jar{.perl-module} or maybe HTTP::Cookies{.perl-module}

This defaults to Cookie::Jar{.perl-module}

    use Cookie::Jar;
    my $jar = Cookie::Jar->new;
    my $p = HTTP::Promise->new( cookie_jar => $jar );
    $p->cookie_jar( $jar );

{=pod::coverage} decodable

decodable

This calls \"decodable\" in HTTP::Promise::Stream{.perl-module} passing it whatever arguments that were provided.

default_header

Sets one more default headers. This is a shortcut to $p->default_headers->header

    $p->default_header( $field );
    $p->default_header( $field => $value );
    $p->default_header( 'Accept-Encoding' => scalar( HTTP::Promise->decodable ) );
    $p->default_header( 'Accept-Language' => 'fr, en, ja' );

default_headers

Sets or gets the default header object{.perl-module}, which is set to undef by default.

This can be either an HTTP::Promise::Headers{.perl-module} or HTTP::Headers{.perl-module} object.

    use HTTP::Promise::Headers;
    my $headers = HTTP::Promise::Headers->new(
        'Accept-Encoding' => scalar( HTTP::Promise->decodable ),
        'Accept-Language' => 'fr, en, ja',
    );
    my $p = HTTP::Promise->new( default_headers => $headers );

default_protocol

Sets or gets the default protocol to use. For example: HTTP/1.1

delete

Provided with an uri and an optional hash of header name/value pairs, and this will issue a DELETE http request to the given uri.

It returns a promise{.perl-module}, which can be used to call one or more then{.perl-module} and catch{.perl-module}

    # or $p->delete( $uri, $field1 => $value1, $field2 => $value2 )
    $p->delete( $uri )->then(sub
    {
        my( $resolve, $reject ) = @$_;
        # an HTTP::Promise::Response is returned
        my $resp = shift( @_ );
        # Do something with the $resp object
    })->catch(sub
    {
        my $ex = shift( @_ );
        # An HTTP::Promise::Exception object is passed with an error code
        say( "Error code; ", $ex->code, " and message: ", $ex->message );
    });

dnt

Boolean. If set to a true value, this will set the DNT header to 1

expect_threshold

Sets or gets the body size threshold beyond which, this module will issue a conditional Expect HTTP header in order to ensure the remote HTTP server is ok.

ext_vary

Boolean. When this is set to a true value, this will have the files use extensions that reflect not just their content, but also their encoding when applicable.

For example, if an HTTP response HTML content is gzip encoded into a file, the file extensions will be html.gz

Default set to $EXTENSION_VARY, which by default is true.

file

If a temporary file has been set, the response content file can be retrieved with this method.

    my $p = HTTP::Promise->new( threshold => 512000 ); # 500kb
    # If the response payload exceeds 500kb, HTTP::Promise will save the content to a 
    # temporary file
    # or
    my $p = HTTP::Promise->new( use_content_file => 1 ); # always use a temporary file
    # Returns a Module::Generic::File object
    my $f = $p->file;

from

\"the email address for the human user who controls the requesting user agent. The address should be machine-usable, as defined in RFC2822{.perl-module}. The from value is sent as the From header in the requests\" (Excerpt taken from LWP::UserAgent documentation)

The default value is undef, so no From field is set by default.

    my $p = HTTP::Promise->new( from => 'john.doe@example.com' );
    $p->from( 'john.doe@example.com' );

get

Provided with an uri and an optional hash of header name/value pairs, and this will issue a GET http request to the given uri.

It returns a promise{.perl-module}, which can be used to call one or more then{.perl-module} and catch{.perl-module}

    # or $p->get( $uri, $field1 => $value1, $field2 => $value2 )
    $p->get( $uri )->then(sub
    {
        my( $resolve, $reject ) = @$_;
        # an HTTP::Promise::Response is returned
        my $resp = shift( @_ );
        # Do something with the $resp object
    })->catch(sub
    {
        my $ex = shift( @_ );
        # An HTTP::Promise::Exception object is passed with an error code
        say( "Error code; ", $ex->code, " and message: ", $ex->message );
    });

Provided with an uri and an optional hash of header name/value pairs, and this will issue a HEAD http request to the given uri.

It returns a promise{.perl-module}, which can be used to call one or more then{.perl-module} and catch{.perl-module}

    # or $p->head( $uri, $field1 => $value1, $field2 => $value2 )
    $p->head( $uri )->then(sub
    {
        my( $resolve, $reject ) = @$_;
        # an HTTP::Promise::Response is returned
        my $resp = shift( @_ );
        # Do something with the $resp object
    })->catch(sub
    {
        my $ex = shift( @_ );
        # An HTTP::Promise::Exception object is passed with an error code
        say( "Error code; ", $ex->code, " and message: ", $ex->message );
    });

inactivity_timeout

Sets or gets the inactivity timeout in seconds. If timeout is reached, the connection is closed.

is_protocol_supported

Provided with a protocol, such as http, or https, and this returns true if the protocol is supported or false otherwise.

This basically returns true if the protocol is either http or https and false otherwise, because HTTP::Promise supports only HTTP protocol.

languages

This is an alias for \"accept_language\"{.perl-module}

local_address

\"Get/set the local interface to bind to for network connections. The interface can be specified as a hostname or an IP address. This value is passed as the LocalAddr argument to IO::Socket::INET{.perl-module}.\" (Excerpt taken from LWP::UserAgent documentation)

The default value is undef.

    my $p = HTTP::Promise->new( local_address => 'localhost' );
    $p->local_address( '127.0.0.1' );

max_body_in_memory_size

Sets or gets the maximum HTTP response body size beyond which the data will automatically be saved in a temporary file.

max_headers_size

Sets or gets the maximum HTTP response headers size, beyond which an error is triggered.

max_redirect

An integer. Sets or gets the maximum number of allowed redirection possible. Default is 7.

    my $p = HTTP::Promise->new( max_redirect => 5 );
    $p->max_redirect(12);
    my $max = $p->max_redirect;

max_size

\"Get/set the size limit for response content. The default is undef, which means that there is no limit. If the returned response content is only partial, because the size limit was exceeded, then a Client-Aborted header will be added to the response. The content might end up longer than max_size as we abort once appending a chunk of data makes the length exceed the limit. The Content-Length header, if present, will indicate the length of the full content and will normally not be the same as length( $resp->content )\" (Excerpt taken from LWP::UserAgent documentation)

    my $p = HTTP::Promise->max_size(512000); # 512kb
    $p->max_size(512000);
    my $max = $p->max_size;

mirror

Provided with an uri and a filepath and this will issue a conditional request to the remote server to return the remote content if it has been modified since the last modification time of the filepath. Of course, if that file does not exists, then it is downloaded. If the remote resource has been changed since last time, it is downloaded again and its content stored into the filepath

Just like other http methods, this returns a promise{.perl-module} object.

It can then be used to call one or more then{.perl-module} and catch{.perl-module}

    $p->mirror( $uri => '/some/where/file.txt' )->then(sub
    {
        my( $resolve, $reject ) = @$_;
        # an HTTP::Promise::Response is returned
        my $resp = shift( @_ );
        # Do something with the $resp object
    })->catch(sub
    {
        my $ex = shift( @_ );
        # An HTTP::Promise::Exception object is passed with an error code
        say( "Error code; ", $ex->code, " and message: ", $ex->message );
    });

no_proxy

Sets or gets a list of domain names for which the proxy will not apply. By default this is empty.

This returns an array object{.perl-module}

    my $p = HTTP::Promise->new( no_proxy => [qw( example.com www2.example.net )] );
    $p->no_proxy( [qw( localhost example.net )] );
    my $ar = $p->no_proxy;
    say $ar->length, " proxy exception(s) set.";

options

Provided with an uri, and this will issue an OPTIONS http request to the given uri.

It returns a promise{.perl-module}, which can be used to call one or more then{.perl-module} and catch{.perl-module}

    # or $p->head( $uri, $field1 => $value1, $field2 => $value2 )
    $p->options( $uri )->then(sub
    {
        my( $resolve, $reject ) = @$_;
        # an HTTP::Promise::Response is returned
        my $resp = shift( @_ );
        # Do something with the $resp object
    })->catch(sub
    {
        my $ex = shift( @_ );
        # An HTTP::Promise::Exception object is passed with an error code
        say( "Error code; ", $ex->code, " and message: ", $ex->message );
    });

patch

Provided with an uri and an optional hash of form data, followed by an hash of header name/value pairs and this will issue a PATCH http request to the given uri.

If a special header name Content is provided, its value will be used to create the key-value pairs form data.

It returns a promise{.perl-module}, which can be used to call one or more then{.perl-module} and catch{.perl-module}

    # or $p->patch( $uri, \@form, $field1 => $value1, $field2 => $value2 )
    # or $p->patch( $uri, \%form, $field1 => $value1, $field2 => $value2 )
    # or $p->patch( $uri, $field1 => $value1, $field2 => $value2 )
    # or $p->patch( $uri, $field1 => $value1, $field2 => $value2, Content => \@form )
    # or $p->patch( $uri, $field1 => $value1, $field2 => $value2, Content => \%form )
    $p->patch( $uri )->then(sub
    {
        my( $resolve, $reject ) = @$_;
        # an HTTP::Promise::Response is returned
        my $resp = shift( @_ );
        # Do something with the $resp object
    })->catch(sub
    {
        my $ex = shift( @_ );
        # An HTTP::Promise::Exception object is passed with an error code
        say( "Error code; ", $ex->code, " and message: ", $ex->message );
    });

post

Provided with an uri and an optional hash of form data, followed by an hash of header name/value pairs and this will issue a POST http request to the given uri.

If a special header name Content is provided, its value will be used to create the key-value pairs form data. THat Content value can either be an array reference, or an hash reference of key-value pairs. If if is just a string, it will be used as-is as the request body.

How the form data is formatted depends on the Content-Type set in the headers passed. If the Content-Type header is form-data or multipart/form-data, the form data will be formatted as a multipart/form-data post, otherwise they will be formatted as a application/x-www-form-urlencoded post.

It returns a promise{.perl-module}, which can be used to call one or more then{.perl-module} and catch{.perl-module}

    # or $p->post( $uri, \@form, $field1 => $value1, $field2 => $value2 )
    # or $p->post( $uri, \%form, $field1 => $value1, $field2 => $value2 )
    # or $p->post( $uri, $field1 => $value1, $field2 => $value2 )
    # or $p->post( $uri, $field1 => $value1, $field2 => $value2, Content => \@form )
    # or $p->post( $uri, $field1 => $value1, $field2 => $value2, Content => \%form )
    # or $p->post( $uri, $field1 => $value1, $field2 => $value2, Content => $content )
    $p->post( $uri )->then(sub
    {
        my( $resolve, $reject ) = @$_;
        # an HTTP::Promise::Response is returned
        my $resp = shift( @_ );
        # Do something with the $resp object
    })->catch(sub
    {
        my $ex = shift( @_ );
        # An HTTP::Promise::Exception object is passed with an error code
        say( "Error code; ", $ex->code, " and message: ", $ex->message );
    });

prepare_headers

Provided with an HTTP::Promise::Request{.perl-module} object, and this will set the following request headers, if they are not set already.

You can override this method if you create a module of your own that inherits from HTTP::Promise{.perl-module}.

It returns the HTTP::Promise::Request{.perl-module} received, or upon error, it sets an error{.perl-module} and returns undef

Headers set, if not set already are:

proxy

Array reference. This sets the scheme and their proxy or proxies. Default to undef. For example:

    my $p = HTTP::Promise->new( proxy => [ [qw( http ftp )] => 'https://proxy.example.com:8001' ] );
    my $p = HTTP::Promise->new( proxy => [ http => 'https://proxy.example.com:8001' ] );
    my $p = HTTP::Promise->new( proxy => [ ftp => 'http://ftp.example.com:8001/', 
                                           [qw( http https )] => 'https://proxy.example.com:8001' ] );
    my $proxy = $p->proxy( 'https' );

proxy_authorization

Sets or gets the proxy authorization string. This is computed automatically when you set a user and a password to the proxy URI by setting the value to \"proxy\"{.perl-module}

put

Provided with an uri and an optional hash of form data, followed by an hash of header name/value pairs and this will issue a PUT http request to the given uri.

If a special header name Content is provided, its value will be used to create the key-value pairs form data. THat Content value can either be an array reference, or an hash reference of key-value pairs. If if is just a string, it will be used as-is as the request body.

How the form data is formatted depends on the Content-Type set in the headers passed. If the Content-Type header is form-data or multipart/form-data, the form data will be formatted as a multipart/form-data post, otherwise they will be formatted as a application/x-www-form-urlencoded put.

It returns a promise{.perl-module}, which can be used to call one or more then{.perl-module} and catch{.perl-module}

    # or $p->put( $uri, \@form, $field1 => $value1, $field2 => $value2 )
    # or $p->put( $uri, \%form, $field1 => $value1, $field2 => $value2 )
    # or $p->put( $uri, $field1 => $value1, $field2 => $value2 )
    # or $p->put( $uri, $field1 => $value1, $field2 => $value2, Content => \@form )
    # or $p->put( $uri, $field1 => $value1, $field2 => $value2, Content => \%form )
    # or $p->put( $uri, $field1 => $value1, $field2 => $value2, Content => $content )
    $p->put( $uri )->then(sub
    {
        my( $resolve, $reject ) = @$_;
        # an HTTP::Promise::Response is returned
        my $resp = shift( @_ );
        # Do something with the $resp object
    })->catch(sub
    {
        my $ex = shift( @_ );
        # An HTTP::Promise::Exception object is passed with an error code
        say( "Error code; ", $ex->code, " and message: ", $ex->message );
    });

request

This method will issue the propre request in accordance with the request object provided. It will process redirects and authentication responses transparently. This means it may end up sending multiple request, up to the limit set with the object option \"max_redirect\"{.perl-module}

This method takes the following parameters:

1. a request object{.perl-module}, which is typically HTTP::Promise::Request{.perl-module}, or HTTP::Request{.perl-module}, but any class that implements a similar interface is acceptable
2. an optional hash or hash reference of parameters:
`read_size`

:   Integer. If provided, this will instruct to read the response by
    that much bytes at a time.

`use_content_file`

:   Boolean. If true, this will instruct the use of a temporary file
    to store the response content. That file may then be retrieved
    with the method [\"file\"](#file){.perl-module}.

    You can also control the use of a temporary file to store the
    response content with the
    [\"threshold\"](#threshold){.perl-module} object option.

It returns a promise object{.perl-module} 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->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;
    });

requests_redirectable

Array reference. Sets or gets the list of http method that are allowed to be redirected. By default this is an empty list, i.e. all http methods are allowed to be redirected. Defaults to GET and HEAD as per rfc 2616{.perl-module}

This returns an array object{.perl-module}

    my $p = HTTP::Promise->new( requests_redirectable => [qw( HEAD GET POST )] );
    $p->requests_redirectable( [qw( HEAD GET POST )] );
    my $ok_redir = $p->requests_redirectable;
    # Add put
    $ok_redir->push( 'PUT' );
    # Remove POST we just added
    $ok_redir->remove( 'POST' );

send

Provided with an HTTP::Promise::Request{.perl-module}, and an optional hash or hash reference of options and this will attempt to connect to the specified uri{.perl-module}

Supported options:

send_te

Boolean. Enables or disables the TE http header. Defaults to true. If true, the TE will be added to the outgoing http request.

    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{.perl-module}. Possible values are: cbor{.perl-module}, sereal{.perl-module} or storable{.perl-module}

By default, the value is set to the global variable $SERIALISER, which is a copy of the $SERIALISER in Promise::Me{.perl-module}, which should be by default storable

simple_request

This method takes the same parameters as \"request\"{.perl-module} and differs in that it will not try to handle redirects or authentication.

It returns a promise object{.perl-module} 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;
    });

ssl_opts

Hash reference object{.perl-module}. 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{.perl-module} or Net::SSL{.perl-module} 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\"{.perl-module}. Default to global variable $CONTENT_SIZE_THRESHOLD, which is undef by default.

See also the \"max_size\"{.perl-module} 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{.perl-module} is still returned. The response object will have a standard http status code of 500, i.e. server error. This response will have the Client-Warning header set to the value of Internal response.

Returns a number object{.perl-module}

    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\"{.perl-module}

uri_escape

URI-escape the given string using \"uri_escape\" in URI::Escape::XS{.perl-module}

uri_unescape

URI-unescape the given string using \"uri_unescape\" in URI::Escape::XS{.perl-module}

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{.perl-module} object and can be retrieved with \"file\"{.perl-module}.

AUTHOR

Jacques Deguest \<jack@deguest.jp{classes="ARRAY(0x55748b07a818)"}>

CREDITS

This module is inspired by the design and workflow of Gisle Aas and his implementation of HTTP::Message{.perl-module}, but built completely differently.

HTTP::Promise::Entity{.perl-module} and HTTP::Promise::Body{.perl-module} have been inspired by Erik Dorfman (a.k.a. Eryq) and Dianne Skoll\'s implementation of MIME::Entity{.perl-module}

BUGS

You can report bugs at \https://gitlab.com/jackdeguest/HTTP-Promise/issues\

SEE ALSO

HTTP::Promise{.perl-module}, HTTP::Promise::Request{.perl-module}, HTTP::Promise::Response{.perl-module}, HTTP::Promise::Message{.perl-module}, HTTP::Promise::Entity{.perl-module}, HTTP::Promise::Headers{.perl-module}, HTTP::Promise::Body{.perl-module}, HTTP::Promise::Body::Form{.perl-module}, HTTP::Promise::Body::Form::Data{.perl-module}, HTTP::Promise::Body::Form::Field{.perl-module}, HTTP::Promise::Status{.perl-module}, HTTP::Promise::MIME{.perl-module}, HTTP::Promise::Parser{.perl-module}, HTTP::Promise::IO{.perl-module}, HTTP::Promise::Stream{.perl-module}, HTTP::Promise::Exception{.perl-module}

Promise::Me{.perl-module}, Cookie::Jar{.perl-module}, Module::Generic::File{.perl-module}, Module::Generic::Scalar{.perl-module}, Module::Generic{.perl-module}

HTTP::XSHeaders{.perl-module}, File::MMagic::XS{.perl-module}, CryptX{.perl-module}, HTTP::Parser2::XS{.perl-module}, URI::Encode::XS{.perl-module}, URI::Escape::XS{.perl-module}, URL::Encode::XS{.perl-module}

IO::Compress::Bzip2{.perl-module}, IO::Compress::Deflate{.perl-module}, IO::Compress::Gzip{.perl-module}, IO::Compress::Lzf{.perl-module}, IO::Compress::Lzip{.perl-module}, IO::Compress::Lzma{.perl-module}, IO::Compress::Lzop{.perl-module}, IO::Compress::RawDeflate{.perl-module}, IO::Compress::Xz{.perl-module}, IO::Compress::Zip{.perl-module}, IO::Compress::Zstd{.perl-module}

rfc6266 on Content-Disposition{.perl-module}, rfc7230 on Message Syntax and Routing{.perl-module}, rfc7231 on Semantics and Content{.perl-module}, rfc7232 on Conditional Requests{.perl-module}, rfc7233 on Range Requests{.perl-module}, rfc7234 on Caching{.perl-module}, rfc7235 on Authentication{.perl-module}, rfc7578 on multipart/form-data{.perl-module}, rfc7540 on HTTP/2.0{.perl-module}

COPYRIGHT & LICENSE

Copyright (c) 2021 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.