/ 
Net-QUIC-0.01
/ Net::QUIC::Connection

NAME

Net::QUIC::Connection - one QUIC connection

SYNOPSIS

A client Connection normally comes from Net::QUIC::Driver:

my $connection = $driver->connection;

Wait for the QUIC/TLS handshake:

return if !$connection->ready;

Open a bidirectional stream:

my $stream = $connection->open_bidi_stream;

if ($stream) {
    $stream->send("hello");
    $stream->finish;
}

Accept streams opened by the peer:

while (my $stream = $connection->next_stream) {
    ...
}

Close the Connection normally:

$connection->close;

DESCRIPTION

Net::QUIC::Connection represents one QUIC connection.

Application protocol code normally works with Connection and Net::QUIC::Stream. UDP socket and timer integration normally stays in Net::QUIC::Driver.

A client Driver owns one Connection. A server Driver can expose many Connections through next_connection.

Connection objects are created by Driver or Net::QUIC::Endpoint. Direct native construction is private.

HANDSHAKE READINESS

ready

if ($connection->ready) {
    ...
}

Returns true after the QUIC cryptographic handshake has completed.

A server Connection may be returned before this becomes true.

Application work that requires an established connection should wait for ready.

OPENING STREAMS

open_bidi_stream

my $stream = $connection->open_bidi_stream;

Opens a local bidirectional stream and returns a Net::QUIC::Stream.

Both endpoints can send application bytes on a bidirectional stream.

Returns undef when the peer's current bidirectional stream limit has been reached.

That is normal QUIC flow control. It does not mean the Connection failed.

Other failures still throw an exception.

open_uni_stream

my $stream = $connection->open_uni_stream;

Opens a local unidirectional stream.

This endpoint can send application bytes on the stream but cannot receive application bytes from it.

Returns undef when the peer's current unidirectional stream limit has been reached.

Other failures still throw an exception.

on_stream_available

$connection->on_stream_available(sub {
    my ($connection, $type) = @_;

    return if $type ne 'bidi';

    my $stream = $connection->open_bidi_stream;
    return if !defined $stream;

    ...
});

Registers a callback for stream-limit recovery.

Use it when open_bidi_stream or open_uni_stream returned undef and the application wants to continue when the peer later grants more stream credit.

$type is:

bidi

or:

uni

The callback runs outside ngtcp2's internal callback stack, so opening a stream from it is safe.

Pass undef to remove the callback:

$connection->on_stream_available(undef);

PEER-CREATED STREAMS

next_stream

while (my $stream = $connection->next_stream) {
    ...
}

Returns the next stream opened by the peer, or undef when no new incoming stream is waiting.

The returned object is a Net::QUIC::Stream.

CLOSING

close

$connection->close;

or:

$connection->close($application_error_code);

Starts a normal QUIC application-level Connection close.

The application error code defaults to zero.

Calling close again while the Connection is already closing is harmless.

close does not immediately destroy the object. QUIC has a closing/draining period during which late packets still need network and timer service.

When the Connection belongs to a Driver, Driver automatically services the close packet and timeout changes.

closed

if ($connection->closed) {
    ...
}

Returns true after the Connection has completely finished its QUIC closing or draining period and no longer needs network or timer service.

close_info can become available before closed becomes true.

CLOSE AND ERROR INFORMATION

close_info

my $info = $connection->close_info;

Returns undef while no Connection close or failure has been recorded.

Once a close or failure is known, returns a small hash reference.

The common fields are:

type
initiator
code

type is one of:

application
transport
tls
certificate
handshake
idle
drop

initiator is:

local

or:

peer

code is the application error code, QUIC transport error code, or TLS alert code as appropriate.

For example, a normal peer application close can be:

{
    type      => 'application',
    initiator => 'peer',
    code      => 0,
}

frame_type is included when a peer transport close identifies the QUIC frame that caused the error.

native_error is included for failures detected locally by ngtcp2.

TLS certificate verification failures use:

type => 'certificate'

Other TLS failures use:

type => 'tls'

Handshake timeout uses:

type => 'handshake'

Local API misuse, invalid configuration, allocation failure, and internal implementation failures still throw Perl exceptions. Those are local programming or system failures rather than ordinary remote Connection outcomes.

DRIVER NOTIFICATION

Connections obtained through Net::QUIC::Driver are privately connected back to that Driver.

State-changing application calls such as stream send/finish/reset, data consumption, and Connection close can therefore cause QUIC output and timer changes to be serviced automatically.

Application code does not need to call a separate pump or service method.

SEE ALSO

Net::QUIC

Net::QUIC::Driver

Net::QUIC::Stream

Net::QUIC::Endpoint