NAME

Unblock::HTTP2 - non-blocking HTTP/2 protocol engine for Perl

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);

use Unblock::HTTP2::Client;

# $client_stream is a separate connected framework stream.
my $client = Unblock::HTTP2::Client->new(
    transport => $client_stream,
);

$client->request(
    method    => 'GET',
    target    => '/',
    scheme    => 'https',
    authority => 'example.test',
    on_response => sub {
        my ($tx, $response) = @_;
        print $response->status, "\n";
    },
    on_body => sub {
        my ($tx, $response, $bytes) = @_;
        print $bytes;
    },
);

Both $stream and $client_stream are framework-owned transport objects. Each implements unblock_send($bytes), unblock_finish(), and unblock_abort($reason). They feed received bytes with input(). Outgoing HTTP/2 bytes are sent automatically through unblock_send(). No output() polling loop is needed in this mode.

For complete, runnable integration examples, see Unblock::HTTP2::Integration and the examples/ directory.

DESCRIPTION

Unblock::HTTP2 is an HTTP/2 protocol engine.

It handles HTTP/2 framing, HPACK, multiplexed streams, SETTINGS, flow control, PING, GOAWAY, trailers, CONNECT, and RFC 9218 priority signaling.

It does not own sockets, TLS, ALPN, an event loop, connection pooling, or retry policy.

HTTP messages are Uniform::HTTP::Request and Uniform::HTTP::Response objects.

libnghttp2 is used through a small private XS binding contained in this distribution.

MODULES

Unblock::HTTP2::Integration

How to attach an event-framework stream.

Unblock::HTTP2::Client

One client HTTP/2 connection.

Unblock::HTTP2::Server

One server HTTP/2 connection.

Unblock::HTTP2::Transaction

One HTTP request/response transaction carried by an HTTP/2 stream.

Unblock::HTTP2::NativeABI

Optional native transport ABI for XS-backed integrations.

ERROR CODES

The standard HTTP/2 error codes are available as package constants, including NO_ERROR, PROTOCOL_ERROR, REFUSED_STREAM, and CANCEL.

error_name($code) returns the symbolic name for a known code.

TRANSPORT BOUNDARY

Create a Client or Server with transport => $framework_stream. The framework provides unblock_send(), unblock_finish(), and unblock_abort(). Feed received bytes with input(). The engine automatically delivers outgoing HTTP/2 bytes to the framework.

The previous manual want_write() and output() interface remains available without an attached transport.

XS-backed transports can instead use Unblock::HTTP2::NativeABI for borrowed input and native output sinks.

For a complete description of callbacks, backpressure, EOF, and shutdown, see Unblock::HTTP2::Integration.

SEE ALSO

Uniform::HTTP, Alien::nghttp2

LICENSE

MIT License.