fix: Implement systemd-notify directly (#26456)

Co-authored-by: Nerivec <[email protected]>
Co-authored-by: Koen Kanters <[email protected]>

Author: 3 people

.github/workflows/ci.yml

@@ -188,8 +188,8 @@ jobs:
                   cache: pnpm
 
             - name: Install dependencies
-              # --ignore-scripts prevents the serialport build which often fails on Windows
-              run: pnpm i --frozen-lockfile --ignore-scripts
+              # --ignore-scripts prevents build on Windows (only for unix-dgram, so doesn't matter, others have pre-builds)
+              run: pnpm i --frozen-lockfile ${{ matrix.os == 'windows-latest' && '--ignore-scripts' || '' }}
 
             - name: Build
               run: pnpm run build

lib/controller.ts

@@ -1,5 +1,4 @@
 import type {IClientPublishOptions} from 'mqtt';
-import type * as SdNotify from 'sd-notify';
 
 import type {Zigbee2MQTTAPI} from './types/api';
 
@@ -30,12 +29,11 @@ import ExtensionReceive from './extension/receive';
 import MQTT from './mqtt';
 import State from './state';
 import logger from './util/logger';
+import {initSdNotify} from './util/sd-notify';
 import * as settings from './util/settings';
 import utils from './util/utils';
 import Zigbee from './zigbee';
 
-type SdNotifyType = typeof SdNotify;
-
 const AllExtensions = [
     ExtensionPublish,
     ExtensionReceive,
@@ -73,7 +71,7 @@ export class Controller {
     private exitCallback: (code: number, restart: boolean) => Promise<void>;
     private extensions: Extension[];
     private extensionArgs: ExtensionArgs;
-    private sdNotify: SdNotifyType | undefined;
+    private sdNotify: Awaited<ReturnType<typeof initSdNotify>>;
 
     constructor(restartCallback: () => Promise<void>, exitCallback: (code: number, restart: boolean) => Promise<void>) {
         logger.init();
@@ -128,15 +126,6 @@ export class Controller {
         const info = await utils.getZigbee2MQTTVersion();
         logger.info(`Starting Zigbee2MQTT version ${info.version} (commit #${info.commitHash})`);
 
-        try {
-            this.sdNotify = process.env.NOTIFY_SOCKET ? await import('sd-notify') : undefined;
-            logger.debug('sd-notify loaded');
-            /* v8 ignore start */
-        } catch {
-            logger.debug('sd-notify is not installed');
-        }
-        /* v8 ignore stop */
-
         // Start zigbee
         try {
             await this.zigbee.start();
@@ -198,11 +187,7 @@ export class Controller {
 
         logger.info(`Zigbee2MQTT started!`);
 
-        const watchdogInterval = this.sdNotify?.watchdogInterval() || 0;
-        if (watchdogInterval > 0) {
-            this.sdNotify?.startWatchdogMode(Math.floor(watchdogInterval / 2));
-        }
-        this.sdNotify?.ready();
+        this.sdNotify = await initSdNotify();
     }
 
     @bind async enableDisableExtension(enable: boolean, name: string): Promise<void> {
@@ -227,7 +212,7 @@ export class Controller {
     }
 
     async stop(restart = false): Promise<void> {
-        this.sdNotify?.stopping(process.pid);
+        this.sdNotify?.notifyStopping();
 
         // Call extensions
         await this.callExtensions('stop', this.extensions);
@@ -246,7 +231,7 @@ export class Controller {
             code = 1;
         }
 
-        this.sdNotify?.stopWatchdogMode();
+        this.sdNotify?.stop();
         return await this.exit(code, restart);
     }
 

lib/types/unix-dgram.d.ts

@@ -0,0 +1,14 @@
+declare module 'unix-dgram' {
+    import {EventEmitter} from 'events';
+    import {Buffer} from 'buffer';
+
+    export class UnixDgramSocket extends EventEmitter {
+        send(buf: Buffer, callback?: (err?: Error) => void): void;
+        send(buf: Buffer, offset: number, length: number, path: string, callback?: (err?: Error) => void): void;
+        bind(path: string): void;
+        connect(remotePath: string): void;
+        close(): void;
+    }
+
+    export function createSocket(type: 'unix_dgram', listener?: (msg: Buffer) => void): UnixDgramSocket;
+}

lib/util/sd-notify.ts

@@ -0,0 +1,68 @@
+import type {UnixDgramSocket} from 'unix-dgram';
+
+import {platform} from 'node:os';
+
+import logger from './logger';
+
+/**
+ * Handle sd_notify protocol, @see https://www.freedesktop.org/software/systemd/man/latest/sd_notify.html
+ * No-op if running on unsupported platforms or without Type=notify
+ * Soft-fails if improperly setup (this is not necessary for Zigbee2MQTT to function properly)
+ */
+export async function initSdNotify(): Promise<{notifyStopping: () => void; stop: () => void} | undefined> {
+    if (!process.env.NOTIFY_SOCKET) {
+        return;
+    }
+
+    let socket: UnixDgramSocket | undefined;
+
+    try {
+        const {createSocket} = await import('unix-dgram');
+        socket = createSocket('unix_dgram');
+    } catch (error) {
+        if (platform() !== 'win32' || process.env.WSL_DISTRO_NAME) {
+            // not on plain Windows
+            logger.error(`Could not init sd_notify: ${(error as Error).message}`);
+            logger.debug((error as Error).stack!);
+        } else {
+            // this should not happen
+            logger.warning(`NOTIFY_SOCKET env is set: ${(error as Error).message}`);
+        }
+
+        return;
+    }
+
+    const sendToSystemd = (msg: string): void => {
+        const buffer = Buffer.from(msg);
+
+        socket.send(buffer, 0, buffer.byteLength, process.env.NOTIFY_SOCKET!, (err) => {
+            if (err) {
+                logger.warning(`Failed to send "${msg}" to systemd: ${err.message}`);
+            }
+        });
+    };
+    const notifyStopping = (): void => sendToSystemd('STOPPING=1');
+
+    sendToSystemd('READY=1');
+
+    const wdUSec = process.env.WATCHDOG_USEC !== undefined ? Math.max(0, parseInt(process.env.WATCHDOG_USEC, 10)) : -1;
+
+    if (wdUSec > 0) {
+        // Convert us to ms, send twice as frequently as the timeout
+        const watchdogInterval = setInterval(() => sendToSystemd('WATCHDOG=1'), wdUSec / 1000 / 2);
+
+        return {
+            notifyStopping,
+            stop: (): void => clearInterval(watchdogInterval),
+        };
+    }
+
+    if (wdUSec !== -1) {
+        logger.warning(`WATCHDOG_USEC invalid: "${process.env.WATCHDOG_USEC}", parsed to "${wdUSec}"`);
+    }
+
+    return {
+        notifyStopping,
+        stop: (): void => {},
+    };
+}

package.json

@@ -76,7 +76,6 @@
         "@types/node": "^22.13.5",
         "@types/object-assign-deep": "^0.4.3",
         "@types/readable-stream": "4.0.18",
-        "@types/sd-notify": "^2.8.2",
         "@types/serve-static": "^1.15.7",
         "@types/ws": "8.5.14",
         "@vitest/coverage-v8": "^3.0.7",
@@ -95,14 +94,13 @@
         "onlyBuiltDependencies": [
             "@serialport/bindings-cpp",
             "esbuild",
-            "sd-notify",
             "unix-dgram"
         ]
     },
     "bin": {
         "zigbee2mqtt": "cli.js"
     },
     "optionalDependencies": {
-        "sd-notify": "^2.8.0"
+        "unix-dgram": "^2.0.6"
     }
 }

pnpm-lock.yaml

@@ -14,6 +14,7 @@ import {devices, mockController as mockZHController, events as mockZHEvents, ret
 import type {Mock, MockInstance} from 'vitest';
 
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 
 import stringify from 'json-stable-stringify-without-jsonify';
@@ -24,15 +25,12 @@ import {Controller as ZHController} from 'zigbee-herdsman';
 import {Controller} from '../lib/controller';
 import * as settings from '../lib/util/settings';
 
-process.env.NOTIFY_SOCKET = 'mocked';
 const LOG_MQTT_NS = 'z2m:mqtt';
 
-vi.mock('sd-notify', () => ({
-    watchdogInterval: vi.fn(() => 3000),
-    startWatchdogMode: vi.fn(),
-    stopWatchdogMode: vi.fn(),
-    ready: vi.fn(),
-    stopping: vi.fn(),
+const mockUnixDgramSend = vi.fn();
+
+vi.mock('unix-dgram', () => ({
+    createSocket: vi.fn(() => ({send: mockUnixDgramSend})),
 }));
 
 const mocksClear = [
@@ -49,6 +47,7 @@ const mocksClear = [
     mockLogger.debug,
     mockLogger.info,
     mockLogger.error,
+    mockUnixDgramSend,
 ];
 
 describe('Controller', () => {
@@ -338,14 +337,32 @@ describe('Controller', () => {
         expect(mockExit).toHaveBeenCalledWith(0, true);
     });
 
-    it('Start controller and stop', async () => {
+    it('Start controller and stop without SdNotify', async () => {
         mockZHController.stop.mockRejectedValueOnce('failed');
         await controller.start();
         await controller.stop();
         expect(mockMQTTEndAsync).toHaveBeenCalledTimes(1);
         expect(mockZHController.stop).toHaveBeenCalledTimes(1);
         expect(mockExit).toHaveBeenCalledTimes(1);
         expect(mockExit).toHaveBeenCalledWith(1, false);
+        expect(mockUnixDgramSend).toHaveBeenCalledTimes(0);
+    });
+
+    it('Start controller and stop with SdNotify', async () => {
+        vi.spyOn(os, 'platform').mockImplementationOnce(() => 'linux');
+
+        process.env.NOTIFY_SOCKET = 'mocked'; // coverage
+
+        mockZHController.stop.mockRejectedValueOnce('failed');
+        await controller.start();
+        await controller.stop();
+        expect(mockMQTTEndAsync).toHaveBeenCalledTimes(1);
+        expect(mockZHController.stop).toHaveBeenCalledTimes(1);
+        expect(mockExit).toHaveBeenCalledTimes(1);
+        expect(mockExit).toHaveBeenCalledWith(1, false);
+        expect(mockUnixDgramSend).toHaveBeenCalledTimes(2);
+
+        delete process.env.NOTIFY_SOCKET;
     });
 
     it('Start controller adapter disconnects', async () => {