NAME
Unblock::HTTP3::Client - one non-blocking HTTP/3 client connection
SYNOPSIS
use Unblock::HTTP3::Client;
# $quic is a ready Net::QUIC::Connection.
my $client = Unblock::HTTP3::Client->new(quic => $quic);
$client->start;
my $tx = $client->request(
method => 'GET',
target => '/',
scheme => 'https',
authority => 'localhost',
on_response => sub {
my ($tx, $response) = @_;
print $response->status, "\n";
},
on_body => sub {
my ($tx, $response, $bytes) = @_;
print $bytes;
},
on_complete => sub {
my ($tx) = @_;
print "complete\n";
},
on_error => sub {
my ($tx, $error, $code) = @_;
warn "HTTP/3 request failed: $error\n";
},
);DESCRIPTION
One Client owns HTTP/3 protocol state on one existing Net::QUIC connection. Several Transactions can run at once on the same connection.
This class does not open UDP sockets, perform TLS handshakes, choose timers, or run an event loop. Use Unblock::HTTP3::Integration to connect an event framework through Net::QUIC::Driver.
HTTP/3 response messages are canonical Uniform::HTTP::Response objects.
RECEIVE BODY OPTIONS
receive_body accepts buffered or stream. Buffering remains the default. max_buffered_body_bytes is a positive byte limit, defaulting to 64 MiB. Zero does not mean unlimited. Buffered reception installs the body on the same Uniform message before freezing it and invoking the body-completion callback. Empty completed bodies have an empty string representation. The engine releases retained chunks on failure or cancellation.
Select streaming per transaction with $tx->on_data(...) during the header callback. Legacy on_body still selects streaming automatically. Do not combine on_data and on_body. See "RECEIVE AND FINISH CALLBACKS" in Unblock::HTTP3::Transaction.
A buffer limit failure resets only the affected stream. It does not call successful body completion.
CONSTRUCTOR
new
my $client = Unblock::HTTP3::Client->new(
quic => $quic,
);quic is required and must be a Net::QUIC::Connection.
An optional on_request_available => sub { ... } callback receives this same Client after a prior request() returned undef because QUIC could not open a bidirectional stream, and a later QUIC bidi availability event occurs. The callback is a one-shot hint, not reserved stream credit; try the unsubmitted request again from a later event-loop turn. No notification occurs for unidirectional stream events or normal traffic. This callback is not an automatic retry mechanism.
Useful optional constructor settings include receive_body, send_buffer_limit, max_field_section_size, max_buffered_body_bytes, max_streaming_body_bytes, qpack_max_table_capacity, qpack_blocked_streams, enable_http_datagrams, and remembered_peer_settings.
The connection can be created before QUIC is ready, but for ordinary 1-RTT operation call start() only after $quic->ready is true.
REQUESTS
request
my $tx = $client->request(
method => 'GET',
target => '/resource',
scheme => 'https',
authority => 'example.com',
on_response => sub { ... },
);Returns an Unblock::HTTP3::Transaction when a request stream is admitted, or undef if QUIC has no local bidirectional stream credit. No request is submitted or frozen in the latter case, and an optional on_request_available callback can signal when trying again may work. Request fields are used to construct a canonical Uniform::HTTP::Request. The existing object form is also accepted:
my $tx = $client->request(
$uniform_request,
on_response => sub { ... },
);Object identity is retained for the object form. HTTP/3 validates request semantics, pseudo-headers and any explicit protocol version.
The following keys are request options, not Uniform message fields:
stream_body
receive_body
datagrams
early_data
on_informational
on_response
on_body
on_complete
on_error
on_drainstream_body => 1 starts an outbound streaming request body. Do not combine it with an already-buffered request body.
my $tx = $client->request(
method => 'POST', target => '/upload', scheme => 'https',
authority => 'example.com', stream_body => 1,
);
$tx->write("first chunk");
$tx->end("final chunk");An on_body callback automatically selects streaming response delivery. Without it, received response bodies are buffered on the Uniform message, unless receive_body explicitly selects streaming mode. The advanced receive_body hash form configures a Body::Reader.
REQUEST CALLBACKS
on_informational($tx, $response)-
Called for 1xx response headers before a final response. HTTP/3 does not use status 101.
on_response($tx, $response)-
Called when final response headers arrive. The response body may still be incomplete at that point.
on_body($tx, $response, $bytes)-
Called for incoming response body chunks in streaming mode.
on_complete($tx)-
Called when the HTTP/3 Transaction has completed.
on_error($tx, $error, $error_code)-
Called when a Transaction fails. The numeric code is an HTTP/3 or stream diagnostic when one is available.
on_drain($tx)-
Used with
stream_body => 1. Called when outbound body production can resume after backpressure.
An application may also use the advanced pull and Body::Reader interfaces instead of the common callback style.
CONNECTION METHODS
start
Starts HTTP/3 control streams and installs the QUIC stream-activity handlers. For ordinary requests, the Net::QUIC connection must be ready first.
next_transaction
Pulls the next Transaction available from the engine. Pull-only Transactions stay strongly queued until retrieved. When a response is also delivered through on_response, on_complete, on_body, on_data, or on_finish, its pull notification is weak: keep the Transaction received from the callback if it must survive beyond its terminal lifecycle. Callback delivery does not accumulate completed Transactions and bodies in a second strong queue. The callback API does not require polling; mixed callers can still pull a live Transaction.
next_informational
Pulls the next informational-response notification when using the low-level polling interface.
quic
Returns the underlying Net::QUIC::Connection.
started
True once HTTP/3 has started.
failed
True if the HTTP/3 connection has failed.
error
Returns the HTTP/3 connection failure message, if any.
error_code
Returns the associated failure code, if any.
HTTP/3 FEATURES
HTTP Datagrams, Capsules, Extended CONNECT, priorities, and 0-RTT are supported through the connection or Transaction objects. Request 0-RTT requires an explicit early_data => 1 and compatible remembered settings. Early requests can be replayed; retries are not automatic.
See Unblock::HTTP3::Connection for settings, shutdown, ORIGIN and extension controls. See Unblock::HTTP3::Transaction for request-stream state.
SEE ALSO
Unblock::HTTP3::Integration, Unblock::HTTP3::Server, Unblock::HTTP3::Transaction, Uniform::HTTP::Request, Net::QUIC::Driver
LICENSE
MIT License.