NAME
Uniform::HTTP::Message - Lossless framework-neutral HTTP message
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 shared semantic base for requests and responses. It preserves duplicate fields, field order, and original field-name spelling. It performs no parsing, serialization, encoding, or I/O.
The canonical class is mutable, complete, and lossless. Adapters may implement the same methods without subclassing, but must report their capabilities accurately.
CONSTRUCTOR
new
Accepts optional version, headers, and body named arguments. headers must be an array reference of two-element array references. An omitted body is distinct from a buffered empty string.
METHODS
version
Returns the HTTP version without an HTTP/ prefix, or undef when no version is represented. Passing a version sets it; passing undef clears it.
header
Returns the first matching field value using ASCII case-insensitive matching. Passing a value replaces every matching occurrence with one field at the position of the first occurrence, or appends it when the field was absent.
header_values
Returns an array reference containing every matching value in message order. Values are never comma-joined.
add_header
Appends one field occurrence and returns the message.
remove_header
Removes every matching field occurrence and returns the message.
header_count
Returns the number of field occurrences.
header_name
Returns the original field name at a zero-based index. An index beyond the end returns undef.
header_value
Returns the field value at a zero-based index. An index beyond the end returns undef.
body
Returns buffered body bytes, or undef when no body buffer is present. Passing a defined byte string installs a complete body buffer and returns the message. It never reads a stream, filehandle, callback, or framework input.
has_buffered_body
Returns true only when body() is locally available, including an empty buffer.
is_complete
Returns true for canonical messages. An adapter may return true, false, or undef when the native environment cannot determine completeness.
is_mutable
Returns true for canonical messages. Adapter mutators must throw when this is false.
headers_are_lossless
Returns true when duplicate occurrences, inter-field order, and original field-name spelling are faithfully represented.
BYTE CONTRACT
Methods accept Perl byte strings. Values containing characters outside the byte range are rejected; no encoding is guessed. Field names are HTTP tokens. Field values reject prohibited control bytes while permitting horizontal tab and bytes from 0x80 through 0xff.
MUTATION
All successful mutators return the receiving object. Canonical messages are mutable. Read-only or committed adapters report false from is_mutable() and throw if a mutator is attempted.
AUTHOR
Joshua S. Day <HAX@cpan.org>
LICENSE
This software is available under the MIT License.