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

package/node_modules/@homematic-manager/backend/dist/meta/occuliteProvider.js

@@ -0,0 +1,305 @@
+/**
+ * The `occulite` provider: names, rooms and functions from an openccu-lite box, and written back
+ * to it.
+ *
+ * The shape of it is the one openccu-lite's porting kit prescribes and the one their own
+ * `occulited` expects: **snapshot once, then follow the change stream**, and re-snapshot when the
+ * stream says the history is gone (`resync`), when a whole store was imported, or when a revision
+ * arrives that is not the next one. Nothing polls. A rename made in another frontend, or by another
+ * person in another browser, is in this application's grid inside a second.
+ *
+ * Failure is degradation, never an exception (their invariant 5, our D-2):
+ *
+ * - the box is off → the last snapshot from the cache file, `reachable: false`, one notice, and a
+ *   reconnect loop with a backoff;
+ * - the credential is refused (401) → no names rather than no application, one notice, and a retry
+ *   on the next reconnect;
+ * - the credential may read but not write (403) → the names are shown and `writable` is false, so
+ *   the UI can say why the rename button does nothing.
+ *
+ * The snapshot is persisted where the ReGa provider persists its names, for the same reason: a
+ * restart while the box is unreachable must not leave the grid nameless.
+ */
+import { applyEvent, emptyDocument, isMetaError, parseDocument, summariseAll, } from '@homematic-manager/core';
+import { errorMessage } from '../errors.js';
+import { readJsonFile, writeJsonFile } from '../util/jsonFile.js';
+import { MetaApiClient } from './client.js';
+/** First wait before the event stream is opened again, in milliseconds. */
+export const RECONNECT_MIN_MS = 2000;
+/** Longest wait between two attempts. A box that is being updated is back well inside a minute. */
+export const RECONNECT_MAX_MS = 60_000;
+export class OcculiteProvider {
+    kind = 'occulite';
+    #options;
+    #client;
+    #document = emptyDocument();
+    #reachable = false;
+    #writable = true;
+    #error;
+    #abort;
+    #loop;
+    /** So that the same failure is not written into the log every two seconds. */
+    #lastNotice = '';
+    /** Ends the wait between two attempts at the event stream; set while the loop is sleeping. */
+    #wake;
+    constructor(options) {
+        this.#options = options;
+        this.#client = options.client;
+    }
+    state() {
+        return {
+            provider: 'occulite',
+            reachable: this.#reachable,
+            writable: this.#writable,
+            revision: this.#document.revision,
+            objects: Object.keys(this.#document.objects).length,
+            url: this.#client.baseUrl,
+            ...(this.#options.implementation === undefined ? {} : { implementation: this.#options.implementation }),
+            ...(this.#error === undefined ? {} : { error: this.#error }),
+        };
+    }
+    document() {
+        return this.#document;
+    }
+    /**
+     * The cached snapshot first, then the box.
+     *
+     * In that order on purpose: the cache is instant and the box may be a second away, and a grid
+     * that shows the names it had a moment ago and then corrects them is better than one that shows
+     * addresses while a request is in flight.
+     */
+    async start() {
+        await this.#loadCache();
+        this.#abort = new AbortController();
+        const signal = this.#abort.signal;
+        await this.#refresh();
+        this.#loop = this.#follow(signal);
+    }
+    async stop() {
+        this.#abort?.abort();
+        this.#abort = undefined;
+        try {
+            await this.#loop;
+        }
+        catch {
+            // the loop ends by being aborted; that is not a failure
+        }
+        this.#loop = undefined;
+    }
+    /**
+     * A fresh snapshot, on demand - the credential changed, or a host asked for one.
+     *
+     * It also ends the wait before the next attempt at the event stream. On the box the first page
+     * load is what hands the addon a session at all, and without this the store would be read at
+     * once but only *followed* after the backoff had run out.
+     */
+    async refresh() {
+        await this.#refresh();
+        this.#wake?.();
+    }
+    async setNames(entries) {
+        if (entries.length === 0) {
+            return;
+        }
+        const sets = {};
+        for (const entry of entries) {
+            sets[entry.ref] = { name: entry.name };
+        }
+        await this.#write(() => this.#client.bulk(sets));
+    }
+    async setMembership(entries) {
+        if (entries.length === 0) {
+            return;
+        }
+        const sets = {};
+        for (const entry of entries) {
+            sets[entry.ref] = { enums: entry.paths };
+        }
+        await this.#write(() => this.#client.bulk(sets));
+    }
+    async createEnum(id, name) {
+        await this.#write(() => this.#client.createEnum(id, name));
+    }
+    async updateEnum(id, name) {
+        await this.#write(() => this.#client.updateEnum(id, name));
+    }
+    async deleteEnum(id, detach) {
+        await this.#write(() => this.#client.deleteEnum(id, detach ? 'detach' : 'refuse'));
+    }
+    async createNode(enumId, parent, id, name, options) {
+        await this.#write(() => this.#client.createNode(enumId, {
+            parent,
+            id,
+            name,
+            ...(options.icon === undefined ? {} : { icon: options.icon }),
+            ...(options.position === undefined ? {} : { position: options.position }),
+        }));
+        return `${parent ?? enumId}/${id}`;
+    }
+    async updateNode(path, patch) {
+        await this.#write(() => this.#client.updateNode(path, patch));
+    }
+    async deleteNode(path, detach) {
+        await this.#write(() => this.#client.deleteNode(path, detach ? 'detach' : 'refuse'));
+    }
+    async import(document, mode) {
+        await this.#write(() => this.#client.import(document, mode));
+    }
+    /**
+     * One write, then a fresh snapshot.
+     *
+     * The snapshot rather than trusting the event stream: a write is a user action, they are rare,
+     * and the alternative is a UI whose own change appears only if the stream happens to be up. A
+     * 403 is turned into `writable: false` so the state says *why*, and is then re-thrown for the
+     * caller to show.
+     */
+    async #write(call) {
+        try {
+            const answer = await call();
+            if (!this.#writable) {
+                this.#writable = true;
+                this.#options.onStateChanged(this.state());
+            }
+            await this.#refresh();
+            return answer;
+        }
+        catch (error) {
+            if (isMetaError(error) && error.code === 'forbidden') {
+                this.#writable = false;
+                this.#error = error.message;
+                this.#options.onStateChanged(this.state());
+            }
+            throw error;
+        }
+    }
+    /** `GET /snapshot`, with every failure turned into a state instead of an exception. */
+    async #refresh() {
+        try {
+            const document = await this.#client.snapshot();
+            this.#document = document;
+            this.#reachable = true;
+            this.#error = undefined;
+            this.#lastNotice = '';
+            // told before it is persisted, and on purpose: the document is already visible to every
+            // reader, so a listener that hears about it one `await` later would be looking at a
+            // change nobody announced
+            this.#options.onStateChanged(this.state());
+            this.#options.onChanged();
+            await this.#saveCache();
+        }
+        catch (error) {
+            this.#fail(error);
+        }
+    }
+    /**
+     * The change stream, for as long as the provider is running.
+     *
+     * Every reconnect resumes at the revision this provider holds. The box replays what it still
+     * has and answers `resync` when it does not, which is the one case where a snapshot is fetched
+     * again - together with `import`, which means the whole store was replaced.
+     */
+    async #follow(signal) {
+        // read through a function: `aborted` changes while this loop is awaiting, and neither the
+        // type checker's narrowing nor the lint rule that follows it can know that
+        const aborted = () => signal.aborted;
+        let wait = this.#options.reconnectMinMs ?? RECONNECT_MIN_MS;
+        while (!aborted()) {
+            try {
+                for await (const event of this.#client.events(this.#document.revision, signal)) {
+                    wait = this.#options.reconnectMinMs ?? RECONNECT_MIN_MS;
+                    if (!this.#reachable) {
+                        this.#reachable = true;
+                        this.#error = undefined;
+                        this.#options.onStateChanged(this.state());
+                    }
+                    const next = applyEvent(this.#document, event);
+                    if (next === 'resync') {
+                        await this.#refresh();
+                        continue;
+                    }
+                    if (next.revision === this.#document.revision) {
+                        // a replayed event we already had
+                        continue;
+                    }
+                    this.#document = next;
+                    this.#options.onStateChanged(this.state());
+                    this.#options.onChanged();
+                    await this.#saveCache();
+                }
+            }
+            catch (error) {
+                if (aborted()) {
+                    return;
+                }
+                this.#fail(error);
+            }
+            if (aborted()) {
+                return;
+            }
+            await this.#sleep(wait, signal);
+            wait = Math.min(wait * 2, this.#options.reconnectMaxMs ?? RECONNECT_MAX_MS);
+            // a reconnect is also the moment to try the credential again: a token that was added on
+            // the box while this was running starts working without a restart here
+            if (!aborted() && !this.#reachable) {
+                await this.#refresh();
+            }
+        }
+    }
+    #fail(error) {
+        const message = isMetaError(error) ? error.message : errorMessage(error);
+        this.#reachable = false;
+        this.#error = message;
+        this.#options.onStateChanged(this.state());
+        if (message !== this.#lastNotice) {
+            this.#lastNotice = message;
+            this.#options.onNotice('warn', `the openccu-lite metadata store is not answering: ${message}`);
+        }
+    }
+    async #loadCache() {
+        if (this.#options.cacheFile === undefined) {
+            return;
+        }
+        const raw = await readJsonFile(this.#options.cacheFile);
+        if (raw === undefined) {
+            return;
+        }
+        try {
+            this.#document = parseDocument(raw);
+            this.#options.onChanged();
+        }
+        catch {
+            // a cache file that cannot be read is a cache file, not a store: it is replaced by the
+            // next snapshot and nobody needs to hear about it
+        }
+    }
+    async #saveCache() {
+        if (this.#options.cacheFile === undefined) {
+            return;
+        }
+        try {
+            await writeJsonFile(this.#options.cacheFile, this.#document);
+        }
+        catch (error) {
+            this.#options.onNotice('warn', `the metadata cache could not be written: ${errorMessage(error)}`);
+        }
+    }
+    #sleep(ms, signal) {
+        if (this.#options.wait) {
+            return this.#options.wait(ms, signal);
+        }
+        return new Promise((resolve) => {
+            const done = () => {
+                clearTimeout(timer);
+                this.#wake = undefined;
+                resolve();
+            };
+            const timer = setTimeout(done, ms);
+            timer.unref();
+            this.#wake = done;
+            signal.addEventListener('abort', done, { once: true });
+        });
+    }
+}
+/** Every object of the current document as the UI shows it. Re-exported for the backend's reads. */
+export { summariseAll };
+//# sourceMappingURL=occuliteProvider.js.map

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

@@ -0,0 +1,68 @@
+/**
+ * The metadata provider: one interface, two implementations, the same public surface.
+ *
+ * D-40. `local` keeps names, rooms and functions in this profile - a user on Homegear, on a bare
+ * rfd or on the desktop gets a taxonomy for the first time. `occulite` reads them from an
+ * openccu-lite box, follows its change stream and **writes back**, because on that box this
+ * application is the editor of the store: there is no ReGaHSS and no WebUI to do it instead.
+ *
+ * `rega` (task 27) is the third: on a CCU with ReGaHSS the rooms and functions are ReGa's own enum
+ * objects, read and written through the script transport the names already use, so that one
+ * editing UI serves a CCU and a box. A box that has ReGa never has a metadata API, so the three
+ * never compete: the box's API wins when it answers, ReGa when it is on and answered, and `local`
+ * is what every other system - Homegear, a bare rfd, the desktop without a CCU - gets.
+ */
+import type { MetaDocument, MetaEnum, MetaImportMode, MetaNodePatch, MetaState } from '@homematic-manager/core';
+/** One name to write: the store's identity is the ref, not the bare address. */
+export interface MetaNameEntry {
+    readonly ref: string;
+    readonly name: string;
+}
+/** The complete membership one object should have afterwards. */
+export interface MetaMembershipEntry {
+    readonly ref: string;
+    readonly paths: readonly string[];
+}
+export interface MetaProviderEvents {
+    /** The document changed - locally, or on the box because somebody else edited it. */
+    readonly onChanged: () => void;
+    /** Reachability, writability or the revision changed. */
+    readonly onStateChanged: (state: MetaState) => void;
+    readonly onNotice: (level: 'info' | 'warn' | 'error', message: string) => void;
+}
+/**
+ * What the backend calls. Every write is asynchronous because one of the two implementations is a
+ * box on the network; every read is synchronous because both keep the document in memory.
+ */
+export interface MetadataProvider {
+    readonly kind: 'local' | 'occulite' | 'rega';
+    state(): MetaState;
+    /** Loads the document (a file, or the box's snapshot) and starts following changes. */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Reads everything again.
+     *
+     * Called when the credential changes - on the box that is the moment a user opens the page and
+     * the addon learns their session - so that names appear at once instead of at the next
+     * reconnect of the event stream.
+     */
+    refresh(): Promise<void>;
+    document(): MetaDocument;
+    setNames(entries: readonly MetaNameEntry[]): Promise<void>;
+    setMembership(entries: readonly MetaMembershipEntry[]): Promise<void>;
+    createEnum(id: string, name: Readonly<Record<string, string>>): Promise<void>;
+    updateEnum(id: string, name: Readonly<Record<string, string>>): Promise<void>;
+    deleteEnum(id: string, detach: boolean): Promise<void>;
+    /** Answers with the path the node got; the id is derived from the name by the caller. */
+    createNode(enumId: string, parent: string | null, id: string, name: string, options: {
+        readonly icon?: string;
+        readonly position?: number;
+    }): Promise<string>;
+    updateNode(path: string, patch: MetaNodePatch): Promise<void>;
+    deleteNode(path: string, detach: boolean): Promise<void>;
+    import(document: unknown, mode: MetaImportMode): Promise<void>;
+}
+/** The enums of a document, for a caller that only wants the trees. */
+export declare function enumsOf(document: MetaDocument): Readonly<Record<string, MetaEnum>>;
+//# sourceMappingURL=provider.d.ts.map

package/node_modules/@homematic-manager/backend/dist/meta/provider.js

@@ -0,0 +1,19 @@
+/**
+ * The metadata provider: one interface, two implementations, the same public surface.
+ *
+ * D-40. `local` keeps names, rooms and functions in this profile - a user on Homegear, on a bare
+ * rfd or on the desktop gets a taxonomy for the first time. `occulite` reads them from an
+ * openccu-lite box, follows its change stream and **writes back**, because on that box this
+ * application is the editor of the store: there is no ReGaHSS and no WebUI to do it instead.
+ *
+ * `rega` (task 27) is the third: on a CCU with ReGaHSS the rooms and functions are ReGa's own enum
+ * objects, read and written through the script transport the names already use, so that one
+ * editing UI serves a CCU and a box. A box that has ReGa never has a metadata API, so the three
+ * never compete: the box's API wins when it answers, ReGa when it is on and answered, and `local`
+ * is what every other system - Homegear, a bare rfd, the desktop without a CCU - gets.
+ */
+/** The enums of a document, for a caller that only wants the trees. */
+export function enumsOf(document) {
+    return document.enums;
+}
+//# sourceMappingURL=provider.js.map

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

@@ -0,0 +1,84 @@
+/**
+ * The `rega` metadata provider (task 27): the CCU's own rooms and functions, through ReGaHSS.
+ *
+ * On a CCU the rooms and functions the user sees in the WebUI live in ReGa's DOM - enum objects
+ * under `ID_ROOMS` and `ID_FUNCTIONS`, each holding channel ids - and a taxonomy kept in this
+ * profile beside them would be a second truth. So on a CCU with ReGa this provider *is* the store:
+ * the same {@link MetadataProvider} surface the box's provider has, over the same script transport
+ * the names already use, so that the editing UI of task 25 does not know which one it talks to.
+ *
+ * What ReGa's model is, and therefore what this provider is:
+ *
+ * - **Flat.** A room is a room; there is no room below another and no floor. `state().flat` says
+ *   so, `createNode` with a parent and a move under a parent are refused.
+ * - **Two taxonomies, fixed.** Rooms and functions exist; nothing else can be created or deleted.
+ * - **Channels are members, devices are not.** The WebUI assigns channels. A device ref in a
+ *   membership write is applied to every channel of the device except the `:0` maintenance
+ *   channel, which is what a user who "puts the device in the kitchen" means.
+ * - **Identity is the ReGa id.** A node's id is `r<id>`, stable across renames, so a path never
+ *   has to be rewritten when a room is renamed.
+ * - **No change stream.** ReGa tells nobody when the WebUI edits a room. This provider reads
+ *   everything on `start()`, after every write of its own, and on `refresh()`, which the UI asks
+ *   for through `meta.refresh`.
+ *
+ * Failure is a state, never an exception (D-2): a script that does not run leaves the last
+ * document in place, sets `reachable: false` and says so once.
+ */
+import { type Language, type MetaDocument, type MetaNodePatch, type MetaState } from '@homematic-manager/core';
+import type { MetadataProvider, MetaMembershipEntry, MetaNameEntry, MetaProviderEvents } from './provider.js';
+/** The part of the ReGa transport this provider uses: run a script, read what it wrote. */
+export type RegaScriptRunner = (script: string) => Promise<{
+    output: string;
+}>;
+export interface RegaMetaProviderOptions extends MetaProviderEvents {
+    readonly exec: RegaScriptRunner;
+    /**
+     * The interface an address belongs to, from the device caches - the fallback for a device
+     * whose interface ReGa does not name (an older firmware, a CUxD device).
+     */
+    readonly interfaceOf: (address: string) => string | undefined;
+    /**
+     * The language the stock rooms and functions are shown in. ReGa stores them as translation keys
+     * (`roomKitchen`) and the WebUI translates them on display; the CCU's own default is German.
+     */
+    readonly language?: Language | undefined;
+}
+/**
+ * The rooms and functions a CCU comes with, as the WebUI translates them (`translate.lang.js` of
+ * the German and the English WebUI, firmware 3.89.8). ReGa's objects carry the *key* as their
+ * `Name()` - `roomKitchen`, not `Küche` - and every WebUI page translates it on display, so a list
+ * that shows the keys is not what the user sees on the CCU. Found in the first lab pass of task 27.
+ * A name that is not one of these keys is shown as it is; a rename writes the literal name.
+ */
+export declare const REGA_STOCK_NAMES: Readonly<Record<string, Readonly<Record<'de' | 'en', string>>>>;
+/** `roomKitchen` -> `Küche`; anything that is not a stock key is answered as it is. */
+export declare function regaStockName(name: string, language: Language | undefined): string;
+/** `r4711` - the node id of a ReGa enum object; stable across renames. */
+export declare function regaNodeId(id: number): string;
+/** The ReGa id behind a node id, or `undefined` for anything that is not one. */
+export declare function parseRegaNodeId(id: string): number | undefined;
+export declare class RegaMetaProvider implements MetadataProvider {
+    #private;
+    readonly kind: "rega";
+    constructor(options: RegaMetaProviderOptions);
+    state(): MetaState;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Reads everything again. Never throws: a ReGa that does not answer is a state. */
+    refresh(): Promise<void>;
+    document(): MetaDocument;
+    setNames(entries: readonly MetaNameEntry[]): Promise<void>;
+    setMembership(entries: readonly MetaMembershipEntry[]): Promise<void>;
+    createEnum(): Promise<void>;
+    updateEnum(): Promise<void>;
+    deleteEnum(): Promise<void>;
+    /**
+     * A new room or function. The id the caller derived from the name is not used: ReGa hands out
+     * the id, and `r<id>` is what keeps the path stable when the room is renamed later.
+     */
+    createNode(enumId: string, parent: string | null, _id: string, name: string): Promise<string>;
+    updateNode(path: string, patch: MetaNodePatch): Promise<void>;
+    deleteNode(path: string, detach: boolean): Promise<void>;
+    import(): Promise<void>;
+}
+//# sourceMappingURL=regaProvider.d.ts.map