NAME

Linux::Event::HTTP::Server::Connection - HTTP/1 connection protocol state

DESCRIPTION

Linux::Event::HTTP::Server::Connection owns HTTP/1 request boundaries, request sequencing, response serialization, persistence policy, and the mapping between a streaming response body and Linux::Event transport backpressure. Linux::Event continues to own the socket, TLS transport, readiness, and native ordered-byte output queue.

Each active exchange is represented by one Linux::Event::HTTP::Transaction containing the Request and Response. The existing server callback API remains on_request($conn, $req, $res); the active Transaction is available through $conn->transaction when lifecycle, streaming-body, Upgrade, or CONNECT tunnel operations are needed.

Response message completion and server output completion are intentionally separate. Response->is_complete describes the message body; Transaction tracks whether response output has started or finished before the Connection advances to a pipelined request.

TRANSACTION

transaction returns the currently active HTTP Transaction, or undef when no exchange is active on the connection. During on_request, on_body, and on_request_end it refers to the Transaction containing the supplied Request and Response.

For a valid server-side HTTP/1.1 CONNECT request, $conn->transaction->tunnel($class) accepts the tunnel and schedules handoff of the same live stream object to the target Linux::Event stream class after the successful response head is queued. Rejecting CONNECT requires no special API: configure an ordinary non-2xx Response instead.

RESPONSE BODIES

A complete scalar body is configured on the Response:

$res->header('Content-Type', 'text/plain');
$res->body("hello\n");

When configured during an HTTP callback, the scalar body is sent automatically after that callback returns. For a Response completed later from another event, explicitly tell the Transaction to send the now-complete message:

my $tx = $conn->transaction;
$tx->response->body("later\n");
$tx->send_response;

A streaming body is produced through the active Transaction:

my $body = $conn->transaction->response_body(
    on_drain  => sub ($body) { ... },
    on_cancel => sub ($body) { ... },
);

$body->write($bytes);
$body->complete;

The writable producer belongs to the Transaction, not the Response message. It does not maintain a second output queue. write feeds the existing Linux::Event ordered-byte destination. Its false return preserves the normal high-watermark contract, and on_drain is driven by the connection's native drain transition. on_cancel runs if the connection disappears before the producer completes.

on_data is reserved by this HTTP connection implementation. Connection-level on_drain and on_close callbacks or subclass methods remain supported; HTTP composes its body-stream bookkeeping with those lifecycle callbacks rather than replacing them.

REQUEST BODY STREAMING

on_request runs after the validated request head is available. on_body receives decoded request-body bytes. on_request_end runs when the complete request input boundary has been consumed. The Request's is_complete state is updated at that boundary. If no response body has been sent by then, input pauses so a later asynchronous callback may finish configuring the Response without allowing the next request to overtake it.

SEE ALSO

Linux::Event::HTTP::Server, Linux::Event::HTTP::Transaction, Linux::Event::HTTP::Request, Linux::Event::HTTP::Response, Linux::Event::HTTP::Body::Stream, Linux::Event::IO::Sock::Stream.