homematic-manager 3.0.0-beta.13 → 3.0.0-beta.15

package/dist/cli.js

@@ -169,6 +169,7 @@ function startHost(values, log, version) {
         ...(values.callbackIp === undefined ? {} : { callbackIp: values.callbackIp }),
         ...(values.callbackXmlrpcPort === undefined ? {} : { callbackXmlrpcPort: values.callbackXmlrpcPort }),
         ...(values.callbackBinrpcPort === undefined ? {} : { callbackBinrpcPort: values.callbackBinrpcPort }),
+        ...(values.inContainer ? { inContainer: true } : {}),
         ...(values.callbackXmlrpcDefaultPort === undefined
             ? {}
             : { callbackXmlrpcDefaultPort: values.callbackXmlrpcDefaultPort }),

package/dist/options.d.ts

@@ -154,6 +154,11 @@ export declare const OPTIONS: {
         readonly describe: "binrpc callback port while the configured one is 0; a free port when it is taken (the CCU addon sets 2032)";
         readonly defaultDescription: "none, a free port";
     };
+    readonly 'in-container': {
+        readonly type: "boolean";
+        readonly describe: "we run in a container (the image sets it): the interface popup says to publish the callback ports unchanged";
+        readonly default: false;
+    };
     readonly 'idle-unsubscribe': {
         readonly type: "string";
         readonly describe: "drop the event subscriptions after this long with no page open (5m, 300s, 0 to disable)";
@@ -234,6 +239,8 @@ export interface WebOptions {
     /** Task 35 (D-43): the CCU addon's fixed callback ports, taken while the configured ones are `0`. */
     readonly callbackXmlrpcDefaultPort: number | undefined;
     readonly callbackBinrpcDefaultPort: number | undefined;
+    /** Task 38: set by the image's `HMM_IN_CONTAINER`. */
+    readonly inContainer: boolean;
     readonly demo: boolean;
     /** D-31, in milliseconds; `0` disables the idle unsubscribe. */
     readonly idleUnsubscribeMs: number;

package/dist/options.js

@@ -154,6 +154,11 @@ export const OPTIONS = {
         describe: 'binrpc callback port while the configured one is 0; a free port when it is taken (the CCU addon sets 2032)',
         defaultDescription: 'none, a free port',
     },
+    'in-container': {
+        type: 'boolean',
+        describe: 'we run in a container (the image sets it): the interface popup says to publish the callback ports unchanged',
+        default: false,
+    },
     'idle-unsubscribe': {
         type: 'string',
         describe: 'drop the event subscriptions after this long with no page open (5m, 300s, 0 to disable)',
@@ -338,6 +343,7 @@ export function parseOptions(argv, env = process.env) {
         callbackBinrpcPort: number('callback-binrpc-port'),
         callbackXmlrpcDefaultPort,
         callbackBinrpcDefaultPort,
+        inContainer: boolean('in-container') ?? false,
         demo: boolean('demo'),
         idleUnsubscribeMs: parseDuration(string('idle-unsubscribe'), '--idle-unsubscribe'),
         logLevel: isLogLevel(logLevel) ? logLevel : 'info',

package/dist/server.d.ts

@@ -110,14 +110,23 @@ export interface WebHostOptions {
     /** Written to `ConnectionConfig.local` - the addon's "we run on the CCU" mode. */
     readonly local?: boolean | undefined;
     /**
-     * Written to `ConnectionConfig.callback`. A host that cannot see the address the CCU reaches it
+     * Laid over `ConnectionConfig.callback`. A host that cannot see the address the CCU reaches it
      * on has to be told: a container on a bridge network sees `172.17.0.x`, and an `init` that
      * announces that address gets no events at all. With `--network host` none of this is needed.
+     *
+     * Task 38: these three are pinned, not written. They win over `config.json` for as long as the
+     * host runs with them, the settings dialog shows them read-only, and the file keeps what the
+     * user saved. An empty address and a port of `0` pin nothing.
      */
     readonly callbackIp?: string | undefined;
-    /** Fixed callback ports, so a container can publish them. `0` picks a free one. */
+    /** Fixed callback ports, so a container can publish them. `0` pins nothing. */
     readonly callbackXmlrpcPort?: number | undefined;
     readonly callbackBinrpcPort?: number | undefined;
+    /**
+     * Task 38: the host runs in a container (`HMM_IN_CONTAINER`, set by the image). The interface
+     * popup then says beside each callback URL that its port must be published unchanged.
+     */
+    readonly inContainer?: boolean | undefined;
     /**
      * Task 35 (D-43): the callback ports taken while the configuration says `0` - the CCU addon's
      * fixed pair. Handed to the backend and never written to `config.json`, so a port the user set

package/dist/server.js

@@ -24,7 +24,7 @@
 import fs from 'node:fs/promises';
 import http from 'node:http';
 import path from 'node:path';
-import { ApiWebSocketServer, Backend, RegaAuthenticator } from '@homematic-manager/backend';
+import { ApiWebSocketServer, Backend, RegaAuthenticator, } from '@homematic-manager/backend';
 import { applyCookieToken, applySessionToken, clearedSessionCookie, createToken, isLoopbackHost, readCookie, SESSION_COOKIE, sessionCookie, TOKEN_COOKIE, tokenCookie, } from './auth.js';
 import { DeviceImageService, readIconMapFile } from './images.js';
 import { clientAddress, parseLoginForm, pickLanguage, readBody, renderLoginPage, } from './login.js';
@@ -104,6 +104,16 @@ export async function createWebHost(options = {}) {
         if (defaultCallbackPorts !== undefined) {
             log.info(`callback: default ports xmlrpc=${String(defaultCallbackPorts.xmlrpc)} binrpc=${String(defaultCallbackPorts.binrpc)} while the configuration says 0`);
         }
+        const pinnedCallback = callbackPins(options);
+        if (pinnedCallback !== undefined) {
+            const { ip, xmlrpcPort, binrpcPort } = pinnedCallback;
+            const parts = [
+                ...(ip === undefined ? [] : [`ip=${ip}`]),
+                ...(xmlrpcPort === undefined ? [] : [`xmlrpc=${String(xmlrpcPort)}`]),
+                ...(binrpcPort === undefined ? [] : [`binrpc=${String(binrpcPort)}`]),
+            ];
+            log.info(`callback: ${parts.join(' ')} set at start, read-only in the settings dialog`);
+        }
         backend = await Backend.open({
             dataDir,
             version: options.version ?? packageVersion(),
@@ -113,6 +123,8 @@ export async function createWebHost(options = {}) {
             // window can never be idled out however the backend is configured.
             ...(options.idleUnsubscribeMs === undefined ? {} : { idleUnsubscribeMs: options.idleUnsubscribeMs }),
             ...(defaultCallbackPorts === undefined ? {} : { defaultCallbackPorts }),
+            ...(pinnedCallback === undefined ? {} : { pinnedCallback }),
+            ...(options.inContainer === true ? { inContainer: true } : {}),
             ...options.backendOptions,
         });
         backend.on('notice', (notice) => {
@@ -556,17 +568,30 @@ function callbackDefaults(options) {
     const binrpc = options.callbackBinrpcDefaultPort ?? 0;
     return xmlrpc === 0 && binrpc === 0 ? undefined : { xmlrpc, binrpc };
 }
-/** `--ccu`, `--local` and the callback options win over what `config.json` holds. */
+/**
+ * Task 38: the callback fields given at start, or nothing. An empty address and a port of `0` are
+ * "not configured" in the connection model and pin nothing.
+ */
+function callbackPins(options) {
+    const pins = {
+        ...(options.callbackIp === undefined || options.callbackIp === '' ? {} : { ip: options.callbackIp }),
+        ...(options.callbackXmlrpcPort === undefined || options.callbackXmlrpcPort === 0
+            ? {}
+            : { xmlrpcPort: options.callbackXmlrpcPort }),
+        ...(options.callbackBinrpcPort === undefined || options.callbackBinrpcPort === 0
+            ? {}
+            : { binrpcPort: options.callbackBinrpcPort }),
+    };
+    return Object.keys(pins).length === 0 ? undefined : pins;
+}
+/**
+ * `--ccu` and `--local` win over what `config.json` holds, and are written to it. The callback
+ * options are not: since task 38 the backend lays them over the profile (`pinnedCallback`).
+ */
 async function applyConnectionOptions(backend, options, log) {
     const wantsHost = options.ccu !== undefined && options.ccu !== '';
     const wantsLocal = options.local !== undefined;
-    const callback = {
-        ...(options.callbackIp === undefined ? {} : { ip: options.callbackIp }),
-        ...(options.callbackXmlrpcPort === undefined ? {} : { xmlrpcPort: options.callbackXmlrpcPort }),
-        ...(options.callbackBinrpcPort === undefined ? {} : { binrpcPort: options.callbackBinrpcPort }),
-    };
-    const wantsCallback = Object.keys(callback).length > 0;
-    if (!wantsHost && !wantsLocal && !wantsCallback) {
+    if (!wantsHost && !wantsLocal) {
         return;
     }
     const config = await backend.request('config.get');
@@ -574,22 +599,11 @@ async function applyConnectionOptions(backend, options, log) {
         ...config.connection,
         ...(wantsHost ? { host: options.ccu } : {}),
         ...(wantsLocal ? { local: options.local } : {}),
-        callback: { ...config.connection.callback, ...callback },
     };
-    if (connection.host === config.connection.host &&
-        connection.local === config.connection.local &&
-        connection.callback.ip === config.connection.callback.ip &&
-        connection.callback.xmlrpcPort === config.connection.callback.xmlrpcPort &&
-        connection.callback.binrpcPort === config.connection.callback.binrpcPort) {
+    if (connection.host === config.connection.host && connection.local === config.connection.local) {
         return;
     }
-    if (wantsHost || wantsLocal) {
-        log.info(`connection: host=${connection.host}${connection.local === true ? ' (local)' : ''}`);
-    }
-    if (wantsCallback) {
-        const { ip, xmlrpcPort, binrpcPort } = connection.callback;
-        log.info(`callback: ${ip === '' ? 'auto' : ip} xmlrpc=${String(xmlrpcPort)} binrpc=${String(binrpcPort)}`);
-    }
+    log.info(`connection: host=${connection.host}${connection.local === true ? ' (local)' : ''}`);
     await backend.request('config.set', connection);
 }
 async function withTimeout(work, ms, onTimeout) {

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

@@ -39,6 +39,12 @@ export interface BackendOptions extends Omit<ConfigStoreOptions, 'version'> {
         readonly xmlrpc: number;
         readonly binrpc: number;
     };
+    /**
+     * Task 38: the host runs in a container (the image sets `HMM_IN_CONTAINER`). Where its callback
+     * servers listen beyond the loopback, `AppConfig.publishCallbackPorts` tells the interface
+     * popup to say that the callback ports must be published unchanged.
+     */
+    readonly inContainer?: boolean;
     readonly rpcTimeoutMs?: number;
     readonly watchdogIntervalMs?: number;
     readonly serviceMessagePollMs?: number;

package/node_modules/@homematic-manager/backend/dist/api/backend.js

@@ -14,7 +14,7 @@
  * main process with it, issue #127).
  */
 import path from 'node:path';
-import { RPC_METHOD_NAMES, RSSI_UNKNOWN, countsAsServiceMessage, isAcknowledgeable, maintenanceAddress, mergeMethodHelp, methodsFor, normaliseDescription, repairMisdecodedUtf8, } from '@homematic-manager/core';
+import { RPC_METHOD_NAMES, RSSI_UNKNOWN, countsAsServiceMessage, isAcknowledgeable, isKnownInterface, maintenanceAddress, mergeMethodHelp, methodsFor, callbackPinOption, normaliseDescription, repairMisdecodedUtf8, } from '@homematic-manager/core';
 import { CacheStore } from '../cache/store.js';
 import { ConfigStore } from '../config/store.js';
 import { LinkTemplateStore } from '../config/linkTemplates.js';
@@ -23,7 +23,7 @@ import { DataFileServer } from '../data/files.js';
 import { installModeCalls } from '../devices/installMode.js';
 import { discoverCcus } from '../discovery/discover.js';
 import { BackendError, configError, connectionError, errorMessage, internalError, isMethodUnsupported, validationError, } from '../errors.js';
-import { InterfaceManager, firstBidcosInterfaceAddress } from '../interfaces/manager.js';
+import { InterfaceManager, LOOPBACK_IP, callbackBindHost, firstBidcosInterfaceAddress, } from '../interfaces/manager.js';
 import { MetaService } from '../meta/service.js';
 import { RegaService } from '../rega/client.js';
 import { listDevicesAnswer } from '../rpc/server.js';
@@ -44,6 +44,12 @@ export const HMIP_SWEEP_DELAY_MS = 1000;
 function isHmipInterface(name, type) {
     return /hmip/i.test(name) || /hmip/i.test(type);
 }
+/** Task 38: how a log line names a callback field. */
+const CALLBACK_FIELD_WORDS = {
+    ip: 'callback address',
+    xmlrpcPort: 'XML-RPC callback port',
+    binrpcPort: 'BIN-RPC callback port',
+};
 /** Implements the whole contract. `open()` loads, `start()` connects, `stop()` disconnects. */
 export class Backend {
     events;
@@ -86,7 +92,23 @@ export class Backend {
      * table - and it is emptied whenever the connection is rebuilt.
      */
     #noServiceMessages = new Set();
+    /**
+     * B-26 (#158): interfaces whose last `getServiceMessages` failed for a reason that may pass - a
+     * timeout, a process that is restarting. The failure is logged when the interface lands in
+     * here and not again until a call succeeds; before, the five-minute poll logged it every round.
+     */
+    #serviceMessageFailures = new Set();
+    /**
+     * B-26 (#158): the `system.listMethods` answer of a user-defined interface, asked once and
+     * dropped when the interface subscribes again - a re-`init` may be a restarted, updated process.
+     * `undefined` inside means "no usable list", and the method is then tried once, as before.
+     */
+    #listedMethods = new Map();
+    /** B-26: interfaces that do not have `system.listMethods` itself; kept for the connection. */
+    #noListMethods = new Set();
     #idleTimer;
+    /** Task 38: the saved callback values a pinned one replaces are logged by the first `start()` only. */
+    #pinsReported = false;
     constructor(options, config, caches) {
         this.#options = options;
         this.#config = config;
@@ -158,6 +180,14 @@ export class Backend {
         if (this.#config.importedFromLegacy) {
             this.#notice('info', 'the configuration of Homematic Manager 2.x was imported');
         }
+        if (!this.#pinsReported) {
+            // Task 38: once per process - the value in config.json stays, it only has no effect
+            this.#pinsReported = true;
+            for (const { field, saved, pinned } of this.#config.ignoredCallback) {
+                this.#notice('info', `callback: the saved ${CALLBACK_FIELD_WORDS[field]} ${String(saved)} is ignored, ` +
+                    `${callbackPinOption(field)} sets ${String(pinned)}`);
+            }
+        }
         const problems = validateConnection(this.#config.connection);
         if (problems.length > 0) {
             this.#notice('info', `not connecting: ${problems.join(', ')}`);
@@ -466,6 +496,9 @@ export class Backend {
     async #connect() {
         const connection = this.#config.connection;
         this.#noServiceMessages.clear();
+        this.#serviceMessageFailures.clear();
+        this.#listedMethods.clear();
+        this.#noListMethods.clear();
         const manager = (this.#options.createInterfaceManager ?? ((options) => new InterfaceManager(options)))({
             connection,
             handler: this.#callbackHandler(),
@@ -483,6 +516,7 @@ export class Backend {
             ...(this.#options.defaultCallbackPorts === undefined
                 ? {}
                 : { defaultCallbackPorts: this.#options.defaultCallbackPorts }),
+            ...(this.#config.callbackPins === undefined ? {} : { callbackPins: this.#config.callbackPins }),
             ...(this.#options.rpcTimeoutMs === undefined ? {} : { rpcTimeoutMs: this.#options.rpcTimeoutMs }),
             ...(this.#options.watchdogIntervalMs === undefined
                 ? {}
@@ -647,6 +681,8 @@ export class Backend {
     }
     /** Fills the caches of an interface that has just subscribed. */
     async #onInterfaceConnected(interfaceName) {
+        // B-26: a (re-)`init` may be a restarted process, so its method list is asked again
+        this.#listedMethods.delete(interfaceName);
         try {
             await this.#refreshDevices(interfaceName);
         }
@@ -821,9 +857,16 @@ export class Backend {
      */
     #withHostFacts(config) {
         const ports = this.#options.defaultCallbackPorts;
-        return ports === undefined
-            ? config
-            : { ...config, callbackDefaultPorts: { xmlrpc: ports.xmlrpc, binrpc: ports.binrpc } };
+        const pins = this.#config.callbackPins;
+        // Task 38: a container whose callback servers listen on the loopback only has nothing to publish
+        const bindHost = this.#options.callbackHost ?? callbackBindHost(config.connection);
+        const publish = this.#options.inContainer === true && bindHost !== LOOPBACK_IP;
+        return {
+            ...config,
+            ...(ports === undefined ? {} : { callbackDefaultPorts: { xmlrpc: ports.xmlrpc, binrpc: ports.binrpc } }),
+            ...(pins === undefined ? {} : { callbackPinned: { ...pins } }),
+            ...(publish ? { publishCallbackPorts: true } : {}),
+        };
     }
     async #setConfig(connection, options) {
         const previousHost = this.#config.connection.host;
@@ -1133,23 +1176,69 @@ export class Backend {
      * Does it make sense to ask this interface for its service messages?
      *
      * The built-in answer comes from the core's table: hmipserver has no `getServiceMessages` (the
-     * HmIP sweep below reads the `:0` channels instead) and the group process behind
-     * `VirtualDevices` answers it with invalid XML-RPC. A user-defined interface is asked once and
-     * then remembered for this session - see {@link isMethodUnsupported}.
+     * HmIP sweep below reads the `:0` channels instead), the group process behind `VirtualDevices`
+     * answers it with invalid XML-RPC, and CUxD with a fault and a warning in the CCU's syslog
+     * (B-26, #158). A user-defined interface is judged by its own `system.listMethods` where that
+     * gives a list, and is otherwise asked once and then remembered for this session - see
+     * {@link isMethodUnsupported}.
      */
-    #hasServiceMessages(interfaceName) {
+    async #hasServiceMessages(interfaceName) {
         if (this.#noServiceMessages.has(interfaceName)) {
             return false;
         }
-        return this.#manager?.resolved(interfaceName)?.serviceMessages !== false;
+        if (this.#manager?.resolved(interfaceName)?.serviceMessages === false) {
+            return false;
+        }
+        // the table is measured for the built-in processes; asking rfd for its method list after
+        // every `init` would buy nothing
+        if (isKnownInterface(interfaceName)) {
+            return true;
+        }
+        const listed = await this.#methodList(interfaceName);
+        return listed === undefined || listed.has('getServiceMessages');
+    }
+    /**
+     * B-26 (#158): the methods a user-defined interface lists in `system.listMethods`, or
+     * `undefined` when it gave no usable list.
+     *
+     * Asked once and shared by concurrent callers; the answer is dropped when the interface
+     * subscribes again. A process that does not have `system.listMethods` either is remembered for
+     * the connection, so it is not asked after every re-`init`; any other failure is forgotten, and
+     * the next caller asks again.
+     */
+    #methodList(interfaceName) {
+        if (this.#noListMethods.has(interfaceName)) {
+            return Promise.resolve(undefined);
+        }
+        const cached = this.#listedMethods.get(interfaceName);
+        if (cached) {
+            return cached;
+        }
+        const pending = this.#read(interfaceName, 'system.listMethods', []).then((answer) => {
+            const names = asStrings(answer);
+            return names.length === 0 ? undefined : new Set(names);
+        }, (error) => {
+            if (isMethodUnsupported(error)) {
+                this.#noListMethods.add(interfaceName);
+            }
+            if (this.#listedMethods.get(interfaceName) === pending) {
+                this.#listedMethods.delete(interfaceName);
+            }
+            return undefined;
+        });
+        this.#listedMethods.set(interfaceName, pending);
+        return pending;
     }
     /** Reads the BidCos service messages of one interface into the store. */
     async #refreshServiceMessages(interfaceName) {
-        if (!this.#hasServiceMessages(interfaceName)) {
+        if (!(await this.#hasServiceMessages(interfaceName))) {
             return;
         }
         try {
             const answer = await this.#read(interfaceName, 'getServiceMessages', []);
+            if (this.#serviceMessageFailures.delete(interfaceName)) {
+                this.#notice('info', `${interfaceName}: getServiceMessages answers again`, interfaceName);
+            }
             if (!Array.isArray(answer)) {
                 return;
             }
@@ -1176,8 +1265,14 @@ export class Backend {
             // of it on hardware (task 17). Remembered, and never asked again this session.
             if (isMethodUnsupported(error)) {
                 this.#noServiceMessages.add(interfaceName);
+                this.#serviceMessageFailures.delete(interfaceName);
+                return;
+            }
+            // B-26 (#158): once per interface until a call succeeds again, not once per poll
+            if (this.#serviceMessageFailures.has(interfaceName)) {
                 return;
             }
+            this.#serviceMessageFailures.add(interfaceName);
             this.#notice('info', `${interfaceName}: getServiceMessages failed: ${errorMessage(error)}`, interfaceName);
         }
     }

package/node_modules/@homematic-manager/backend/dist/config/store.d.ts

@@ -17,10 +17,26 @@
  * D-17's one-time import of the 2.x configuration happens exactly when there is no `config.json`
  * yet, which is the only definition of "first start" that survives a reinstall.
  */
-import type { AppConfig, ConnectionConfig, DiscoveredCcu } from '@homematic-manager/core';
+import type { AppConfig, CallbackPins, ConnectionConfig, DiscoveredCcu } from '@homematic-manager/core';
 import { type LegacyEnvironment } from './legacyImport.js';
 /** A host as a directory name: everything unusual becomes `_`. */
 export declare function hostKey(host: string): string;
+/**
+ * Task 38: the callback fields the host was started with (`HMM_CALLBACK_*`, `--callback-*`). An
+ * empty address and a port of `0` are "nothing set" in the connection model, so they pin nothing.
+ */
+export interface PinnedCallback {
+    readonly ip?: string | undefined;
+    readonly xmlrpcPort?: number | undefined;
+    readonly binrpcPort?: number | undefined;
+}
+type CallbackField = keyof CallbackPins;
+/** A saved callback value the host's own one replaced on this start. */
+export interface IgnoredCallbackValue {
+    readonly field: CallbackField;
+    readonly saved: string | number;
+    readonly pinned: string | number;
+}
 export interface ConfigStoreOptions {
     /** The profile directory; created on the first write. */
     readonly dataDir: string;
@@ -32,6 +48,12 @@ export interface ConfigStoreOptions {
     readonly importLegacy?: boolean;
     /** Where the 2.x configuration is looked for; injected by the tests. */
     readonly legacyEnvironment?: LegacyEnvironment;
+    /**
+     * Task 38: callback fields set at start. They win over `config.json` in everything the store
+     * hands out, a `setConnection` cannot change them, and they are never written to the file - the
+     * file keeps what the user saved, so a start without the option goes back to that.
+     */
+    readonly pinnedCallback?: PinnedCallback;
 }
 /** The persisted `AppConfig` plus the derived fields the UI wants with it. */
 export declare class ConfigStore {
@@ -39,6 +61,10 @@ export declare class ConfigStore {
     readonly dataDir: string;
     readonly file: string;
     private constructor();
+    /** Task 38: which callback fields the host pinned; `undefined` when it pinned none. */
+    get callbackPins(): CallbackPins | undefined;
+    /** Task 38: the saved callback values a pinned one replaced when the store was opened. */
+    get ignoredCallback(): readonly IgnoredCallbackValue[];
     /** Loads the configuration, importing the 2.x one when this is the first start (D-17). */
     static open(options: ConfigStoreOptions): Promise<ConfigStore>;
     get importedFromLegacy(): boolean;
@@ -55,4 +81,5 @@ export declare class ConfigStore {
     cacheFile(name: string): string;
     save(): Promise<void>;
 }
+export {};
 //# sourceMappingURL=store.d.ts.map

package/node_modules/@homematic-manager/backend/dist/config/store.js

@@ -30,13 +30,23 @@ export function hostKey(host) {
         .replace(/[^a-z0-9._-]/g, '_');
     return key === '' ? 'unconfigured' : key;
 }
+const CALLBACK_FIELDS = ['ip', 'xmlrpcPort', 'binrpcPort'];
+function pinnedValue(pinned, field) {
+    const value = pinned[field];
+    return value === undefined || value === '' || value === 0 ? undefined : value;
+}
 /** The persisted `AppConfig` plus the derived fields the UI wants with it. */
 export class ConfigStore {
     dataDir;
     file;
     #version;
     #localAddresses;
+    #pinned;
+    #ignored = [];
+    /** The effective connection: the saved one with the pinned callback fields over it. */
     #connection;
+    /** Task 38: the callback as the user saved it, which is what `config.json` keeps. */
+    #savedCallback;
     #discovered = [];
     /** True when the connection came from the 2.x configuration on this start (D-17). */
     #importedFromLegacy = false;
@@ -45,8 +55,42 @@ export class ConfigStore {
         this.file = path.join(options.dataDir, 'config.json');
         this.#version = options.version;
         this.#localAddresses = options.localAddresses ?? (() => localIPv4Addresses());
-        this.#connection = connection;
+        this.#pinned = options.pinnedCallback ?? {};
+        this.#savedCallback = connection.callback;
+        this.#connection = this.#withPins(connection);
         this.#importedFromLegacy = imported;
+        for (const field of CALLBACK_FIELDS) {
+            const pinned = pinnedValue(this.#pinned, field);
+            const saved = connection.callback[field];
+            // an empty address or a 0 saved nothing, so nothing is being ignored
+            if (pinned !== undefined && saved !== '' && saved !== 0 && saved !== pinned) {
+                this.#ignored.push({ field, saved, pinned });
+            }
+        }
+    }
+    #withPins(connection) {
+        const callback = { ...connection.callback };
+        for (const field of CALLBACK_FIELDS) {
+            const pinned = pinnedValue(this.#pinned, field);
+            if (pinned !== undefined) {
+                callback[field] = pinned;
+            }
+        }
+        return { ...connection, callback };
+    }
+    /** Task 38: which callback fields the host pinned; `undefined` when it pinned none. */
+    get callbackPins() {
+        const pins = {};
+        for (const field of CALLBACK_FIELDS) {
+            if (pinnedValue(this.#pinned, field) !== undefined) {
+                pins[field] = true;
+            }
+        }
+        return Object.keys(pins).length === 0 ? undefined : pins;
+    }
+    /** Task 38: the saved callback values a pinned one replaced when the store was opened. */
+    get ignoredCallback() {
+        return this.#ignored;
     }
     /** Loads the configuration, importing the 2.x one when this is the first start (D-17). */
     static async open(options) {
@@ -80,7 +124,16 @@ export class ConfigStore {
     }
     /** Replaces the connection and persists it. */
     async setConnection(connection) {
-        this.#connection = normaliseConnection(connection);
+        const normalised = normaliseConnection(connection);
+        // Task 38: a pinned field keeps what the file had; whatever came in for it is not saved
+        const savedCallback = { ...normalised.callback };
+        for (const field of CALLBACK_FIELDS) {
+            if (pinnedValue(this.#pinned, field) !== undefined) {
+                savedCallback[field] = this.#savedCallback[field];
+            }
+        }
+        this.#savedCallback = savedCallback;
+        this.#connection = this.#withPins(normalised);
         this.#importedFromLegacy = false;
         await this.save();
         return this.config;
@@ -98,7 +151,10 @@ export class ConfigStore {
         return path.join(this.cacheDir, name);
     }
     async save() {
-        await writeJsonFile(this.file, { version: this.#version, connection: this.#connection });
+        await writeJsonFile(this.file, {
+            version: this.#version,
+            connection: { ...this.#connection, callback: this.#savedCallback },
+        });
     }
 }
 //# sourceMappingURL=store.js.map

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

@@ -73,4 +73,10 @@ export declare function isMethodUnsupported(value: unknown): boolean;
  * the message text as well, because `connectionError()` composes its text before the cause is set.
  */
 export declare function isConnectionRefused(value: unknown): boolean;
+/**
+ * Task 38: a callback server's bind failed because another process holds the port - hm2mqtt.js on
+ * the same pair, or a second container on the host network. Looked for along the `cause` chain and
+ * in the text, for the same reason as {@link isConnectionRefused}.
+ */
+export declare function isAddressInUse(value: unknown): boolean;
 //# sourceMappingURL=errors.d.ts.map

package/node_modules/@homematic-manager/backend/dist/errors.js

@@ -133,8 +133,10 @@ const UNSUPPORTED_METHOD_PATTERNS = [
     /unknown xml-rpc tag/i,
     // binrpc's own parser
     /malformed response/i,
-    // an interface that answers XML-RPC properly but has no handler for the method
-    /unknown method/i,
+    // an interface that answers XML-RPC properly but has no handler for the method. rfd words it
+    // `unknown method name`, CUxD `unknown.method name` - both with faultCode -1, which is also
+    // eq-3's "generic error", so the code alone says nothing (B-26, #158)
+    /unknown[ ._]method/i,
     /method not found/i,
 ];
 /** The standard XML-RPC fault code for a method the server does not have. */
@@ -182,4 +184,20 @@ export function isConnectionRefused(value) {
     }
     return /\bECONNREFUSED\b/.test(errorMessage(value));
 }
+/**
+ * Task 38: a callback server's bind failed because another process holds the port - hm2mqtt.js on
+ * the same pair, or a second container on the host network. Looked for along the `cause` chain and
+ * in the text, for the same reason as {@link isConnectionRefused}.
+ */
+export function isAddressInUse(value) {
+    let current = value;
+    for (let depth = 0; current !== undefined && current !== null && depth < 10; depth += 1) {
+        const candidate = current;
+        if (candidate.code === 'EADDRINUSE') {
+            return true;
+        }
+        current = candidate.cause;
+    }
+    return /\bEADDRINUSE\b/.test(errorMessage(value));
+}
 //# sourceMappingURL=errors.js.map

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

@@ -19,7 +19,7 @@
  * dialog. 2.x probed six ports with a 5 s timeout each before the window became usable, which is
  * the root of the "endless loading" issues #121, #126, #128 and #134.
  */
-import type { ConnectionConfig, InterfaceState, ResolvedInterface } from '@homematic-manager/core';
+import type { CallbackPins, ConnectionConfig, InterfaceState, ResolvedInterface } from '@homematic-manager/core';
 import { type InterfaceTarget } from '../config/defaults.js';
 import { RpcClient, type RpcCallRecord, type RpcClientOptions } from '../rpc/client.js';
 import { type CallbackHandler, type CallbackServerSet } from '../rpc/server.js';
@@ -83,6 +83,11 @@ export interface InterfaceManagerOptions {
         readonly xmlrpc: number;
         readonly binrpc: number;
     };
+    /**
+     * Task 38: the callback fields the host set at start. Only used to name the option in the log
+     * line of a fixed port that cannot be opened.
+     */
+    readonly callbackPins?: CallbackPins;
     /** Injected by the tests. */
     readonly createClient?: (options: RpcClientOptions) => RpcClient;
     readonly createCallbackServers?: (handler: CallbackHandler) => CallbackServerSet;