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

package/src/bdx/BdxSession.ts

@@ -0,0 +1,174 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { AsyncObservable, ClassExtends, Diagnostic, Logger, StorageContext } from "#general";
+import { BdxMessageType, BdxStatusCode } from "#types";
+import { bdxSessionInitiator } from "./bdx-session-initiator.js";
+import { BdxError } from "./BdxError.js";
+import { BdxMessenger } from "./BdxMessenger.js";
+import { BdxSessionConfiguration } from "./BdxSessionConfiguration.js";
+import { DrivenSendingFlow } from "./flow/DrivenSendingFlow.js";
+import { DrivingReceivingFlow } from "./flow/DrivingReceivingFlow.js";
+import { Flow } from "./flow/Flow.js";
+import { FollowingReceivingFlow } from "./flow/FollowingReceivingFlow.js";
+import { FollowingSendingFlow } from "./flow/FollowingSendingFlow.js";
+import { PersistedFileDesignator } from "./PersistedFileDesignator.js";
+
+const logger = Logger.get("BdxSession");
+
+/**
+ * Class to manage one BDX session.
+ *
+ * Matter BDX protocol is used to transfer files between devices.
+ *
+ * Notes:
+ * * Even though Matter allows 64bit values for size and offset, we do not use them, as they make no sense for now.
+ *   We support up to MAX_SAFE_INTEGER for size and offset (which basically is 2^53 - 1 and so far enough for us).
+ * * We support partial transfers (startOffset or shorter dataLength) only when we act as the sender. As a receiver,
+ *   only full transfers are supported.
+ * * We do not use BlockQueryWithSkip when requesting data ourselves
+ */
+export class BdxSession {
+    #messenger: BdxMessenger;
+    #started = false;
+    #closed = AsyncObservable();
+    #isClosed = false;
+
+    #config: BdxSessionConfiguration;
+
+    #transferFlow?: Flow;
+
+    /** Initializes a BdxSession as a sender, means that we upload data to the peer. */
+    static asSender(messenger: BdxMessenger, options: BdxSessionConfiguration.SenderInitiatorOptions): BdxSession {
+        return new BdxSession(messenger, { isSender: true, ...options });
+    }
+
+    /** Initializes a BdxSession as a receiver, means that we download data from the peer. */
+    static asReceiver(messenger: BdxMessenger, options: BdxSessionConfiguration.InitiatorOptions): BdxSession {
+        return new BdxSession(messenger, { isSender: false, ...options });
+    }
+
+    /** Initializes a BdxSession from an incoming *Init message. The message determines the direction of the transfer. */
+    static fromMessage(
+        storage: StorageContext,
+        messenger: BdxMessenger,
+        options: BdxSessionConfiguration.ReceiverOptions,
+    ): BdxSession {
+        const { initMessageType, initMessage } = options;
+        if (initMessageType !== BdxMessageType.SendInit && initMessageType !== BdxMessageType.ReceiveInit) {
+            throw new BdxError(
+                `Invalid message type for BDX session initialization: ${BdxMessageType[initMessageType]} (${initMessageType})`,
+                BdxStatusCode.UnexpectedMessage,
+            );
+        }
+
+        const { fileDesignator } = initMessage;
+
+        return new BdxSession(messenger, {
+            isSender: initMessageType === BdxMessageType.ReceiveInit,
+            fileDesignator: new PersistedFileDesignator(fileDesignator, storage),
+            ...options,
+        });
+    }
+
+    private constructor(messenger: BdxMessenger, options: BdxSessionConfiguration.Options) {
+        this.#messenger = messenger;
+
+        this.#config = new BdxSessionConfiguration(options);
+
+        const exchange = messenger.exchange;
+        if (!exchange.channel.isReliable) {
+            throw new BdxError("Bdx Protocol requires a reliable channel for message exchange");
+        }
+        exchange.closed.on(async () => {
+            logger.debug(`Closing BDX session for exchange ${exchange.id}`);
+            await this.close();
+        });
+    }
+
+    /** Method called to start the session. It will end with a successful Transfer or with an error */
+    async processTransfer() {
+        if (this.#started) {
+            throw new BdxError("BDX session already started", BdxStatusCode.UnexpectedMessage);
+        }
+        if (this.#isClosed) {
+            throw new BdxError("BDX session already closed", BdxStatusCode.UnexpectedMessage);
+        }
+
+        const { isSender, isInitiator, fileDesignator } = this.#config;
+        logger.info(
+            `Starting BDX session`,
+            Diagnostic.dict({
+                exId: this.#messenger.exchange.id,
+                isSender,
+                isInitiator,
+                blobName: fileDesignator?.text,
+            }),
+        );
+
+        this.#started = true;
+        try {
+            this.#transferFlow = this.#initializeFlow(await bdxSessionInitiator(this.#messenger, this.#config));
+
+            await this.#transferFlow.processTransfer();
+
+            await this.close();
+        } catch (error) {
+            BdxError.accept(error);
+            await this.#messenger.sendError(error.code);
+
+            logger.warn(`BDX session failed with error:`, error);
+
+            await this.close(error);
+            throw error;
+        }
+    }
+
+    #initializeFlow(transferParameters: Flow.TransferOptions): Flow {
+        const { transferMode, asynchronousTransfer, dataLength, isDriver, fileDesignator } = transferParameters;
+        const isSenderDrive = transferMode === Flow.DriverMode.SenderDrive;
+
+        const role = `${isSenderDrive ? `${asynchronousTransfer ? "async " : ""}sending` : "receiving"} ${isDriver ? "driver" : "follower"}`;
+        logger.debug(
+            `Starting transfer flow as ${role}`,
+            Diagnostic.dict({
+                exId: this.#messenger.exchange.id,
+                dataLength,
+                blobName: fileDesignator.text,
+            }),
+        );
+
+        let FlowImpl: ClassExtends<Flow>;
+        if (isDriver) {
+            if (isSenderDrive || asynchronousTransfer) {
+                FlowImpl = DrivenSendingFlow;
+            } else {
+                FlowImpl = DrivingReceivingFlow;
+            }
+        } else if (isSenderDrive || asynchronousTransfer) {
+            FlowImpl = FollowingSendingFlow;
+        } else {
+            FlowImpl = FollowingReceivingFlow;
+        }
+
+        return new FlowImpl(this.#messenger, transferParameters);
+    }
+
+    get closed() {
+        return this.#closed;
+    }
+
+    async close(error?: unknown) {
+        if (this.#isClosed) {
+            return;
+        }
+        this.#isClosed = true;
+        await this.#transferFlow?.close(error);
+        await this.#closed.emit();
+    }
+}
+
+export namespace BdxSession {}

package/src/bdx/BdxSessionConfiguration.ts

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ImplementationError } from "#general";
+import { BdxMessageType } from "#types";
+import { Flow } from "./flow/Flow.js";
+import { PersistedFileDesignator } from "./PersistedFileDesignator.js";
+import { BdxInit } from "./schema/BdxInitMessagesSchema.js";
+
+export class BdxSessionConfiguration {
+    #isSender: boolean;
+    #initMessage?: BdxInit;
+    #transferConfig: BdxSessionConfiguration.Config;
+    #fileDesignator: PersistedFileDesignator;
+
+    constructor(options: BdxSessionConfiguration.Options) {
+        const { isSender, fileDesignator, initMessage } = options;
+        this.#fileDesignator = fileDesignator;
+        this.#isSender = isSender;
+        this.#initMessage = initMessage;
+        this.#transferConfig = { ...BdxSessionConfiguration.DefaultConfig, ...options };
+
+        // Validate Config
+        const {
+            preferredDriverModes = [],
+            maxBlockSize,
+            maxTransferSize,
+            asynchronousTransferAllowed,
+            senderStartOffset,
+            senderMaxLength,
+        } = this.#transferConfig;
+        if (preferredDriverModes.length === 0) {
+            throw new ImplementationError("At least one preferred driver mode must be set.");
+        }
+        if (maxBlockSize !== undefined && maxBlockSize <= 0) {
+            throw new ImplementationError("Max block size must be greater than 0");
+        }
+        if (maxTransferSize !== undefined && maxTransferSize <= 0) {
+            throw new ImplementationError("Max transfer size must be greater than 0");
+        }
+        if (asynchronousTransferAllowed) {
+            throw new ImplementationError("Asynchronous transfer is not supported");
+        }
+        if (!isSender && (senderStartOffset !== undefined || senderMaxLength !== undefined)) {
+            throw new ImplementationError("Sender start offset and sender max length are only supported for senders");
+        }
+    }
+
+    get isSender(): boolean {
+        return this.#isSender;
+    }
+
+    get initMessage(): BdxInit | undefined {
+        return this.#initMessage;
+    }
+
+    get isInitiator(): boolean {
+        return this.#initMessage === undefined;
+    }
+
+    get fileDesignator(): PersistedFileDesignator {
+        return this.#fileDesignator;
+    }
+
+    get transferConfig(): BdxSessionConfiguration.Config {
+        return this.#transferConfig;
+    }
+}
+
+export namespace BdxSessionConfiguration {
+    export interface Config {
+        /**
+         * Array of preferred transfer driver modes, in order of preference. Use this to configure the proposed behavior.
+         * Default is [SenderDrive, ReceiverDrive]
+         */
+        preferredDriverModes?: Flow.DriverMode[];
+
+        /** Asynchronous transfer is not supported right now because provisional. */
+        asynchronousTransferAllowed?: false; // not supported right now, so must be false
+
+        /** Maximum block size to use for the session. This value is ignored if the transport only supports smaller blocks. */
+        maxBlockSize?: number;
+
+        /** Maximum transfer size to use for the session. Defaults to 100MB */
+        maxTransferSize?: number;
+
+        /** The start offset of the data to send. When using this, you need to know what you are doing. */
+        senderStartOffset?: number;
+
+        /** The maximum length of the data to send. When using this, you need to know what you are doing. */
+        senderMaxLength?: number;
+    }
+
+    export const DefaultConfig: BdxSessionConfiguration.Config = {
+        preferredDriverModes: [
+            Flow.DriverMode.SenderDrive, // Default if multiple is supported, so lets use this
+            Flow.DriverMode.ReceiverDrive,
+        ],
+        asynchronousTransferAllowed: false, // Provisional, not supported
+        maxTransferSize: 1_024 * 100_000, // 100 MB, lets use that as maximum transfer filesize for now just to protect
+    };
+
+    export interface InitiatorOptions extends BdxSessionConfiguration.Config {
+        /** FileDesignator to use for the session. The value is usually pre-determined with the peer. */
+        fileDesignator: PersistedFileDesignator;
+    }
+
+    export interface SenderInitiatorOptions extends InitiatorOptions {
+        /** The start offset of the data to send. When using this, you need to know what you are doing. */
+        senderStartOffset?: number;
+
+        /** The maximum length of the data to send. When using this, you need to know what you are doing. */
+        senderMaxLength?: number;
+    }
+
+    export interface ReceiverOptions extends BdxSessionConfiguration.Config {
+        initMessageType: BdxMessageType;
+        initMessage: BdxInit; // The initial message received to start the session
+    }
+
+    export interface Options extends BdxSessionConfiguration.Config {
+        /** True if the session is initiated as a sender, false for receiver */
+        isSender: boolean;
+
+        /** File designator to use for the session */
+        fileDesignator: PersistedFileDesignator;
+
+        /** The initial message received to start the session */
+        initMessage?: BdxInit;
+    }
+}

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