HTTP::Promise::Response - Asynchronous HTTP Request and Promise
use HTTP::Promise::Response; my $resp = HTTP::Promise::Response->new || die( HTTP::Promise::Response->error, "\n" );
v0.1.0
HTTP::Promise::Response implements a similar interface to HTTP::Response, 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::Response inherits from HTTP::Promise::Message
One major difference with HTTP::Response is that the HTTP response 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.
HTTP::Response
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 | | | +------------------------+
my $req = HTTP::Promise::Response->new( $code, $status, $headers, $content, host => 'example.com', uri => 'https://example.com/somewhere', ); my $req = HTTP::Promise::Response->new( $code, $status, $headers, $content, { host => 'example.com', uri => 'https://example.com/somewhere', }); my $req = HTTP::Promise::Response->new( $code, $status, $headers, host => 'example.com', uri => 'https://example.com/somewhere', ); my $req = HTTP::Promise::Response->new( $code, $status, $headers, { host => 'example.com', uri => 'https://example.com/somewhere', });
Provided with an HTTP code, HTTP status, 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::Response 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
undef
$code
An integer representing the status code, such as 101 (switching protocol).
101
$status
The status string, such as Switching Protocol.
Switching Protocol
$headers
Either an array reference of header-value pairs, or an HTTP::Promise::Headers object or an HTTP::Headers object.
If an array reference is provided, an HTTP::Promise::Headers object will be instantiated with it.
For example::
my $r = HTTP::Promise::Response->new( $code, $status, [ 'Content-Type' => 'text/html; charset=utf-8', Content_Encoding => 'gzip', ]);
$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:
code
Same as $code above.
content
Same as $content above.
headers
Same as $headers above.
protocol
The HTTP protocol, such as HTTP/1.1 or HTTP/2
HTTP/1.1
HTTP/2
status
Same as $status above.
version
The HTTP protocol version. Defaults to 1.17
1.17
This is inherited from HTTP::Promise::Message. See "add_content" in HTTP::Promise::Message
This is inherited from HTTP::Promise::Message. See "add_content_utf8" in HTTP::Promise::Message
This is inherited from HTTP::Promise::Message. See "add_part" in HTTP::Promise::Message
This is inherited from HTTP::Promise::Message. See "as_string" in HTTP::Promise::Message
Returns the base URI as an URI object if it can find one, or undef otherwise.
This is inherited from HTTP::Promise::Message and returns the multipart boundary currently set in the Content-Type header.
Content-Type
This is inherited from HTTP::Promise::Message. See "can" in HTTP::Promise::Message
This is inherited from HTTP::Promise::Message. See "clear" in HTTP::Promise::Message
This clones the current object and returns the clone version.
Sets or gets the HTTP response code. This returns a number object
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 );
This is inherited from HTTP::Promise::Message. See "content_charset" in HTTP::Promise::Message
This is inherited from HTTP::Promise::Message. See "content_ref" in HTTP::Promise::Message
Calculates the "current age" of the response as specified by rfc2616, section 13.2.3.
The age of a response is the time since it was sent by the origin server. The returned value is a number representing the age in seconds.
This is inherited from HTTP::Promise::Message. See "decodable" in HTTP::Promise::Message
This is inherited from HTTP::Promise::Message. See "decode" in HTTP::Promise::Message
This is inherited from HTTP::Promise::Message. See "decode_content" in HTTP::Promise::Message
This is inherited from HTTP::Promise::Message. See "decoded_content" in HTTP::Promise::Message
This is inherited from HTTP::Promise::Message. See "decoded_content_utf8" in HTTP::Promise::Message
Sets or gets the default HTTP protocol to use. This defaults to HTTP/1.0
HTTP/1.0
This dumps the HTTP response and prints it on the STDOUT in void context, or returns a string of it.
STDOUT
This is inherited from HTTP::Promise::Message. See "encode" in HTTP::Promise::Message
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.
Returns a possible filename, if any, for this response.
To achieve this, it tries different approaches:
Content-Disposition
It will check in the Content-Disposition header of the response to see if there ia a filename attribute, or a filename* attribute (as defined in rfc2231)
filename
filename*
For example:
Content-Disposition: form-data; name="myfile"; filename*=UTF-8''%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB.txt
or
Content-Disposition: form-data; name="myfile"; filename*=UTF-8'ja-JP'%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB.txt
In the above example, note the * after the attribute name filename. It is not a typo and part of the rfc2231 standard
*
or encoded with quoted-printable
Content-Disposition: attachment; filename="=?UTF-8?Q?=E3=83=95=E3=82=A1=E3=82=A4=E3=83=AB.txt?="
or encoded with base64
Content-Disposition: attachment; filename="=?UTF-8?B?44OV44Kh44Kk44OrLnR4dAo?="
Here the filename would be ファイル.txt (i.e. "file.txt" in Japanese)
ファイル.txt
Content-Location
It will use the base filename of the URI.
request URI
If there was an initial request URI, it will use the URI base filename.
This might not be the original request URI, because there might have been some redirect responses first.
Whatever filename found is returned as-is. You need to be careful there are no dangerous characters in it before relying on it as part of a filepath.
If nothing is found, undef is returned.
Returns the time (in seconds since epoch) when this entity is no longer fresh.
Options might be passed to control expiry heuristics. See the description of "freshness_lifetime".
Calculates the "freshness lifetime" of the response as specified by rfc2616, section 13.2.4 and updated by rfc7234, section 4.2.
The "freshness lifetime" is the length of time between the generation of a response and its expiration time. The returned value is the number of seconds until expiry.
If the response does not contain an Expires or a Cache-Control header, then this function will apply some simple heuristic based on the Last-Modified header to determine a suitable lifetime. The following options might be passed to control the heuristics:
Expires
Cache-Control
Last-Modified
heuristic_expiry
Boolean. If set to a false value, do not apply heuristics and just return undef when Expires or Cache-Control field is lacking.
h_lastmod_fraction
Integer. This number represent the fraction of the difference since the Last-Modified timestamp to make the expiry time.
The default is 0.10, the suggested typical setting of 10% in rfc2616.
0.10
h_min
Integer representing seconds. This is the lower limit of the heuristic expiry age to use. The default is 60 (1 minute).
60
h_max
Integer representing seconds. This is the upper limit of the heuristic expiry age to use. The default is 86400 (24 hours).
86400
h_default
Integer representing seconds. This is the expiry age to use when nothing else applies.
The default is 3600 (1 hour) or h_min if greater.
3600
This is inherited from HTTP::Promise::Message. See "header" in HTTP::Promise::Message
Sets or gets a HTTP::Promise::Headers object.
A header object is always created upon instantiation, whether you provided headers fields or not.
This is inherited from HTTP::Promise::Message. See "headers_as_string" in HTTP::Promise::Message
Returns true if the "code" corresponds to a client error, which typically is a code from 400 to 499, or false otherwise.
400
499
See also "is_client_error" in HTTP::Promise::Status
This is inherited from HTTP::Promise::Message. See "is_encoding_supported" in HTTP::Promise::Message
Returns true if the "code" corresponds to an error (client error or server error), which typically is a code from 400 to 599, or false otherwise.
599
See also "is_error" in HTTP::Promise::Status
Returns true if the response is fresh, based on the values of "freshness_lifetime" and "current_age". If the response is no longer fresh, then it has to be re-fetched or re-validated by the origin server.
Options might be passed to control expiry heuristics, see the description of "freshness_lifetime".
Returns true if the "code" corresponds to an informational code, which typically is a code from 100 to 199, or false otherwise.
100
199
See also "is_info" in HTTP::Promise::Status
Returns true if the "code" corresponds to a redirection, which typically is a code from 300 to 399, or false otherwise.
300
399
See also "is_redirect" in HTTP::Promise::Status
Returns true if the "code" corresponds to a server error, which typically is a code from 500 to 599, or false otherwise.
500
See also "is_server_error" in HTTP::Promise::Status
Returns true if the "code" corresponds to a successful response, which typically is a code from 200 to 299, or false otherwise.
200
299
See also "is_success" in HTTP::Promise::Status
This is inherited from HTTP::Promise::Message. See "make_boundary" in HTTP::Promise::Message
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.
This is inherited from HTTP::Promise::Message. See "parts" in HTTP::Promise::Message
Sets or gets an HTTP::Promise::Message object corresponding to the previous HTTP query. This is used to keep track of redirection.
This is inherited from HTTP::Promise::Message. See "protocol" in HTTP::Promise::Message
Returns an array object of redirect responses that lead up to this response by following the $r-previous> chain. The list order is oldest first.
$r-
my $reds = $r->redirects; say "Number of redirects: ", $reds->length;
Sets or gets the HTTP::Promise::Request related to this response.
It is not necessarily the same request passed to the "request" in HTTP::Promise, because there might have been redirects and authorisation retries in between.
Returns a string representing the start-line containing the protocol, the code and the status of the response.
GET / HTTP/1.1
See rfc7230, section 3.1
Sets or gets the response status string, such as OK for code 200. This returns a scalar object
OK
Returns a regular string made of the "code" and the "status". If no status is set, this will guess it from "status_message" in HTTP::Promise::Status
This is inherited from HTTP::Promise::Message. See "version" in HTTP::Promise::Message
Jacques Deguest <jack@deguest.jp>
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(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.
To install HTTP::Promise, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTTP::Promise
CPAN shell
perl -MCPAN -e shell install HTTP::Promise
For more information on module installation, please visit the detailed CPAN module installation guide.