@matter/thread-br-client 0.0.1

package/src/coap/CoapClient.ts

@@ -0,0 +1,355 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    Bytes,
+    Crypto,
+    type Duration,
+    type Entropy,
+    type Environment,
+    ImplementationError,
+    Logger,
+    Millis,
+    Seconds,
+    Time,
+    TimeoutError,
+    Timer,
+} from "@matter/general";
+import type { DtlsChannel } from "../dtls/channel/DtlsChannel.js";
+import { CoapMessage } from "./CoapMessage.js";
+
+const logger = Logger.get("CoapClient");
+
+/** Thrown when a CON request exhausts MAX_RETRANSMIT without receiving an ACK,
+ *  or when an empty ACK is received but no separate response arrives within
+ *  {@link SEPARATE_RESPONSE_TIMEOUT}. */
+export class CoapTimeoutError extends TimeoutError {
+    constructor(messageId: number) {
+        super(`CoAP CON messageId=${messageId} timed out after MAX_RETRANSMIT`);
+        this.name = "CoapTimeoutError";
+    }
+}
+
+/** RFC 7252 §4.2 retransmission constants. */
+const RFC_ACK_TIMEOUT = Seconds(2);
+const RFC_ACK_RANDOM_FACTOR = 1.5;
+const MAX_RETRANSMIT = 4;
+/** Wait this long after an empty ACK (RFC 7252 §5.2.2 separate response) for the
+ *  matching response message to arrive. Spec EXCHANGE_LIFETIME is 247s; we use a
+ *  much tighter ceiling because Thread MeshCoP transactions are local-network
+ *  fast paths — a no-show after 30s indicates a dropped response, not network
+ *  delay. */
+const SEPARATE_RESPONSE_TIMEOUT = Seconds(30);
+
+export interface CoapClientOpts {
+    /** Override ACK_TIMEOUT for testing. Default: 2000ms per RFC 7252 §4.2. */
+    ackTimeoutMs?: number;
+    /** Override the separate-response wait window. Default: 30000ms. */
+    separateResponseTimeoutMs?: number;
+}
+
+type PendingState = {
+    resolve: (msg: CoapMessage) => void;
+    reject: (err: Error) => void;
+    tokenHex: string;
+    onEmptyAck: () => void;
+};
+
+type Listener = {
+    uriPath: string[];
+    handler: (msg: CoapMessage) => void;
+};
+
+function pathsEqual(a: string[], b: string[]): boolean {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) return false;
+    }
+    return true;
+}
+
+function tokenHex(token: Uint8Array): string {
+    let out = "";
+    for (const b of token) {
+        out += b.toString(16).padStart(2, "0");
+    }
+    return out;
+}
+
+export class CoapClient {
+    #entropy: Entropy;
+    #messageId: number;
+    #channel: DtlsChannel;
+    #ackTimeoutMs: number;
+    #separateResponseTimeout: Duration;
+    /** Tracks the per-message-id retransmit slot. Removed once the BR ACKs the
+     *  request — either with a piggybacked response or an empty ACK announcing
+     *  a separate response. */
+    #pendingByMsgId = new Map<number, PendingState>();
+    /** Tracks the per-token response correlation slot. Removed only when the
+     *  response actually arrives (or the separate-response wait times out). */
+    #pendingByToken = new Map<string, PendingState>();
+    #listeners = new Set<Listener>();
+
+    constructor(channel: DtlsChannel, environment: Environment, opts?: CoapClientOpts) {
+        this.#channel = channel;
+        this.#entropy = environment.get(Crypto);
+        this.#messageId = this.#entropy.randomUint16;
+        this.#ackTimeoutMs = opts?.ackTimeoutMs ?? RFC_ACK_TIMEOUT;
+        this.#separateResponseTimeout =
+            opts?.separateResponseTimeoutMs !== undefined
+                ? Millis(opts.separateResponseTimeoutMs)
+                : SEPARATE_RESPONSE_TIMEOUT;
+        void this.#runRecvLoop();
+    }
+
+    async request(opts: {
+        type: "CON" | "NON";
+        code: string;
+        uriPath: string[];
+        payload?: Uint8Array;
+    }): Promise<CoapMessage> {
+        const messageId = this.#nextMessageId();
+        const token = this.#randomToken();
+        const msg: CoapMessage = {
+            type: opts.type,
+            code: opts.code,
+            messageId,
+            token,
+            uriPath: opts.uriPath,
+            payload: opts.payload ?? new Uint8Array(),
+        };
+
+        if (opts.type === "NON") {
+            await this.#channel.send(CoapMessage.encode(msg));
+            // NON messages receive no ACK per RFC 7252 §4.3; return a synthetic sentinel.
+            // Callers must not inspect code/type of this response.
+            return { type: "NON", code: "0.00", messageId, token, payload: new Uint8Array() };
+        }
+
+        return this.#sendCon(msg);
+    }
+
+    listen(uriPath: string[], handler: (msg: CoapMessage) => void): () => void {
+        const entry: Listener = { uriPath: [...uriPath], handler };
+        this.#listeners.add(entry);
+        return () => {
+            this.#listeners.delete(entry);
+        };
+    }
+
+    async close(): Promise<void> {
+        this.#listeners.clear();
+        await this.#channel.close();
+    }
+
+    async #sendCon(msg: CoapMessage): Promise<CoapMessage> {
+        if (this.#pendingByMsgId.has(msg.messageId)) {
+            throw new ImplementationError(
+                `CoapClient: messageId collision at ${msg.messageId} — too many concurrent CON requests`,
+            );
+        }
+        const reqTokenHex = tokenHex(msg.token);
+        if (this.#pendingByToken.has(reqTokenHex)) {
+            throw new ImplementationError(`CoapClient: token collision for ${reqTokenHex}`);
+        }
+
+        const encoded = CoapMessage.encode(msg);
+
+        return new Promise<CoapMessage>((resolve, reject) => {
+            let retransmitTimer: Timer | undefined;
+            let separateTimer: Timer | undefined;
+            let attempt = 0;
+
+            const cleanup = (): void => {
+                if (retransmitTimer !== undefined) {
+                    retransmitTimer.stop();
+                    retransmitTimer = undefined;
+                }
+                if (separateTimer !== undefined) {
+                    separateTimer.stop();
+                    separateTimer = undefined;
+                }
+                this.#pendingByMsgId.delete(msg.messageId);
+                this.#pendingByToken.delete(reqTokenHex);
+            };
+
+            const state: PendingState = {
+                resolve: (response: CoapMessage) => {
+                    cleanup();
+                    resolve(response);
+                },
+                reject: (err: Error) => {
+                    cleanup();
+                    reject(err);
+                },
+                tokenHex: reqTokenHex,
+                onEmptyAck: () => {
+                    // Stop retransmitting; the BR has accepted the request and will deliver
+                    // the response in a separate CON/NON message with the same token.
+                    if (retransmitTimer !== undefined) {
+                        retransmitTimer.stop();
+                        retransmitTimer = undefined;
+                    }
+                    this.#pendingByMsgId.delete(msg.messageId);
+                    separateTimer = Time.getTimer("coap-separate-response", this.#separateResponseTimeout, () => {
+                        state.reject(new CoapTimeoutError(msg.messageId));
+                    }).start();
+                },
+            };
+
+            const scheduleRetransmit = (delayMs: number): void => {
+                retransmitTimer = Time.getTimer("coap-retransmit", Millis(Math.round(delayMs)), () => {
+                    retransmitTimer = undefined;
+                    if (!this.#pendingByMsgId.has(msg.messageId)) return;
+                    if (attempt >= MAX_RETRANSMIT) {
+                        state.reject(new CoapTimeoutError(msg.messageId));
+                        return;
+                    }
+                    attempt++;
+                    void this.#channel
+                        .send(encoded)
+                        .catch(err =>
+                            logger.warn(`CoAP retransmit send failed for messageId=${msg.messageId}: ${err}`),
+                        );
+                    scheduleRetransmit(Math.min(delayMs * 2, this.#ackTimeoutMs * 2 ** MAX_RETRANSMIT));
+                }).start();
+            };
+
+            this.#pendingByMsgId.set(msg.messageId, state);
+            this.#pendingByToken.set(reqTokenHex, state);
+
+            const initialDelay = this.#ackTimeoutMs * (1 + Math.random() * (RFC_ACK_RANDOM_FACTOR - 1.0));
+            void this.#channel
+                .send(encoded)
+                .then(() => {
+                    scheduleRetransmit(initialDelay);
+                })
+                .catch(err => {
+                    state.reject(err instanceof Error ? err : new Error(String(err)));
+                });
+        });
+    }
+
+    async #runRecvLoop(): Promise<void> {
+        let channelError: Error | undefined;
+        try {
+            for await (const bytes of this.#channel) {
+                let msg: CoapMessage;
+                try {
+                    msg = CoapMessage.decode(Bytes.of(bytes));
+                } catch (err) {
+                    logger.debug(`CoAP inbound decode failed, dropping: ${err}`);
+                    continue;
+                }
+
+                await this.#dispatchInbound(msg);
+            }
+        } catch (err) {
+            channelError = err instanceof Error ? err : new Error(String(err));
+        } finally {
+            const err = channelError ?? new Error("CoapClient: channel closed");
+            // Reject all outstanding requests (both maps reference the same PendingState entries).
+            for (const state of this.#pendingByToken.values()) {
+                state.reject(err);
+            }
+            this.#pendingByMsgId.clear();
+            this.#pendingByToken.clear();
+        }
+    }
+
+    async #dispatchInbound(msg: CoapMessage): Promise<void> {
+        if (msg.type === "ACK") {
+            const state = this.#pendingByMsgId.get(msg.messageId);
+            if (state === undefined) {
+                // Stray ACK (duplicate or for a request we no longer track) — ignore.
+                return;
+            }
+            const isEmptyAck = msg.code === "0.00" && msg.payload.length === 0;
+            if (isEmptyAck) {
+                // Separate response coming.
+                state.onEmptyAck();
+                return;
+            }
+            // Piggybacked response.
+            state.resolve(msg);
+            return;
+        }
+
+        if (msg.type === "RST") {
+            const state = this.#pendingByMsgId.get(msg.messageId);
+            if (state !== undefined) {
+                state.reject(new Error(`CoAP RST received for messageId=${msg.messageId}`));
+            }
+            return;
+        }
+
+        // CON or NON. Check token first so a separate response is routed back to the
+        // originating #sendCon call regardless of which Uri-Path the BR replied on.
+        const inboundTokenHex = tokenHex(msg.token);
+        const pending = this.#pendingByToken.get(inboundTokenHex);
+        if (pending !== undefined) {
+            if (msg.type === "CON") {
+                await this.#sendEmptyAck(msg.messageId);
+            }
+            pending.resolve(msg);
+            return;
+        }
+
+        // Not a response to any pending request. ACK incoming CONs (RFC 7252 §4.3)
+        // and dispatch to listeners (this is the multicast diagnostic-answer path).
+        if (msg.type === "CON") {
+            await this.#sendEmptyAck(msg.messageId);
+        }
+        this.#dispatchToListeners(msg);
+    }
+
+    async #sendEmptyAck(messageId: number): Promise<void> {
+        // RFC 7252 §4.1: Empty messages have Code 0.00, no Token, no options, no payload.
+        const ack: CoapMessage = {
+            type: "ACK",
+            code: "0.00",
+            messageId,
+            token: new Uint8Array(),
+            payload: new Uint8Array(),
+        };
+        try {
+            await this.#channel.send(CoapMessage.encode(ack));
+        } catch (err) {
+            logger.debug(`Failed to send ACK for messageId=${messageId}:`, err);
+        }
+    }
+
+    #dispatchToListeners(msg: CoapMessage): void {
+        const inbound = msg.uriPath ?? [];
+        const uri = inbound.length > 0 ? `/${inbound.join("/")}` : "(none)";
+        let delivered = 0;
+        for (const listener of this.#listeners) {
+            if (!pathsEqual(listener.uriPath, inbound)) continue;
+            delivered++;
+            try {
+                listener.handler(msg);
+            } catch (err) {
+                logger.warn("CoapClient listener handler threw:", err);
+            }
+        }
+        if (delivered === 0) {
+            logger.debug(
+                `CoAP inbound consumed by no request or listener: uri=${uri} type=${msg.type} code=${msg.code} payloadLen=${msg.payload.length}`,
+            );
+        }
+    }
+
+    #nextMessageId(): number {
+        const id = this.#messageId;
+        this.#messageId = (this.#messageId + 1) & 0xffff;
+        return id;
+    }
+
+    #randomToken(): Uint8Array {
+        return Bytes.of(this.#entropy.randomBytes(4));
+    }
+}

package/src/coap/CoapMessage.ts

@@ -0,0 +1,190 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, MatterError } from "@matter/general";
+
+export type CoapType = "CON" | "NON" | "ACK" | "RST";
+
+export interface CoapMessage {
+    type: CoapType;
+    code: string;
+    messageId: number;
+    token: Uint8Array;
+    uriPath?: string[];
+    payload: Uint8Array;
+}
+
+/** Thrown when a CoAP datagram cannot be decoded per RFC 7252 §3. */
+export class CoapError extends MatterError {}
+
+const VERSION = 1;
+const OPTION_URI_PATH = 11;
+const PAYLOAD_MARKER = 0xff;
+
+const TYPE_TO_BITS: Record<CoapType, number> = { CON: 0, NON: 1, ACK: 2, RST: 3 };
+const BITS_TO_TYPE: readonly CoapType[] = ["CON", "NON", "ACK", "RST"];
+
+function encodeCode(code: string): number {
+    const match = /^(\d)\.(\d{2})$/.exec(code);
+    if (match === null) {
+        throw new CoapError(`Invalid CoAP code "${code}"`);
+    }
+    const cls = Number(match[1]);
+    const detail = Number(match[2]);
+    if (cls > 7 || detail > 31) {
+        throw new CoapError(`CoAP code "${code}" out of range (class 0-7, detail 0-31)`);
+    }
+    return (cls << 5) | detail;
+}
+
+function decodeCode(byte: number): string {
+    const cls = byte >> 5;
+    const detail = byte & 0x1f;
+    return `${cls}.${detail.toString().padStart(2, "0")}`;
+}
+
+/** RFC 7252 §3.1 option delta/length nibble: 0–12 literal, 13 → +1 ext byte, 14 → +2 ext bytes. */
+function encodeExtension(value: number): { nibble: number; extension: number[] } {
+    if (value < 13) {
+        return { nibble: value, extension: [] };
+    }
+    if (value < 269) {
+        return { nibble: 13, extension: [value - 13] };
+    }
+    const extended = value - 269;
+    return { nibble: 14, extension: [(extended >> 8) & 0xff, extended & 0xff] };
+}
+
+/** Avoids spread, which hits the JS engine's call-argument limit for a large payload. */
+function pushAll(out: number[], bytes: Iterable<number>): void {
+    for (const b of bytes) {
+        out.push(b);
+    }
+}
+
+function encodeOption(out: number[], delta: number, value: Uint8Array): void {
+    const d = encodeExtension(delta);
+    const l = encodeExtension(value.length);
+    out.push((d.nibble << 4) | l.nibble);
+    pushAll(out, d.extension);
+    pushAll(out, l.extension);
+    pushAll(out, value);
+}
+
+export namespace CoapMessage {
+    export function encode(msg: CoapMessage): Uint8Array {
+        const tokenLength = msg.token.length;
+        if (tokenLength > 8) {
+            throw new CoapError(`CoAP token too long: ${tokenLength} (max 8)`);
+        }
+
+        const out = new Array<number>();
+        out.push((VERSION << 6) | (TYPE_TO_BITS[msg.type] << 4) | tokenLength);
+        out.push(encodeCode(msg.code));
+        out.push((msg.messageId >> 8) & 0xff, msg.messageId & 0xff);
+        pushAll(out, msg.token);
+
+        if (msg.uriPath !== undefined) {
+            let lastOptionNumber = 0;
+            for (const segment of msg.uriPath) {
+                encodeOption(out, OPTION_URI_PATH - lastOptionNumber, Bytes.of(Bytes.fromString(segment)));
+                lastOptionNumber = OPTION_URI_PATH;
+            }
+        }
+
+        if (msg.payload.length > 0) {
+            out.push(PAYLOAD_MARKER);
+            pushAll(out, msg.payload);
+        }
+
+        return Uint8Array.from(out);
+    }
+
+    export function decode(bytes: Uint8Array): CoapMessage {
+        if (bytes.length < 4) {
+            throw new CoapError(`CoAP message too short: ${bytes.length} bytes`);
+        }
+
+        const version = bytes[0] >> 6;
+        if (version !== VERSION) {
+            throw new CoapError(`Unsupported CoAP version ${version}`);
+        }
+        const type = BITS_TO_TYPE[(bytes[0] >> 4) & 0x3];
+        const tokenLength = bytes[0] & 0x0f;
+        if (tokenLength > 8) {
+            throw new CoapError(`Invalid CoAP token length ${tokenLength}`);
+        }
+
+        const code = decodeCode(bytes[1]);
+        const messageId = (bytes[2] << 8) | bytes[3];
+
+        let pos = 4;
+        if (pos + tokenLength > bytes.length) {
+            throw new CoapError("CoAP token exceeds message length");
+        }
+        const token = bytes.slice(pos, pos + tokenLength);
+        pos += tokenLength;
+
+        const readExtension = (nibble: number): number => {
+            if (nibble < 13) {
+                return nibble;
+            }
+            if (nibble === 13) {
+                if (pos >= bytes.length) {
+                    throw new CoapError("Truncated CoAP option (1-byte extension)");
+                }
+                return bytes[pos++] + 13;
+            }
+            if (nibble === 14) {
+                if (pos + 2 > bytes.length) {
+                    throw new CoapError("Truncated CoAP option (2-byte extension)");
+                }
+                const value = ((bytes[pos] << 8) | bytes[pos + 1]) + 269;
+                pos += 2;
+                return value;
+            }
+            throw new CoapError("Reserved CoAP option nibble 15");
+        };
+
+        const uriPath = new Array<string>();
+        let optionNumber = 0;
+        let payload = new Uint8Array();
+        while (pos < bytes.length) {
+            const header = bytes[pos];
+            if (header === PAYLOAD_MARKER) {
+                pos++;
+                payload = bytes.slice(pos);
+                if (payload.length === 0) {
+                    throw new CoapError("CoAP payload marker with no payload");
+                }
+                break;
+            }
+            pos++;
+
+            const delta = readExtension(header >> 4);
+            const length = readExtension(header & 0x0f);
+            optionNumber += delta;
+            if (pos + length > bytes.length) {
+                throw new CoapError("CoAP option value exceeds message length");
+            }
+            const value = bytes.slice(pos, pos + length);
+            pos += length;
+
+            if (optionNumber === OPTION_URI_PATH) {
+                uriPath.push(Bytes.toString(value));
+            }
+        }
+
+        return {
+            type,
+            code,
+            messageId,
+            token,
+            uriPath: uriPath.length > 0 ? uriPath : undefined,
+            payload,
+        };
+    }
+}

package/src/coap/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export { CoapClient, CoapTimeoutError } from "./CoapClient.js";
+export type { CoapMessage, CoapType } from "./CoapMessage.js";