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

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, 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;
@@ -87,6 +93,8 @@ export class Backend {
      */
     #noServiceMessages = 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 +166,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(', ')}`);
@@ -483,6 +499,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
                 ? {}
@@ -821,9 +838,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;

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

@@ -182,4 +182,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;

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

@@ -19,8 +19,8 @@
  * 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 { INTERFACE_NAMES, interfaceDefinition, interfacePort, isKnownInterface } from '@homematic-manager/core';
-import { configError, connectionError, errorMessage, isConnectionRefused } from '../errors.js';
+import { INTERFACE_NAMES, callbackPinOption, interfaceDefinition, interfacePort, isKnownInterface, } from '@homematic-manager/core';
+import { configError, connectionError, errorMessage, isAddressInUse, isConnectionRefused } from '../errors.js';
 import { interfaceTargets } from '../config/defaults.js';
 import { RpcClient } from '../rpc/client.js';
 import { CallbackServers } from '../rpc/server.js';
@@ -82,6 +82,13 @@ export class InterfaceManager {
     #now;
     #interfaces = new Map();
     #servers;
+    /**
+     * Task 38: protocols whose fixed callback port could not be opened. Their interfaces are not
+     * subscribed - an `init` with a URL nobody listens on would only look like a working one - and
+     * a later `init` attempt tries the port again.
+     */
+    #callbackFailures = new Map();
+    #reopening = new Map();
     #watchdog;
     #detected = [];
     #stopping = false;
@@ -180,7 +187,17 @@ export class InterfaceManager {
             throw configError('no interface selected');
         }
         for (const protocol of new Set(targets.map((target) => target.resolved.protocol))) {
-            await this.#servers.ensure(protocol);
+            try {
+                await this.#servers.ensure(protocol);
+            }
+            catch (error) {
+                // a free port (0, or task 35's fallback failing too) that cannot be had is what it was
+                const port = this.#fixedCallbackPort(protocol);
+                if (port === 0) {
+                    throw error;
+                }
+                this.#noteCallbackFailure(protocol, port, error);
+            }
         }
         for (const target of targets) {
             this.#interfaces.set(target.resolved.name, this.#create(target));
@@ -344,7 +361,7 @@ export class InterfaceManager {
     }
     /** `init(url, '')` with a hard timeout; a CCU that is gone must not hold anything up. */
     async #deregister(entry) {
-        if (!entry.target.resolved.init) {
+        if (!entry.target.resolved.init || this.#callbackFailures.has(entry.target.resolved.protocol)) {
             return;
         }
         const url = this.#callbackUrl(entry.target.resolved.protocol);
@@ -392,6 +409,62 @@ export class InterfaceManager {
     #callbackUrl(protocol) {
         return this.#servers.callbackUrl(protocol, this.callbackIp);
     }
+    /** The port the connection fixes for a protocol; `0` when it leaves the choice to the host. */
+    #fixedCallbackPort(protocol) {
+        const { callback } = this.#options.connection;
+        return protocol === 'binrpc' ? callback.binrpcPort : callback.xmlrpcPort;
+    }
+    /**
+     * Task 38: a fixed callback port that cannot be opened is loud, once, and never replaced by a
+     * free port. In a container a free port is exactly the one nobody published, and behind a
+     * firewall the one nobody opened: the interfaces would be subscribed and silent.
+     */
+    #noteCallbackFailure(protocol, port, error) {
+        const inUse = isAddressInUse(error);
+        const field = protocol === 'binrpc' ? 'binrpcPort' : 'xmlrpcPort';
+        const source = this.#options.callbackPins?.[field] === true
+            ? callbackPinOption(field)
+            : `connection.callback.${field} in the settings`;
+        const what = inUse ? 'is in use' : 'cannot be opened';
+        this.#callbackFailures.set(protocol, { port, inUse, message: `callback port ${String(port)} ${what}` });
+        this.#options.onNotice('error', `callback server: the ${protocol} port ${String(port)} set by ${source} ${what} - the ${protocol} ` +
+            `interfaces are not subscribed and get no events, and no free port is taken instead ` +
+            `(${errorMessage(error)})`);
+    }
+    /** Task 38: one more try at a failed fixed port, shared by every interface of the protocol. */
+    #reopenCallbackServer(protocol) {
+        const pending = this.#reopening.get(protocol);
+        if (pending) {
+            return pending;
+        }
+        const attempt = this.#servers
+            .ensure(protocol)
+            .then((port) => {
+            this.#callbackFailures.delete(protocol);
+            this.#options.onNotice('info', `callback server: the ${protocol} port ${String(port)} is open now`);
+            return true;
+        }, () => false)
+            .finally(() => {
+            this.#reopening.delete(protocol);
+        });
+        this.#reopening.set(protocol, attempt);
+        return attempt;
+    }
+    /** Task 38: an interface whose callback server is not there; backs off like a failed `init`, silently. */
+    #noteNoCallbackServer(entry, failure) {
+        entry.failures += 1;
+        const base = this.#options.initBackoffMs ?? WATCHDOG_INTERVAL_MS;
+        entry.retryAt = this.#now() + Math.min(base * 2 ** (entry.failures - 1), MAX_INIT_BACKOFF_MS);
+        this.#update(entry, {
+            connected: false,
+            error: failure.message,
+            absent: false,
+            subscribing: false,
+            callbackUrl: undefined,
+            callbackFailure: { port: failure.port, inUse: failure.inUse },
+        });
+        this.#options.onStateChanged(this.states());
+    }
     async #init(interfaceName) {
         const entry = this.#interfaces.get(interfaceName);
         if (!entry || this.#stopping) {
@@ -404,7 +477,14 @@ export class InterfaceManager {
             entry.lastEvent = this.#now();
             return;
         }
+        const failure = this.#callbackFailures.get(resolved.protocol);
+        // the first attempt comes straight after the failed bind in `start()`; only a retry binds again
+        if (failure !== undefined && (entry.failures === 0 || !(await this.#reopenCallbackServer(resolved.protocol)))) {
+            this.#noteNoCallbackServer(entry, this.#callbackFailures.get(resolved.protocol) ?? failure);
+            return;
+        }
         const url = this.#callbackUrl(resolved.protocol);
+        this.#update(entry, { callbackUrl: url, callbackFailure: undefined });
         try {
             await entry.client.call('init', [url, resolved.ident]);
             entry.lastEvent = this.#now();
@@ -483,6 +563,22 @@ export class InterfaceManager {
                 state.error = changes.error;
             }
         }
+        if ('callbackUrl' in changes) {
+            if (changes.callbackUrl === undefined) {
+                delete state.callbackUrl;
+            }
+            else {
+                state.callbackUrl = changes.callbackUrl;
+            }
+        }
+        if ('callbackFailure' in changes) {
+            if (changes.callbackFailure === undefined) {
+                delete state.callbackFailure;
+            }
+            else {
+                state.callbackFailure = changes.callbackFailure;
+            }
+        }
         entry.state = state;
     }
     #startWatchdog() {

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

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