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

package/node_modules/@homematic-manager/backend/dist/groups/client.js

@@ -0,0 +1,233 @@
+/**
+ * Task 57: the HTTP client for openccu-lite's heating groups - `/api/system/v1/groups`.
+ *
+ * The heating groups (the `VirtualDevices` group devices `INT000000N`) are the group process's,
+ * and that process has no RPC method to create one, change its members or delete it: the CCU's
+ * WebUI does all of that through the process's own HTTP pages, behind a WebUI session. On
+ * openccu-lite the box's `occulited` is the one client of those pages and offers them as a plain
+ * JSON API with the box's own login - the one this application already has for the metadata store
+ * (D-40). This client speaks that API and nothing else; on a CCU it is never built.
+ *
+ * Like the metadata client: `fetch` and `AbortSignal` only, a typed answer or a thrown
+ * {@link BackendError} whose `kind` says what the UI should make of it. The box's error body
+ * (`{error, message}`) is kept, because its message is the one worth showing - "there is no group
+ * 7", "members: hmipserver's device ids, as GET /groups/types lists them".
+ */
+import { BackendError } from '../errors.js';
+/**
+ * How long a call may take. A change makes the box's group process configure direct links, and the
+ * box itself waits up to thirty seconds for that process before it answers `502`; this has to
+ * outlast it, or the UI reports a timeout for a change that went through.
+ */
+export const GROUPS_TIMEOUT_MS = 45_000;
+/** The box refused or could not answer; `status` and `code` are what it said. */
+export class HeatingGroupsApiError extends BackendError {
+    status;
+    /** The API's error word: `unknown-group`, `invalid`, `unsupported`, `hmipserver`, `forbidden`. */
+    code;
+    constructor(status, code, message) {
+        super({ message, kind: kindOf(status, code) });
+        this.name = 'HeatingGroupsApiError';
+        this.status = status;
+        this.code = code;
+    }
+}
+/**
+ * What the UI should make of a status: a credential problem is `config` (the settings dialog is
+ * where the token lives), a refused body or an id the box no longer has is `validation` (the
+ * dialog shows the message), a box or group process that does not answer is `connection`.
+ */
+function kindOf(status, code) {
+    if (status === 401 || status === 403 || code === 'unsupported') {
+        return 'config';
+    }
+    if (status === 404 || status === 422 || status === 400) {
+        return 'validation';
+    }
+    if (status === 502 || status === 503 || status === 504) {
+        return 'connection';
+    }
+    return 'internal';
+}
+export class HeatingGroupsClient {
+    #options;
+    #fetch;
+    constructor(options) {
+        this.#options = options;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+    }
+    get baseUrl() {
+        return this.#options.baseUrl;
+    }
+    /**
+     * Does this box have the groups API, and may this credential read it? One `GET /groups`; the
+     * answer's status is the whole result. Never throws: the state is what the UI decides the tab by.
+     */
+    async probe() {
+        try {
+            await this.#json('GET', '/groups');
+            return { available: true };
+        }
+        catch (error) {
+            if (error instanceof HeatingGroupsApiError) {
+                if (error.code === 'unsupported') {
+                    return { available: false, reason: 'unsupported', message: error.message };
+                }
+                if (error.status === 401 || error.status === 403) {
+                    return { available: false, reason: 'forbidden', message: error.message };
+                }
+                if (error.status === 404) {
+                    // an older box: the route itself is missing, not a group
+                    return { available: false, reason: 'not-offered', message: error.message };
+                }
+            }
+            return { available: false, reason: 'error', message: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    /**
+     * `GET /groups`, then each group once for its members - the list itself names none, and a
+     * grid of groups without their members would say nothing. A group whose detail fails (deleted
+     * between the two calls) is listed without members rather than failing the list.
+     */
+    async list() {
+        const answer = (await this.#json('GET', '/groups'));
+        const groups = await Promise.all((answer.groups ?? []).map(async (wire) => {
+            let members = [];
+            try {
+                members = (await this.get(wire.id)).members;
+            }
+            catch {
+                // listed without members; the next refresh has them, or the group is gone
+            }
+            return { ...toGroup(wire), members };
+        }));
+        return { groups, devicesToConfigure: answer.devices_to_configure ?? [] };
+    }
+    /** `GET /groups/types` - what a new group can be, and what each type could take now. */
+    async types() {
+        const answer = (await this.#json('GET', '/groups/types'));
+        return (answer.types ?? []).map((type) => ({
+            id: type.id ?? '',
+            label: type.label ?? type.id ?? '',
+            assignable: type.assignable ?? [],
+            leftover: type.leftover ?? [],
+        }));
+    }
+    /** `GET /groups/{id}`. */
+    async get(id) {
+        return toDetail((await this.#json('GET', `/groups/${String(id)}`)));
+    }
+    /** `POST /groups` - the box's `create` then `save`, and the metadata side effects in one go. */
+    async create(name, type, members) {
+        return toChange((await this.#json('POST', '/groups', { name, type, members: [...members] })));
+    }
+    /**
+     * `PUT /groups/{id}` - the name and the members as a whole; a field left out keeps its value.
+     * Adding and removing is this call with the new list, exactly as the WebUI saved it.
+     */
+    async update(id, change) {
+        const body = {
+            ...(change.name === undefined ? {} : { name: change.name }),
+            ...(change.members === undefined ? {} : { members: [...change.members] }),
+        };
+        return toChange((await this.#json('PUT', `/groups/${String(id)}`, body)));
+    }
+    /** `DELETE /groups/{id}` - answers with the former members, whose group membership is gone. */
+    async remove(id) {
+        const answer = (await this.#json('DELETE', `/groups/${String(id)}`));
+        return answer.former_members ?? [];
+    }
+    #url(route) {
+        return `${this.#options.baseUrl.replace(/\/$/, '')}/api/system/v1${route}`;
+    }
+    async #json(method, route, body) {
+        const credential = this.#options.credential();
+        let response;
+        try {
+            response = await this.#fetch(this.#url(route), {
+                method,
+                signal: AbortSignal.timeout(this.#options.timeoutMs ?? GROUPS_TIMEOUT_MS),
+                headers: {
+                    Accept: 'application/json',
+                    ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+                    ...(credential === undefined ? {} : { Authorization: `Bearer ${credential}` }),
+                },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            });
+        }
+        catch (error) {
+            // the box is off, or the change outlasted the timeout above
+            throw new BackendError({
+                message: `the groups API at ${this.#options.baseUrl} did not answer: ${errorText(error)}`,
+                kind: 'connection',
+            }, { cause: error });
+        }
+        if (!response.ok) {
+            throw await refusal(response);
+        }
+        if (response.status === 204) {
+            return {};
+        }
+        try {
+            return await response.json();
+        }
+        catch (error) {
+            throw new BackendError({ message: `the groups API answered ${String(response.status)} without JSON`, kind: 'internal' }, { cause: error });
+        }
+    }
+}
+function toGroup(wire) {
+    return {
+        id: wire.id,
+        name: wire.name,
+        type: wire.type,
+        typeLabel: wire.type_label ?? wire.type,
+        device: wire.device,
+        ref: wire.ref,
+    };
+}
+function toDetail(wire) {
+    const types = wire.types ?? [];
+    return {
+        id: wire.id,
+        name: wire.name,
+        type: wire.type,
+        typeLabel: types.find((type) => type.id === wire.type)?.label ?? wire.type,
+        device: wire.device,
+        ref: wire.ref,
+        deviceName: wire.device_name ?? '',
+        forbidSingleOperation: wire.forbid_single_operation === true,
+        members: wire.members ?? [],
+        assignable: wire.assignable ?? [],
+        leftover: wire.leftover ?? [],
+        types,
+    };
+}
+function toChange(wire) {
+    return { ...toDetail(wire), devicesToConfigure: wire.devices_to_configure ?? [] };
+}
+/** The API's `{error, message}` body as the error, or the status when there is none. */
+async function refusal(response) {
+    let code = response.status === 401 || response.status === 403 ? 'forbidden' : 'error';
+    let message = `${String(response.status)} ${response.statusText}`.trim();
+    try {
+        const body = (await response.json());
+        if (typeof body.error === 'string') {
+            code = body.error;
+        }
+        if (typeof body.message === 'string') {
+            message = body.message;
+        }
+    }
+    catch {
+        // not JSON: lighttpd's own error page, or a box that is not openccu-lite at all
+    }
+    if (response.status === 401 || response.status === 403) {
+        message = `the system refused the credential for the heating groups (${String(response.status)}): ${message}`;
+    }
+    return new HeatingGroupsApiError(response.status, code, message);
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=client.js.map

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

@@ -31,6 +31,7 @@ export * from './cache/names.js';
 export * from './cache/unreach.js';
 export * from './cache/store.js';
 export * from './meta/index.js';
+export * from './groups/client.js';
 export * from './write/queue.js';
 export * from './write/paramset.js';
 export * from './rega/auth.js';

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

@@ -36,6 +36,8 @@ export * from './cache/unreach.js';
 export * from './cache/store.js';
 // the metadata store: names, rooms and functions, local or from an openccu-lite box (task 24)
 export * from './meta/index.js';
+// the heating groups of openccu-lite, through the box's system API (task 57)
+export * from './groups/client.js';
 // the write path (task 6)
 export * from './write/queue.js';
 export * from './write/paramset.js';

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

@@ -10,6 +10,12 @@
  *    `ping`, whose answer arrives as an event and resets the clock. HmIP-RF gets 600 s because
  *    hmipserver answers pings but sends events rarely (eq-3/occu#42); an interface that answers no
  *    ping at all (VirtualDevices) is watched by events only.
+ *    At the start (task 56, D-52) an `init` that is refused or times out is not left to the watchdog:
+ *    it is tried again after 1, 2, 4 and 8 s and then every 2 s, and the interface shows *waiting*.
+ *    HmIP-RF has a liveness ping of its own besides (B-56, D-53): after 30 s of silence it is
+ *    pinged, and a missing PONG 10 s later means hmipserver has restarted - it reads its handler
+ *    list back but sends nothing until the client calls `init` again - so the interface shows
+ *    *reconnecting* and is subscribed again on the quick schedule of the start.
  * 3. `init(url, '')` on shutdown, so the CCU stops calling a process that is gone - with a hard
  *    timeout, because 2.x's `stop()` waited for an unreachable CCU and only a second `stop()` (or
  *    the 15 s fallback timer) got the app closed.
@@ -39,6 +45,34 @@ export declare const SHUTDOWN_TIMEOUT_MS = 5000;
  * then with a doubling delay up to this ceiling, and only the first failure produces a notice.
  */
 export declare const MAX_INIT_BACKOFF_MS = 300000;
+/**
+ * Task 56 (D-52): the waits between the `init` attempts of an interface that refuses or does not
+ * answer at the start, before {@link START_RETRY_INTERVAL_MS} takes over.
+ *
+ * On openccu-lite the addon may start before the interface processes (`runtime.start: "early"`):
+ * a Raspberry Pi 3 measured the first `init` 45 s before hmipserver answered, and on the 15 s watchdog
+ * ticks with the doubling back-off below HmIP-RF was asked again only 17 s after it was there.
+ */
+export declare const START_RETRY_DELAYS_MS: readonly number[];
+/**
+ * Task 56 (D-57): the wait between two start attempts after {@link START_RETRY_DELAYS_MS}.
+ *
+ * D-52 had 15 s here. Measured on openccu-lite with the addon started early, that made HmIP-RF on a
+ * Raspberry Pi 4 connect 2-3 s *later* than when the addon waits for hmipserver, because hmipserver
+ * came up between two attempts 15 s apart; with 2 s it connected 9.6 s earlier. A refused
+ * connection on the loopback every 2 s for at most the start window costs nothing.
+ */
+export declare const START_RETRY_INTERVAL_MS = 2000;
+/**
+ * Task 56: how long after `start()` (or a D-31 resubscribe) an interface that has not answered yet
+ * is *waiting* rather than missing. Two minutes cover a Raspberry Pi 3 booting with the addon
+ * started early, where the interface processes come up about 50 s after it. After the window the
+ * interface is treated as before: "not present" or "not answering", said once, and tried with the
+ * back-off up to {@link MAX_INIT_BACKOFF_MS} - a CCU without a wired gateway never runs `hs485d`.
+ */
+export declare const START_WINDOW_MS = 120000;
+/** Task 56: the wait before start attempt number `attempt` (1 for the first retry). */
+export declare function startRetryDelay(attempt: number): number;
 /**
  * D-31: the grace period a server install waits, with no UI session connected, before it drops its
  * event subscriptions. Five minutes; `0` turns the whole thing off, which is what Electron uses.
@@ -49,25 +83,69 @@ export interface ManagedInterface {
     readonly target: InterfaceTarget;
     readonly client: RpcClient;
     state: InterfaceState;
-    /** Milliseconds since epoch of the last event, ping answer or successful `init`. */
+    /**
+     * Milliseconds since epoch of the last event, ping answer or successful `init` - for the state
+     * the UI shows, never for a timeout (B-65: see {@link lastSeenMono}).
+     */
     lastEvent: number;
+    /**
+     * B-65: the same moment on the monotonic clock, which the watchdog measures the silence
+     * against. On the wall clock a box without a real-time clock, whose date NTP moves months
+     * forward a few seconds after the start, made every interface look silent once and re-`init`ed
+     * it. `-Infinity` until the first one, so an interface never heard of is due at once.
+     */
+    lastSeenMono: number;
     /** Consecutive failed `init` calls; 0 as soon as one succeeds. */
     failures: number;
-    /** Milliseconds since epoch before which the watchdog does not try `init` again. */
+    /** On the monotonic clock (B-65): the moment before which the watchdog does not try `init` again. */
     retryAt: number;
+    /** Task 56: failed `init` attempts while waiting at the start; 0 once it answered. */
+    waitingAttempts: number;
+    /** Task 56: the timer of the next start attempt, which the watchdog then leaves alone. */
+    retryTimer: ReturnType<typeof setTimeout> | undefined;
+    /** Task 56: `init` succeeded since the last start - its failures are an outage, not a start. */
+    answered: boolean;
+    /**
+     * Task 56, B-56: when the current window of quick retries began, on the monotonic clock - the
+     * start (or a D-31 resubscribe) for every interface, or the moment a liveness ping went
+     * unanswered for this one.
+     */
+    windowStart: number;
+    /** B-56: the last event on the monotonic clock, for the liveness ping. */
+    lastEventMono: number;
+    /**
+     * B-56: an event arrived since the last successful `init`. Only then does a missing PONG mean
+     * that the subscription was lost: an interface that never reached us - a callback address the
+     * CCU cannot reach - would otherwise be re-`init`ed every 40 s, and hmipserver re-sends every
+     * device at each `init` (occu#45).
+     */
+    heardSinceInit: boolean;
+    /** B-56: the timer of the next liveness check, and the one waiting for its PONG. */
+    livenessTimer: ReturnType<typeof setTimeout> | undefined;
+    /** B-56: lost its subscription (no PONG) and is being subscribed again. */
+    reconnecting: boolean;
+    /** B-56: a liveness ping is out and its PONG is being waited for. */
+    awaitingPong: boolean;
 }
 export interface InterfaceManagerOptions {
     readonly connection: ConnectionConfig;
     /** What the callback servers do with an incoming call. */
     readonly handler: CallbackHandler;
     readonly onStateChanged: (states: InterfaceState[]) => void;
-    readonly onNotice: (level: 'info' | 'warn' | 'error', message: string, interfaceName?: string) => void;
+    readonly onNotice: (level: 'debug' | 'info' | 'warn' | 'error', message: string, interfaceName?: string) => void;
     /** Called after a successful `init`; the backend fills its caches there. */
     readonly onConnected?: (interfaceName: string) => void | Promise<void>;
     readonly onCall?: (record: RpcCallRecord) => void;
     /** Task 48: the origin of a call that names none, handed to every client (the backend's request context). */
     readonly originOf?: RpcClientOptions['originOf'];
     readonly now?: () => number;
+    /**
+     * Task 56: a clock that only moves forward, for the start window. The wall clock is no use
+     * there: a box without a real-time clock boots with a date months old and NTP moves it forward
+     * a few seconds after the start (seen on a Raspberry Pi 4, where the jump ended the window at
+     * once). Defaults to `performance.now()`.
+     */
+    readonly monotonicNow?: () => number;
     readonly rpcTimeoutMs?: number;
     readonly watchdogIntervalMs?: number;
     /**
@@ -76,6 +154,18 @@ export interface InterfaceManagerOptions {
      * interface that fails once and then works.
      */
     readonly initBackoffMs?: number;
+    /**
+     * Task 56: how long after the start a refused or unanswered `init` means *waiting*; defaults to
+     * {@link START_WINDOW_MS}. `0` turns the quick start retries off.
+     */
+    readonly startWindowMs?: number;
+    /**
+     * B-56: overrides the liveness ping interval of every interface that has one (HmIP-RF, 30 s in
+     * the table); `0` turns the liveness ping off. The PONG timeout is {@link pongTimeoutMs}.
+     */
+    readonly pingIntervalMs?: number;
+    /** B-56: how long the PONG may take; defaults to {@link PONG_TIMEOUT_SECONDS}. */
+    readonly pongTimeoutMs?: number;
     /** Address to bind the callback servers to; left out, {@link callbackBindHost} decides. */
     readonly callbackHost?: string;
     /**
@@ -91,6 +181,14 @@ export interface InterfaceManagerOptions {
      * line of a fixed port that cannot be opened.
      */
     readonly callbackPins?: CallbackPins;
+    /**
+     * B-69: whether the interface lists any device now - the backend's device cache. An interface
+     * that answers no ping (VirtualDevices) is watched by its events alone, and with no device it
+     * has nothing to send: on a system without virtual groups the group process was subscribed
+     * again every time its event timeout ran out, about every 75 s. Left out, every such interface
+     * is judged by its events, as before.
+     */
+    readonly listsDevices?: (interfaceName: string) => boolean;
     /** Injected by the tests. */
     readonly createClient?: (options: RpcClientOptions) => RpcClient;
     readonly createCallbackServers?: (handler: CallbackHandler) => CallbackServerSet;
@@ -190,8 +288,16 @@ export declare class InterfaceManager {
     subscribe(): Promise<void>;
     /** One watchdog round; public so a test can drive it without waiting 15 s. */
     tick(): Promise<void>;
-    /** A callback arrived; the interface is alive. */
-    noteEvent(interfaceName: string): void;
+    /**
+     * A callback arrived; the interface is alive.
+     *
+     * B-56: only an `event` proves that the subscription delivers. A device callback (`newDevices`,
+     * `deleteDevices`, …) does not: a restarted hmipserver announces its devices to the handler it
+     * read back, and then sends it no event at all (measured on a Raspberry Pi 4, 16 s after the
+     * restart). Such a callback that nobody asked for is the moment to check, so the liveness ping
+     * goes out at once.
+     */
+    noteEvent(interfaceName: string, kind?: 'event' | 'device'): void;
     /** `interfaces.reconnect`: subscribes again, to one interface or to all of them. */
     reconnect(interfaceName?: string): Promise<void>;
     /**