@project-chip/matter.js 0.13.0-alpha.0-20250304-d4a7592a4 → 0.13.0-alpha.0-20250307-ebf84a05a

package/src/MatterDevice.ts

@@ -1,324 +0,0 @@
-/**
- * @license
- * Copyright 2022-2025 Matter.js Authors
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * Important note: This file is part of the legacy matter-node (internal) API and should not be used anymore directly!
- * Please use the new API classes!
- * @deprecated
- */
-
-import {
-    Construction,
-    InternalError,
-    ObserverGroup,
-    StorageContext,
-    TransportInterface,
-    TransportInterfaceSet,
-    asyncNew,
-} from "#general";
-import {
-    ChannelManager,
-    CommissioningConfigProvider,
-    DeviceAdvertiser,
-    DeviceCommissioner,
-    ExchangeManager,
-    Fabric,
-    FabricAction,
-    FabricManager,
-    FailsafeContext,
-    InstanceBroadcaster,
-    PaseServer,
-    PeerAddress,
-    ProtocolHandler,
-    SecureChannelProtocol,
-    Session,
-    SessionManager,
-    SessionParameters,
-} from "#protocol";
-import { CommissioningOptions, FabricIndex } from "#types";
-
-export class MatterDevice {
-    readonly #exchangeManager;
-    readonly #fabricManager: FabricManager;
-    readonly #sessionManager: SessionManager;
-    readonly #commissioner: DeviceCommissioner;
-    readonly #advertiser: DeviceAdvertiser;
-    readonly #transportInterfaces: TransportInterfaceSet;
-    readonly #channelManager: ChannelManager;
-    readonly #observers = new ObserverGroup();
-    #isClosing = false;
-
-    #construction: Construction<MatterDevice>;
-
-    get construction() {
-        return this.#construction;
-    }
-
-    static async create(
-        sessionStorage: StorageContext,
-        fabricStorage: StorageContext,
-        getCommissioningConfig: () => CommissioningOptions.Configuration,
-        minimumCaseSessionsPerFabricAndNode = 3,
-        commissioningChangedCallback: (fabricIndex: FabricIndex, fabricAction: FabricAction) => void,
-        sessionChangedCallback: (fabricIndex: FabricIndex) => void,
-        sessionParameters?: Partial<SessionParameters>,
-    ) {
-        return asyncNew(
-            MatterDevice,
-            sessionStorage,
-            fabricStorage,
-            getCommissioningConfig,
-            minimumCaseSessionsPerFabricAndNode,
-            commissioningChangedCallback,
-            sessionChangedCallback,
-            sessionParameters,
-        );
-    }
-
-    constructor(
-        readonly sessionStorage: StorageContext,
-        readonly fabricStorage: StorageContext,
-        getCommissioningConfig: () => CommissioningOptions.Configuration,
-        minimumCaseSessionsPerFabricAndNode: number,
-        private readonly commissioningChangedCallback: (fabricIndex: FabricIndex, fabricAction: FabricAction) => void,
-        private readonly sessionChangedCallback: (fabricIndex: FabricIndex) => void,
-        sessionParameters: Partial<SessionParameters> = {},
-    ) {
-        this.#channelManager = new ChannelManager(minimumCaseSessionsPerFabricAndNode);
-
-        this.#fabricManager = new FabricManager(fabricStorage);
-
-        this.#observers.on(this.#fabricManager.events.deleted, async ({ fabricIndex }) =>
-            this.commissioningChangedCallback(fabricIndex, FabricAction.Removed),
-        );
-        this.#observers.on(this.#fabricManager.events.updated, ({ fabricIndex }) =>
-            this.commissioningChangedCallback(fabricIndex, FabricAction.Updated),
-        );
-
-        this.#sessionManager = new SessionManager({
-            fabrics: this.#fabricManager,
-            storage: sessionStorage,
-            parameters: sessionParameters,
-            owner: this,
-        });
-
-        this.#transportInterfaces = new TransportInterfaceSet();
-
-        this.#exchangeManager = new ExchangeManager({
-            transportInterfaces: this.#transportInterfaces,
-            sessionManager: this.#sessionManager,
-            channelManager: this.#channelManager,
-        });
-
-        const secureChannelProtocol = new SecureChannelProtocol(this.#sessionManager, this.#fabricManager);
-
-        this.#exchangeManager.addProtocolHandler(secureChannelProtocol);
-
-        this.#observers.on(this.#sessionManager.sessions.added, session => {
-            if (session.fabric) {
-                this.sessionChangedCallback(session.fabric.fabricIndex);
-            }
-        });
-
-        this.#observers.on(this.#sessionManager.sessions.deleted, async session => {
-            const currentFabricIndex = session.fabric?.fabricIndex;
-            if (currentFabricIndex !== undefined) {
-                this.sessionChangedCallback(currentFabricIndex);
-            }
-        });
-
-        this.#observers.on(this.#sessionManager.subscriptionsChanged, (session, _subscription) => {
-            const currentFabric = session.fabric;
-            if (currentFabric !== undefined) {
-                this.sessionChangedCallback(currentFabric.fabricIndex);
-            }
-        });
-
-        this.#advertiser = new DeviceAdvertiser({
-            fabrics: this.fabricManager,
-            sessions: this.sessionManager,
-        });
-        this.#commissioner = new DeviceCommissioner({
-            fabrics: this.fabricManager,
-            sessions: this.sessionManager,
-            advertiser: this.#advertiser,
-            secureChannelProtocol,
-            commissioningConfig: new (class extends CommissioningConfigProvider {
-                get values() {
-                    return getCommissioningConfig();
-                }
-            })(),
-        });
-
-        this.#construction = Construction(this, async () => {
-            await this.#fabricManager.construction.ready;
-
-            // Attach added events delayed because initialization from storage would else trigger it
-            this.#observers.on(this.#fabricManager.events.added, ({ fabricIndex }) =>
-                this.commissioningChangedCallback(fabricIndex, FabricAction.Added),
-            );
-
-            await this.#sessionManager.construction.ready;
-        });
-    }
-
-    get fabricManager() {
-        return this.#fabricManager;
-    }
-
-    get sessionManager() {
-        return this.#sessionManager;
-    }
-
-    get exchangeManager() {
-        return this.#exchangeManager;
-    }
-
-    get advertiser() {
-        return this.#advertiser;
-    }
-
-    get commissioner() {
-        return this.#commissioner;
-    }
-
-    get failsafeContext() {
-        return this.#commissioner.failsafeContext;
-    }
-
-    get isClosing() {
-        return this.#isClosing;
-    }
-
-    async beginTimed(failsafeContext: FailsafeContext) {
-        return this.#commissioner.beginTimed(failsafeContext);
-    }
-
-    assertFailSafeArmed(message?: string) {
-        return this.#commissioner.assertFailsafeArmed(message);
-    }
-
-    isFailsafeArmed() {
-        return this.#commissioner.isFailsafeArmed;
-    }
-
-    hasBroadcaster(broadcaster: InstanceBroadcaster) {
-        return this.#advertiser.hasBroadcaster(broadcaster);
-    }
-
-    addBroadcaster(broadcaster: InstanceBroadcaster) {
-        this.#advertiser.addBroadcaster(broadcaster);
-        return this;
-    }
-
-    async deleteBroadcaster(broadcaster: InstanceBroadcaster) {
-        return this.#advertiser.deleteBroadcaster(broadcaster);
-    }
-
-    addTransportInterface(transport: TransportInterface) {
-        this.#transportInterfaces.add(transport);
-        return this;
-    }
-
-    async deleteTransportInterface(transport: TransportInterface) {
-        this.#transportInterfaces.delete(transport);
-    }
-
-    hasProtocolHandler(protocolId: number) {
-        return this.exchangeManager.hasProtocolHandler(protocolId);
-    }
-
-    addProtocolHandler(protocol: ProtocolHandler) {
-        this.exchangeManager.addProtocolHandler(protocol);
-        return this;
-    }
-
-    async start() {
-        await this.startAnnouncement();
-    }
-
-    async startAnnouncement() {
-        return this.#advertiser.startAdvertising();
-    }
-
-    async announce(announceOnce = false) {
-        return this.#advertiser.advertise(announceOnce);
-    }
-
-    reAnnounceAsCommissionable() {
-        this.#commissioner.reactivateAdvertiser();
-    }
-
-    findFabricFromDestinationId(destinationId: Uint8Array, peerRandom: Uint8Array) {
-        return this.#fabricManager.findFabricFromDestinationId(destinationId, peerRandom);
-    }
-
-    async sendFabricAnnouncements(fabrics: Fabric[], expireCommissioningAnnouncement = false) {
-        return this.#advertiser.advertiseFabrics(fabrics, expireCommissioningAnnouncement);
-    }
-
-    getFabricByIndex(fabricIndex: FabricIndex) {
-        return this.#fabricManager.findByIndex(fabricIndex);
-    }
-
-    initiateExchange(address: PeerAddress, protocolId: number) {
-        return this.#exchangeManager.initiateExchange(address, protocolId);
-    }
-
-    getFabrics() {
-        return this.#fabricManager.fabrics;
-    }
-
-    isCommissioned() {
-        return !!this.#fabricManager.length;
-    }
-
-    async allowEnhancedCommissioning(
-        discriminator: number,
-        paseServer: PaseServer,
-        commissioningEndCallback: () => void,
-    ) {
-        return this.#commissioner.allowEnhancedCommissioning(discriminator, paseServer, commissioningEndCallback);
-    }
-
-    async allowBasicCommissioning(commissioningEndCallback?: () => void) {
-        return this.#commissioner.allowBasicCommissioning(commissioningEndCallback);
-    }
-
-    async endCommissioning() {
-        return this.#commissioner.endCommissioning();
-    }
-
-    existsOpenPaseSession() {
-        return !!this.#sessionManager.getPaseSession();
-    }
-
-    async close() {
-        this.#isClosing = true;
-        this.#observers.close();
-        await this.#commissioner.close();
-        await this.#advertiser.close();
-        await this.exchangeManager.close();
-        await this.#sessionManager.close();
-        await this.#channelManager.close();
-        await this.#transportInterfaces.close();
-    }
-
-    getActiveSessionInformation() {
-        return this.#sessionManager.getActiveSessionInformation();
-    }
-
-    static of(session: Session | undefined) {
-        if (session === undefined) {
-            throw new InternalError("Device operation without session");
-        }
-        const device = session.owner;
-        if (!(device instanceof MatterDevice)) {
-            throw new InternalError("Device operation on non-device session");
-        }
-        return device;
-    }
-}

package/src/MatterNode.ts

@@ -1,24 +0,0 @@
-/**
- * @license
- * Copyright 2022-2025 Matter.js Authors
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { MdnsBroadcaster, MdnsScanner } from "#protocol";
-
-/**
- * Abstract base class that represents a node in the matter ecosystem.
- */
-export abstract class MatterNode {
-    abstract close(): Promise<void>;
-
-    abstract getPort(): number | undefined;
-
-    abstract initialize(ipv4Disabled: boolean): void;
-
-    abstract start(): Promise<void>;
-
-    abstract setMdnsBroadcaster(mdnsBroadcaster: MdnsBroadcaster): void;
-
-    abstract setMdnsScanner(mdnsScanner: MdnsScanner): void;
-}

package/src/MatterServer.ts

@@ -1,276 +0,0 @@
-/**
- * @license
- * Copyright 2022-2025 Matter.js Authors
- * SPDX-License-Identifier: Apache-2.0
- */
-import { Logger, Network, NetworkError, StorageManager, SyncStorage } from "#general";
-import { MdnsBroadcaster, MdnsScanner } from "#protocol";
-import { CommissioningController } from "./CommissioningController.js";
-import { CommissioningServer } from "./CommissioningServer.js";
-import { MatterNode } from "./MatterNode.js";
-
-const logger = Logger.get("MatterServer");
-
-const MATTER_PORT = 5540;
-
-export type NodeOptions = {
-    /** Unique storage key for this node to use for the storage context of this node. If not provided the order of node addition is used. */
-    uniqueStorageKey?: string;
-
-    /**
-     * Deprecated name for uniqueStorageKey
-     * TODO: Remove with 0.8 or such
-     * @deprecated
-     */
-    uniqueNodeId?: string;
-};
-
-export type MatterServerOptions = {
-    /** If set to true no IPv4 socket listener is sed and only IPv6 is supported. */
-    disableIpv4?: boolean;
-
-    /**
-     * Interface to use for MDNS announcements. If not provided announcements will be sent from all network interfaces
-     * TODO: Remove in later versions then 0.7
-     * @deprecated
-     */
-    mdnsAnnounceInterface?: string;
-
-    /**
-     * Interface to use for MDNS announcements and scanning. If not provided announcements/scanning will be done on all
-     * network interfaces
-     */
-    mdnsInterface?: string;
-};
-
-/**
- * Main Matter server class that represents the process on the host allowing to commission and pair multiple devices
- * by reusing MDNS scanner and broadcaster
- */
-export class MatterServer {
-    private started = false;
-    private readonly nodes = new Map<string, MatterNode>();
-
-    private mdnsScanner?: MdnsScanner;
-    private mdnsBroadcaster?: MdnsBroadcaster;
-
-    private readonly formerlyUsedPorts = new Array<number>();
-
-    /**
-     * Create a new Matter server instance
-     *
-     * @param storageManager Storage manager instance to use for all nodes
-     * @param options Optional MatterServer options
-     */
-    constructor(
-        private readonly storageManager: StorageManager<SyncStorage>,
-        private readonly options?: MatterServerOptions,
-    ) {}
-
-    get ipv4Disabled() {
-        return !!this.options?.disableIpv4;
-    }
-
-    private getNextMatterPort(desiredPort?: number) {
-        // Build a temporary map with all ports in use
-        const portCheckMap = new Map<number, boolean>();
-        for (const node of this.nodes.values()) {
-            const nodePort = node.getPort();
-            if (nodePort === undefined) continue;
-            if (portCheckMap.has(nodePort)) {
-                throw new NetworkError(`Port ${nodePort} is already in use by other node.`);
-            }
-            portCheckMap.set(nodePort, true);
-        }
-
-        if (desiredPort !== undefined) {
-            if (portCheckMap.has(desiredPort)) {
-                throw new NetworkError(`Port ${desiredPort} is already in use by other node.`);
-            }
-            return desiredPort;
-        }
-
-        // Try to find a free port with consideration of currently blocked ports, we start at the matter default port
-        let portToCheck = MATTER_PORT;
-        while ((portCheckMap.has(portToCheck) || this.formerlyUsedPorts.includes(portToCheck)) && portToCheck < 65536) {
-            portToCheck++;
-        }
-        // If we did not find an available port, check the oldest blocked ones
-        if (portToCheck === 65536) {
-            for (let i = 0; i < this.formerlyUsedPorts.length; i++) {
-                const port = this.formerlyUsedPorts[i];
-                this.formerlyUsedPorts.splice(i, 1); // Irrelevant of next check result, remove from blocked ports
-                if (!portCheckMap.has(port)) {
-                    // Should normally be always the case, but lets make sure
-                    portToCheck = port;
-                    break;
-                }
-            }
-            if (portToCheck === 65536) {
-                throw new NetworkError("No free port available for Matter server.");
-            }
-        }
-
-        return portToCheck;
-    }
-
-    /**
-     * Add a CommissioningServer node to the server
-     *
-     * @param commissioningServer CommissioningServer node to add
-     * @param nodeOptions Optional options for the node (e.g. unique node id)
-     */
-    async addCommissioningServer(commissioningServer: CommissioningServer, nodeOptions?: NodeOptions) {
-        const storageKey = nodeOptions?.uniqueStorageKey ?? nodeOptions?.uniqueNodeId ?? this.nodes.size.toString();
-        if (this.nodes.has(storageKey)) {
-            throw new Error(`Node with storage key "${storageKey}" already exists.`);
-        }
-        commissioningServer.setPort(this.getNextMatterPort(commissioningServer.getPort()));
-        await commissioningServer.setStorage(this.storageManager.createContext(storageKey));
-        logger.debug(`Adding CommissioningServer using storage key "${storageKey}".`);
-        await this.prepareNode(commissioningServer);
-        this.nodes.set(storageKey, commissioningServer);
-    }
-
-    /**
-     * Remove a CommissioningServer node from the server, close the CommissioningServer and optionally destroy the
-     * storage context.
-     *
-     * @param commissioningServer CommissioningServer node to remove
-     * @param destroyStorage If true the storage context will be destroyed
-     */
-    async removeCommissioningServer(commissioningServer: CommissioningServer, destroyStorage = false) {
-        // Find instance from list
-        for (const [key, value] of this.nodes.entries()) {
-            if (value === commissioningServer) {
-                this.nodes.delete(key);
-
-                const port = commissioningServer.getPort();
-                if (port !== undefined) {
-                    // Remember port to not reuse for this run if not needed to prevent issues with controllers
-                    this.formerlyUsedPorts.push(port);
-                }
-
-                // Close instance
-                await commissioningServer.close();
-
-                if (destroyStorage) {
-                    // Destroy storage
-                    await commissioningServer.factoryReset();
-                }
-                return;
-            }
-        }
-
-        throw new Error("CommissioningServer to remove not found.");
-    }
-
-    /**
-     * Add a Controller node to the server
-     *
-     * @param commissioningController Controller node to add
-     * @param nodeOptions Optional options for the node (e.g. unique node id)
-     */
-    async addCommissioningController(commissioningController: CommissioningController, nodeOptions?: NodeOptions) {
-        const storageKey = nodeOptions?.uniqueStorageKey ?? nodeOptions?.uniqueNodeId ?? this.nodes.size.toString();
-        if (this.nodes.has(storageKey)) {
-            throw new Error(`Node with storage key "${storageKey}" already exists.`);
-        }
-
-        const localPort = commissioningController.getPort();
-        if (localPort !== undefined) {
-            // If a local port for controller is defined verify that the port is not overlapping with other nodes
-            // Method throws if port is already used
-            this.getNextMatterPort(localPort);
-        }
-        commissioningController.setStorage(this.storageManager.createContext(storageKey));
-        logger.debug(`Adding CommissioningController using storage key "${storageKey}".`);
-        await this.prepareNode(commissioningController);
-        this.nodes.set(storageKey, commissioningController);
-    }
-
-    /**
-     * Remove a Controller node from the server, close the Controller and optionally destroy the storage context.
-     *
-     * @param commissioningController Controller node to remove
-     * @param destroyStorage If true the storage context will be destroyed
-     */
-    async removeCommissioningController(commissioningController: CommissioningController, destroyStorage = false) {
-        // Find instance from list
-        for (const [key, value] of this.nodes.entries()) {
-            if (value === commissioningController) {
-                this.nodes.delete(key);
-
-                // Close instance
-                await commissioningController.close();
-
-                if (destroyStorage) {
-                    // Destroy storage
-                    await commissioningController.resetStorage();
-                }
-                return;
-            }
-        }
-
-        throw new Error("CommissioningController to remove not found.");
-    }
-
-    /**
-     * Start the server and all nodes. If the nodes do not have specified a delayed announcement or pairing they will
-     * be announced/paired immediately.
-     */
-    async start() {
-        if (this.mdnsBroadcaster === undefined) {
-            this.mdnsBroadcaster = await MdnsBroadcaster.create(Network.get(), {
-                enableIpv4: !this.ipv4Disabled,
-                multicastInterface: this.options?.mdnsInterface ?? this.options?.mdnsAnnounceInterface,
-            });
-        }
-        if (this.mdnsScanner === undefined) {
-            this.mdnsScanner = await MdnsScanner.create(Network.get(), {
-                enableIpv4: !this.ipv4Disabled,
-                netInterface: this.options?.mdnsInterface,
-            });
-        }
-        this.started = true;
-        for (const [key, node] of this.nodes.entries()) {
-            try {
-                await this.prepareNode(node);
-            } catch (error: any) {
-                // TODO: Find a better way how to report back such issues and which nodes errored
-                logger.error(`Failed to start node with storageKey ${key}:`, error);
-            }
-        }
-    }
-
-    private async prepareNode(node: MatterNode) {
-        node.initialize(this.ipv4Disabled);
-        if (this.mdnsBroadcaster === undefined || this.mdnsScanner === undefined) {
-            logger.debug("Mdns instances not yet created, delaying node preparation.");
-            return;
-        }
-        node.setMdnsBroadcaster(this.mdnsBroadcaster);
-        node.setMdnsScanner(this.mdnsScanner);
-        if (this.started) {
-            await node.start();
-        }
-    }
-
-    /**
-     * Close the server and all nodes
-     */
-    async close() {
-        for (const [key, node] of this.nodes.entries()) {
-            try {
-                await node.close();
-            } catch (error) {
-                logger.error(`Failed to close node with storageKey ${key}: ${error}`);
-            }
-        }
-        await this.mdnsBroadcaster?.close();
-        this.mdnsBroadcaster = undefined;
-        await this.mdnsScanner?.close();
-        this.mdnsScanner = undefined;
-        this.started = false;
-    }
-}