homematic-manager 3.0.0-beta.2 → 3.0.0-beta.21

package/node_modules/@homematic-manager/backend/dist/rpc/origin.js

@@ -0,0 +1,35 @@
+/**
+ * Who asked for an RPC call: the console, a UI action, or the backend on its own.
+ *
+ * Task 48: the RPC log shows every outgoing call, and the background ones - `init`, `ping`, the
+ * service-message poll, the sweeps after an event - can be frequent, so every entry carries where
+ * it came from and the drawer can hide them. The origin is a property of the call chain, not of a
+ * function: `#refreshDevices` runs for the Devices tab's refresh button and for a `newDevices`
+ * callback alike. Threading a parameter through the forty call sites of `#read`/`#write` and every
+ * helper between them would change signatures for nothing, so the origin travels in Node's
+ * `AsyncLocalStorage`: `Backend.request` opens a `ui` (or `console`) context, and whatever is
+ * awaited inside it inherits that.
+ *
+ * Two things must be explicit, and the tests hold them:
+ * - Anything long-lived that is *created* inside a request would inherit its context forever - the
+ *   watchdog interval, the callback servers, the polling timers after a `config.set`. The places
+ *   that create such things run under `background` on purpose (`Backend.#connect`, the timers, the
+ *   manager's callbacks), and the manager's own calls name their origin outright.
+ * - A queued write runs from the timer that drained the queue, which is the *previous* task's
+ *   context; `Backend.#write` therefore captures the origin at enqueue time.
+ *
+ * The RPC client itself does not read this module: it takes a resolver (`originOf`) and an
+ * explicit origin per call, so the logging layer stays free of Node (task 52 wants the same engine
+ * in a browser host one day, where an explicit parameter would replace the storage).
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+const storage = new AsyncLocalStorage();
+/** The origin of the current call chain; `background` outside of any request. */
+export function currentOrigin() {
+    return storage.getStore() ?? 'background';
+}
+/** Runs `fn` with `origin` as the answer of {@link currentOrigin} for everything it awaits. */
+export function runWithOrigin(origin, fn) {
+    return storage.run(origin, fn);
+}
+//# sourceMappingURL=origin.js.map

package/node_modules/@homematic-manager/backend/dist/rpc/server.d.ts

@@ -88,11 +88,23 @@ export declare class CallbackServers implements CallbackServerSet {
     constructor(options: {
         handler: CallbackHandler;
         host?: string;
+        /** The configured ports; `0` means none is configured. */
         ports: {
             xmlrpc: number;
             binrpc: number;
         };
+        /**
+         * Task 35 (D-43): the port a protocol takes while its configured port is `0` - the CCU
+         * addon's fixed pair, so that a restart registers the very URL it registered before.
+         * Unlike a configured port, a default that is taken is no error: the server falls back to
+         * a free port for this start, and `onFallback` hears about it once.
+         */
+        defaultPorts?: {
+            xmlrpc: number;
+            binrpc: number;
+        };
         onError?: (error: unknown) => void;
+        onFallback?: (protocol: RpcProtocol, port: number, error: unknown) => void;
     });
     /** Starts the server for a protocol if it is not running yet, and returns its port. */
     ensure(protocol: RpcProtocol): Promise<number>;

package/node_modules/@homematic-manager/backend/dist/rpc/server.js

@@ -17,7 +17,7 @@
  */
 import binrpc from 'binrpc';
 import xmlrpc from 'homematic-xmlrpc';
-import { interfaceNameFromIdent } from '@homematic-manager/core';
+import { interfaceNameFromIdent, normaliseDescription, } from '@homematic-manager/core';
 import { connectionError, errorMessage } from '../errors.js';
 /** The callback methods this server answers, in the order `system.listMethods` returns them. */
 export const CALLBACK_METHODS = [
@@ -199,11 +199,18 @@ export class CallbackServer {
         return new Promise((resolve, reject) => {
             const server = xmlrpc.createServer({ host: this.host, port: this.#requestedPort });
             this.#xmlrpcServer = server;
+            let listening = false;
             server.on('error', (error) => {
-                reject(connectionError(`xmlrpc callback server on port ${String(this.#requestedPort)}: ${error.message}`, error));
+                // a bind that fails is the rejection's to report, once; `onError` is for a server
+                // that is running
+                if (!listening) {
+                    reject(connectionError(`xmlrpc callback server on port ${String(this.#requestedPort)}: ${error.message}`, error));
+                    return;
+                }
                 this.#onError(error);
             });
             server.on('listening', () => {
+                listening = true;
                 const address = server.httpServer.address();
                 resolve(typeof address === 'object' && address !== null ? address.port : this.#requestedPort);
             });
@@ -221,11 +228,16 @@ export class CallbackServer {
         return new Promise((resolve, reject) => {
             const server = binrpc.createServer({ host: this.host, port: this.#requestedPort });
             this.#binrpcServer = server;
+            let listening = false;
             server.on('error', (error) => {
-                reject(connectionError(`binrpc callback server on port ${String(this.#requestedPort)}: ${error.message}`, error));
+                if (!listening) {
+                    reject(connectionError(`binrpc callback server on port ${String(this.#requestedPort)}: ${error.message}`, error));
+                    return;
+                }
                 this.#onError(error);
             });
             server.on('listening', () => {
+                listening = true;
                 const address = server.server.address();
                 resolve(typeof address === 'object' && address !== null ? address.port : this.#requestedPort);
             });
@@ -266,7 +278,9 @@ function asDescriptions(value) {
             entry !== null &&
             !Array.isArray(entry) &&
             typeof entry['ADDRESS'] === 'string') {
-            descriptions.push(entry);
+            // #143: the list fields of a description are made into lists here, once, for every
+            // interface - the group process sends `PARAMSETS` as a string on some boxes.
+            descriptions.push(normaliseDescription(entry));
         }
     }
     return descriptions;
@@ -282,12 +296,16 @@ export class CallbackServers {
     #handler;
     #host;
     #ports;
+    #defaultPorts;
     #onError;
+    #onFallback;
     constructor(options) {
         this.#handler = options.handler;
         this.#host = options.host ?? '0.0.0.0';
         this.#ports = options.ports;
+        this.#defaultPorts = options.defaultPorts ?? { xmlrpc: 0, binrpc: 0 };
         this.#onError = options.onError ?? (() => undefined);
+        this.#onFallback = options.onFallback ?? (() => undefined);
     }
     /** Starts the server for a protocol if it is not running yet, and returns its port. */
     async ensure(protocol) {
@@ -295,10 +313,24 @@ export class CallbackServers {
         if (running) {
             return running.port;
         }
+        const configured = protocol === 'binrpc' ? this.#ports.binrpc : this.#ports.xmlrpc;
+        const preferred = protocol === 'binrpc' ? this.#defaultPorts.binrpc : this.#defaultPorts.xmlrpc;
+        if (configured !== 0 || preferred === 0) {
+            return this.#start(protocol, configured);
+        }
+        try {
+            return await this.#start(protocol, preferred);
+        }
+        catch (error) {
+            this.#onFallback(protocol, preferred, error);
+            return this.#start(protocol, 0);
+        }
+    }
+    async #start(protocol, port) {
         const server = new CallbackServer({
             protocol,
             host: this.#host,
-            port: protocol === 'binrpc' ? this.#ports.binrpc : this.#ports.xmlrpc,
+            port,
             handler: this.#handler,
             onError: this.#onError,
         });

package/node_modules/@homematic-manager/backend/dist/util/net.d.ts

@@ -7,15 +7,100 @@
  * 5 s timeout each before the window became usable) and it destroys the socket instead of leaving
  * it to time out.
  */
+import dgram from 'node:dgram';
+import dns from 'node:dns';
 import net from 'node:net';
 import os from 'node:os';
-/** Every non-internal IPv4 address of this machine; candidates for the callback address. */
+import type { CallbackAddressInfo } from '@homematic-manager/core';
+/**
+ * Every non-internal IPv4 address of this machine, then `127.0.0.1`; candidates for the callback
+ * address. The loopback comes last so nothing that picked "the first candidate" changes - but it
+ * has to be offered: on an openccu-lite box the interface processes bind the loopback only
+ * (their D-29), so for the Homematic Manager running *on* the box it is the one address they
+ * can call back (openccu-lite task 28.10, maintainer 2026-09-08).
+ */
 export declare function localIPv4Addresses(interfaces?: () => NodeJS.Dict<os.NetworkInterfaceInfo[]>): string[];
+/** One IPv4 address of this machine; `netmask` is absent where it is not known (an injected list). */
+export interface LocalIPv4 {
+    readonly address: string;
+    readonly netmask?: string;
+}
+/**
+ * B-53: every non-internal IPv4 address of this machine with its netmask, in the order
+ * `os.networkInterfaces()` gives them - the loopback is not in it.
+ */
+export declare function localIPv4Interfaces(interfaces?: () => NodeJS.Dict<os.NetworkInterfaceInfo[]>): LocalIPv4[];
+/** A dotted IPv4 address as a number; `undefined` for anything else. */
+export declare function ipv4ToNumber(address: string): number | undefined;
+/** True when `target` is in the network of `address/netmask`. False when any of them is no IPv4 address. */
+export declare function inSubnet(address: string, netmask: string, target: string): boolean;
+/** `169.254.0.0/16`, the address an interface gives itself when no DHCP server answered. */
+export declare function isLinkLocal(address: string): boolean;
+/** `127.0.0.0/8`. */
+export declare function isLoopback(address: string): boolean;
+/**
+ * B-53: what the automatic callback address is worked out from. Injected by the tests, so that no
+ * unit test depends on the network of the machine it runs on.
+ */
+export interface CallbackNetwork {
+    /** This machine's non-internal IPv4 addresses, see {@link localIPv4Interfaces}. */
+    readonly interfaces: () => LocalIPv4[];
+    /** The CCU host's IPv4 address; `undefined` when it does not resolve. Never rejects. */
+    readonly resolve: (host: string) => Promise<string | undefined>;
+    /** The local address the operating system sends from towards `address`; `undefined` when there is no route. Never rejects. */
+    readonly route: (address: string) => Promise<string | undefined>;
+}
+/** How long a name lookup for the callback address may take before the first address is used. */
+export declare const RESOLVE_TIMEOUT_MS = 3000;
+/** The CCU host's IPv4 address, through the system resolver (`/etc/hosts`, mDNS where the OS has it). */
+export declare function resolveIPv4(host: string, lookup?: typeof dns.promises.lookup): Promise<string | undefined>;
+/**
+ * The local address a UDP socket gets when it is `connect()`ed to `address`: the source address of
+ * the route the operating system would take. `connect` on a datagram socket only sets the default
+ * peer - no packet is sent - so this works for a CCU behind a router or a VPN as well as for one in
+ * the same network.
+ */
+export declare function routeSource(address: string, createSocket?: typeof dgram.createSocket): Promise<string | undefined>;
+/** The machine's own network, as the running host sees it. */
+export declare function systemNetwork(): CallbackNetwork;
+/**
+ * A network made of a fixed address list, for a caller that injects `localAddresses` (the tests and
+ * the e2e hosts): no netmasks, no name lookup beyond an address literal, no route.
+ */
+export declare function staticNetwork(addresses: () => string[]): CallbackNetwork;
+/**
+ * B-53 (#162, #165): the automatic callback address, and every address with whether it is in the
+ * CCU's network. Synchronous: `hostAddress` and `routed` are what {@link describeCallbackAddresses}
+ * found out, and `undefined` when nothing could be.
+ *
+ * The order: the CCU on the loopback (or `local`) is called back on the loopback; then the
+ * address in the CCU's network; then the route's source address; then the first address that is
+ * not link-local. A link-local address wins only as the CCU's own network, and the loopback is
+ * never chosen for a CCU elsewhere unless this machine has no other address at all.
+ */
+export declare function pickCallbackAddress(host: string, hostAddress: string | undefined, interfaces: readonly LocalIPv4[], routed: string | undefined, local?: boolean): CallbackAddressInfo;
+/**
+ * B-53: {@link pickCallbackAddress} with the facts looked up - the CCU's name resolved, and the route
+ * asked for only when no address shares the CCU's network. Never rejects.
+ */
+export declare function describeCallbackAddresses(host: string, network: CallbackNetwork, local?: boolean): Promise<CallbackAddressInfo>;
 export interface ProbeOptions {
     readonly timeoutMs?: number;
     /** Injected for the tests; defaults to `net.connect`. */
     readonly connect?: typeof net.connect;
 }
+/**
+ * What a port probe found.
+ *
+ * B-28: `refused` and `unreachable` are different answers. A refused connection means nothing listens
+ * there - the interface process is not installed, the normal state of BidCos-Wired on a CCU without a
+ * wired gateway. A connection that times out, or a host without a route, says nothing about the
+ * process: a slow CCU-Jack, a remote CUxD on a box that is rebooting. Only the first may be shown as
+ * "not present".
+ */
+export type PortProbe = 'open' | 'refused' | 'unreachable';
+/** Whether a TCP connection to `host:port` is accepted, refused, or not answered in time. Never throws. */
+export declare function probePortState(host: string, port: number, options?: ProbeOptions): Promise<PortProbe>;
 /** True when a TCP connection to `host:port` is accepted within the timeout. Never throws. */
 export declare function probePort(host: string, port: number, options?: ProbeOptions): Promise<boolean>;
 /** Resolves after `ms`; the timer never keeps the process alive. */

package/node_modules/@homematic-manager/backend/dist/util/net.js

@@ -7,9 +7,17 @@
  * 5 s timeout each before the window became usable) and it destroys the socket instead of leaving
  * it to time out.
  */
+import dgram from 'node:dgram';
+import dns from 'node:dns';
 import net from 'node:net';
 import os from 'node:os';
-/** Every non-internal IPv4 address of this machine; candidates for the callback address. */
+/**
+ * Every non-internal IPv4 address of this machine, then `127.0.0.1`; candidates for the callback
+ * address. The loopback comes last so nothing that picked "the first candidate" changes - but it
+ * has to be offered: on an openccu-lite box the interface processes bind the loopback only
+ * (their D-29), so for the Homematic Manager running *on* the box it is the one address they
+ * can call back (openccu-lite task 28.10, maintainer 2026-09-08).
+ */
 export function localIPv4Addresses(interfaces = os.networkInterfaces) {
     const addresses = [];
     for (const entries of Object.values(interfaces())) {
@@ -19,33 +27,239 @@ export function localIPv4Addresses(interfaces = os.networkInterfaces) {
             }
         }
     }
+    addresses.push('127.0.0.1');
     return addresses;
 }
-/** True when a TCP connection to `host:port` is accepted within the timeout. Never throws. */
-export function probePort(host, port, options = {}) {
+/** The address an interface process on this machine calls back on. */
+const LOOPBACK = '127.0.0.1';
+/**
+ * B-53: every non-internal IPv4 address of this machine with its netmask, in the order
+ * `os.networkInterfaces()` gives them - the loopback is not in it.
+ */
+export function localIPv4Interfaces(interfaces = os.networkInterfaces) {
+    const found = [];
+    for (const entries of Object.values(interfaces())) {
+        for (const entry of entries ?? []) {
+            if (entry.family === 'IPv4' && !entry.internal && !found.some((seen) => seen.address === entry.address)) {
+                found.push({ address: entry.address, netmask: entry.netmask });
+            }
+        }
+    }
+    return found;
+}
+/** A dotted IPv4 address as a number; `undefined` for anything else. */
+export function ipv4ToNumber(address) {
+    const parts = address.split('.');
+    if (parts.length !== 4) {
+        return undefined;
+    }
+    let value = 0;
+    for (const part of parts) {
+        if (!/^\d{1,3}$/.test(part)) {
+            return undefined;
+        }
+        const byte = Number(part);
+        if (byte > 255) {
+            return undefined;
+        }
+        value = value * 256 + byte;
+    }
+    return value;
+}
+/** True when `target` is in the network of `address/netmask`. False when any of them is no IPv4 address. */
+export function inSubnet(address, netmask, target) {
+    const a = ipv4ToNumber(address);
+    const m = ipv4ToNumber(netmask);
+    const t = ipv4ToNumber(target);
+    if (a === undefined || m === undefined || t === undefined) {
+        return false;
+    }
+    // `>>> 0` keeps the results unsigned; `&` alone would make 192.168.x.x negative
+    return (a & m) >>> 0 === (t & m) >>> 0;
+}
+/** `169.254.0.0/16`, the address an interface gives itself when no DHCP server answered. */
+export function isLinkLocal(address) {
+    return address.startsWith('169.254.');
+}
+/** `127.0.0.0/8`. */
+export function isLoopback(address) {
+    return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(address);
+}
+/** How long a name lookup for the callback address may take before the first address is used. */
+export const RESOLVE_TIMEOUT_MS = 3000;
+/** The CCU host's IPv4 address, through the system resolver (`/etc/hosts`, mDNS where the OS has it). */
+export async function resolveIPv4(host, lookup = dns.promises.lookup) {
+    if (ipv4ToNumber(host) !== undefined) {
+        return host;
+    }
+    if (host === '' || net.isIPv6(host)) {
+        return undefined;
+    }
+    try {
+        const result = await withTimeout(lookup(host, { family: 4 }), RESOLVE_TIMEOUT_MS, () => new Error('timeout'));
+        return result.address;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The local address a UDP socket gets when it is `connect()`ed to `address`: the source address of
+ * the route the operating system would take. `connect` on a datagram socket only sets the default
+ * peer - no packet is sent - so this works for a CCU behind a router or a VPN as well as for one in
+ * the same network.
+ */
+export function routeSource(address, createSocket = dgram.createSocket) {
+    return new Promise((resolve) => {
+        let socket;
+        try {
+            socket = createSocket('udp4');
+        }
+        catch {
+            resolve(undefined);
+            return;
+        }
+        let settled = false;
+        const done = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            try {
+                socket.close();
+            }
+            catch {
+                // already closed
+            }
+            resolve(result);
+        };
+        socket.on('error', () => {
+            done(undefined);
+        });
+        try {
+            // the port does not matter, nothing is sent; 9 is "discard"
+            socket.connect(9, address, () => {
+                try {
+                    done(socket.address().address);
+                }
+                catch {
+                    done(undefined);
+                }
+            });
+        }
+        catch {
+            done(undefined);
+        }
+    });
+}
+/** The machine's own network, as the running host sees it. */
+export function systemNetwork() {
+    return {
+        interfaces: () => localIPv4Interfaces(),
+        resolve: (host) => resolveIPv4(host),
+        route: (address) => routeSource(address),
+    };
+}
+/**
+ * A network made of a fixed address list, for a caller that injects `localAddresses` (the tests and
+ * the e2e hosts): no netmasks, no name lookup beyond an address literal, no route.
+ */
+export function staticNetwork(addresses) {
+    return {
+        interfaces: () => addresses()
+            .filter((address) => !isLoopback(address))
+            .map((address) => ({ address })),
+        resolve: (host) => Promise.resolve(ipv4ToNumber(host) === undefined ? undefined : host),
+        route: () => Promise.resolve(undefined),
+    };
+}
+/**
+ * B-53 (#162, #165): the automatic callback address, and every address with whether it is in the
+ * CCU's network. Synchronous: `hostAddress` and `routed` are what {@link describeCallbackAddresses}
+ * found out, and `undefined` when nothing could be.
+ *
+ * The order: the CCU on the loopback (or `local`) is called back on the loopback; then the
+ * address in the CCU's network; then the route's source address; then the first address that is
+ * not link-local. A link-local address wins only as the CCU's own network, and the loopback is
+ * never chosen for a CCU elsewhere unless this machine has no other address at all.
+ */
+export function pickCallbackAddress(host, hostAddress, interfaces, routed, local = false) {
+    const matches = (entry) => hostAddress !== undefined && entry.netmask !== undefined && inSubnet(entry.address, entry.netmask, hostAddress);
+    const ccuOnLoopback = local || (hostAddress !== undefined && isLoopback(hostAddress));
+    const addresses = interfaces.map((entry) => ({
+        address: entry.address,
+        inSubnet: matches(entry),
+        ...(isLinkLocal(entry.address) ? { linkLocal: true } : {}),
+    }));
+    addresses.push({ address: LOOPBACK, inSubnet: ccuOnLoopback });
+    const choose = () => {
+        if (ccuOnLoopback) {
+            return { address: LOOPBACK, reason: 'loopback' };
+        }
+        const subnet = interfaces.find((entry) => matches(entry));
+        if (subnet !== undefined) {
+            return { address: subnet.address, reason: 'subnet' };
+        }
+        if (routed !== undefined && !isLinkLocal(routed) && interfaces.some((entry) => entry.address === routed)) {
+            return { address: routed, reason: 'route' };
+        }
+        const first = interfaces.find((entry) => !isLinkLocal(entry.address));
+        return { address: first?.address ?? LOOPBACK, reason: 'first' };
+    };
+    return {
+        host,
+        ...(hostAddress === undefined ? {} : { hostAddress }),
+        auto: choose(),
+        addresses,
+    };
+}
+/**
+ * B-53: {@link pickCallbackAddress} with the facts looked up - the CCU's name resolved, and the route
+ * asked for only when no address shares the CCU's network. Never rejects.
+ */
+export async function describeCallbackAddresses(host, network, local = false) {
+    const interfaces = network.interfaces();
+    if (local) {
+        return pickCallbackAddress(host, undefined, interfaces, undefined, true);
+    }
+    const hostAddress = host === '' ? undefined : await network.resolve(host);
+    const inNetwork = hostAddress !== undefined &&
+        (isLoopback(hostAddress) ||
+            interfaces.some((entry) => entry.netmask !== undefined && inSubnet(entry.address, entry.netmask, hostAddress)));
+    const routed = hostAddress === undefined || inNetwork ? undefined : await network.route(hostAddress);
+    return pickCallbackAddress(host, hostAddress, interfaces, routed);
+}
+/** Whether a TCP connection to `host:port` is accepted, refused, or not answered in time. Never throws. */
+export function probePortState(host, port, options = {}) {
     const timeoutMs = options.timeoutMs ?? 2000;
     const connect = options.connect ?? net.connect;
     return new Promise((resolve) => {
         let settled = false;
-        const done = (open) => {
+        const done = (result) => {
             if (settled) {
                 return;
             }
             settled = true;
             socket.destroy();
-            resolve(open);
+            resolve(result);
         };
         const socket = connect({ host, port, timeout: timeoutMs }, () => {
-            done(true);
+            done('open');
         });
-        socket.on('error', () => {
-            done(false);
+        socket.on('error', (error) => {
+            // node's happy-eyeballs connect aggregates the per-address failures in `errors`
+            const codes = [error.code, ...(error.errors ?? []).map((entry) => entry.code)];
+            done(codes.includes('ECONNREFUSED') ? 'refused' : 'unreachable');
         });
         socket.on('timeout', () => {
-            done(false);
+            done('unreachable');
         });
     });
 }
+/** True when a TCP connection to `host:port` is accepted within the timeout. Never throws. */
+export async function probePort(host, port, options = {}) {
+    return (await probePortState(host, port, options)) === 'open';
+}
 /** Resolves after `ms`; the timer never keeps the process alive. */
 export function delay(ms) {
     return new Promise((resolve) => {

package/node_modules/@homematic-manager/backend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homematic-manager/backend",
-  "version": "3.0.0-beta.2",
+  "version": "3.0.0-beta.21",
   "type": "module",
   "description": "Homematic Manager backend: XML-RPC/BIN-RPC clients and callback servers, caches, optional ReGa",
   "license": "AGPL-3.0-or-later",