The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
HTTP-Promise-v0.1.4
River stage one • 1 direct dependent • 2 total dependents
1 ++
/ HTTP::Promise::Request

NAME

HTTP::Promise::Request - Asynchronous HTTP Request and Promise

SYNOPSIS

    use HTTP::Promise::Request;
    my $this = HTTP::Promise::Request->new || die( HTTP::Promise::Request->error, "\n" );

VERSION

    v0.1.0_2

DESCRIPTION

HTTP::Promise::Request implements a similar interface to HTTP::Request, but does not inherit from it. It uses a different API internally and relies on XS modules for speed while offering more features.

HTTP::Promise::Request inherits from HTTP::Promise::Message

One major difference with HTTP::Request is that the HTTP request content is not necessarily stored in memory, but it relies on HTTP::Promise::Body as you can see below, and this class has 2 subclasses: 1 storing data in memory when the size is reasonable (threshold set by you) and 1 storing data in a file on the filesystem for larger content.

Here is how it fits in overall relation with other classes.

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

CONSTRUCTOR

new

    my $r = HTTP::Promise::Request->new( $method, $uri, $headers, $content, k1 => v1, k2 => v2);
    my $r = HTTP::Promise::Request->new( $method, $uri, $headers, $content, { k1 => v1, k2 => v2 });
    my $r = HTTP::Promise::Request->new( $method, $uri, $headers, k1 => v1, k2 => v2);
    my $r = HTTP::Promise::Request->new( $method, $uri, $headers, { k1 => v1, k2 => v2 });
    my $r = HTTP::Promise::Request->new( $method, $uri, k1 => v1, k2 => v2);
    my $r = HTTP::Promise::Request->new( $method, k1 => v1, k2 => v2);
    my $r = HTTP::Promise::Request->new( k1 => v1, k2 => v2 );
    die( HTTP::Promise::Request->error ) if( !defined( $r ) );

Provided with an HTTP method, URI, an optional set of headers, as either an array reference or a HTTP::Promise::Headers or a HTTP::Headers object, some optional content and an optional hash reference of options (as the last or only parameter), and this instantiates a new HTTP::Promise::Request object. The supported arguments are as follow. Each arguments can be set or changed later using the method with the same name.

It returns the newly created object upon success, and upon error, such as bad argument provided, this sets an error and returns undef

It takes the following arguments:

1. $method

This is a proper HTTP method in upper case. Note that you can also provide non-standard method in any case you want.

2. $uri

The request uri such as / or an absolute uri, typical for making request to proxy, such as https://example.org/some/where

3. $headers

An HTTP::Promise::Headers object or an array reference of header field-value pairs, such as:

    my $r = HTTP::Promise::Request->new( $method, $uri, [
        'Content-Type' => 'text/html; charset=utf-8',
        Content_Encoding => 'gzip',
    ]);
4. $content

$content can either be a string, a scalar reference, or an HTTP::Promise::Body object (HTTP::Promise::Body::File and HTTP::Promise::Body::Scalar)

Each supported option below can also be set using its corresponding method.

Supported options are:

  • content

    Same as $content above.

  • headers

    Same as $headers above.

  • method

    Same as $method above.

  • protocol

    The HTTP protocol, such as HTTP/1.1 or HTTP/2

  • uri

    The request uri, such as /chat or it could also be a fully qualified uri such as wss://example.com/chat

  • version

    The HTTP protocol version. Defaults to 1.17

METHODS

accept_decodable

This sets and returns the header Accept-Encoding after having set it the value of "decodable"

add_content

This is inherited from HTTP::Promise::Message. See "add_content" in HTTP::Promise::Message

add_content_utf8

This is inherited from HTTP::Promise::Message. See "add_content_utf8" in HTTP::Promise::Message

add_part

This is inherited from HTTP::Promise::Message. See "add_part" in HTTP::Promise::Message

as_string

Depending on whether uri_absolute is true, this returns a HTTP request with an URI including the HTTP host (a.k.a absolute-form) or only the absolute path (a.k.a origin-form). The former is used when issuing requests to proxies.

origin-form:

    GET /where?q=now HTTP/1.1
    Host: www.example.org

absolute-form:

    GET http://www.example.org/pub/WWW/TheProject.html HTTP/1.1

See rfc7230, section 5.3

boundary

This is inherited from HTTP::Promise::Message and returns the multipart boundary currently set in the Content-Type header.

can

This is inherited from HTTP::Promise::Message. See "can" in HTTP::Promise::Message

clear

This is inherited from HTTP::Promise::Message. See "clear" in HTTP::Promise::Message

clone

This clones the current object and returns the clone version.

content

This is inherited from HTTP::Promise::Message. See "content" in HTTP::Promise::Message

Use this method with care, because it will stringify the request body, thus loading it into memory, which could potentially be important if the body size is large. Maybe you can check the body size first? Something like:

    my $content;
    $content = $r->content if( $r->body->length < 102400 );

content_charset

This is inherited from HTTP::Promise::Message. See "content_charset" in HTTP::Promise::Message

content_ref

This is inherited from HTTP::Promise::Message. See "content_ref" in HTTP::Promise::Message

Sets or gets the Cookie::Jar object. This is used to read and store cookies.

decodable

This is inherited from HTTP::Promise::Message. See "decodable" in HTTP::Promise::Message

decode

This is inherited from HTTP::Promise::Message. See "decode" in HTTP::Promise::Message

decode_content

This is inherited from HTTP::Promise::Message. See "decode_content" in HTTP::Promise::Message

decoded_content

This is inherited from HTTP::Promise::Message. See "decoded_content" in HTTP::Promise::Message

decoded_content_utf8

This is inherited from HTTP::Promise::Message. See "decoded_content_utf8" in HTTP::Promise::Message

default_protocol

Sets or gets the default HTTP protocol to use. This defaults to HTTP/1.1

dump

This dumps the HTTP request and prints it on the STDOUT in void context, or returns a string of it.

encode

This is inherited from HTTP::Promise::Message. See "encode" in HTTP::Promise::Message

entity

Sets or gets an HTTP::Promise::Entity object.

This object is automatically created upon instantiation of the HTTP request, and if you also provide some content when creating a new object, an HTTP::Promise::Body object will also be created.

This is inherited from HTTP::Promise::Message. See "header" in HTTP::Promise::Message

headers

Sets or gets a HTTP::Promise::Headers object.

A header object is always created upon instantiation, whether you provided headers fields or not.

headers_as_string

This is inherited from HTTP::Promise::Message. See "headers_as_string" in HTTP::Promise::Message

is_encoding_supported

This is inherited from HTTP::Promise::Message. See "is_encoding_supported" in HTTP::Promise::Message

make_boundary

This is inherited from HTTP::Promise::Message. See "make_boundary" in HTTP::Promise::Message

make_form_data

This takes either an HTTP::Promise::Body::Form object, an HTTP::Promise::Body::Form::Data object, an array reference or an hash reference of form name-value pairs and builds a multipart/form-data

If a boundary is already set in the Content-Type header field, it will be used, otherwise a new one will be generated.

Each name provided will be the form-data name for each part.

It returns the current entity object, or upon error, sets an error and returns undef.

Each value provided can be either one of the following:

1. string
2. a Module::Generic::File object

In this case, the file-mime type will try to be guessed. If you prefer to be specific about the file mime-type, use the alternate hash reference below.

3. an hash reference

For more granular control, you can provide an hash reference with the following supported properties:

  • encoding

    The encoding to be applied to the content. This will also set the Content-Encoding for this form-data part.

    Note that when provided, the encodings will be applied immediately on the form-data content, whether it is a string or a file.

  • file

    A filepath to content for this part. The file content will not be loaded into memory, but instead will be used as-is. When it will need to be sent, it will be read from in chunks.

    If this provided, the body object will be a HTTP::Promise::Body::File

  • filename

    The filename attribute of the Content-Disposition or this form-data part.

    If this is not provided and headers property is not provided, or headers is specified, but the Content-Disposition filename attribute is not set, then the file basename will be used instead.

  • headers

    An HTTP::Promise::Headers object or an array reference of header field-value pairs.

  • type

    The mime-type to be used for this form-data part.

    If a file is provided and this is not specified, it will try to guess the mime-type using HTTP::Promise::MIME

    Note that even if this provided, and if a headers has been specified, it will not override an existing Content-Type header that would have been set.

  • value

    The form-data value. This is an alternative to providing the form-data content as a file

    Obviously you should not use both and if you do, file will take priority.

    If this provided, the body object will be a HTTP::Promise::Body::Scalar

multipart/form-data is the only valid Content-Type for sending multiple data. rfc7578 in section 4.3 states: "[RFC2388] suggested that multiple files for a single form field be transmitted using a nested "multipart/mixed" part. This usage is deprecated."

See also this Stackoverflow discussion and this one too

See also HTTP::Promise::Body::Form::Data for an alternate easy way to create and manipulate form-data, and see also "as_form_data" in HTTP::Promise::Entity, which will create and return a HTTP::Promise::Body::Form::Data object.

method

Sets or gets the HTTP method, such as CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE which are the standard ones as defined by rfc7231, section 4.1

Note that casing must be uppercase for standard methods, but non-standard ones can be whatever you want as long as it complies with the rfc7231.

This returns the current method set, if any, as an scalar object

parse

Provided with a scalar reference of data, a glob or a file path, and an hash or hash reference of options and this will parse the data provided using "parse" in HTTP::Promise::Parser, passing it whatever options has been provided. See "parse_fh" in HTTP::Promise::Parser for the supported options.

This returns the resulting HTTP::Promise::Message object from the parsing, or, upon error, sets an error and returns undef.

Note that the resulting HTTP::Promise::Message object can be a HTTP::Promise::Request or HTTP::Promise::Response object (both of which inherits from HTTP::Promise::Message) if a start-line was found, or else just an HTTP::Promise::Message object.

parts

This is inherited from HTTP::Promise::Message. See "parts" in HTTP::Promise::Message

protocol

This is inherited from HTTP::Promise::Message. See "protocol" in HTTP::Promise::Message

start_line

Read-only.

Returns a regular string representing the start-line containing the method, the uri and the protocol of the request.

For example:

    GET / HTTP/1.1

See rfc7230, section 3.1

timeout

Sets or gets the timeout as an integer. This returns the value as an number object

uri

Sets or gets the uri. Returns the current value, if any, as an URI object.

uri_absolute

Boolean. Sets or gets whether "as_string" will return a request including an uri in absolute-form (with the host included) or in origin-form (only with the absolute path).

If true, it sets the former otherwise the latter. Default to false.

uri_canonical

Returns the current "uri" in its canonical form by calling "canonical" in URI

version

This is inherited from HTTP::Promise::Message. See "version" in HTTP::Promise::Message

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

rfc7230, and rfc7231

HTTP::Promise, HTTP::Promise::Request, HTTP::Promise::Response, HTTP::Promise::Message, HTTP::Promise::Entity, HTTP::Promise::Headers, HTTP::Promise::Body, HTTP::Promise::Body::Form, HTTP::Promise::Body::Form::Data, HTTP::Promise::Body::Form::Field, HTTP::Promise::Status, HTTP::Promise::MIME, HTTP::Promise::Parser, HTTP::Promise::IO, HTTP::Promise::Stream, HTTP::Promise::Exception

COPYRIGHT & LICENSE

Copyright(c) 2022 DEGUEST Pte. Ltd.

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.