/ 
Unblock-HTTP3-0.13
/ Unblock::HTTP3::Transaction

NAME

Unblock::HTTP3::Transaction - one HTTP/3 request and response transaction

RECEIVE AND FINISH CALLBACKS

$tx->on_data(sub {
    my ($tx, $bytes) = @_;
    consume_chunk($bytes);
});

Register during the incoming-header callback (server on_request or client on_response). This selects streaming for this transaction. Only decoded HTTP body bytes are passed; content encodings such as gzip are not decoded. No full body is accumulated. Registering after body delivery starts or ends, registering twice, or combining this callback with on_body is an error. Client request() also accepts on_data before the request is dispatched.

$tx->on_finish(sub {
    my ($tx) = @_;
    record_outcome($tx->state, $tx->error);
});

Runs once after the applicable completion or error callbacks for a terminal complete, cancelled, or error transaction. The state is committed before the callback. Cancellation alone does not call on_error. A completed incoming request can still have an unfinished response; it is not terminal until both sides required by the engine have finished.

Client request() also accepts on_finish. Register it before the transaction becomes terminal. Duplicate and late registration are errors. An exception from this terminal observer is ignored so cleanup and other transactions can continue. Earlier callbacks keep the engine's exception policy, but cannot suppress this notification.

DESCRIPTION

A Transaction represents one HTTP request/response exchange carried by one HTTP/3 request stream.

request() returns the Uniform request. response() returns the final Uniform response when one is available.

COMMON API

The application-facing API intentionally matches the other Unblock HTTP engines:

respond
write
end
send_informational

A server sends a final response with named fields:

$transaction->respond(status => 200, body => "hello\n");

An existing Uniform-compatible Response object is also accepted:

$transaction->respond($response);

For a streaming response:

$transaction->respond(
    $response,
    stream_body => 1,
);

$transaction->write($chunk);
$transaction->end($last_chunk);

A client request opened with stream_body => 1 uses the same write() and end() methods.

send_informational(status => 103) sends a server-side 1xx response before the final response. It also accepts a Uniform-compatible Response object. HTTP/3 does not use status 101.

ADVANCED BODY API

request_body() and response_body() expose Unblock::HTTP3::Body::Stream or Unblock::HTTP3::Body::Reader when explicit HTTP/3 body control is needed.

The common Transaction methods are a convenience layer over those body objects, not a replacement for them.

STATE

Useful lifecycle methods are:

state
error
is_complete
is_cancelled
is_error
is_terminal

state() returns active, complete, cancelled, or error.

HTTP/3 STATE

stream_id() returns the HTTP/3 request stream ID.

priority() gets or changes RFC 9218 priority state.

local_reset_code(), remote_reset_code(), local_stop_sending_code(), and remote_stop_sending_code() preserve HTTP/3 stream diagnostics.

is_aborted() is true when any RESET_STREAM or STOP_SENDING condition has been recorded.

protocol() and is_extended_connect() expose Extended CONNECT state.

early_data() reports whether the request used QUIC 0-RTT.

INFORMATIONAL RESPONSES

next_informational() returns the next queued informational Response for users of the pull interface.

CAPSULES AND DATAGRAMS

capsules() returns the generic RFC 9297 Capsule stream for an Extended CONNECT Transaction.

HTTP Datagram methods include:

datagrams_enabled
send_datagram
next_datagram
on_datagram
max_datagram_payload_size

CANCELLATION

cancel() cancels the HTTP/3 request stream with H3_REQUEST_CANCELLED.

SEE ALSO

Unblock::HTTP3, Unblock::HTTP3::Client, Unblock::HTTP3::Server, Unblock::HTTP3::Body::Stream, Unblock::HTTP3::Body::Reader

LICENSE

MIT License.