/ 
Uniform-HTTP-0.03
/ Uniform::HTTP::Message

NAME

Uniform::HTTP::Message - Common HTTP message behavior

SYNOPSIS

use Uniform::HTTP::Message;

my $message = Uniform::HTTP::Message->new(
    version => '1.1',
    headers => [
        [ 'Content-Type', 'text/plain' ],
        [ 'Set-Cookie',   'a=1' ],
        [ 'Set-Cookie',   'b=2' ],
    ],
    body => "hello\n",
);

DESCRIPTION

Uniform::HTTP::Message is the common base for Uniform::HTTP::Request and Uniform::HTTP::Response.

It stores HTTP version, headers, and an optional buffered body. It does not parse HTTP, send data, read streams, or perform network I/O.

Headers preserve duplicate fields, field order, and original field-name spelling.

Most applications will create Request or Response objects rather than using Message directly.

CONSTRUCTOR

new

my $message = Uniform::HTTP::Message->new(
    version => '1.1',
    headers => [
        [ 'Content-Type', 'text/plain' ],
    ],
    body => 'hello',
);

All arguments are optional.

headers must be an array reference containing [ name, value ] pairs.

HEADERS

my $value = $message->header('Content-Type');

Returns the first matching value. Header names are matched case-insensitively.

Set or replace a header with:

$message->header('Content-Type', 'application/json');

When duplicate fields already exist, the setter replaces them with one field.

header_values

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

Returns an array reference containing every matching value in order.

add_header

$message->add_header('Set-Cookie', 'c=3');

Appends one new field without replacing existing fields.

remove_header

$message->remove_header('X-Debug');

Removes every matching field.

header_count

Returns the number of header field occurrences.

header_name

my $name = $message->header_name($index);

Returns the original field name at a zero-based index.

header_value

my $value = $message->header_value($index);

Returns the field value at a zero-based index.

headers_are_lossless

Returns true for canonical Uniform messages because duplicate fields, order, and original field-name spelling are preserved.

Adapters may return false when their native framework cannot preserve all of those details.

BODY

body

my $bytes = $message->body;

Returns the buffered body, or undef when no buffered body is present.

Set a buffered body with:

$message->body($bytes);

Calling body() never reads a socket, filehandle, callback, or streaming source.

has_buffered_body

Returns true when body() contains a buffered body. An empty string still counts as a buffered body.

VERSION

version

my $version = $message->version;

Returns values such as 1.1, 2, or 3, without an HTTP/ prefix.

Set or clear it with:

$message->version('2');
$message->version(undef);

MESSAGE STATE

is_mutable

Returns true while the represented message values can still be changed.

Canonical Uniform messages begin mutable.

freeze

$message->freeze;

Freezes a canonical Uniform object. After this, setters throw an exception.

freeze() only changes the local object. It does not send headers, commit a framework response, or perform I/O.

is_complete

Returns true when the message is known to be complete.

Canonical objects begin complete. An adapter may return undef when its framework cannot determine completeness yet.

mark_incomplete

Marks a canonical message incomplete.

mark_complete

Marks a canonical message complete.

These two helpers are useful when a detached Uniform object is following externally managed streaming progress.

BYTE STRINGS

Message values are byte strings. Uniform::HTTP does not guess a character encoding.

Header names must be valid HTTP tokens. Header values reject prohibited control bytes.

SEE ALSO

Uniform::HTTP, Uniform::HTTP::Request, Uniform::HTTP::Response.

The full adapter contract is documented in docs/MESSAGE-SPEC.md.

AUTHOR

Joshua S. Day <HAX@cpan.org>

LICENSE

This software is available under the MIT License.