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

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();

package/src/bdx/schema/BdxBlockMessagesSchema.ts

@@ -0,0 +1,99 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, DataReader, DataWriter, Endian } from "#general";
+import { Schema } from "#types";
+
+interface BdxCounterOnly {
+    blockCounter: number;
+}
+
+/** @see {@link MatterSpecification.v141.Core}, section 11.22.6.2 */
+export interface BdxBlockQuery extends BdxCounterOnly {}
+
+/** @see {@link MatterSpecification.v141.Core}, section 11.22.6.6 */
+export interface BdxBlockAck extends BdxCounterOnly {}
+
+/** @see {@link MatterSpecification.v141.Core}, section 11.22.6.7 */
+export interface BdxBlockAckEof extends BdxCounterOnly {}
+
+/** @see {@link MatterSpecification.v141.Core}, section 11.22.6.3 */
+export interface BdxBlockQueryWithSkip extends BdxCounterOnly {
+    bytesToSkip: number | bigint;
+}
+
+/** @see {@link MatterSpecification.v141.Core}, section 11.22.6.4 */
+export interface BdxBlock extends BdxCounterOnly {
+    data: Bytes;
+}
+
+/** @see {@link MatterSpecification.v141.Core}, section 11.22.6.5 */
+export interface BdxBlockEof extends BdxBlock {}
+
+/** Schema for BDX messages that only contain a block counter: BlockQuery, BlockAck, BlockAckEof. */
+export class BdxCounterOnlyMessageSchema extends Schema<BdxCounterOnly> {
+    encodeInternal(message: BdxCounterOnly) {
+        const { blockCounter } = message;
+
+        const writer = new DataWriter(Endian.Little);
+        writer.writeUInt32(blockCounter);
+        return writer.toByteArray();
+    }
+
+    decodeInternal(bytes: Bytes): BdxCounterOnly {
+        const reader = new DataReader(bytes, Endian.Little);
+        return {
+            blockCounter: reader.readUInt32(),
+        };
+    }
+}
+const BdxCounterOnlyMessage = new BdxCounterOnlyMessageSchema();
+export const BdxBlockQueryMessage = BdxCounterOnlyMessage;
+export const BdxBlockAckMessage = BdxCounterOnlyMessage;
+export const BdxBlockAckEofMessage = BdxCounterOnlyMessage;
+
+/** Schema for BDX BlockQueryWithSkip message. */
+export class BdxBlockQueryWithSkipMessageSchema extends Schema<BdxBlockQueryWithSkip> {
+    encodeInternal(message: BdxBlockQueryWithSkip) {
+        const { blockCounter, bytesToSkip } = message;
+
+        const writer = new DataWriter(Endian.Little);
+        writer.writeUInt32(blockCounter);
+        writer.writeUInt64(bytesToSkip);
+        return writer.toByteArray();
+    }
+
+    decodeInternal(bytes: Bytes): BdxBlockQueryWithSkip {
+        const reader = new DataReader(bytes, Endian.Little);
+        return {
+            blockCounter: reader.readUInt32(),
+            bytesToSkip: reader.readUInt64(),
+        };
+    }
+}
+export const BdxBlockQueryWithSkipMessage = new BdxBlockQueryWithSkipMessageSchema();
+
+/** Schema for BDX Block and BlockEof message that contain Block data. */
+export class BdxBlockMessageSchema extends Schema<BdxBlock> {
+    encodeInternal(message: BdxBlock) {
+        const { blockCounter, data } = message;
+
+        const writer = new DataWriter(Endian.Little);
+        writer.writeUInt32(blockCounter);
+        writer.writeByteArray(data);
+        return writer.toByteArray();
+    }
+
+    decodeInternal(bytes: Bytes): BdxBlock {
+        const reader = new DataReader(bytes, Endian.Little);
+        return {
+            blockCounter: reader.readUInt32(),
+            data: reader.remainingBytes,
+        };
+    }
+}
+export const BdxBlockMessage = new BdxBlockMessageSchema();
+export const BdxBlockEofMessage = BdxBlockMessage;