/ 
Linux-Event-HTTP-0.004
/ Linux::Event::HTTP::Server

NAME

Linux::Event::HTTP::Server - Native Linux listener for Unblock HTTP

SYNOPSIS

my $server = Linux::Event::HTTP::Server->new(
    loop => $loop, port => 8080,
    on_request => sub ($tx, $request) {
        $tx->respond(status => 200, body => "Hello\n");
    },
);

DESCRIPTION

HTTP/1 is enabled by default. Callbacks receive real Unblock transactions and Uniform messages. on_headers runs before the body; on_request runs once after successful body completion. Set $tx->on_data(...) during on_headers to stream a request. Otherwise Unblock buffers up to 1 MiB; configure http1 => { max_buffered_body_bytes => ... } to change it.

tls and tuning configure the Linux::Event listener's accepted streams. HTTP owns TLS ALPN selection; do not specify tls => { alpn => ... }. native_input => 0 selects the Perl input path for diagnostics. on_listener_error receives listener failures; on_error is the HTTP engine error callback. Unknown options are rejected.

loop, listener, host, port, pause, resume, close and connection_count expose listener controls and live connection count. close stops accepting connections; existing connections continue.

shutdown(grace => 30, on_complete => sub ($server) { ... }) stops listening, drains admitted HTTP/1 requests, and closes remaining owned connections when the grace period expires. TLS handshakes without admitted requests close immediately. Completion runs once after owned connections and their transactions have finished; it can run synchronously if idle. Repeated shutdown calls have no effect. grace is non-negative seconds. on_handoff enables generic HTTP1 101 Upgrade and successful CONNECT handoff for non-WebSocket protocols. It runs after HTTP accepts the switch response into the existing write queue and receives ($tx, $request, $response, $transport). Return a successor protocol object implementing input, input_eof, transport_error and resume_output. The Linux::Event stream transitions in place; any same-read native input tail is preserved without duplication. The successor owns the socket after handoff. WebSocket handshakes take precedence when both callbacks are enabled. For HTTP2/HTTP3, on_handoff($tx, $request, $bridge) returns a stream-local consumer for a CONNECT request (not a whole socket). The Server responds with status 200, forwards DATA and EOF to the consumer, and preserves ordinary sibling streams. Return undef to reject with 403. Configure http2 => { enable_connect_protocol => 1 } or http3 => { enable_extended_connect => 1 } for Extended CONNECT; no WebSocket advertisement is required. The bridge accepts unblock_send, unblock_finish, and unblock_abort, with deferred bounded output. It invokes resume_output for flow control. Generic handoff never replaces the multiplexed transport.

http2 => 1 enables optional Unblock::HTTP2 (at least 0.13). Server HTTP/2 requires TLS and uses ALPN, with HTTP/1 fallback unless http1 => 0. A hashref supplies HTTP/2 engine tuning. Shutdown sends GOAWAY and drains admitted streams. Cleartext HTTP/2 remains unimplemented. HTTP/2 on_error may include a third protocol error-code argument. Optional http3 => 1 uses Unblock::HTTP3 0.14 and Net::QUIC 0.06 on UDP alongside the TCP listener at the same concrete host and port. Its credentials are taken from tls => { cert_file, key_file }. quic => { ... } configures Net::QUIC server transport policy. Wildcard-bound HTTP3 and H3-only listeners are not yet supported. close stops H3 admission by sending GOAWAY to attached sessions; shutdown also waits for draining sessions until the grace deadline. Forced expiry releases the UDP socket and timer. The supported concrete-address HTTP3 lifecycle passed the Stage D QUIC loopback and cleanup tests.

Opt-in http1 => { websocket => 1 } with on_websocket uses Unblock's HTTP1 handshake and transitions the same Linux::Event socket to WebSocket without losing same-read bytes. Native and Perl input paths are tested. http2 => { websocket => 1 } and http3 => { websocket => 1 } enable Extended CONNECT on individual multiplexed streams. The H2 path passes real TLS loopback. H2 and H3 WebSocket Extended CONNECT are verified by real TLS and QUIC loopback with independent ordinary HTTP streams. Unblock::HTTP3 0.14 includes the completion-order fix for WebSocket Close and stream FIN. WebSocket remains an optional dependency, loaded only when enabled.