@matter/protocol 0.16.0-alpha.0-20250916-d577beb1d → 0.16.0-alpha.0-20250921-b7a3dda23

package/src/bdx/flow/DrivingReceivingFlow.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InboundFlow } from "./InboundFlow.js";
+
+/**
+ * BDX Transport flow logic for a "BDX Driving Receiver":
+ * - Requests the next Blow using BlockQuery and then reads the Block
+ * - Last message is confirmed with an AckEof
+ */
+export class DrivingReceivingFlow extends InboundFlow {
+    async transferNextChunk() {
+        const { writeController } = this.stream;
+
+        const blockCounter = this.nextMessageCounter;
+
+        // Query next block (We never Ack block from before because we are usually never sleepy)
+        // Think about cases to use BlockQueryWithSkip
+        await this.messenger.sendBlockQuery({ blockCounter });
+
+        // Read returned Block
+        const {
+            kind: messageType,
+            message: { blockCounter: dataBlockCounter, data },
+        } = await this.messenger.readBlock();
+        this.validateCounter(dataBlockCounter, blockCounter);
+
+        // Write the received data chunk into the writing stream
+        if (this.writeDataChunk(writeController, data, messageType)) {
+            this.finalBlockCounter = dataBlockCounter;
+            return true;
+        }
+
+        return false;
+    }
+}

package/src/bdx/flow/Flow.ts

@@ -0,0 +1,124 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "#general";
+import { BdxStatusCode } from "#types";
+import { BdxError } from "../BdxError.js";
+import { BdxMessenger } from "../BdxMessenger.js";
+import { PersistedFileDesignator } from "../PersistedFileDesignator.js";
+
+/** Base class for BDX transfer flows. */
+export abstract class Flow {
+    readonly #transferParameters: Flow.TransferOptions;
+    readonly #messenger: BdxMessenger;
+    #isClosed = false;
+    #blockCounter = 0;
+    #bytesLeft?: number;
+    #finalBlockCounter?: number;
+
+    constructor(messenger: BdxMessenger, transferParameters: Flow.TransferOptions) {
+        this.#messenger = messenger;
+        this.#transferParameters = transferParameters;
+        this.#bytesLeft = transferParameters.dataLength;
+    }
+
+    protected get transferParameters(): Flow.TransferOptions {
+        return this.#transferParameters;
+    }
+
+    protected get isClosed() {
+        return this.#isClosed;
+    }
+
+    protected get messenger() {
+        return this.#messenger;
+    }
+
+    protected get bytesLeft(): number | undefined {
+        return this.#bytesLeft;
+    }
+
+    protected set bytesLeft(value: number) {
+        this.#bytesLeft = value;
+    }
+
+    protected set finalBlockCounter(blockCounter: number) {
+        if (this.#finalBlockCounter !== undefined) {
+            throw new InternalError("Transfer already finalized. finalizeTransfer() should only be called once.");
+        }
+        this.#finalBlockCounter = blockCounter;
+    }
+
+    protected get finalBlockCounter() {
+        if (this.#finalBlockCounter === undefined) {
+            throw new InternalError("Transfer not finalized. Call finalizeTransfer() after completing the transfer.");
+        }
+        return this.#finalBlockCounter;
+    }
+
+    /** Determines the next message counter to use for the next message, also handles wrapping around at 2^32. */
+    protected get nextMessageCounter() {
+        this.#blockCounter = (this.#blockCounter + 1) % 0x100000000; // wrap around at 2^32
+        return this.#blockCounter;
+    }
+
+    /** Utility function to check if a block counter is valid */
+    protected validateCounter(messageBlockCounter: number, expectedCounter = this.nextMessageCounter) {
+        if (messageBlockCounter !== expectedCounter) {
+            throw new BdxError(
+                `Received Block with unexpected block counter: ${messageBlockCounter}, expected: ${expectedCounter}`,
+                BdxStatusCode.BadBlockCounter,
+            );
+        }
+        return messageBlockCounter;
+    }
+
+    async close(_error?: unknown) {
+        this.#isClosed = true;
+    }
+
+    /**
+     * Main logic method to execute the flow.
+     * The promise resolves when the flow is complete, or rejects on any error or unexpected conditions.
+     */
+    async processTransfer() {
+        await this.initTransfer();
+
+        // Continue to transfer chunks until done or closed
+        while (!this.isClosed) {
+            if (await this.transferNextChunk()) {
+                break;
+            }
+        }
+
+        if (!this.isClosed) {
+            await this.finalizeTransfer();
+        }
+    }
+
+    protected abstract initTransfer(): Promise<void>;
+
+    protected abstract transferNextChunk(): Promise<boolean>;
+
+    protected abstract finalizeTransfer(): Promise<void>;
+}
+
+export namespace Flow {
+    export interface TransferOptions {
+        transferMode: DriverMode;
+        asynchronousTransfer: false; // Not supported currently, so always false
+        dataLength?: number;
+        startOffset: number;
+        blockSize: number;
+        isDriver: boolean;
+        fileDesignator: PersistedFileDesignator;
+    }
+
+    export enum DriverMode {
+        SenderDrive = "senderDrive",
+        ReceiverDrive = "receiverDrive",
+    }
+}

package/src/bdx/flow/FollowingReceivingFlow.ts

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger } from "#general";
+import { BdxMessageType, BdxStatusCode } from "#types";
+import { BdxMessenger } from "../BdxMessenger.js";
+import { BdxMessage } from "../schema/BdxMessage.js";
+import { OutboundFlow } from "./OutboundFlow.js";
+
+const logger = Logger.get("BdxFollowingReceivingFlow");
+/**
+ * BDX Transport flow logic for a "BDX Following Receiver":
+ * - Reads BlockQuery(WithSkip) messages and responds with Block or (for last block) BlockEof.
+ *   Data are skipped over when requested by the peer.
+ * - After the last block is send it expects an AckEof
+ */
+export class FollowingReceivingFlow extends OutboundFlow {
+    protected async transferNextChunk() {
+        const { iterator, streamReader } = this.stream;
+
+        // Read the data query from the peer
+        const blockQuery = await this.messenger.readBlockQuery();
+        const bytesToSkip = BdxMessage.is(blockQuery, BdxMessageType.BlockQueryWithSkip)
+            ? BdxMessenger.asSafeNumber(
+                  blockQuery.message.bytesToSkip,
+                  "BytesToSkip",
+                  BdxStatusCode.TransferFailedUnknownError,
+              )
+            : 0;
+
+        const { blockCounter } = blockQuery.message;
+        this.validateCounter(blockCounter);
+
+        if (bytesToSkip > 0) {
+            const skipped = await streamReader.skip(bytesToSkip);
+            logger.debug(`Skipped ${skipped}bytes of data (requested ${bytesToSkip}bytes)`);
+        }
+        const { data, done } = await this.readDataChunk(iterator);
+
+        if (done) {
+            await this.messenger.sendBlockEof({ data, blockCounter });
+            this.finalBlockCounter = blockCounter;
+            return true;
+        }
+
+        await this.messenger.sendBlock({ data, blockCounter });
+        // Ack or next BlockQuery is read on the next iteration
+        return false;
+    }
+}

package/src/bdx/flow/FollowingSendingFlow.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InboundFlow } from "./InboundFlow.js";
+
+/**
+ * BDX Transport flow logic for a "BDX Following Sender":
+ * - Reads the Block and sends an Ack (if synchronous transfer is used)
+ * - Last message is confirmed with an AckEof
+ */
+export class FollowingSendingFlow extends InboundFlow {
+    protected async transferNextChunk() {
+        const { asynchronousTransfer } = this.transferParameters;
+        const { writeController } = this.stream;
+
+        const {
+            kind: messageType,
+            message: { data, blockCounter },
+        } = await this.messenger.readBlock();
+        this.validateCounter(blockCounter);
+
+        // Write the received data chunk into the writing stream
+        if (this.writeDataChunk(writeController, data, messageType)) {
+            this.finalBlockCounter = blockCounter;
+            return true;
+        }
+
+        if (!asynchronousTransfer) {
+            // Sync transfer just requires Ack to be sent back
+            await this.messenger.sendBlockAck({ blockCounter });
+        }
+
+        return false;
+    }
+}

package/src/bdx/flow/InboundFlow.ts

@@ -0,0 +1,104 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, InternalError, MaybePromise } from "#general";
+import { BdxMessageType, BdxStatusCode } from "#types";
+import { BdxError } from "../BdxError.js";
+import { Flow } from "./Flow.js";
+
+/**
+ * Base class for inbound BDX transfer flows where data is received from the peer and written to our node.
+ */
+export abstract class InboundFlow extends Flow {
+    #closeStreams?: (error?: unknown) => Promise<void>;
+    #writeController?: ReadableStreamDefaultController<Bytes>;
+    #writePromise?: MaybePromise<void>;
+
+    /**
+     * Returns initialized streams for the transfer and initializes the #closeStream class function
+     */
+    protected async initTransfer() {
+        // Create a ReadableStream that we can write to and start to write the data into the blob
+        let writeController!: ReadableStreamDefaultController<Bytes>; // variable is set on creation of the ReadableStream
+        const stream = new ReadableStream<Bytes>({
+            start: controller => {
+                writeController = controller;
+            },
+        });
+        const { fileDesignator } = this.transferParameters;
+        const writePromise = fileDesignator.writeFromStream(stream);
+
+        // Method to be used by main close() method to make sure all streams are correctly closed or cancelled
+        this.#closeStreams = async (error?: unknown) => {
+            if (writeController !== undefined) {
+                if (error != undefined) {
+                    // When this is called, we are either done successfully or failed, error the write controller in error case
+                    writeController.error(error);
+                    try {
+                        await writePromise;
+                    } catch {
+                        // Ignore the error because we generated it
+                    }
+                }
+            }
+            // When writing and errored the stream might stay locked, so we cannot cancel it without an exception
+            if (!stream.locked) {
+                await stream.cancel();
+            }
+        };
+
+        this.#writeController = writeController;
+        this.#writePromise = writePromise;
+    }
+
+    protected get stream() {
+        if (!this.#writeController || !this.#writePromise) {
+            throw new InternalError("Transfer not initialized. Call initTransfer() before starting the transfer.");
+        }
+        return { writeController: this.#writeController, writePromise: this.#writePromise };
+    }
+
+    protected async finalizeTransfer() {
+        const { writePromise } = this.stream;
+        const blockCounter = this.finalBlockCounter;
+        await writePromise;
+        await this.messenger.sendBlockAckEof({ blockCounter });
+    }
+
+    protected writeDataChunk(
+        writeController: ReadableStreamDefaultController<Bytes>,
+        data: Bytes,
+        messageType: BdxMessageType,
+    ) {
+        // Enqueue the received data chunk into the writing stream
+        writeController.enqueue(data);
+        if (this.bytesLeft !== undefined) {
+            this.bytesLeft -= data.byteLength;
+        }
+
+        let done = false;
+
+        // Last block received
+        if (messageType === BdxMessageType.BlockEof) {
+            if (this.bytesLeft !== undefined && this.bytesLeft !== 0) {
+                throw new BdxError(
+                    `Received BlockEof with ${this.bytesLeft}bytes left, but no more data available`,
+                    this.bytesLeft > 0 ? BdxStatusCode.LengthTooShort : BdxStatusCode.LengthTooLarge,
+                );
+            }
+
+            done = true;
+            writeController.close();
+        }
+
+        return done;
+    }
+
+    override async close(error?: unknown) {
+        await super.close(error);
+        await this.#closeStreams?.(error);
+    }
+}

package/src/bdx/flow/OutboundFlow.ts

@@ -0,0 +1,124 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { BytesStreamReader, InternalError } from "#general";
+import { BdxStatusCode } from "#types";
+import { BdxError } from "../BdxError.js";
+import { Flow } from "./Flow.js";
+
+/**
+ * Base class for outbound BDX transfer flows where data is read from our node and sent to the peer.
+ */
+export abstract class OutboundFlow extends Flow {
+    #closeStreams?: (error?: unknown) => Promise<void>;
+    #iterator?: AsyncGenerator<Uint8Array<ArrayBufferLike>, void, unknown>;
+    #streamReader?: BytesStreamReader;
+
+    protected get stream() {
+        if (this.#iterator === undefined || this.#streamReader === undefined) {
+            throw new InternalError("Read stream not initialized");
+        }
+        return { iterator: this.#iterator, streamReader: this.#streamReader };
+    }
+
+    /**
+     * Returns initialized streams for the transfer and initializes the #closeStream class function
+     */
+    protected async initTransfer() {
+        const { blockSize } = this.transferParameters;
+
+        const blob = await this.transferParameters.fileDesignator.openBlob();
+        const blobSize = blob.size;
+
+        // Get the full or relevant part of the stream by startOffset and length
+        const { startOffset = 0, dataLength = blobSize } = this.transferParameters;
+
+        const dataBlob =
+            startOffset > 0 || dataLength !== blobSize ? blob.slice(startOffset, startOffset + dataLength) : blob;
+
+        const stream = dataBlob.stream();
+
+        const reader = stream.getReader();
+        // Method to be used by main close() method to make sure all streams are correctly closed or cancelled
+        this.#closeStreams = async (_error?: unknown) => {
+            if (stream.locked) {
+                reader?.releaseLock();
+                try {
+                    await reader?.cancel();
+                } catch (error) {
+                    // A TypeError is expected when the stream is already cancelled, so we ignore it
+                    if (!(error instanceof TypeError)) {
+                        throw error;
+                    }
+                }
+            }
+            await stream.cancel();
+        };
+
+        const streamReader = new BytesStreamReader(reader);
+        this.#iterator = streamReader.read(blockSize);
+        this.#streamReader = streamReader;
+    }
+
+    /**
+     * Reads one data chunk from the reader and does some basic checks.
+     */
+    protected async readDataChunk(reader: AsyncGenerator<Uint8Array<ArrayBufferLike>, void, unknown>) {
+        const { blockSize, dataLength } = this.transferParameters;
+        let { value, done = false } = await reader.next();
+        if (value === undefined) {
+            // Done needs to be true when value is undefined or there is something broken
+            if (!done) {
+                throw new BdxError(
+                    `Data length too short, expected ${blockSize}bytes, but got less`,
+                    BdxStatusCode.LengthTooShort,
+                );
+            }
+            value = new Uint8Array(); // Simulate an empty value when we reached the end of the stream
+        } else if (value.byteLength < blockSize) {
+            // When we get less data than blocksize it is the last block, so validate that
+            ({ done = false } = await reader.next());
+            if (!done) {
+                throw new BdxError(
+                    `Data length too short, expected ${blockSize}bytes, but got less`,
+                    BdxStatusCode.LengthTooShort,
+                );
+            }
+        }
+
+        if (this.bytesLeft !== undefined && dataLength !== undefined) {
+            this.bytesLeft -= value.byteLength;
+            if (this.bytesLeft < 0) {
+                throw new BdxError(
+                    `Data length exceeded, expected ${dataLength}bytes, but got ${-this.bytesLeft}bytes more`,
+                    BdxStatusCode.LengthTooLarge,
+                );
+            }
+            if (done && this.bytesLeft > 0) {
+                throw new BdxError(
+                    `Data length too short, expected ${dataLength}bytes, but got ${this.bytesLeft}bytes less`,
+                    BdxStatusCode.LengthTooShort,
+                );
+            }
+            if (this.bytesLeft === 0) {
+                done = true;
+            }
+        }
+
+        return { data: value, done };
+    }
+
+    protected async finalizeTransfer() {
+        const blockCounter = this.finalBlockCounter;
+        const { blockCounter: ackedBlockCounter } = await this.messenger.readBlockAckEof();
+        this.validateCounter(ackedBlockCounter, blockCounter);
+    }
+
+    override async close(error?: unknown) {
+        await super.close(error);
+        await this.#closeStreams?.(error);
+    }
+}

package/src/bdx/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./BdxClient.js";
+export * from "./BdxError.js";
+export * from "./BdxMessenger.js";
+export * from "./BdxProtocol.js";
+export * from "./BdxSession.js";
+export * from "./BdxSessionConfiguration.js";
+export * from "./FileDesignator.js";
+export * from "./flow/Flow.js";
+export * from "./PersistedFileDesignator.js";
+export * from "./schema/index.js";

package/src/bdx/schema/BdxAcceptMessagesSchema.ts

@@ -0,0 +1,159 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, DataReader, DataWriter, Endian } from "#general";
+import { BdxStatusCode, Schema, TypeFromPartialBitSchema } from "#types";
+import { BdxError } from "../BdxError.js";
+import {
+    BDX_VERSION,
+    BdxRangeControlSchema,
+    BdxTransferControlBitmap,
+    BdxTransferControlSchema,
+} from "./BdxInitMessagesSchema.js";
+
+/** @see {@link MatterSpecification.v141.Core}, section 11.22.5.2 */
+export interface BdxSendAccept {
+    /**
+     * Transfer control details
+     * TC
+     * 1 octet
+     */
+    transferControl: TypeFromPartialBitSchema<typeof BdxTransferControlBitmap>;
+
+    /**
+     * Specifies the maximum data size (in bytes) of the block that the Initiator supports, exclusive of block header
+     * fields, such as a block counter.
+     * MBS, 2 octets
+     */
+    maxBlockSize: number;
+
+    /**
+     * Allows the Initiator to send additional application-specific information about the file to be transferred
+     * MD, Variable length, TLV
+     */
+    metaData?: Bytes;
+}
+
+/** @see {@link MatterSpecification.v141.Core}, section 11.22.5.3 */
+export interface BdxReceiveAccept extends BdxSendAccept {
+    /**
+     * Specifies a predetermined definite length for the transfer
+     * DEFLEN, 4/8 octets
+     */
+    length?: number | bigint;
+}
+
+/** Schema for BDX SendAccept message */
+export class BdxSendAcceptMessageSchema<M extends BdxSendAccept> extends Schema<M> {
+    encodeInternal(message: M) {
+        this.validate(message);
+        const { transferControl, maxBlockSize, metaData } = message;
+
+        const writer = new DataWriter(Endian.Little);
+        writer.writeUInt8(BdxTransferControlSchema.encode(transferControl));
+        writer.writeUInt16(maxBlockSize);
+
+        if (metaData && metaData.byteLength > 0) {
+            writer.writeByteArray(metaData);
+        }
+
+        return writer.toByteArray();
+    }
+
+    decodeInternal(bytes: Bytes): M {
+        const reader = new DataReader(bytes, Endian.Little);
+        const transferControl = BdxTransferControlSchema.decode(reader.readUInt8());
+        const maxBlockSize = reader.readUInt16();
+
+        const metaData = reader.remainingBytesCount > 0 ? reader.remainingBytes : undefined;
+
+        const result = {
+            transferControl,
+            maxBlockSize,
+            metaData,
+        } as M;
+        this.validate(result);
+        return result;
+    }
+
+    override validate({ transferControl, maxBlockSize }: M) {
+        if (transferControl.version !== BDX_VERSION) {
+            throw new BdxError(
+                `Unsupported BDX version: ${transferControl.version}`,
+                BdxStatusCode.VersionNotSupported,
+            );
+        }
+        if (!transferControl.senderDrive && !transferControl.receiverDrive && !transferControl.asynchronousTransfer) {
+            throw new BdxError(
+                "BDX transfer control need to specify at least one of sender drive, receiver drive or asynchronousTransfer",
+                BdxStatusCode.BadMessageContent,
+            );
+        }
+        if (maxBlockSize < 1 || maxBlockSize > 0xffff) {
+            throw new BdxError("Max Block Size must be between 1 and 65535bytes", BdxStatusCode.BadMessageContent);
+        }
+    }
+}
+export const BdxSendAcceptMessage = new BdxSendAcceptMessageSchema();
+
+/** Schema for Bdx ReceiveAccept message */
+export class BdxReceiveAcceptMessageSchema extends BdxSendAcceptMessageSchema<BdxReceiveAccept> {
+    override encodeInternal(message: BdxReceiveAccept) {
+        this.validate(message);
+        const { transferControl, maxBlockSize, metaData, length } = message;
+
+        const rangeControl = {
+            definiteLength: length !== undefined && length !== 0,
+            wideRange: typeof length === "bigint",
+        };
+
+        const writer = new DataWriter(Endian.Little);
+        writer.writeUInt8(BdxTransferControlSchema.encode(transferControl));
+        writer.writeUInt8(BdxRangeControlSchema.encode(rangeControl));
+        writer.writeUInt16(maxBlockSize);
+
+        if (length !== undefined && length !== 0) {
+            if (rangeControl.wideRange) {
+                writer.writeUInt64(length);
+            } else {
+                writer.writeUInt32(length);
+            }
+        }
+
+        if (metaData && metaData.byteLength > 0) {
+            writer.writeByteArray(metaData);
+        }
+
+        return writer.toByteArray();
+    }
+
+    override decodeInternal(bytes: Bytes): BdxReceiveAccept {
+        const reader = new DataReader(bytes, Endian.Little);
+        const transferControl = BdxTransferControlSchema.decode(reader.readUInt8());
+        const rangeControl = BdxRangeControlSchema.decode(reader.readUInt8());
+        const maxBlockSize = reader.readUInt16();
+
+        let length = rangeControl.definiteLength
+            ? rangeControl.wideRange
+                ? reader.readUInt64()
+                : reader.readUInt32()
+            : undefined;
+        if (length === 0) {
+            length = undefined; // 0 also means indefinite length
+        }
+        const metaData = reader.remainingBytesCount > 0 ? reader.remainingBytes : undefined;
+
+        const result = {
+            transferControl,
+            maxBlockSize,
+            metaData,
+            length,
+        };
+        this.validate(result);
+        return result;
+    }
+}
+export const BdxReceiveAcceptMessage = new BdxReceiveAcceptMessageSchema();