/ 
HTTP-Promise-v0.5.2
River stage one • 2 direct dependents • 3 total dependents
/ HTTP::Promise::Response

NAME

HTTP::Promise::Response - HTTP Response Class

SYNOPSIS

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

VERSION

v0.1.0

DESCRIPTION

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.

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 $resp = HTTP::Promise::Response->new( $code, $status, $headers, $content,
    host        => 'example.com',
    uri         => 'https://example.com/somewhere',
);
my $resp = HTTP::Promise::Response->new( $code, $status, $headers, $content, {
    host        => 'example.com',
    uri         => 'https://example.com/somewhere',
});
my $resp = HTTP::Promise::Response->new( $code, $status, $headers,
    host        => 'example.com',
    uri         => 'https://example.com/somewhere',
);
my $resp = 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

1. $code

An integer representing the status code, such as 101 (switching protocol).

2. $status

The status string, such as Switching Protocol.

3. $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',
]);
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:

  • 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

  • status

    Same as $status above.

  • version

    The HTTP protocol version. Defaults to 1.17

METHODS

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

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

base

Returns the base URI as an URI object if it can find one, or undef otherwise.

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.

code

Sets or gets the HTTP response code. This returns a number object

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

current_age

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.

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.0

dump

This dumps the HTTP response 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.

filename

Returns a possible filename, if any, for this response.

To achieve this, it tries different approaches:

1. Content-Disposition header

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)

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)

2. Content-Location header

It will use the base filename of the URI.

3. 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.

fresh_until

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".

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:

  • 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.

  • h_min

    Integer representing seconds. This is the lower limit of the heuristic expiry age to use. The default is 60 (1 minute).

  • h_max

    Integer representing seconds. This is the upper limit of the heuristic expiry age to use. The default is 86400 (24 hours).

  • 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.

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_client_error

Returns true if the "code" corresponds to a client error, which typically is a code from 400 to 499, or false otherwise.

See also "is_client_error" in HTTP::Promise::Status

is_encoding_supported

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

is_error

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.

See also "is_error" in HTTP::Promise::Status

is_fresh

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".

is_info

Returns true if the "code" corresponds to an informational code, which typically is a code from 100 to 199, or false otherwise.

See also "is_info" in HTTP::Promise::Status

is_redirect

Returns true if the "code" corresponds to a redirection, which typically is a code from 300 to 399, or false otherwise.

See also "is_redirect" in HTTP::Promise::Status

is_server_error

Returns true if the "code" corresponds to a server error, which typically is a code from 500 to 599, or false otherwise.

See also "is_server_error" in HTTP::Promise::Status

is_success

Returns true if the "code" corresponds to a successful response, which typically is a code from 200 to 299, or false otherwise.

See also "is_success" in HTTP::Promise::Status

make_boundary

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

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

previous

Sets or gets an HTTP::Promise::Message object corresponding to the previous HTTP query. This is used to keep track of redirection.

protocol

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

redirects

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.

For example:

my $reds = $r->redirects;
say "Number of redirects: ", $reds->length;

request

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.

start_line

Returns a string representing the start-line containing the protocol, the code and the status of the response.

For example:

GET / HTTP/1.1

See rfc7230, section 3.1

status

Sets or gets the response status string, such as OK for code 200. This returns a scalar object

status_line

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

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.