@matter/thread-br-client 0.0.1

package/src/otbr-rest/OtbrRestDiagnosticSource.ts

@@ -0,0 +1,172 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, Logger, Observable } from "@matter/general";
+import type { DiagnosticResponse } from "../diagnostic/DiagnosticResponse.js";
+import type { DiagnosticSource, QueryMulticastHandle, QueryMulticastOptions } from "../diagnostic/DiagnosticSource.js";
+import { DEFAULT_RESET_TLV_TYPES } from "../diagnostic/DiagnosticSource.js";
+import type { OtbrRestCapability } from "./OtbrRestCapability.js";
+import type { OtbrRestClient } from "./OtbrRestClient.js";
+import { OtbrRestError } from "./OtbrRestError.js";
+import { translateNodeJson } from "./translation.js";
+
+const logger = Logger.get("OtbrRestDiagnosticSource");
+
+type ClientLike = Pick<OtbrRestClient, "getDiagnostics" | "getNode" | "resetDiagnosticCounters">;
+
+/**
+ * {@link DiagnosticSource} implementation that wraps the OTBR REST `/diagnostics`
+ * endpoint.
+ *
+ * Unlike the MeshCoP path (DTLS + CoAP), this source requires no DTLS handshake;
+ * the BR exposes a pre-collected mesh-wide diagnostic snapshot over plain HTTP.
+ * TLV type filtering and multicast scoping are not supported on the wire — the
+ * full snapshot is always fetched and filtered client-side.
+ *
+ * Bind one instance per discovered OTBR REST endpoint. The `capability` object
+ * from {@link OtbrRestProbe} records which network this source covers.
+ */
+export class OtbrRestDiagnosticSource implements DiagnosticSource {
+    readonly kind = "otbr-rest" as const;
+
+    readonly #client: ClientLike;
+    readonly #capability: OtbrRestCapability;
+
+    /**
+     * @param client - REST client (or compatible duck type) for the target BR.
+     * @param capability - Probed metadata identifying the network this source covers.
+     */
+    constructor(client: ClientLike, capability: OtbrRestCapability) {
+        this.#client = client;
+        this.#capability = capability;
+    }
+
+    /**
+     * Returns `true` when `extPanId` matches the network this source was probed for.
+     *
+     * @param extPanId - 8-byte Extended PAN ID of the network to query.
+     */
+    canQuery(extPanId: Uint8Array): boolean {
+        return Bytes.areEqual(extPanId, this.#capability.extPanId);
+    }
+
+    /**
+     * Query diagnostics for a single mesh node by RLOC16.
+     *
+     * Fetches the full `/diagnostics` snapshot from the BR and returns the entry
+     * matching `target.rloc16`. IP-only targets are not supported via REST — the
+     * OTBR per-RLOC16 endpoint is not universally available.
+     *
+     * @param target - Must include `rloc16`; `ip` without `rloc16` is rejected.
+     * @param _tlvTypes - Ignored; REST returns the BR's full snapshot unconditionally.
+     * @throws {@link OtbrRestError} with code `"rest_protocol"` when `rloc16` is
+     *   missing, when an ip-only target is supplied, or when no entry matches `rloc16`.
+     * @throws {@link OtbrRestError} when the underlying REST fetch fails.
+     */
+    async queryUnicast(target: { rloc16?: number; ip?: string }, _tlvTypes: number[]): Promise<DiagnosticResponse> {
+        if (target.ip !== undefined && target.rloc16 === undefined) {
+            throw new OtbrRestError(
+                "rest_protocol",
+                "OtbrRestDiagnosticSource: ip-routed unicast is not supported in REST mode — supply rloc16",
+            );
+        }
+        if (target.rloc16 === undefined) {
+            throw new OtbrRestError("rest_protocol", "OtbrRestDiagnosticSource: rloc16 required for unicast query");
+        }
+        // Per-RLOC16 endpoint (`/diagnostics/<rloc16>`) is not universally
+        // supported — fetch the full mesh dump and filter client-side.
+        // tlvTypes is ignored: REST returns the BR's full diagnostic snapshot
+        // with no per-TLV filtering on the wire.
+        const list = await this.#client.getDiagnostics();
+        for (const entry of list) {
+            const decoded = translateNodeJson(entry);
+            if (decoded.rloc16 === target.rloc16) return decoded;
+        }
+        throw new OtbrRestError("rest_protocol", `rloc16 0x${target.rloc16.toString(16)} not found in /diagnostics`);
+    }
+
+    /**
+     * Stream all mesh-node diagnostics from the OTBR `/diagnostics` endpoint.
+     *
+     * Because the REST surface returns a pre-collected snapshot in a single HTTP
+     * response, multicast scope and `opts.windowMs` have no effect — all nodes are
+     * emitted in one burst and `done` resolves immediately after. The returned
+     * handle is still conformant to {@link QueryMulticastHandle}; callers may
+     * call `close()` before `done` resolves with no ill effect.
+     *
+     * @param _scope - Ignored; REST has no per-scope filtering.
+     * @param _opts - Ignored; see above.
+     * @returns Handle with `onNode`, `onError`, `done`, and `close`.
+     */
+    queryMulticast(_scope: "ff03::1" | "ff03::2", _opts: QueryMulticastOptions): QueryMulticastHandle {
+        // scope/tlvTypes/windowMs are no-ops for REST: the BR has already
+        // collected diagnostics for the whole mesh and exposes the snapshot
+        // via /diagnostics. REST emits all nodes in a single burst and resolves
+        // `done` immediately after — windowMs is irrelevant.
+        const onNode = new Observable<[DiagnosticResponse]>();
+        const onError = new Observable<[Error]>();
+        let resolveDone!: () => void;
+        let rejectDone!: (err: Error) => void;
+        const done = new Promise<void>((resolve, reject) => {
+            resolveDone = resolve;
+            rejectDone = reject;
+        });
+
+        const start = Date.now();
+        logger.debug(`[ThreadDiag] REST GET /diagnostics ${this.#capability.baseUrl}`);
+        void (async () => {
+            try {
+                const list = await this.#client.getDiagnostics();
+                for (const entry of list) {
+                    onNode.emit(translateNodeJson(entry));
+                }
+                logger.debug(`[ThreadDiag] REST /diagnostics OK nodes=${list.length} duration=${Date.now() - start}ms`);
+                resolveDone();
+            } catch (err) {
+                const e = err instanceof Error ? err : new Error(String(err));
+                onError.emit(e);
+                rejectDone(e);
+            }
+        })();
+
+        return {
+            onNode,
+            onError,
+            done,
+            close: async () => {
+                // The fetch is in-flight — let it complete; ignore the outcome.
+                await done.catch(() => {});
+            },
+        };
+    }
+
+    /**
+     * Zero MAC and MLE counters on a single mesh node via the OTBR REST API.
+     *
+     * Posts a `resetNetworkDiagCounterTask` action to `/api/actions`. Only
+     * available on camelCase OTBR backends (post-2024 builds detected as
+     * `keyFormat === "camel"` during probing). Throws {@link OtbrRestError}
+     * with code `"rest_disabled"` when the backend does not support this
+     * endpoint. Mutating but low-risk — counters only, no network state altered.
+     *
+     * @param _target - Accepted for interface compatibility; REST resets all
+     *   nodes atomically, so target is not forwarded on the wire.
+     * @param _tlvTypes - Accepted for interface compatibility; the REST action
+     *   always resets all diagnostic counters regardless of tlvTypes.
+     */
+    async resetCounters(
+        _target: { rloc16?: number; ip?: string },
+        _tlvTypes: ReadonlyArray<number> = DEFAULT_RESET_TLV_TYPES,
+    ): Promise<void> {
+        if (this.#capability.keyFormat !== "camel") {
+            throw new OtbrRestError(
+                "rest_disabled",
+                "OtbrRestDiagnosticSource: resetCounters requires the camelCase (/api/actions) OTBR backend",
+            );
+        }
+        await this.#client.resetDiagnosticCounters({ action: "resetNetworkDiagCounterTask" });
+    }
+}

package/src/otbr-rest/OtbrRestError.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MatterError } from "@matter/general";
+
+export type OtbrRestErrorCode =
+    "rest_unreachable" | "rest_protocol" | "rest_disabled" | "rest_unsupported" | "rest_conflict" | "rest_not_allowed";
+
+export interface OtbrRestErrorOptions {
+    cause?: Error;
+    httpStatus?: number;
+}
+
+export class OtbrRestError extends MatterError {
+    readonly code: OtbrRestErrorCode;
+    override readonly cause?: Error;
+    readonly httpStatus?: number;
+
+    constructor(code: OtbrRestErrorCode, message: string, opts?: OtbrRestErrorOptions) {
+        super(message);
+        this.name = "OtbrRestError";
+        this.code = code;
+        this.cause = opts?.cause;
+        this.httpStatus = opts?.httpStatus;
+    }
+}

package/src/otbr-rest/OtbrRestProbe.ts

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, Logger, Millis, Seconds, Time, Timer } from "@matter/general";
+import type { OtbrRestCapability } from "./OtbrRestCapability.js";
+import { OtbrRestClient } from "./OtbrRestClient.js";
+import { OtbrRestError } from "./OtbrRestError.js";
+
+const logger = Logger.get("OtbrRestProbe");
+
+const DEFAULT_PROBE_PORT = 8081;
+const DEFAULT_PROBE_TIMEOUT = Seconds(1);
+
+const HTTP_OK = 200;
+const HTTP_NOT_FOUND = 404;
+
+export class OtbrRestProbe {
+    /**
+     * Probe a host:port for OTBR REST. Returns the detected capability or
+     * `null` if the endpoint is not OTBR or not reachable within
+     * `timeoutMs`. Detection mirrors python-otbr-api: a 200 on
+     * `/api/actions` indicates the modern camelCase backend, a 404 the
+     * legacy pascalCase backend; everything else is "not OTBR".
+     */
+    static async probe(
+        host: string,
+        port: number = DEFAULT_PROBE_PORT,
+        timeoutMs: number = DEFAULT_PROBE_TIMEOUT,
+    ): Promise<OtbrRestCapability | null> {
+        const client = new OtbrRestClient({ host, port, timeoutMs });
+        const baseUrl = client.baseUrl;
+        logger.debug(`[ThreadDiag] probe START ${baseUrl} timeout=${timeoutMs}ms`);
+
+        const keyFormat = await detectCase(baseUrl, timeoutMs);
+        if (keyFormat === null) {
+            logger.debug(`[ThreadDiag] probe MISS ${baseUrl} (case detect failed)`);
+            return null;
+        }
+
+        try {
+            const node = await client.getNode();
+            logger.debug(
+                `[ThreadDiag] probe OK ${baseUrl} keyFormat=${keyFormat} xp=${Bytes.toHex(node.extPanId).toUpperCase()} network="${node.networkName}"`,
+            );
+            return {
+                baseUrl,
+                keyFormat,
+                probedAt: Date.now(),
+                networkName: node.networkName,
+                extPanId: node.extPanId,
+            };
+        } catch (err) {
+            if (err instanceof OtbrRestError) {
+                logger.debug(`[ThreadDiag] probe MISS ${baseUrl} /node ${err.code} (${err.message})`);
+                return null;
+            }
+            throw err;
+        }
+    }
+}
+
+async function detectCase(baseUrl: string, timeoutMs: number): Promise<"camel" | "pascal" | null> {
+    const controller = new AbortController();
+    const timer: Timer = Time.getTimer("otbr-probe-timeout", Millis(timeoutMs), () => controller.abort()).start();
+    try {
+        const response = await fetch(`${baseUrl}/api/actions`, {
+            method: "GET",
+            headers: { Accept: "application/json" },
+            signal: controller.signal,
+        });
+        if (response.status === HTTP_OK) return "camel";
+        if (response.status === HTTP_NOT_FOUND) return "pascal";
+        logger.debug(`probe of ${baseUrl} rejected: /api/actions returned ${response.status}`);
+        return null;
+    } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.debug(`probe of ${baseUrl} rejected: /api/actions ${message}`);
+        return null;
+    } finally {
+        timer.stop();
+    }
+}

package/src/otbr-rest/caseNormalizer.ts

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Acronym-bearing keys whose camelCase form is not just "lowercase the first
+ * letter". Mirrors python-otbr-api's `_PASCAL_TO_CAMEL` table — entries that
+ * naive lowercasing would turn into things like `mACCounters` or `iP6...`.
+ */
+const IRREGULAR: Readonly<Record<string, string>> = {
+    BaId: "baId",
+    IP6AddressList: "ip6AddressList",
+    MACCounters: "macCounters",
+    PSKc: "pskc",
+};
+
+function normalizeKey(key: string): string {
+    const mapped = IRREGULAR[key];
+    if (mapped !== undefined) return mapped;
+    if (key.length === 0) return key;
+    return key.charAt(0).toLowerCase() + key.slice(1);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    if (value === null || typeof value !== "object") return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Recursively rewrites object keys from PascalCase (or already-camelCase) to
+ * camelCase. Idempotent — running it twice yields identical output. Arrays,
+ * primitives and `null` pass through unchanged.
+ */
+export function normalizeKeys(value: unknown): unknown {
+    if (Array.isArray(value)) {
+        return value.map(item => normalizeKeys(item));
+    }
+    if (isPlainObject(value)) {
+        const out: Record<string, unknown> = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[normalizeKey(k)] = normalizeKeys(v);
+        }
+        return out;
+    }
+    return value;
+}

package/src/otbr-rest/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export { normalizeKeys } from "./caseNormalizer.js";
+export type { OtbrRestCapability } from "./OtbrRestCapability.js";
+export { OtbrRestClient } from "./OtbrRestClient.js";
+export type {
+    OtbrDatasetHex,
+    OtbrJoiner,
+    OtbrLeaderData,
+    OtbrNodeInfo,
+    OtbrRestClientOptions,
+} from "./OtbrRestClient.js";
+export { OtbrRestDiagnosticSource } from "./OtbrRestDiagnosticSource.js";
+export { OtbrRestError } from "./OtbrRestError.js";
+export type { OtbrRestErrorCode, OtbrRestErrorOptions } from "./OtbrRestError.js";
+export { OtbrRestProbe } from "./OtbrRestProbe.js";
+export { translateNodeJson } from "./translation.js";