@onekeyfe/hd-transport 1.2.0-alpha.1 → 1.2.0-alpha.11

package/src/protocols/v2/session.ts

@@ -1,6 +1,6 @@
 import { PROTOCOL_V2_PACKET_SRC_COMMAND } from '../../constants';
 import { ProtocolV2FrameAssembler, concatUint8Arrays } from './frame-assembler';
-import { nextProtoSeq } from './encode';
+import { ProtocolV2SequenceCursor } from './sequence-cursor';
 import { ProtocolV2 } from '..';
 import * as check from '../../utils/highlevel-checks';
 import { LogBlockCommand } from '../../utils/logBlockCommand';
@@ -13,6 +13,13 @@ export type ProtocolV2Schemas = {
   protocolV2: Root;
 };
 
+export type ProtocolV2CallContext = {
+  messageName: string;
+  timeoutMs?: number;
+  highVolume: boolean;
+  generation: number;
+};
+
 type ProtocolLogger = {
   debug?: (...args: any[]) => void;
   error?: (...args: any[]) => void;
@@ -22,11 +29,15 @@ export type ProtocolV2SessionOptions = {
   schemas: ProtocolV2Schemas;
   router: number;
   packetSrc?: number;
-  writeFrame: (frame: Uint8Array) => Promise<void>;
-  readFrame: () => Promise<Uint8Array>;
+  maxFrameBytes?: number;
+  prepareCall?: (context: ProtocolV2CallContext) => Promise<void> | void;
+  writeFrame: (frame: Uint8Array, context: ProtocolV2CallContext) => Promise<void>;
+  readFrame: (context: ProtocolV2CallContext) => Promise<Uint8Array>;
   logger?: ProtocolLogger;
   logPrefix?: string;
   createTimeoutError?: (name: string, timeoutMs: number) => Error;
+  sequenceCursor?: ProtocolV2SequenceCursor;
+  generation?: number;
 };
 
 export type ProtocolV2CallOptions = {
@@ -37,6 +48,7 @@ export type ProtocolV2CallOptions = {
 };
 
 export { concatUint8Arrays, ProtocolV2FrameAssembler };
+export { ProtocolV2SequenceCursor };
 
 export function hexToBytes(hex: string): Uint8Array {
   const clean = hex.replace(/\s+/g, '');
@@ -229,24 +241,23 @@ export async function withProtocolTimeout<T>(
   }
 }
 
-// Watchdog for the write phase only. Writing a single frame (max 4608 bytes)
-// is a bounded transport operation, unlike the read phase where long-running
-// device operations (firmware install, user confirmation) can legitimately
-// take minutes — so no default timeout is applied to reads.
-export const PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS = 30000;
+// Write completion is owned by the concrete transport. A Promise.race watchdog
+// here can return while libusb/WebUSB is still flushing a large Protocol V2
+// frame, which desynchronizes later request/response pairs.
+export const PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS = 0;
 
 export class ProtocolV2Session {
   private readonly options: ProtocolV2SessionOptions;
 
+  private readonly sequenceCursor: ProtocolV2SequenceCursor;
+
   // Serializes call() invocations: responses are matched only by type, so two
   // in-flight calls on the same session would steal each other's responses.
   private pendingCall: Promise<unknown> = Promise.resolve();
 
-  // Per-session sequence counter (1-255, wraps skipping 0).
-  private protoSeq = 0;
-
   constructor(options: ProtocolV2SessionOptions) {
     this.options = options;
+    this.sequenceCursor = options.sequenceCursor ?? new ProtocolV2SequenceCursor();
   }
 
   call(
@@ -271,25 +282,41 @@ export class ProtocolV2Session {
       schemas,
       router,
       packetSrc = PROTOCOL_V2_PACKET_SRC_COMMAND,
+      maxFrameBytes,
+      prepareCall,
       writeFrame,
       readFrame,
       logger,
       logPrefix = 'ProtocolV2',
       createTimeoutError,
+      generation = 0,
     } = this.options;
 
     const shouldReduceDebug = shouldReduceProtocolV2Debug(name);
-    this.protoSeq = nextProtoSeq(this.protoSeq);
+    const callContext: ProtocolV2CallContext = {
+      messageName: name,
+      timeoutMs: callOptions.timeoutMs,
+      highVolume: shouldReduceDebug,
+      generation,
+    };
+    await prepareCall?.(callContext);
+    const protoSeq = this.sequenceCursor.next();
     const frame = ProtocolV2.encodeFrame(schemas, name, data, {
       packetSrc,
       router,
-      seq: this.protoSeq,
+      seq: protoSeq,
       logger: shouldReduceDebug ? undefined : logger,
       logPrefix,
       context: `tx:${name}`,
     });
     const expectedSeq = frame[6];
 
+    if (maxFrameBytes !== undefined && frame.length > maxFrameBytes) {
+      throw new Error(
+        `Protocol V2 frame too large for transport: ${frame.length} > ${maxFrameBytes}`
+      );
+    }
+
     if (!shouldReduceDebug) {
       logger?.debug?.(
         `[${logPrefix}] TX payload name=${name}`,
@@ -305,7 +332,7 @@ export class ProtocolV2Session {
     // Lenient watchdog on the write phase only — see
     // PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS for the rationale.
     await withProtocolTimeout(
-      writeFrame(frame),
+      writeFrame(frame, callContext),
       PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS,
       () =>
         new Error(
@@ -324,7 +351,7 @@ export class ProtocolV2Session {
       // terminal response. Consume those frames here so callers still see a
       // request/terminal-response shaped API.
       while (!cancellation.cancelled) {
-        const rxFrame = await readFrame();
+        const rxFrame = await readFrame(callContext);
         if (cancellation.cancelled) {
           // Timed out while waiting: drop the late frame and stop reading.
           break;
@@ -336,37 +363,45 @@ export class ProtocolV2Session {
             } seq=${rxFrame[6]} headerHex=${frameHeaderDebugHex(rxFrame)}`
           );
         }
-        const decoded = ProtocolV2.decodeFrame(schemas, rxFrame, {
-          logger: shouldReduceDebug ? undefined : logger,
-          logPrefix,
-          context: `rx:${name}`,
-        });
-        if (!shouldReduceDebug && decoded.seq !== expectedSeq) {
-          logger?.debug?.(
-            `[${logPrefix}] seq differs for ${name}: tx=${expectedSeq}, rx=${decoded.seq}`
-          );
-        }
-        if (!shouldReduceDebug) {
-          logger?.debug?.(
-            `[${logPrefix}] TX name=${name} seq=${expectedSeq} | RX seq=${decoded.seq} messageTypeId=${decoded.messageTypeId} pbPayload=${decoded.pbPayload.length}B`
-          );
-          logger?.debug?.(
-            `[${logPrefix}] RX payload type=${decoded.type} messageTypeId=${decoded.messageTypeId}`,
-            sanitizeProtocolV2DebugPayload(decoded.message)
-          );
+        const isAck = ProtocolV2.isAckFrame(rxFrame);
+        if (isAck) {
+          if (!shouldReduceDebug) {
+            logger?.debug?.(`[${logPrefix}] skip Proto Link ACK seq=${rxFrame[6]}`);
+          }
         }
-
-        const response = check.call(decoded);
-        if (callOptions.intermediateTypes?.includes(response.type)) {
-          callOptions.onIntermediateResponse?.(response);
-        } else if (isExpectedTerminalResponse(response, callOptions.expectedTypes)) {
-          return response;
-        } else if (!shouldReduceDebug) {
-          logger?.debug?.(
-            `[${logPrefix}] skip unexpected response for ${name}: expected=${callOptions.expectedTypes?.join(
-              '|'
-            )} got=${response.type}`
-          );
+        if (!isAck) {
+          const decoded = ProtocolV2.decodeFrame(schemas, rxFrame, {
+            logger: shouldReduceDebug ? undefined : logger,
+            logPrefix,
+            context: `rx:${name}`,
+          });
+          if (!shouldReduceDebug && decoded.seq !== expectedSeq) {
+            logger?.debug?.(
+              `[${logPrefix}] seq differs for ${name}: tx=${expectedSeq}, rx=${decoded.seq}`
+            );
+          }
+          if (!shouldReduceDebug) {
+            logger?.debug?.(
+              `[${logPrefix}] TX name=${name} seq=${expectedSeq} | RX seq=${decoded.seq} messageTypeId=${decoded.messageTypeId} pbPayload=${decoded.pbPayload.length}B`
+            );
+            logger?.debug?.(
+              `[${logPrefix}] RX payload type=${decoded.type} messageTypeId=${decoded.messageTypeId}`,
+              sanitizeProtocolV2DebugPayload(decoded.message)
+            );
+          }
+
+          const response = check.call(decoded);
+          if (callOptions.intermediateTypes?.includes(response.type)) {
+            callOptions.onIntermediateResponse?.(response);
+          } else if (isExpectedTerminalResponse(response, callOptions.expectedTypes)) {
+            return response;
+          } else if (!shouldReduceDebug) {
+            logger?.debug?.(
+              `[${logPrefix}] skip unexpected response for ${name}: expected=${callOptions.expectedTypes?.join(
+                '|'
+              )} got=${response.type}`
+            );
+          }
         }
       }
       // Only reachable after cancellation; the outer promise has already been

package/src/protocols/v2/usb-transport-base.ts

@@ -0,0 +1,194 @@
+import { ProtocolV2FrameAssembler } from './frame-assembler';
+import { ProtocolV2LinkManager } from './link-manager';
+
+import type { MessageFromOneKey, TransportCallOptions } from '../../types';
+import type { ProtocolV2CallContext, ProtocolV2Schemas, ProtocolV2SessionOptions } from './session';
+
+export type ProtocolV2UsbTransportBaseOptions = {
+  router: number;
+  maxFrameBytes: number;
+  logPrefix: string;
+};
+
+type ProtocolV2UsbCancellation = {
+  generation: number;
+  reason?: string;
+  promise: Promise<string>;
+  cancel: (reason: string) => void;
+};
+
+export abstract class ProtocolV2UsbTransportBase<Key> {
+  private readonly protocolV2UsbLinks: ProtocolV2LinkManager<Key>;
+
+  private readonly protocolV2UsbAssemblers = new Map<Key, ProtocolV2FrameAssembler>();
+
+  private readonly protocolV2UsbGenerations = new Map<Key, number>();
+
+  private readonly protocolV2UsbCancellations = new Map<Key, ProtocolV2UsbCancellation>();
+
+  private readonly protocolV2UsbOptions: ProtocolV2UsbTransportBaseOptions;
+
+  protected constructor(options: ProtocolV2UsbTransportBaseOptions) {
+    this.protocolV2UsbOptions = options;
+    this.protocolV2UsbLinks = new ProtocolV2LinkManager<Key>({
+      getSchemas: () => this.getProtocolV2UsbSchemas(),
+      classifyError: () => 'link-fatal',
+      onLinkInvalidated: async (key, reason) => {
+        this.protocolV2UsbAssemblers.get(key)?.reset();
+        await this.resetProtocolV2UsbNativeLink(key, reason);
+        await this.onProtocolV2UsbLinkInvalidated(key, reason);
+      },
+    });
+  }
+
+  protected abstract getProtocolV2UsbSchemas(): ProtocolV2Schemas;
+
+  protected abstract getProtocolV2UsbLogger(): ProtocolV2SessionOptions['logger'];
+
+  protected abstract writeProtocolV2UsbPacket(
+    key: Key,
+    frame: Uint8Array,
+    context: ProtocolV2CallContext
+  ): Promise<void>;
+
+  protected abstract readProtocolV2UsbPacket(
+    key: Key,
+    context: ProtocolV2CallContext
+  ): Promise<Uint8Array>;
+
+  protected abstract resetProtocolV2UsbNativeLink(key: Key, reason: string): Promise<void>;
+
+  protected abstract createProtocolV2UsbTimeoutError(name: string, timeoutMs: number): Error;
+
+  protected onProtocolV2UsbLinkInvalidated(_key: Key, _reason: string): Promise<void> | void {
+    // 子类按需清理协议缓存或记录平台日志。
+  }
+
+  protected async rotateProtocolV2UsbGeneration(key: Key, reason: string): Promise<number> {
+    await this.protocolV2UsbLinks.invalidateLink(key, reason);
+    const generation = (this.protocolV2UsbGenerations.get(key) ?? 0) + 1;
+    this.protocolV2UsbGenerations.set(key, generation);
+    this.protocolV2UsbCancellations.set(key, this.createProtocolV2UsbCancellation(generation));
+    this.protocolV2UsbAssemblers.set(
+      key,
+      new ProtocolV2FrameAssembler(this.protocolV2UsbOptions.maxFrameBytes)
+    );
+    return generation;
+  }
+
+  protected callProtocolV2Usb(
+    key: Key,
+    name: string,
+    data: Record<string, unknown>,
+    options?: TransportCallOptions
+  ): Promise<MessageFromOneKey> {
+    return this.protocolV2UsbLinks.call(
+      key,
+      () => this.createProtocolV2UsbAdapter(key),
+      name,
+      data,
+      options
+    );
+  }
+
+  protected invalidateProtocolV2UsbLink(key: Key, reason: string): Promise<void> {
+    return this.protocolV2UsbLinks.invalidateLink(key, reason);
+  }
+
+  protected invalidateAllProtocolV2UsbLinks(reason: string): Promise<void> {
+    return this.protocolV2UsbLinks.invalidateAllLinks(reason);
+  }
+
+  protected async disposeProtocolV2UsbLinks(reason: string): Promise<void> {
+    await this.protocolV2UsbLinks.dispose(reason);
+    this.protocolV2UsbAssemblers.clear();
+    this.protocolV2UsbGenerations.clear();
+    this.protocolV2UsbCancellations.clear();
+  }
+
+  private createProtocolV2UsbAdapter(key: Key) {
+    const generation = this.protocolV2UsbGenerations.get(key);
+    if (generation === undefined) {
+      throw new Error('Protocol V2 USB generation has not been initialized');
+    }
+    const cancellation = this.protocolV2UsbCancellations.get(key);
+    if (!cancellation || cancellation.generation !== generation) {
+      throw new Error('Protocol V2 USB cancellation state has not been initialized');
+    }
+
+    const assertCurrentGeneration = () => {
+      if (cancellation.reason) {
+        throw new Error(cancellation.reason);
+      }
+      if (this.protocolV2UsbGenerations.get(key) !== generation) {
+        throw new Error('Protocol V2 USB connection generation changed');
+      }
+    };
+
+    return {
+      router: this.protocolV2UsbOptions.router,
+      maxFrameBytes: this.protocolV2UsbOptions.maxFrameBytes,
+      generation,
+      prepareCall: () => {
+        assertCurrentGeneration();
+        this.getProtocolV2UsbAssembler(key).reset();
+      },
+      writeFrame: async (frame: Uint8Array, context: ProtocolV2CallContext) => {
+        assertCurrentGeneration();
+        await this.writeProtocolV2UsbPacket(key, frame, context);
+        assertCurrentGeneration();
+      },
+      readFrame: async (context: ProtocolV2CallContext) => {
+        assertCurrentGeneration();
+        const assembler = this.getProtocolV2UsbAssembler(key);
+        let frame = assembler.push(new Uint8Array(0));
+        while (!frame) {
+          const packetRead = this.readProtocolV2UsbPacket(key, context).then(packet => ({
+            packet,
+          }));
+          const cancelled = cancellation.promise.then(reason => ({ reason }));
+          const result = await Promise.race([packetRead, cancelled]);
+          if ('reason' in result) {
+            throw new Error(result.reason);
+          }
+          assertCurrentGeneration();
+          frame = assembler.push(result.packet);
+        }
+        assertCurrentGeneration();
+        return frame;
+      },
+      reset: (reason: string) => {
+        cancellation.cancel(reason);
+        this.protocolV2UsbAssemblers.get(key)?.reset();
+      },
+      logger: this.getProtocolV2UsbLogger(),
+      logPrefix: this.protocolV2UsbOptions.logPrefix,
+      createTimeoutError: (messageName: string, timeoutMs: number) =>
+        this.createProtocolV2UsbTimeoutError(messageName, timeoutMs),
+    };
+  }
+
+  private getProtocolV2UsbAssembler(key: Key): ProtocolV2FrameAssembler {
+    const assembler = this.protocolV2UsbAssemblers.get(key);
+    if (!assembler) {
+      throw new Error('Protocol V2 USB assembler has not been initialized');
+    }
+    return assembler;
+  }
+
+  private createProtocolV2UsbCancellation(generation: number): ProtocolV2UsbCancellation {
+    let resolveCancellation: (reason: string) => void = () => undefined;
+    const cancellation: ProtocolV2UsbCancellation = {
+      generation,
+      promise: new Promise(resolve => {
+        resolveCancellation = resolve;
+      }),
+      cancel: reason => {
+        if (cancellation.reason) return;
+        cancellation.reason = reason;
+        resolveCancellation(reason);
+      },
+    };
+    return cancellation;
+  }
+}

package/src/serialization/protobuf/messages.ts

@@ -30,7 +30,12 @@ export const createMessageFromName = (messages: protobuf.Root, name: string) =>
 export const createMessageFromType = (messages: protobuf.Root, typeId: number) => {
   const MessageType = messages.lookupEnum('MessageType');
 
-  const messageName = MessageType.valuesById[typeId].replace('MessageType_', '');
+  const rawMessageName = MessageType.valuesById[typeId];
+  if (!rawMessageName) {
+    throw new Error(`MessageType id "${typeId}" is not defined in protobuf schema`);
+  }
+
+  const messageName = rawMessageName.replace('MessageType_', '');
 
   const Message = messages.lookupType(messageName);