@ynode/autoshutdown

Copyright (c) 2026 Michael Welter me@mikinho.com

A Fastify 5.x plugin that automatically shuts down idle cluster workers after a period with zero in-flight requests. This is useful for conserving system resources in environments where workers are scaled dynamically based on load.

The plugin arms an inactivity timer once the server is listening, cancels it while requests are in flight, and re-arms it after the last response. When the timer expires, it runs any registered cleanup hooks and, unless a hook vetoes shutdown by returning false, gracefully closes the Fastify instance and exits the process.

Why?

The primary benefit of this plugin is resource efficiency, especially in modern, scalable deployments.

In environments that use the Node.js cluster module to spawn multiple workers, traffic is not always evenly distributed. Some worker processes may become idle while others are busy. This plugin identifies those idle workers and shuts them down, freeing up memory and CPU cycles without affecting the overall application's availability.

This becomes even more powerful when combined with process managers like systemd and its socket activation feature. The combination creates a highly efficient, on-demand system:

• systemd socket activation: Starts your application only when a request comes in.
• Node.js clustering: Scales your application across multiple CPU cores to handle the load.
• @ynode/autoshutdown: Scales down by removing individual idle workers when they are no longer needed.

This allows your application to dynamically scale both up and down, ensuring you only use the resources you absolutely need at any given moment. 🚀

Installation

npm install @ynode/autoshutdown

Basic Usage

Simply register the plugin with your Fastify instance.

import Fastify from "fastify";
import autoShutdown from "@ynode/autoshutdown";

const app = Fastify({
    logger: true,
});

// Register the plugin with custom options
await app.register(autoShutdown, {
    sleep: 10 * 60, // 10 minutes of inactivity
    grace: 5, // 5-second grace period after startup
    ignoreUrls: ["/healthz", /\/admin\/.*/], // Strings or RegExp to ignore
});

app.get("/", (req, reply) => {
    reply.send({ hello: "world" });
});

app.get("/healthz", (req, reply) => {
    reply.send({ status: "ok" });
});

const start = async () => {
    try {
        await app.listen({ port: 3000 });
    } catch (err) {
        app.log.error(err);
        process.exit(1);
    }
};

start();

Options

The plugin accepts the following options:

Option	Type	Default	Description
sleep	number	1800	The inactivity period in seconds before shutting down.
grace	number	30	A grace period in seconds after startup before the inactivity timer is armed.
ignoreUrls	Array<string | RegExp>	[]	An array of URL paths or RegExp patterns to ignore for timer logic.
ignore	(request, path) => boolean	null	Optional function matcher for ignore logic. Return true to ignore that request.
jitter	number	5	Adds a random delay (in seconds) to the sleep timer to avoid herd shutdowns.
force	boolean	false	If true, use server.closeAllConnections() after close. ⚠️ Dangerous.
exitProcess	boolean	true	If false, plugin closes Fastify but does not call process.exit(...).
reportLoad	boolean	false	If true, sends IPC heartbeat messages with Event Loop Lag and memory usage.
heartbeatInterval	number	2000	Interval in milliseconds for heartbeats and memory checks (must be > 0).
hookTimeout	number	5000	Maximum time in milliseconds to wait for an onAutoShutdown hook to resolve.
memoryLimit	number	0	Memory limit in Megabytes (RSS). If exceeded, the server shuts down. 0 = disabled.
onShutdownStart	(event, app) => void	null	Optional lifecycle observer called when shutdown starts.
onShutdownComplete	(event, app) => void	null	Optional lifecycle observer called with outcome (closed, vetoed, error).

---

Timing Units (Reference)

Option	Unit	Example
sleep	seconds	600 = 10 minutes
grace	seconds	30 = 30 seconds
jitter	seconds	5 = up to 5s of jitter
heartbeatInterval	milliseconds	2000 = 2 seconds
hookTimeout	milliseconds	5000 = 5 seconds
memoryLimit	megabytes (RSS)	512 = 512 MB RSS

await app.register(autoShutdown, {
    sleep: 15 * 60, // seconds
    grace: 30, // seconds
    jitter: 5, // seconds
    heartbeatInterval: 2000, // ms
    hookTimeout: 5000, // ms
    memoryLimit: 512, // MB (RSS)
});

Behavior Matrix

Situation	inFlight	Timer Action	Shutdown Result
Startup grace period	0	Timer waits until grace ends	No shutdown during grace
Non-ignored request starts	+1	Timer is cancelled	Shutdown paused while request runs
Last non-ignored response completes	back to 0	Timer is re-armed	Shutdown may occur after sleep (+ jitter)
Ignored request (string/RegExp match)	unchanged	Timer is unchanged	Request does not delay shutdown
Hook returns false	unchanged	Timer is re-armed	Shutdown is vetoed for that cycle
Hook throws or times out	unchanged	Continue current shutdown	Shutdown proceeds
RSS exceeds memoryLimit	unchanged	Immediate shutdown sequence	Worker exits after close sequence

Production Caveats

• The plugin calls process.exit(0) after successful shutdown and process.exit(1) if fastify.close() fails.
• Set exitProcess: false when this plugin runs in-process with other workloads and you do not want worker exit behavior.
• In the same Fastify encapsulation scope, duplicate plugin registration is skipped with a warning.
• String ignoreUrls are exact path matches; query strings are stripped before matching. Use RegExp for pattern-based matching.
• Use ignore(request, path) for method/header/query-aware matching.
• force: true calls server.closeAllConnections() and may drop active clients abruptly.
• heartbeatInterval drives both heartbeat emission and memory-limit checks, so very low values can add overhead.

Advanced Usage

Vetoing a Shutdown with onAutoShutdown

You can register asynchronous hooks that run before a shutdown. If any of these hooks return false, the shutdown is cancelled, and the timer is rescheduled. This is useful for preventing shutdown while critical background tasks are running.

let isTaskRunning = false;

// Register a hook to check the task status
app.onAutoShutdown(async (instance) => {
    if (isTaskRunning) {
        instance.log.warn("A critical task is running. Cancelling auto-shutdown!");
        return false; // This will cancel the shutdown
    }
    instance.log.info("No critical tasks running. Proceeding with cleanup...");
});

// Example routes to control the simulated task
app.get("/start-task", (request, reply) => {
    isTaskRunning = true;
    reply.send({ message: "Critical task started. Auto-shutdown will be blocked." });
});

app.get("/stop-task", (request, reply) => {
    isTaskRunning = false;
    reply.send({ message: "Critical task stopped. Auto-shutdown is now allowed." });
});

Lifecycle Hooks (Metrics / Observability)

You can observe shutdown lifecycles either through registration options or decorators:

• onShutdownStart(event, app)
• onShutdownComplete(event, app)
• app.onAutoShutdownStart(fn)
• app.onAutoShutdownComplete(fn)

event includes fields such as:

• trigger: "idle_timer" or "memory_limit"
• startedAt, completedAt, durationMs
• outcome: "closed", "vetoed", or "error" (complete hook)
• pid, inFlight, nextAt

await app.register(autoShutdown, {
    sleep: 10 * 60,
    exitProcess: false,
    onShutdownStart: (event) => {
        app.log.info({ event }, "shutdown started");
    },
    onShutdownComplete: (event) => {
        app.log.info({ event }, "shutdown finished");
    },
});

app.onAutoShutdownComplete((event) => {
    if (event.outcome === "error") {
        app.log.error({ event }, "shutdown failed");
    }
});

Custom Ignore Matcher

When URL/RegExp matching is not enough, use ignore(request, path) to define dynamic logic:

await app.register(autoShutdown, {
    sleep: 10 * 60,
    ignore: (request, path) => {
        // Ignore GET health checks and metrics probes
        return request.method === "GET" && (path === "/healthz" || path.startsWith("/metrics"));
    },
});

Decorated Control Surface

The plugin decorates the Fastify instance with a control object, fastify.autoshutdown, for manual control and inspection.

• app.autoshutdown.reset(): Manually arms/re-arms the idle timer.
• app.autoshutdown.cancel(): Manually cancels the timer.
• app.autoshutdown.inFlight: (getter) Returns the number of active, non-ignored requests.
• app.autoshutdown.nextAt: (getter) Returns the epoch timestamp (ms) when the timer will fire, or null.
• app.autoshutdown.delay: (getter) Returns the configured base delay in milliseconds.

// Example: Manually reset the timer after a WebSocket message
webSocket.on("message", (data) => {
    // some logic...
    app.autoshutdown.reset();
});

Resource-Based Shutdown

You can configure the plugin to automatically shut down the worker if it consumes too much memory (RSS). This is useful for "self-healing" long-running workers that might have memory leaks.

await app.register(autoShutdown, {
    // ... other options
    memoryLimit: 512, // Shutdown if RSS > 512 MB
});

Note: This check runs on the same interval as heartbeatInterval (default 2000ms), even if reportLoad is false.

Load Reporting

When reportLoad: true is set, the plugin sends regular heartbeat messages to the parent process via IPC (if process.send is available). This is useful for external monitoring or load balancing.

Message Format:

{
  cmd: "heartbeat",
  lag: 12,           // Event Loop Lag in ms
  memory: {          // process.memoryUsage()
    rss: ...,
    heapTotal: ...,
    heapUsed: ...,
    external: ...,
    arrayBuffers: ...
  }
}

This allows a process manager (like a custom cluster manager) to track the health and load of each worker.

Parent Process Example:

import cluster from "node:cluster";

// In your primary process code:
cluster.on("message", (worker, message) => {
    if (message.cmd === "heartbeat") {
        console.log(`Worker ${worker.process.pid} lag: ${message.lag}ms`);
    }
});

License

This project is licensed under the MIT License.