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

package/src/protocols/v2/decode.ts

@@ -1,4 +1,9 @@
-import { PROTO_DATA_TYPE_ACK, PROTO_HEAD_CRC_SIZE, PROTO_HEAD_SOF } from './constants';
+import {
+  PROTO_DATA_TYPE_ACK,
+  PROTO_DATA_TYPE_PACKET,
+  PROTO_HEAD_CRC_SIZE,
+  PROTO_HEAD_SOF,
+} from './constants';
 import { crc8 } from './crc8';
 
 export interface ProtoV2Frame {
@@ -8,9 +13,23 @@ export interface ProtoV2Frame {
   pbPayload: Uint8Array;
   /** Sequence number from the frame header */
   seq: number;
+  /** Routing channel from the frame header */
+  router: number;
+  /** Packet source from the frame header */
+  packetSrc: number;
+  /** Packet or ACK discriminator from the frame header */
+  dataType: number;
 }
 
-function validateFrame(data: Uint8Array): number {
+export type ProtoV2FrameHeader = {
+  frameLen: number;
+  router: number;
+  packetSrc: number;
+  dataType: number;
+  seq: number;
+};
+
+export function inspectFrameHeader(data: Uint8Array): ProtoV2FrameHeader {
   if (data.length < PROTO_HEAD_CRC_SIZE) {
     throw new Error(`Protocol V2 frame too short: ${data.length} bytes`);
   }
@@ -23,8 +42,10 @@ function validateFrame(data: Uint8Array): number {
 
   const frameLen = data[1] + data[2] * 256;
 
-  if (data.length < frameLen) {
-    throw new Error(`Frame truncated: expected ${frameLen} bytes, got ${data.length}`);
+  if (data.length !== frameLen) {
+    throw new Error(
+      `Protocol V2 frame length mismatch: expected ${frameLen} bytes, got ${data.length}`
+    );
   }
 
   const expectedHeaderCrc = crc8(data, 3);
@@ -45,7 +66,22 @@ function validateFrame(data: Uint8Array): number {
     );
   }
 
-  return frameLen;
+  // eslint-disable-next-line no-bitwise
+  const dataType = data[5] & 0x03;
+  // eslint-disable-next-line no-bitwise
+  const packetSrc = (data[5] >> 2) & 0x0f;
+  const seq = data[6];
+  if (seq === 0) {
+    throw new Error('Invalid Protocol V2 sequence: 0 is reserved');
+  }
+
+  return {
+    frameLen,
+    router: data[4],
+    packetSrc,
+    dataType,
+    seq,
+  };
 }
 
 export function isAckFrame(data: Uint8Array): boolean {
@@ -54,9 +90,9 @@ export function isAckFrame(data: Uint8Array): boolean {
     return false;
   }
 
-  const frameLen = validateFrame(data);
-  if (frameLen !== PROTO_HEAD_CRC_SIZE) {
-    throw new Error(`Invalid Protocol V2 ACK frame length: ${frameLen}`);
+  const header = inspectFrameHeader(data);
+  if (header.frameLen !== PROTO_HEAD_CRC_SIZE) {
+    throw new Error(`Invalid Protocol V2 ACK frame length: ${header.frameLen}`);
   }
   return true;
 }
@@ -72,9 +108,10 @@ export function isAckFrame(data: Uint8Array): boolean {
  * Returns the decoded messageTypeId, raw protobuf payload, and sequence number.
  */
 export function decodeFrame(data: Uint8Array): ProtoV2Frame {
-  const frameLen = validateFrame(data);
-
-  const seq = data[6];
+  const { frameLen, router, packetSrc, dataType, seq } = inspectFrameHeader(data);
+  if (dataType !== PROTO_DATA_TYPE_PACKET) {
+    throw new Error(`Invalid Protocol V2 data type: expected packet, got ${dataType}`);
+  }
   // Payload spans bytes 7 to frameLen-2 (inclusive), excluding final CRC byte
   const payloadData = data.slice(7, frameLen - 1);
 
@@ -85,5 +122,5 @@ export function decodeFrame(data: Uint8Array): ProtoV2Frame {
   const messageTypeId = payloadData[0] + payloadData[1] * 256;
   const pbPayload = payloadData.slice(2);
 
-  return { messageTypeId, pbPayload, seq };
+  return { messageTypeId, pbPayload, seq, router, packetSrc, dataType };
 }

package/src/protocols/v2/encode.ts

@@ -43,7 +43,7 @@ export function encodeFrame(
   const payloadLen = payload ? payload.length : 0;
   const frameLen = payloadLen + PROTO_HEAD_CRC_SIZE;
   if (frameLen > PROTOCOL_V2_FRAME_MAX_BYTES) {
-    throw new Error(`Protocol V2 frame too large: ${frameLen}`);
+    throw new Error(`Protocol V2 frame too large: ${frameLen} > ${PROTOCOL_V2_FRAME_MAX_BYTES}`);
   }
   const frame = new Uint8Array(frameLen);
 

package/src/protocols/v2/errors.ts

@@ -0,0 +1,54 @@
+export type ProtocolV2LinkErrorCode =
+  | 'response-timeout'
+  | 'io'
+  | 'generation'
+  | 'router'
+  | 'packet-source'
+  | 'ack-sequence'
+  | 'response-sequence'
+  | 'frame';
+
+export class ProtocolV2LinkError extends Error {
+  readonly code: ProtocolV2LinkErrorCode;
+
+  readonly cause?: unknown;
+
+  constructor(code: ProtocolV2LinkErrorCode, message: string, cause?: unknown) {
+    super(message);
+    this.name = 'ProtocolV2LinkError';
+    this.code = code;
+    this.cause = cause;
+  }
+}
+
+export const isProtocolV2LinkError = (error: unknown): error is ProtocolV2LinkError =>
+  error instanceof ProtocolV2LinkError;
+
+export type ProtocolV2LinkDisabledError = Error & {
+  name: 'ProtocolV2LinkDisabledError';
+  failureCode: string | number;
+  firmwareMessage: string;
+};
+
+export const createProtocolV2LinkDisabledError = (
+  failureCode: string | number,
+  firmwareMessage: string
+): ProtocolV2LinkDisabledError =>
+  Object.assign(new Error(firmwareMessage), {
+    name: 'ProtocolV2LinkDisabledError' as const,
+    failureCode,
+    firmwareMessage,
+  });
+
+export const isProtocolV2LinkDisabledError = (
+  error: unknown
+): error is ProtocolV2LinkDisabledError =>
+  error instanceof Error &&
+  error.name === 'ProtocolV2LinkDisabledError' &&
+  'failureCode' in error &&
+  'firmwareMessage' in error;
+
+export const isProtocolV2LinkDisabledFailure = (failureCode: unknown, firmwareMessage: unknown) =>
+  (failureCode === 'Failure_ProcessError' || failureCode === 5) &&
+  typeof firmwareMessage === 'string' &&
+  firmwareMessage.trim().toLowerCase() === 'link disabled';

package/src/protocols/v2/frame-assembler.ts

@@ -1,6 +1,7 @@
 import { PROTOCOL_V2_FRAME_MAX_BYTES } from '../../constants';
 import { PROTO_HEAD_CRC_SIZE, PROTO_HEAD_SOF, PROTO_PRE_HEAD_SIZE } from './constants';
 import { crc8 } from './crc8';
+import { ProtocolV2LinkError } from './errors';
 
 export function concatUint8Arrays(arrays: Uint8Array[]): Uint8Array {
   const totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0);
@@ -58,7 +59,7 @@ export class ProtocolV2FrameAssembler {
 
     if (this.buffer[0] !== PROTO_HEAD_SOF) {
       this.reset();
-      throw new Error('Invalid Protocol V2 SOF');
+      throw new ProtocolV2LinkError('frame', 'Invalid Protocol V2 SOF');
     }
 
     const expectedLen = this.buffer[1] + this.buffer[2] * 256;
@@ -67,11 +68,11 @@ export class ProtocolV2FrameAssembler {
       // complete frame: without resetting, this poison prefix would stay in
       // the buffer forever and deadlock the caller's drain loop.
       this.reset();
-      throw new Error(`Protocol V2 frame length too small: ${expectedLen}`);
+      throw new ProtocolV2LinkError('frame', `Protocol V2 frame length too small: ${expectedLen}`);
     }
     if (expectedLen > this.maxFrameBytes) {
       this.reset();
-      throw new Error(`Protocol V2 frame too large: ${expectedLen}`);
+      throw new ProtocolV2LinkError('frame', `Protocol V2 frame too large: ${expectedLen}`);
     }
 
     if (this.buffer.length < PROTO_PRE_HEAD_SIZE) return undefined;
@@ -82,7 +83,8 @@ export class ProtocolV2FrameAssembler {
     const expectedHeaderCrc = crc8(this.buffer, 3);
     if (this.buffer[3] !== expectedHeaderCrc) {
       this.reset();
-      throw new Error(
+      throw new ProtocolV2LinkError(
+        'frame',
         `Protocol V2 header CRC mismatch: expected 0x${expectedHeaderCrc
           .toString(16)
           .padStart(2, '0')}`

package/src/protocols/v2/index.ts

@@ -2,4 +2,6 @@ export * from './constants';
 export * from './crc8';
 export * from './encode';
 export * from './decode';
+export * from './errors';
 export * from './frame-assembler';
+export * from './ble-frame-writer';

package/src/protocols/v2/link-manager.ts

@@ -1,4 +1,5 @@
 import { ProtocolV2SequenceCursor } from './sequence-cursor';
+import { ProtocolV2LinkError } from './errors';
 import { ProtocolV2Session, getErrorMessage } from './session';
 
 import type { MessageFromOneKey, TransportCallOptions } from '../../types';
@@ -40,6 +41,12 @@ export class ProtocolV2LinkManager<Key> {
 
   private readonly callQueues = new Map<Key, Promise<unknown>>();
 
+  private readonly generations = new Map<Key, number>();
+
+  private readonly invalidationReasons = new Map<Key, { generation: number; reason: string }>();
+
+  private readonly invalidations = new Map<Key, Promise<void>>();
+
   private readonly options: ProtocolV2LinkManagerOptions<Key>;
 
   constructor(options: ProtocolV2LinkManagerOptions<Key>) {
@@ -53,7 +60,11 @@ export class ProtocolV2LinkManager<Key> {
     data: Record<string, unknown>,
     options?: TransportCallOptions
   ): Promise<MessageFromOneKey> {
-    const run = () => this.executeCall(key, createAdapter, name, data, options);
+    const generation = this.generations.get(key) ?? 0;
+    const run = () => {
+      this.assertCallGeneration(key, generation);
+      return this.executeCall(key, createAdapter, name, data, options);
+    };
     const previous = this.callQueues.get(key) ?? Promise.resolve();
     const result = previous.then(run, run);
     const queue = result.catch(() => undefined);
@@ -67,24 +78,61 @@ export class ProtocolV2LinkManager<Key> {
     return result;
   }
 
+  sendFlowControl(
+    key: Key,
+    createAdapter: () => ProtocolV2LinkAdapter,
+    name: string,
+    data: Record<string, unknown>
+  ): Promise<MessageFromOneKey> {
+    const generation = this.generations.get(key) ?? 0;
+    this.assertCallGeneration(key, generation);
+    return this.getOrCreateLink(key, createAdapter).session.sendFlowControl(name, data);
+  }
+
   async invalidateLink(key: Key, reason: string): Promise<void> {
+    const generation = (this.generations.get(key) ?? 0) + 1;
+    this.generations.set(key, generation);
+    this.invalidationReasons.set(key, { generation, reason });
+
+    const pendingInvalidation = this.invalidations.get(key);
     const link = this.links.get(key);
-    if (!link) return;
+    if (!link) {
+      await pendingInvalidation;
+      return;
+    }
 
     this.links.delete(key);
     link.state.invalidatedReason = reason;
-    await link.adapter.reset(reason);
-    await this.options.onLinkInvalidated?.(key, reason);
+    const invalidation = (async () => {
+      await pendingInvalidation?.catch(() => undefined);
+      await link.adapter.reset(reason);
+      await this.options.onLinkInvalidated?.(key, reason);
+    })();
+    this.invalidations.set(key, invalidation);
+
+    try {
+      await invalidation;
+    } finally {
+      if (this.invalidations.get(key) === invalidation) {
+        this.invalidations.delete(key);
+      }
+    }
   }
 
   async invalidateAllLinks(reason: string): Promise<void> {
-    await Promise.all(Array.from(this.links.keys(), key => this.invalidateLink(key, reason)));
+    const keys = new Set([
+      ...this.links.keys(),
+      ...this.callQueues.keys(),
+      ...this.invalidations.keys(),
+    ]);
+    await Promise.all(Array.from(keys, key => this.invalidateLink(key, reason)));
   }
 
   async dispose(reason: string): Promise<void> {
     await this.invalidateAllLinks(reason);
     this.sequences.clear();
     this.callQueues.clear();
+    this.invalidations.clear();
   }
 
   private getOrCreateLink(key: Key, createAdapter: () => ProtocolV2LinkAdapter): ProtocolV2Link {
@@ -157,4 +205,16 @@ export class ProtocolV2LinkManager<Key> {
       this.callQueues.delete(key);
     }
   }
+
+  private assertCallGeneration(key: Key, generation: number) {
+    const currentGeneration = this.generations.get(key) ?? 0;
+    if (currentGeneration === generation) return;
+
+    const invalidation = this.invalidationReasons.get(key);
+    const reason =
+      invalidation?.generation === currentGeneration
+        ? invalidation.reason
+        : 'Protocol V2 link generation changed';
+    throw new ProtocolV2LinkError('generation', reason);
+  }
 }