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

package/node_modules/@homematic-manager/backend/dist/rega/scripts.js

@@ -117,6 +117,177 @@ export function acknowledgeAlarmScript(interfaceName, address, datapoint) {
 export function isPlainRegaName(value) {
     return /^[A-Za-z0-9_.:-]+$/.test(value);
 }
+/*
+ * Task 27: rooms and functions through ReGa's own objects.
+ *
+ * ReGa keeps rooms and functions as enum objects under `ID_ROOMS` and `ID_FUNCTIONS`, each holding
+ * the ids of the channels in it (`EnumUsedIDs()`), and a channel is put in or taken out with
+ * `Add(id)` / `Remove(id)` on the enum - which is what the WebUI does when a room is edited. The
+ * read script is `homematic-rega`'s `channels.rega`, `rooms.rega` and `functions.rega` in one
+ * round trip, plus the interface name of every device, because the metadata store keys objects by
+ * `<interface>.<address>` and the address alone is not a ref.
+ */
+/** Everything the ReGa metadata provider reads, in one script and one JSON document. */
+export const META_READ_SCRIPT = `string sDevId;
+string sChnId;
+string sEnumId;
+string sMember;
+string sIface;
+object oIface;
+boolean bFirst = true;
+boolean bFirstMember = true;
+Write('{"objects":[');
+foreach (sDevId, root.Devices().EnumUsedIDs()) {
+    object oDevice = dom.GetObject(sDevId);
+    if (oDevice.ReadyConfig()) {
+        sIface = "";
+        oIface = dom.GetObject(oDevice.Interface());
+        if (oIface) { sIface = oIface.Name(); }
+        if (bFirst) { bFirst = false; } else { Write(','); }
+        Write('{"id":' # sDevId # ',"address":"' # oDevice.Address() # '","interface":"' # sIface # '","name":"');
+        WriteURL(oDevice.Name());
+        Write('"}');
+        foreach (sChnId, oDevice.Channels()) {
+            object oChannel = dom.GetObject(sChnId);
+            Write(',{"id":' # sChnId # ',"address":"' # oChannel.Address() # '","interface":"' # sIface # '","name":"');
+            WriteURL(oChannel.Name());
+            Write('"}');
+        }
+    }
+}
+Write('],"rooms":[');
+bFirst = true;
+foreach (sEnumId, dom.GetObject(ID_ROOMS).EnumUsedIDs()) {
+    object oRoom = dom.GetObject(sEnumId);
+    if (bFirst) { bFirst = false; } else { Write(','); }
+    Write('{"id":' # sEnumId # ',"name":"');
+    WriteURL(oRoom.Name());
+    Write('","channels":[');
+    bFirstMember = true;
+    foreach (sMember, oRoom.EnumUsedIDs()) {
+        if (bFirstMember) { bFirstMember = false; } else { Write(','); }
+        Write(sMember);
+    }
+    Write(']}');
+}
+Write('],"functions":[');
+bFirst = true;
+foreach (sEnumId, dom.GetObject(ID_FUNCTIONS).EnumUsedIDs()) {
+    object oFunction = dom.GetObject(sEnumId);
+    if (bFirst) { bFirst = false; } else { Write(','); }
+    Write('{"id":' # sEnumId # ',"name":"');
+    WriteURL(oFunction.Name());
+    Write('","channels":[');
+    bFirstMember = true;
+    foreach (sMember, oFunction.EnumUsedIDs()) {
+        if (bFirstMember) { bFirstMember = false; } else { Write(','); }
+        Write(sMember);
+    }
+    Write(']}');
+}
+Write(']}');
+`;
+/**
+ * Decodes what ReGa's `WriteURL()` produces: `%XX` and `%uXXXX` escapes whose bytes are ISO-8859-1
+ * characters, not UTF-8 sequences - which is why `decodeURIComponent` would throw on `K%FCche`.
+ * The same rule `homematic-rega` applies to its own scripts' output.
+ */
+export function unescapeRegaUrl(value) {
+    return value.replace(/%u([0-9a-f]{4})|%([0-9a-f]{2})/gi, (_match, long, short) => String.fromCharCode(Number.parseInt(long ?? short ?? '0', 16)));
+}
+/** Reads what {@link META_READ_SCRIPT} wrote. Throws on anything that is not the expected shape. */
+export function parseMetaSnapshot(output) {
+    const parsed = JSON.parse(output);
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error('the ReGa metadata script answered with no document');
+    }
+    const raw = parsed;
+    return {
+        objects: parseObjects(raw.objects),
+        rooms: parseEnums(raw.rooms, 'rooms'),
+        functions: parseEnums(raw.functions, 'functions'),
+    };
+}
+function parseObjects(value) {
+    if (!Array.isArray(value)) {
+        throw new Error('the ReGa metadata script answered without an object list');
+    }
+    const objects = [];
+    for (const item of value) {
+        if (typeof item !== 'object' || item === null) {
+            continue;
+        }
+        const entry = item;
+        if (typeof entry.id !== 'number' || typeof entry.address !== 'string' || entry.address === '') {
+            continue;
+        }
+        objects.push({
+            id: entry.id,
+            address: entry.address,
+            interfaceName: typeof entry.interface === 'string' ? entry.interface : '',
+            name: typeof entry.name === 'string' ? unescapeRegaUrl(entry.name) : '',
+        });
+    }
+    return objects;
+}
+function parseEnums(value, what) {
+    if (!Array.isArray(value)) {
+        throw new Error(`the ReGa metadata script answered without the ${what}`);
+    }
+    const enums = [];
+    for (const item of value) {
+        if (typeof item !== 'object' || item === null) {
+            continue;
+        }
+        const entry = item;
+        if (typeof entry.id !== 'number') {
+            continue;
+        }
+        const channels = Array.isArray(entry.channels)
+            ? entry.channels.filter((id) => typeof id === 'number')
+            : [];
+        enums.push({ id: entry.id, name: typeof entry.name === 'string' ? unescapeRegaUrl(entry.name) : '', channels });
+    }
+    return enums;
+}
+const ENUM_ROOT = { room: 'ID_ROOMS', function: 'ID_FUNCTIONS' };
+/**
+ * A new room or function: an enum object, named, and put into ReGa's list of them. The script
+ * writes the new id, which is the only thing the caller needs to address it from then on.
+ */
+export function createEnumNodeScript(kind, name) {
+    return [
+        'object oNew = dom.CreateObject(OT_ENUM);',
+        `oNew.Name("${escapeRegaString(name)}");`,
+        `dom.GetObject(${ENUM_ROOT[kind]}).Add(oNew.ID());`,
+        'Write(oNew.ID());',
+        '',
+    ].join('\n');
+}
+/** Reads the id {@link createEnumNodeScript} wrote, or `undefined` when ReGa wrote something else. */
+export function parseCreatedId(output) {
+    const trimmed = output.trim();
+    return /^\d+$/.test(trimmed) ? Number(trimmed) : undefined;
+}
+/**
+ * Removes a room or function: out of ReGa's list first, then the object itself. The memberships go
+ * with it, which is what the caller has already confirmed with the user (`has-members`).
+ */
+export function deleteEnumNodeScript(kind, id) {
+    return [
+        `object oGone = dom.GetObject(${String(id)});`,
+        `if (oGone) { dom.GetObject(${ENUM_ROOT[kind]}).Remove(${String(id)}); dom.DeleteObject(${String(id)}); }`,
+        '',
+    ].join('\n');
+}
+/** `Add` / `Remove` on the enum, one statement per change; `undefined` when there is none. */
+export function membershipScript(changes) {
+    if (changes.length === 0) {
+        return undefined;
+    }
+    const lines = changes.map((change) => `dom.GetObject(${String(change.enumId)}).${change.on ? 'Add' : 'Remove'}(${String(change.channelId)});`);
+    return `${lines.join('\n')}\n`;
+}
 /**
  * D-32: does this user exist, and what is their level?
  *

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

@@ -25,7 +25,7 @@
  * `unitLabel()` in the core still repairs. See the README for what remains broken in the libraries
  * (BIN-RPC decodes strings as UTF-8, and both request paths write UTF-8).
  */
-import type { ExplicitDouble, RpcProtocol, RpcValue } from '@homematic-manager/core';
+import type { ExplicitDouble, RpcOrigin, RpcProtocol, RpcValue } from '@homematic-manager/core';
 /**
  * What may be sent to an interface: everything an answer can carry, plus the explicit-double
  * wrapper both encoders understand. A paramset payload is full of them, and an interface that gets
@@ -34,7 +34,7 @@ import type { ExplicitDouble, RpcProtocol, RpcValue } from '@homematic-manager/c
 export type RpcOutValue = boolean | number | string | ExplicitDouble | RpcOutValue[] | {
     [key: string]: RpcOutValue;
 };
-/** What the write log and the RPC console record for one call. */
+/** What the RPC log records for one call - every call, task 48. */
 export interface RpcCallRecord {
     readonly interfaceName: string;
     readonly method: string;
@@ -45,6 +45,13 @@ export interface RpcCallRecord {
     readonly durationMs: number;
     /** Milliseconds since epoch. */
     readonly timestamp: number;
+    /** Who asked: the console, a UI action, or the backend on its own. */
+    readonly origin: RpcOrigin;
+}
+/** Per-call options of {@link RpcClient.call}. */
+export interface RpcCallOptions {
+    /** The origin of this call, when the caller knows it better than the client's resolver does. */
+    readonly origin?: RpcOrigin;
 }
 /** Anything that answers `methodCall`; the tests pass a fake instead of a socket. */
 export interface RpcTransport {
@@ -70,8 +77,13 @@ export interface RpcClientOptions {
     readonly encoding?: string;
     /** A CCU's TLS certificate is self-signed, so this is false by default. */
     readonly rejectUnauthorized?: boolean;
-    /** Called for every finished call - the write log and the console history hang off it. */
+    /** Called for every finished call - the RPC log hangs off it. */
     readonly onCall?: (record: RpcCallRecord) => void;
+    /**
+     * The origin of a call that names none: the backend answers from its request context (task
+     * 48). Without a resolver every call is `background`, which is right for a client on its own.
+     */
+    readonly originOf?: () => RpcOrigin;
     /** Injected by the tests in place of the real libraries. */
     readonly createTransport?: (options: RpcClientOptions) => RpcTransport;
 }
@@ -90,9 +102,10 @@ export declare class RpcClient {
     get description(): string;
     /**
      * Calls a method. Rejects with a `BackendError`: `kind: 'rpc'` for a fault the interface
-     * answered, `kind: 'connection'` for a timeout or a socket problem.
+     * answered, `kind: 'connection'` for a timeout or a socket problem. Every call, however it
+     * ends, is reported through `onCall` with its origin - the one given here, or the resolver's.
      */
-    call(method: string, params?: readonly RpcOutValue[]): Promise<RpcValue>;
+    call(method: string, params?: readonly RpcOutValue[], options?: RpcCallOptions): Promise<RpcValue>;
     /** Closes the underlying socket, if the library has one. */
     close(): void;
     get closed(): boolean;

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

@@ -113,6 +113,7 @@ export class RpcClient {
     #transport;
     #timeoutMs;
     #onCall;
+    #originOf;
     #closed = false;
     constructor(options) {
         this.name = options.name;
@@ -121,6 +122,7 @@ export class RpcClient {
         this.protocol = options.protocol;
         this.#timeoutMs = options.timeoutMs ?? DEFAULT_RPC_TIMEOUT_MS;
         this.#onCall = options.onCall ?? (() => undefined);
+        this.#originOf = options.originOf ?? (() => 'background');
         this.#transport = (options.createTransport ?? createTransport)(options);
     }
     /** A short description for error messages: `HmIP-RF (ccu.lan:2010, xmlrpc)`. */
@@ -129,21 +131,24 @@ export class RpcClient {
     }
     /**
      * Calls a method. Rejects with a `BackendError`: `kind: 'rpc'` for a fault the interface
-     * answered, `kind: 'connection'` for a timeout or a socket problem.
+     * answered, `kind: 'connection'` for a timeout or a socket problem. Every call, however it
+     * ends, is reported through `onCall` with its origin - the one given here, or the resolver's.
      */
-    async call(method, params = []) {
+    async call(method, params = [], options = {}) {
         if (this.#closed) {
             throw connectionError(`${this.description}: the client is closed`);
         }
+        // resolved before the first await: the context that asked is the one that counts
+        const origin = options.origin ?? this.#originOf();
         const started = Date.now();
         try {
             const result = await withTimeout(this.#invoke(method, [...params]), this.#timeoutMs, () => connectionError(`${this.description}: ${method} timed out after ${String(this.#timeoutMs)} ms`));
-            this.#record(method, params, started, { ok: true, result });
+            this.#record(method, params, started, origin, { ok: true, result });
             return result;
         }
         catch (error) {
             const failure = this.#asBackendError(method, error);
-            this.#record(method, params, started, { ok: false, error: failure.message });
+            this.#record(method, params, started, origin, { ok: false, error: failure.message });
             throw failure;
         }
     }
@@ -186,7 +191,7 @@ export class RpcClient {
         const message = error instanceof Error ? error.message : String(error);
         return connectionError(`${this.description}: ${method} failed: ${message}`, error);
     }
-    #record(method, params, started, outcome) {
+    #record(method, params, started, origin, outcome) {
         this.#onCall({
             interfaceName: this.name,
             method,
@@ -196,6 +201,7 @@ export class RpcClient {
             ...(outcome.error === undefined ? {} : { error: outcome.error }),
             durationMs: Date.now() - started,
             timestamp: started,
+            origin,
         });
     }
 }

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

@@ -0,0 +1,86 @@
+/**
+ * The session RPC log: every outgoing call of the session, and the write list that decides what
+ * is paced.
+ *
+ * 2.x had no log at all except the debug option `rpcLogFolder` (`main.js:830-838`), which dumped
+ * every `putParamset` as a JSON file. That option is the right forensic tool for a device that
+ * ended up in `CONFIG_PENDING` and it is kept, verbatim in file name and content. On top of it
+ * every write was recorded in a ring the UI shows and exports (task 6, item 5) - and since task 48
+ * every call is: the maintainer wants to see *every* outgoing RPC call in the one global log, the
+ * reads, the keep-alive and the `init`s included, each with where it came from (`origin`) so the
+ * background traffic can be hidden rather than left out.
+ *
+ * What bounds it, because the keep-alive runs every few seconds on several interfaces and a
+ * `listDevices` answer is hundreds of kilobytes: a ring of {@link DEFAULT_CAPACITY} entries, a
+ * byte budget over the whole ring ({@link DEFAULT_BUDGET_BYTES}) that evicts the oldest entries
+ * first, and a cap per answer ({@link DEFAULT_RESULT_CAP_BYTES}) above which only a preview and
+ * the size are kept. Parameters are never cut - a write's parameters are what went on the wire -
+ * but the secrets among them are: a passphrase or a device key has no business in a log.
+ *
+ * Only the writes are persisted (`write-log.json`, as before task 48): they are the history that
+ * matters after a restart; the reads of the previous session are noise, and a CCU's flash does not
+ * want a `ping` written to it every few seconds.
+ *
+ * Which calls count as writes is a fixed list: it decides what is paced (`WriteQueue`), what is
+ * persisted, and what a `rpc.call` from the console is allowed to do without a warning.
+ */
+import type { RpcLogEntry, RpcValue } from '@homematic-manager/core';
+import type { RpcCallRecord } from './client.js';
+/**
+ * The RPC methods that change something on the CCU or on a device.
+ *
+ * Everything not in here is a read: it bypasses the write queue and is not persisted. The list is
+ * the eQ-3 method catalogue of the core (`RPC_METHODS`) filtered by hand - `getLinks` and
+ * `rssiInfo` read, `addLink` and `setBidcosInterface` do not.
+ */
+export declare const WRITE_METHODS: ReadonlySet<string>;
+/** Does this method change something? */
+export declare function isWriteMethod(method: string): boolean;
+/** How many entries the ring keeps. */
+export declare const DEFAULT_CAPACITY = 1000;
+/** The byte budget of the whole ring, measured as the JSON length of its entries. */
+export declare const DEFAULT_BUDGET_BYTES: number;
+/** An answer bigger than this is kept as a preview with its size. */
+export declare const DEFAULT_RESULT_CAP_BYTES: number;
+/** What a secret is logged as. */
+export declare const REDACTED = "***";
+/**
+ * The parameters as the log keeps them. A struct with a `KEY` in it is a whitelist entry of
+ * `setInstallModeWithWhitelist` (the HmIP device key from the sticker); the key goes, the rest -
+ * `ADDRESS`, `KEY_MODE` - stays, so the log still says which device was admitted.
+ */
+export declare function redactParams(method: string, params: readonly RpcValue[]): RpcValue[];
+export interface RpcLogOptions {
+    /** How many entries the ring keeps. */
+    readonly capacity?: number;
+    /** The byte budget of the ring; the oldest entries go when it is exceeded. */
+    readonly budgetBytes?: number;
+    /** An answer over this many bytes of JSON is kept as a preview with its size. */
+    readonly resultCapBytes?: number;
+    /** `<cache>/write-log.json`; omit to keep the log in memory only. Only the writes go there. */
+    readonly file?: string;
+    /** The 2.x `rpcLogFolder`: every `putParamset` is dumped there as JSON. Empty = off. */
+    readonly rpcLogFolder?: string;
+    readonly onAppended?: (entry: RpcLogEntry) => void;
+    readonly onError?: (error: unknown) => void;
+    readonly writeDelayMs?: number;
+}
+/** Every outgoing RPC call of this session, newest last. */
+export declare class RpcLog {
+    #private;
+    constructor(options?: RpcLogOptions);
+    /** The folder the `putParamset` dumps go to; empty switches them off. */
+    setRpcLogFolder(folder: string): void;
+    /** Records one finished call and returns its entry. */
+    append(record: RpcCallRecord): RpcLogEntry;
+    /** The newest `limit` entries, oldest first. */
+    list(limit?: number): RpcLogEntry[];
+    clear(): void;
+    get size(): number;
+    /** The JSON length of everything in the ring - what the budget is measured against. */
+    get bytes(): number;
+    /** Reads the writes of the previous session, if there is a file. */
+    load(): Promise<void>;
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=log.d.ts.map

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

@@ -0,0 +1,241 @@
+/**
+ * The session RPC log: every outgoing call of the session, and the write list that decides what
+ * is paced.
+ *
+ * 2.x had no log at all except the debug option `rpcLogFolder` (`main.js:830-838`), which dumped
+ * every `putParamset` as a JSON file. That option is the right forensic tool for a device that
+ * ended up in `CONFIG_PENDING` and it is kept, verbatim in file name and content. On top of it
+ * every write was recorded in a ring the UI shows and exports (task 6, item 5) - and since task 48
+ * every call is: the maintainer wants to see *every* outgoing RPC call in the one global log, the
+ * reads, the keep-alive and the `init`s included, each with where it came from (`origin`) so the
+ * background traffic can be hidden rather than left out.
+ *
+ * What bounds it, because the keep-alive runs every few seconds on several interfaces and a
+ * `listDevices` answer is hundreds of kilobytes: a ring of {@link DEFAULT_CAPACITY} entries, a
+ * byte budget over the whole ring ({@link DEFAULT_BUDGET_BYTES}) that evicts the oldest entries
+ * first, and a cap per answer ({@link DEFAULT_RESULT_CAP_BYTES}) above which only a preview and
+ * the size are kept. Parameters are never cut - a write's parameters are what went on the wire -
+ * but the secrets among them are: a passphrase or a device key has no business in a log.
+ *
+ * Only the writes are persisted (`write-log.json`, as before task 48): they are the history that
+ * matters after a restart; the reads of the previous session are noise, and a CCU's flash does not
+ * want a `ping` written to it every few seconds.
+ *
+ * Which calls count as writes is a fixed list: it decides what is paced (`WriteQueue`), what is
+ * persisted, and what a `rpc.call` from the console is allowed to do without a warning.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { DebouncedJsonFile } from '../util/jsonFile.js';
+/**
+ * The RPC methods that change something on the CCU or on a device.
+ *
+ * Everything not in here is a read: it bypasses the write queue and is not persisted. The list is
+ * the eQ-3 method catalogue of the core (`RPC_METHODS`) filtered by hand - `getLinks` and
+ * `rssiInfo` read, `addLink` and `setBidcosInterface` do not.
+ */
+export const WRITE_METHODS = new Set([
+    'abortDeleteDevice',
+    'activateLinkParamset',
+    'addDevice',
+    'addLink',
+    'addVirtualDeviceInstance',
+    'changeKey',
+    'clearConfigCache',
+    'deleteDevice',
+    'determineParameter',
+    'installFirmware',
+    'putParamset',
+    'removeLink',
+    'replaceDevice',
+    'reportValueUsage',
+    'restoreConfigToDevice',
+    'searchDevices',
+    'setBidcosInterface',
+    'setInstallMode',
+    'setInstallModeWithWhitelist',
+    'setInterfaceClock',
+    'setLinkInfo',
+    'setMetadata',
+    'setRFLGWInfoLED',
+    'setTeam',
+    'setTempKey',
+    'setValue',
+    'updateFirmware',
+]);
+/** Does this method change something? */
+export function isWriteMethod(method) {
+    return WRITE_METHODS.has(method);
+}
+/** How many entries the ring keeps. */
+export const DEFAULT_CAPACITY = 1000;
+/** The byte budget of the whole ring, measured as the JSON length of its entries. */
+export const DEFAULT_BUDGET_BYTES = 4 * 1024 * 1024;
+/** An answer bigger than this is kept as a preview with its size. */
+export const DEFAULT_RESULT_CAP_BYTES = 8 * 1024;
+/** How much of a capped answer the preview shows. */
+const PREVIEW_CHARS = 512;
+/** What a secret is logged as. */
+export const REDACTED = '***';
+/**
+ * Methods whose every parameter is a secret: `changeKey(passphrase)` sets the BidCos security key,
+ * `setTempKey(passphrase)` the temporary one for pairing.
+ */
+const SECRET_METHODS = new Set(['changeKey', 'setTempKey']);
+/**
+ * The parameters as the log keeps them. A struct with a `KEY` in it is a whitelist entry of
+ * `setInstallModeWithWhitelist` (the HmIP device key from the sticker); the key goes, the rest -
+ * `ADDRESS`, `KEY_MODE` - stays, so the log still says which device was admitted.
+ */
+export function redactParams(method, params) {
+    if (SECRET_METHODS.has(method)) {
+        return params.map(() => REDACTED);
+    }
+    if (method === 'setInstallModeWithWhitelist') {
+        return params.map((param) => redactKeys(param));
+    }
+    return [...params];
+}
+function redactKeys(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => redactKeys(entry));
+    }
+    if (typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, key === 'KEY' ? REDACTED : entry]));
+    }
+    return value;
+}
+/** Every outgoing RPC call of this session, newest last. */
+export class RpcLog {
+    #capacity;
+    #budgetBytes;
+    #resultCapBytes;
+    /** Oldest first; a plain array rather than the core's ring, because the byte budget evicts from the front too. */
+    #entries = [];
+    #bytes = 0;
+    #file;
+    #onAppended;
+    #onError;
+    #rpcLogFolder;
+    #nextId = 1;
+    constructor(options = {}) {
+        this.#capacity = options.capacity ?? DEFAULT_CAPACITY;
+        this.#budgetBytes = options.budgetBytes ?? DEFAULT_BUDGET_BYTES;
+        this.#resultCapBytes = options.resultCapBytes ?? DEFAULT_RESULT_CAP_BYTES;
+        this.#onAppended = options.onAppended ?? (() => undefined);
+        this.#onError = options.onError ?? (() => undefined);
+        this.#rpcLogFolder = options.rpcLogFolder ?? '';
+        this.#file =
+            options.file === undefined
+                ? undefined
+                : new DebouncedJsonFile(options.file, {
+                    delayMs: options.writeDelayMs ?? 500,
+                    ...(options.onError ? { onError: options.onError } : {}),
+                });
+    }
+    /** The folder the `putParamset` dumps go to; empty switches them off. */
+    setRpcLogFolder(folder) {
+        this.#rpcLogFolder = folder;
+    }
+    /** Records one finished call and returns its entry. */
+    append(record) {
+        const entry = {
+            id: this.#nextId,
+            timestamp: record.timestamp,
+            interfaceName: record.interfaceName,
+            method: record.method,
+            // an explicit-double wrapper is JSON like everything else; the log keeps it verbatim
+            // so that a CONFIG_PENDING can be traced back to exactly what went on the wire
+            params: redactParams(record.method, record.params),
+            ok: record.ok,
+            ...this.#resultOf(record.result),
+            ...(record.error === undefined ? {} : { error: record.error }),
+            durationMs: record.durationMs,
+            origin: record.origin,
+        };
+        this.#nextId += 1;
+        this.#push(entry);
+        if (isWriteMethod(entry.method)) {
+            this.#persist();
+        }
+        this.#onAppended(entry);
+        void this.#dump(record);
+        return entry;
+    }
+    /** The newest `limit` entries, oldest first. */
+    list(limit) {
+        const entries = this.#entries.map((item) => item.entry);
+        return limit === undefined || limit >= entries.length ? entries : entries.slice(entries.length - limit);
+    }
+    clear() {
+        this.#entries = [];
+        this.#bytes = 0;
+        this.#persist();
+    }
+    get size() {
+        return this.#entries.length;
+    }
+    /** The JSON length of everything in the ring - what the budget is measured against. */
+    get bytes() {
+        return this.#bytes;
+    }
+    /** Reads the writes of the previous session, if there is a file. */
+    async load() {
+        const stored = await this.#file?.read();
+        if (!Array.isArray(stored)) {
+            return;
+        }
+        for (const entry of stored) {
+            if (typeof entry === 'object' && entry !== null && typeof entry.id === 'number') {
+                // a file from before task 48 has no origin; a persisted entry is a write, and a
+                // write the user did not ask for does not exist
+                const stored = entry;
+                const loaded = { ...stored, origin: stored.origin ?? 'ui' };
+                this.#push(loaded);
+                this.#nextId = Math.max(this.#nextId, loaded.id + 1);
+            }
+        }
+    }
+    async flush() {
+        await this.#file?.flush();
+    }
+    #push(entry) {
+        const bytes = JSON.stringify(entry).length;
+        this.#entries.push({ entry, bytes });
+        this.#bytes += bytes;
+        while (this.#entries.length > this.#capacity || (this.#bytes > this.#budgetBytes && this.#entries.length > 1)) {
+            const evicted = this.#entries.shift();
+            if (evicted) {
+                this.#bytes -= evicted.bytes;
+            }
+        }
+    }
+    /** The answer as the entry keeps it: whole under the cap, a preview and its size above. */
+    #resultOf(result) {
+        if (result === undefined) {
+            return {};
+        }
+        const json = JSON.stringify(result);
+        if (json.length <= this.#resultCapBytes) {
+            return { result };
+        }
+        return { result: `${json.slice(0, PREVIEW_CHARS)}…`, resultBytes: json.length };
+    }
+    #persist() {
+        this.#file?.save(this.#entries.map((item) => item.entry).filter((entry) => isWriteMethod(entry.method)));
+    }
+    /** The 2.x dump: `<folder>/<epoch ms>_<interface>_<method>.json` with the parameters. */
+    async #dump(record) {
+        if (this.#rpcLogFolder === '' || record.method !== 'putParamset') {
+            return;
+        }
+        const file = path.join(this.#rpcLogFolder, `${String(record.timestamp)}_${record.interfaceName}_${record.method}.json`);
+        try {
+            await fs.writeFile(file, JSON.stringify(record.params, null, '  '), 'utf8');
+        }
+        catch (error) {
+            this.#onError(error);
+        }
+    }
+}
+//# sourceMappingURL=log.js.map

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

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