@matter/protocol 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/peer/ControllerDiscovery.ts

@@ -0,0 +1,231 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { anyPromise, ClassExtends, Logger, NoResponseTimeoutError, serverAddressToString } from "#general";
+import { NodeId } from "#types";
+import {
+    AddressTypeFromDevice,
+    CommissionableDevice,
+    CommissionableDeviceIdentifiers,
+    DiscoverableDevice,
+    OperationalDevice,
+    Scanner,
+} from "../common/Scanner.js";
+import { Fabric } from "../fabric/Fabric.js";
+import { MdnsScanner } from "../mdns/MdnsScanner.js";
+import { RetransmissionLimitReachedError } from "../protocol/MessageExchange.js";
+import { CommissioningError } from "./ControllerCommissioningFlow.js";
+
+const logger = Logger.get("ControllerDiscovery");
+
+export class DiscoveryError extends RetransmissionLimitReachedError {}
+
+/**
+ * Special Error instance used to detect if the retransmission limit was reached during pairing for case or pase.
+ * Mainly means that the device was not responding to the pairing request.
+ */
+export class PairRetransmissionLimitReachedError extends RetransmissionLimitReachedError {}
+
+export class ControllerDiscovery {
+    /**
+     * Discovers devices by a provided identifier and a list of scanners (e.g. IP and BLE in parallel).
+     * It returns after the timeout or if at least one device was found.
+     * The method returns a list of addresses of the discovered devices.
+     */
+    static async discoverDeviceAddressesByIdentifier(
+        scanners: Array<Scanner>,
+        identifier: CommissionableDeviceIdentifiers,
+        timeoutSeconds = 30,
+    ): Promise<CommissionableDevice[]> {
+        logger.info(`Start Discovering devices using identifier ${Logger.toJSON(identifier)} ...`);
+
+        const scanResults = scanners.map(async scanner => {
+            const foundDevices = await scanner.findCommissionableDevices(identifier, timeoutSeconds);
+            logger.info(`Found ${foundDevices.length} devices using identifier ${Logger.toJSON(identifier)}`);
+            if (foundDevices.length === 0) {
+                throw new CommissioningError(
+                    `No device discovered using identifier ${Logger.toJSON(
+                        identifier,
+                    )}! Please check that the relevant device is online.`,
+                );
+            }
+
+            const devices = foundDevices.filter(device => device.addresses.length > 0);
+            if (devices.length === 0) {
+                throw new CommissioningError(
+                    `Device discovered using identifier ${Logger.toJSON(
+                        identifier,
+                    )}, but no Network addresses discovered.`,
+                );
+            }
+            return devices;
+        });
+
+        return await anyPromise(scanResults);
+    }
+
+    static async discoverCommissionableDevices(
+        scanners: Array<Scanner>,
+        timeoutSeconds: number,
+        identifier: CommissionableDeviceIdentifiers = {},
+        discoveredCallback?: (device: CommissionableDevice) => void,
+    ): Promise<CommissionableDevice[]> {
+        const discoveredDevices = new Map<string, CommissionableDevice>();
+
+        await Promise.all(
+            scanners.map(async scanner => {
+                await scanner.findCommissionableDevicesContinuously(
+                    identifier,
+                    device => {
+                        const { deviceIdentifier } = device;
+                        if (!discoveredDevices.has(deviceIdentifier)) {
+                            discoveredDevices.set(deviceIdentifier, device);
+                            discoveredCallback?.(device);
+                        }
+                    },
+                    timeoutSeconds,
+                );
+            }),
+        );
+
+        // The final answer only consists the devices still left, so expired ones will be excluded
+        const finalDiscoveredDevices = new Map<string, CommissionableDevice>();
+        scanners.forEach(scanner => {
+            const devices = scanner.getDiscoveredCommissionableDevices(identifier);
+            devices.forEach(device => {
+                const { deviceIdentifier } = device;
+                if (!discoveredDevices.has(deviceIdentifier)) {
+                    discoveredDevices.set(deviceIdentifier, device);
+                    discoveredCallback?.(device);
+                }
+                if (!finalDiscoveredDevices.has(deviceIdentifier)) {
+                    finalDiscoveredDevices.set(deviceIdentifier, device);
+                }
+            });
+        });
+
+        return Array.from(finalDiscoveredDevices.values());
+    }
+
+    static async discoverOperationalDevice(
+        fabric: Fabric,
+        peerNodeId: NodeId,
+        scanner: MdnsScanner,
+        timeoutSeconds?: number,
+        ignoreExistingRecords?: boolean,
+    ): Promise<OperationalDevice> {
+        const foundDevice = await scanner.findOperationalDevice(
+            fabric,
+            peerNodeId,
+            timeoutSeconds,
+            ignoreExistingRecords,
+        );
+        if (foundDevice === undefined) {
+            throw new DiscoveryError(
+                "The operational device cannot be found on the network. Please make sure it is online.",
+            );
+        }
+        return foundDevice;
+    }
+
+    static cancelOperationalDeviceDiscovery(fabric: Fabric, peerNodeId: NodeId, scanner: MdnsScanner) {
+        scanner.cancelOperationalDeviceDiscovery(fabric, peerNodeId);
+    }
+
+    static cancelCommissionableDeviceDiscovery(scanner: Scanner, identifier: CommissionableDeviceIdentifiers = {}) {
+        scanner.cancelCommissionableDeviceDiscovery(identifier);
+    }
+
+    /**
+     * Helper method to iterate through a list of server addresses and try to execute a method on each of them. If the
+     * method throws a configurable error (or EHOSTUNREACH), the server address list is updated (to also add later
+     * discovered addresses or devices) and then next server address is tried.The result of the first successful method
+     * call is returned. The logic makes sure to only try each unique address (IP/port) once.
+     */
+    static async iterateServerAddresses<DD extends DiscoverableDevice<any>, T, E extends Error>(
+        devices: DD[],
+        errorType: ClassExtends<E>,
+        updateDevicesFunc: () => Promise<DD[]>,
+        func: (address: AddressTypeFromDevice<DD>, device?: DD) => Promise<T>,
+        lastKnownAddress?: AddressTypeFromDevice<DD>,
+    ): Promise<{ result: T; resultAddress: AddressTypeFromDevice<DD>; resultDevice?: DD }> {
+        const processOneAddress = async (
+            address: AddressTypeFromDevice<DD>,
+            device?: DD,
+        ): Promise<{ result: T; resultAddress: AddressTypeFromDevice<DD>; resultDevice?: DD } | undefined> => {
+            const serverKey = serverAddressToString(address);
+
+            logger.debug(`Try to communicate with ${serverKey} ...`);
+            try {
+                return { result: await func(address, device), resultAddress: address, resultDevice: device };
+            } catch (error) {
+                if (error instanceof errorType || error instanceof NoResponseTimeoutError) {
+                    logger.debug(`Failed to communicate with ${serverKey}, try other servers ...`, error);
+                } else {
+                    throw error;
+                }
+            }
+        };
+
+        const addresses = new Map<string, { address: AddressTypeFromDevice<DD>; device?: DD }>();
+
+        devices.forEach(device =>
+            device.addresses.forEach(address => addresses.set(serverAddressToString(address), { address, device })),
+        );
+        const triedAddresses = new Set<string>();
+
+        if (lastKnownAddress !== undefined) {
+            const knownKey = serverAddressToString(lastKnownAddress);
+            const knownDevice = addresses.has(serverAddressToString(lastKnownAddress))
+                ? addresses.get(knownKey)?.device
+                : undefined;
+            addresses.delete(knownKey);
+            const result = await processOneAddress(lastKnownAddress, knownDevice);
+            if (result !== undefined) {
+                return result;
+            }
+            triedAddresses.add(knownKey);
+        }
+
+        while (true) {
+            logger.debug(
+                `Server addresses to try: ${Array.from(addresses)
+                    .map(([addressString, { device }]) => `${device?.DN}: ${addressString}`)
+                    .join(",")}`,
+            );
+
+            let triedOne = false;
+            for (const { address, device } of addresses.values()) {
+                const serverKey = serverAddressToString(address);
+                if (triedAddresses.has(serverKey)) continue;
+                triedAddresses.add(serverKey);
+
+                try {
+                    triedOne = true;
+                    const result = await processOneAddress(address, device);
+                    if (result !== undefined) {
+                        return result;
+                    }
+                } catch (error) {
+                    if (error instanceof errorType || error instanceof NoResponseTimeoutError) {
+                        logger.debug(`Failed to communicate with ${serverKey}, try next server ...`, error);
+                    } else {
+                        throw error;
+                    }
+                }
+            }
+            if (triedOne) {
+                (await updateDevicesFunc()).forEach(device =>
+                    device.addresses.forEach(address =>
+                        addresses.set(serverAddressToString(address), { address, device }),
+                    ),
+                ); // Update list and add new
+            } else {
+                throw new PairRetransmissionLimitReachedError(`Failed to connect on any discovered server`);
+            }
+        }
+    }
+}

package/src/peer/OperationalPeer.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { DiscoveryData } from "#common/Scanner.js";
+import { ServerAddressIp } from "#general";
+import { PeerAddress } from "./PeerAddress.js";
+
+/**
+ * Operational information for a single peer.
+ *
+ * For our purposes a "peer" is another node commissioned to a fabric to which we have access.
+ */
+
+export interface OperationalPeer {
+    /**
+     * The logical address of the peer.
+     */
+    address: PeerAddress;
+
+    /**
+     * A physical address the peer may be accessed at, if known.
+     */
+    operationalAddress?: ServerAddressIp;
+
+    /**
+     * Additional information collected while locating the peer.
+     */
+    discoveryData?: DiscoveryData;
+}

package/src/peer/PeerAddress.ts

@@ -0,0 +1,78 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { FabricIndex, NodeId } from "@matter/types";
+
+/**
+ * This is the "logical" address of a peer node consisting of a fabric and node ID.
+ */
+export interface PeerAddress {
+    fabricIndex: FabricIndex;
+    nodeId: NodeId;
+}
+
+const interned = Symbol("interned-logical-address");
+
+const internedAddresses = new Map<FabricIndex, Map<NodeId, PeerAddress>>();
+
+/**
+ * Obtain a canonical instance of a logical address.
+ *
+ * This allows for identification based on object comparison.  Interned addresses render to a string in the format
+ * "@<fabric index>:<node id>"
+ */
+export function PeerAddress(address: PeerAddress): PeerAddress {
+    if (interned in address) {
+        return address;
+    }
+
+    let internedFabric = internedAddresses.get(address.fabricIndex);
+    if (internedFabric === undefined) {
+        internedAddresses.set(address.fabricIndex, (internedFabric = new Map()));
+    }
+
+    let internedAddress = internedFabric.get(address.nodeId);
+    if (internedAddress) {
+        return internedAddress;
+    }
+
+    internedFabric.set(
+        address.nodeId,
+        (internedAddress = {
+            ...address,
+
+            [interned]: true,
+
+            toString() {
+                const nodeStr = this.nodeId > 0xffff ? `0x${this.nodeId.toString(16)}` : this.nodeId;
+                return `peer@${this.fabricIndex}:${nodeStr}`;
+            },
+        } as PeerAddress),
+    );
+
+    return internedAddress;
+}
+
+/**
+ * A collection of items keyed by logical address.
+ */
+export class PeerAddressMap<T> extends Map<PeerAddress, T> {
+    override delete(key: PeerAddress) {
+        return super.delete(PeerAddress(key));
+    }
+
+    override has(key: PeerAddress) {
+        return super.has(PeerAddress(key));
+    }
+
+    override set(key: PeerAddress, value: T) {
+        return super.set(PeerAddress(key), value);
+    }
+
+    override get(key: PeerAddress) {
+        return super.get(PeerAddress(key));
+    }
+}