NAME
HTTP::Promise::Request - HTTP Request Class
SYNOPSIS
use HTTP::Promise::Request;
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 ) );VERSION
v0.2.0DESCRIPTION
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 ) );
my $decodable = $r->accept_decodable;
my $r2 = $r->clone;
$r->cookie_jar( Cookie::Jar->new );
my $jar = $r->cookie_jar;
my $proto = $r->default_protocol; # HTTP/1.1
say $r->dump;
my $headers = $r->headers; # Returns an HTTP::Promise::Headers object
$r->make_form_data;
$r->method( 'GET' );
my $method = $r->method;
my $r3 = $r->parse( $data );
say $r->start_line;
say $r->start_line( "\015\012" );
$r->timeout(5);
$r->uri( 'https://example.org/some/where' );
my $uri = $r->uri; # Returns an URI object
my $bool = $r->uri_absolute;
my $canonical_uri = $r->uri_canonical;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 ashttps://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 -
$contentcan 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:
contentSame as
$contentabove.headersSame as
$headersabove.methodSame as
$methodabove.protocolThe HTTP protocol, such as
HTTP/1.1orHTTP/2uriThe request uri, such as
/chator it could also be a fully qualified uri such aswss://example.com/chatversionThe 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.orgabsolute-form:
GET http://www.example.org/pub/WWW/TheProject.html HTTP/1.1boundary
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
cookie_jar
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.
header
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
host
my $req = HTTP::Promise::Request->new( GET => 'https://example.com' );
say $req->host; # example.com
my $req = HTTP::Promise::Request->new( GET => 'https://example.com:8080' );
say $req->host; # example.com:8080
my $req = HTTP::Promise::Request->new( GET => 'http://example.com' );
say $req->host; # example.com
my $req = HTTP::Promise::Request->new( GET => 'http://example.com:8383' );
say $req->host; # example.com:8383Read-only. Returns the request URI host part. The port number is added and separated by a colon if the port number is not standard.
So, if the protocol is https and the port number used is something other than 443, it will be suffixed. If the protocol is http and the port number used is something other than 80, it will be suffixed.
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 referencebelow. - 3. an hash reference
-
For more granular control, you can provide an hash reference with the following supported properties:
encodingThe encoding to be applied to the content. This will also set the
Content-Encodingfor thisform-datapart.Note that when provided, the encodings will be applied immediately on the
form-datacontent, whether it is a string or a file.fileA 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
filenameThe
filenameattribute of theContent-Dispositionor thisform-datapart.If this is not provided and
headersproperty is not provided, orheadersis specified, but theContent-Dispositionfilenameattribute is not set, then thefilebasename will be used instead.headersAn HTTP::Promise::Headers object or an array reference of header field-value pairs.
typeThe mime-type to be used for this
form-datapart.If a
fileis provided and this is not specified, it will try to guess the mime-type using HTTP::Promise::MIMENote that even if this provided, and if a
headershas been specified, it will not override an existingContent-Typeheader that would have been set.valueThe
form-datavalue. This is an alternative to providing theform-datacontent as afileObviously you should not use both and if you do,
filewill 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.1timeout
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
url_encode
my $v = $req->url_encode( "=encoding utf-8\n\n=head1 Hello World" );
# %3Dencoding+utf-8%0A%0A%3Dhead1+Hello+Worldor
use utf8;
my $v = $req->url_encode( "文字化けかな" );
# %C3%A6%C2%96%C2%87%C3%A5%C2%AD%C2%97%C3%A5%C2%8C%C2%96%C3%A3%C2%81%C2%91%C3%A3%C2%81%C2%8B%C3%A3%C2%81%C2%AAThis returns the string provided properly URL-encoded.
This is actually a convenient wrapper around URL::Encode::XS::url_encode or URL::Encode::XS::url_encode_utf8 if this is regarded as a Perl internal UTF-8 string.
url_encode_utf8
Returns the string provided URL-encoded.
This is to be used on Perl internal UTF-8 strings.
version
This is inherited from HTTP::Promise::Message. See "version" in HTTP::Promise::Message
AUTHOR
Jacques Deguest <jack@deguest.jp>
SEE ALSO
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.