NAME

Linux::Event::HTTP::Client::Connection - low-level HTTP/1 client connection

DESCRIPTION

Linux::Event::HTTP::Client::Connection is the advanced low-level HTTP/1 executor for one persistent Linux::Event stream.

Most applications should use Linux::Event::HTTP::Client instead.

This class does not provide high-level URL policy, redirects, cookies, authentication retry, proxy selection, connection pooling, or HTTP/2 multiplexing. It executes one HTTP/1 Transaction at a time on one connection.

SYNOPSIS

my $conn = Linux::Event::HTTP::Client::Connection->connect(
    loop => $loop,
    host => '127.0.0.1',
    port => 8080,
);

my $tx = $conn->request(
    Linux::Event::HTTP::Request->new(
        method  => 'GET',
        target  => '/',
        headers => [ [ Host => 'example.test' ] ],
    ),

    on_response => sub ($tx, $res) { ... },
    on_body     => sub ($tx, $res, $bytes) { ... },
    on_complete => sub ($tx) { ... },
    on_error    => sub ($tx, $error) { ... },
);

METHODS

connect

Uses the normal asynchronous Linux::Event Stream connect contract.

HTTP owns protocol input and terminal transport callbacks. on_data is not an HTTP Client::Connection extension point.

transaction

Returns the active Transaction, or undef while idle.

request

Starts one HTTP/1 exchange and returns its Transaction immediately.

Only one Transaction may be active at a time. HTTP/1 pipelining is not enabled.

For HTTP/1.1, the Request must contain exactly one Host field.

Scalar request bodies automatically receive Content-Length when needed.

stream_body selects incremental request production. Unknown-length HTTP/1.1 streaming uses chunked transfer coding. HTTP/1.0 streaming requires Content-Length.

Response bodies are incremental-first. on_body receives decoded body bytes. buffer_body => $max_bytes requests bounded whole-body accumulation and cannot be combined with on_body.

upgrade_to opts a request into validated HTTP/1.1 Upgrade handoff.

tunnel_to opts a CONNECT request into validated tunnel handoff.

Cancellation closes the HTTP/1 connection when the remaining response cannot be safely abandoned and reused.

RESPONSE FRAMING

The connection handles HTTP/1 response framing before application body delivery:

• HEAD, 204, and 304 have no delivered response body.

• Content-Length bodies end at the declared length.

• Chunked transfer coding is decoded before on_body or buffer_body.

• Responses without a length or transfer coding are close-delimited.

• A validated 101 ends HTTP framing for Upgrade handoff.

• A successful CONNECT 2xx ends HTTP framing at the response-head boundary.

SEE ALSO

Linux::Event::HTTP::Client, Linux::Event::HTTP::Transaction, Linux::Event::HTTP::Request, Linux::Event::HTTP::Response.