/ 
Unblock-HTTP3-0.13
/ Unblock::HTTP3::Server

NAME

Unblock::HTTP3::Server - one non-blocking HTTP/3 server connection

SYNOPSIS

use Unblock::HTTP3::Server;

# $quic is one accepted, ready Net::QUIC::Connection.
my $server = Unblock::HTTP3::Server->new(
    quic => $quic,
    on_request => sub {
        my ($tx, $request) = @_;
        $tx->respond(status => 200, body => "hello\n");
    },
);

$server->start;

DESCRIPTION

One Server manages one HTTP/3 connection over an existing Net::QUIC connection. A single server UDP socket may serve multiple QUIC connections, each with its own Unblock::HTTP3::Server instance.

The event loop owns the UDP socket and timer. Net::QUIC::Driver owns the QUIC transport. This class owns HTTP/3 state, including QPACK and request stream handling.

The application sees canonical Uniform::HTTP::Request objects. It does not need to build Uniform response objects manually for common replies.

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 $server = Unblock::HTTP3::Server->new(
    quic       => $quic,
    on_request => sub { ... },
);

quic must be a Net::QUIC::Connection. The callback-style application normally supplies on_request. Users of the pull API may omit it.

Connection options 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, quic_max_bidi_streams, enable_extended_connect, enable_http_datagrams, origins, remembered_local_settings, and extension options.

REQUEST CALLBACKS

on_request($tx, $request)

Called when request headers arrive. The request body may still be arriving.

on_body($tx, $request, $bytes)

Called for incoming request body chunks. Supplying on_body selects streaming request-body reception automatically.

on_request_end($tx, $request)

Called when the request body and trailers have completed. This callback does not independently force streamed or buffered body reception.

on_error($tx, $error, $error_code)

Called when a Transaction fails, with the available HTTP/3 or stream code.

receive_body selects the default body ownership model. Without an on_body callback and with the default buffered mode, the Uniform request body becomes available as a complete buffer at message end.

RESPONDING

respond

Inside an on_request callback, call:

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

Or pass an existing Uniform-compatible Response object:

$tx->respond($uniform_response);

The named form constructs a canonical Uniform::HTTP::Response for you. respond() sends a final response. It can only be called once for a Transaction.

send_informational

$tx->send_informational(status => 103);

Sends a 1xx response before the final response. Status 101 is not valid in HTTP/3. A Uniform Response object is also accepted.

STREAMING RESPONSES

Start an outgoing response body with stream_body => 1:

$tx->respond(
    status      => 200,
    stream_body => 1,
    on_drain    => sub {
        my ($tx) = @_;
        # Resume sending once output pressure has eased.
    },
);

$tx->write("first part");
$tx->end("last part");

write() adds outbound body data. end() sends the last data and finishes the sending side. Consult Unblock::HTTP3::Transaction for advanced body readers/writers, cancellation and reset information.

CONNECTION METHODS

start

Starts HTTP/3 processing and installs the QUIC stream callbacks. For ordinary 1-RTT operation, call after $quic->ready is true.

next_transaction

Returns the next newly received request Transaction for pull-style users. Pull-only requests remain strongly queued until retrieved. When on_request also delivers the Transaction, its queue notification is weak. A mixed callback/pull consumer may retrieve the live Transaction, but should keep the callback's Transaction reference if it needs it after the request becomes terminal and the native stream closes. Callback-only servers do not retain all completed request bodies through this optional pull queue.

quic

Returns the underlying Net::QUIC::Connection.

started

True if HTTP/3 has started.

failed

True if HTTP/3 has encountered a fatal connection error.

error

The HTTP/3 connection error message, if any.

error_code

The corresponding HTTP/3 error code, if any.

SHUTDOWN AND ADVANCED FEATURES

The Server inherits HTTP/3 graceful shutdown, extension streams, settings, priority, Capsules, Extended CONNECT, and HTTP Datagrams from Unblock::HTTP3::Connection. QUIC itself is managed by Net::QUIC.

Each accepted QUIC connection needs its own Server object. Keep it alive until that QUIC connection closes. See Unblock::HTTP3::Integration and the complete Linux::Event server example for this lifecycle.

SEE ALSO

Unblock::HTTP3::Integration, Unblock::HTTP3::Client, Unblock::HTTP3::Transaction, Uniform::HTTP::Response, Net::QUIC::Driver

LICENSE

MIT License.