/ 
Linux-Event-HTTP-0.001
/ Linux::Event::HTTP::Client::Connection

NAME

Linux::Event::HTTP::Client::Connection - one HTTP/1 client connection

SYNOPSIS

use Linux::Event::HTTP::Client::Connection;
use Linux::Event::HTTP::Request;

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 => 'POST',
        target => '/',
        headers => [ [ Host => 'example.test' ] ],
    ),
    stream_body => {
        on_drain  => sub ($body) { ... },
        on_cancel => sub ($body) { ... },
    },
    on_response => sub ($tx, $res) {
        say $res->status;
    },
    on_body => sub ($tx, $res, $bytes) {
        process_bytes($bytes);
    },
    on_complete => sub ($tx) {
        say 'done';
    },
    on_error => sub ($tx, $error) {
        warn $error;
    },
);

my $body = $tx->request_body;
$body->write($bytes);
$body->complete;

DESCRIPTION

Linux::Event::HTTP::Client::Connection is the low-level HTTP/1 execution object for one persistent Linux::Event stream socket. URL parsing, destination selection, connection pooling, redirects, and higher-level convenience belong above this class.

The connection executes one Linux::Event::HTTP::Transaction at a time. After a persistent response completes, another Transaction may reuse the same socket. HTTP/1 client pipelining is deliberately not enabled.

Outgoing Request bodies may be complete scalars or Transaction-owned streaming producers. Streaming writes use Linux::Event's existing ordered-byte queue and cooperative high/low-watermark backpressure; HTTP maintains no second output queue.

Response bodies are incremental-first. on_body receives delivered body bytes; when it is absent, body bytes are drained and discarded rather than accumulated implicitly into the Response object. Explicit buffer_body requests bounded whole-body accumulation using the same framing/consumption path.

HTTP/1.1 101 Switching Protocols can hand the same live connection to another Linux::Event::IO::Sock::Stream subclass with upgrade_to. A successful CONNECT can similarly hand the same live socket to a tunnel protocol class with tunnel_to.

METHODS

connect

Uses the normal Linux::Event::IO::Sock::Stream asynchronous connect contract. Requests may be submitted before transport readiness because Linux::Event already queues pre-connect output in order.

The HTTP implementation owns on_data, on_eof, on_error, and on_close. Transport on_drain is composed with streaming Request producer drain bookkeeping. Per-Transaction response callbacks belong to request.

transaction

Returns the currently active Transaction, or undef when the connection is idle.

request

Starts one exchange and returns its Transaction immediately. Only one Transaction may be active on this connection at a time.

For HTTP/1.1, the Request must contain exactly one Host field. A complete scalar body automatically gains Content-Length when it was not already supplied. An explicit Content-Length must match the scalar body.

stream_body => { ... } selects incremental Request production. The hash accepts on_drain and on_cancel, and the stable producer is then available through $tx->request_body. When Content-Length is supplied it is enforced exactly. Without Content-Length, HTTP/1.1 automatically uses chunked transfer coding. HTTP/1.0 streaming requires Content-Length; request bodies are never close-delimited. Scalar body and stream_body are mutually exclusive.

on_response runs once after the final response head is validated and before body delivery. on_informational receives non-switching 1xx responses such as 100 Continue. on_body receives decoded Content-Length, chunked, or close-delimited body bytes. on_complete runs after the complete message boundary. on_error reports terminal protocol or transport failure.

upgrade_to => $class opts this request into HTTP/1.1 Upgrade handoff. The Request must be bodyless and must advertise Connection: Upgrade plus at least one Upgrade protocol. A valid 101 must select a protocol offered by the Request, must contain Connection: Upgrade, and cannot contain Content-Length or Transfer-Encoding. on_upgrade receives ($tx, $res, $connection) after the HTTP Transaction completes and after the same live stream object has been transitioned to $class. Any bytes already read after the 101 head are preserved as input for the target protocol. on_complete then runs for the completed HTTP Transaction. A bare 101 without upgrade_to is a protocol error and closes the HTTP connection.

tunnel_to => $class is valid only for an HTTP/1.1 CONNECT Request. The request-target must be authority-form host:port, Host must match that authority exactly apart from case, and the Request must have no scalar or streaming body, Content-Length, or Transfer-Encoding. on_tunnel receives ($tx, $res, $connection) after any successful 2xx CONNECT response completes the HTTP Transaction and the same live stream has transitioned to $class. Bytes already read after the response head are tunnel input. Content-Length and Transfer-Encoding on a successful CONNECT response are ignored as required by HTTP semantics. Non-2xx CONNECT responses remain ordinary HTTP responses and may use on_body or buffer_body normally. on_complete runs after a successful tunnel handoff or after an ordinary non-2xx response completes.

buffer_body => $max_bytes explicitly requests whole-body buffering with a positive byte limit. It cannot be combined with on_body. The limit counts the same body bytes that on_body would receive: HTTP/1 chunk framing has already been removed. A known Content-Length above the limit fails after on_response and before body accumulation. Unknown-length/chunked bodies fail as soon as the delivered byte count would cross the limit. Limit failure is a Transaction error and closes the connection. On successful completion, $tx->response->body returns the buffered scalar, including the empty string for a bodyless response.

If a final Response arrives before an outgoing streaming Request body is complete, the Request producer is cancelled and that HTTP/1 connection is not reused. This permits early server rejection without leaving an application producer running against an exchange that has already ended.

Cancellation closes the connection because an HTTP/1 response cannot in general be abandoned mid-message and then safely reused without consuming its remaining wire bytes.

RESPONSE FRAMING

The client applies HTTP/1 message framing independently from application body handling:

  • HEAD, 204, and 304 responses have no delivered message body;

  • Content-Length bodies are delivered incrementally to their exact length;

  • HTTP/1 chunked transfer coding is decoded with the existing native _HTTP1::Chunked decoder;

  • responses without a length or transfer coding are close-delimited and make the connection non-reusable.

  • a validated 101 response terminates HTTP framing and transitions the same live stream to the explicitly requested target protocol class.

  • any successful 2xx CONNECT response terminates HTTP framing immediately after its header section and transitions the same live stream into tunnel mode; Content-Length and Transfer-Encoding fields on that successful response are ignored.

There is no implicit or unbounded whole-body buffer. Explicit buffer_body uses this same framing path and enforces its configured bound.

SEE ALSO

Linux::Event::HTTP::Client, Linux::Event::HTTP::Request, Linux::Event::HTTP::Response, Linux::Event::HTTP::Transaction, Linux::Event::HTTP::Body::Stream, Linux::Event::IO::Sock::Stream.