/ 
Unblock-HTTP-0.02
/ Unblock::HTTP::QUIC

NAME

Unblock::HTTP::QUIC - Manage HTTP/3 connections above Net::QUIC::Driver

DESCRIPTION

This is the small, event-loop-neutral HTTP/3 connection manager. It uses Net::QUIC::Driver for packet processing and timer management. The host still owns one UDP socket and one replaceable timer. The manager attaches ready server connections to one reusable Server definition and starts client sessions when QUIC is ready. It retains each HTTP/3 session until its QUIC connection closes.

It does not create a UDP socket, negotiate transport addresses, or provide a general user agent. It does not run an extra packet pump.

SERVER

use Unblock::HTTP::QUIC;
use Unblock::HTTP::Server;

my $server = Unblock::HTTP::Server->new(
    http3 => {},
    on_request => sub {
        my ($tx, $request) = @_;
        $tx->respond(status => 200, body => "hello\n");
    },
);

my $http = Unblock::HTTP::QUIC->server(
    certificate_file => $cert,
    private_key_file => $key,
    server => $server,
    send => sub { my ($datagram) = @_; ... },
    set_timeout => sub { my ($seconds) = @_; ... },
);

$http->start;

Forward UDP and timer events:

$http->receive($bytes, $packed_local, $packed_peer);
$http->timeout;
$http->writable;

No code is required to pull new QUIC connections, check handshake readiness, or create per-connection HTTP/3 Servers.

CLIENT

my $http = Unblock::HTTP::QUIC->client(
    local => $packed_local,
    peer => $packed_peer,
    server_name => 'example.test',
    send => sub { ... },
    set_timeout => sub { ... },
    on_ready => sub {
        my ($client, $manager) = @_;
        $client->request(
            method => 'GET', target => '/', scheme => 'https',
            authority => 'example.test', on_response => sub { ... },
        );
    },
);

$http->start;

on_ready fires once per ready QUIC connection. On a server manager it receives the actual HTTP3 Server engine and the manager. On a client manager it receives the actual HTTP3 Client engine and manager. The shared multi-origin Client uses connect_quic instead; this helper remains a low-level Net::QUIC::Driver convenience.

METHODS

start, receive, timeout, writable

Forwarded to Net::QUIC::Driver. receive takes one UDP payload plus its concrete packed local and remote addresses and optionally ECN. timeout is called on expiration of the single timer specified by set_timeout. writable is for recovery after UDP send congestion.

session, sessions

session returns the ready HTTP client on a client manager, or undef until its handshake finishes. sessions returns active ready HTTP engines on the server side and unified sessions on the client side.

driver

Returns the underlying Net::QUIC::Driver for advanced transport control.

OPTIONS

Normal Net::QUIC::Driver client or server options are accepted, including send and set_timeout. ALPN is fixed to h3. A server manager requires server => $server_definition with HTTP/3 enabled. Configure HTTP engine options and callbacks on that definition; the manager never overrides them. A client manager still accepts extra engine options in http3.

This checkpoint retains the scan of all connections after Driver events. It does not yet claim constant-cost lifecycle coordination at high concurrency.

LICENSE

MIT License.