@matter/protocol 0.16.0-alpha.0-20251203-aaf94bca8 → 0.16.0-alpha.0-20251207-37e501b18

package/src/peer/Peer.ts

@@ -0,0 +1,161 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { BasicInformation } from "#clusters/basic-information";
+import { BasicMultiplex, BasicSet, Diagnostic, isIpNetworkChannel, Lifetime, Logger, MaybePromise } from "#general";
+import type { MdnsClient } from "#mdns/MdnsClient.js";
+import type { NodeSession } from "#session/NodeSession.js";
+import type { SecureSession } from "#session/SecureSession.js";
+import type { SessionManager } from "#session/SessionManager.js";
+import { ObservablePeerDescriptor, PeerDescriptor } from "./PeerDescriptor.js";
+import type { NodeDiscoveryType } from "./PeerSet.js";
+
+const logger = Logger.get("Peer");
+
+/**
+ * A node on a fabric we are a member of.
+ */
+export class Peer {
+    #lifetime: Lifetime;
+    #descriptor: PeerDescriptor;
+    #context: Peer.Context;
+    #sessions = new BasicSet<NodeSession>();
+    #workers: BasicMultiplex;
+    #isSaving = false;
+    #limits: BasicInformation.CapabilityMinima = {
+        caseSessionsPerFabric: 3,
+        subscriptionsPerFabric: 3,
+    };
+
+    // TODO - manage these internally and/or factor away
+    activeDiscovery?: Peer.ActiveDiscovery;
+    activeReconnection?: Peer.ActiveReconnection;
+
+    constructor(descriptor: PeerDescriptor, context: Peer.Context) {
+        this.#lifetime = context.lifetime.join(descriptor.address.toString());
+        this.#workers = new BasicMultiplex();
+
+        this.#descriptor = new ObservablePeerDescriptor(descriptor, () => {
+            if (this.#isSaving) {
+                return;
+            }
+
+            this.#isSaving = true;
+            this.#workers.add(this.#save());
+        });
+        this.#context = context;
+
+        this.#sessions.added.on(session => {
+            // Remove channel when destroyed
+            session.closing.on(() => {
+                this.#sessions.delete(session);
+            });
+
+            // Ensure operational address is always the most recent IP
+            const { channel } = session.channel;
+            if (isIpNetworkChannel(channel)) {
+                this.#descriptor.operationalAddress = channel.networkAddress;
+            }
+        });
+    }
+
+    get fabric() {
+        return this.#context.sessions.fabricFor(this.address);
+    }
+
+    get limits() {
+        return this.#limits;
+    }
+
+    set limits(limits: BasicInformation.CapabilityMinima) {
+        this.#limits = limits;
+    }
+
+    get address() {
+        return this.#descriptor.address;
+    }
+
+    get descriptor() {
+        return this.#descriptor;
+    }
+
+    get sessions() {
+        return this.#sessions;
+    }
+
+    /**
+     * Permanently forget the peer.
+     */
+    async delete() {
+        logger.info("Removing", Diagnostic.strong(this.toString()));
+        await this.close();
+        await this.#context.deletePeer(this);
+        await this.#context.sessions.deleteResumptionRecord(this.address);
+    }
+
+    /**
+     * Close the peer without removing persistent state.
+     */
+    async close() {
+        using _lifetime = this.#lifetime.closing();
+
+        if (this.activeDiscovery) {
+            this.activeDiscovery.stopTimerFunc?.();
+
+            // This ends discovery without triggering promises
+            this.activeDiscovery.mdnsClient?.cancelOperationalDeviceDiscovery(this.fabric, this.address.nodeId, false);
+
+            this.activeDiscovery = undefined;
+        }
+
+        if (this.activeReconnection) {
+            this.activeReconnection.rejecter("Peer closed");
+            this.activeReconnection = undefined;
+        }
+
+        for (const session of this.#context.sessions.sessionsFor(this.address)) {
+            await session.initiateClose();
+        }
+
+        await this.#workers;
+
+        this.#context.closed(this);
+    }
+
+    toString() {
+        return this.address.toString();
+    }
+
+    async #save() {
+        using _lifetime = this.#lifetime.join("saving");
+        this.#isSaving = false;
+        await this.#context.savePeer(this);
+    }
+}
+
+export namespace Peer {
+    export interface Context {
+        lifetime: Lifetime.Owner;
+        sessions: SessionManager;
+        savePeer(peer: Peer): MaybePromise<void>;
+        deletePeer(peer: Peer): MaybePromise<void>;
+        closed(peer: Peer): void;
+    }
+
+    // TODO - factor away
+    export interface ActiveDiscovery {
+        type: NodeDiscoveryType;
+        promises?: (() => Promise<SecureSession>)[];
+        stopTimerFunc?: (() => void) | undefined;
+        mdnsClient?: MdnsClient;
+    }
+
+    // TODO - factor away
+    export interface ActiveReconnection {
+        promise: Promise<SecureSession>;
+        rejecter: (reason?: any) => void;
+    }
+}

package/src/peer/PeerAddress.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { DiagnosticPresentation } from "#general";
 import { FabricIndex, GroupId, NodeId } from "#types";
 
 /**
@@ -51,8 +52,11 @@ export function PeerAddress<T extends undefined | PeerAddress>(address: T): T {
             [interned]: true,
 
             toString() {
-                const nodeStr = this.nodeId > 0xffff ? `0x${this.nodeId.toString(16)}` : this.nodeId;
-                return `peer@${this.fabricIndex}:${nodeStr}`;
+                return `@${this.fabricIndex.toString(16)}:${this.nodeId.toString(16)}`;
+            },
+
+            get [DiagnosticPresentation.value]() {
+                return this.toString();
             },
         } as PeerAddress),
     );

package/src/peer/PeerAddressStore.ts

@@ -8,16 +8,16 @@ import { ReadScope } from "#action/client/ReadScope.js";
 import { Construction, MaybePromise } from "#general";
 import { DecodedAttributeReportValue } from "#interaction/AttributeDataDecoder.js";
 import { AttributeId, ClusterId, EndpointNumber, EventNumber } from "#types";
-import { OperationalPeer } from "./OperationalPeer.js";
 import { PeerAddress } from "./PeerAddress.js";
+import { PeerDescriptor } from "./PeerDescriptor.js";
 import type { PeerSet } from "./PeerSet.js";
 
 /**
  * The interface {@link PeerSet} uses for persisting operational information.
  */
 export abstract class PeerAddressStore {
-    abstract loadPeers(): MaybePromise<Iterable<OperationalPeer>>;
-    abstract updatePeer(peer: OperationalPeer): MaybePromise<void>;
+    abstract loadPeers(): MaybePromise<Iterable<PeerDescriptor>>;
+    abstract updatePeer(peer: PeerDescriptor): MaybePromise<void>;
     abstract deletePeer(address: PeerAddress): MaybePromise<void>;
     abstract createNodeStore(address: PeerAddress): MaybePromise<PeerDataStore | undefined>;
 }

package/src/peer/PeerDescriptor.ts

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { DiscoveryData } from "#common/Scanner.js";
+import { isDeepEqual, ServerAddressUdp } from "#general";
+import type { PeerDataStore } from "#peer/PeerAddressStore.js";
+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 PeerDescriptor {
+    /**
+     * The logical address of the peer.
+     */
+    address: PeerAddress;
+
+    /**
+     * A physical address the peer may be accessed at, if known.
+     */
+    operationalAddress?: ServerAddressUdp;
+
+    /**
+     * Additional information collected while locating the peer.
+     */
+    discoveryData?: DiscoveryData;
+
+    /**
+     * The data store for the peer.
+     *
+     * @deprecated
+     */
+    dataStore?: PeerDataStore;
+}
+
+export class ObservablePeerDescriptor implements PeerDescriptor {
+    #address: PeerAddress;
+    #operationalAddress?: ServerAddressUdp;
+    #discoveryData?: DiscoveryData;
+    #dataStore?: PeerDataStore;
+    #onChange: () => void;
+
+    constructor({ address, operationalAddress, discoveryData, dataStore }: PeerDescriptor, onChange: () => void) {
+        this.#address = PeerAddress(address);
+        this.#operationalAddress = operationalAddress;
+        this.#discoveryData = discoveryData;
+        this.#dataStore = dataStore;
+        this.#onChange = onChange;
+    }
+
+    get address() {
+        return this.#address;
+    }
+
+    get operationalAddress() {
+        return this.#operationalAddress;
+    }
+
+    set operationalAddress(value: ServerAddressUdp | undefined) {
+        if (isDeepEqual(this.#operationalAddress, value)) {
+            return;
+        }
+
+        this.#operationalAddress = value;
+        this.#onChange();
+    }
+
+    get discoveryData() {
+        return this.#discoveryData;
+    }
+
+    set discoveryData(value: DiscoveryData | undefined) {
+        if (isDeepEqual(value, this.#discoveryData)) {
+            return;
+        }
+
+        this.#discoveryData = { ...this.#discoveryData, ...value };
+        this.#onChange();
+    }
+
+    get dataStore() {
+        return this.#dataStore;
+    }
+}