@ledgerhq/react-native-hw-transport-ble 6.31.0 → 6.32.0-nightly.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @ledgerhq/react-native-hw-transport-ble
 
+## 6.32.0-nightly.0
+
+### Minor Changes
+
+- [#5171](https://github.com/LedgerHQ/ledger-live/pull/5171) [`52a373273d`](https://github.com/LedgerHQ/ledger-live/commit/52a373273dee3b2cb5a3e8d2d4b05f90616d71a2) Thanks [@alexandremgo](https://github.com/alexandremgo)! - Feat: new abort timeout on opening transport and APDU exchange
+
+  On `@ledgerhq/hw-transport`
+
+  - `exchange` adding an optional `abortTimeoutMs` arg to its definition
+  - `send` taking an optional `abortTimeoutMs` and passing it to `exchange`
+  - Some documentation and tracing
+
+  On `@ledgerhq/react-native-hw-transport-ble`
+
+  - `open`: enabling optional timeout when opening a transport instance
+  - `exchange`: enabling optional timeout on APDU exchange, calling `cancelPendingOperations` on timeout
+  - `cancelPendingOperations`: using a `currentTransactionIds` array of transactions id for each `write`, we can try to abort completely pending writes
+  - More documentation + tracing + simple unit tests
+
+### Patch Changes
+
+- Updated dependencies [[`52a373273d`](https://github.com/LedgerHQ/ledger-live/commit/52a373273dee3b2cb5a3e8d2d4b05f90616d71a2), [`52a373273d`](https://github.com/LedgerHQ/ledger-live/commit/52a373273dee3b2cb5a3e8d2d4b05f90616d71a2)]:
+  - @ledgerhq/hw-transport@6.30.1-nightly.0
+  - @ledgerhq/errors@6.16.1-nightly.0
+  - @ledgerhq/devices@8.2.0-nightly.0
+
 ## 6.31.0
 
 ### Minor Changes

package/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2017-present Ledger https://www.ledger.com/
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/lib/BleTransport.d.ts

@@ -4,7 +4,7 @@ import type { Subscription as TransportSubscription, Observer as TransportObserv
 import { DeviceId, Device, Characteristic } from "react-native-ble-plx";
 import type { DeviceModel } from "@ledgerhq/devices";
 import { TraceContext } from "@ledgerhq/logs";
-import { Observable, Observer } from "rxjs";
+import { Observable, Observer, SchedulerLike } from "rxjs";
 import { HwTransportError } from "@ledgerhq/errors";
 import { ReconnectionConfig } from "./types";
 export declare const setReconnectionConfig: (config: ReconnectionConfig | null | undefined) => void;
@@ -49,37 +49,82 @@ export default class BleTransport extends Transport {
      * Opens a BLE transport
      *
      * @param {Device | string} deviceOrId
-     * @param timeoutMs TODO: to keep, used in a separate PR
+     * @param timeoutMs Applied when trying to connect to a device
      * @param context An optional context object for log/tracing strategy
+     * @param injectedDependencies Contains optional injected dependencies used by the transport implementation
+     *  - rxjsScheduler: dependency injected RxJS scheduler to control time. Default AsyncScheduler.
      */
-    static open(deviceOrId: Device | string, timeoutMs?: number, context?: TraceContext): Promise<BleTransport>;
+    static open(deviceOrId: Device | string, timeoutMs?: number, context?: TraceContext, { rxjsScheduler }?: {
+        rxjsScheduler?: SchedulerLike;
+    }): Promise<BleTransport>;
     /**
      * Exposes method from the ble-plx library to disconnect a device
      *
      * Disconnects from {@link Device} if it's connected or cancels pending connection.
+     * A "disconnect" event will normally be emitted by the ble-plx lib once the device is disconnected.
+     * Errors are logged but silenced.
      */
-    static disconnect: (id: DeviceId, context?: TraceContext) => Promise<void>;
+    static disconnectDevice: (id: DeviceId, context?: TraceContext) => Promise<void>;
     device: Device;
     deviceModel: DeviceModel;
     disconnectTimeout: null | ReturnType<typeof setTimeout>;
     id: string;
     isConnected: boolean;
     mtuSize: number;
-    notifyObservable: Observable<any>;
+    notifyObservable: Observable<Buffer | Error>;
     notYetDisconnected: boolean;
-    writeCharacteristic: Characteristic;
-    writeCmdCharacteristic: Characteristic | undefined;
-    constructor(device: Device, writeCharacteristic: Characteristic, writeCmdCharacteristic: Characteristic | undefined, notifyObservable: Observable<any>, deviceModel: DeviceModel, { context }?: {
+    writableWithResponseCharacteristic: Characteristic;
+    writableWithoutResponseCharacteristic: Characteristic | undefined;
+    rxjsScheduler?: SchedulerLike;
+    currentTransactionIds: Array<string>;
+    /**
+     * The static `open` function is used to handle BleTransport instantiation
+     *
+     * @param device
+     * @param writableWithResponseCharacteristic A BLE characteristic that we can write on,
+     *   and that will be acknowledged in response from the device when it receives the written value.
+     * @param writableWithoutResponseCharacteristic A BLE characteristic that we can write on,
+     *   and that will not be acknowledged in response from the device
+     * @param notifyObservable A multicast observable that emits messages received from the device
+     * @param deviceModel
+     * @param params Contains optional options and injected dependencies used by the transport implementation
+     *  - abortTimeoutMs: stop the exchange after a given timeout. Another timeout exists
+     *    to detect unresponsive device (see `unresponsiveTimeout`). This timeout aborts the exchange.
+     *  - rxjsScheduler: dependency injected RxJS scheduler to control time. Default: AsyncScheduler.
+     */
+    constructor(device: Device, writableWithResponseCharacteristic: Characteristic, writableWithoutResponseCharacteristic: Characteristic | undefined, notifyObservable: Observable<Buffer | Error>, deviceModel: DeviceModel, { context, rxjsScheduler }?: {
         context?: TraceContext;
+        rxjsScheduler?: SchedulerLike;
     });
     /**
-     * Send data to the device using a low level API.
-     * It's recommended to use the "send" method for a higher level API.
+     * A message exchange (APDU request <-> response) with the device that can be aborted
+     *
+     * The message will be BLE-encoded/framed before being sent, and the response will be BLE-decoded.
+     *
+     * @param message A buffer (u8 array) of a none BLE-encoded message (an APDU for ex) to be sent to the device
+     *   as a request
+     * @param options Contains optional options for the exchange function
+     *  - abortTimeoutMs: stop the exchange after a given timeout. Another timeout exists
+     *    to detect unresponsive device (see `unresponsiveTimeout`). This timeout aborts the exchange.
+     * @returns A promise that resolves with the response data from the device.
+     */
+    exchange: (message: Buffer, { abortTimeoutMs }?: {
+        abortTimeoutMs?: number | undefined;
+    }) => Promise<Buffer>;
+    /**
+     * Tries to cancel all operations that have a recorded transaction and are pending
+     *
+     * Cancelling transaction which doesn't exist is ignored.
      *
-     * @param {Buffer} apdu - The data to send.
-     * @returns {Promise<Buffer>} A promise that resolves with the response data from the device.
+     * Note: cancelling `writableWithoutResponseCharacteristic.write...` will throw a `BleError` with code `OperationCancelled`
+     * but this error should be ignored. (In `exchange` our observable is unsubscribed before `cancelPendingOperations`
+     * is called so the error is ignored)
+     */
+    private cancelPendingOperations;
+    /**
+     * Sets the collection of current transaction ids to an empty array
      */
-    exchange: (apdu: Buffer) => Promise<any>;
+    private clearCurrentTransactionIds;
     /**
      * Negotiate with the device the maximum transfer unit for the ble frames
      * @returns Promise<number>
@@ -95,10 +140,16 @@ export default class BleTransport extends Transport {
     /**
      * Do not call this directly unless you know what you're doing. Communication
      * with a Ledger device should be through the {@link exchange} method.
-     * @param buffer
-     * @param txid
+     *
+     * For each call a transaction id is added to the current stack of transaction ids.
+     * With this transaction id, a pending BLE communication operations can be cancelled.
+     * Note: each frame/packet of a longer BLE-encoded message to be sent should have their unique transaction id.
+     *
+     * @param buffer BLE-encoded packet to send to the device
+     * @param frameId Frame id to make `write` aware of a bigger message that this frame/packet is part of.
+     *  Helps creating related a collection of transaction ids
      */
-    write: (buffer: Buffer, txid?: string | undefined) => Promise<void>;
+    write: (buffer: Buffer) => Promise<void>;
     /**
      * We intentionally do not immediately close a transport connection.
      * Instead, we queue the disconnect and wait for a future connection to dismiss the event.

package/lib/BleTransport.d.ts.map

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