NAME

HTTP::Promise::Headers::AltSvc - AltSvc Header Field

SYNOPSIS

    use HTTP::Promise::Headers::AltSvc;
    my $alt = HTTP::Promise::Headers::AltSvc->new || 
        die( HTTP::Promise::Headers::AltSvc->error, "\n" );
    $alt->alternative( q{h2="new.example.org:80"} );
    $alt->alternative( 'h2', 'new.example.org:80' );
    my $def = $alt->alternative; # h2="new.example.org:80"
    $alt->ma(2592000);
    $alt->persist(1);
    $alt->authority( 'new.example.org:443' );
    $alt->protocol( 'h2' );
    say "$alt"; # stringifies
    say $alt->as_string; # same

VERSION

    v0.1.0

DESCRIPTION

The following description is taken from Mozilla documentation.

    Alt-Svc: clear
    Alt-Svc: <protocol-id>=<alt-authority>

The special value clear indicates that the origin requests all alternative services for that origin to be invalidated.

protocol-id is the ALPN protocol identifier. Examples include h2 for HTTP/2 and h3-25 for draft 25 of the HTTP/3 protocol.

alt-authority is the quoted string specifying the alternative authority which consists of an optional host override, a colon, and a mandatory port number.

    Alt-Svc: h2=":443"; ma=2592000;
    Alt-Svc: h2=":443"; ma=2592000; persist=1
    Alt-Svc: h2="alt.example.com:443", h2=":443"
    Alt-Svc: h3-25=":443"; ma=3600, h2=":443"; ma=3600

Multiple entries can be specified in a single Alt-Svc header using comma as separator. In that case, early entries are considered more preferable.

You can achieve this the following way:

    my $alt1 = HTTP::Promise::Headers::AltSvc->new( q{h2="alt.example.com:443"} );
    $alt1->ma(3600);
    $alt1->persist(1);
    my $alt2 = HTTP::Promise::Headers::AltSvc->new( q{h2=":443"} );
    $alt2->ma(3600);
    my $headers = HTTP::Promise::Headers->new;
    $headers->push_header( alt_svc => "$alt1", alt_svc => "$alt2" );

CONSTRUCTOR

new

You can create a new instance of this class without passing any parameter, and set them afterward.

If you want to set parameters upon object instantiation, this takes either an array reference with 2 values (protocol and authority), or a string (or something that stringifies, and an optional hash or hash reference of parameters and it returns a new object.

If you provide a string, it will be parsed, so be careful what you provide, and make sure that non-ascii characters are escaped first. For example:

    my $alt = HTTP::Promise::Headers::AltSvc->new( 'w=x:y#z' );

It will be interpreted, wrongly, as w being the protocol and x:y#z, so instead you would need to either escape it before (with URI::Escape::XS for example), or provide it as an array of 2 elements (protocol and authority), such as:

    my $alt = HTTP::Promise::Headers::AltSvc->new( ['w=x:y#z', 'new.example.org:443'] );

METHODS

alternative

Sets or gets the alternative protocol and authority.

For example:

    $h->alternative( $proto, $auth );
    my $alt = $h->alternative; # h2="alt.example.com:443"

authority

Sets or gets the authority, which is the value in the equal assignment, such as:

    h2="alt.example.com:443"

Here the authority would be alt.example.com:443

    my $u = URI->new( 'https://alt.example.com' );
    $h->authority( $u->host_port );

ma

This is optional and takes a number.

The number of seconds for which the alternative service is considered fresh. If omitted, it defaults to 24 hours. Alternative service entries can be cached for up to <max-age> seconds, minus the age of the response (from the Age header). Once the cached entry expires, the client can no longer use this alternative service for new connections.

param

Set or get an arbitrary name-value pair attribute.

params

Set or get multiple name-value parameters.

Calling this without any parameters, retrieves the associated hash object

persist

This is optional and takes a number.

Usually cached alternative service entries are cleared on network configuration changes. Use of the persist=1 parameter requests that the entry not be deleted by such changes.

protocol

Sets or gets the protocol. For example:

    $alt->protocol( 'h2' );

Here, h2 is the protocol and means HTTP/2. h3-25 would be for draft 25 of the HTTP/3 protocol.

You can even pass unsafe characters. They will be encoded upon stringification:

    $alt->protocol( 'w=x:y#z' ); # example from rfc7838

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

Mozilla documentation, rfc7838, section 3

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.

cpanm HTTP::Promise

perl -MCPAN -e shell
install HTTP::Promise