AnyEven...:Server(3)

📦
version 1.99998 · 2 versions
, in fedora 43

💖 AnyEven...:Server(3) — the vibe

okay bestie, so this is a page from the User Contributed Perl Documentation, and it's filed under AnyEven...:Server(3) (yes the name is truncated like that, we don't make the rules 💅). The actual star of the show is AnyEvent::HTTP::Server, and I'm gonna walk you through every single bit of it, no cap.

✨ NAME ✨

AnyEvent::HTTP::Server — it's an AnyEvent HTTP/1.1 Server. that's the whole name section, she's brief but she ate.

🎀 SYNOPSIS 🎀

here's the serve, exactly as written:

use AnyEvent::HTTP::Server;
my $s = AnyEvent::HTTP::Server->new(
    host => '0.0.0.0',
    port => 80,
    cb => sub {
      my $request = shift;
      my $status  = 200;
      my $content = "<h1>Reply message</h1>";
      my $headers = { 'content-type' => 'text/html' };
      $request->reply($status, $content, headers => $headers);
    }
);
$s->listen;

## you may also prefork on N cores:

# fork() ? next : last for (1..$N-1);

## Of course this is very simple example
## don't use such prefork in production

$s->accept;

my $sig = AE::signal INT => sub {
    warn "Stopping server";
    $s->graceful(sub {
        warn "Server stopped";
        EV::unloop;
    });
};

EV::loop;
🫶 heads up: that prefork situation is a very simple example — the original literally says don't use such prefork in production. love that for us, respect the disclaimer.

🌈 DESCRIPTION 🌈

okay so AnyEvent::HTTP::Server is a very fast asynchronous HTTP server written in perl. it has been tested in high load production environments and may be considered both fast and stable. she's got range, she's got stamina, she's that girl. 👑

you can easily implement your own HTTP daemon with AnyEvent::HTTP::Server and the Daemond::Lite module, both of which are found at <https://github.com/Mons> 🦋

and important lore: this is the second verson available as AnyEvent-HTTP-Server-II. the first version is now obsolette. rip to the original, she's retired, we move on. 💀

🧚 HANDLING REQUEST 🧚

you handle an HTTP request by passing the cb parameter to AnyEvent::HTTP::Server->new() like this:

my $dispatcher = sub {
  my $request = shift;
  #... Request processing code goes here ...
  1;
};

my $s = AnyEvent::HTTP::Server->new( host => '0.0.0.0', port => 80, cb => $dispatcher,);

so here's the tea: the $dispatcher coderef will be called in a list context, and its return value should resolve to true — or the request processing will be aborted by AnyEvent:HTTP::Server. no true, no service, periodt. 😭

🌸 POST requests, the special sauce 🌸

you're also able to process POST requests by returning a specially crafted hash reference from the cb parameter coderef ($dispatcher in our example). this hash must contain the form key, holding a code reference. if the conetnt-encoding header is application/x-www-form-urlencoded, the form callback will be called.

my $post_action = sub {
  my ( $request, $form ) = @_;
  $request->reply(
    200, # HTTP Status
    "You just send long_data_param_name value of $form->{long_data_param_name}",  # Content
    headers=> { 'content-type' =< 'text/plain'}, # Response headers
  );
}

my $dispatcher = sub {
  my $request = shift;

  if ( $request->headers->{'content-type'} =~ m{^application/x-www-form-urlencoded\s*$} ) {
    return {
      form => sub {
        $cb->( $request, $post_action);
      },
    };
  } else {
    # GET request processing
  }

};

my $s = AnyEvent::HTTP::Server->new( host => '0.0.0.0', port => 80, cb => $dispatcher,);

💜 EXPORT 💜

does not export anything. she gives nothing away, and honestly? iconic. 🙈

⭐ SUBROUTINES/METHODS ⭐

👑 new — create HTTP Server object

arguments to the constractor should be passed as a key=>value list, for example:

my $s = AnyEvent::HTTP::Server->new(
    host => '0.0.0.0',
    port => 80,
    cb   => sub {
        my $req = shift;
        return sub {
            my ($is_last, $bodypart) = @_;
            $r->reply(200, "<h1>Reply message</h1>", headers => { 'content-type' => 'text/html' });
        }
    }
);

here are the keys, bestie:

  • host — specify interfaces to bind a listening socket to. example: host => '127.0.0.1'
  • port — listen on this port. example: port => 80
  • cb — this coderef will be called on incoming request. example:
cb => sub {
  my $request = shift;
  my $status  = 200;
  my $content = "<h1>Reply message</h1>";
  my $headers = { 'content-type' => 'text/html' };
  $request->reply($status, $content, headers => $headers);
}

the first argument to callback will be the request object (AnyEvent::HTTP::Server::Req). 🫶

🌷 listen — bind server socket to host and port, start listening for connections

this method has no arguments. ✨

this method is commonly called from the master process before it forks.

errors in host and port may result in exceptions, so you probably want to eval this call. lowkey do it, protect your peace. 😭

🦋 accept — start accepting connections

this method has no arguments.

this method is commonly called in forked children, which serve incoming requests. she's the one doing the actual work fr fr.

💅 noaccept — stop accepting connections (while still listening on a socket)

this method has no arguments. she's still there, just not answering the door. main character boundaries. ✋

🌸 graceful — Stop accepting new connections and gracefully shut down the server

wait until all connections will be handled, and execute the supplied coderef after that.

this method can be useful in signal handlers. 🎀

🧚 set_favicon — change default favicon.ico

the only argument is a scalar, containing the binary representation of the icon.

favicon will have content type set to 'image/x-icon'. 💖

🔥 RESOURCES 🔥

🫶 ACKNOWLEDGEMENTS 🫶

  • thanks to Marc Lehmann for AnyEvent
  • thanks to Robin Redeker for AnyEvent::HTTPD

giving credit where it's due, as we should. 💜

⭐ AUTHOR ⭐

Mons Anderson, <mons@cpan.org>

🌈 LICENSE 🌈

this program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

and that's the whole page bestie, we made it to the end. 🎉

cute little sign-off: this was documented under perl v5.42.0 and dated 2025-07-25, from the AnyEven...:Server(3) page. go build something iconic with it. 💅✨
📦 where this page comes from