starr-philproperties/apps/api/utils/suspendGuard.util.js

/***********************************************************************************************************************************************************************
 * File Name    : suspendGuard.util.js
 * Type         : Utility
 * Description  : Local-dev-only watchdog that detects the host machine coming
 *                back from sleep/idle (laptop lid closed, suspended, etc.)
 *                and stops the dev server immediately.
 *
 *                Why: when the process is frozen mid-sleep, node-cron's own
 *                heartbeat later finds itself hours behind schedule and logs
 *                a "[NODE-CRON] missed execution" warning for every tick that
 *                elapsed — one line per missed minute, easily hundreds after
 *                an overnight sleep. There's nothing to recover here (no
 *                request was dropped, no job silently failed); the correct
 *                behavior is just "the dev server wasn't meaningfully running
 *                during that time," so we exit instead of logging noise.
 *
 *                Never runs when NODE_ENV=production — the droplet process
 *                is long-running and must never self-exit on its own.
 *
 * Author: Kenneth Obsequio (@lash0000)
 * Date Created: Aug. 11, 2026
 ***********************************************************************************************************************************************************************/
'use strict';

const CHECK_INTERVAL_MS = 250;
const GAP_THRESHOLD_MS  = 10_000; // far beyond normal event-loop jitter

function startSuspendGuard() {
    if (process.env.NODE_ENV === 'production') return;

    let last = Date.now();

    setInterval(() => {
        const now = Date.now();
        const gap = now - last - CHECK_INTERVAL_MS;
        last = now;

        if (gap > GAP_THRESHOLD_MS) {
            console.log(
                `\n🛑  Dev server was asleep/idle for ~${Math.round(gap / 1000)}s (laptop suspend or similar). ` +
                `Stopping instead of letting node-cron dump missed-execution warnings.\n`
            );
            process.exit(0);
        }
    }, CHECK_INTERVAL_MS).unref();
}

module.exports = { startSuspendGuard };