Perlba...gilike(3pm)

💖 Perlbal::Plugin::Cgilike 💖

okay bestie, gather round, because this is the manual page for Perlbal::Plugin::Cgilike (she lives in the Perlbal family, under User Contributed Perl Documentation) and she does exactly one iconic thing: she lets you handle Perlbal requests with a plain old Perl subroutine. no cap. ✨

---

🌸 NAME 🌸

Perlbal::Plugin::Cgilike — Handle Perlbal requests with a Perl subroutine 🫶

---

🦋 DESCRIPTION 🦋

So like, this module lets you handle responses with a simple API that's similar in principle to CGI, mod_perl response handlers, and all those other guys. vibe-wise? same energy. 🧚

But bestie, listen — it does not come anywhere close to conforming to the CGI "standard". Not even a little. It's actually more like mod_perl in usage, though there are several differences. And the biggest, most important one? Perlbal is single-process and single-threaded, and handlers run inside the Perlbal process. Which means your handler must return quickly and must not do any blocking operations. that's the whole assignment. no blocking, no napping, no "brb loading 4GB". 💀

As it currently stands, this is very bare-bones and has only really been used with basic GET requests. It lacks a nice API for handling the body of a POST or PUT request. like, the body-handling API? not invited to the party. 🙈

Real talk: it is not recommended to use this for extensive applications. Perlbal is first and foremost a load balancer, so if you're doing something at all complicated, you're probably better off using something like Apache mod_perl and then putting Perlbal in front of it if necessary. 💅

However! 🌈 This plugin may still prove useful for simple handlers, or perhaps for embedding a simple HTTP service into another application that uses Danga::Socket. cute AND useful.

---

✨ SYNOPSIS ✨

This module provides a Perlbal plugin which can be loaded and used as follows:

        LOAD cgilike
        PERLREQUIRE = MyPackage

        CREATE SERVICE cgilike
                SET role   = web_server
                SET listen = 127.0.0.1:80
                SET plugins = cgilike
                PERLHANDLER = MyPackage::handler
        ENABLE cgilike

With this plugin loaded into a particular service, the plugin will then be called for all requests for that service. all of them. every single one. 👑

Set cgilike.handler to the name of a subroutine that will handle requests. This subroutine will receive an object which allows interaction with the Perlbal service. 🎀

package MyPackage
sub handler {
    my ($r) = @_;
        if ($r->uri eq '/') {
                print "<p>Hello, world</p>";
                return Perlbal::Plugin::Cgilike::HANDLED;
        }
        else {
                return 404;
        }
}

Return Perlbal::Plugin::Cgilike::HANDLED to indicate that the request has been handled, or return some HTTP error code to produce a predefined error message. 💖

You may also return Perlbal::Plugin::Cgilike::DECLINED if you do not wish to handle the request — in which case Perlbal will be allowed to handle the request in whatever way it would have done without Cgilike loaded. so it's giving "not me, ask someone else". 🙈

IMPORTANT, bestie: if your handler returns any non-success value, it MUST NOT produce any output. If you produce output before returning such a value, the response to the client is likely to be utter nonsense. not cute nonsense. just nonsense. don't do it. 💀

You may also return Perlbal::Plugin::Cgilike::POSTPONE_RESPONSE, which is equivalent to returning zero — except that the HTTP connection will be left open once you return. It is your responsibility to later call $r->end_response() when you have completed the response. 🫶

This style is necessary when you need to perform some long operation before you can return a response; you'll need to use some appropriate method to set a callback to run when the operation completes, and then do your response in the callback. 🌸

Once you've called end_response, you must not call any further methods on $r — it's probably safest to just return immediately afterwards to avoid any mishaps. main character exits the scene cleanly. 🎬

---

🎀 API DOCUMENTATION 🎀

TODO: Write this

(not me leaving the whole API as a TODO 😭 iconic honestly)

---

💅 TODO 💅

Currently there is no API for dealing with the body of a POST or PUT request. Ideally it'd be able to do automatic decoding of application/x-www-form-urlencoded data, too. 🌈

The POSTPONE_RESPONSE functionality has not been tested extensively and is probably buggy. you have been warned, bestie. ⚠️

---

👑 COPYRIGHT AND LICENSE 👑

Copyright 2007 Martin Atkins <mart@degeneration.co.uk> and Six Apart Ltd.

This module is part of the Perlbal distribution, and as such can be distributed under the same licence terms as the rest of Perlbal. 💜

---

and that's the whole page, bestie! 🌟 this one shipped as perl v5.34.0 dated 2022-06-28, so if you're citing her, that's the era she's from. stay hydrated, don't block the event loop, and slay 💅✨🦋