/ 
Uniform-HTTP-0.06
/ Uniform::HTTP::FastPath

NAME

Uniform::HTTP::FastPath - Optional fast path for native HTTP engines

SYNOPSIS

use Uniform::HTTP::FastPath;

if (Uniform::HTTP::FastPath::can_view($request)) {
    my $view = Uniform::HTTP::FastPath::view($request);
    $native_engine->send_uniform_fast($view);
}

DESCRIPTION

Uniform::HTTP::FastPath is an optional interface for native-backed HTTP implementations.

It lets an engine inspect a canonical Uniform message in one operation instead of making many Perl method calls. It can also build a canonical Request or Response from values that the engine has already validated.

Normal application code should use Uniform::HTTP::Request and Uniform::HTTP::Response. Adapters and subclasses use the normal portable Uniform API.

FastPath does not parse HTTP, serialize HTTP, perform I/O, or choose an HTTP version.

ABI

The current fast-path ABI is version 1:

Uniform::HTTP::FastPath::ABI_VERSION()   # 1

A native consumer must check the ABI version before interpreting a view. Incompatible layouts will use a new ABI version.

can_view

my $ok = Uniform::HTTP::FastPath::can_view($message);

Returns true only for exact canonical objects:

Uniform::HTTP::Message
Uniform::HTTP::Request
Uniform::HTTP::Response

Subclasses and adapters return false because their storage or behavior may be different.

view

my $view = Uniform::HTTP::FastPath::view($message);

Returns an array reference with this ABI 1 layout:

0   ABI version
1   message kind
2   flags
3   HTTP version
4   request method
5   request target
6   request scheme
7   request authority
8   request protocol
9   response status
10  response reason
11  headers
12  trailers
13  buffered body

Use the SLOT_* constants instead of hardcoded indexes when writing Perl code.

Message kinds are:

KIND_MESSAGE
KIND_REQUEST
KIND_RESPONSE

Request-only slots are undef for responses. Response-only slots are undef for requests.

FLAGS

SLOT_FLAGS can contain:

FLAG_HAS_BUFFERED_BODY
FLAG_COMPLETE
FLAG_MUTABLE
FLAG_INITIAL_MUTABLE
FLAG_BODY_MUTABLE
FLAG_TRAILERS_MUTABLE
FLAG_HEADERS_LOSSLESS
FLAG_TRAILERS_LOSSLESS
FLAG_TARGET_EXACT

These describe the canonical object at the time view() is called.

HEADERS AND TRAILERS

The header and trailer slots contain the canonical ordered arrays of [ name, value ] pairs.

These arrays are borrowed, not copied. A consumer must not modify them, and the source message must not be changed while native code is using the view.

Take a new view after changing a message.

TRUSTED CONSTRUCTION

request_from_validated

my $request =
    Uniform::HTTP::FastPath::request_from_validated($view);

response_from_validated

my $response =
    Uniform::HTTP::FastPath::response_from_validated($view);

These functions are for protocol engines that have already validated the message values.

They skip the normal per-field HTTP validation and adopt the header and trailer arrays from the view. This avoids repeating work already done by a trusted parser.

The caller must guarantee that all supplied values satisfy the normal Uniform::HTTP rules. After successful construction, the caller must not modify the adopted header or trailer arrays.

Use the normal Request or Response constructor for application input, wire data that has not been fully validated, or data from an untrusted adapter.

NATIVE HEADER

Uniform::HTTP is pure Perl. No compiler is required to install it.

XS consumers can compile uniform_http_fastpath.h as part of their own distribution. The header constructs exact canonical Message, Request, and Response objects from validated native byte spans. It can also inspect a canonical object without allocating a Perl view or making per-field Perl calls.

Find the installed header directory with:

my $include = Uniform::HTTP::FastPath::native_include_dir();

The native contract has its own version:

Uniform::HTTP::FastPath::NATIVE_ABI_VERSION()   # 1

Consumers must initialize a per-interpreter handle with uhttp_native_init. It checks the compiled header against the installed runtime. The Perl helper native_compatible(abi, layout) supports that handshake; consumers do not choose or override the header's private storage revision.

Construction copies native input bytes and requires explicit trusted opt-in. It does not validate HTTP syntax. Inspection borrows existing values only while the source is alive and unchanged. Adapters and subclasses use the portable API. No native setter or alternate message class is introduced.

The Perl FastPath ABI, including its array-adoption rules, is unchanged. See docs/NATIVE-FASTPATH.md for the C API, ownership rules, examples, and author-only conformance tests. Normal applications do not need this interface.

FALLBACK

FastPath is never required.

A native implementation should use can_view() and fall back to the normal Uniform methods when it returns false. This keeps adapters, subclasses, and pure-Perl implementations fully portable.

SECURITY

Trusted construction deliberately bypasses normal semantic validation.

Do not use request_from_validated() or response_from_validated() as general-purpose constructors. They are an interface between Uniform and a component that has already enforced the same invariants.

The ordinary public constructors remain fully validated.

VERSION

Module version 0.06. Perl and native FastPath ABI versions are both 1.

AUTHOR

Joshua S. Day <HAX@cpan.org>

LICENSE

This software is available under the MIT License.