/ 
Unblock-HTTP2-0.12
/ Unblock::HTTP2::Transaction

NAME

Unblock::HTTP2::Transaction - one HTTP/2 request/response transaction

SYNOPSIS

# Inside a Server on_request callback:
my ($tx, $request) = @_;
$tx->send_informational(status => 103);
$tx->respond(status => 200, body => "hello\n");

# Alternatively, to stream a different response:
$tx->respond(status => 200, stream_body => 1);
$tx->write($chunk);
$tx->end($final_chunk);

The second example is an alternative to the first, not a second response on the same Transaction. respond(), send_informational(), and Client request() accept named HTTP fields directly; creating a Uniform message by hand is optional.

RECEIVE AND FINISH CALLBACKS

$tx->on_data(sub {
    my ($tx, $bytes) = @_;
    consume_chunk($bytes);
});

Register during the incoming-header callback (server on_request or client on_response). This selects streaming for this transaction. Only decoded HTTP body bytes are passed; content encodings such as gzip are not decoded. No full body is accumulated. Registering after body delivery starts or ends, registering twice, or combining this callback with on_body is an error. Client request() also accepts on_data before the request is dispatched.

$tx->on_finish(sub {
    my ($tx) = @_;
    record_outcome($tx->state, $tx->error);
});

Runs once after the applicable completion or error callbacks for a terminal complete, cancelled, or error transaction. The state is committed before the callback. Cancellation alone does not call on_error. A completed incoming request can still have an unfinished response; it is not terminal until both sides required by the engine have finished.

Client request() also accepts on_finish. Register it before the transaction becomes terminal. Duplicate and late registration are errors. An exception from this terminal observer is ignored so cleanup and other transactions can continue. Earlier callbacks keep the engine's exception policy, but cannot suppress this notification.

DESCRIPTION

A Transaction represents one HTTP request/response exchange carried by one multiplexed HTTP/2 stream.

request() returns the Uniform request. response() returns the Uniform response once one is available.

STREAMING BODIES

For a streaming local body:

$transaction->write($chunk);
$transaction->end($last_chunk);

write() always accepts the bytes. A false return means the cooperative high-water mark was reached, or an attached host has become congested. Wait for on_drain before producing more.

Incoming body bytes are consumed automatically after the body callback returns.

For manual receive flow control:

$transaction->auto_consume(0);
$transaction->consume($bytes_processed);

unconsumed_bytes() reports body bytes still waiting for stream-level credit.

SERVER RESPONSES

A server Transaction can send an informational response with:

$transaction->send_informational(status => 103);

The final response uses:

$transaction->respond(status => 200, body => "hello\n");

Both calls accept a canonical Uniform::HTTP::Response object too.

Pass stream_body => 1 to respond() to produce the response body with write() and end(). on_drain and on_error are response options, not HTTP fields.

RESETS

cancel() sends the standard HTTP/2 CANCEL reset.

reset($error_code) sends an explicit RST_STREAM reason.

The Transaction preserves:

error
error_code
error_name
reset_by_peer

These facts are exposed for higher-level retry and policy decisions.

PRIORITY

Client Transactions can use update_priority($field_value) to send an RFC 9218 PRIORITY_UPDATE after the peer has enabled modern priorities.

STATE

Useful state accessors include:

stream_id
state
is_complete
is_cancelled
is_error
is_terminal

HTTP/2 half-close is preserved. One direction may finish before the full Transaction becomes terminal.

SEE ALSO

Unblock::HTTP2, Unblock::HTTP2::Client, Unblock::HTTP2::Server, Unblock::HTTP2::Integration

LICENSE

MIT License.