NAME
Linux::Event::HTTP::Server - HTTP 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;DESCRIPTION
Linux::Event::HTTP::Server is the ordinary entry point for an HTTP server. It listens using Linux::Event and invokes on_request whenever a validated request head is available.
The callback receives:
$conn- the persistent HTTP connection$req- the current Linux::Event::HTTP::Request$res- the Linux::Event::HTTP::Response for that request
Request and Response are HTTP message objects. The one-request/one-response exchange is represented by Linux::Event::HTTP::Transaction and is available as $conn->transaction while active. Response does not retain a hidden Connection or peer-Request back-reference.
A complete scalar response body is configured on the Response:
$res->body("hello\n");For an incremental outgoing body, use the active Transaction:
on_request => sub ($conn, $req, $res) {
$res->header('Content-Type', 'text/plain');
my $body = $conn->transaction->response_body;
$body->write("one\n");
$body->complete("two\n");
},Completing an HTTP response does not normally close the connection. HTTP keep-alive may reuse the same connection for later Transactions.
DEFERRED RESPONSES
Inside an HTTP callback, $res->body(...) is committed after callback return when protocol state permits. This allows metadata to be configured in any natural order before output begins.
If another event completes the Response later, retain the Transaction and send the complete scalar message 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;
},
);The explicit send_response call is intentional. Response remains a transport-independent message and setting body later does not secretly write to a socket.
REQUEST BODIES
Request bodies are incremental-first. Add on_body when body bytes are needed, and on_request_end when work should happen after the complete request input has arrived:
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 absent, the server drains request-body bytes without building a whole-body scalar. Request->is_complete becomes true at the actual request-body boundary.
UPGRADE
HTTP Upgrade is an exchange operation owned by Transaction. Configure the Response switching metadata and ask the active Transaction to hand off the live transport:
$res->header('Upgrade', 'my-protocol');
$conn->transaction->upgrade('MyProtocolConnection');The server validates the HTTP/1.1 Upgrade, queues the 101 response, completes the HTTP Transaction, and then uses Linux::Event transition_to() on the same stream object. Response itself has no upgrade method.
CONNECTION SUBCLASSES
Most applications do not need to subclass the HTTP connection. Use connection_class when reusable transport defaults, stream tuning, socket policy, or callback methods belong on a class:
package MyHTTP;
use parent 'Linux::Event::HTTP::Server::Connection';
sub stream_tuning ($class) {
return read_budget_bytes => 262_144;
}
sub on_request ($self, $req, $res) {
$res->body("hello\n");
}
package main;
my $server = Linux::Event::HTTP::Server->new(
loop => $loop,
port => 8080,
connection_class => 'MyHTTP',
);connection_class defaults to Linux::Event::HTTP::Server::Connection.
TUNING AND CONNECTION CALLBACKS
Supply deployment-specific Stream tuning directly to the Server. These values override stream_tuning() defaults on the configured Connection class:
my $server = Linux::Event::HTTP::Server->new(
loop => $loop,
port => 8080,
tuning => {
read_size => 131_072,
read_budget_bytes => 524_288,
idle_timeout => 60,
},
on_request => sub ($conn, $req, $res) {
$res->body("hello\n");
},
);Accepted-connection lifecycle callbacks are on_ready, on_transport_ready, on_drain, on_eof, on_error, and on_close. on_listener_error is the distinct callback for listening and acceptance failures. The advanced on_accept($listener, $conn) callback receives the underlying Listener and each newly accepted HTTP Connection.
TLS
HTTPS uses the same Server API. Activate Linux::Event TLS transport policy with the Server tls option:
my $server = Linux::Event::HTTP::Server->new(
loop => $loop,
port => 8443,
tls => {
cert_file => '/etc/myapp/server-cert.pem',
key_file => '/etc/myapp/server-key.pem',
alpn => ['http/1.1'],
},
on_request => sub ($conn, $req, $res) {
$res->body("secure\n");
},
);A Connection subclass may define tls_defaults() for reusable ALPN and timeout defaults. The Server tls option is still required to activate TLS, so the same Connection class may be used for plain HTTP and HTTPS listeners.
METHODS
listener
Returns the underlying Linux::Event::IO::Sock::Listener for advanced use.
connection_class
Returns the configured HTTP Connection class name.
data
Returns the application data supplied to the Server.
loop, 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 HTTP connections keep their independent lifecycles.
SEE ALSO
Linux::Event::HTTP::Server::Connection, Linux::Event::HTTP::Transaction, Linux::Event::HTTP::Request, Linux::Event::HTTP::Response, Linux::Event::HTTP::Body::Stream, Linux::Event::TLS.