/ 
Unblock-HTTP3-0.03
/ Unblock::HTTP3::Transaction

NAME

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

SYNOPSIS

my $tx = $h3->request($request);

my $request  = $tx->request;
my $response = $tx->response;

if ($tx->is_terminal) {
    ...
}

DESCRIPTION

A Transaction represents one HTTP/3 request stream.

It keeps the Request, final Response, streaming body objects, informational responses, Datagram state, priority, and lifecycle state together. Applications normally do not need to match responses with raw QUIC stream IDs.

METHODS

stream_id

Returns the HTTP/3 request stream ID.

request

Returns the Uniform::HTTP::Request associated with this Transaction.

response

Returns the final Uniform::HTTP::Response when one is available.

On a server, the Transaction receives a mutable Response when the request is created.

local_reset_code

Returns the RESET_STREAM application error code explicitly requested by the local HTTP/3 layer for this request stream, or undef when none was requested.

A peer STOP_SENDING can cause QUIC itself to send the required RESET_STREAM. That transport-generated response is not reported here. The peer request is reported by "remote_stop_sending_code".

remote_reset_code

Returns the RESET_STREAM application error code received from the peer for this request stream, or undef when none has been received.

local_stop_sending_code

Returns the STOP_SENDING application error code sent locally for this request stream, or undef when none has been sent.

remote_stop_sending_code

Returns the STOP_SENDING application error code received from the peer for this request stream, or undef when none has been received.

is_aborted

True when any local or remote RESET_STREAM or STOP_SENDING code has been recorded for the Transaction.

These are HTTP/3 transport diagnostics. They are intentionally kept on the Transaction instead of the canonical Uniform Request or Response objects.

protocol

Returns the Extended CONNECT protocol identifier, or undef for an ordinary request or basic CONNECT tunnel.

is_extended_connect

True when the request is Extended CONNECT.

early_data

True when this Transaction's request was carried in QUIC 0-RTT.

0-RTT can be replayed and must be treated accordingly by the application.

priority

my $priority = $tx->priority;

$tx->priority(
    urgency     => 0,
    incremental => 1,
);

Gets or changes the live RFC 9218 priority.

Urgency is 0 through 7, where 0 is most urgent. Incremental is 0 or 1.

On a client, changing priority sends PRIORITY_UPDATE. On a server, it changes the local response scheduling priority.

request_body

Returns the request body stream object when the Transaction is configured for streaming.

On a client this is a writable Unblock::HTTP3::Body::Stream.

On a server this is a readable Unblock::HTTP3::Body::Reader.

response_body

Returns the response body stream object when the Transaction is configured for streaming.

On a server this is a writable Unblock::HTTP3::Body::Stream.

On a client this is a readable Unblock::HTTP3::Body::Reader.

send_response

Server only. Sends the final buffered or bodyless Response.

For a streaming response body, use response_body instead.

send_informational

$tx->send_informational(
    Uniform::HTTP::Response->new(
        status => 103,
    ),
);

Server only. Sends a 1xx response before the final Response. Status 101 is not used by HTTP/3.

next_informational

Client only. Returns the next received informational Response, or undef.

is_response_started

True after final response headers have started sending.

capsules

my $capsules = $tx->capsules;

Creates or returns a Unblock::HTTP3::Capsule::Stream for an Extended CONNECT Transaction.

The higher-level protocol is responsible for deciding whether Capsule Protocol use has been negotiated.

datagrams_enabled

True when this Transaction has HTTP Datagram semantics.

send_datagram

my $accepted = $tx->send_datagram($bytes);

Sends one RFC 9297 HTTP Datagram.

A false return means the unreliable payload was not accepted for transmission. The caller decides whether to retry or drop it.

next_datagram

Returns the next queued HTTP Datagram payload, or undef.

on_datagram

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

Installs or replaces the receive callback. Passing undef removes it.

Queued Datagrams are drained to a newly installed callback.

max_datagram_payload_size

Returns the current maximum HTTP Datagram payload size for this Transaction. Returns zero when a Datagram cannot currently be sent.

cancel

Cancels the request stream with H3_REQUEST_CANCELLED. Returns the Transaction.

state

Returns one of:

active
complete
cancelled
error

error

Returns the Transaction error text when state is error.

is_complete

True when state is complete.

is_cancelled

True when state is cancelled.

is_terminal

True when the Transaction is complete, cancelled, or in error.

SEE ALSO

Unblock::HTTP3::Connection, Uniform::HTTP::Request, Uniform::HTTP::Response, Unblock::HTTP3::Body::Stream, Unblock::HTTP3::Body::Reader, Unblock::HTTP3::Capsule::Stream

AUTHOR

Joshua S. Day

LICENSE

This software is available under the MIT License.