@matter-server/ble-proxy 0.7.2-alpha.0-20260601-e778038 → 0.8.0

package/src/ProxyBleChannel.ts

@@ -78,16 +78,20 @@ export class ProxyBleCentralInterface implements Transport {
         }
 
         const { peripheralAddress } = address;
-        const { hasAdditionalAdvertisementData } = this.#bleScanner.getDiscoveredDevice(peripheralAddress);
 
-        if (!this.#handler.connected) {
-            throw new BleError("BLE proxy client not connected");
+        const connection = this.#handler.getOwner(peripheralAddress);
+        if (!connection) {
+            throw new BleError(`No connected BLE proxy client owns peripheral ${peripheralAddress}`);
         }
 
-        logger.debug(`Connecting to peripheral ${peripheralAddress} via proxy`);
+        const discovered = this.#bleScanner.getDiscoveredDevice(peripheralAddress);
+        const { hasAdditionalAdvertisementData } = discovered;
+        const rssi = discovered.peripheral.rssi;
+
+        logger.debug(`Connecting to peripheral ${peripheralAddress} (rssi=${rssi ?? "n/a"}) via proxy`);
 
         // 1. Connect
-        const { connection_handle, mtu: peripheralMtu } = await this.#handler.sendCommand(BleProxyCommand.Connect, {
+        const { connection_handle, mtu: peripheralMtu } = await connection.sendCommand(BleProxyCommand.Connect, {
             address: peripheralAddress,
         });
 
@@ -95,11 +99,17 @@ export class ProxyBleCentralInterface implements Transport {
         if (mtu > MatterBle.MAXIMUM_BTP_MTU) {
             mtu = MatterBle.MAXIMUM_BTP_MTU;
         }
-        logger.debug(`Connected to ${peripheralAddress}, handle=${connection_handle}, mtu=${mtu}`);
+        logger.info(
+            `Connected to ${peripheralAddress}, handle=${connection_handle}, mtu=${mtu}, rssi=${rssi ?? "n/a"}`,
+        );
+
+        // The owner connection's observables outlive a failed open; a leaked observer would corrupt
+        // the next channel on the same connection. Detach on every exit path; assigned once registered.
+        let detachObservers: (() => void) | undefined;
 
         try {
             // 2. Discover services
-            const { services } = await this.#handler.sendCommand(BleProxyCommand.DiscoverServices, {
+            const { services } = await connection.sendCommand(BleProxyCommand.DiscoverServices, {
                 connection_handle,
             });
 
@@ -109,7 +119,7 @@ export class ProxyBleCentralInterface implements Transport {
             }
 
             // 3. Discover characteristics
-            const { characteristics } = await this.#handler.sendCommand(BleProxyCommand.DiscoverCharacteristics, {
+            const { characteristics } = await connection.sendCommand(BleProxyCommand.DiscoverCharacteristics, {
                 connection_handle,
                 service_uuid: matterService.uuid,
             });
@@ -136,34 +146,15 @@ export class ProxyBleCentralInterface implements Transport {
             // 4. Read C3 if present and has additional data
             if (c3Uuid && hasAdditionalAdvertisementData) {
                 logger.debug(`Reading additional commissioning data from C3`);
-                await this.#handler.sendCommand(BleProxyCommand.ReadCharacteristic, {
+                await connection.sendCommand(BleProxyCommand.ReadCharacteristic, {
                     connection_handle,
                     characteristic_uuid: c3Uuid,
                 });
-                // Additional commissioning data read but not used directly by the proxy -
-                // it's handled by matter.js commissioning flow internally
             }
 
-            // 5. Send BTP handshake request on C1 and atomically subscribe to C2 for the
-            // response indication. The combo eliminates the WebSocket round-trip between
-            // Write Response and CCCD enable — without it, a peripheral that pushes the
-            // handshake indication immediately after Write Response can fire before the
-            // proxy client has enabled notifications, and the indication is lost.
-            const btpHandshakeRequest = BtpCodec.encodeBtpHandshakeRequest({
-                versions: MatterBle.BTP_SUPPORTED_VERSIONS,
-                attMtu: mtu,
-                clientWindowSize: MatterBle.BTP_MAXIMUM_WINDOW_SIZE,
-            });
-            logger.debug(`Sending BTP handshake request on C1 and subscribing C2 atomically`);
-            await this.#handler.sendCommand(BleProxyCommand.WriteAndSubscribe, {
-                connection_handle,
-                write_uuid: c1Uuid,
-                write_value: Buffer.from(btpHandshakeRequest as ArrayBuffer).toString("base64"),
-                write_response: true,
-                subscribe_uuid: c2Uuid,
-            });
-
-            // 6. Wait for BTP handshake response via binary frame
+            // 5. Register the handshake observer BEFORE sending: the C2 indication is a separate
+            // binary frame that can beat the WriteAndSubscribe response, and binaryFrameReceived
+            // drops frames emitted with no listener attached.
             const {
                 promise: handshakePromise,
                 resolver: handshakeResolver,
@@ -191,34 +182,74 @@ export class ProxyBleCentralInterface implements Transport {
                     }
                 }
             };
-            this.#handler.binaryFrameReceived.on(handshakeObserver);
+            connection.binaryFrameReceived.on(handshakeObserver);
+
+            // 6. Write C1 and subscribe C2 atomically so the peripheral can't fire its indication
+            // before notifications are enabled (no round-trip between Write Response and CCCD enable).
+            const btpHandshakeRequest = BtpCodec.encodeBtpHandshakeRequest({
+                versions: MatterBle.BTP_SUPPORTED_VERSIONS,
+                attMtu: mtu,
+                clientWindowSize: MatterBle.BTP_MAXIMUM_WINDOW_SIZE,
+            });
+            logger.debug(`Sending BTP handshake request on C1 and subscribing C2 atomically`);
 
             let handshakeResponse: Uint8Array;
             try {
+                await connection.sendCommand(BleProxyCommand.WriteAndSubscribe, {
+                    connection_handle,
+                    write_uuid: c1Uuid,
+                    write_value: Buffer.from(btpHandshakeRequest as ArrayBuffer).toString("base64"),
+                    write_response: true,
+                    subscribe_uuid: c2Uuid,
+                });
                 handshakeResponse = await handshakePromise;
             } finally {
-                this.#handler.binaryFrameReceived.off(handshakeObserver);
+                connection.binaryFrameReceived.off(handshakeObserver);
                 btpHandshakeTimeout.stop();
             }
 
-            // 7. Create BTP session
-            // Use a ref object so closures can access the channel after it's created
+            // 7. Register the live observer BEFORE creating the session (same non-buffering frame
+            // race as step 5); frames seen before the session exists are buffered, then flushed below.
             const onMatterMessageListener = this.#onMatterMessageListener;
             const channelRef: { channel?: ProxyBleChannel } = {};
+            const sessionRef: { session?: BtpSessionHandler } = {};
+            const earlyFrames = new Array<Uint8Array>();
+
+            const forwardToBtp = (payload: Uint8Array) => {
+                sessionRef.session
+                    ?.handleIncomingBleData(payload)
+                    .catch(error =>
+                        logger.warn(`Peripheral ${peripheralAddress}: Error handling incoming BLE data`, error),
+                    );
+            };
 
+            const binaryObserver = (frame: { connectionHandle: number; opcode: number; payload: Uint8Array }) => {
+                if (frame.connectionHandle === connection_handle && frame.opcode === BinaryFrameOpcode.Notification) {
+                    const payload = new Uint8Array(frame.payload);
+                    if (sessionRef.session) {
+                        forwardToBtp(payload);
+                    } else {
+                        earlyFrames.push(payload);
+                    }
+                }
+            };
+            connection.binaryFrameReceived.on(binaryObserver);
+            detachObservers = () => connection.binaryFrameReceived.off(binaryObserver);
+
+            // 8. Create the BTP session.
             const btpSession = await BtpSessionHandler.createAsCentral(
                 handshakeResponse,
                 // Write callback: send binary frame to proxy client
                 async (data: Bytes) => {
                     const bytes = data instanceof Uint8Array ? data : new Uint8Array(data as ArrayBuffer);
-                    this.#handler.sendBinaryFrame(BinaryFrameOpcode.WriteData, connection_handle, bytes);
+                    connection.sendBinaryFrame(BinaryFrameOpcode.WriteData, connection_handle, bytes);
                 },
                 // Disconnect callback
                 async () => {
                     if (!channelRef.channel?.connected) return;
                     logger.debug(`Disconnecting from ${peripheralAddress} via proxy`);
                     try {
-                        await this.#handler.sendCommand(BleProxyCommand.Disconnect, { connection_handle });
+                        await connection.sendCommand(BleProxyCommand.Disconnect, { connection_handle });
                     } catch (error) {
                         logger.debug(
                             `Peripheral ${peripheralAddress}: Error sending Disconnect to proxy client`,
@@ -234,18 +265,12 @@ export class ProxyBleCentralInterface implements Transport {
                     }
                 },
             );
+            sessionRef.session = btpSession;
 
-            // 8. Wire up binary frame notifications to BTP session
-            const binaryObserver = (frame: { connectionHandle: number; opcode: number; payload: Uint8Array }) => {
-                if (frame.connectionHandle === connection_handle && frame.opcode === BinaryFrameOpcode.Notification) {
-                    btpSession
-                        .handleIncomingBleData(new Uint8Array(frame.payload))
-                        .catch(error =>
-                            logger.warn(`Peripheral ${peripheralAddress}: Error handling incoming BLE data`, error),
-                        );
-                }
-            };
-            this.#handler.binaryFrameReceived.on(binaryObserver);
+            for (const payload of earlyFrames) {
+                forwardToBtp(payload);
+            }
+            earlyFrames.length = 0;
 
             // 9. Handle unexpected disconnects from proxy client
             const eventObserver = (event: string, data: Record<string, unknown>) => {
@@ -261,21 +286,32 @@ export class ProxyBleCentralInterface implements Transport {
                         .catch(error => logger.debug(`Peripheral ${peripheralAddress}: Error closing channel`, error));
                 }
             };
-            this.#handler.eventReceived.on(eventObserver);
+            connection.eventReceived.on(eventObserver);
+
+            // The Disconnected event covers one peripheral; this covers the whole owning client vanishing.
+            const ownerClosedObserver = () => {
+                logger.info(`Owning proxy client for ${peripheralAddress} disconnected`);
+                channelRef.channel?.markDisconnected();
+                channelRef.channel
+                    ?.close()
+                    .catch(error => logger.debug(`Peripheral ${peripheralAddress}: Error closing channel`, error));
+            };
+            connection.closed.on(ownerClosedObserver);
 
-            // Cleanup function to remove observers when channel closes
-            const cleanupObservers = () => {
-                this.#handler.binaryFrameReceived.off(binaryObserver);
-                this.#handler.eventReceived.off(eventObserver);
+            detachObservers = () => {
+                connection.binaryFrameReceived.off(binaryObserver);
+                connection.eventReceived.off(eventObserver);
+                connection.closed.off(ownerClosedObserver);
             };
 
-            const proxyChannel = new ProxyBleChannel(peripheralAddress, btpSession, cleanupObservers);
+            const proxyChannel = new ProxyBleChannel(peripheralAddress, btpSession, detachObservers);
             channelRef.channel = proxyChannel;
             return proxyChannel;
         } catch (error) {
-            // Clean up on failure — best-effort tear-down of the peripheral on the proxy side
+            // Clean up on failure — detach observers and best-effort tear-down on the proxy side
+            detachObservers?.();
             try {
-                await this.#handler.sendCommand(BleProxyCommand.Disconnect, { connection_handle });
+                await connection.sendCommand(BleProxyCommand.Disconnect, { connection_handle });
             } catch (cleanupError) {
                 logger.debug(`Peripheral ${peripheralAddress}: Error during connect-failure cleanup`, cleanupError);
             }

package/src/ProxyBleClient.ts

@@ -6,8 +6,9 @@
 
 import { createPromise, Logger, Seconds, withTimeout } from "@matter/main";
 import { BleError, MatterBle } from "@matter/main/protocol";
+import type { BleProxyConnection } from "./BleProxyConnection.js";
 import type { BleProxyHandler } from "./BleProxyHandler.js";
-import { BleProxyCommand, BleProxyEvent, type DeviceDiscoveredData } from "./BleProxyProtocol.js";
+import type { DeviceDiscoveredData } from "./BleProxyProtocol.js";
 
 const logger = Logger.get("ProxyBleClient");
 
@@ -43,18 +44,19 @@ export class ProxyBleClient {
     #deviceDiscoveredCallback: ((peripheral: ProxyPeripheral, matterServiceData: Uint8Array) => void) | undefined;
     #isScanning = false;
 
-    readonly #eventObserver = (event: string, data: Record<string, unknown>) => {
-        if (event === BleProxyEvent.DeviceDiscovered) {
-            this.#handleDeviceDiscovered(data as unknown as DeviceDiscoveredData);
-        } else if (event === BleProxyEvent.ScanStopped) {
-            logger.info(`Scan stopped by proxy client: ${(data as { reason?: string }).reason ?? "unknown"}`);
-            this.#isScanning = false;
-        }
+    readonly #deviceDiscoveredObserver = (data: DeviceDiscoveredData, _connection: BleProxyConnection) => {
+        this.#handleDeviceDiscovered(data);
+    };
+
+    readonly #scanStoppedObserver = (reason: string) => {
+        logger.info(`Scan stopped by proxy client: ${reason}`);
+        this.#isScanning = false;
     };
 
     constructor(handler: BleProxyHandler) {
         this.#handler = handler;
-        this.#handler.eventReceived.on(this.#eventObserver);
+        this.#handler.deviceDiscovered.on(this.#deviceDiscoveredObserver);
+        this.#handler.scanStopped.on(this.#scanStoppedObserver);
     }
 
     setDiscoveryCallback(callback: (peripheral: ProxyPeripheral, matterServiceData: Uint8Array) => void): void {
@@ -88,31 +90,23 @@ export class ProxyBleClient {
         logger.debug("Start BLE scanning via proxy ...");
         // Matter discovery only needs one event per state change; opt out of the spec's
         // default true so a 10 Hz peripheral advertise doesn't flood the WebSocket.
-        await this.#handler.sendCommand(BleProxyCommand.StartScan, {
-            service_uuids: ["fff6"],
-            allow_duplicates: false,
-        });
+        await this.#handler.startScan({ service_uuids: ["fff6"], allow_duplicates: false });
         this.#isScanning = true;
     }
 
     async stopScanning(): Promise<void> {
-        if (!this.#isScanning) {
-            return;
-        }
-
-        if (!this.#handler.connected) {
-            this.#isScanning = false;
-            return;
-        }
-
-        logger.debug("Stop BLE scanning via proxy ...");
-        await this.#handler.sendCommand(BleProxyCommand.StopScan);
+        // Clear hub scan intent unconditionally: a transient all-clients-disconnect can reset
+        // #isScanning while the hub still intends to scan, and skipping stopScan here would let
+        // a reconnecting client auto-resume a scan the caller already ended.
         this.#isScanning = false;
+        logger.debug("Stop BLE scanning via proxy ...");
+        await this.#handler.stopScan();
     }
 
     close(): void {
         this.#isScanning = false;
-        this.#handler.eventReceived.off(this.#eventObserver);
+        this.#handler.deviceDiscovered.off(this.#deviceDiscoveredObserver);
+        this.#handler.scanStopped.off(this.#scanStoppedObserver);
     }
 
     #handleDeviceDiscovered(data: DeviceDiscoveredData): void {
@@ -150,7 +144,9 @@ export class ProxyBleClient {
             return;
         }
 
-        logger.debug(`Discovered device ${address} (${name ?? "unnamed"}) via proxy`);
+        logger.info(
+            `Discovered commissionable device ${address} (${name ?? "unnamed"}) rssi=${rssi ?? "n/a"} via proxy`,
+        );
         this.#discoveredPeripherals.set(address, { peripheral, matterServiceData });
         this.#deviceDiscoveredCallback?.(peripheral, matterServiceData);
     }

package/src/index.ts

@@ -8,6 +8,7 @@
  * @matter-server/ble-proxy - BLE proxy for matter.js over WebSocket
  */
 
+export * from "./BleProxyConnection.js";
 export * from "./BleProxyHandler.js";
 export * from "./BleProxyProtocol.js";
 export * from "./ProxyBle.js";