@matter/protocol 0.16.0-alpha.0-20250913-0bc2515df → 0.16.0-alpha.0-20250920-809524dba

package/src/bdx/schema/BdxInitMessagesSchema.ts

@@ -0,0 +1,213 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, DataReader, DataWriter, Endian } from "#general";
+import { BdxStatusCode, BitField, BitFlag, BitmapSchema, Schema, TypeFromPartialBitSchema } from "#types";
+import { BdxError } from "../BdxError.js";
+
+export const BDX_VERSION = 0;
+
+/**
+ * BDX Transfer protocol bitmap definition
+ * Bit 7 is reserved for future use
+ *
+ * @see {@link MatterSpecification.v141.Core}, section 11.22.5.1
+ */
+export const BdxTransferControlBitmap = {
+    /** Protocol Version, Only allowed version is 0.0 for now */
+    version: BitField(0, 4),
+
+    /** Indicates if Sender drive is supported by Initiator */
+    senderDrive: BitFlag(4),
+
+    /** Indicates if Receiver drive is supported by Initiator */
+    receiverDrive: BitFlag(5),
+
+    /**
+     * Indicates if Asynchronous Transfer is supported by Initiator
+     * Synchronous mode is always implicitly supported.
+     */
+    asynchronousTransfer: BitFlag(6),
+};
+export const BdxTransferControlSchema = BitmapSchema(BdxTransferControlBitmap);
+
+/**
+ * BDX Range control bitmap definition
+ * Bits 2-3 and 5-7 is reserved for future use
+ *
+ * @see {@link MatterSpecification.v141.Core}, section 11.22.5.1
+ */
+export const BdxRangeControlBitmap = {
+    /** Indicates if the transfer has a definite length */
+    definiteLength: BitFlag(0),
+
+    /** Indicates if the transfer has a start offset */
+    startOffset: BitFlag(1),
+
+    /**
+     * Indicates if wide (64-bit) range enabled for values
+     * Offset (STARTFOFS) and length (DEFLEN) are 4 octets (32-bit) little-endian unsigned quantities.
+     */
+    wideRange: BitFlag(4),
+};
+export const BdxRangeControlSchema = BitmapSchema(BdxRangeControlBitmap);
+
+/** @see {@link MatterSpecification.v141.Core}, section 11.22.5.1 */
+export type BdxInit = {
+    /**
+     * Transfer protocol details
+     * PTC
+     * 1 octet
+     */
+    transferProtocol: TypeFromPartialBitSchema<typeof BdxTransferControlBitmap>;
+
+    /**
+     * Range Control details - Removed because it is used by encoding/decoding implicitly
+     * RTC, 1 octet
+     */
+    //rangeControl: TypeFromPartialBitSchema<typeof BdxRangeControlBitmap>;
+
+    /**
+     * Specifies the maximum data size (in bytes) of the block that the Initiator supports, exclusive of block header
+     * fields, such as a block counter.
+     * PMBS, 2 octets
+     */
+    maxBlockSize: number;
+
+    /**
+     * Optional 32-bit/64-bit length that specifies the offset in bytes from start of the file from which the Sender
+     * would start the transfer.
+     * STARTOFS, 4/8 octets
+     */
+    startOffset?: number | bigint;
+
+    /**
+     * Specifies a predetermined definite length for the transfer
+     * DEFLEN, 4/8 octets
+     */
+    maxLength?: number | bigint;
+
+    /**
+     * Identifier chosen by the Initiator to identify the payload to be transferred.
+     * FD, 2 octets + Variable length
+     */
+    fileDesignator: Bytes;
+
+    /**
+     * Allows the Initiator to send additional application-specific information about the file to be transferred
+     * MD, Variable length, TLV
+     */
+    metaData?: Bytes;
+};
+
+/** Schema for BDX SendInit and ReceiveInit messages. */
+export class BdxInitMessageSchema extends Schema<BdxInit> {
+    encodeInternal(message: BdxInit) {
+        this.validate(message);
+        const { transferProtocol, maxBlockSize, startOffset, maxLength, fileDesignator, metaData } = message;
+
+        const rangeControl = {
+            startOffset: startOffset !== undefined,
+            definiteLength: maxLength !== undefined && maxLength !== 0,
+            wideRange: typeof startOffset === "bigint" || typeof maxLength === "bigint",
+        };
+
+        const writer = new DataWriter(Endian.Little);
+        writer.writeUInt8(BdxTransferControlSchema.encode(transferProtocol));
+        writer.writeUInt8(BdxRangeControlSchema.encode(rangeControl));
+        writer.writeUInt16(maxBlockSize);
+
+        if (startOffset !== undefined) {
+            if (rangeControl.wideRange) {
+                writer.writeUInt64(startOffset);
+            } else {
+                writer.writeUInt32(startOffset);
+            }
+        }
+        if (maxLength !== undefined && maxLength !== 0) {
+            if (rangeControl.wideRange) {
+                writer.writeUInt64(maxLength);
+            } else {
+                writer.writeUInt32(maxLength);
+            }
+        }
+
+        writer.writeUInt16(fileDesignator.byteLength);
+        writer.writeByteArray(fileDesignator);
+
+        if (metaData && metaData.byteLength > 0) {
+            writer.writeByteArray(metaData);
+        }
+
+        return writer.toByteArray();
+    }
+
+    decodeInternal(bytes: Bytes): BdxInit {
+        const reader = new DataReader(bytes, Endian.Little);
+        const transferProtocol = BdxTransferControlSchema.decode(reader.readUInt8());
+        const rangeControl = BdxRangeControlSchema.decode(reader.readUInt8());
+        const maxBlockSize = reader.readUInt16();
+
+        const startOffset = rangeControl.startOffset
+            ? rangeControl.wideRange
+                ? reader.readUInt64()
+                : reader.readUInt32()
+            : undefined;
+        let maxLength = rangeControl.definiteLength
+            ? rangeControl.wideRange
+                ? reader.readUInt64()
+                : reader.readUInt32()
+            : undefined;
+        if (maxLength === 0) {
+            maxLength = undefined; // 0 also means indefinite length
+        }
+
+        const fileDesignatorLength = reader.readUInt16();
+        const fileDesignator = reader.readByteArray(fileDesignatorLength);
+
+        const metaData = reader.remainingBytesCount > 0 ? reader.remainingBytes : undefined;
+
+        const result = {
+            transferProtocol,
+            maxBlockSize,
+            startOffset,
+            maxLength,
+            fileDesignator,
+            metaData,
+        };
+        this.validate(result);
+        return result;
+    }
+
+    override validate({ transferProtocol, maxBlockSize, fileDesignator }: BdxInit) {
+        if (transferProtocol.version !== BDX_VERSION) {
+            throw new BdxError(
+                `Unsupported BDX version: ${transferProtocol.version}`,
+                BdxStatusCode.VersionNotSupported,
+            );
+        }
+        if (!transferProtocol.senderDrive && !transferProtocol.receiverDrive) {
+            throw new BdxError(
+                "BDX transfer protocol needs to allow either sender or receiver drive",
+                BdxStatusCode.BadMessageContent,
+            );
+        }
+        if (fileDesignator.byteLength === 0) {
+            throw new BdxError("File Designator cannot be empty", BdxStatusCode.BadMessageContent);
+        }
+        if (fileDesignator.byteLength > 0xffff) {
+            throw new BdxError(
+                "File Designator length exceeds maximum allowed size of 65535bytes",
+                BdxStatusCode.BadMessageContent,
+            );
+        }
+        if (maxBlockSize < 1 || maxBlockSize > 0xffff) {
+            throw new BdxError("Max Block Size must be between 1 and 65535bytes", BdxStatusCode.BadMessageContent);
+        }
+    }
+}
+export const BdxSendInitMessage = new BdxInitMessageSchema();
+export const BdxReceiveInitMessage = BdxSendInitMessage;

package/src/bdx/schema/BdxMessage.ts

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, InternalError } from "#general";
+import { BdxMessageType, Schema, SchemaType } from "#types";
+import { BdxReceiveAcceptMessage, BdxSendAcceptMessage } from "./BdxAcceptMessagesSchema.js";
+import {
+    BdxBlockAckEofMessage,
+    BdxBlockAckMessage,
+    BdxBlockEofMessage,
+    BdxBlockMessage,
+    BdxBlockQueryMessage,
+    BdxBlockQueryWithSkipMessage,
+} from "./BdxBlockMessagesSchema.js";
+import { BdxReceiveInitMessage, BdxSendInitMessage } from "./BdxInitMessagesSchema.js";
+
+export interface BdxMessage<T extends BdxMessageType> {
+    kind: T;
+    message: SchemaType<BdxMessage.Kinds[T]>;
+}
+
+/** Convenient wrapper around BDX message encoding/decoding and type guards. */
+export namespace BdxMessage {
+    export function encode<T extends BdxMessageType>({ kind, message }: BdxMessage<T>) {
+        if (!(kind in Kinds)) {
+            throw new InternalError(`Can not encode unknown BDX message type: ${kind}`);
+        }
+        return Kinds[kind].encode(message);
+    }
+
+    export function decode<T extends BdxMessageType>(kind: T, payload: Bytes): BdxMessage<T> {
+        if (!(kind in Kinds)) {
+            throw new InternalError(`Can not decode unknown BDX message type: ${kind}`);
+        }
+        return { kind, message: Kinds[kind].decode(payload) };
+    }
+
+    export function is<T extends BdxMessageType>(message: BdxMessage<any>, kind: T): message is BdxMessage<T> {
+        return message.kind === kind;
+    }
+
+    export function assert<T extends BdxMessageType>(
+        message: BdxMessage<any>,
+        kind: T,
+    ): asserts message is BdxMessage<T> {
+        if (message.kind !== kind) {
+            throw new InternalError(
+                `Expected BDX message of type ${BdxMessageType[kind]}, but got ${BdxMessageType[message.kind]}(${message.kind})`,
+            );
+        }
+    }
+
+    export const Kinds: { [key: number]: Schema<any> } = {
+        [BdxMessageType.SendInit]: BdxSendInitMessage,
+        [BdxMessageType.ReceiveInit]: BdxReceiveInitMessage,
+        [BdxMessageType.SendAccept]: BdxSendAcceptMessage,
+        [BdxMessageType.ReceiveAccept]: BdxReceiveAcceptMessage,
+        [BdxMessageType.BlockQuery]: BdxBlockQueryMessage,
+        [BdxMessageType.BlockQueryWithSkip]: BdxBlockQueryWithSkipMessage,
+        [BdxMessageType.Block]: BdxBlockMessage,
+        [BdxMessageType.BlockEof]: BdxBlockEofMessage,
+        [BdxMessageType.BlockAck]: BdxBlockAckMessage,
+        [BdxMessageType.BlockAckEof]: BdxBlockAckEofMessage,
+    } as const;
+
+    export type Kinds = typeof Kinds;
+}

package/src/bdx/schema/BdxStatusMessageSchema.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ProtocolStatusMessage, ProtocolStatusMessageSchema } from "#protocol/ProtocolStatusMessage.js";
+import { BDX_PROTOCOL_ID, BdxStatusCode } from "#types";
+
+export type BdxStatus = Omit<ProtocolStatusMessage<BdxStatusCode>, "protocolData">;
+
+export class BdxStatusMessageSchema extends ProtocolStatusMessageSchema<BdxStatus> {}
+
+export const BdxStatusMessage = new BdxStatusMessageSchema(BDX_PROTOCOL_ID, false);

package/src/bdx/schema/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./BdxAcceptMessagesSchema.js";
+export * from "./BdxBlockMessagesSchema.js";
+export * from "./BdxInitMessagesSchema.js";
+export * from "./BdxMessage.js";
+export * from "./BdxStatusMessageSchema.js";

package/src/index.ts

@@ -6,6 +6,7 @@
 
 export * from "./action/index.js";
 export * from "./advertisement/index.js";
+export * from "./bdx/index.js";
 export * from "./ble/index.js";
 export * from "./certificate/index.js";
 export * from "./cluster/index.js";

package/src/mdns/MdnsClient.ts

@@ -1402,13 +1402,13 @@ export class MdnsClient implements Scanner {
                 if (key === undefined || value === undefined) continue;
                 if (["T", "D", "CM", "DT", "PH", "ICD"].includes(key)) {
                     const intValue = parseInt(value);
-                    if (isNaN(intValue)) continue;
+                    if (!Number.isFinite(intValue)) continue;
                     result[key] = intValue;
                 } else if (["VP", "DN", "RI", "PI"].includes(key)) {
                     result[key] = value;
                 } else if (["SII", "SAI", "SAT"].includes(key)) {
                     const intValue = parseInt(value);
-                    if (isNaN(intValue)) continue;
+                    if (!Number.isFinite(intValue)) continue;
                     result[key] = intValue;
                     result[key] = Millis(intValue);
                 }

package/src/protocol/ExchangeManager.ts

@@ -242,6 +242,7 @@ export class ExchangeManager {
                 );
                 await exchange.send(SecureMessageType.StandaloneAck, new Uint8Array(0), {
                     includeAcknowledgeMessageId: message.packetHeader.messageId,
+                    protocolId: SECURE_CHANNEL_PROTOCOL_ID,
                 });
                 await exchange.close();
                 return;
@@ -294,6 +295,7 @@ export class ExchangeManager {
                 this.#addExchange(exchangeIndex, exchange);
                 await exchange.send(SecureMessageType.StandaloneAck, new Uint8Array(0), {
                     includeAcknowledgeMessageId: message.packetHeader.messageId,
+                    protocolId: SECURE_CHANNEL_PROTOCOL_ID,
                 });
                 await exchange.close();
                 logger.debug(

package/src/protocol/MessageExchange.ts

@@ -88,6 +88,11 @@ export type ExchangeSendOptions = {
 
     /** Additional context information for logging to be included at the beginning of the Message log. */
     logContext?: ExchangeLogContext;
+
+    // TODO Restructure exchange logic to not be protocol bound like now. The Protocol binding should move to the
+    //  messages itself
+    /** Allows to override the protocol ID of the message, mainly used for standalone acks. */
+    protocolId?: number;
 };
 
 /**
@@ -264,7 +269,10 @@ export class MessageExchange {
         } = message;
         if (!requiresAck || !this.channel.usesMrp) return;
 
-        await this.send(SecureMessageType.StandaloneAck, new Uint8Array(0), { includeAcknowledgeMessageId: messageId });
+        await this.send(SecureMessageType.StandaloneAck, new Uint8Array(0), {
+            includeAcknowledgeMessageId: messageId,
+            protocolId: SECURE_CHANNEL_PROTOCOL_ID,
+        });
     }
 
     async onMessageReceived(message: Message, duplicate = false) {
@@ -360,11 +368,14 @@ export class MessageExchange {
             requiresAck,
             includeAcknowledgeMessageId,
             logContext,
+            protocolId = this.#protocolId,
         } = options ?? {};
         if (!this.channel.usesMrp && includeAcknowledgeMessageId !== undefined) {
             throw new InternalError("Cannot include an acknowledge message ID when MRP is not used");
         }
-        if (messageType === SecureMessageType.StandaloneAck) {
+        const isStandaloneAck = SecureMessageType.isStandaloneAck(protocolId, messageType);
+
+        if (isStandaloneAck) {
             if (!this.channel.usesMrp) {
                 return;
             }
@@ -372,8 +383,9 @@ export class MessageExchange {
                 throw new MatterFlowError("A standalone ack may not require acknowledgement.");
             }
         }
-        if (this.#sentMessageToAck !== undefined && messageType !== SecureMessageType.StandaloneAck)
+        if (this.#sentMessageToAck !== undefined && !isStandaloneAck) {
             throw new MatterFlowError("The previous message has not been acked yet, cannot send a new message.");
+        }
 
         this.#used = true;
         this.session.notifyActivity(false);
@@ -426,11 +438,10 @@ export class MessageExchange {
             packetHeader,
             payloadHeader: {
                 exchangeId: this.#exchangeId,
-                protocolId:
-                    messageType === SecureMessageType.StandaloneAck ? SECURE_CHANNEL_PROTOCOL_ID : this.#protocolId,
+                protocolId,
                 messageType,
                 isInitiatorMessage: this.isInitiator,
-                requiresAck: requiresAck ?? (this.channel.usesMrp && messageType !== SecureMessageType.StandaloneAck),
+                requiresAck: requiresAck ?? (this.channel.usesMrp && !isStandaloneAck),
                 ackedMessageId,
                 hasSecuredExtension: false,
             },

package/src/protocol/ProtocolStatusMessage.ts

@@ -15,7 +15,7 @@ export type ProtocolStatusMessage<T> = {
     protocolData?: Bytes;
 };
 
-export abstract class ProtocolStatusMessageSchema<T extends ProtocolStatusMessage<any>> extends Schema<T, Bytes> {
+export abstract class ProtocolStatusMessageSchema<T extends ProtocolStatusMessage<any>> extends Schema<T> {
     #protocolId: number;
     #vendorId: number;
     #protocolSpecificDataAllowed: boolean;