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

package/src/protocols/v2/session.ts

@@ -1,12 +1,23 @@
-import { PROTOCOL_V2_PACKET_SRC_COMMAND } from '../../constants';
+import {
+  PROTOCOL_V2_DEFAULT_RESPONSE_TIMEOUT_MS,
+  PROTOCOL_V2_PACKET_SRC_COMMAND,
+} from '../../constants';
 import { ProtocolV2FrameAssembler, concatUint8Arrays } from './frame-assembler';
 import { ProtocolV2SequenceCursor } from './sequence-cursor';
+import {
+  ProtocolV2LinkError,
+  createProtocolV2LinkDisabledError,
+  isProtocolV2LinkDisabledError,
+  isProtocolV2LinkDisabledFailure,
+} from './errors';
 import { ProtocolV2 } from '..';
 import * as check from '../../utils/highlevel-checks';
 import { LogBlockCommand } from '../../utils/logBlockCommand';
 
 import type { Root } from 'protobufjs/light';
-import type { MessageFromOneKey } from '../../types';
+import type { MessageFromOneKey, TransportWriteMetrics } from '../../types';
+
+export * from './errors';
 
 export type ProtocolV2Schemas = {
   protocolV1: Root;
@@ -16,8 +27,10 @@ export type ProtocolV2Schemas = {
 export type ProtocolV2CallContext = {
   messageName: string;
   timeoutMs?: number;
-  highVolume: boolean;
+  highThroughput: boolean;
+  writeWithResponse?: boolean;
   generation: number;
+  signal: AbortSignal;
 };
 
 type ProtocolLogger = {
@@ -45,6 +58,9 @@ export type ProtocolV2CallOptions = {
   expectedTypes?: string[];
   intermediateTypes?: string[];
   onIntermediateResponse?: (response: MessageFromOneKey) => void;
+  onWriteCompleted?: (metrics: TransportWriteMetrics) => void;
+  returnAfterWrite?: boolean;
+  writeWithResponse?: boolean;
 };
 
 export { concatUint8Arrays, ProtocolV2FrameAssembler };
@@ -71,7 +87,7 @@ export function bytesToHex(bytes: Uint8Array): string {
     .join('');
 }
 
-const HIGH_VOLUME_PROTOCOL_V2_CALLS = new Set([
+const REDUCED_DEBUG_PROTOCOL_V2_CALLS = new Set([
   ...LogBlockCommand,
   'FilesystemFileRead',
   'FileRead',
@@ -79,7 +95,22 @@ const HIGH_VOLUME_PROTOCOL_V2_CALLS = new Set([
 ]);
 
 function shouldReduceProtocolV2Debug(name: string) {
-  return HIGH_VOLUME_PROTOCOL_V2_CALLS.has(name);
+  return REDUCED_DEBUG_PROTOCOL_V2_CALLS.has(name);
+}
+
+const HIGH_THROUGHPUT_PROTOCOL_V2_CALLS = new Set([
+  'FilesystemFileWrite',
+  'FileWrite',
+  'EmmcFileWrite',
+  'FirmwareUpload',
+  'ResourceAck',
+  'FilesystemFileRead',
+  'FileRead',
+  'EmmcFileRead',
+]);
+
+export function isProtocolV2HighThroughputCall(name: string) {
+  return HIGH_THROUGHPUT_PROTOCOL_V2_CALLS.has(name);
 }
 
 const COMMON_TERMINAL_RESPONSE_TYPES = new Set([
@@ -114,11 +145,13 @@ export async function withProtocolTimeout<T>(
   promise: Promise<T>,
   timeoutMs: number | undefined,
   createTimeoutError: () => Error,
-  onTimeout?: () => void
+  onTimeout?: () => void,
+  abortSignal?: AbortSignal
 ): Promise<T> {
   if (!timeoutMs) return promise;
 
   let timer: ReturnType<typeof setTimeout> | undefined;
+  let abortHandler: (() => void) | undefined;
   try {
     return await Promise.race([
       promise,
@@ -130,17 +163,29 @@ export async function withProtocolTimeout<T>(
           reject(createTimeoutError());
         }, timeoutMs);
       }),
+      ...(abortSignal
+        ? [
+            new Promise<never>((_, reject) => {
+              abortHandler = () => {
+                reject(new Error('Protocol V2 operation aborted'));
+              };
+              if (abortSignal.aborted) {
+                abortHandler();
+              } else {
+                abortSignal.addEventListener('abort', abortHandler, { once: true });
+              }
+            }),
+          ]
+        : []),
     ]);
   } finally {
     if (timer) clearTimeout(timer);
+    if (abortHandler) {
+      abortSignal?.removeEventListener('abort', abortHandler);
+    }
   }
 }
 
-// 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;
 
@@ -150,6 +195,12 @@ export class ProtocolV2Session {
   // in-flight calls on the same session would steal each other's responses.
   private pendingCall: Promise<unknown> = Promise.resolve();
 
+  // Flow-control messages may interrupt a call that is waiting for a device UI
+  // response, but their frames must never interleave with the active request write.
+  private pendingWrite: Promise<unknown> = Promise.resolve();
+
+  private lastResponseSequence?: number;
+
   constructor(options: ProtocolV2SessionOptions) {
     this.options = options;
     this.sequenceCursor = options.sequenceCursor ?? new ProtocolV2SequenceCursor();
@@ -168,7 +219,48 @@ export class ProtocolV2Session {
     return result;
   }
 
-  private async executeCall(
+  sendFlowControl(name: string, data: Record<string, unknown>): Promise<MessageFromOneKey> {
+    const {
+      schemas,
+      router,
+      packetSrc = PROTOCOL_V2_PACKET_SRC_COMMAND,
+      maxFrameBytes,
+      writeFrame,
+      generation = 0,
+    } = this.options;
+    const abortController = new AbortController();
+    const context: ProtocolV2CallContext = {
+      messageName: name,
+      highThroughput: false,
+      generation,
+      signal: abortController.signal,
+    };
+    const protoSeq = this.sequenceCursor.next();
+    const frame = ProtocolV2.encodeFrame(schemas, name, data, {
+      packetSrc,
+      router,
+      seq: protoSeq,
+    });
+
+    if (maxFrameBytes !== undefined && frame.length > maxFrameBytes) {
+      return Promise.reject(
+        new Error(`Protocol V2 frame too large for transport: ${frame.length} > ${maxFrameBytes}`)
+      );
+    }
+
+    return this.serializeWrite(() => writeFrame(frame, context)).then(() => ({
+      type: 'WriteCompleted',
+      message: {},
+    }));
+  }
+
+  private serializeWrite<T>(write: () => Promise<T>): Promise<T> {
+    const result = this.pendingWrite.then(write, write);
+    this.pendingWrite = result.catch(() => undefined);
+    return result;
+  }
+
+  private executeCall(
     name: string,
     data: Record<string, unknown>,
     callOptions: ProtocolV2CallOptions
@@ -186,81 +278,121 @@ export class ProtocolV2Session {
       createTimeoutError,
       generation = 0,
     } = this.options;
+    const timeoutMs =
+      callOptions.timeoutMs && callOptions.timeoutMs > 0
+        ? callOptions.timeoutMs
+        : PROTOCOL_V2_DEFAULT_RESPONSE_TIMEOUT_MS;
+    const abortController = new AbortController();
 
     const shouldReduceDebug = shouldReduceProtocolV2Debug(name);
-    const callContext: ProtocolV2CallContext = {
+    const baseCallContext: ProtocolV2CallContext = {
       messageName: name,
-      timeoutMs: callOptions.timeoutMs,
-      highVolume: shouldReduceDebug,
+      timeoutMs,
+      highThroughput: isProtocolV2HighThroughputCall(name),
+      ...(callOptions.writeWithResponse === undefined
+        ? {}
+        : { writeWithResponse: callOptions.writeWithResponse }),
       generation,
+      signal: abortController.signal,
     };
-    await prepareCall?.(callContext);
-    const protoSeq = this.sequenceCursor.next();
-    const frame = ProtocolV2.encodeFrame(schemas, name, data, {
-      packetSrc,
-      router,
-      seq: protoSeq,
-    });
-    const txMetadata = ProtocolV2.inspectFrame(schemas, frame);
 
-    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`, {
-        method: name,
-        type: name,
-        typeId: txMetadata.messageTypeId,
-        seq: txMetadata.seq,
-        bytes: frame.length,
+    const runCall = async (): Promise<MessageFromOneKey> => {
+      await prepareCall?.(baseCallContext);
+      const protoSeq = this.sequenceCursor.next();
+      const frame = ProtocolV2.encodeFrame(schemas, name, data, {
+        packetSrc,
+        router,
+        seq: protoSeq,
       });
-    }
 
-    // Lenient watchdog on the write phase only — see
-    // PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS for the rationale.
-    await withProtocolTimeout(
-      writeFrame(frame, callContext),
-      PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS,
-      () =>
-        new Error(
-          `Protocol V2 write timeout after ${PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS}ms for ${name}`
-        )
-    );
+      if (maxFrameBytes !== undefined && frame.length > maxFrameBytes) {
+        throw new Error(
+          `Protocol V2 frame too large for transport: ${frame.length} > ${maxFrameBytes}`
+        );
+      }
 
-    // Cancellation flag for the read loop: when the response timeout fires,
-    // Promise.race alone would leave this loop running as a zombie that keeps
-    // consuming frames meant for the next call. The timeout callback flips the
-    // flag so the loop exits and discards any late frame.
-    const cancellation = { cancelled: false };
+      const writeStartedAt = Date.now();
+      await this.serializeWrite(() => writeFrame(frame, baseCallContext));
+      try {
+        callOptions.onWriteCompleted?.({
+          elapsedMs: Math.max(Date.now() - writeStartedAt, 0),
+          frameBytes: frame.byteLength,
+        });
+      } catch (error) {
+        logger?.error?.(`${logPrefix} write metrics callback failed: ${String(error)}`);
+      }
+
+      if (callOptions.returnAfterWrite) {
+        return { type: 'WriteCompleted', message: {} };
+      }
 
-    const readResponse = async (): Promise<MessageFromOneKey> => {
       // Some Protocol V2 operations emit progress notifications before the
       // terminal response. Consume those frames here so callers still see a
       // request/terminal-response shaped API.
-      while (!cancellation.cancelled) {
-        const rxFrame = await readFrame(callContext);
-        if (cancellation.cancelled) {
-          // Timed out while waiting: drop the late frame and stop reading.
-          break;
+      while (!abortController.signal.aborted) {
+        const rxFrame = await readFrame(baseCallContext);
+        if (abortController.signal.aborted) break;
+
+        let header: ReturnType<typeof ProtocolV2.inspectFrameHeader>;
+        try {
+          header = ProtocolV2.inspectFrameHeader(rxFrame);
+        } catch (cause) {
+          throw new ProtocolV2LinkError(
+            'frame',
+            `Protocol V2 frame validation failed: ${getErrorMessage(cause)}`,
+            cause
+          );
+        }
+        if (header.router !== router) {
+          throw new ProtocolV2LinkError(
+            'router',
+            `Protocol V2 router mismatch: expected ${router}, got ${header.router}`
+          );
+        }
+        if (header.packetSrc !== packetSrc) {
+          throw new ProtocolV2LinkError(
+            'packet-source',
+            `Protocol V2 packet source mismatch: expected ${packetSrc}, got ${header.packetSrc}`
+          );
         }
-        const isAck = ProtocolV2.isAckFrame(rxFrame);
-        if (!isAck) {
-          const rxMetadata = ProtocolV2.inspectFrame(schemas, rxFrame);
-
-          if (!shouldReduceDebug) {
-            logger?.debug?.(`[${logPrefix}] RX`, {
-              method: name,
-              type: rxMetadata.type,
-              typeId: rxMetadata.messageTypeId,
-              seq: rxMetadata.seq,
-              bytes: rxFrame.length,
-            });
-          }
 
-          const decoded = ProtocolV2.decodeFrame(schemas, rxFrame);
+        let isAck: boolean;
+        try {
+          isAck = ProtocolV2.isAckFrame(rxFrame);
+        } catch (cause) {
+          throw new ProtocolV2LinkError(
+            'frame',
+            `Protocol V2 ACK validation failed: ${getErrorMessage(cause)}`,
+            cause
+          );
+        }
+        if (isAck) {
+          if (header.seq !== protoSeq) {
+            throw new ProtocolV2LinkError(
+              'ack-sequence',
+              `Protocol V2 ACK sequence mismatch: expected ${protoSeq}, got ${header.seq}`
+            );
+          }
+        } else {
+          let decoded: ReturnType<typeof ProtocolV2.decodeFrame>;
+          try {
+            decoded = ProtocolV2.decodeFrame(schemas, rxFrame);
+          } catch (cause) {
+            throw new ProtocolV2LinkError(
+              'frame',
+              `Protocol V2 frame decode failed: ${getErrorMessage(cause)}`,
+              cause
+            );
+          }
+          // Firmware owns one TX sequence across all channels and packet sources,
+          // so frames routed elsewhere create valid gaps in this session.
+          if (this.lastResponseSequence === decoded.seq) {
+            throw new ProtocolV2LinkError(
+              'response-sequence',
+              `Protocol V2 duplicate response sequence: ${decoded.seq}`
+            );
+          }
+          this.lastResponseSequence = decoded.seq;
 
           const response = check.call(decoded);
           if (callOptions.intermediateTypes?.includes(response.type)) {
@@ -276,20 +408,19 @@ export class ProtocolV2Session {
           }
         }
       }
-      // Only reachable after cancellation; the outer promise has already been
-      // rejected by the timeout, so this rejection is consumed by the race.
+
       throw new Error(`Protocol V2 read loop cancelled after timeout for ${name}`);
     };
 
     return withProtocolTimeout(
-      readResponse(),
-      callOptions.timeoutMs,
+      runCall(),
+      timeoutMs,
       () =>
         createTimeoutError
-          ? createTimeoutError(name, callOptions.timeoutMs ?? 0)
-          : new Error(`Protocol V2 response timeout after ${callOptions.timeoutMs}ms for ${name}`),
+          ? createTimeoutError(name, timeoutMs)
+          : new Error(`Protocol V2 response timeout after ${timeoutMs}ms for ${name}`),
       () => {
-        cancellation.cancelled = true;
+        abortController.abort();
       }
     );
   }
@@ -320,13 +451,26 @@ export async function probeProtocolV2({
     const response = await call(
       'Ping',
       { message: 'protocol-v2-probe' },
-      { timeoutMs, expectedTypes: ['Success'] }
+      {
+        timeoutMs,
+        expectedTypes: ['Success'],
+      }
     );
     if (response.type === 'Success') {
       return true;
     }
+    if (response.type === 'Failure') {
+      const failureCode = response.message?.code;
+      const firmwareMessage = response.message?.message;
+      if (isProtocolV2LinkDisabledFailure(failureCode, firmwareMessage)) {
+        throw createProtocolV2LinkDisabledError(failureCode, firmwareMessage);
+      }
+    }
     probeError = new Error(`unexpected response type ${response.type}`);
   } catch (error) {
+    if (isProtocolV2LinkDisabledError(error)) {
+      throw error;
+    }
     probeError = error;
   }
 

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

@@ -1,5 +1,7 @@
 import { ProtocolV2FrameAssembler } from './frame-assembler';
+import { ProtocolV2LinkError, isProtocolV2LinkError } from './errors';
 import { ProtocolV2LinkManager } from './link-manager';
+import { getErrorMessage } from './session';
 
 import type { MessageFromOneKey, TransportCallOptions } from '../../types';
 import type { ProtocolV2CallContext, ProtocolV2Schemas, ProtocolV2SessionOptions } from './session';
@@ -32,7 +34,7 @@ export abstract class ProtocolV2UsbTransportBase<Key> {
     this.protocolV2UsbOptions = options;
     this.protocolV2UsbLinks = new ProtocolV2LinkManager<Key>({
       getSchemas: () => this.getProtocolV2UsbSchemas(),
-      classifyError: () => 'link-fatal',
+      classifyError: error => (isProtocolV2LinkError(error) ? 'link-fatal' : 'recoverable'),
       onLinkInvalidated: async (key, reason) => {
         this.protocolV2UsbAssemblers.get(key)?.reset();
         await this.resetProtocolV2UsbNativeLink(key, reason);
@@ -61,7 +63,7 @@ export abstract class ProtocolV2UsbTransportBase<Key> {
   protected abstract createProtocolV2UsbTimeoutError(name: string, timeoutMs: number): Error;
 
   protected onProtocolV2UsbLinkInvalidated(_key: Key, _reason: string): Promise<void> | void {
-    // 子类按需清理协议缓存或记录平台日志。
+    // Subclasses may clear protocol caches or emit platform-specific diagnostics.
   }
 
   protected async rotateProtocolV2UsbGeneration(key: Key, reason: string): Promise<number> {
@@ -91,6 +93,19 @@ export abstract class ProtocolV2UsbTransportBase<Key> {
     );
   }
 
+  protected sendProtocolV2UsbFlowControl(
+    key: Key,
+    name: string,
+    data: Record<string, unknown>
+  ): Promise<MessageFromOneKey> {
+    return this.protocolV2UsbLinks.sendFlowControl(
+      key,
+      () => this.createProtocolV2UsbAdapter(key),
+      name,
+      data
+    );
+  }
+
   protected invalidateProtocolV2UsbLink(key: Key, reason: string): Promise<void> {
     return this.protocolV2UsbLinks.invalidateLink(key, reason);
   }
@@ -118,10 +133,13 @@ export abstract class ProtocolV2UsbTransportBase<Key> {
 
     const assertCurrentGeneration = () => {
       if (cancellation.reason) {
-        throw new Error(cancellation.reason);
+        throw new ProtocolV2LinkError('generation', cancellation.reason);
       }
       if (this.protocolV2UsbGenerations.get(key) !== generation) {
-        throw new Error('Protocol V2 USB connection generation changed');
+        throw new ProtocolV2LinkError(
+          'generation',
+          'Protocol V2 USB connection generation changed'
+        );
       }
     };
 
@@ -131,11 +149,14 @@ export abstract class ProtocolV2UsbTransportBase<Key> {
       generation,
       prepareCall: () => {
         assertCurrentGeneration();
-        this.getProtocolV2UsbAssembler(key).reset();
       },
       writeFrame: async (frame: Uint8Array, context: ProtocolV2CallContext) => {
         assertCurrentGeneration();
-        await this.writeProtocolV2UsbPacket(key, frame, context);
+        try {
+          await this.writeProtocolV2UsbPacket(key, frame, context);
+        } catch (error) {
+          throw this.createProtocolV2UsbIoError('write', error);
+        }
         assertCurrentGeneration();
       },
       readFrame: async (context: ProtocolV2CallContext) => {
@@ -143,13 +164,15 @@ export abstract class ProtocolV2UsbTransportBase<Key> {
         const assembler = this.getProtocolV2UsbAssembler(key);
         let frame = assembler.push(new Uint8Array(0));
         while (!frame) {
-          const packetRead = this.readProtocolV2UsbPacket(key, context).then(packet => ({
-            packet,
-          }));
+          const packetRead = this.readProtocolV2UsbPacket(key, context)
+            .then(packet => ({ packet }))
+            .catch(error => {
+              throw this.createProtocolV2UsbIoError('read', error);
+            });
           const cancelled = cancellation.promise.then(reason => ({ reason }));
           const result = await Promise.race([packetRead, cancelled]);
           if ('reason' in result) {
-            throw new Error(result.reason);
+            throw new ProtocolV2LinkError('generation', result.reason);
           }
           assertCurrentGeneration();
           frame = assembler.push(result.packet);
@@ -191,4 +214,13 @@ export abstract class ProtocolV2UsbTransportBase<Key> {
     };
     return cancellation;
   }
+
+  private createProtocolV2UsbIoError(operation: 'read' | 'write', error: unknown) {
+    if (isProtocolV2LinkError(error)) return error;
+    return new ProtocolV2LinkError(
+      'io',
+      `Protocol V2 USB ${operation} failed: ${getErrorMessage(error) || 'unknown error'}`,
+      error
+    );
+  }
 }

package/src/serialization/protobuf/decode.ts

@@ -70,7 +70,10 @@ function messageToJSON(Message: Message<Record<string, unknown>>, fields: Type['
     }
     // message type
     else if (field.resolvedType!.fields) {
-      res[key] = messageToJSON(value, field.resolvedType!.fields);
+      // [compatibility]: absent optional sub-messages are not own properties
+      // of the decoded instance, so value is undefined here; decode them to
+      // null, matching the optional primitive-field convention above.
+      res[key] = value == null ? null : messageToJSON(value, (field.resolvedType as Type).fields);
     } else {
       throw new Error(`case not handled: ${key}`);
     }

package/src/serialization/protobuf/encode.ts

@@ -1,5 +1,6 @@
 import { Buffer } from 'buffer';
 import ByteBuffer from 'bytebuffer';
+import { Enum } from 'protobufjs/light';
 
 import { isPrimitiveField } from '../../utils/protobuf';
 
@@ -49,7 +50,10 @@ export function patch(Message: Type, payload: any) {
     // repeated
     if (field.repeated) {
       const RefMessage = Message.lookupTypeOrEnum(field.type);
-      patched[key] = value.map((v: any) => patch(RefMessage, v));
+      patched[key] =
+        RefMessage instanceof Enum
+          ? value.map((v: any) => transform(field.type, v))
+          : value.map((v: any) => patch(RefMessage, v));
     }
     // message type
     else if (typeof value === 'object' && value !== null) {