@onekeyfe/hd-core 1.1.34-alpha.2 → 1.1.34-alpha.3

package/src/api/firmware/FirmwareCheckpoint.ts

@@ -0,0 +1,188 @@
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+import type {
+  FirmwareCheckpoint,
+  FirmwareCheckpointParams,
+  FirmwareCheckpointStage,
+} from '../../types/api/firmwareUpdate';
+
+const CHECKPOINT_TIMEOUT_MS = 5000;
+const MAX_CHECKPOINT_TARGET_LENGTH = 160;
+
+type FirmwareCheckpointState = {
+  latestSequence: number;
+  tail: Promise<void>;
+};
+
+const checkpointStateBySink = new WeakMap<
+  NonNullable<FirmwareCheckpointParams['checkpointSink']>,
+  FirmwareCheckpointState
+>();
+
+const checkpointError = (message: string) =>
+  ERRORS.TypedError(HardwareErrorCode.RuntimeError, message, {
+    firmwareUpdateCode: 'FirmwareCheckpointRejected',
+  });
+
+export const validateFirmwareCheckpoint = (value: unknown): FirmwareCheckpoint => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw checkpointError('Firmware resume checkpoint is invalid');
+  }
+  const checkpoint = value as Partial<FirmwareCheckpoint>;
+  const allowedKeys = new Set([
+    'schemaVersion',
+    'sequence',
+    'stage',
+    'destructiveActionStarted',
+    'target',
+    'epoch',
+  ]);
+  if (
+    Object.keys(checkpoint).some(key => !allowedKeys.has(key)) ||
+    !['schemaVersion', 'sequence', 'stage', 'destructiveActionStarted'].every(key =>
+      Object.prototype.hasOwnProperty.call(checkpoint, key)
+    ) ||
+    checkpoint.schemaVersion !== 1 ||
+    !Number.isSafeInteger(checkpoint.sequence) ||
+    (checkpoint.sequence as number) < 1 ||
+    ![
+      'EPOCH_STARTED',
+      'EPOCH_COMPLETED',
+      'BEFORE_DEVICE_MODE_CHANGE',
+      'FILE_TRANSFER_STARTED',
+      'FILE_TRANSFER_COMPLETED',
+      'INSTALL_REQUESTED',
+      'INSTALL_ACCEPTED',
+      'FINAL_VERIFIED',
+    ].includes(checkpoint.stage as string) ||
+    checkpoint.destructiveActionStarted !== true ||
+    (checkpoint.target !== undefined &&
+      (!checkpoint.target ||
+        checkpoint.target.length > MAX_CHECKPOINT_TARGET_LENGTH ||
+        /(?:https?|file):\/\//iu.test(checkpoint.target) ||
+        /^(?:\/|[A-Za-z]:[\\/])/u.test(checkpoint.target))) ||
+    (checkpoint.epoch !== undefined &&
+      (!Number.isSafeInteger(checkpoint.epoch) || checkpoint.epoch < 0))
+  ) {
+    throw checkpointError('Firmware resume checkpoint fields are invalid');
+  }
+  return checkpoint as FirmwareCheckpoint;
+};
+
+const validateCheckpointParams = (params: FirmwareCheckpointParams, required: boolean) => {
+  const { checkpointSequenceStart, checkpointSink } = params;
+  const resumeCheckpoint =
+    params.resumeCheckpoint === undefined
+      ? undefined
+      : validateFirmwareCheckpoint(params.resumeCheckpoint);
+  if (
+    checkpointSequenceStart !== undefined &&
+    (!Number.isSafeInteger(checkpointSequenceStart) || checkpointSequenceStart < 0)
+  ) {
+    throw checkpointError('Firmware checkpoint sequence is invalid');
+  }
+  if (
+    checkpointSink !== undefined &&
+    (typeof checkpointSink !== 'object' ||
+      checkpointSink === null ||
+      typeof checkpointSink.commit !== 'function')
+  ) {
+    throw checkpointError('Firmware checkpoint sink is invalid');
+  }
+  if (required && !checkpointSink) {
+    throw checkpointError('Prepared firmware update requires a checkpoint sink');
+  }
+  if (resumeCheckpoint && checkpointSequenceStart !== resumeCheckpoint.sequence) {
+    throw checkpointError('Firmware checkpoint sequence does not match recovery state');
+  }
+};
+
+const waitForCheckpoint = async (commit: Promise<void>) => {
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await Promise.race([
+      commit,
+      new Promise<never>((_, reject) => {
+        timeoutId = setTimeout(
+          () => reject(checkpointError('Firmware checkpoint commit timed out')),
+          CHECKPOINT_TIMEOUT_MS
+        );
+      }),
+    ]);
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
+  }
+};
+
+export class FirmwareCheckpointWriter {
+  private readonly sink: FirmwareCheckpointParams['checkpointSink'];
+
+  private readonly sequenceStart: number;
+
+  constructor(params: FirmwareCheckpointParams, { required = false } = {}) {
+    validateCheckpointParams(params, required);
+    this.sink = params.checkpointSink;
+    this.sequenceStart = params.checkpointSequenceStart ?? 0;
+  }
+
+  async commit({
+    stage,
+    target,
+    epoch,
+  }: {
+    stage: FirmwareCheckpointStage;
+    target?: string;
+    epoch?: number;
+  }): Promise<void> {
+    if (!this.sink) return;
+    if (
+      (target !== undefined &&
+        (!target ||
+          target.length > MAX_CHECKPOINT_TARGET_LENGTH ||
+          /(?:https?|file):\/\//iu.test(target) ||
+          /^(?:\/|[A-Za-z]:[\\/])/u.test(target))) ||
+      (epoch !== undefined && (!Number.isSafeInteger(epoch) || epoch < 0))
+    ) {
+      throw checkpointError('Firmware checkpoint metadata is invalid');
+    }
+
+    let state = checkpointStateBySink.get(this.sink);
+    if (!state) {
+      state = {
+        latestSequence: this.sequenceStart,
+        tail: Promise.resolve(),
+      };
+      checkpointStateBySink.set(this.sink, state);
+    } else if (this.sequenceStart > state.latestSequence) {
+      state.latestSequence = this.sequenceStart;
+    }
+    const activeState = state;
+
+    const queuedCommit = activeState.tail.then(async () => {
+      const sequence = activeState.latestSequence + 1;
+      const checkpoint: FirmwareCheckpoint = {
+        schemaVersion: 1,
+        sequence,
+        stage,
+        destructiveActionStarted: true,
+        ...(target ? { target } : {}),
+        ...(epoch !== undefined ? { epoch } : {}),
+      };
+      try {
+        await this.sink?.commit(checkpoint);
+        activeState.latestSequence = sequence;
+      } catch (error) {
+        throw checkpointError(
+          `Firmware checkpoint commit was rejected: ${
+            error instanceof Error ? error.message : 'unknown error'
+          }`
+        );
+      }
+    });
+
+    // Keep the real commit serialized even when the caller's timeout fires. A
+    // later call cannot overtake an unresolved or late checkpoint write.
+    activeState.tail = queuedCommit.catch(() => undefined);
+    await waitForCheckpoint(queuedCommit);
+  }
+}

package/src/api/firmware/FirmwareHostBinding.ts

@@ -0,0 +1,108 @@
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+import type { FirmwareUpdateHostBinding } from '../../types/api/firmwareUpdate';
+
+const bindingError = (message: string): never => {
+  throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, message, {
+    firmwareUpdateCode: 'FirmwareArtifactReaderInvalid',
+  });
+};
+
+class FirmwareHostBindingRegistry {
+  private generation = 0;
+
+  private binding?: FirmwareUpdateHostBinding;
+
+  register(binding: FirmwareUpdateHostBinding): number {
+    if (
+      !binding ||
+      typeof binding.artifactReader?.open !== 'function' ||
+      typeof binding.artifactReader.read !== 'function' ||
+      typeof binding.artifactReader.close !== 'function' ||
+      typeof binding.checkpointSink?.commit !== 'function'
+    ) {
+      return bindingError('Firmware host binding is invalid');
+    }
+    this.generation += 1;
+    this.binding = binding;
+    return this.generation;
+  }
+
+  unregister(generation?: number): boolean {
+    if (generation !== undefined && generation !== this.generation) {
+      return false;
+    }
+    this.generation += 1;
+    this.binding = undefined;
+    return true;
+  }
+
+  getGeneration(): number {
+    return this.generation;
+  }
+
+  resolve(generation: number): FirmwareUpdateHostBinding {
+    if (
+      !Number.isSafeInteger(generation) ||
+      generation <= 0 ||
+      generation !== this.generation ||
+      !this.binding
+    ) {
+      return bindingError(`Firmware host binding generation ${generation} is stale`);
+    }
+    const { binding } = this;
+    const assertCurrent = () => {
+      if (generation !== this.generation || binding !== this.binding) {
+        bindingError(`Firmware host binding generation ${generation} is stale`);
+      }
+    };
+    return {
+      artifactReader: {
+        open: async input => {
+          assertCurrent();
+          const opened = await binding.artifactReader.open(input);
+          try {
+            assertCurrent();
+          } catch (error) {
+            if (opened?.readerId) {
+              await binding.artifactReader
+                .close({ readerId: opened.readerId })
+                .catch(() => undefined);
+            }
+            throw error;
+          }
+          return opened;
+        },
+        read: async input => {
+          assertCurrent();
+          const result = await binding.artifactReader.read(input);
+          assertCurrent();
+          return result;
+        },
+        close: input => binding.artifactReader.close(input),
+      },
+      checkpointSink: {
+        commit: async checkpoint => {
+          assertCurrent();
+          await binding.checkpointSink.commit(checkpoint);
+          assertCurrent();
+        },
+      },
+    };
+  }
+}
+
+const firmwareHostBindingRegistry = new FirmwareHostBindingRegistry();
+
+export const registerFirmwareUpdateHostBinding = (binding: FirmwareUpdateHostBinding): number =>
+  firmwareHostBindingRegistry.register(binding);
+
+export const unregisterFirmwareUpdateHostBinding = (generation?: number): boolean =>
+  firmwareHostBindingRegistry.unregister(generation);
+
+export const getFirmwareUpdateHostBindingGeneration = (): number =>
+  firmwareHostBindingRegistry.getGeneration();
+
+export const resolveFirmwareUpdateHostBinding = (
+  generation: number | undefined
+): FirmwareUpdateHostBinding => firmwareHostBindingRegistry.resolve(generation ?? Number.NaN);

package/src/api/firmware/FirmwareUpdateBaseMethod.ts

@@ -8,12 +8,15 @@ import {
 
 import { FirmwareUpdateTipMessage, UI_REQUEST, createUiMessage } from '../../events/ui-request';
 import { DevicePool } from '../../device/DevicePool';
-import { LoggerNames, getDeviceType, getDeviceUUID, getLogger, wait } from '../../utils';
+import { LoggerNames, getLogger, wait } from '../../utils';
 import { DeviceModelToTypes } from '../../types';
 import { DataManager } from '../../data-manager';
 import { BaseMethod } from '../BaseMethod';
 import { DEVICE } from '../../events';
+import { createFirmwareProgressThrottle } from './progressThrottle';
+import { writeFirmwareByteSource } from './FirmwareArtifactSource';
 
+import type { FirmwareCheckpointWriter } from './FirmwareCheckpoint';
 import type {
   IFirmwareUpdateProgressType,
   IFirmwareUpdateTipMessage,
@@ -23,6 +26,7 @@ import type { RebootType } from '@onekeyfe/hd-transport';
 import type { Deferred } from '@onekeyfe/hd-shared';
 import type { KnownDevice } from '../../types';
 import type { TypedResponseMessage } from '../../device/DeviceCommands';
+import type { FirmwareByteSource } from './FirmwareArtifactSource';
 
 const Log = getLogger(LoggerNames.Method);
 const SESSION_ERROR = 'session not found';
@@ -40,6 +44,8 @@ const isDeviceDisconnectedError = (error: unknown) => {
 export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
   checkPromise: Deferred<any> | null = null;
 
+  private shouldPostFirmwareProgress = createFirmwareProgressThrottle();
+
   init(): void {}
 
   run(): Promise<any> {
@@ -83,6 +89,10 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
    * @param progress Post the percentage of the progress
    */
   postProgressMessage = (progress: number, progressType: IFirmwareUpdateProgressType) => {
+    if (!this.shouldPostFirmwareProgress(progress, progressType)) {
+      return;
+    }
+
     this.postMessage(
       createUiMessage(UI_REQUEST.FIRMWARE_PROGRESS, {
         device: this.device.toMessageObject() as KnownDevice,
@@ -138,12 +148,14 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
     // check device goto bootloader mode
     let isFirstCheck = true;
     let checkCount = 0;
+    let hasPromptedWebDevice = false;
+    let isPromptingWebDevice = false;
     // eslint-disable-next-line prefer-const
     let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
 
     const isTouchOrProDevice =
-      getDeviceType(this?.device?.features) === EDeviceType.Touch ||
-      getDeviceType(this?.device?.features) === EDeviceType.Pro;
+      this?.device?.getCurrentDeviceType() === EDeviceType.Touch ||
+      this?.device?.getCurrentDeviceType() === EDeviceType.Pro;
 
     const intervalTimer: ReturnType<typeof setInterval> | undefined = setInterval(
       async () => {
@@ -158,23 +170,28 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
         if (
           checkCount > 4 &&
           DataManager.isBrowserWebUsb(DataManager.getSettings('env')) &&
-          !this.payload.skipWebDevicePrompt
+          !this.payload.skipWebDevicePrompt &&
+          !hasPromptedWebDevice &&
+          !isPromptingWebDevice
         ) {
-          clearInterval(intervalTimer);
-          clearTimeout(timeoutTimer);
-
+          isPromptingWebDevice = true;
           try {
             this.postTipMessage(FirmwareUpdateTipMessage.SelectDeviceInBootloaderForWebDevice);
             const confirmed = await this._promptDeviceInBootloaderForWebDevice();
+            hasPromptedWebDevice = true;
             if (confirmed) {
               await this._checkDeviceInBootloaderMode(connectId, intervalTimer, timeoutTimer);
             }
           } catch (e) {
+            clearInterval(intervalTimer);
+            clearTimeout(timeoutTimer);
             Log.log(
               'FirmwareUpdateBaseMethod [checkDeviceToBootloader] _promptDeviceInBootloaderForWebDevice failed: ',
               e
             );
             this.checkPromise?.reject(e);
+          } finally {
+            isPromptingWebDevice = false;
           }
           return;
         }
@@ -187,7 +204,7 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
               true
             );
             await this.device.initialize();
-            if (this.device.features?.bootloader_mode) {
+            if (this.device.isBootloader()) {
               clearInterval(intervalTimer);
               this.checkPromise?.resolve(true);
             }
@@ -220,7 +237,7 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
     const devicesDescriptor = deviceDiff?.descriptors ?? [];
     const { deviceList } = await DevicePool.getDevices(devicesDescriptor, connectId);
 
-    if (deviceList.length === 1 && deviceList[0]?.features?.bootloader_mode) {
+    if (deviceList.length === 1 && deviceList[0]?.isBootloader()) {
       // should update current device from cache
       // because device was reboot and had some new requests
       this.device.updateFromCache(deviceList[0]);
@@ -234,14 +251,17 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
     return false;
   }
 
-  async enterBootloaderMode() {
+  async enterBootloaderMode(checkpointWriter?: FirmwareCheckpointWriter) {
     const typedCall = this.device.getCommands().typedCall.bind(this.device.getCommands());
-    if (this.device.features && !this.device.features.bootloader_mode) {
-      const uuid = getDeviceUUID(this.device.features);
-      const deviceType = getDeviceType(this.device.features);
+    if (this.device.features && !this.device.isBootloader()) {
+      const serialNo = this.device.getCurrentSerialNo();
+      const deviceType = this.device.getCurrentDeviceType();
       // auto go to bootloader mode
       try {
         this.postTipMessage(FirmwareUpdateTipMessage.AutoRebootToBootloader);
+        await checkpointWriter?.commit({
+          stage: 'BEFORE_DEVICE_MODE_CHANGE',
+        });
         const bootRes = await typedCall('DeviceBackToBoot', 'Success');
         // @ts-expect-error
         if (bootRes.type === 'CallMethodError') {
@@ -252,7 +272,7 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
 
         // force clean classic device cache so that the device can initialize again
         if (DeviceModelToTypes.model_classic.includes(deviceType)) {
-          DevicePool.clearDeviceCache(uuid);
+          DevicePool.clearDeviceCache(serialNo);
         }
         delete DevicePool.devicesCache[''];
         await this.checkPromise?.promise;
@@ -373,6 +393,54 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
     return totalSize !== undefined ? (processedSize ?? 0) + payload.byteLength : 0;
   }
 
+  async emmcCommonUpdateProcessFromSource({
+    source,
+    filePath,
+    processedSize,
+    totalSize,
+  }: {
+    source: FirmwareByteSource;
+    filePath: string;
+    processedSize?: number;
+    totalSize?: number;
+  }) {
+    if (!filePath.startsWith('0:')) {
+      throw new Error('filePath must start with 0:');
+    }
+    const env = DataManager.getSettings('env');
+    const chunkSize = 1024 * (DataManager.isBleConnect(env) ? 16 : 128);
+
+    await writeFirmwareByteSource({
+      source,
+      chunkSize,
+      write: async ({ data, sourceOffset, length, first }) => {
+        const progress =
+          totalSize !== undefined && processedSize !== undefined
+            ? Math.min(Math.ceil(((processedSize + sourceOffset + length) / totalSize) * 100), 99)
+            : Math.min(Math.ceil(((sourceOffset + length) / source.size) * 100), 99);
+        const writeRes = await this.emmcFileWriteWithRetry(
+          filePath,
+          length,
+          sourceOffset,
+          data,
+          first,
+          progress
+        );
+        if (!writeRes) {
+          throw ERRORS.TypedError(
+            HardwareErrorCode.EmmcFileWriteFirmwareError,
+            'transfer data error'
+          );
+        }
+        const processedBytes = Number(writeRes.message.processed_byte);
+        this.postProgressMessage(progress, 'transferData');
+        return Number.isFinite(processedBytes) ? processedBytes : length;
+      },
+    });
+
+    return totalSize !== undefined ? (processedSize ?? 0) + source.size : 0;
+  }
+
   async emmcFileWriteWithRetry(
     filePath: string,
     chunkLength: number,
@@ -436,7 +504,7 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
           const deviceDiff = await this.device.deviceConnector?.enumerate();
           const devicesDescriptor = deviceDiff?.descriptors ?? [];
           const { deviceList } = await DevicePool.getDevices(devicesDescriptor, undefined);
-          if (deviceList.length === 1 && deviceList[0]?.features?.bootloader_mode) {
+          if (deviceList.length === 1 && deviceList[0]?.isBootloader()) {
             this.device.updateFromCache(deviceList[0]);
             await this.device.acquire();
             this.device.getCommands().mainId = this.device.mainId ?? '';

package/src/api/firmware/FirmwareUpdateCapabilities.ts

@@ -0,0 +1,13 @@
+import type { FirmwareUpdateCapabilities } from '../../types/api/firmwareUpdateCapabilities';
+
+export const getFirmwareUpdateCapabilities = (): FirmwareUpdateCapabilities => ({
+  planSchemaVersion: 1,
+  preparedPlanSchemaVersion: 1,
+  hostBindingProtocolVersion: 1,
+  checkpointSchemaVersion: 1,
+  manifestModes: ['external-only', 'sdk-managed'],
+  supportsArtifactReader: true,
+  supportsAwaitableCheckpoint: true,
+  supportsResume: true,
+  supportsReconciliation: true,
+});