@onekeyfe/hd-transport-web-device 1.2.0-alpha.13 → 1.2.0-alpha.131

package/src/webusb.ts

@@ -6,8 +6,8 @@ import transport, {
   PROTOCOL_V1_USB_PACKET_SIZE,
   PROTOCOL_V2_CHANNEL_USB,
   PROTOCOL_V2_FRAME_MAX_BYTES,
-  ProtocolV2FrameAssembler,
-  ProtocolV2Session,
+  ProtocolV2LinkError,
+  ProtocolV2UsbTransportBase,
   probeProtocolV2 as probeProtocolV2Helper,
 } from '@onekeyfe/hd-transport';
 import {
@@ -19,12 +19,12 @@ import {
 } from '@onekeyfe/hd-shared';
 import ByteBuffer from 'bytebuffer';
 
-import { createTransportCallLog, shouldSuppressHighVolumeCallLog } from './transportLog';
-
 import type {
   AcquireInput,
   OneKeyDeviceInfoBase,
   ProtocolType,
+  ProtocolV2CallContext,
+  ProtocolV2Schemas,
   TransportCallOptions,
 } from '@onekeyfe/hd-transport';
 
@@ -39,7 +39,12 @@ const REPORT_ID = PROTOCOL_V1_REPORT_ID;
 const HEADER_LENGTH = PROTOCOL_V1_MESSAGE_HEADER_SIZE;
 const PACKET_IO_MAX_RETRIES = 3;
 const PACKET_IO_RETRY_DELAY = 300;
-const PROTOCOL_PROBE_TIMEOUT = 1000;
+// Legacy devices can take longer to answer Initialize after a WebUSB reset.
+// Keep this aligned with Node USB so a slow Protocol V1 response is not
+// misreported as a protocol mismatch during acquire.
+const PROTOCOL_V1_PROBE_TIMEOUT = 5000;
+const PROTOCOL_V2_PROBE_TIMEOUT = 1000;
+const EXPECTED_PROTOCOL_V2_PROBE_ATTEMPTS = 2;
 function inferProtocolHintFromDeviceName(name?: string | null): ProtocolType | undefined {
   return /\bpro\s*2\b/i.test(name ?? '') ? 'V2' : undefined;
 }
@@ -64,38 +69,22 @@ interface TransferCancelToken {
   cancelled: boolean;
 }
 
-export default class WebUsbTransport {
+export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string> {
   messages: ReturnType<typeof transport.parseConfigure> | undefined;
 
   /** Protobuf schema for Protocol V2 transports. */
   messagesV2: ReturnType<typeof transport.parseConfigure> | undefined;
 
+  private protocolV2SchemaSource: string | undefined;
+
   /** Per-path protocol type detected by active wire-level probe. */
   private deviceProtocol: Map<string, ProtocolType> = new Map();
 
   private deviceProtocolHints: Map<string, ProtocolType> = new Map();
 
-  /** 按设备缓存 Protocol V2 frame assembler，保留同一次读取里多出来的后续 frame。 */
-  private protocolV2Assemblers: Map<string, ProtocolV2FrameAssembler> = new Map();
-
-  /** 按设备缓存 Protocol V2 session，保持 seq 与设备会话一致递增。 */
-  private protocolV2Sessions: Map<string, ProtocolV2Session> = new Map();
-
-  /** 当前 Protocol V2 调用的读取超时，由缓存 session 的 readFrame 闭包读取。 */
-  private protocolV2ReadTimeouts: Map<string, number | undefined> = new Map();
-
   /** Per-path USB endpoint / interface numbers (discovered from USB descriptors) */
   private deviceEndpoints: Map<string, DeviceEndpoints> = new Map();
 
-  /**
-   * 早期 Pro2 工程板 USB descriptor 没有烧录 serial number。
-   * 为这类设备生成会话内稳定的 mock path（同一 USBDevice 实例复用同一 path），
-   * 避免设备因为空 serial 被发现流程整体丢弃。重新插拔后实例变化，path 会重新生成。
-   */
-  private mockSerialPaths: WeakMap<USBDevice, string> = new WeakMap();
-
-  private mockSerialCounter = 0;
-
   name = 'WebUsbTransport';
 
   stopped = false;
@@ -118,6 +107,14 @@ export default class WebUsbTransport {
 
   interfaceId = INTERFACE_ID;
 
+  constructor() {
+    super({
+      router: PROTOCOL_V2_CHANNEL_USB,
+      maxFrameBytes: PROTOCOL_V2_FRAME_MAX_BYTES,
+      logPrefix: 'ProtocolV2 WebUSB',
+    });
+  }
+
   /**
    * Initialize WebUSB transport
    */
@@ -147,9 +144,20 @@ export default class WebUsbTransport {
    * Cache the Protocol V2 protobuf schema.
    */
   configureProtocolV2(signedData: any) {
+    const schemaSource =
+      typeof signedData === 'string'
+        ? signedData
+        : JSON.stringify(signedData) ?? String(signedData);
+    if (schemaSource === this.protocolV2SchemaSource) return;
+
+    const hadProtocolV2Schema = this.protocolV2SchemaSource !== undefined;
     this.messagesV2 = parseConfigure(signedData);
-    this.protocolV2Sessions.clear();
-    this.protocolV2ReadTimeouts.clear();
+    this.protocolV2SchemaSource = schemaSource;
+    if (!hadProtocolV2Schema) return;
+
+    this.invalidateAllProtocolV2UsbLinks('Protocol V2 schema reconfigured').catch(error =>
+      this.Log?.debug('[WebUsbTransport] schema link cleanup failed:', error)
+    );
   }
 
   /**
@@ -181,26 +189,6 @@ export default class WebUsbTransport {
     return this.deviceList;
   }
 
-  /**
-   * 设备 path：正常设备直接用 USB serial number；
-   * 空 serial（早期工程板）回退到会话内稳定的 mock path。
-   */
-  private getDevicePath(device: USBDevice): string {
-    if (typeof device.serialNumber === 'string' && device.serialNumber.length > 0) {
-      return device.serialNumber;
-    }
-    let path = this.mockSerialPaths.get(device);
-    if (!path) {
-      this.mockSerialCounter += 1;
-      path = `mock-serial:${device.vendorId.toString(16)}:${device.productId.toString(16)}:${
-        this.mockSerialCounter
-      }`;
-      this.mockSerialPaths.set(device, path);
-      this.Log?.debug(`[WebUSB] device has no serial number, using mock path: ${path}`);
-    }
-    return path;
-  }
-
   /**
    * Get list of connected devices
    */
@@ -213,11 +201,12 @@ export default class WebUsbTransport {
         (desc: { vendorId: number; productId: number }) =>
           dev.vendorId === desc.vendorId && dev.productId === desc.productId
       );
-      return isOneKey && !isKnownTrezorWebUsbDevice(dev);
+      const hasSerialNumber = typeof dev.serialNumber === 'string' && dev.serialNumber.length > 0;
+      return isOneKey && hasSerialNumber && !isKnownTrezorWebUsbDevice(dev);
     });
 
     this.deviceList = onekeyDevices.map(device => {
-      const path = this.getDevicePath(device);
+      const path = device.serialNumber as string;
       const protocolHint = inferProtocolHintFromDeviceName(device.productName);
       if (protocolHint) {
         this.deviceProtocolHints.set(path, protocolHint);
@@ -239,13 +228,16 @@ export default class WebUsbTransport {
   async acquire(input: AcquireInput) {
     if (!input.path) return;
     try {
+      await this.rotateProtocolV2UsbGeneration(input.path, 'WebUSB transport acquired');
       await this.closeOpenDevice(input.path);
       await this.connect(input.path ?? '', true);
       const deviceName = this.deviceList.find(device => device.path === input.path)?.device
         .productName;
       const protocolHint = input.expectedProtocol
         ? undefined
-        : this.deviceProtocolHints.get(input.path) ?? inferProtocolHintFromDeviceName(deviceName);
+        : input.protocolHint ??
+          this.deviceProtocolHints.get(input.path) ??
+          inferProtocolHintFromDeviceName(deviceName);
       if (protocolHint) {
         this.deviceProtocolHints.set(input.path, protocolHint);
       }
@@ -253,6 +245,7 @@ export default class WebUsbTransport {
       return await Promise.resolve(input.path);
     } catch (e) {
       this.Log.debug('acquire error: ', e instanceof Error ? `${e.name}: ${e.message}` : String(e));
+      await this.closeOpenDevice(input.path);
       throw e;
     }
   }
@@ -269,13 +262,17 @@ export default class WebUsbTransport {
     );
   }
 
-  private createProtocolDetectionError() {
+  private createProtocolProbeTimeoutError(expected: ProtocolType, attempts: number) {
     return ERRORS.TypedError(
-      HardwareErrorCode.RuntimeError,
-      'Unable to detect USB protocol: device did not respond to Protocol V1 Initialize or Protocol V2 Ping'
+      HardwareErrorCode.DeviceInitializeFailed,
+      `Protocol ${expected} probe timeout after ${attempts} attempts`
     );
   }
 
+  private createProtocolDetectionError() {
+    return ERRORS.TypedError(HardwareErrorCode.DeviceNotFound);
+  }
+
   private async detectProtocol(
     path: string,
     expectedProtocol?: ProtocolType,
@@ -286,29 +283,54 @@ export default class WebUsbTransport {
         this.deviceProtocol.set(path, 'V1');
         return 'V1';
       }
+      await this.closeConnectionAfterProbe(path);
       throw this.createProtocolMismatchError(expectedProtocol);
     }
 
     if (expectedProtocol === 'V2') {
-      // 免探测路径：调用方显式承诺该设备是 V2（例如固件升级重启后的重连场景，
-      // 上层已经探测过协议并通过 expectedProtocol 传回），这里不再重复探测。
-      this.deviceProtocol.set(path, 'V2');
-      return 'V2';
+      for (let attempt = 1; attempt <= EXPECTED_PROTOCOL_V2_PROBE_ATTEMPTS; attempt += 1) {
+        if (await this.probeProtocolV2(path)) {
+          this.deviceProtocol.set(path, 'V2');
+          return 'V2';
+        }
+        if (attempt < EXPECTED_PROTOCOL_V2_PROBE_ATTEMPTS) {
+          await this.resetConnectionAfterProbe(path);
+          this.Log?.debug(
+            `[WebUsbTransport] Protocol V2 probe timed out, retrying ${
+              attempt + 1
+            }/${EXPECTED_PROTOCOL_V2_PROBE_ATTEMPTS}`
+          );
+        } else {
+          await this.closeConnectionAfterProbe(path);
+        }
+      }
+      this.deviceProtocol.delete(path);
+      throw this.createProtocolProbeTimeoutError(
+        expectedProtocol,
+        EXPECTED_PROTOCOL_V2_PROBE_ATTEMPTS
+      );
     }
 
-    // 项目约束：协议判断必须在连接后主动探测，不能依赖设备名/PID/descriptor。
-    // 设备名 hint（如 "Pro 2"）只用于调整探测顺序：hint=V2 时先探 V2、失败回落 V1，
-    // 不能作为最终结论。
+    // Protocol must be actively probed after connection. Name, PID, and descriptors only
+    // influence probe order; a V2 hint probes V2 first and falls back to V1.
     const probeOrder: ProtocolType[] =
       protocolHint === 'V2' || this.deviceProtocol.get(path) === 'V2' ? ['V2', 'V1'] : ['V1', 'V2'];
 
-    for (const protocol of probeOrder) {
+    for (const [index, protocol] of probeOrder.entries()) {
       const detected =
         protocol === 'V1' ? await this.probeProtocolV1(path) : await this.probeProtocolV2(path);
       if (detected) {
         this.deviceProtocol.set(path, protocol);
         return protocol;
       }
+      if (index < probeOrder.length - 1) {
+        // A timed-out WebUSB transferIn cannot be cancelled in place. Closing and
+        // reopening the device guarantees the next protocol probe cannot consume a
+        // late response from the previous protocol generation.
+        await this.resetConnectionAfterProbe(path);
+      } else {
+        await this.closeConnectionAfterProbe(path);
+      }
     }
 
     this.deviceProtocol.delete(path);
@@ -420,16 +442,12 @@ export default class WebUsbTransport {
     // Discover endpoints from USB descriptors; descriptors are not used for protocol selection.
     const endpoints = this.discoverEndpoints(device);
     this.deviceEndpoints.set(path, endpoints);
-    this.protocolV2Assemblers.get(path)?.reset();
-    this.protocolV2Assemblers.set(path, new ProtocolV2FrameAssembler(PROTOCOL_V2_FRAME_MAX_BYTES));
-
     await device.claimInterface(endpoints.interfaceNumber);
     await this.clearEndpointHalt(device, 'in', endpoints.endpointIn);
     await this.clearEndpointHalt(device, 'out', endpoints.endpointOut);
   }
 
   private async closeOpenDevice(path: string) {
-    this.protocolV2Assemblers.get(path)?.reset();
     const current = this.deviceList.find(device => device.path === path)?.device;
     if (!current?.opened) return;
 
@@ -463,6 +481,10 @@ export default class WebUsbTransport {
   }
 
   async post(session: string, name: string, data: Record<string, unknown>) {
+    if (this.deviceProtocol.get(session) === 'V2') {
+      await this.sendProtocolV2UsbFlowControl(session, name, data);
+      return;
+    }
     await this.call(session, name, data);
   }
 
@@ -624,33 +646,30 @@ export default class WebUsbTransport {
     throw lastError;
   }
 
-  private async resetConnectionAfterProbe(path: string) {
-    this.protocolV2Assemblers.get(path)?.reset();
-    this.protocolV2Sessions.delete(path);
-    this.protocolV2ReadTimeouts.delete(path);
-
-    try {
-      const device = await this.findDevice(path);
-      if (device.opened) {
-        const endpoints = this.deviceEndpoints.get(path);
-        const ifaceNum = endpoints?.interfaceNumber ?? this.interfaceId;
-        try {
-          await device.releaseInterface(ifaceNum);
-        } catch (error) {
-          this.Log.debug('[WebUsbTransport] releaseInterface after protocol probe error:', error);
-        }
-        await device.close();
-      }
-    } catch (error) {
-      this.Log.debug('[WebUsbTransport] close after protocol probe error:', error);
+  private async transferInOnce(path: string, length: number): Promise<DataView> {
+    const device = await this.findDevice(path);
+    if (!device.opened) {
+      throw new Error('USBDevice is not open for transferIn');
     }
+    const endpoints = this.deviceEndpoints.get(path);
+    const endpointIn = endpoints?.endpointIn ?? this.endpointId;
+    const result = await device.transferIn(endpointIn, length);
+    return this.getTransferInData(result);
+  }
+
+  private async closeConnectionAfterProbe(path: string) {
+    await this.rotateProtocolV2UsbGeneration(path, 'WebUSB protocol probe reset');
+    await this.closeOpenDevice(path);
+  }
 
+  private async resetConnectionAfterProbe(path: string) {
+    await this.closeConnectionAfterProbe(path);
     await this.getConnectedDevices();
     await this.connect(path, false);
   }
 
   private async withProtocolReadTimeout<T>(
-    _path: string,
+    path: string,
     promise: Promise<T>,
     timeoutMs: number,
     protocol: ProtocolType,
@@ -672,9 +691,16 @@ export default class WebUsbTransport {
       return await Promise.race([
         guardedPromise,
         new Promise<never>((_, reject) => {
-          timer = setTimeout(() => {
+          timer = setTimeout(async () => {
             timedOut = true;
             onTimeout?.();
+            if (protocol === 'V1') {
+              try {
+                await this.resetConnectionAfterProbe(path);
+              } catch (error) {
+                this.Log.debug('[WebUsbTransport] reset after Protocol V1 timeout failed:', error);
+              }
+            }
             reject(new Error(`Protocol ${protocol} read timeout after ${timeoutMs}ms`));
           }, timeoutMs);
         }),
@@ -690,7 +716,14 @@ export default class WebUsbTransport {
     }
 
     try {
-      await this.callProtocolV1(path, 'Initialize', {}, { timeoutMs: PROTOCOL_PROBE_TIMEOUT });
+      await this.callProtocolV1(
+        path,
+        'Initialize',
+        {},
+        {
+          timeoutMs: PROTOCOL_V1_PROBE_TIMEOUT,
+        }
+      );
       return true;
     } catch (_error) {
       return false;
@@ -704,10 +737,9 @@ export default class WebUsbTransport {
 
     return probeProtocolV2Helper({
       call: (name, data, options) => this.callProtocolV2(path, name, data, options),
-      timeoutMs: PROTOCOL_PROBE_TIMEOUT,
+      timeoutMs: PROTOCOL_V2_PROBE_TIMEOUT,
       logger: this.Log,
       logPrefix: 'ProtocolV2 WebUSB',
-      onProbeFailed: () => this.resetConnectionAfterProbe(path),
     });
   }
 
@@ -737,10 +769,6 @@ export default class WebUsbTransport {
       );
     }
 
-    if (!shouldSuppressHighVolumeCallLog(name)) {
-      this.Log.debug('transport call', createTransportCallLog(name, protocol));
-    }
-
     if (protocol === 'V2') {
       return this.callProtocolV2(path, name, data, options);
     }
@@ -788,94 +816,7 @@ export default class WebUsbTransport {
     data: Record<string, unknown>,
     options?: TransportCallOptions
   ) {
-    const protocolV1Messages = this.messages;
-    if (!this.messagesV2) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.TransportNotConfigured,
-        'Protocol V2 schema not configured'
-      );
-    }
-    if (!protocolV1Messages) {
-      throw ERRORS.TypedError(HardwareErrorCode.TransportNotConfigured);
-    }
-
-    let session = this.protocolV2Sessions.get(path);
-    if (!session) {
-      session = new ProtocolV2Session({
-        schemas: {
-          protocolV1: protocolV1Messages,
-          protocolV2: this.messagesV2,
-        },
-        router: PROTOCOL_V2_CHANNEL_USB,
-        writeFrame: (frame: Uint8Array) => this.transferOutOnce(path, frame),
-        readFrame: () => this.receiveProtocolV2Frame(path, this.protocolV2ReadTimeouts.get(path)),
-        logger: this.Log,
-        logPrefix: 'ProtocolV2 WebUSB',
-        createTimeoutError: (messageName: string, timeoutMs: number) =>
-          new Error(`Protocol V2 response timeout after ${timeoutMs}ms for ${messageName}`),
-      });
-      this.protocolV2Sessions.set(path, session);
-    }
-
-    this.protocolV2ReadTimeouts.set(path, options?.timeoutMs);
-    this.protocolV2Assemblers.get(path)?.reset();
-    try {
-      return await session.call(name, data, options);
-    } catch (error) {
-      const message =
-        error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
-      if (message.includes('protocol v2 read timeout') || message.includes('response timeout')) {
-        try {
-          await this.resetConnectionAfterProbe(path);
-        } catch (resetError) {
-          this.Log.debug('[WebUsbTransport] Protocol V2 timeout reset failed:', resetError);
-        }
-      }
-      throw error;
-    } finally {
-      this.protocolV2ReadTimeouts.delete(path);
-    }
-  }
-
-  private async receiveProtocolV2Frame(path: string, timeoutMs?: number): Promise<Uint8Array> {
-    let assembler = this.protocolV2Assemblers.get(path);
-    if (!assembler) {
-      assembler = new ProtocolV2FrameAssembler(PROTOCOL_V2_FRAME_MAX_BYTES);
-      this.protocolV2Assemblers.set(path, assembler);
-    }
-
-    let frame: Uint8Array | undefined = assembler.push(new Uint8Array(0));
-    const deadline = timeoutMs ? Date.now() + timeoutMs : undefined;
-
-    while (!frame) {
-      const cancelToken = { cancelled: false };
-      const transferIn = this.transferInWithRetry(path, PROTOCOL_V2_FRAME_MAX_BYTES, cancelToken);
-      const dataView = deadline
-        ? await this.withProtocolReadTimeout(
-            path,
-            transferIn,
-            Math.max(deadline - Date.now(), 1),
-            'V2',
-            () => {
-              cancelToken.cancelled = true;
-            }
-          )
-        : await transferIn;
-      const bytes = new Uint8Array(
-        this.toArrayBuffer(
-          dataView.buffer.slice(dataView.byteOffset, dataView.byteOffset + dataView.byteLength)
-        )
-      );
-      try {
-        frame = assembler.push(bytes);
-      } catch (error) {
-        throw ERRORS.TypedError(
-          HardwareErrorCode.NetworkError,
-          error instanceof Error ? error.message : String(error)
-        );
-      }
-    }
-    return frame;
+    return this.callProtocolV2Usb(path, name, data, options);
   }
 
   /**
@@ -930,20 +871,63 @@ export default class WebUsbTransport {
    * Release device
    */
   async release(path: string) {
-    const device: USBDevice = await this.findDevice(path);
-    const endpoints = this.deviceEndpoints.get(path);
-    const ifaceNum = endpoints?.interfaceNumber ?? this.interfaceId;
-    await device.releaseInterface(ifaceNum);
-    await device.close();
+    await this.invalidateProtocolV2UsbLink(path, 'WebUSB transport released');
+    await this.closeOpenDevice(path);
     this.deviceProtocol.delete(path);
     this.deviceProtocolHints.delete(path);
-    this.protocolV2Assemblers.get(path)?.reset();
-    this.protocolV2Assemblers.delete(path);
-    this.protocolV2Sessions.delete(path);
-    this.protocolV2ReadTimeouts.delete(path);
     this.deviceEndpoints.delete(path);
   }
 
+  protected getProtocolV2UsbSchemas(): ProtocolV2Schemas {
+    if (!this.messages || !this.messagesV2) {
+      throw ERRORS.TypedError(HardwareErrorCode.TransportNotConfigured);
+    }
+    return {
+      protocolV1: this.messages,
+      protocolV2: this.messagesV2,
+    };
+  }
+
+  protected getProtocolV2UsbLogger() {
+    return this.Log;
+  }
+
+  protected async writeProtocolV2UsbPacket(
+    path: string,
+    frame: Uint8Array,
+    _context: ProtocolV2CallContext
+  ): Promise<void> {
+    await this.transferOutOnce(path, frame);
+  }
+
+  protected async readProtocolV2UsbPacket(
+    path: string,
+    _context: ProtocolV2CallContext
+  ): Promise<Uint8Array> {
+    const dataView = await this.transferInOnce(path, PROTOCOL_V2_FRAME_MAX_BYTES);
+    return new Uint8Array(
+      this.toArrayBuffer(
+        dataView.buffer.slice(dataView.byteOffset, dataView.byteOffset + dataView.byteLength)
+      )
+    );
+  }
+
+  protected async resetProtocolV2UsbNativeLink(path: string, _reason: string): Promise<void> {
+    await this.closeOpenDevice(path);
+  }
+
+  protected onProtocolV2UsbLinkInvalidated(path: string, reason: string) {
+    this.deviceProtocol.delete(path);
+    this.Log?.debug(`[WebUsbTransport] Protocol V2 link invalidated: ${path}`, reason);
+  }
+
+  protected createProtocolV2UsbTimeoutError(name: string, timeoutMs: number): Error {
+    return new ProtocolV2LinkError(
+      'response-timeout',
+      `Protocol V2 response timeout after ${timeoutMs}ms for ${name}`
+    );
+  }
+
   /**
    * Expose the detected protocol type for a given device path.
    * Used by upper layers (e.g. TransportManager) to select the correct schema.