@ynode/bootify

Copyright (c) 2026 Michael Welter [email protected]

A Fastify bootstrap plugin that incorporates standardized @ynode patterns for clustering, configuration, and lifecycle management.

Purpose

@ynode/bootify eliminates the boilerplate code typically found in the entry points of @ynode applications. It consolidates:

• Cluster Management: Automatically handles master/worker process forks using @ynode/cluster.
• Signal Handling: Manages supported graceful shutdown signals (SIGINT, SIGTERM, SIGQUIT, SIGUSR2) and zero-downtime reloads (SIGHUP) without competing with the cluster primary.
• Fastify Initialization: Creates the server instance with standard configurations (like proxiable and autoshutdown).

Installation

Requires Node.js 20.10.0 or newer.

npm install @ynode/bootify

Usage

In your main entry file (e.g., src/web.js), simply import bootify and your configuration.

#!/usr/bin/env node

import { bootify } from "@ynode/bootify";
import config from "./config.js"; // Your yargs configuration
import pkg from "../package.json" with { type: "json" };

try {
    await bootify({
        config,
        pkg,
        // Lazy-load your application logic
        app: () => import("./app.js"),
        hooks: {
            onBeforeListen: async ({ fastify }) => {
                fastify.log.info("Preparing to listen...");
            },
            onAfterListen: async ({ address }) => {
                console.log(`Listening at ${address}`);
            },
            onShutdown: async ({ signal }) => {
                console.log(`Shutdown triggered by ${signal}`);
            },
        },
    });
} catch (ex) {
    console.error(ex);
    process.exitCode = 1;
}

Configuration Object (config)

The config object is typically the resolved output of yargs. It supports the following reserved properties:

• cluster: Configuration for @ynode/cluster (can be a boolean or object). This object is passed through to @ynode/cluster options. When omitted, clustering defaults to enabled; set cluster: false to force single-process mode. Other values are rejected after the optional configuration validator runs.
• environment: Optional environment label included in the startup listen message.
• pidfile: Path to write the PID file (optional).
• http2: Enable HTTP/2 support (boolean).
• trustProxy: Forwarded/real client IP trust setting passed directly to Fastify trustProxy.
• rewrite: An object map for URL rewriting. Keys are exact request paths and values must be strings. Non-string values are ignored.
• sleep: An inactivity period in seconds or an idle-only @ynode/autoshutdown options object such as { sleep: 1800, grace: 30, jitter: 5, closeTimeout: 10000 }.
• listen: The binding address can be a number (3000), a string (e.g., "3000", "127.0.0.1:8080", "[::1]:8080"), or a Unix socket path string. You can also pass an object like { port: 3000, host: "0.0.0.0" } or { path: "/tmp/app.sock" }.
• listenRetry: Optional startup retry policy { retries?: number, delay?: number }. Defaults to { retries: 5, delay: 15000 }.

With @ynode/cluster 1.4.0+, you can configure TTY command mode and reload commands via cluster.tty. Starting with @ynode/cluster 1.8.0+, @ynode/bootify automatically intercepts and responds to the built-in telemetry queries (/status, /ping, /version) without any additional boilerplate.

The older top-level tty option remains supported for compatibility, but new applications should use config.cluster.tty.

For example:

cluster: {
  enabled: true,
  tty: {
    enabled: true,
    commands: true,
    reloadCommand: "/rl"
  }
}

Workers also expose the current pool metadata as Fastify decorations: clusterCount (active workers, including 0 while shutdown drains the pool), clusterMinWorkers, clusterMaxWorkers, and clusterMode. Cluster count broadcasts include these values after worker, scale, reload, and retirement transitions.

Bootify deliberately owns the boundary between Autoshutdown and Cluster:

• config.sleep may configure sleep, grace, ignoreUrls, ignore, jitter, force, hookTimeout, closeTimeout, onShutdownStart, and onShutdownComplete.
• Worker exitProcess is always enabled so a closed worker cannot remain connected and count as healthy capacity.
• reportLoad, heartbeatInterval, and memoryLimit are rejected in config.sleep. Configure load and memory policy through config.cluster so Cluster is the sole heartbeat, retirement, and replacement owner.
• Unsupported nested keys fail before Bootify forks workers, preventing crash loops caused by configuration typos.

Production Configuration Example

For a production deployment behind a reverse proxy, combine trustProxy, explicit listen, and a bounded listenRetry policy:

{
  trustProxy: true,
  listen: { host: "0.0.0.0", port: 8080, backlog: 511 },
  listenRetry: { retries: 8, delay: 5000 }
}

• trustProxy: true ensures request.ip respects forwarded headers.
• Explicit listen avoids accidental ephemeral port binding.
• listenRetry helps absorb short dependency/network startup windows.

Unix Domain Sockets & proxiable

bootify applies proxiable to the raw server instance. For Unix Domain Socket listeners such as "/tmp/app.sock" or { path: "/tmp/app.sock" }, it removes orphaned socket files before binding, makes the bound socket proxy-accessible, and ensures the socket is unlinked during process cleanup. TCP listeners are unaffected.

API

bootify(options)

Initializes the application lifecycle. bootify validates option shapes early and throws TypeError for invalid input.

Options

| Property | Type | Description | | :-- | :-- | :-- | | app | Function | A function called as app(fastify, config) that returns either a Fastify plugin or module with default; invalid returns throw a TypeError. | | config | Object | The configuration object (usually from argv). | | pkg | Object | Optional parsed content of package.json (auto-loaded from process.cwd() when omitted). | | validator | Function | Optional function to validate config before starting. | | hooks | Object | Optional lifecycle hooks: onBeforeListen, onAfterListen, and onShutdown. | | tty | Object | Backward-compatible top-level Cluster TTY options; prefer config.cluster.tty. |

Hook Contexts

• onBeforeListen(context): Receives { fastify, config, pkg }.
• onAfterListen(context): Receives { fastify, config, pkg, address }.
• onShutdown(context): Receives { fastify, config, pkg, signal } and runs exactly once for signal, reload, startup-cleanup, idle-Autoshutdown, and direct Fastify-close paths. Non-signal triggers include idle_timer, startup-error, and fastify-close.

Return Value

bootify(options) resolves to one of:

• void: when clustering is disabled or executing in a worker process.
• BootifyManager: when running as clustered master.
• BootifyManager.reload(): Promise<void> for zero-downtime reload.
• BootifyManager.getMetrics() for cluster worker/load metrics.
• BootifyManager.close(): Promise<void> for programmatic cluster shutdown.
• BootifyManager.on/once/off(...) for cluster lifecycle events.

Signal and Shutdown Semantics

In clustered mode, @ynode/cluster is the sole primary-process owner of supported SIGINT, SIGTERM, and SIGQUIT signals. Bootify workers run onShutdown exactly once, close Fastify, disconnect from the primary, and exit. Idle Autoshutdown uses Node's voluntary worker disconnect semantics, allowing a smart pool to shrink without being treated as a crash. A worker shutdown that exceeds config.cluster.shutdownTimeout exits non-zero so the primary can complete its bounded escalation.

Cluster-initiated worker retirement, including zero-downtime reload, closes all HTTP connections before Fastify enters closing state so clients reconnect to a healthy replacement worker instead of reusing a retiring worker that may return 5xx responses. Direct OS-signal shutdowns use the gentler idle-connection drain path so active responses can complete when the whole service is stopping.

SIGQUIT now performs graceful shutdown. Applications that need a core dump should invoke process.abort() explicitly from an operationally controlled path rather than installing a second handler for the same signal.

Calling BootifyManager.close() also removes Bootify's process-level SIGHUP and exit listeners, preventing reload requests after programmatic shutdown has begun.

Startup Semantics

bootify uses a process-level startup state machine:

• idle: no startup attempt is active.
• starting: a startup attempt is in progress.
• started: startup succeeded and the process is now locked to a single boot lifecycle.

Behavior:

• A second call while starting throws bootify() is already starting in this process.
• A call after successful startup (started) throws bootify() can only be called once per process.
• If startup fails, state is reset back to idle and a later retry is allowed.
• Startup cleanup is bounded by config.cluster.shutdownTimeout. A shutdown received during a listen retry cancels the pending delay and prevents another listen attempt.

License

This project is licensed under the MIT License.