/ 
Unblock-HTTP3-0.01
/ Unblock::HTTP3::Connection

NAME

Unblock::HTTP3::Connection - one HTTP/3 connection over Net::QUIC

SYNOPSIS

use Unblock::HTTP3::Connection;
use Uniform::HTTP::Request;

my $h3 = Unblock::HTTP3::Connection->client(
    quic => $quic,
);

$h3->start;

my $tx = $h3->request(
    Uniform::HTTP::Request->new(
        method    => 'GET',
        target    => '/',
        scheme    => 'https',
        authority => 'example.com',
    ),
);

DESCRIPTION

One Unblock::HTTP3::Connection wraps one Net::QUIC::Connection.

Unblock::HTTP3 owns HTTP/3 connection state, control streams, QPACK integration, request streams, HTTP/3 errors, and HTTP/3 extensions. Net::QUIC owns QUIC and TLS. The event-loop adapter owns the UDP socket and timer.

Uniform::HTTP supplies common request and response semantics.

CONSTRUCTORS

client

my $h3 = Unblock::HTTP3::Connection->client(
    quic => $quic,
);

Creates client-side HTTP/3 state.

server

my $h3 = Unblock::HTTP3::Connection->server(
    quic => $quic,
);

Creates server-side HTTP/3 state.

OPTIONS

quic is required and must be a Net::QUIC::Connection.

Common options are:

send_buffer_limit

Maximum buffered HTTP/3 output bytes. The default is 4 MiB.

max_field_section_size

Maximum decoded header or trailer field-section size. The default is 65536 bytes.

max_buffered_body_bytes

Maximum body size retained in a buffered Request or Response. The default is 64 MiB.

max_streaming_body_bytes

Maximum queued incoming streaming body bytes. The default is 4 MiB.

receive_body

buffered by default. Use stream to receive bodies through Unblock::HTTP3::Body::Reader.

qpack_max_table_capacity

Local QPACK dynamic-table capacity. The default is 4096.

qpack_blocked_streams

Local QPACK blocked-stream limit. The default is 100.

enable_extended_connect

Server only. Advertises Extended CONNECT support.

enable_http_datagrams

Advertises RFC 9297 HTTP Datagram support. The Net::QUIC connection must also have QUIC DATAGRAM receive support.

datagram_request

Server-only callback used to decide whether an incoming request uses HTTP Datagrams. It receives the Connection and Request.

max_buffered_datagram_bytes

Maximum total bytes retained in Transaction Datagram queues. The default is 1 MiB.

max_buffered_datagrams

Maximum number of retained HTTP Datagrams. The default is 1024.

quic_max_bidi_streams

Server-only synchronization value for libnghttp3 request stream validation. The default is 100, matching Net::QUIC 0.04. If the QUIC server uses a different transport->{max_bidi_streams} value, pass the same value here.

extension_settings

Hash reference of additional HTTP/3 SETTINGS identifiers and values.

on_extension_settings

Callback run after peer extension SETTINGS are accepted. It receives the Connection and a hash reference of peer extension SETTINGS. Dying from the callback rejects the settings with H3_SETTINGS_ERROR.

extension_stream_handlers

Hash reference mapping extension unidirectional stream types to callbacks.

remembered_peer_settings

Client-only opaque value previously returned by peer_settings_state. Used for HTTP/3 0-RTT.

remembered_local_settings

Server-only opaque value previously returned by local_settings_state. Used to validate HTTP/3 settings when accepting 0-RTT.

METHODS

start

Starts HTTP/3 processing and creates the required control and QPACK streams.

Normally QUIC is already ready. A returning client with remembered peer SETTINGS may start while QUIC early data is pending. A server with remembered local SETTINGS may start early to parse accepted 0-RTT requests.

Returns the Connection.

request

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

Client only. Submits a Uniform::HTTP::Request or Unblock::HTTP3::Request and returns a Unblock::HTTP3::Transaction.

Useful per-request options are:

stream_body
receive_body
datagrams
early_data

stream_body configures an outgoing streaming request body.

receive_body configures streaming response receipt.

datagrams => 1 marks the request as using HTTP Datagram semantics.

early_data => 1 explicitly permits submission before the QUIC handshake finishes. 0-RTT is replayable. Unblock::HTTP3 does not retry an early request automatically if QUIC rejects it.

next_transaction

Returns the next ready Transaction, or undef when none is queued.

On a server this is a newly received request.

On a client this is an existing Transaction whose final response headers have arrived.

next_informational

Client only. Returns a Transaction which has received a new 1xx response. Retrieve the response with $tx->next_informational.

role

Returns client or server.

quic

Returns the wrapped Net::QUIC::Connection.

nghttp3_version

Returns the runtime libnghttp3 version string.

started

True after start succeeds.

failed

True after a fatal local HTTP/3 error.

error

Returns the saved error text after failed becomes true.

error_code

Returns the HTTP/3 application error code associated with error, or undef when no fatal HTTP/3 error has been recorded.

receive_body_mode

my $mode = $h3->receive_body_mode;
$h3->receive_body_mode('stream');

Gets or changes the default receive mode for future Transactions. Valid values are buffered and stream.

max_field_section_size

Returns the configured field-section limit.

max_buffered_body_bytes

Returns the configured buffered-body limit.

max_streaming_body_bytes

Returns the configured queued streaming-body limit.

qpack_max_table_capacity

Returns the configured QPACK table capacity.

qpack_blocked_streams

Returns the configured QPACK blocked-stream limit.

extended_connect_enabled

True when this server advertises Extended CONNECT support.

peer_extended_connect_enabled

True when the peer advertised Extended CONNECT support.

http_datagrams_enabled

True when this endpoint advertises SETTINGS_H3_DATAGRAM.

peer_http_datagrams_enabled

True when the peer advertised SETTINGS_H3_DATAGRAM.

can_send_http_datagrams

True when HTTP Datagrams are negotiated and Net::QUIC currently permits QUIC DATAGRAM transmission.

can_receive_http_datagrams

True when HTTP Datagrams are negotiated and local QUIC DATAGRAM receive support is active.

datagram_receive_drops

Returns the number of incoming HTTP Datagram payloads dropped because bounded Transaction receive queues were full.

local_settings_state

Returns an opaque byte string representing this endpoint's advertised HTTP/3 SETTINGS. Store it without modifying it.

peer_settings_state

Returns an opaque byte string representing the current peer HTTP/3 SETTINGS after peer_settings_received becomes true. Before that it returns undef.

A client should save this with Net::QUIC's early-data state from the same connection when it intends to attempt 0-RTT later.

using_remembered_peer_settings

True while a returning client is still using remembered server SETTINGS before the new server SETTINGS frame arrives.

peer_settings_received

True after the peer SETTINGS frame has been accepted.

early_data_status

Returns Net::QUIC's early-data status:

none
pending
accepted
rejected

Calling this method also applies any required HTTP/3 rollback after QUIC rejects early data.

extension_settings

Returns a copy of the local extension SETTINGS.

extension_setting

my $value = $h3->extension_setting($id);
$h3->extension_setting($id, $value);

Gets or sets one extension SETTING. Values may only be changed before start.

Core, HTTP/3-reserved, and GREASE setting identifiers cannot be assigned extension semantics.

peer_extension_settings

Returns a copy of peer extension SETTINGS.

peer_extension_setting

my $value = $h3->peer_extension_setting($id);

Returns one peer extension SETTING, or undef if it was not advertised.

extension_stream_handler

$h3->extension_stream_handler(
    $type,
    sub {
        my ($connection, $stream) = @_;
        ...
    },
);

Registers one incoming extension unidirectional stream handler before start.

open_extension_stream

my $stream = $h3->open_extension_stream($type);

Opens an outgoing HTTP/3 extension unidirectional stream.

Returns Unblock::HTTP3::Extension::Stream, or undef when QUIC unidirectional stream credit is exhausted.

shutdown_notice

Sends the first graceful HTTP/3 shutdown notice. Returns the Connection.

shutdown

Begins final graceful HTTP/3 shutdown. Returns the Connection.

The application or event-loop adapter decides how long to allow between shutdown_notice and shutdown.

shutdown_notice_sent

True after the first graceful shutdown notice has been submitted.

shutdown_started

True after final graceful shutdown has started.

remote_shutdown_id

Returns the most recent shutdown identifier received from the peer, or undef before the peer begins graceful shutdown.

drained

Server only. True when graceful shutdown has no request streams left to process.

NOTES

Unblock::HTTP3 does not own the event loop. Network and timer activity continue to be driven through Net::QUIC.

HTTP/3 Server Push is not exposed because the libnghttp3 version used by this release does not implement it.

SEE ALSO

Unblock::HTTP3, Unblock::HTTP3::Transaction, Unblock::HTTP3::Request, Unblock::HTTP3::Response, Net::QUIC, Uniform::HTTP

AUTHOR

Joshua S. Day

LICENSE

This software is available under the MIT License.