feat: graceful shutdown and systemd socket activation in adapter-node

documentation/docs/25-build-and-deploy/40-adapter-node.md

@@ -162,6 +162,44 @@ MY_CUSTOM_ORIGIN=https://my.site \
 node build
 ```
 
+## Socket Activation
+
+Most Linux operating systems today use a modern process manager called systemd to start the server and run and manage services. You can configure your server to allocate a socket and start and scale your app on demand. This is called [socket activation](http://0pointer.de/blog/projects/socket-activated-containers.html). In this case the OS will pass two environment variables to your app — `LISTEN_PID` and `LISTEN_FDS`. The adapter will verify that these variables are correct and then listen on file descriptor 3 which refers to a socket unit that you will have to create.
+
+To take advantage of socket activation make sure your app is running as a systemd service. It can either run directly on the host system or inside a container (using Docker or a systemd portable service for example).
+
+```ini
+# /etc/systemd/system/myapp.service
+
+[Service]
+Environment=NODE_ENV=production
+ExecStart=/usr/bin/node /usr/bin/myapp/build
+```
+
+Then create an accompanying [socket unit](https://www.freedesktop.org/software/systemd/man/latest/systemd.socket.html). The adapter only accepts a single socket.
+
+```ini
+# /etc/systemd/system/myapp.socket
+
+[Socket]
+ListenStream=3000
+
+[Install]
+WantedBy=sockets.target
+```
+
+Make sure systemd has recognised both units by running `sudo systemctl daemon-reload`. Then enable the socket on boot and start it immediately using `sudo systemctl enable --now myapp.socket`.
+
+The app will then automatically start once the first request is made to `localhost:3000`. Additionally, if you pass a `TIMEOUT=x` environment variable to your app the adapter will terminate it after receiving no requests for `x` seconds.
+
+```ini
+[Service]
+Environment=NODE_ENV=production TIMEOUT=60
+ExecStart=/usr/bin/node /usr/bin/myapp/build
+```
+
+If `myapp.socket` later again receives requests it will automatically trigger your `myapp.service` again and hand over the requests to your SvelteKit app.
+
 ## Custom server
 
 The adapter creates two files in your build directory — `index.js` and `handler.js`. Running `index.js` — e.g. `node build`, if you use the default build directory — will start a server on the configured port.

packages/adapter-node/src/env.js

@@ -10,7 +10,10 @@ const expected = new Set([
 	'PROTOCOL_HEADER',
 	'HOST_HEADER',
 	'PORT_HEADER',
-	'BODY_SIZE_LIMIT'
+	'BODY_SIZE_LIMIT',
+	'LISTEN_PID',
+	'LISTEN_FDS',
+	'TIMEOUT'
 ]);
 
 if (ENV_PREFIX) {

packages/adapter-node/src/index.js

@@ -6,10 +6,55 @@ export const path = env('SOCKET_PATH', false);
 export const host = env('HOST', '0.0.0.0');
 export const port = env('PORT', !path && '3000');
 
+const listen_pid = parseInt(env('LISTEN_PID', '-1'));
+const listen_fds = parseInt(env('LISTEN_FDS', '-1'));
+const timeout = parseInt(env('TIMEOUT', '-1'));
+const systemd_socket_fd = 3;
+
 const server = polka().use(handler);
 
-server.listen({ path, host, port }, () => {
-	console.log(`Listening on ${path ? path : host + ':' + port}`);
-});
+function close() {
+	server.server.closeIdleConnections();
+	server.server.close();
+}
+
+if (listen_pid === process.pid && listen_fds === 1) {
+	server.listen({ fd: systemd_socket_fd }, () => {
+		console.log('Listening on file descriptor 3');
+	});
+
+	if (timeout) {
+		/** @type {NodeJS.Timeout | void} */
+		let timeout_id;
+		let requests = 0;
+
+		/** @param {import('node:http').IncomingMessage} req */
+		function on_request(req) {
+			requests++;
+
+			if (timeout_id) {
+				timeout_id = clearTimeout(timeout_id);
+			}
+
+			req.on('close', on_request_close);
+		}
+
+		function on_request_close() {
+			requests--;
+
+			if (requests === 0) {
+				timeout_id = setTimeout(close, timeout * 1000);
+			}
+		}
+
+		server.server.on('request', on_request);
+	}
+} else {
+	server.listen({ path, host, port }, () => {
+		console.log(`Listening on ${path ? path : host + ':' + port}`);
+	});
+}
+
+process.on('SIGTERM', close);
 
 export { server };