view release on metacpan or  search on metacpan

lib/HTTP/Promise.pm  view on Meta::CPAN

It defaults to C<$Promise::Me::SHARE_MEDIUM>

=item * C<no_proxy>

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

=item * C<proxy>

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

=item * C<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.

=item * C<serialiser>

String. Specify the serialiser to use for L<Promise::Me>. Possible values are: L<cbor|CBOR::XS>, L<sereal|Sereal> or L<storable|Storable::Improved>

By default it uses the value set in the global variable C<$SERIALISER>, which is a copy of the C<$SERIALISER> in L<Promise::Me>, which should be by default C<storable>

=item * C<shared_mem_size>

Integer. This will be passed on to L<Promise::Me>. See L<Promise::Me> for more details.

It defaults to C<$Promise::Me::RESULT_MEMORY_SIZE>

=item * C<ssl_opts>

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

=over 8

=item 1. C<verify_hostname>

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

=over 12

=item 1.1. If environment variable C<PERL_LWP_SSL_VERIFY_HOSTNAME> is set, the ssl option property C<verify_hostname> takes its value.

=item 1.2. If environment variable C<HTTPS_CA_FILE> or C<HTTPS_CA_DIR> are set to a true value, then the ssl option property C<verify_hostname> is set to C<0> and option property C<SSL_verify_mode> is set to C<1>

=item 1.3 If none of the above applies, it defaults C<verify_hostname> to C<1>

=back

=item 2. C<SSL_ca_file>

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

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

=item 3. C<SSL_ca_path>

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

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

=back

Other options can be set and are processed directly by the SSL Socket implementation in use. See L<IO::Socket::SSL> or L<Net::SSL> for details.

Example of C<ssl_opts>:

    my $ssl_opts = 
    {
        SSL_ca_file          => "/usr/local/lib/perl5/site_perl/5.36.1/Mozilla/CA/cacert.pem",
        SSL_verify_mode      => IO::Socket::SSL::SSL_VERIFY_PEER(),  # Explicit constant for clarity
        SSL_verifycn_scheme  => "www",
        SSL_hostname         => $host,  # Explicit SNI; prevents issues if PeerHost changes
        SSL_version          => "TLSv1_2:TLSv1_3",  # Enforce modern TLS (adjust for legacy if needed)
        # SSL_fingerprint    => "sha256$your_cert_fingerprint",  # If pinning a specific cert
        # SSL_ocsp_mode      => IO::Socket::SSL::SSL_OCSP_TRY_STAPLE(),  # For revocation checks
    };

=item * C<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 L</file>. Default to global variable C<$CONTENT_SIZE_THRESHOLD>, which is C<undef> by default.

See also the C<max_size> option.

=item * C<timeout>

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

=item * C<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.

=item * C<use_promise>

Boolean. When true, this will have L<HTTP::Promise> HTTP methods return a L<HTTP::Promise|promise>, and when false, it returns directly the L<HTTP::Promise::Response|response object>. Defaults to true.

=back

=head1 METHODS

The following methods are available. This interface provides similar interface as L<LWP::UserAgent> while providing more granular control.

=head2 accept_encoding

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

You can set it to C<none> to disable it. By default, this is C<auto>, and it will set the C<Accept-Encoding> C<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: C<bzip2,deflate,gzip,rawdeflate,brotli>

See L<HTTP::Promise::Stream> for more details.

Returns a L<scalar object|Module::Generic::Scalar> of the current value.

=head2 accept_language

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

See also L<HTTP::Promise::Headers::AcceptLanguage>

=head2 agent

This is a string.

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

It defaults to C<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 C<User-Agent> header field is only set to this provided value if it is not already set.

=head2 accept_language

Sets or gets an array of acceptable response content languages.

lib/HTTP/Promise.pm  view on Meta::CPAN

=head2 simple_request

This method takes the same parameters as L</request> and differs in that it will not try to handle redirects or authentication.

It returns a L<promise object|Promise::Me> 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 L</use_promise> is set to false, this will return an L<HTTP::Promise::Response> object directly.

=head2 ssl_opts

L<Hash reference object|Module::Generic::Hash>. Sets or gets the ssl options properties used when making requests over ssl. The default values are set as follows:

=over 8

=item 1. C<verify_hostname>

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

=over 12

=item 1.1. If environment variable C<PERL_LWP_SSL_VERIFY_HOSTNAME> is set, the ssl option property C<verify_hostname> takes its value.

=item 1.2. If environment variable C<HTTPS_CA_FILE> or C<HTTPS_CA_DIR> are set to a true value, then the ssl option property C<verify_hostname> is set to C<0> and option property C<SSL_verify_mode> is set to C<1>

=item 1.3 If none of the above applies, it defaults C<verify_hostname> to C<1>

=back

=item 2. C<SSL_ca_file>

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

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

=item 3. C<SSL_ca_path>

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

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

=back

Other options can be set and are processed directly by the SSL Socket implementation in use. See L<IO::Socket::SSL> or L<Net::SSL> for details.

=head2 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 C<EINTR> error occurs.

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

=head2 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 L</file>. Default to global variable C<$CONTENT_SIZE_THRESHOLD>, which is C<undef> by default.

See also the L</max_size> option.

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

=head2 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 C<timeout> seconds. When a request times out, a L<response object|HTTP::Promise::Response> is still returned.  The response object will have a standard http status ...

Returns a L<number object|Module::Generic::Number>

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

=head2 upgrade_insecure_requests

This is an alias for L</auto_switch_https>

=head2 uri_escape

URI-escape the given string using L<URI::Escape::XS/uri_escape>

=head2 uri_unescape

URI-unescape the given string using L<URI::Escape::XS/uri_unescape>

=head2 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 L<Module::Generic::File> object and can be retrieved with L</file>.

=head2 use_promise

Boolean. When true, this will have L<HTTP::Promise> HTTP methods return a L<HTTP::Promise|promise>, and when false, it returns directly the L<HTTP::Promise::Response|response object>. Defaults to true.

=head1 CLASS FUNCTIONS

=head2 fetch

This method can be exported, such as:

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