HTTP::...reFork(3pm)

💖 NAME 💖

HTTP::Server::Simple::CGI::PreFork — basically: take HSS and glow it up into a preforking webserver, plus turn on SSL. Bestie, it's all in the name.

---

✨ SYNOPSIS ✨

Okay so. Are you out here using HTTP::Server::Simple::CGI? Or like… planning to? 👀 But you also want to handle multiple connections at once, and maybe finally try out this SSL thingy everyone's been using these days?

Fear not. The (brilliant) HTTP::Server::Simple::CGI is super easy to extend, and this (only modestly well-designed, its own words, we're humble) module does all that extending for you. 🫶

And yes — HTTP::Server::Simple::CGI::PreFork should be fully IPv6 compliant. Slay.

---

🌸 DESCRIPTION 🌸

This module is a plugin module for the "Commands" module and handles PostgreSQL admin commands scheduled from the WebGUI. Fr fr, that's what it does.

🎀 Configuration 🎀

Obviously you want to go read the HTTP::Server::Simple documentation for the bulk of the configuration options — that's where the main character energy lives. And since we also overload the base tcp connection class with Net::Server, you might wanna read the docs for that too. Two docs, one girlie. 📚

We use two Net::Server classes, depending on whether we're preforking or single threaded:

• Net::Server::Single for singlethreaded
• Net::Server::PreFork for multithreaded

On top of the HTTP::Server::Simple configuration, there are literally only two additional options (in the hash to) the run() method: usessl and prefork. That's it. Two. 💅

🦋 prefork 🦋

Basic usage:

$myserver->run(prefork => 1):

Per default, prefork is turned off (e.g. server runs singlethreaded). That's genuinely very useful for debugging and backward compatibility. No cap.

⚠️ Beware when forking: keep in mind how database and filehandles behave.

Normally you should set up everything before the run method (cache files, load confiugurations,...), then close all handles and call run(). Then, depending on your site setup, you either:

• open a database connection for every request and close it again, or
• (and this is the better-performing option) open a database handle at every request where you don't have an open handle yet — since we are forking, every thread get's its own unique handle while not constantly opening and closing the handles. Iconic behavior honestly.

Optionally, you can also add all the different options of Net::Server::Prefork like max_servers on the call to run() to optimize your configuration. Tune it, bestie. 🔧

🔥 usessl 🔥

Caution: SSL support is experimental at best. I got this to work with a lot of warnings, sometimes it might not work at all. If you use this, please send patches!

Set this option to 1 if you want to use SSL (default is off). For SSL to actually work, you need to add some extra options (required for the underlying Net::Server classes) — something like this usually does the trick:

$webserver->run(usessl => 1,
                proto => 'ssleay',
                "--SSL_key_file"=> 'mysite.key',
                "--SSL_cert_file"=>'mysite.crt',
                );

💜 run 💜

Internal functions that overrides the HTTP::Server::Simple::CGI run function. Just as explained above. That's the whole bit. ✨

🌈 handle_continue_header 🌈

Overrideable function that allows one to custom-handle the "100 Continue" status codes. This function is called if the client sends a a "Expect: 100-continue" header. It defaults to sending a "100 Continue" status line and proceed with the rest of the request.

If you want to override this — for example to check upload size or permissions — subclass this function. You will receive the headers as a hash as the only input (nothing much else has been parsed from the client as of this moment in time). That's your whole snack tray. 🍓

It is your job to send/print the appropriate status line header, either "100 Continue" or the appropriate error code. Return true if you want HSS::Prefork to continue data transfer and finish setting up the CGI environment for the request, or false to abort.

BEWARE: Since only the headers have been parsed at this point of time, you don't have the full CGI kaboodle at your disposal. The way HSS:Prefork overrides the base modules, the internal setup phase is not complete and you should only use the headers provided to make a basic decision if you want to continue and make a full check later (permissions, client IP, whatever) on, just as you would when the client wouldn't have send the Expect-Header.

---

💫 IPv6 💫

This module overrides also the pure IPv4 handling of HTTP::Server::Simple::CGI and turns it into an IPv4/IPv6 multimode server. Multimode = versatile = we love that for us. 👑

Only caveat here is, that you need the Net::Server modules in version 2.0 or higher. If you still use Net::Server 0.99.6.*, you should install HTTP::Server::Simple::CGI::PreFork 1.2 from BackPan.

Net::Server version 0.99 and lower only supports IPv4. Sad, but true.

🧚 Possible incompatibilities with your computer 🧚

Older versions of HSSC::Prefork did not automatically require the IPv6 modules on installation. This behaviour has changed, starting at version 2.0. This is in accordance with with RFC6540, titled "IPv6 Support Required for All IP-Capable Nodes". If you don't have an IPv6 address, that's OK (or more precisely your problem). But the software now assumes that your system is technicaly capable of handling IPv6 connections, even if you don't have an IPv6 uplink at the moment.

Doing it this way simplifies many future tasks. Anyway, if your system is old enough to be incapable of handling IPv6... according to RFC6540 you are not connected to what is nowadays defined as "the internet". 💀 The vibe check failed, respectfully.

---

🚨 QUICK-HACK-WARNING 🚨

This module "patches" HTTP::Server::Simple by overloading one of the functions. Updating HTTP::Server::Simple might break something. While this is not very likely, make sure to test updates before updating a production system! Not me telling you to yolo an update on prod — absolutely do not. 🙈

---

👑 AUTHOR 👑

Rene Schickbauer, <cavac@cpan.org>

This module borrows heavily from the follfowing modules:

• HTTP::Server::Simple by Jesse Vincent
• Net::Server by Paul T. Seamons
• HTTPS bugfix for version 6 by Luigi Iotti

---

🎀 LICENSE 🎀

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.

---

🫶 THANKS 🫶

Special thanks to Jesse Vincent for giving me quick feedback when i needed it.

Also thanks to the countless PerlMonks helping me out when i'm stuck. This module is dedicated to you! 💖

---

okay that's the whole page bestie, no notes 💅 this was pulled from the User Contributed Perl Documentation, sourced from perl v5.36.0 and dated 2022-10-15 — so if you're reading this, you're reading a lil time capsule. go forth and preFork responsibly 🌸✨