/ 
Linux-Event-HTTP-0.005
/ README.md

Linux::Event::HTTP

Build HTTP servers and make HTTP requests with Linux::Event. HTTP/1.1 works out of the box. HTTP/2 and HTTP/3 are optional.

This module handles the HTTP connection for you. You provide callbacks to receive requests, send responses, or handle errors.

Requirements: Linux and Perl 5.36 or newer.

Install

cpanm Linux::Event::HTTP

Your first server

Save as server.pl:

#!/usr/bin/env perl
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 ($tx, $req) {
        $tx->respond(
            status => 200,
            headers => [['content-type', 'text/plain']],
            body => "Hello from Linux::Event!\n",
        );
    },
);

say "Listening on http://127.0.0.1:8080/";
$loop->run;

Start it with perl server.pl. In another terminal, run:

curl http://127.0.0.1:8080/

The on_request callback runs when the entire request has arrived. $req is the incoming request; $tx is the transaction used to reply. The server keeps running until you stop it.

Your first client

Save as client.pl:

#!/usr/bin/env perl
use v5.36;
use Linux::Event::Loop;
use Linux::Event::HTTP::Client;

my $loop = Linux::Event::Loop->new;
my $client = Linux::Event::HTTP::Client->new(loop => $loop);

$client->get(
    'https://example.com/',
    timeout => 15,

    on_response => sub ($tx, $res) {
        say "HTTP ", $res->status;
        say $res->body;
    },

    on_error => sub ($object, $error, @details) {
        warn "Request failed: $error\n";
    },

    on_finish => sub { $loop->stop },
);

$loop->run;

Run perl client.pl. The client waits asynchronously for the server. By default, on_response runs after the whole response body has arrived. on_error handles connection and protocol failures. on_finish runs at the end of either outcome, so it is a convenient place to stop a one-request program.

An HTTP response like 404 or 500 is still an HTTP response; inspect $res->status. It is not necessarily a connection error.

Next steps

Read the Getting Started guide for these everyday tasks:

The public interfaces are Client and Server. You can use one client for many requests, and a server can handle many connections.

Protocols and advanced features

HTTP/1.1 is enabled by default. For HTTP/2, install Unblock::HTTP2 0.13+ and set http2 => 1; servers also need TLS. For HTTP/3, install Unblock::HTTP3 0.14+ and Net::QUIC 0.06+, then set http3 => 1 and configure TLS. HTTP/3 servers require a concrete listener host and run alongside a TCP listener. WebSocket and CONNECT handoff are also available.

Linux::Event manages sockets, TLS, and timers. Unblock::HTTP manages HTTP transactions and connection pooling; Uniform::HTTP supplies request and response objects. You do not need to learn these internals to make ordinary HTTP requests.

For more detail, see Architecture, CONNECT handoff, Benchmarking, and the 0.005 release notes. Version 0.004 replaced the former public API; see the 0.004 release notes before migrating older applications.

Development

perl Makefile.PL
make
make test