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

package/dist/esm/ProxyBleClient.js

@@ -5,7 +5,6 @@
  */
 import { createPromise, Logger, Seconds, withTimeout } from "@matter/main";
 import { BleError, MatterBle } from "@matter/main/protocol";
-import { BleProxyCommand, BleProxyEvent } from "./BleProxyProtocol.js";
 const logger = Logger.get("ProxyBleClient");
 const SCAN_CONNECT_WAIT = Seconds(30);
 class ProxyBleClient {
@@ -13,17 +12,17 @@ class ProxyBleClient {
   #discoveredPeripherals = /* @__PURE__ */ new Map();
   #deviceDiscoveredCallback;
   #isScanning = false;
-  #eventObserver = (event, data) => {
-    if (event === BleProxyEvent.DeviceDiscovered) {
-      this.#handleDeviceDiscovered(data);
-    } else if (event === BleProxyEvent.ScanStopped) {
-      logger.info(`Scan stopped by proxy client: ${data.reason ?? "unknown"}`);
-      this.#isScanning = false;
-    }
+  #deviceDiscoveredObserver = (data, _connection) => {
+    this.#handleDeviceDiscovered(data);
+  };
+  #scanStoppedObserver = (reason) => {
+    logger.info(`Scan stopped by proxy client: ${reason}`);
+    this.#isScanning = false;
   };
   constructor(handler) {
     this.#handler = handler;
-    this.#handler.eventReceived.on(this.#eventObserver);
+    this.#handler.deviceDiscovered.on(this.#deviceDiscoveredObserver);
+    this.#handler.scanStopped.on(this.#scanStoppedObserver);
   }
   setDiscoveryCallback(callback) {
     this.#deviceDiscoveredCallback = callback;
@@ -51,27 +50,18 @@ class ProxyBleClient {
       }
     }
     logger.debug("Start BLE scanning via proxy ...");
-    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() {
-    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);
     this.#isScanning = false;
+    logger.debug("Stop BLE scanning via proxy ...");
+    await this.#handler.stopScan();
   }
   close() {
     this.#isScanning = false;
-    this.#handler.eventReceived.off(this.#eventObserver);
+    this.#handler.deviceDiscovered.off(this.#deviceDiscoveredObserver);
+    this.#handler.scanStopped.off(this.#scanStoppedObserver);
   }
   #handleDeviceDiscovered(data) {
     const { address, name, rssi, connectable, service_data } = data;
@@ -101,7 +91,9 @@ class ProxyBleClient {
       logger.debug(`Peripheral ${address} does not advertise valid Matter service data, ignoring`);
       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/dist/esm/ProxyBleClient.js.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../../src/ProxyBleClient.ts"],
-  "mappings": "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",
+  "mappings": "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",
   "names": []
 }

package/dist/esm/index.d.ts

@@ -6,6 +6,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";

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AAEH,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC"}

package/dist/esm/index.js

@@ -3,6 +3,7 @@
  * Copyright 2025-2026 Open Home Foundation
  * SPDX-License-Identifier: Apache-2.0
  */
+export * from "./BleProxyConnection.js";
 export * from "./BleProxyHandler.js";
 export * from "./BleProxyProtocol.js";
 export * from "./ProxyBle.js";

package/dist/esm/index.js.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../../src/index.ts"],
-  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAUA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;",
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAUA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;",
   "names": []
 }

package/package.json

@@ -1,46 +1,47 @@
 {
     "name": "@matter-server/ble-proxy",
-    "version": "0.7.2-alpha.0-20260601-e778038",
-    "type": "module",
+    "version": "0.8.0",
     "description": "BLE proxy implementation for matter.js - proxies BLE operations over WebSocket",
+    "homepage": "https://github.com/matter-js/matterjs-server",
     "bugs": {
         "url": "https://github.com/matter-js/matterjs-server/issues"
     },
-    "homepage": "https://github.com/matter-js/matterjs-server",
+    "author": "Open Home Foundation",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/matter-js/matterjs-server.git"
     },
-    "author": "Open Home Foundation",
+    "files": [
+        "dist/**/*",
+        "src/**/*",
+        "LICENSE",
+        "README.md"
+    ],
+    "type": "module",
     "main": "dist/esm/index.js",
+    "publishConfig": {
+        "access": "public"
+    },
     "scripts": {
         "clean": "nacho-build clean",
         "build": "nacho-build",
         "build-clean": "nacho-build --clean",
         "noble-ble-proxy": "nacho-run src/example/noble-ble-proxy.ts"
     },
-    "engines": {
-        "node": ">=20.19.0 <22.0.0 || >=22.13.0"
-    },
     "dependencies": {
-        "@matter/main": "0.17.0",
-        "@matter-server/ws-controller": "0.7.2-alpha.0-20260601-e778038",
+        "@matter-server/ws-controller": "0.8.0",
+        "@matter/main": "0.17.1-alpha.0-20260602-24f28a953",
         "ws": "^8.21.0"
     },
-    "optionalDependencies": {
-        "@matter/nodejs-ble": "0.17.0"
-    },
     "devDependencies": {
         "@types/node": "^25.9.1",
         "@types/ws": "^8.18.1"
     },
-    "files": [
-        "dist/**/*",
-        "src/**/*",
-        "LICENSE",
-        "README.md"
-    ],
-    "publishConfig": {
-        "access": "public"
+    "optionalDependencies": {
+        "@matter/nodejs-ble": "0.17.1-alpha.0-20260602-24f28a953",
+        "dbus-next": "npm:@jellybrick/dbus-next@^0.10.3"
+    },
+    "engines": {
+        "node": ">=22.13.0"
     }
 }

package/src/BleProxyConnection.ts

@@ -0,0 +1,282 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { createPromise, Logger, Observable, Seconds, Time, withTimeout } from "@matter/main";
+import { Mark } from "@matter/main/protocol";
+import { WebSocket } from "ws";
+import {
+    BLE_PROXY_PROTOCOL_VERSION,
+    decodeBinaryFrame,
+    encodeBinaryFrame,
+    type BinaryFrame,
+    type BleProxyCommandMap,
+    type BleProxyCommandName,
+    type BleProxyEventName,
+    type CommandMessage,
+    type EventMessage,
+    type HelloMessage,
+    type ResponseMessage,
+} from "./BleProxyProtocol.js";
+
+const logger = Logger.get("BleProxyConnection");
+
+const frameHead = (payload: Uint8Array): string =>
+    Array.from(payload.subarray(0, 8))
+        .map(b => b.toString(16).padStart(2, "0"))
+        .join("");
+
+/** Counter for generating unique connection IDs. */
+let connectionIdCounter = 0;
+
+/**
+ * Generate a unique connection ID as a hex string, rolling over at 0xFFFF to keep it short.
+ * Same scheme as the controller WebSocket handler, prefixed `ble` so proxy sockets are
+ * distinguishable from the controller WebSocket connections in shared logs.
+ */
+function generateConnectionId(): string {
+    const id = connectionIdCounter;
+    connectionIdCounter = (connectionIdCounter + 1) & 0xffff;
+    return `ble${id.toString(16)}`;
+}
+
+const HANDSHAKE_TIMEOUT = Seconds(10);
+/**
+ * Default per-command timeout. Long enough to cover the slowest BLE
+ * commissioning ops (peripheral connect ≤ 30 s, service discovery on
+ * Android-side adapters can take several seconds), short enough that an
+ * unresponsive-but-still-connected proxy client doesn't hang commissioning
+ * indefinitely.
+ */
+const COMMAND_TIMEOUT = Seconds(60);
+
+/**
+ * One BLE proxy client socket. Owns that client's handshake state, pending
+ * command map, and command/event/binary-frame plumbing. The hub
+ * (`BleProxyHandler`) creates one per accepted WebSocket connection.
+ */
+export class BleProxyConnection {
+    readonly #ws: WebSocket;
+    readonly #id = generateConnectionId();
+    #handshakeComplete = false;
+    #closedEmitted = false;
+    #pendingCommands = new Map<
+        number,
+        { resolver: (result: Record<string, unknown> | undefined) => void; rejecter: (reason?: unknown) => void }
+    >();
+    /** Command ID counter. Rolls over at 0xFFFF to stay in safe integer range. */
+    #nextCommandId = 0;
+
+    readonly binaryFrameReceived = new Observable<[frame: BinaryFrame]>();
+    readonly eventReceived = new Observable<[event: BleProxyEventName, data: Record<string, unknown>]>();
+    /** Emitted once when this connection completes the protocol handshake. */
+    readonly handshakeCompleted = new Observable<[]>();
+    /** Emitted once when this connection is torn down (close, error, or handshake failure). */
+    readonly closed = new Observable<[]>();
+
+    constructor(ws: WebSocket) {
+        this.#ws = ws;
+        logger.info(`[${this.#id}] BLE proxy connection established, waiting for handshake`);
+
+        const handshakeTimer = Time.getTimer("BLE proxy handshake timeout", HANDSHAKE_TIMEOUT, () => {
+            if (!this.#handshakeComplete) {
+                logger.warn(`[${this.#id}] Handshake timeout - closing connection`);
+                ws.close(4001, "Handshake timeout");
+                this.#cleanup();
+            }
+        }).start();
+
+        ws.on("message", (data, isBinary) => {
+            if (isBinary) {
+                this.#handleBinaryMessage(data as Buffer);
+            } else {
+                this.#handleTextMessage(data.toString(), handshakeTimer);
+            }
+        });
+
+        ws.on("close", () => {
+            handshakeTimer.stop();
+            logger.info(`[${this.#id}] BLE proxy connection closed`);
+            this.#cleanup();
+        });
+
+        ws.on("error", err => {
+            logger.error(`[${this.#id}] BLE proxy WebSocket error`, err);
+            handshakeTimer.stop();
+            this.#cleanup();
+        });
+    }
+
+    get id(): string {
+        return this.#id;
+    }
+
+    get connected(): boolean {
+        return this.#handshakeComplete && this.#ws.readyState === WebSocket.OPEN;
+    }
+
+    /**
+     * Send a typed command to this client and wait for the response.
+     * Rejects if the connection is not ready or the client disconnects first.
+     */
+    async sendCommand<C extends BleProxyCommandName>(
+        command: C,
+        ...rest: BleProxyCommandMap[C]["args"] extends undefined ? [] : [args: BleProxyCommandMap[C]["args"]]
+    ): Promise<BleProxyCommandMap[C]["result"]> {
+        if (!this.connected) {
+            throw new Error("BLE proxy client not connected");
+        }
+
+        const args = rest[0];
+        const id = this.#nextCommandId;
+        this.#nextCommandId = (this.#nextCommandId + 1) & 0xffff;
+        const message: CommandMessage = { id, command };
+        if (args !== undefined) {
+            message.args = args as Record<string, unknown>;
+        }
+
+        const { promise, resolver, rejecter } = createPromise<Record<string, unknown> | undefined>();
+        this.#pendingCommands.set(id, { resolver, rejecter });
+
+        this.#ws.send(JSON.stringify(message), err => {
+            if (err) {
+                this.#pendingCommands.delete(id);
+                rejecter(new Error(`Failed to send command ${command}: ${err.message}`));
+            }
+        });
+
+        return withTimeout(COMMAND_TIMEOUT, promise, () => this.#pendingCommands.delete(id)) as Promise<
+            BleProxyCommandMap[C]["result"]
+        >;
+    }
+
+    sendBinaryFrame(opcode: number, connectionHandle: number, payload: Uint8Array): void {
+        if (!this.connected) {
+            throw new Error("BLE proxy client not connected");
+        }
+        logger.debug(
+            `[${this.#id}] [FRAME] ${Mark.OUTBOUND} opcode=${opcode} handle=${connectionHandle} len=${payload.length} head=${frameHead(payload)}`,
+        );
+        this.#ws.send(encodeBinaryFrame(opcode, connectionHandle, payload));
+    }
+
+    #handleTextMessage(raw: string, handshakeTimer: { stop: () => void }): void {
+        let parsed: unknown;
+        try {
+            parsed = JSON.parse(raw);
+        } catch {
+            logger.warn(`[${this.#id}] Received invalid JSON from BLE proxy client`);
+            return;
+        }
+
+        const msg = parsed as Record<string, unknown>;
+
+        if (!this.#handshakeComplete) {
+            this.#handleHandshake(msg, handshakeTimer);
+            return;
+        }
+
+        if ("id" in msg && "success" in msg) {
+            this.#handleResponse(msg as unknown as ResponseMessage);
+            return;
+        }
+
+        if ("event" in msg && "data" in msg) {
+            const evt = msg as unknown as EventMessage;
+            this.eventReceived.emit(evt.event, evt.data);
+            return;
+        }
+
+        logger.warn(`[${this.#id}] Received unknown message from BLE proxy client:`, msg);
+    }
+
+    #handleHandshake(msg: Record<string, unknown>, handshakeTimer: { stop: () => void }): void {
+        if (msg.type !== "hello") {
+            logger.warn(`[${this.#id}] Expected hello message, got: ${JSON.stringify(msg)}`);
+            this.#ws.close(4002, "Expected hello message");
+            this.#cleanup();
+            return;
+        }
+
+        const hello = msg as unknown as HelloMessage;
+        handshakeTimer.stop();
+
+        if (hello.version !== BLE_PROXY_PROTOCOL_VERSION) {
+            logger.warn(
+                `[${this.#id}] BLE proxy client version ${hello.version} not supported (server supports ${BLE_PROXY_PROTOCOL_VERSION})`,
+            );
+            this.#ws.send(
+                JSON.stringify({
+                    type: "hello_response",
+                    version: BLE_PROXY_PROTOCOL_VERSION,
+                    error: "unsupported_version",
+                    message: `Server supports protocol version ${BLE_PROXY_PROTOCOL_VERSION}, client sent version ${hello.version}`,
+                }),
+            );
+            this.#ws.close(4003, "Unsupported protocol version");
+            this.#cleanup();
+            return;
+        }
+
+        this.#handshakeComplete = true;
+        this.#ws.send(JSON.stringify({ type: "hello_response", version: BLE_PROXY_PROTOCOL_VERSION }));
+        logger.info(`[${this.#id}] BLE proxy handshake complete (version ${BLE_PROXY_PROTOCOL_VERSION})`);
+        this.handshakeCompleted.emit();
+    }
+
+    #handleResponse(msg: ResponseMessage): void {
+        const pending = this.#pendingCommands.get(msg.id);
+        if (!pending) {
+            logger.warn(`[${this.#id}] Received response for unknown command id ${msg.id}`);
+            return;
+        }
+        this.#pendingCommands.delete(msg.id);
+
+        if (msg.success) {
+            pending.resolver(msg.result);
+        } else {
+            pending.rejecter(new Error(`${msg.error}: ${msg.message}`));
+        }
+    }
+
+    #handleBinaryMessage(data: Buffer): void {
+        if (!this.#handshakeComplete) {
+            logger.warn(`[${this.#id}] Received binary frame before handshake`);
+            return;
+        }
+
+        try {
+            const frame = decodeBinaryFrame(new Uint8Array(data));
+            logger.debug(
+                `[${this.#id}] [FRAME] ${Mark.INBOUND} opcode=${frame.opcode} handle=${frame.connectionHandle} len=${frame.payload.length} head=${frameHead(frame.payload)}`,
+            );
+            this.binaryFrameReceived.emit(frame);
+        } catch (err) {
+            logger.warn(`[${this.#id}] Failed to decode binary frame:`, err);
+        }
+    }
+
+    /** Close the socket if open, reject all pending commands, emit `closed` once. */
+    close(): void {
+        if (this.#ws.readyState === WebSocket.OPEN) {
+            this.#ws.close();
+        }
+        this.#cleanup();
+    }
+
+    #cleanup(): void {
+        this.#handshakeComplete = false;
+
+        for (const [id, pending] of this.#pendingCommands) {
+            pending.rejecter(new Error("BLE proxy client disconnected"));
+            this.#pendingCommands.delete(id);
+        }
+
+        if (!this.#closedEmitted) {
+            this.#closedEmitted = true;
+            this.closed.emit();
+        }
+    }
+}