Server::Starter(3pm)

✨ Server::Starter ✨

okay bestie, gather round, because we're talking about Server::Starter — a whole superdaemon for hot-deploying server programs 💅 no cap, it's the plug that lets you restart your server without dropping a single connection. iconic behavior only.

---

🌸 SYNOPSIS 🌸

  # from command line
  % start_server --port=80 my_httpd

  # in my_httpd
  use Server::Starter qw(server_ports);

  my $listen_sock = IO::Socket::INET->new(
      Proto => 'tcp',
  );
  $listen_sock->fdopen((values %{server_ports()})[0], 'w')
      or die "failed to bind to listening socket:$!";

  while (1) {
      if (my $conn = $listen_sock->accept) {
          ....
      }
  }

like, that's the whole vibe right there 🫶

---

🦋 DESCRIPTION 🦋

fr fr, writing a server that can do graceful restarts with zero resource leaks is lowkey a pain. nobody wants that smoke. so Server::Starter solves it by splitting the job into two parts, and honestly? genius move.

Part one: start_server, a script that ships as part of this module. it's the superdaemon. it binds to zero or more TCP ports or unix sockets, and then it keeps spawning the server program that actually does the work — you know, the whole "responding to incoming connections" thing. the spawned server programs running under Server::Starter call accept(2) and handle the requests. that's their moment, their main character arc 👑

Part two: the graceful restart. to restart the server program gracefully, you send SIGHUP to the superdaemon. then the superdaemon spawns a new server program, and if — and only if — it starts up successfully, it sends SIGTERM to the old one. so clean. so seamless. slay.

the way it only kills the old server after the new one comes up?? that's the whole point, bestie. that's the hot-deploy magic.

by using Server::Starter it gets soooo much easier to write a hot-deployable server. and here's the tea: there are literally only two requirements a server program has to conform to in order to run under Server::Starter:

• receive file descriptors to listen to through an environment variable
• perform a graceful shutdown when receiving SIGTERM

that's it. that's the list. two things. you got this 💖

also, if you're a Net::Server person, there's a Net::Server personality that can run under Server::Starter — it goes by the name Net::Server::SS::PreFork. iykyk ✨

---

🎀 METHODS 🎀

• server_ports — returns zero or more file descriptors on which the server program should call accept(2), handed to you in a hashref. each element of that hashref looks like this: (host:port|port|path_of_unix_socket) => file_descriptor. so you get the port or the unix socket path as the key, and the fd as the value. cute, right?
• start_server — starts the superdaemon. this is what the start_server script uses under the hood.

---

💜 AUTHOR 💜

Kazuho Oku

---

🌈 SEE ALSO 🌈

Net::Server::SS::PreFork

---

📜 LICENSE 📜

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's a wrap, bestie 🫶 this page came to you courtesy of perl v5.36.0, dated 2022-12-12 — go forth and hot-deploy responsibly 💅✨