NAME

Unblock::HTTP2::Client - one HTTP/2 client connection

SYNOPSIS

use Unblock::HTTP2::Client;

# $stream is a connected socket or TLS stream owned by your framework.
my $client = Unblock::HTTP2::Client->new(
    transport => $stream,
);

my $transaction = $client->request(
    method    => 'GET',
    target    => '/',
    scheme    => 'https',
    authority => 'example.com',

    on_response => sub {
        my ($tx, $response) = @_;
        print "Status: ", $response->status, "\n";
    },
    on_body => sub {
        my ($tx, $response, $bytes) = @_;
        print $bytes;
    },
    on_complete => sub {
        my ($tx) = @_;
        print "Response complete\n";
    },
);

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

The framework stream implements unblock_send(), unblock_finish(), and unblock_abort(). The Client automatically sends its connection preface, SETTINGS, requests, and other outgoing frames through the host. The framework retains ownership of sockets, TLS, and its write queue.

See Unblock::HTTP2::Integration and examples/io-async-client.pl for a complete connection example.

DESCRIPTION

A Client owns one HTTP/2 client session.

It does not create a socket, perform TLS, run an event loop, or own a transport write queue.

With transport => $host, feed network bytes using input(). Generated output is automatically delivered to the host's unblock_send() method. Without an attached host, manually drain output() while want_write() is true.

Many request transactions can be active at once.

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_active_transactions, max_header_list_size, and an optional transport object.

The attached transport implements unblock_send(), unblock_finish(), and unblock_abort(). See Unblock::HTTP2::Integration.

Connection callbacks are:

on_settings($client, $peer_settings, $changed_settings)
on_settings_ack($client, $acked_settings)
on_ping($client, $opaque)
on_ping_ack($client, $opaque)
on_invalid_frame($client, $frame, $lib_error_code)

REQUESTS

request($request, %options) sends a Uniform::HTTP::Request and returns a Unblock::HTTP2::Transaction. The simpler named-field form also works:

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

Callbacks and stream_body are options, not Uniform message fields.

Useful callbacks are:

on_response($transaction, $response)

Final response headers arrived.

on_informational($transaction, $response)

An informational response arrived.

on_body($transaction, $response, $bytes)

A response body chunk arrived.

on_complete($transaction)

The response completed.

on_error($transaction, $error, $error_code)

The transaction failed or its HTTP/2 stream was reset. $error_code can be undefined when there is no HTTP/2 reset code.

on_drain($transaction)

A streaming request body can produce more data.

Set stream_body => 1 to produce the request body with the Transaction write() and end() methods.

CONNECTION CONTROL

The Client also 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

can_open_transaction() reports whether another local request transaction can be opened.

SEE ALSO

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

LICENSE

MIT License.

cpanm Unblock::HTTP2

perl -MCPAN -e shell
install Unblock::HTTP2