@ledgerhq/hw-transport - npm Package Compare versions

Comparing version 6.28.8 to 6.29.0-nightly.0

CHANGELOG.md

 # @ledgerhq/hw-transport
 
+## 6.29.0-nightly.0
+
+### Minor Changes
+
+- [#4709](https://github.com/LedgerHQ/ledger-live/pull/4709) [`9e2d32aec4`](https://github.com/LedgerHQ/ledger-live/commit/9e2d32aec4ebd8774880f94e3ef0e805ebb172ac) Thanks [@alexandremgo](https://github.com/alexandremgo)! - feat: usage of new tracing system
+
+  The tracing helps keeping a context (for ex a `job id`) that is propagated to other logs,
+  creating a (simple) tracing span
+
+### Patch Changes
+
+- Updated dependencies [[`9e2d32aec4`](https://github.com/LedgerHQ/ledger-live/commit/9e2d32aec4ebd8774880f94e3ef0e805ebb172ac)]:
+  - @ledgerhq/logs@6.11.0-nightly.0
+  - @ledgerhq/devices@8.0.8-nightly.0
+
 ## 6.28.8
@@ -4,0 +19,0 @@

lib-es/Transport.d.ts

@@ -6,2 +6,3 @@ /// <reference types="node" />
 import { TransportError, StatusCodes, getAltStatusMessage, TransportStatusError } from "@ledgerhq/errors";
+import { LocalTracer, TraceContext, LogType } from "@ledgerhq/logs";
 export { TransportError, TransportStatusError, StatusCodes, getAltStatusMessage };
@@ -47,2 +48,7 @@ /**
     deviceModel: DeviceModel | null | undefined;
+    tracer: LocalTracer;
+    constructor({ context, logType }?: {
+        context?: TraceContext;
+        logType?: LogType;
+    });
     /**
@@ -86,2 +92,3 @@ * Check if the transport is supported on the current platform/browser.
      * @param {number} timeout - An optional timeout for the transport connection.
+     * @param {TraceContext} context Optional tracing/log context
      * @returns {Promise<Transport>} A promise that resolves with a Transport instance.
@@ -91,3 +98,3 @@ * @example
      */
-    static readonly open: (descriptor?: any, timeout?: number) => Promise<Transport>;
+    static readonly open: (descriptor?: any, timeoutMs?: number, context?: TraceContext) => Promise<Transport>;
     /**
@@ -170,2 +177,11 @@ * Send data to the device using a low level API.
     decorateAppAPIMethod<R, A extends any[]>(methodName: string, f: (...args: A) => Promise<R>, ctx: any, scrambleKey: string): (...args: A) => Promise<R>;
+    /**
+     * Updates the context used by the logging/tracing mechanism
+     *
+     * Useful when re-using (cached) the same Transport instance,
+     * but with a new tracing context.
+     *
+     * @param context A TraceContext, that can undefined to reset the context
+     */
+    setTraceContext(context?: TraceContext): void;
     static ErrorMessage_ListenTimeout: string;
@@ -172,0 +188,0 @@ static ErrorMessage_NoDeviceFound: string;

lib-es/Transport.js

@@ -12,3 +12,5 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
 import { TransportRaceCondition, TransportError, StatusCodes, getAltStatusMessage, TransportStatusError, } from "@ledgerhq/errors";
+import { LocalTracer } from "@ledgerhq/logs";
 export { TransportError, TransportStatusError, StatusCodes, getAltStatusMessage };
+const DEFAULT_LOG_TYPE = "transport";
 /**
@@ -20,3 +22,3 @@ * The Transport class defines a generic interface for communicating with a Ledger hardware wallet.
 class Transport {
-    constructor() {
+    constructor({ context, logType } = {}) {
         this.exchangeTimeout = 30000;
@@ -48,5 +50,9 @@ this.unresponsiveTimeout = 15000;
         this.exchangeAtomicImpl = (f) => __awaiter(this, void 0, void 0, function* () {
+            const tracer = this.tracer.withUpdatedContext({ function: "exchangeAtomicImpl" });
+            tracer.trace("Starting an atomic APDU exchange");
             if (this.exchangeBusyPromise) {
+                tracer.trace("Atomic exchange is already busy");
                 throw new TransportRaceCondition("An action was already pending on the Ledger device. Please deny or reconnect.");
             }
+            // Sets the atomic guard
             let resolveBusy;
@@ -59,2 +65,3 @@ const busyPromise = new Promise(r => {
             const timeout = setTimeout(() => {
+                tracer.trace(`Timeout reached, emitting Transport event "unresponsive"`);
                 unresponsiveReached = true;
@@ -65,3 +72,5 @@ this.emit("unresponsive");
                 const res = yield f();
+                tracer.trace("Received a response from atomic exchange");
                 if (unresponsiveReached) {
+                    tracer.trace("Device was unresponsive, emitting responsive");
                     this.emit("responsive");
@@ -79,2 +88,3 @@ }
         this._appAPIlock = null;
+        this.tracer = new LocalTracer(logType !== null && logType !== void 0 ? logType : DEFAULT_LOG_TYPE, context);
     }
@@ -231,2 +241,13 @@ /**
     }
+    /**
+     * Updates the context used by the logging/tracing mechanism
+     *
+     * Useful when re-using (cached) the same Transport instance,
+     * but with a new tracing context.
+     *
+     * @param context A TraceContext, that can undefined to reset the context
+     */
+    setTraceContext(context) {
+        this.tracer = this.tracer.withContext(context);
+    }
 }
@@ -233,0 +254,0 @@ Transport.ErrorMessage_ListenTimeout = "No Ledger device found (timeout)";

lib/Transport.d.ts

@@ -6,2 +6,3 @@ /// <reference types="node" />
 import { TransportError, StatusCodes, getAltStatusMessage, TransportStatusError } from "@ledgerhq/errors";
+import { LocalTracer, TraceContext, LogType } from "@ledgerhq/logs";
 export { TransportError, TransportStatusError, StatusCodes, getAltStatusMessage };
@@ -47,2 +48,7 @@ /**
     deviceModel: DeviceModel | null | undefined;
+    tracer: LocalTracer;
+    constructor({ context, logType }?: {
+        context?: TraceContext;
+        logType?: LogType;
+    });
     /**
@@ -86,2 +92,3 @@ * Check if the transport is supported on the current platform/browser.
      * @param {number} timeout - An optional timeout for the transport connection.
+     * @param {TraceContext} context Optional tracing/log context
      * @returns {Promise<Transport>} A promise that resolves with a Transport instance.
@@ -91,3 +98,3 @@ * @example
      */
-    static readonly open: (descriptor?: any, timeout?: number) => Promise<Transport>;
+    static readonly open: (descriptor?: any, timeoutMs?: number, context?: TraceContext) => Promise<Transport>;
     /**
@@ -170,2 +177,11 @@ * Send data to the device using a low level API.
     decorateAppAPIMethod<R, A extends any[]>(methodName: string, f: (...args: A) => Promise<R>, ctx: any, scrambleKey: string): (...args: A) => Promise<R>;
+    /**
+     * Updates the context used by the logging/tracing mechanism
+     *
+     * Useful when re-using (cached) the same Transport instance,
+     * but with a new tracing context.
+     *
+     * @param context A TraceContext, that can undefined to reset the context
+     */
+    setTraceContext(context?: TraceContext): void;
     static ErrorMessage_ListenTimeout: string;
@@ -172,0 +188,0 @@ static ErrorMessage_NoDeviceFound: string;

lib/Transport.js

@@ -22,2 +22,4 @@ "use strict";
 Object.defineProperty(exports, "TransportStatusError", { enumerable: true, get: function () { return errors_1.TransportStatusError; } });
+const logs_1 = require("@ledgerhq/logs");
+const DEFAULT_LOG_TYPE = "transport";
 /**
@@ -29,3 +31,3 @@ * The Transport class defines a generic interface for communicating with a Ledger hardware wallet.
 class Transport {
-    constructor() {
+    constructor({ context, logType } = {}) {
         this.exchangeTimeout = 30000;
@@ -57,5 +59,9 @@ this.unresponsiveTimeout = 15000;
         this.exchangeAtomicImpl = (f) => __awaiter(this, void 0, void 0, function* () {
+            const tracer = this.tracer.withUpdatedContext({ function: "exchangeAtomicImpl" });
+            tracer.trace("Starting an atomic APDU exchange");
             if (this.exchangeBusyPromise) {
+                tracer.trace("Atomic exchange is already busy");
                 throw new errors_1.TransportRaceCondition("An action was already pending on the Ledger device. Please deny or reconnect.");
             }
+            // Sets the atomic guard
             let resolveBusy;
@@ -68,2 +74,3 @@ const busyPromise = new Promise(r => {
             const timeout = setTimeout(() => {
+                tracer.trace(`Timeout reached, emitting Transport event "unresponsive"`);
                 unresponsiveReached = true;
@@ -74,3 +81,5 @@ this.emit("unresponsive");
                 const res = yield f();
+                tracer.trace("Received a response from atomic exchange");
                 if (unresponsiveReached) {
+                    tracer.trace("Device was unresponsive, emitting responsive");
                     this.emit("responsive");
@@ -88,2 +97,3 @@ }
         this._appAPIlock = null;
+        this.tracer = new logs_1.LocalTracer(logType !== null && logType !== void 0 ? logType : DEFAULT_LOG_TYPE, context);
     }
@@ -240,2 +250,13 @@ /**
     }
+    /**
+     * Updates the context used by the logging/tracing mechanism
+     *
+     * Useful when re-using (cached) the same Transport instance,
+     * but with a new tracing context.
+     *
+     * @param context A TraceContext, that can undefined to reset the context
+     */
+    setTraceContext(context) {
+        this.tracer = this.tracer.withContext(context);
+    }
 }
@@ -242,0 +263,0 @@ Transport.ErrorMessage_ListenTimeout = "No Ledger device found (timeout)";

package.json

 {
   "name": "@ledgerhq/hw-transport",
-  "version": "6.28.8",
+  "version": "6.29.0-nightly.0",
   "description": "Ledger Hardware Wallet common interface of the communication layer",
@@ -29,4 +29,5 @@ "keywords": [
     "events": "^3.3.0",
-    "@ledgerhq/devices": "^8.0.7",
-    "@ledgerhq/errors": "^6.14.0"
+    "@ledgerhq/devices": "^8.0.8-nightly.0",
+    "@ledgerhq/errors": "^6.14.0",
+    "@ledgerhq/logs": "^6.11.0-nightly.0"
   },
@@ -33,0 +34,0 @@ "gitHead": "dd0dea64b58e5a9125c8a422dcffd29e5ef6abec",

README.md

@@ -23,20 +23,23 @@ <img src="https://user-images.githubusercontent.com/4631227/191834116-59cf590e-25cc-4956-ae5c-812ea464f324.png" height="100" />
 *   [Transport](#transport)
+    *   [Parameters](#parameters)
     *   [exchange](#exchange)
-        *   [Parameters](#parameters)
+        *   [Parameters](#parameters-1)
     *   [exchangeBulk](#exchangebulk)
-        *   [Parameters](#parameters-1)
+        *   [Parameters](#parameters-2)
     *   [setScrambleKey](#setscramblekey)
-        *   [Parameters](#parameters-2)
+        *   [Parameters](#parameters-3)
     *   [close](#close)
     *   [on](#on)
-        *   [Parameters](#parameters-3)
+        *   [Parameters](#parameters-4)
     *   [off](#off)
-        *   [Parameters](#parameters-4)
+        *   [Parameters](#parameters-5)
     *   [setDebugMode](#setdebugmode)
     *   [setExchangeTimeout](#setexchangetimeout)
-        *   [Parameters](#parameters-5)
+        *   [Parameters](#parameters-6)
     *   [setExchangeUnresponsiveTimeout](#setexchangeunresponsivetimeout)
-        *   [Parameters](#parameters-6)
+        *   [Parameters](#parameters-7)
     *   [send](#send)
-        *   [Parameters](#parameters-7)
+        *   [Parameters](#parameters-8)
+    *   [setTraceContext](#settracecontext)
+        *   [Parameters](#parameters-9)
     *   [isSupported](#issupported)
@@ -46,9 +49,9 @@ *   [list](#list)
     *   [listen](#listen)
-        *   [Parameters](#parameters-8)
+        *   [Parameters](#parameters-10)
         *   [Examples](#examples-1)
     *   [open](#open)
-        *   [Parameters](#parameters-9)
+        *   [Parameters](#parameters-11)
         *   [Examples](#examples-2)
     *   [create](#create)
-        *   [Parameters](#parameters-10)
+        *   [Parameters](#parameters-12)
         *   [Examples](#examples-3)
@@ -88,2 +91,9 @@
 
+#### Parameters
+
+*   `$0` **{context: TraceContext?, logType: LogType?}**  (optional, default `{}`)
+
+    *   `$0.context`  
+    *   `$0.logType`  
+
 #### exchange
@@ -196,2 +206,13 @@
 
+#### setTraceContext
+
+Updates the context used by the logging/tracing mechanism
+
+Useful when re-using (cached) the same Transport instance,
+but with a new tracing context.
+
+##### Parameters
+
+*   `context` **TraceContext?** A TraceContext, that can undefined to reset the context
+
 #### isSupported
@@ -254,3 +275,3 @@
 
-Type: function (descriptor: any, timeout: [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)): [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Transport](#transport)>
+Type: function (descriptor: any, timeoutMs: [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number), context: TraceContext): [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Transport](#transport)>
 
@@ -261,2 +282,3 @@ ##### Parameters
 *   `timeout` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** An optional timeout for the transport connection.
+*   `context` **TraceContext** Optional tracing/log context
 
@@ -263,0 +285,0 @@ ##### Examples

src/Transport.ts

@@ -10,3 +10,5 @@ import EventEmitter from "events";
 } from "@ledgerhq/errors";
+import { LocalTracer, TraceContext, LogType } from "@ledgerhq/logs";
 export { TransportError, TransportStatusError, StatusCodes, getAltStatusMessage };
+const DEFAULT_LOG_TYPE = "transport";
 
@@ -56,3 +58,8 @@ /**
   deviceModel: DeviceModel | null | undefined = null;
+  tracer: LocalTracer;
 
+  constructor({ context, logType }: { context?: TraceContext; logType?: LogType } = {}) {
+    this.tracer = new LocalTracer(logType ?? DEFAULT_LOG_TYPE, context);
+  }
+
   /**
@@ -99,2 +106,3 @@ * Check if the transport is supported on the current platform/browser.
    * @param {number} timeout - An optional timeout for the transport connection.
+   * @param {TraceContext} context Optional tracing/log context
    * @returns {Promise<Transport>} A promise that resolves with a Transport instance.
@@ -104,3 +112,7 @@ * @example
    */
-  static readonly open: (descriptor?: any, timeout?: number) => Promise<Transport>;
+  static readonly open: (
+    descriptor?: any,
+    timeoutMs?: number,
+    context?: TraceContext,
+  ) => Promise<Transport>;
 
@@ -291,3 +303,7 @@ /**
   exchangeAtomicImpl = async (f: () => Promise<Buffer | void>): Promise<Buffer | void> => {
+    const tracer = this.tracer.withUpdatedContext({ function: "exchangeAtomicImpl" });
+    tracer.trace("Starting an atomic APDU exchange");
+
     if (this.exchangeBusyPromise) {
+      tracer.trace("Atomic exchange is already busy");
       throw new TransportRaceCondition(
@@ -298,2 +314,3 @@ "An action was already pending on the Ledger device. Please deny or reconnect.",
 
+    // Sets the atomic guard
     let resolveBusy;
@@ -306,2 +323,3 @@ const busyPromise: Promise<void> = new Promise(r => {
     const timeout = setTimeout(() => {
+      tracer.trace(`Timeout reached, emitting Transport event "unresponsive"`);
       unresponsiveReached = true;
@@ -313,4 +331,6 @@ this.emit("unresponsive");
       const res = await f();
+      tracer.trace("Received a response from atomic exchange");
 
       if (unresponsiveReached) {
+        tracer.trace("Device was unresponsive, emitting responsive");
         this.emit("responsive");
@@ -360,4 +380,16 @@ }
 
+  /**
+   * Updates the context used by the logging/tracing mechanism
+   *
+   * Useful when re-using (cached) the same Transport instance,
+   * but with a new tracing context.
+   *
+   * @param context A TraceContext, that can undefined to reset the context
+   */
+  setTraceContext(context?: TraceContext) {
+    this.tracer = this.tracer.withContext(context);
+  }
+
   static ErrorMessage_ListenTimeout = "No Ledger device found (timeout)";
   static ErrorMessage_NoDeviceFound = "No Ledger device found";
 }

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

100480

increased by8.45%

Lines of code

1230

increased by9.14%

Number of lines in readme file

305

increased by7.77%

Worsened metrics

Dependency count

4

increased by33.33%

Number of low quality alerts

1

increased byInfinity%

Dependency changes

• + Added@ledgerhq/logs@^6.11.0-nightly.0

• Updated@ledgerhq/devices@^8.0.8-nightly.0