/ 
Linux-Event-HTTP-0.003
/ Linux::Event::HTTP::Server

NAME

Linux::Event::HTTP::Server - HTTP/1.x and HTTP/2 server endpoint

SYNOPSIS

use v5.36;
use Linux::Event::Loop;
use Linux::Event::HTTP::Server;

my $loop = Linux::Event::Loop->new;

my $server = Linux::Event::HTTP::Server->new(
    loop => $loop,
    host => '127.0.0.1',
    port => 8080,

    on_request => sub ($conn, $req, $res) {
        $res->header('Content-Type', 'text/plain');
        $res->body("hello\n");
    },
);

$loop->run;

For HTTPS with HTTP/2 negotiation:

my $server = Linux::Event::HTTP::Server->new(
    loop  => $loop,
    port  => 8443,
    http2 => 1,

    tls => {
        cert_file => '/path/server-cert.pem',
        key_file  => '/path/server-key.pem',
    },

    on_request => sub ($conn, $req, $res) {
        $res->body("HTTP " . $req->version . "\n");
    },
);

DESCRIPTION

Linux::Event::HTTP::Server is the ordinary server entry point.

The same on_request callback model is used for HTTP/1 and HTTP/2. The callback receives:

($conn, $req, $res)

where $req is the Request message, $res is the Response message, and $conn is the live HTTP connection.

The active Linux::Event::HTTP::Transaction is available through:

my $tx = $conn->transaction;

Use the Transaction only when exchange lifecycle operations are needed, such as streaming output, delayed output, Upgrade, or CONNECT handoff.

CONSTRUCTOR

my $server = Linux::Event::HTTP::Server->new(%options);

Common options are:

  • loop

    The Linux::Event::Loop.

  • host, port, path

    Listener address options passed to Linux::Event.

  • on_request

    Required unless the configured connection class provides an on_request method.

  • on_body

    Receives request-body chunks:

    on_body => sub ($conn, $req, $res, $bytes) { ... }

    If omitted, request-body bytes are drained instead of accumulated.

  • on_request_end

    Runs after the complete request body boundary is reached.

  • tls

    Enables Linux::Event TLS transport.

  • http2

    When true, enables HTTP/2 negotiation for TLS connections. HTTP/2 requires Net::HTTP2::nghttp2 0.011 or newer.

  • http2_max_header_list_size

    Maximum decoded HTTP/2 request/trailer header-list size. Default: 65,536 bytes.

  • tuning

    Linux::Event Stream tuning for accepted connections.

  • data

    Application data available through $server->data and connection state.

  • connection_class

    Advanced HTTP/1 connection subclass. The default is Linux::Event::HTTP::Server::Connection. HTTP/2 currently requires the default connection class.

Listener and accepted-connection lifecycle callbacks supported by the constructor include on_ready, on_transport_ready, on_drain, on_eof, on_error, on_close, and on_listener_error.

RESPONSES

For a complete response already in memory:

on_request => sub ($conn, $req, $res) {
    $res->status(200);
    $res->header('Content-Type', 'text/plain');
    $res->body("hello\n");
}

A scalar body configured during an HTTP callback is committed after that callback returns.

Completing a response does not normally close the connection. HTTP persistence is handled by the selected protocol.

STREAMING RESPONSES

For incremental output, obtain a body producer from the Transaction:

on_request => sub ($conn, $req, $res) {
    my $body = $conn->transaction->response_body(
        on_drain  => sub ($body) { ... },
        on_cancel => sub ($body) { ... },
    );

    $body->write($chunk);
    $body->complete($final_chunk);
};

write follows Linux::Event backpressure semantics. A false return means the bytes were accepted but the producer should pause until on_drain runs.

REQUEST BODIES

Request bodies are streaming-first:

my $server = Linux::Event::HTTP::Server->new(
    loop => $loop,
    port => 8080,

    on_request => sub ($conn, $req, $res) {
        $conn->data->{body} = '';
    },

    on_body => sub ($conn, $req, $res, $bytes) {
        $conn->data->{body} .= $bytes;
    },

    on_request_end => sub ($conn, $req, $res) {
        $res->body("received\n");
    },
);

If on_body is omitted, body bytes are drained rather than stored in the Request.

DELAYED RESPONSES

A Response may be completed by another event later. Retain the Transaction and send the finished scalar response explicitly:

my $tx = $conn->transaction;

Linux::Event::Kernel::Timer->new(
    loop  => $conn->loop,
    after => 0.1,

    on_timer => sub ($timer) {
        $tx->response->body("later\n");
        $tx->send_response;
    },
);

send_response is explicit because Response is a message object, not a hidden transport handle.

TLS AND HTTP/2

TLS is enabled with the tls constructor option.

HTTP/2 is enabled with:

http2 => 1

When enabled, the Server advertises h2 before http/1.1. ALPN selects the protocol while applications continue using the same on_request callback and Request/Response classes.

The current production HTTP/2 server path is TLS + ALPN. Cleartext h2c is not provided.

http2 => 1 owns the TLS ALPN list and currently requires the default connection class.

UPGRADE AND CONNECT

HTTP/1.1 protocol handoff belongs to Transaction.

Upgrade:

$res->header('Upgrade', 'my-protocol');
$conn->transaction->upgrade('MyProtocolConnection');

CONNECT:

if ($req->method eq 'CONNECT') {
    $conn->transaction->tunnel('MyTunnelConnection');
}

Both operations transition the same live Linux::Event stream after the HTTP exchange reaches the correct boundary. Already-read post-HTTP bytes are preserved.

These are HTTP/1 transport-handoff operations; they do not describe HTTP/2 stream-level tunnels.

MANAGED PRE-FORK

For plain HTTP, the underlying Listener can be intentionally shared with Linux::Event managed fork support:

my $pid = $loop->fork(
    share => [ $server->listener ],
);

Worker creation and supervision remain application policy. This documented sharing pattern is for plain HTTP; do not assume the same recipe for TLS Listeners without separate validation.

METHODS

listener

Returns the underlying Linux::Event::IO::Sock::Listener.

loop

Returns the Loop.

connection_class

Returns the configured HTTP/1 connection class.

http2

True when HTTP/2 support was enabled for this Server.

http2_max_header_list_size

Returns the configured HTTP/2 decoded header-list limit.

data

Returns the Server application data.

fh, fd, host, port, path, family, family_number, is_tcp, is_unix, state

Delegate to the underlying Listener.

pause

Pauses acceptance and returns the Server.

resume

Resumes acceptance and returns the Server.

close

Closes the listening endpoint and returns the Server. Existing accepted connections keep their own lifecycles.

SEE ALSO

Linux::Event::HTTP, Linux::Event::HTTP::Client, Linux::Event::HTTP::Server::Connection, Linux::Event::HTTP::Transaction, Linux::Event::HTTP::Request, Linux::Event::HTTP::Response, Linux::Event::HTTP::Body::Stream.