/ 
Uniform-HTTP-0.06
/ Uniform::HTTP::Request

NAME

Uniform::HTTP::Request - Framework-neutral HTTP request

SYNOPSIS

use Uniform::HTTP::Request;

my $request = Uniform::HTTP::Request->new(
    method    => 'GET',
    target    => '/items?id=42',
    scheme    => 'https',
    authority => 'example.com',
    headers   => [
        [ 'Accept', 'application/json' ],
    ],
);

DESCRIPTION

Uniform::HTTP::Request represents HTTP request data without owning a connection, transaction, event loop, or transport.

A request always has a method and request target. It may also carry scheme, authority, protocol, version, headers, trailers, and a buffered body.

Creating or changing a request never sends anything.

CONSTRUCTOR

new

my $request = Uniform::HTTP::Request->new(
    method => 'POST',
    target => '/items',
    body   => $bytes,
);

method and target are required.

Optional arguments are:

  • scheme

  • authority

  • protocol

  • version

  • headers

  • trailers

  • body

METHODS

method

my $method = $request->method;

Returns the HTTP method.

Set it with:

$request->method('POST');

target

my $target = $request->target;

Returns the HTTP request target as bytes.

Examples include:

/
/items?id=42
*
example.com:443

Set it with:

$request->target('/other');

scheme

Returns the request scheme, such as http or https, or undef when no scheme is represented.

Uniform does not invent a scheme from the transport or target.

authority

Returns the request authority, such as:

example.com
example.com:8443

or undef when none is represented.

Uniform does not invent an authority from Host or the request target.

protocol

my $protocol = $request->protocol;
$request->protocol('websocket');
$request->protocol(undef);

Returns the Extended CONNECT protocol-name token, or undef when absent. The exact token bytes and spelling are preserved. Tokens such as websocket, connect-udp, and future names use the same API. It is not an HTTP version or an Upgrade field list, and it is never inferred from Upgrade.

The token must use HTTP token syntax. Uniform does not interpret the token, check a registry, change the method, or perform negotiation. All request metadata setters are blocked by freeze_initial() as well as freeze().

target_is_exact

Returns true for canonical Uniform requests because target() contains the exact value supplied by the caller.

Adapters return false when they had to reconstruct a target from separate framework values.

HTTP/2 AND HTTP/3

HTTP/2 and HTTP/3 carry request routing information in pseudo-fields.

For normal requests, an adapter can expose exact :path bytes through target().

Ordinary CONNECT has no :path. In that case the exact :authority bytes are exposed as the authority-form target:

method    => 'CONNECT',
target    => 'example.com:443',
authority => 'example.com:443',

Extended CONNECT instead supplies protocol metadata and keeps the exact :path as the target:

method    => 'CONNECT',
protocol  => 'websocket',
scheme    => 'https',
authority => 'example.com',
target    => '/chat',

The sender validates required field combinations and negotiation for its HTTP version. Uniform checks individual value syntax, allowing metadata to be assembled in any order. It does not certify a legal wire request.

Leaving version unset is appropriate for an application-created request. The sender may select a version without modifying the object.

INHERITED METHODS

Headers, trailers, bodies, versions, section mutability, and completeness come from Uniform::HTTP::Message.

SEE ALSO

Uniform::HTTP, Uniform::HTTP::Message, Uniform::HTTP::Response.

AUTHOR

Joshua S. Day <HAX@cpan.org>

LICENSE

This software is available under the MIT License.