NAME
Linux::Event::HTTP::Transaction - lifecycle of one HTTP request/response exchange
DESCRIPTION
A Transaction represents exactly one HTTP exchange: one Linux::Event::HTTP::Request and, once available, one Linux::Event::HTTP::Response.
Request and Response are HTTP message objects. Transaction owns the lifecycle that connects them, including output progress, cancellation, protocol Upgrade, CONNECT tunnel handoff, and writable body producers for outgoing messages. It does not own a socket, parser, connection pool, redirect chain, or transport output queue. Client and server connection implementations advance Transaction state and move produced bytes through their transport.
Redirects are separate HTTP exchanges and therefore use separate Transaction objects.
Applications normally receive Transactions from a Client or an active server Connection; they do not construct them directly.
METHODS
request
Returns the Request for this exchange. It is available for the entire Transaction lifetime.
response
Returns the Response after the response head has been received or created, or undef before a Response exists.
request_body
Returns the writable producer for an outgoing streaming Request body when the Client request selected incremental body production:
my $tx = $client->post(
$url,
stream_body => {
on_drain => sub ($body) { ... },
on_cancel => sub ($body) { ... },
},
);
my $body = $tx->request_body;
$body->write($bytes);
$body->complete;The producer belongs to the Transaction rather than the Request message.
response_body
Returns the writable producer for an outgoing streaming Response body. On a server, the active transaction can be obtained from the connection:
my $body = $conn->transaction->response_body(
on_drain => sub ($body) { ... },
on_cancel => sub ($body) { ... },
);
$body->write($bytes);
$body->complete;Creating the producer marks the Response body as incremental rather than a complete scalar body. The Request/Response message objects themselves do not own transport writers.
send_response
Explicitly commits and sends an already configured complete scalar Response. Ordinary server callbacks do not need this method: a scalar $res->body(...) is committed automatically after the callback returns. It is useful when a Response is completed later from another event callback:
my $tx = $conn->transaction;
$timer = Linux::Event::Kernel::Timer->new(
loop => $conn->loop,
after => 0.1,
on_timer => sub ($timer) {
$tx->response->body("later\n");
$tx->send_response;
},
);The explicit send step is what lets Response remain a transport-independent message rather than retaining a hidden Connection back-reference.
upgrade
Schedules an HTTP protocol Upgrade for this exchange. Configure the Response Upgrade header first, then request the lifecycle handoff through the Transaction:
$res->header('Upgrade', 'my-protocol');
$conn->transaction->upgrade('MyProtocolConnection');tunnel
Accepts a valid server-side HTTP/1.1 CONNECT exchange and schedules handoff of the same live stream to another Linux::Event stream class:
if ($req->method eq 'CONNECT') {
$conn->transaction->tunnel('MyTunnelConnection');
}The default Response status is 200. Applications may configure another 2xx status or additional response headers before calling tunnel. Successful CONNECT responses cannot carry an HTTP message body, Content-Length, Transfer-Encoding, or Connection: close. The Request must use authority-form host:port, have a matching Host field, and contain no HTTP message body or message-framing fields.
tunnel only completes the HTTP CONNECT handshake and transfers ownership of the accepted stream. Opening or bridging an upstream destination is application or higher-protocol policy.
is_response_started
True after response output has begun. This is exchange/output state, not a property of the Response message itself.
is_upgrading
True while a protocol Upgrade handoff is pending.
is_tunneling
True while a successful server-side CONNECT tunnel handoff is pending.
state
Returns the coarse application-visible lifecycle state. The common states are pending, active, complete, cancelled, and error. Connection implementations may track finer protocol phases privately without exposing parser or transport internals here.
cancel
Requests cancellation of this exchange. Cancellation is idempotent from the application's perspective. The current Client or Connection controller is responsible for the protocol action needed to abandon the exchange safely.
is_complete
True only after the exchange completes successfully.
is_cancelled
True after the exchange has been cancelled.
is_terminal
True for successful completion, cancellation, or error.
error
Returns the terminal error value after failure, or undef otherwise.