feat: add QrKeyringDeferredPromiseBridge

Author: mikesposito

packages/keyring-eth-qr/package.json

@@ -55,6 +55,7 @@
     "@metamask/eth-sig-util": "^8.2.0",
     "@metamask/keyring-utils": "workspace:^",
     "@metamask/utils": "^11.1.0",
+    "async-mutex": "^0.5.0",
     "hdkey": "^2.1.0",
     "uuid": "^9.0.1"
   },

packages/keyring-eth-qr/src/qr-keyring-deferred-promise-bridge.test.ts

@@ -0,0 +1,90 @@
+import { type QrScanRequest, QrScanRequestType } from './qr-keyring';
+import { QrKeyringDeferredPromiseBridge } from './qr-keyring-deferred-promise-bridge';
+
+describe('QrKeyringDeferredPromiseBridge', () => {
+  describe('requestScan', () => {
+    it('calls `onScanRequested` if any', async () => {
+      const request: QrScanRequest = {
+        type: QrScanRequestType.PAIR,
+      };
+      const onScanRequested = jest.fn();
+      const bridge = new QrKeyringDeferredPromiseBridge({
+        onScanRequested,
+      });
+      onScanRequested.mockImplementation(() => {
+        bridge.resolvePendingScan({
+          type: 'test',
+          cbor: 'testData',
+        });
+      });
+
+      await bridge.requestScan(request);
+
+      expect(onScanRequested).toHaveBeenCalledWith(request);
+    });
+  });
+
+  describe('resolvePendingScan', () => {
+    it('resolves the pending scan with the given result', async () => {
+      const request: QrScanRequest = {
+        type: QrScanRequestType.PAIR,
+      };
+      const result = {
+        type: 'test',
+        cbor: 'testData',
+      };
+      const onScanRequested = jest.fn();
+      const onScanResolved = jest.fn();
+      const bridge = new QrKeyringDeferredPromiseBridge({
+        onScanRequested,
+        onScanResolved,
+      });
+      onScanRequested.mockImplementation(() => {
+        bridge.resolvePendingScan(result);
+      });
+
+      const pendingScan = await bridge.requestScan(request);
+
+      expect(onScanResolved).toHaveBeenCalledWith(result);
+      expect(pendingScan).toStrictEqual(result);
+    });
+
+    it('throws an error if no pending scan exists', () => {
+      const bridge = new QrKeyringDeferredPromiseBridge();
+
+      expect(() => {
+        bridge.resolvePendingScan({ type: 'test', cbor: 'testData' });
+      }).toThrow('No pending scan to resolve.');
+    });
+  });
+
+  describe('rejectPendingScan', () => {
+    it('calls `onScanRejected` if any', async () => {
+      const error = new Error('Test error');
+      const onScanRejected = jest.fn();
+      const onScanRequested = jest.fn();
+      const bridge = new QrKeyringDeferredPromiseBridge({
+        onScanRequested,
+        onScanRejected,
+      });
+      onScanRequested.mockImplementation(() => {
+        bridge.rejectPendingScan(error);
+      });
+
+      await expect(
+        bridge.requestScan({
+          type: QrScanRequestType.PAIR,
+        }),
+      ).rejects.toThrow(error);
+      expect(onScanRejected).toHaveBeenCalledWith(error);
+    });
+
+    it('throws an error if no pending scan exists', () => {
+      const bridge = new QrKeyringDeferredPromiseBridge();
+
+      expect(() => {
+        bridge.rejectPendingScan(new Error('Test error'));
+      }).toThrow('No pending scan to reject.');
+    });
+  });
+});

packages/keyring-eth-qr/src/qr-keyring-deferred-promise-bridge.ts

@@ -0,0 +1,95 @@
+import { type DeferredPromise, createDeferredPromise } from '@metamask/utils';
+import { Mutex } from 'async-mutex';
+
+import type {
+  QrKeyringBridge,
+  QrScanRequest,
+  SerializedUR,
+} from './qr-keyring';
+
+export type QrKeyringScannerOptions = {
+  /**
+   * Callback invoked when a scan request is made.
+   * This can be used to trigger the actual scanning process.
+   */
+  onScanRequested?: (request: QrScanRequest) => void;
+  /**
+   * Callback invoked when a scan is successfully resolved.
+   * This can be used to handle the result of the scan.
+   */
+  onScanResolved?: (result: SerializedUR) => void;
+  /**
+   * Callback invoked when a scan is rejected with an error.
+   * This can be used to handle errors that occur during the scan.
+   */
+  onScanRejected?: (error: Error) => void;
+};
+
+/**
+ * A bridge that turns the scan request into a deferred promise, allowing
+ * the consumer to control the resolution and rejection of the scan.
+ */
+export class QrKeyringDeferredPromiseBridge implements QrKeyringBridge {
+  readonly #lock = new Mutex();
+
+  readonly #onScanRequested?: ((request: QrScanRequest) => void) | undefined;
+
+  readonly #onScanResolved?: ((result: SerializedUR) => void) | undefined;
+
+  readonly #onScanRejected?: ((error: Error) => void) | undefined;
+
+  #pendingScan?: DeferredPromise<SerializedUR> | null;
+
+  constructor({
+    onScanRequested,
+    onScanResolved,
+    onScanRejected,
+  }: QrKeyringScannerOptions = {}) {
+    this.#onScanRequested = onScanRequested;
+    this.#onScanResolved = onScanResolved;
+    this.#onScanRejected = onScanRejected;
+  }
+
+  /**
+   * Request a QR code scan, obtaining a CBOR and a type as response.
+   *
+   * @param request - The type of QR scan request.
+   * @returns A promise that resolves with the scanned data as a serialized UR.
+   */
+  async requestScan(request: QrScanRequest): Promise<SerializedUR> {
+    return this.#lock.runExclusive(async () => {
+      const deferredPromise = createDeferredPromise<SerializedUR>();
+      this.#pendingScan = deferredPromise;
+      this.#onScanRequested?.(request);
+      return deferredPromise.promise;
+    });
+  }
+
+  /**
+   * Resolve the pending scan with the given result.
+   *
+   * @param result - The scanned data as a serialized UR.
+   */
+  resolvePendingScan(result: SerializedUR): void {
+    if (!this.#pendingScan) {
+      throw new Error('No pending scan to resolve.');
+    }
+    this.#pendingScan.resolve(result);
+    this.#pendingScan = null;
+    this.#onScanResolved?.(result);
+  }
+
+  /**
+   * Reject the pending scan with the given error.
+   *
+   * @param error - The error to reject the scan with.
+   */
+  rejectPendingScan(error: Error): void {
+    if (!this.#pendingScan) {
+      throw new Error('No pending scan to reject.');
+    }
+    this.#pendingScan.reject(error);
+    this.#pendingScan = null;
+    this.#onScanRejected?.(error);
+  }
+}

yarn.lock

@@ -1732,6 +1732,7 @@ __metadata:
     "@types/hdkey": "npm:^2.0.1"
     "@types/jest": "npm:^29.5.12"
     "@types/node": "npm:^20.12.12"
+    async-mutex: "npm:^0.5.0"
     deepmerge: "npm:^4.2.2"
     depcheck: "npm:^1.4.7"
     hdkey: "npm:^2.1.0"