/ 
Uniform-HTTP-0.03
/ Uniform::HTTP

NAME

Uniform::HTTP - Framework-neutral HTTP messages and authentication

SYNOPSIS

use Uniform::HTTP::Request;
use Uniform::HTTP::Response;

my $request = Uniform::HTTP::Request->new(
    method    => 'GET',
    target    => '/users?id=42',
    scheme    => 'https',
    authority => 'example.com',
);

my $response = Uniform::HTTP::Response->new(
    status => 200,
    body   => "hello\n",
);

DESCRIPTION

Uniform::HTTP provides small HTTP message objects that are not tied to one client, server, framework, transport, or event loop.

It gives HTTP implementations a common way to represent requests, responses, headers, buffered bodies, and authentication data.

Uniform::HTTP does not open sockets, parse network traffic, serialize HTTP, or send requests. The surrounding HTTP implementation still owns those jobs.

START HERE

Most application code uses Uniform::HTTP::Request and Uniform::HTTP::Response.

A request needs a method and target:

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

A response needs a status:

my $response = Uniform::HTTP::Response->new(
    status => 200,
    body   => 'ok',
);

Headers are stored as ordered name/value pairs so duplicate fields are not lost:

my $response = Uniform::HTTP::Response->new(
    status => 200,
    headers => [
        [ 'Set-Cookie', 'a=1' ],
        [ 'Set-Cookie', 'b=2' ],
    ],
);

my $values = $response->header_values('Set-Cookie');

body() only returns a body that is already buffered. It never consumes a stream or performs I/O.

AUTHENTICATION

Uniform::HTTP::Auth prepares Basic, Bearer, and Digest authentication field values.

use Uniform::HTTP::Auth;

my $auth = Uniform::HTTP::Auth->new(
    origin => 'https://example.com:443',
    credentials => {
        username => 'user',
        password => 'secret',
    },
);

Authentication calculation is separate from sending or retrying a request.

MODULES

SCOPE

Uniform::HTTP represents HTTP semantics. It deliberately does not own:

  • sockets, TLS, or connections

  • HTTP parsing or serialization

  • HTTP/1 framing or HTTP/2 and HTTP/3 streams

  • event loops

  • streaming I/O

  • retries, redirects, or framework lifecycle

This narrow boundary is what allows the same contract to be used by unrelated HTTP implementations.

Library authors implementing adapters should see docs/MESSAGE-SPEC.md and docs/ADAPTERS.md in the distribution.

VERSION

Version 0.03.

AUTHOR

Joshua S. Day <HAX@cpan.org>

LICENSE

This software is available under the MIT License.