NAME
Linux::Event::HTTP::Transaction - one HTTP request/response exchange
DESCRIPTION
A Transaction represents exactly one HTTP exchange:
one Request + one Response + exchange lifecycleThis definition is the same for HTTP/1 and HTTP/2. An HTTP/2 connection may have many Transactions active at once because each stream is a separate exchange.
Request and Response are message objects. Transaction owns the lifecycle that connects them: streaming body producers, cancellation, delayed response send, and HTTP/1 Upgrade/CONNECT handoff.
A Transaction does not own the socket, connection pool, redirect chain, or transport output queue.
Applications normally receive Transactions from Linux::Event::HTTP::Client or from an active server connection.
METHODS
request
Returns the Request for this exchange.
response
Returns the Response once one exists, or undef beforehand.
request_body
Returns the writable producer for an outgoing streaming Request body.
my $body = $operation->request_body;
$body->write($bytes);
$body->complete;The producer belongs to the Transaction, not to Request.
response_body
Creates or returns the writable producer for an outgoing streaming Response:
my $body = $conn->transaction->response_body(
on_drain => sub ($body) { ... },
on_cancel => sub ($body) { ... },
);
$body->write($bytes);
$body->complete;send_response
Explicitly sends a complete scalar server Response that was finished after the original HTTP callback returned.
Ordinary responses completed during on_request, on_body, or on_request_end do not need this call.
upgrade
Schedules an HTTP/1.1 Upgrade handoff:
$res->header('Upgrade', 'my-protocol');
$conn->transaction->upgrade('MyProtocolConnection');The same live Linux::Event stream is transitioned after the HTTP exchange reaches the required boundary.
tunnel
Accepts a valid server-side HTTP/1.1 CONNECT exchange and schedules handoff of the same live stream:
$conn->transaction->tunnel('MyTunnelConnection');Opening or bridging the upstream destination remains application policy.
is_response_started
True after response output has begun.
is_upgrading
True while an HTTP/1 Upgrade handoff is pending.
is_tunneling
True while an HTTP/1 CONNECT handoff is pending.
state
Returns the coarse lifecycle state: pending, active, complete, cancelled, or error.
cancel
Requests cancellation. Application-visible cancellation is idempotent; the active protocol executor chooses the correct wire action.
is_complete
True after successful exchange completion.
is_cancelled
True after cancellation.
is_terminal
True after success, cancellation, or error.
error
Returns the terminal error value after failure, or undef otherwise.
SEE ALSO
Linux::Event::HTTP::Request, Linux::Event::HTTP::Response, Linux::Event::HTTP::Client::Operation, Linux::Event::HTTP::Body::Stream.