NAME

Unblock::HTTP2::Server - one HTTP/2 server connection

SYNOPSIS

use Unblock::HTTP2::Server;

# $stream is an accepted connection owned by your event framework.
my $server = Unblock::HTTP2::Server->new(
    transport  => $stream,
    on_request => sub {
        my ($tx, $request) = @_;
        $tx->respond(
            status => 200,
            body   => "Hello World!\n",
        );
    },
);

# In the framework's read callback:
$server->input($received_http2_bytes);

The framework stream implements unblock_send(), unblock_finish(), and unblock_abort(). The Server automatically hands outgoing frames to the framework. A separate Server is created for each accepted connection, and each Server may handle many concurrent Transactions.

See Unblock::HTTP2::Integration and examples/linux-event-server.pl for complete adapter examples.

DESCRIPTION

A Server owns one HTTP/2 server session.

It does not create a listening socket, own an accepted socket, perform TLS, or run an event loop.

An optional attached framework host receives wire output automatically. Without one, drain output() while want_write() is true. See Unblock::HTTP2::Integration.

RECEIVE BODY OPTIONS

receive_body accepts buffered or stream. Streaming 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. Do not combine buffered mode with legacy on_body. Do not combine on_data and on_body. See "RECEIVE AND FINISH CALLBACKS" in Unblock::HTTP2::Transaction.

A buffer limit failure resets only the affected stream. It does not call successful body completion.

CONSTRUCTOR

new() accepts an initial settings hash, max_concurrent_streams, max_header_list_size, enable_connect_protocol, and an optional transport object with unblock_send(), unblock_finish(), and unblock_abort() methods.

Connection callbacks are:

on_settings($server, $peer_settings, $changed_settings)
on_settings_ack($server, $acked_settings)
on_ping($server, $opaque)
on_ping_ack($server, $opaque)
on_priority($server, $stream_id, $field_value)
on_invalid_frame($server, $frame, $lib_error_code)

REQUEST CALLBACKS

Request callbacks are:

on_request($transaction, $request)
on_body($transaction, $request, $bytes)
on_request_end($transaction, $request)
on_error($transaction, $error, $error_code)

on_request runs when the request headers have been accepted. on_request_end runs after the complete request and any trailers have arrived. $error_code can be undefined when there is no HTTP/2 reset code. $transaction can be undefined for an error that occurs before a Transaction exists.

Use send_informational() for informational responses and respond() for the final response. Both accept named response fields as well as canonical Uniform::HTTP::Response objects.

CONNECTION CONTROL

The Server exposes the common connection methods:

is_closed
close_reason
transaction_count
transaction_for_stream_id
local_settings
local_setting
peer_settings
peer_setting
update_settings
settings_pending
ping
draining
drain
goaway
local_goaway
peer_goaway
want_read
want_write
input
output
input_eof
transport_error
resume_output
close

The server can also observe RFC 9218 priority updates with on_priority.

SEE ALSO

Unblock::HTTP2, Unblock::HTTP2::Integration, Unblock::HTTP2::Transaction, Uniform::HTTP::Response

LICENSE

MIT License.

cpanm Unblock::HTTP2

perl -MCPAN -e shell
install Unblock::HTTP2