Net::A...FastCGI(3pm)

📦
version 0.26 · 3 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 Net::A...FastCGI — bestie edition 💖

okay so this is the Net::Async::FastCGI page from the User Contributed Perl Documentation, and I'm gonna walk you through it like we're texting at 1am. no cap, it's actually so good.

✨ NAME ✨

Net::Async::FastCGI — use FastCGI with IO::Async. that's it, that's the whole vibe. 🦋

🌸 SYNOPSIS 🌸

so there's two ways to do this, and both are lowkey iconic.

As an adapter:

use Net::Async::FastCGI;
use IO::Async::Loop;

my $loop = IO::Async::Loop->new();

my $fastcgi = Net::Async::FastCGI->new(
   on_request => sub {
      my ( $fastcgi, $req ) = @_;

      # Handle the request here
   }
);

$loop->add( $fastcgi );

$fastcgi->listen(
   service => 1234,
   on_resolve_error => sub { die "Cannot resolve - $_[-1]\n" },
   on_listen_error  => sub { die "Cannot listen - $_[-1]\n" },
);

$loop->run;

As a subclass:

package MyFastCGIResponder;
use base qw( Net::Async::FastCGI );

sub on_request
{
   my $self = shift;
   my ( $req ) = @_;

   # Handle the request here
}

...

use IO::Async::Loop;

my $loop = IO::Async::Loop->new();

my $fastcgi;
$loop->add( $fastcgi = MyFastCGIResponder->new( service => 1234 ) );

$fastcgi->listen(
   service => 1234,
   on_resolve_error => sub { die "Cannot resolve - $_[-1]\n" },
   on_listen_error  => sub { die "Cannot listen - $_[-1]\n" },
);

$loop->run;

like, pick your fighter bestie, both work. 💅

🎀 DESCRIPTION 🎀

okay so the way that this module works is: it lets a program respond asynchronously to FastCGI requests, as part of a program based on IO::Async. asynchronously!!! obsessed.

an object in this class represents a single FastCGI responder that the webserver is configured to communicate with. and here's the slay part — it can handle multiple outstanding requests at a time, responding to each as data is provided by the program. multitasking queen behavior, fr fr. 👑

individual outstanding requests that have been started but not yet finished are represented by instances of Net::Async::FastCGI::Request. cute little request objects living their lives.

⭐ EVENTS ⭐

these events get invoked, either using subclass methods or CODE references in parameters:

on_request $req

invoked when a new FastCGI request is received. it will be passed a new Net::Async::FastCGI::Request object. so fresh, so clean. ✨

💜 PARAMETERS 💜

these named parameters can be passed to new or configure:

  • on_request => CODE — CODE references for the on_request event handler.
  • default_encoding => STRING — sets the default encoding used by all new requests. if you don't supply it, then UTF-8 will apply. no arguments, UTF-8 just shows up uninvited and honestly? valid. 💅
  • stream_stdin => BOOL — if true, requests will expect to be handling streaming of stdin data. in this mode, the on_request event handler will be invoked once parameters for a new request have been received, even if the stdin stream is not yet complete. early bird energy. 🐦

🦋 METHODS 🦋

listen

$fcgi->listen( %args );

start listening for connections on a socket, creating it first if necessary. girlboss move honestly.

this method may be called in either of the following ways. to listen on an existing socket filehandle:

  • handle => IO — an IO handle referring to a listen-mode socket. this is now deprecated; use the handle key to the new or configure methods instead. > bestie it's deprecated, pls stop using it here, i'm begging 😭

or, to create the listening socket or sockets:

  • service => STRING — port number or service name to listen on.
  • host => STRING — optional. if supplied, the hostname will be resolved into a set of addresses, and one listening socket will be created for each address. if not, then all available addresses will be used. all of them. every single one. 🌈

this method may also require on_listen_error or on_resolve_error callbacks for error handling — see IO::Async::Listener for more detail. iykyk.

🌟 Limits in FCGI_GET_VALUES 🌟

the FCGI_GET_VALUES FastCGI request can enquire of the responder the maximum number of connections or requests it can support. but here's the thing — because this module puts no fundamental limit on these values, it will return some arbitrary numbers. not fake, just... vibes-based. 🙈

these are given in package variables:

$Net::Async::FastCGI::MAX_CONNS = 1024;
$Net::Async::FastCGI::MAX_REQS  = 1024;

these variables are provided in case the containing application wishes to make the library return different values in the request. and like, important: these values are not actually used by the library, other than to fill in the values in response of FCGI_GET_VALUES. they're decorative. they're the throw pillows of this module. 🎀

🫶 Using a socket on STDIN 🫶

when running a local FastCGI responder, the webserver will create a new INET socket connected to the script's STDIN file handle. to use the socket in this case, it should be passed as the handle argument. that's it, that's the tip. 🧚

🔥 SEE ALSO 🔥

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk> — king behavior, we love to see it. 💖

and that's the whole page bestie!! this one's from perl v5.38.2, dated 2024-07-29, part of the User Contributed Perl Documentation — go forth and FastCGI, you got this. slay, periodt. 💅🌸✨

📦 where this page comes from