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

package/src/bdx/FileDesignator.ts

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes } from "#general";
+
+/**
+ * Class to represent a File designator from Matter.
+ * Specification wise this is a bytes object, but to store in a storage we need a string name.
+ * This class provides a way to convert between the two.
+ */
+export class FileDesignator {
+    #fd: Bytes;
+
+    /** Create a FileDesignator from a string or bytes object. */
+    constructor(fd: string | Bytes) {
+        if (typeof fd === "string") {
+            this.#fd = Bytes.fromString(fd);
+        } else {
+            this.#fd = fd;
+        }
+    }
+
+    /** Return the bytes representation of the FileDesignator. */
+    get bytes(): Bytes {
+        return this.#fd;
+    }
+
+    /** Return the textual/string representation of the FileDesignator. */
+    get text(): string {
+        const fileDesignatorData = Bytes.of(this.#fd);
+        // When all uint8 values are in char() range "a-z0-0-." then use this as the blob name, else hex encode it
+        const isValidName = fileDesignatorData.every(
+            byte =>
+                (byte >= 0x41 && byte <= 0x5a) || // A-Z
+                (byte >= 0x61 && byte <= 0x7a) || // a-z
+                (byte >= 0x30 && byte <= 0x39) || // 0..9
+                byte === 0x2e || // "."
+                byte === 0x2d, // "-"
+        );
+        if (isValidName) {
+            return fileDesignatorData.reduce((name, byte) => name + String.fromCharCode(byte), "");
+        } else {
+            return `0x${Bytes.toHex(fileDesignatorData)}`;
+        }
+    }
+}

package/src/bdx/PersistedFileDesignator.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, ImplementationError, StorageContext } from "#general";
+import { FileDesignator } from "./FileDesignator.js";
+
+/** A FileDesignator that points to a persisted file in a given StorageContext. */
+export class PersistedFileDesignator extends FileDesignator {
+    #storage: StorageContext;
+    #blob?: Blob;
+
+    constructor(fd: string | Bytes, storage: StorageContext) {
+        super(fd);
+        this.#storage = storage;
+    }
+
+    exists() {
+        return this.#storage.has(this.text);
+    }
+
+    async openBlob() {
+        if (this.#blob === undefined) {
+            const blobName = this.text;
+            if (!this.#storage.has(blobName)) {
+                throw new ImplementationError(
+                    "File designator must point to an existing file in the storage to send data",
+                );
+            }
+            this.#blob = await this.#storage.openBlob(blobName);
+        }
+        return this.#blob;
+    }
+
+    writeFromStream(stream: ReadableStream<Bytes>) {
+        return this.#storage.writeBlobFromStream(this.text, stream);
+    }
+}

package/src/bdx/bdx-session-initiator.ts

@@ -0,0 +1,246 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ImplementationError, InternalError, Logger } from "#general";
+import { BdxStatusCode, TypeFromPartialBitSchema } from "#types";
+import { BdxError } from "./BdxError.js";
+import { BdxMessenger } from "./BdxMessenger.js";
+import { BdxSessionConfiguration } from "./BdxSessionConfiguration.js";
+import { Flow } from "./flow/Flow.js";
+import { BdxReceiveAccept, BdxSendAccept } from "./schema/BdxAcceptMessagesSchema.js";
+import { BDX_VERSION, BdxInit, BdxTransferControlBitmap } from "./schema/BdxInitMessagesSchema.js";
+
+const logger = Logger.get("bdxSessionInitiator");
+
+/**
+ * Handles the initiation of a BDX session by exchanging *Init and *Accept messages and negotiating the transfer
+ * parameters.
+ */
+export async function bdxSessionInitiator(messenger: BdxMessenger, config: BdxSessionConfiguration) {
+    if (config.isInitiator) {
+        if (config.isSender) {
+            // We are Sender and Initiator
+            const initMessage = await buildInitMessage();
+            const acceptMessage = await messenger.sendSendInit(initMessage);
+            return collectAcceptParameters(
+                acceptMessage,
+                // We define the data, so we know it are numbers
+                initMessage.startOffset !== undefined ? Number(initMessage.startOffset) : undefined,
+                initMessage.maxLength !== undefined ? Number(initMessage.maxLength) : undefined,
+            );
+        }
+
+        // We are Receiver and Initiator
+        const acceptMessage = await messenger.sendReceiveInit(await buildInitMessage());
+        return collectAcceptParameters(acceptMessage);
+    }
+
+    // We are starting from an incoming *Init message
+    const initMessage = config.initMessage;
+    if (initMessage === undefined) {
+        throw new InternalError("Initial message must be set before starting from initial message");
+    }
+    logger.debug(`Initialize BDX ${config.isSender ? "ReceiveInit" : "SendInit"} from incoming Message`, initMessage);
+
+    if (config.isSender) {
+        // We are Sender and Responder
+        if (!config.fileDesignator.exists()) {
+            throw new BdxError(
+                `File designator ${config.fileDesignator.text} does not point to an existing file in the storage to send data`,
+                BdxStatusCode.FileDesignatorUnknown,
+            );
+        }
+
+        let { startOffset } = initMessage;
+        if (startOffset !== undefined) {
+            startOffset = BdxMessenger.asSafeNumber(startOffset, "Start offset", BdxStatusCode.StartOffsetNotSupported);
+        }
+
+        const acceptMessage = await determineAcceptParameters(initMessage);
+
+        const length =
+            "length" in acceptMessage && typeof acceptMessage.length === "number" ? acceptMessage.length : undefined;
+
+        // If we received an Init message with a maxLength and we are the sender, we need to check if the
+        // available blob size is enough to send the requested maxLength.
+        const blobToRead = await config.fileDesignator.openBlob();
+
+        if (length !== undefined && length > 0) {
+            const availableSize = blobToRead.size - (startOffset ?? 0);
+            if (length > availableSize) {
+                throw new BdxError(
+                    `Requested maxLength ${length}bytes${startOffset ? ` with startOffset ${startOffset}` : ""} exceeds available size ${blobToRead.size} for blob ${config.fileDesignator.text}`,
+                    BdxStatusCode.LengthTooLarge,
+                );
+            }
+        }
+
+        await messenger.sendReceiveAccept(acceptMessage);
+
+        return collectAcceptParameters(acceptMessage, startOffset, length);
+    }
+
+    // We are Receiver and Responder
+    const acceptMessage = {
+        ...(await determineAcceptParameters(initMessage)),
+        length: undefined, // Length is not included in SendAccept, so take out to not confuse in logs
+    };
+    await messenger.sendSendAccept(acceptMessage);
+    return collectAcceptParameters(acceptMessage);
+
+    /** These are the proposed data that we send out to the peer device which include anything we can support */
+    async function buildInitMessage(): Promise<BdxInit> {
+        const {
+            senderStartOffset,
+            maxTransferSize,
+            senderMaxLength,
+            preferredDriverModes,
+            asynchronousTransferAllowed,
+        } = config.transferConfig;
+        const { isSender, fileDesignator } = config;
+
+        let startOffset: number | undefined;
+        let maxLength: number | undefined;
+        if (isSender) {
+            maxLength = (await fileDesignator.openBlob()).size;
+            if (senderStartOffset !== undefined) {
+                if (maxLength <= senderStartOffset) {
+                    throw new ImplementationError(
+                        `Available data of ${maxLength}bytes are smaller than senderStartOffset ${senderStartOffset}bytes`,
+                    );
+                }
+                startOffset = senderStartOffset;
+                maxLength -= startOffset; // maxLength is the full file size we have, so subtract the start offset
+            }
+            if (maxTransferSize !== undefined) {
+                if (maxLength > maxTransferSize) {
+                    throw new ImplementationError(
+                        `Requested maxLength ${maxLength}bytes exceeds maximum transfer size ${maxTransferSize}bytes`,
+                    );
+                }
+            }
+            if (senderMaxLength !== undefined) {
+                if (maxLength >= senderMaxLength) {
+                    maxLength = senderMaxLength;
+                } else {
+                    logger.info(
+                        `Ignoring requested senderMaxLength ${senderMaxLength}bytes as it is larger then the relevant payload size of ${maxLength}bytes`,
+                    );
+                }
+            }
+        }
+
+        let maxBlockSize = messenger.maxPayloadSize - 4; // 4 bytes for the block counter by default
+        const requestedBlockSize = config.transferConfig.maxBlockSize;
+        if (requestedBlockSize !== undefined) {
+            if (maxBlockSize > requestedBlockSize) {
+                maxBlockSize = requestedBlockSize;
+            } else {
+                logger.info(
+                    `Ignoring requested maxBlockSize ${requestedBlockSize}, as it is larger then the transport max payload size ${maxBlockSize}bytes`,
+                );
+            }
+        }
+
+        return {
+            transferProtocol: {
+                version: BDX_VERSION,
+                senderDrive: !!preferredDriverModes?.includes(Flow.DriverMode.SenderDrive),
+                receiverDrive: !!preferredDriverModes?.includes(Flow.DriverMode.ReceiverDrive),
+                asynchronousTransfer: asynchronousTransferAllowed, // always false for now
+            },
+            maxBlockSize,
+            fileDesignator: fileDesignator.bytes,
+            startOffset,
+            maxLength,
+        };
+    }
+
+    /** Determine *Accept response parameters from an *Init message */
+    async function determineAcceptParameters(initMessage: BdxInit): Promise<BdxReceiveAccept | BdxSendAccept> {
+        const { transferProtocol, maxLength: initMaxLength = 0 } = initMessage;
+        let { maxBlockSize } = initMessage;
+
+        // We use the first matching mode between the offered and preferred modes
+        let finalDriverMode: Flow.DriverMode | undefined;
+        for (const mode of config.transferConfig.preferredDriverModes!) {
+            if (transferProtocol[mode]) {
+                finalDriverMode = mode;
+                break;
+            }
+        }
+        if (finalDriverMode === undefined) {
+            throw new BdxError("Can not determine a valid transfer mode", BdxStatusCode.TransferMethodNotSupported);
+        }
+
+        const requestedMaxBlockSize = config.transferConfig.maxBlockSize;
+        if (requestedMaxBlockSize !== undefined && maxBlockSize > requestedMaxBlockSize) {
+            maxBlockSize = requestedMaxBlockSize;
+        }
+
+        const maxLength = BdxMessenger.asSafeNumber(initMaxLength, "Max length", BdxStatusCode.LengthTooLarge);
+        // TODO: How to handle custom metadata?
+
+        const transferControl: TypeFromPartialBitSchema<typeof BdxTransferControlBitmap> = {
+            version: BDX_VERSION, // We support the minimum version, so no need for further checks
+            [finalDriverMode]: true, // this sets either senderDrive or receiveDriver property
+            asynchronousTransfer: false, // Not supported so ignore if it was received
+        };
+        return {
+            transferControl,
+            maxBlockSize,
+            length: maxLength > 0 ? maxLength : undefined,
+        };
+    }
+
+    /**
+     * Collects the negotiated details from the *Accept message into the Transfer parameters.
+     * Also determines by the response if we are the driver or the peer.
+     */
+    function collectAcceptParameters(
+        acceptMessage: BdxSendAccept | BdxReceiveAccept,
+        startOffset = 0,
+        maxLength?: number,
+    ): Flow.TransferOptions {
+        const {
+            transferControl: { senderDrive, asynchronousTransfer },
+            maxBlockSize,
+        } = acceptMessage;
+        if (asynchronousTransfer) {
+            // Async is not supported by matter SDK and such, so always decline this for now
+            throw new BdxError(
+                "Asynchronous transfer is not supported in this implementation",
+                BdxStatusCode.TransferMethodNotSupported,
+            );
+        }
+
+        const dataLength =
+            "length" in acceptMessage && acceptMessage.length !== undefined
+                ? BdxMessenger.asSafeNumber(
+                      acceptMessage.length,
+                      "Accept message length field",
+                      BdxStatusCode.LengthTooLarge,
+                  )
+                : maxLength;
+
+        const transferParameters: Flow.TransferOptions = {
+            transferMode: senderDrive ? Flow.DriverMode.SenderDrive : Flow.DriverMode.ReceiverDrive,
+            asynchronousTransfer: false, // always false for now
+            dataLength,
+            startOffset,
+            blockSize: maxBlockSize,
+            isDriver: (config.isSender && senderDrive) || (!config.isSender && !senderDrive),
+            fileDesignator: config.fileDesignator,
+        };
+
+        logger.debug(
+            `${transferParameters.isDriver ? "We are" : "Peer is"} driving-${config.isSender ? "sender" : "receiver"} with negotiated transfer parameters`,
+            transferParameters,
+        );
+
+        return transferParameters;
+    }
+}

package/src/bdx/flow/DrivenSendingFlow.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { OutboundFlow } from "./OutboundFlow.js";
+
+/**
+ * BDX Transport flow logic for a "BDX Driving Sender":
+ * - Send out the Block and wait for Ack (if synchronous transfer is used)
+ * - Last message is sent with BlockEof and expects AckEof
+ */
+export class DrivenSendingFlow extends OutboundFlow {
+    protected async transferNextChunk() {
+        const { asynchronousTransfer } = this.transferParameters;
+        const { iterator } = this.stream;
+
+        const blockCounter = this.nextMessageCounter;
+        // Read the next data chunk from the storage
+        const { data, done } = await this.readDataChunk(iterator);
+
+        if (done) {
+            // Send the last Block and wait for AckEof and close down
+            await this.messenger.sendBlockEof({ data: data ?? new Uint8Array(), blockCounter });
+            this.finalBlockCounter = blockCounter;
+            return true;
+        }
+
+        // Send the next Block
+        await this.messenger.sendBlock({ data, blockCounter });
+
+        // Sync transfer just continues when the Ack is received
+        if (!asynchronousTransfer) {
+            const { blockCounter: ackedBlockCounter } = await this.messenger.readBlockAck();
+            this.validateCounter(ackedBlockCounter, blockCounter);
+        }
+        return false;
+    }
+}

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;
+    }
+}