@onekeyfe/hd-transport 1.2.0-alpha.8 → 1.2.0-alpha.80

package/src/protocols/v2/session.ts

@@ -1,18 +1,33 @@
-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 { nextProtoSeq } from './encode';
+import { ProtocolV2SequenceCursor } from './sequence-cursor';
+import { ProtocolV2LinkError } 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;
   protocolV2: Root;
 };
 
+export type ProtocolV2CallContext = {
+  messageName: string;
+  timeoutMs?: number;
+  highThroughput: boolean;
+  writeWithResponse?: boolean;
+  generation: number;
+  signal: AbortSignal;
+};
+
 type ProtocolLogger = {
   debug?: (...args: any[]) => void;
   error?: (...args: any[]) => void;
@@ -22,11 +37,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 = {
@@ -34,9 +53,12 @@ export type ProtocolV2CallOptions = {
   expectedTypes?: string[];
   intermediateTypes?: string[];
   onIntermediateResponse?: (response: MessageFromOneKey) => void;
+  onWriteCompleted?: (metrics: TransportWriteMetrics) => void;
+  writeWithResponse?: boolean;
 };
 
 export { concatUint8Arrays, ProtocolV2FrameAssembler };
+export { ProtocolV2SequenceCursor };
 
 export function hexToBytes(hex: string): Uint8Array {
   const clean = hex.replace(/\s+/g, '');
@@ -59,16 +81,7 @@ export function bytesToHex(bytes: Uint8Array): string {
     .join('');
 }
 
-// Frame header bytes worth logging: SOF, len lo/hi, header CRC, router, attr, seq.
-// The rest of the frame is protobuf payload and may contain sensitive fields
-// (mnemonic words via WordAck, PINs, seeds via LoadDevice, ...), so raw frame
-// hex logs must never include it.
-const PROTOCOL_V2_DEBUG_HEADER_BYTES = 7;
-const PROTOCOL_V2_DEBUG_ARRAY_ITEMS_LIMIT = 20;
-const PROTOCOL_V2_DEBUG_OBJECT_KEYS_LIMIT = 40;
-const PROTOCOL_V2_DEBUG_STRING_LIMIT = 512;
-const PROTOCOL_V2_DEBUG_DEPTH_LIMIT = 4;
-const HIGH_VOLUME_PROTOCOL_V2_CALLS = new Set([
+const REDUCED_DEBUG_PROTOCOL_V2_CALLS = new Set([
   ...LogBlockCommand,
   'FilesystemFileRead',
   'FileRead',
@@ -76,103 +89,22 @@ const HIGH_VOLUME_PROTOCOL_V2_CALLS = new Set([
 ]);
 
 function shouldReduceProtocolV2Debug(name: string) {
-  return HIGH_VOLUME_PROTOCOL_V2_CALLS.has(name);
-}
-
-function frameHeaderDebugHex(frame: Uint8Array): string {
-  // Only the frame header is dumped as hex; the payload is logged separately
-  // in sanitized/structured form (sanitizeProtocolV2DebugPayload).
-  return bytesToHex(frame.slice(0, PROTOCOL_V2_DEBUG_HEADER_BYTES));
-}
-
-function getBinaryByteLength(value: unknown): number | undefined {
-  if (value instanceof ArrayBuffer) {
-    return value.byteLength;
-  }
-
-  if (ArrayBuffer.isView(value)) {
-    return value.byteLength;
-  }
-
-  if (typeof Blob !== 'undefined' && value instanceof Blob) {
-    return value.size;
-  }
-
-  return undefined;
-}
-
-function summarizeRedactedData(value: unknown): string {
-  const byteLength = getBinaryByteLength(value);
-  if (byteLength !== undefined) {
-    return `[redacted data: ${byteLength} bytes]`;
-  }
-
-  if (typeof value === 'string') {
-    return `[redacted data: string length=${value.length}]`;
-  }
-
-  if (Array.isArray(value)) {
-    return `[redacted data: array length=${value.length}]`;
-  }
-
-  if (value && typeof value === 'object') {
-    return `[redacted data: object keys=${Object.keys(value).length}]`;
-  }
-
-  return `[redacted data: ${typeof value}]`;
+  return REDUCED_DEBUG_PROTOCOL_V2_CALLS.has(name);
 }
 
-function sanitizeProtocolV2DebugPayload(value: unknown, key = '', depth = 0): unknown {
-  if (/^(data|payload)$/i.test(key) && value !== null && value !== undefined) {
-    return summarizeRedactedData(value);
-  }
-
-  if (/(passphrase|pin|mnemonic|seed|private)/i.test(key)) {
-    return '[redacted sensitive value]';
-  }
-
-  const byteLength = getBinaryByteLength(value);
-  if (byteLength !== undefined) {
-    return `[binary: ${byteLength} bytes]`;
-  }
-
-  if (typeof value === 'string') {
-    return value.length > PROTOCOL_V2_DEBUG_STRING_LIMIT
-      ? `${value.slice(0, PROTOCOL_V2_DEBUG_STRING_LIMIT)}... (len=${value.length})`
-      : value;
-  }
-
-  if (!value || typeof value !== 'object') {
-    return value;
-  }
-
-  if (depth >= PROTOCOL_V2_DEBUG_DEPTH_LIMIT) {
-    return Array.isArray(value)
-      ? `[array length=${value.length}]`
-      : `[object keys=${Object.keys(value).length}]`;
-  }
-
-  if (Array.isArray(value)) {
-    const items = value
-      .slice(0, PROTOCOL_V2_DEBUG_ARRAY_ITEMS_LIMIT)
-      .map(item => sanitizeProtocolV2DebugPayload(item, key, depth + 1));
-    if (value.length > PROTOCOL_V2_DEBUG_ARRAY_ITEMS_LIMIT) {
-      items.push(`... (${value.length - PROTOCOL_V2_DEBUG_ARRAY_ITEMS_LIMIT} more)`);
-    }
-    return items;
-  }
+const HIGH_THROUGHPUT_PROTOCOL_V2_CALLS = new Set([
+  'FilesystemFileWrite',
+  'FileWrite',
+  'EmmcFileWrite',
+  'FirmwareUpload',
+  'ResourceAck',
+  'FilesystemFileRead',
+  'FileRead',
+  'EmmcFileRead',
+]);
 
-  const entries = Object.entries(value).slice(0, PROTOCOL_V2_DEBUG_OBJECT_KEYS_LIMIT);
-  const sanitized: Record<string, unknown> = {};
-  entries.forEach(([entryKey, entryValue]) => {
-    sanitized[entryKey] = sanitizeProtocolV2DebugPayload(entryValue, entryKey, depth + 1);
-  });
-  if (Object.keys(value).length > PROTOCOL_V2_DEBUG_OBJECT_KEYS_LIMIT) {
-    sanitized.__truncated__ = `${
-      Object.keys(value).length - PROTOCOL_V2_DEBUG_OBJECT_KEYS_LIMIT
-    } more keys`;
-  }
-  return sanitized;
+export function isProtocolV2HighThroughputCall(name: string) {
+  return HIGH_THROUGHPUT_PROTOCOL_V2_CALLS.has(name);
 }
 
 const COMMON_TERMINAL_RESPONSE_TYPES = new Set([
@@ -207,11 +139,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,
@@ -223,29 +157,43 @@ 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;
 
+  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;
+  private lastResponseSequence?: number;
 
   constructor(options: ProtocolV2SessionOptions) {
     this.options = options;
+    this.sequenceCursor = options.sequenceCursor ?? new ProtocolV2SequenceCursor();
   }
 
   call(
@@ -261,7 +209,7 @@ export class ProtocolV2Session {
     return result;
   }
 
-  private async executeCall(
+  private executeCall(
     name: string,
     data: Record<string, unknown>,
     callOptions: ProtocolV2CallOptions
@@ -270,118 +218,154 @@ export class ProtocolV2Session {
       schemas,
       router,
       packetSrc = PROTOCOL_V2_PACKET_SRC_COMMAND,
+      maxFrameBytes,
+      prepareCall,
       writeFrame,
       readFrame,
       logger,
       logPrefix = 'ProtocolV2',
       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);
-    this.protoSeq = nextProtoSeq(this.protoSeq);
-    const frame = ProtocolV2.encodeFrame(schemas, name, data, {
-      packetSrc,
-      router,
-      seq: this.protoSeq,
-      logger: shouldReduceDebug ? undefined : logger,
-      logPrefix,
-      context: `tx:${name}`,
-    });
-    const expectedSeq = frame[6];
-
-    if (!shouldReduceDebug) {
-      logger?.debug?.(
-        `[${logPrefix}] TX payload name=${name}`,
-        sanitizeProtocolV2DebugPayload(data)
-      );
-      logger?.debug?.(
-        `[${logPrefix}] TX frame name=${name} len=${frame.length} router=${frame[4]} attr=${
-          frame[5]
-        } seq=${expectedSeq} headerHex=${frameHeaderDebugHex(frame)}`
-      );
-    }
+    const baseCallContext: ProtocolV2CallContext = {
+      messageName: name,
+      timeoutMs,
+      highThroughput: isProtocolV2HighThroughputCall(name),
+      ...(callOptions.writeWithResponse === undefined
+        ? {}
+        : { writeWithResponse: callOptions.writeWithResponse }),
+      generation,
+      signal: abortController.signal,
+    };
 
-    // Lenient watchdog on the write phase only — see
-    // PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS for the rationale.
-    await withProtocolTimeout(
-      writeFrame(frame),
-      PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS,
-      () =>
-        new Error(
-          `Protocol V2 write timeout after ${PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS}ms for ${name}`
-        )
-    );
+    const runCall = async (): Promise<MessageFromOneKey> => {
+      await prepareCall?.(baseCallContext);
+      const protoSeq = this.sequenceCursor.next();
+      const frame = ProtocolV2.encodeFrame(schemas, name, data, {
+        packetSrc,
+        router,
+        seq: protoSeq,
+      });
+
+      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 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)}`);
+      }
 
-    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();
-        if (cancellation.cancelled) {
-          // Timed out while waiting: drop the late frame and stop reading.
-          break;
-        }
-        if (!shouldReduceDebug) {
-          logger?.debug?.(
-            `[${logPrefix}] RX frame len=${rxFrame.length} router=${rxFrame[4]} attr=${
-              rxFrame[5]
-            } seq=${rxFrame[6]} headerHex=${frameHeaderDebugHex(rxFrame)}`
+      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
           );
         }
-        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 (header.router !== router) {
+          throw new ProtocolV2LinkError(
+            'router',
+            `Protocol V2 router mismatch: expected ${router}, got ${header.router}`
           );
         }
-        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)
+        if (header.packetSrc !== packetSrc) {
+          throw new ProtocolV2LinkError(
+            'packet-source',
+            `Protocol V2 packet source mismatch: expected ${packetSrc}, got ${header.packetSrc}`
           );
         }
 
-        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}`
+        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)) {
+            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
-      // 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();
       }
     );
   }
@@ -412,7 +396,10 @@ 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;