NAME

HTTP::Promise::Headers - HTTP Headers Class

SYNOPSIS

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

VERSION

    v0.2.0

DESCRIPTION

This class uses for the most part an XS module (HTTP::XSHeaders) to be very fast, and yet provides a convenient and versatile interface to retrieve and manipulate HTTP headers.

A number of classes has been created to have a more granular control on the creation of some header values. See "SEE ALSO"

All HTTP headers known today have their corresponding method that can be used to easily get or set their corresponding header value.

CONSTRUCTOR

new

This instantiates a new HTTP::Promise::Headers object. You might pass some initial attribute-value pairs as parameters to the constructor.

For example:

    $h = HTTP::Headers->new(
        Date         => 'Mon, 09 May 2022 09:00:00 GMT',
        Content_Type => 'text/html; charset=utf-8; version=5.0',
        Content_Base => 'http://www.example.org/'
    );

The constructor arguments are passed to the "header" method described below.

METHODS

add

This is an alias for "push_header"

as_string

Provided with an optional EOL to be used as End-Of-Line character, and this will return a string representation of the headers. EOL defaults to \015\012. Embedded "\n" characters in header field values will be substituted with this line ending sequence.

This uses "scan" internally and use header field case as suggested by HTTP specifications. It will also follow recommended "Good Practice" of ordering the header fields. Long header values are not folded.

authorization_basic

This is a convenience method around the "authorization" method for the Authorization header using the "Basic Authentication Scheme".

To set the related header value, you provide a login and an optional password, and this will set the Authorization header value and return the current headers object for chaining.

    $h->authorization_basic( $user, $password );

If no value is provided, this will get the curent value of the Authorization header field, base64 decode it, and return the decoded string as a scalar object, i.e. something like usernaem:password

    my $str = $h->authorization_basic;

boundary

This is a convenience method to set or get the boundary, if any, used for multipart Content-Type

If provided, this will add the boundary parameter with the given value to the Content-Type header field.

If no value is provided, this returns the current boundary, if any, or an empty string.

charset

This is a convenience method to set or get the charset associated with the Content-Type header field.

If provided, this will add the charset parameter with the given value to the Content-Type header field.

If no value is provided, this returns the current charset, if any, or an empty string.

clear

This will remove all header fields.

clone

Returns a copy of this HTTP::Promise::Headers object.

content_is_text

Returns true if the Content-Type mime-type is textual in nature, i.e. its first half is text, false otherwise. For example: text/plain or text/html

content_is_html

Returns true if the Content-Type mime-type is html, such as text/html, false otherwise.

content_is_json

Returns true if the Content-Type mime-type is application/json, false otherwise.

content_is_xhtml

Returns true if the Content-Type mime-type is application/xhtml+xml or application/vnd.wap.xhtml+xml, false otherwise.

content_is_xml

Returns true if the Content-Type mime-type is text/xml or application/xml, or contains the keyword xml, false otherwise.

content_type_charset

This is a legacy method and it returns the upper-cased charset specified in the Content-Type header. In list context return the lower-cased bare content type followed by the upper-cased charset. Both values will be undef if not specified in the header.

decode_filename

This takes a file name from the Content-Disposition header value typically and returns it decoded if it was encoded as per the rfc2231

For example:

    Content-Disposition: form-data; name="fileField"; filename*=UTF-8''%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB.txt
 
    my $fname = $h->decode_filename( "UTF-8''%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB.txt" );
 
 or
 
    Content-Disposition: form-data; name="fileField"; filename*=UTF-8'ja-JP'%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB.txt

    my $fname = $h->decode_filename( "UTF-8'ja-JP'%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB.txt" );

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?="

    my $fname = $h->decode_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?="

    my $fname = $h->decode_filename( "=?UTF-8?B?44OV44Kh44Kk44OrLnR4dAo?=" );

In the above example, the result for $fname would yield ファイル.txt (i.e. file.txt in Japanese)

debug

Sets or gets the debug value. If positive, this will trigger an output of debugging messages on the STDERR or in the web server log files. Be mindful that this slows down the script, so make sure to switch it off once you are done.

default_type

Sets or gets the default mime-type to be used.

delete

This is an alias for "remove_header"

encode_filename

This takes a file name to be used in the Content-Disposition header value, and an optional language iso 639 code (see rfc1766), and if it contains non ascii characters, it will utf-8 encode it and URI escape it according to rfc2231 and return the newly encoded file name.

If the file name did not require any encoding, it will return undef, so you can write something like this:

    my $filename = q{マイファイル.txt};
    if( my $enc = $h->encode_filename( $filename ) )
    {
        $filename = $enc;
        # Now $filename is: UTF-8''%E3%83%9E%E3%82%A4%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB.txt
    }

You can optionally pass a language code argument:

    if( my $enc = $h->encode_filename( $filename, 'ja-JP' ) )
    {
        $filename = $enc;
        # Now $filename is: UTF-8'ja-JP'%E3%83%9E%E3%82%A4%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB.txt
    }

The Content-Disposition header value would then contain a property filename* (with the trailing wildcard).

error

Sets or gets an error and when set, this returns undef. When no argument is provided, this returns the latest error set.

The error returned is actually a HTTP::Promise::Exception object.

exists

Provided with a header field name and this returns true if it exists, or false otherwise.

flatten

    $h->flatten();

Returns the list of pairs of keys and values.

get

This is an alias for "header", mainly used without argument.

    $h->header( $field );
    $h->header( $field => $value );
    $h->header( $f1 => $v1, $f2 => $v2, ... );

The following is an extract from the original HTTP::Headers class.

Sets or gets the value of one or more header fields. The header field name ($field) is not case sensitive. To make the life easier for perl users who wants to avoid quoting before the => operator, you can use '_' as a replacement for '-' in header names.

The "header" method accepts multiple field-value ($field = $value>) pairs, which means that you can update several header field values with a single invocation.

The $value argument may be a plain string or an array reference of strings for a multi-valued field. If the $value is provided as undef then the field is removed.

If the $value is not given, then that header field will remain unchanged. In addition to being a string, $value may be something that stringifies.

The old value (or values) of the last of the header fields is returned. If no such field exists undef will be returned.

A multi-valued field will be returned as separate values in list context and will be concatenated with ", " as separator in scalar context. The HTTP spec (rfc7230 which obsoleted rfc2616) promises that joining multiple values in this way will not change the semantic of a header field, but in practice there are cases like old-style Netscape cookies where "," is used as part of the syntax of a single field value.

Examples:

    $h->header( MIME_Version => '1.0',
                 User_Agent   => 'My-Web-Client/0.01' );
    $h->header( Accept => "text/html, text/plain, image/*" );
    $h->header( Accept => [qw( text/html text/plain image/* )] );
    @accepts = $h->header( 'Accept' ); # get multiple values
    $accepts = $h->header( 'Accept' ); # get values as a single string

header_field_names

The following is an extract from the original HTTP::Headers class.

Returns the list of distinct names for the fields present in the header. The field names have case as suggested by HTTP spec, and the names are returned in the recommended "Good Practice" order.

In scalar context return the number of distinct field names.

init_header

    $h->init_header( $field => $value );

Set the specified header to the given value, but only if no previous value for that field is set.

The header field name ($field) is not case sensitive and '_' can be used as a replacement for '-'.

The $value argument may be a scalar or a reference to a list of scalars.

make_boundary

Returns a new boundary using Data::UUID

mime_attr

Provided with a header field name and an attribute name separated by a dot, such as content-disposition.filename and this will return the value for that attribute in this header.

If a value is provided, it will be set, otherwise it will be returned.

If no attribute is provided, it will set or get the header field main value.

For example:

    Content-Disposition: attachment; filename="hello.txt"
    my $dispo = $h->mime_attr( 'content-disposition' );

will return attachment

mime_encoding

Returns the value of the Content-Encoding, Transfer-Encoding or Content-Transfer-Encoding (the latter only exists in mail, not in HTTP)

mime_type

Returns the mime-type from the Content-Type header value, or the one from default_type, if it is set. If nothing is found, this returns an empty string (not undef).

multipart_boundary

Returns the multipart boundary used, if any, or an empty string otherwise.

    my $boundary = $h->multipart_boundary;
    # or you can provide the Content-Type if you already have it; it will save a few cycle
    my $boundary = $h->multipart_boundary( $content_type );

print

Provided with a filehandle, or an HTTP::Promise::IO object and this will print on it the string representation of the headers and return whatever value "print" in perlfunc will return.

proxy_authorization_basic

push_header

    $h->push_header( $field => $value );
    $h->push_header( $f1 => $v1, $f2 => $v2, ... );

Add a new value for the specified header. Previous values for the same header are retained.

As for the "header" method, the field name ($field) is not case sensitive and '_' can be used as a replacement for '-'.

The $value argument may be a scalar or a reference to a list of scalars.

    $header->push_header( Accept => 'image/jpeg' );
    $header->push_header( Accept => [ map( "image/$_", qw( gif png tiff ) )] );

recommended_filename

This returns the filename set in either Content-Disposition with the filename property or in Content-Type with the name property.

If none exists, this returns undef.

remove

This is an alias for "remove_header"

remove_content_headers

This will remove all the headers used to describe the content of a message.

All header field names prefixed with Content- are included in this category, as well as Allow, Expires and Last-Modified. rfc7230 denotes these headers as Entity Header Fields.

The return value is a new HTTP::Promise::Headers object that contains the removed headers only.

remove_header

    my @values = $h->remove_header( $field, ... );
    my $total_values_removed = $h->remove_header( $field, ... );

This function removes the header with the specified names.

The header names ($field) are not case sensitive and '_' can be used as a replacement for '-'.

The return value is the values of the headers removed. In scalar context the number of headers removed is returned.

Note that if you pass in multiple header names then it is generally not possible to tell which of the returned values belonged to which field.

replace

Provided with a header field name and a value and this replace whatever current value with the value provided.

It returns the current object for chaining.

request_timeout

Sets or gets the request timeout. This takes an integer.

scan

    $h->scan( \&process_header_field );

Apply a subroutine to each header field in turn. The callback routine is called with two parameters; the name of the field and a single value (a string). If a header field is multi-valued, then the routine is called once for each value. The field name passed to the callback routine has case as suggested by HTTP spec, and the headers will be visited in the recommended "Good Practice" order.

Any return values of the callback routine are ignored. The loop can be broken by raising an exception (die), but the caller of scan() would have to trap the exception itself.

type

This sets or gets the Content-Type header value when setting a value, and returns only the mime-type when retrieving the value.

    $h->type( 'text/plain' );
    # Assuming Content-Type: text/html; charset=utf-8
    my $type = $h->type; # text/html

uri_escape_utf8

Provided with a string and this returns an URI-escaped string using URI::Escape::XS

HTTP HEADERS METHODS

accept

    $h->accept( q{text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8} );
    $h->accept( [qw( text/html application/xhtml+xml application/xml;q=0.9 */*;q=0.8 )] );

Sets or gets the Accept header field value. It takes either a string or an array or array reference of values.

See rfc7231, section 5.3.2 and Mozilla documentation

accept_charset

    $h->accept( 'utf-8' );

Sets or gets the Accept-Charset headers field value. It takes a single string value.

You should know that the Accept-Charset header is deprecated by HTTP standards and that no modern web browsers is sending nor any modern HTTP server recognising it.

See Mozilla documentation

accept_encoding

    $h->accept_encoding( 'gzip, deflate, br' );
    $h->accept_encoding( [qw( gzip deflate br )] );
    $h->accept_encoding( 'br;q=1.0, gzip;q=0.8, *;q=0.1' );

Sets or gets the Accept-Encoding header field value. It takes either a string or an array or array reference of values.

See also HTTP::Promise::Headers::AcceptEncoding to have a more granular control.

Encoding header fields and their nuances:

Accept-Encoding: The encodings accepted by the client.
Content-Encoding: Contains the encodings that have been applied to the content, before transport
TE: The encodings the user agent accepts.
Transfer-Encoding: The encoding applied during transfer, such as chunked

See rfc7231, section 5.3.4 and Mozilla documentation

accept_language

    $h->accept_language( 'fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5' );
    $h->accept_language( [qw(fr-CH fr;q=0.9 en;q=0.8 de;q=0.7 *;q=0.5 )] );

Sets or gets the Accept-Language header field value. It takes either a string or an array or array reference of values.

See also HTTP::Promise::Headers::AcceptLanguage to have a more granular control.

See rfc7231, section 5.3.5 and Mozilla documentation

accept_patch

    $h->accept_patch( 'application/example, text/example' );
    $h->accept_patch( [qw( application/example text/example )] );
    $h->accept_patch( 'text/example;charset=utf-8' );
    $h->accept_patch( 'application/merge-patch+json' );

Sets or gets the Accept-Patch header field value. It takes either a string or an array or array reference of values.

This is a server response header.

See rfc5789, section 3.1, rfc7231, section 4.3.4 and Mozilla documentation

accept_post

    $h->accept_post( 'application/example, text/example' );
    $h->accept_post( [qw( application/example text/example )] );
    $h->accept_post( 'image/webp' );
    $h->accept_post( '*/*' );

Sets or gets the Accept-Post header field value. It takes either a string or an array or array reference of values.

This is a server response header.

See rfc7231, section 4.3.3 and Mozilla documentation

accept_ranges

    $h->accept_ranges(1234);

Sets or gets the Accept-Ranges header field value. It takes either a string or an array or array reference of values.

This is a server response header.

See rfc7233, section 2.3 and Mozilla documentation

acceptables

This returns a new HTTP::Promise::Headers::Accept object based on the content of the Accept header value.

age

    $h->age(1234);

Sets or gets the Age header field value. It takes a numeric value.

This is a server response header.

See rfc7234, section 5.1 and Mozilla documentation

allow

    $h->allow( 'GET, POST, HEAD' );
    $h->allow( [qw( GET POST HEAD )] );

Sets or gets the Allow header field value. It takes either a string or an array or array reference of values.

This is a server response header.

See rfc7231, section 7.4.1 and Mozilla documentation

allow_credentials

    # Access-Control-Allow-Credentials: true
    $h->allow_credentials( 'true' );

Sets or gets the Access-Control-Allow-Credentials header field value. It takes a string boolean value: true or false.

See Mozilla documentation

allow_headers

    # Access-Control-Allow-Headers: X-Custom-Header, Upgrade-Insecure-Requests
    $h->allow_headers( 'X-Custom-Header, Upgrade-Insecure-Requests' );
    $h->allow_headers( [qw( X-Custom-Header Upgrade-Insecure-Requests )] );

Sets or gets the Access-Control-Allow-Headers header field value. It takes either a string or an array or array reference of values.

This is a server response header.

See rfc7231, section 7.4.1 and Mozilla documentation

allow_methods

    # Access-Control-Allow-Methods: POST, GET, OPTIONS
    $h->allow_methods( 'POST, GET, OPTIONS' );
    $h->allow_methods( [qw( POST GET OPTIONS )] );
    # Access-Control-Allow-Methods: *
    $h->allow_methods( '*' );

Sets or gets the Access-Control-Allow-Methods header field value. It takes either a string or an array or array reference of values.

This is a server response header.

See Mozilla documentation

allow_origin

    # Access-Control-Allow-Origin: *
    $h->allow_origin( '*' );
    # Access-Control-Allow-Origin: https://food.example.org
    $h->allow_origin( 'https://food.example.org' );
    # Access-Control-Allow-Origin: null
    $h->allow_origin( 'null' );

Sets or gets the Access-Control-Allow-Origin header field value. It takes a string value.

This is a server response header.

See Mozilla documentation

alt_svc

    # Alt-Svc: h2=":443"; ma=2592000;
    $h->alt_svc( 'h2=":443"; ma=2592000' );
    # Alt-Svc: h2=":443"; ma=2592000; persist=1
    $h->alt_svc( 'h2=":443"; ma=2592000; persist=1' );
    # Alt-Svc: h2="alt.example.com:443", h2=":443"
    $h->alt_svc( 'h2="alt.example.com:443", h2=":443"' );
    # Alt-Svc: h3-25=":443"; ma=3600, h2=":443"; ma=3600
    $h->alt_svc( 'h3-25=":443"; ma=3600, h2=":443"; ma=3600' );

Sets or gets the Alt-Svc header field value. It takes either a string or an array or array reference of values.

See also HTTP::Promise::Headers::AltSvc to have a more granular control.

See rfc7838, section 3 and Mozilla documentation

alternate_server

This is a convenience method for the header field Alt-Svc.

To et it value, you provide a hash or hash reference of properties, including name and value respectively for the protocol-id and the alternate authority.

    $h->alternate_server( name => 'h2', value => ':443', ma => 2592000, persist => 1 );

would create the header value:

    Alt-Svc: h2=":443"; ma=2592000; persist=1

Without any parameter, it creates a new HTTP::Promise::Headers::AltSvc object for each Alt-Svc header value and returns an array object of all those HTTP::Promise::Headers::AltSvc objects.

authorization

    # Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
    $h->authorization( 'Basic YWxhZGRpbjpvcGVuc2VzYW1l' );

Sets or gets the Authorization header field value. It takes a string value.

cache_control

    # Cache-Control: max-age=604800
    $h->cache_control( 'max-age=604800' );
    # Cache-Control: s-maxage=604800
    $h->cache_control( 's-maxage=604800' );
    # Cache-Control: no-cache
    $h->cache_control( 'no-cache' );
    # Cache-Control: max-age=604800, must-revalidate
    $h->cache_control( 'max-age=604800, must-revalidate' );
    # Cache-Control: public, max-age=604800, immutable
    $h->cache_control( 'public, max-age=604800, immutable' );

Sets or gets the Cache-Control header field value. It takes either a string or an array or array reference of values.

See also HTTP::Promise::Headers::CacheControl to have a more granular control.

See rfc7234, section 5.2 and Mozilla documentation

clear_site_data

    # Clear-Site-Data: "cache", "cookies", "storage", "executionContexts"
    $h->clear_site_data( q{"cache", "cookies", "storage", "executionContexts"} );
    $h->clear_site_data( [qw( cache cookies storage executionContexts )] );

The Clear-Site-Data header accepts one or more directives. If all types of data should be cleared, the wildcard directive ("*") can be used.

See also HTTP::Promise::Headers::ClearSiteData to have a more granular control.

See Mozilla documentation

connection

    # Connection: keep-alive
    # Connection: close

Sets or gets the Connection header field value. It takes a string value.

See rfc7230, section 6.1 and Mozilla documentation

content_disposition

    # Content-Disposition: inline
    # Content-Disposition: attachment
    # Content-Disposition: attachment; filename="filename.jpg"
    # Content-Disposition: form-data; name="fieldName"
    # Content-Disposition: form-data; name="fieldName"; filename="filename.jpg"

Sets or gets the Content-Disposition header field value. It takes a string value.

See also HTTP::Promise::Headers::ContentDisposition to have a more granular control.

See rfc6266, section 4, rfc7578, section 4.2 and Mozilla documentation

content_encoding

    # Content-Encoding: gzip
    # Content-Encoding: compress
    # Content-Encoding: deflate
    # Content-Encoding: br

    # Multiple, in the order in which they were applied
    # Content-Encoding: deflate, gzip

Sets or gets the Cache-Encoding header field value. It takes either a string or an array or array reference of values.

Encoding header fields and their nuances:

Accept-Encoding: The encodings accepted by the client.
Content-Encoding: Contains the encodings that have been applied to the content, before transport
TE: The encodings the user agent accepts.
Transfer-Encoding: The encoding applied during transfer, such as chunked

See rfc7230, section 3.3.1: "Unlike Content-Encoding (Section 3.1.2.1 of [RFC7231]), Transfer-Encoding is a property of the message, not of the representation"

See rfc7231, section 3.1.2.2 and Mozilla documentation

content_language

    # Content-Language: de-DE
    # Content-Language: en-US
    $h->content_language( 'en-GB' );
    # Content-Language: de-DE, en-CA
    $h->content_language( 'de-DE, en-CA' );
    $h->content_language( [qw( de-DE en-CA )] );

Sets or gets the Cache-Language header field value. It takes either a string or an array or array reference of values.

There is no enforcement on the value provided, so it is up to you to set the proper value or values.

See rfc7231, section 3.1.3.2, rfc5646 and Mozilla documentation

content_length

    # Content-Length: 72
    $h->content_length(72);

Sets or gets the Connection header field value. It takes a numeric value.

See rfc7230, section 3.3.2 and Mozilla documentation

content_location

    # Content-Location: /some/where/file.html
    $h->content_location( '/some/where/file.html' );

Sets or gets the Connection header field value. It takes a numeric value.

See rfc7231, section 3.1.4.2 and Mozilla documentation

content_range

    # Content-Range: bytes 200-1000/67589
    # Unsatisfiable range value
    # Content-Range: bytes */1234

Sets or gets the Content-Range header field value. It takes a string value.

See also HTTP::Promise::Headers::ContentRange to have a more granular control.

See rfc7233, section 4.2 and Mozilla documentation

content_security_policy

    # Content-Security-Policy: default-src 'self' http://example.com;
    #                           connect-src 'none';
    # Content-Security-Policy: connect-src http://example.com/;
    #                           script-src http://example.com/

Sets or gets the Content-Security-Policy header field value. It takes a string value.

See also HTTP::Promise::Headers::ContentSecurityPolicy to have a more granular control.

See Mozilla documentation

content_security_policy_report_only

    # Content-Security-Policy-Report-Only: default-src https:; report-uri /csp-violation-report-endpoint/

Sets or gets the Content-Security-Policy-Report-Only header field value. It takes a string value of properly formatted header value.

See also HTTP::Promise::Headers::ContentSecurityPolicyReportOnly to have a more granular control.

content_type

This sets or gets the Content-Type header value. It takes a string value.

If a value is provided, this will set the header value. If no value is provided, this simply return the header field value.

See also HTTP::Promise::Headers::ContentType to have a more granular control.

cross_origin_embedder_policy

    # Cross-Origin-Embedder-Policy: require-corp
    # Cross-Origin-Opener-Policy: same-origin

This sets or gets the Cross-Origin-Embedder-Policy header value. It takes a string value.

It can have either of the following value: require-corp or same-origin

See also Mozilla documentation

cross_origin_opener_policy

    # Cross-Origin-Opener-Policy: unsafe-none
    # Cross-Origin-Opener-Policy: same-origin-allow-popups
    # Cross-Origin-Opener-Policy: same-origin

This sets or gets the Cross-Origin-Opener-Policy header value. It takes a string value.

It can have either of the following value: unsafe-none or same-origin-allow-popups or same-origin

See also Mozilla documentation

cross_origin_resource_policy

This sets or gets the Cross-Origin-Resource-Policy header value. It takes a string value.

It can have either of the following value: same-site or same-origin or same-origin

See also Mozilla documentation

For more example: https://resourcepolicy.fyi/

cspro

This is an alias for "content_security_policy_report_only"

date

This sets or gets the Date header value. It takes a date string value, a unix timestamp or a DateTime value.

If no value is provided, it returns the current value of the Date header field as a DateTime object.

device_memory

    # Device-Memory: 1

This sets or gets the Device-Memory header value. It takes a number.

Mozilla documentation

digest

    # Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
    # Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=,unixsum=30637

This sets or gets the Digest header value. It takes either a string or an array or array reference of properly formatted values.

See draft rfc and Mozilla documentation

dnt

    # DNT: 0
    # DNT: 1
    # DNT: null

This sets or gets the DNT header value. It takes a string value.

See also Mozilla documentation

early_data

    # Early-Data: 1

This sets or gets the Early-Data header value. It takes a string value.

etag

    # ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
    # ETag: W/"0815"

This sets or gets the Etag header value. It takes a string of properly formatted value.

expect

This sets or gets the Expect header value. It takes a string of properly formatted value, typically 100-continue

For example, before sending a very large file:

    PUT /some/where HTTP/1.1
    Host: origin.example.com
    Content-Type: video/h264
    Content-Length: 1234567890987
    Expect: 100-continue

If the server is ok, it would return a 100 Continue

expect_ct

    # Expect-CT: max-age=86400, enforce, report-uri="https://foo.example.com/report"
    $h->expect_ct( q{max-age=86400, enforce, report-uri="https://foo.example.com/report"} );
    $h->expect_ct( [qw( max-age=86400 enforce report-uri="https://foo.example.com/report" )] );

This sets or gets the Expect-CT header value. It takes a string of properly formatted value.

See also HTTP::Promise::Headers::ExpectCT to have a more granular control.

See also rfc draft and Mozilla documentation

expires

This sets or gets the Expires header value. It takes a date string value, a unix timestamp or a DateTime value.

If no value is provided, it returns the current value of the Date header field as a DateTime object.

For example:

    Expires: Wed, 21 Oct 2015 07:28:00 GMT

expose_headers

This sets or gets the Expose-Headers header value. It takes either a string or an array or array reference of properly formatted values.

For example:

    Access-Control-Expose-Headers: *, Authorization

forwarded

This sets or gets the Forwarded header value. It takes either a string or an array or array reference of properly formatted values.

See also HTTP::Promise::Headers::Forwarded to have a more granular control.

For example:

    Forwarded: for=192.0.2.60;proto=http;by=203.0.113.43
    # Values from multiple proxy servers can be appended using a comma
    Forwarded: for=192.0.2.43, for=198.51.100.17

from

This sets or gets the From header value. It takes a string value.

For example:

    From: webmaster@example.org

host

This sets or gets the Host header value. It takes a string value.

For example:

    Host: dev.example.org

if_match

This sets or gets the If-Match header value. It takes a string value.

For example:

    If-Match: "bfc13a64729c4290ef5b2c2730249c88ca92d82d"
    If-Match: "67ab43", "54ed21", "7892dd"
    If-Match: *

if_modified_since

This sets or gets the If-Modified-Since header value. It takes a date string value, a unix timestamp or a DateTime value.

If no value is provided, it returns the current value of the Date header field as a DateTime object.

For example:

    If-Modified-Since: Wed, 21 Oct 2015 07:28:00 GMT

if_none_match

This sets or gets the If-None-Match header value. It takes a string value.

For example:

    If-None-Match: "bfc13a64729c4290ef5b2c2730249c88ca92d82d"
    If-None-Match: W/"67ab43", "54ed21", "7892dd"
    If-None-Match: *

if_range

This sets or gets the If-Range header value. It takes a string value.

For example:

    If-Range: Wed, 21 Oct 2015 07:28:00 GMT

if_unmodified_since

This sets or gets the If-Unmodified-Since header value. It takes a date string value, a unix timestamp or a DateTime value.

If no value is provided, it returns the current value of the Date header field as a DateTime object.

For example:

    If-Unmodified-Since: Wed, 21 Oct 2015 07:28:00 GMT

keep_alive

This sets or gets the Keep-Alive header value. It takes either a string or an array or array reference of properly formatted values.

See also HTTP::Promise::Headers::KeepAlive to have a more granular control.

Example response containing a Keep-Alive header:

    HTTP/1.1 200 OK
    Connection: Keep-Alive
    Content-Encoding: gzip
    Content-Type: text/html; charset=utf-8
    Date: Thu, 11 Aug 2016 15:23:13 GMT
    Keep-Alive: timeout=5, max=1000
    Last-Modified: Mon, 25 Jul 2016 04:32:39 GMT
    Server: Apache

last_modified

This sets or gets the Last-Modified header value. It takes a date string value, a unix timestamp or a DateTime value.

If no value is provided, it returns the current value of the Date header field as a DateTime object.

For example:

    Last-Modified: Wed, 21 Oct 2015 07:28:00 GMT

link

This sets or gets the Link header value. It takes a string value.

See also HTTP::Promise::Headers::Link to have a more granular control.

Example:

    Link: <https://example.com>; rel="preconnect"

location

This sets or gets the Location header value. It takes a string value.

Example:

    Location: /index.html

max_age

This sets or gets the Location header value. It takes a numeric value.

Example:

    Access-Control-Max-Age: 600

See also Mozilla documentation

nel

This sets or gets the NEL header value. It takes a string of properly formatted json value.

Example:

    NEL: { "report_to": "name_of_reporting_group", "max_age": 12345, "include_subdomains": false, "success_fraction": 0.0, "failure_fraction": 1.0 }

origin

This sets or gets the Origin header value. It takes a string of properly formatted json value.

Example:

    Origin: http://dev.example.org:80

proxy

Sets or gets the URI used for the proxy. It returns a URI object.

proxy_authenticate

This sets or gets the Proxy-Authenticate header value. It takes a string value.

Example:

    Proxy-Authenticate: Basic realm="Access to the internal site"

proxy_authorization

This sets or gets the Proxy-Authorization header value. It takes a string value.

Example:

    Proxy-Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l

range

This sets or gets the Range header value. It takes a string value.

See also HTTP::Promise::Headers::Range to have a more granular control.

Example:

    Range: bytes=200-1000, 2000-6576, 19000-

referer

This sets or gets the Referer header value. It takes a string value.

Example:

    Referer: https://dev.example.org/some/where
    Referer: https://example.org/page?q=123
    Referer: https://example.org/

referrer

This is an alias for "referer"

referrer_policy

This sets or gets the Referrer-Policy header value. It takes a string value.

The allowed values can be: no-referrer, no-referrer-when-downgrade, origin, origin-when-cross-origin, same-origin, strict-origin, strict-origin-when-cross-origin, unsafe-url

Example:

    Referrer-Policy: no-referrer
    # With fallback
    Referrer-Policy: no-referrer, strict-origin-when-cross-origin

See also Mozilla documentation

request_headers

This sets or gets the Access-Control-Request-Headers header value. It takes a string value.

Example:

    Access-Control-Request-Headers: X-PINGOTHER, Content-Type

See also Mozilla documentation

request_method

This sets or gets the Access-Control-Request-Method header value. It takes a string value.

Example:

    Access-Control-Request-Method: POST

See also Mozilla documentation

retry_after

This sets or gets the Retry-After header value. It takes a string value.

Example:

    Retry-After: Wed, 21 Oct 2015 07:28:00 GMT
    Retry-After: 120

save_data

This sets or gets the Save-Data header value. It takes a string value.

The value can be either on or off

Example:

    Save-Data: on

See also Mozilla documentation

server

This sets or gets the Server header value. It takes a string value.

Example:

    Server: Apache/2.4.1 (Unix)

server_timing

This sets or gets the Server header value. It takes a string value.

See also HTTP::Promise::Headers::ServerTiming to have a more granular control.

Example:

    # Single metric without value
    Server-Timing: missedCache

    # Single metric with value
    Server-Timing: cpu;dur=2.4

    # Single metric with description and value
    Server-Timing: cache;desc="Cache Read";dur=23.2

    # Two metrics with value
    Server-Timing: db;dur=53, app;dur=47.2

See also Mozilla documentation

set_cookie

This sets or gets the Set-Cookie header value. It takes a string value.

See also Cookie to have a more granular control.

Example:

    Set-Cookie: sessionId=38afes7a8
    Set-Cookie: __Secure-ID=123; Secure; Domain=example.com
    Set-Cookie: __Host-ID=123; Secure; Path=/

sourcemap

This sets or gets the SourceMap header value. It takes a string value.

Example:

    SourceMap: /path/to/file.js.map

strict_transport_security

This sets or gets the Strict-Transport-Security header value. It takes a string value.

See also HTTP::Promise::Headers::StrictTransportSecurity to have a more granular control.

Example:

    Strict-Transport-Security: max-age=63072000; includeSubDomains; preload

te

This sets or gets the TE header value. It takes a string value.

See also HTTP::Promise::Headers::TE to have a more granular control.

Example:

    TE: deflate
    TE: gzip
    TE: trailers

    # Multiple directives, weighted with the quality value syntax:
    TE: trailers, deflate;q=0.5

Notably, the value trailers means the HTTP client support trailers, which are a set of headers sent after the body.

Encoding header fields and their nuances:

Accept-Encoding: The encodings accepted by the client.
Content-Encoding: Contains the encodings that have been applied to the content, before transport
TE: The encodings the user agent accepts.
Transfer-Encoding: The encoding applied during transfer, such as chunked

timing_allow_origin

This sets or gets the Timing-Allow-Origin header value. It takes a string value.

Example:

    Timing-Allow-Origin: *
    Timing-Allow-Origin: https://dev.example.org, https://example.com

See also Mozilla documentation

title

Sets or gets the Title of the HTML document if that were the case. This is here for legacy.

tk

This sets or gets the deprecated Tk header value. It takes a string value.

Example:

    Tk: N

See also Mozilla documentation

trailer

This sets or gets the Trailer header value. It takes a string value.

Example:

    Trailer: Expires

transfer_encoding

This sets or gets the Transfer-Encoding header value. It takes a string value.

Example:

    Transfer-Encoding: chunked
    Transfer-Encoding: compress
    Transfer-Encoding: deflate
    Transfer-Encoding: gzip

    # Several values can be listed, separated by a comma
    Transfer-Encoding: gzip, chunked

Encoding header fields and their nuances:

Accept-Encoding: The encodings accepted by the client.
Content-Encoding: Contains the encodings that have been applied to the content, before transport
TE: The encodings the user agent accepts.
Transfer-Encoding: The encoding applied during transfer, such as chunked

See rfc7230, section 3.3.1: "Unlike Content-Encoding (Section 3.1.2.1 of [RFC7231]), Transfer-Encoding is a property of the message, not of the representation"

upgrade

This sets or gets the Upgrade header value. It takes a string value.

Example:

    Connection: upgrade
    Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11

    Connection: Upgrade
    Upgrade: websocket

upgrade_insecure_requests

This sets or gets the Upgrade-Insecure-Requests header value. It takes a string value.

Example:

    Upgrade-Insecure-Requests: 1

See also Mozilla documentation

user_agent

This sets or gets the User-Agent header value. It takes a string value.

Example:

    User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0
    User-Agent: curl/7.64.1

vary

This sets or gets the Vary header value. It takes a string value.

Example:

    Vary: *
    Vary: Accept-Encoding, User-Agent

via

This sets or gets the Via header value. It takes a string value.

Example:

    Via: 1.1 vegur
    Via: HTTP/1.1 GWA
    Via: 1.0 fred, 1.1 p.example.net

want_digest

This sets or gets the Want-Digest header value. It takes a string value.

Example:

    Want-Digest: sha-256
    Want-Digest: SHA-512;q=0.3, sha-256;q=1, md5;q=0

See also Mozilla documentation

warning

This sets or gets the Warning header value. It takes a string value.

Example:

    Warning: 110 anderson/1.3.37 "Response is stale"

www_authenticate

This sets or gets the WWW-Authenticate header value. It takes a string value.

Example:

    WWW-Authenticate: Basic realm="Access to the staging site", charset="UTF-8"
    WWW-Authenticate: Digest
        realm="http-auth@example.org",
        qop="auth, auth-int",
        algorithm=SHA-256,
        nonce="7ypf/xlj9XXwfDPEoM4URrv/xwf94BcCAzFZH4GiTo0v",
        opaque="FQhe/qaU925kfnzjCev0ciny7QMkPqMAFRtzCUYo5tdS"
    WWW-Authenticate: Digest
        realm="http-auth@example.org",
        qop="auth, auth-int",
        algorithm=MD5,
        nonce="7ypf/xlj9XXwfDPEoM4URrv/xwf94BcCAzFZH4GiTo0v",
        opaque="FQhe/qaU925kfnzjCev0ciny7QMkPqMAFRtzCUYo5tdS"

x

Sets or gets an arbitrary X-* header. For example:

    $h->x( 'Spip-Cache' => 3600 );

would set the X-Spip-Cache header value to 3600

    my $value = $h->x( 'Spip-Cache' );

x_content_type_options

This sets or gets the X-Content-Type-Options header value. It takes a string value.

Example:

    X-Content-Type-Options: nosniff

See also Mozilla documentation

x_dns_prefetch_control

This sets or gets the X-DNS-Prefetch-Control header value. It takes a string value.

Example:

    X-DNS-Prefetch-Control: on
    X-DNS-Prefetch-Control: off

See also Mozilla documentation

x_forwarded_for

This sets or gets the X-Forwarded-For header value. It takes a string value.

Example:

    X-Forwarded-For: 2001:db8:85a3:8d3:1319:8a2e:370:7348
    X-Forwarded-For: 203.0.113.195
    X-Forwarded-For: 203.0.113.195, 2001:db8:85a3:8d3:1319:8a2e:370:7348

x_forwarded_host

This sets or gets the X-Forwarded-Host header value. It takes a string value.

Example:

    X-Forwarded-Host: id42.example-cdn.com

x_forwarded_proto

This sets or gets the X-Forwarded-Proto header value. It takes a string value.

Example:

   X-Forwarded-Proto: https

x_frame_options

This sets or gets the X-Frame-Options header value. It takes a string value.

Example:

    X-Frame-Options: DENY
    X-Frame-Options: SAMEORIGIN

See also Mozilla documentation

x_xss_protection

This sets or gets the X-XSS-Protection header value. It takes a string value.

Example:

    X-XSS-Protection: 0
    X-XSS-Protection: 1
    X-XSS-Protection: 1; mode=block
    X-XSS-Protection: 1; report=https://example.org/some/where

See also Mozilla documentation

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT & LICENSE

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)