react-native-executorch 0.4.9 → 0.5.0-nightly-6f4dd53-20251211

package/src/utils/ResourceFetcher.ts

@@ -1,121 +1,256 @@
+/**
+ * Resource Fetcher
+ *
+ * Provides an interface for downloading files (via `ResourceFetcher.fetch()`)
+ *
+ * Key functionality:
+ * - Download control: pause, resume, and cancel operations through:
+ *   - Single file: `.pauseFetching()`, `.resumeFetching()`, `.cancelFetching()`
+ * - Downloaded file management:
+ *   -  `.getFilesTotalSize()`, `.listDownloadedFiles()`, `.listDownloadedModels()`, `.deleteResources()`
+ *
+ * Remark: The pausing/resuming/canceling works only for fetching remote resources.
+ *
+ * Most exported functions accept:
+ * - Multiple `ResourceSource` arguments, (union type of string, number or object)
+ *
+ * Method `.fetch()` takes argument as callback that reports download progress.
+ * Method`.fetch()` returns array of paths to successfully saved files or null if the download was paused or cancelled  (then resume functions can return paths).
+ *
+ * Technical Implementation:
+ * - Maintains a `downloads` Map instance that tracks:
+ *   - Currently downloading resources
+ *   - Paused downloads
+ * - Successful downloads are automatically removed from the `downloads` Map
+ * - Uses the `ResourceSourceExtended` interface to enable pause/resume functionality:
+ *   - Wraps user-provided `ResourceSource` elements
+ *   - Implements linked list behavior via the `.next` attribute
+ *   - Automatically processes subsequent downloads when `.next` contains a valid resource
+ */
+
 import {
   cacheDirectory,
+  copyAsync,
   createDownloadResumable,
-  getInfoAsync,
-  makeDirectoryAsync,
   moveAsync,
   FileSystemSessionType,
   writeAsStringAsync,
   EncodingType,
   deleteAsync,
   readDirectoryAsync,
-} from 'expo-file-system';
+} from 'expo-file-system/legacy';
 import { Asset } from 'expo-asset';
+import { Platform } from 'react-native';
 import { RNEDirectory } from '../constants/directories';
 import { ResourceSource } from '../types/common';
+import {
+  ResourceFetcherUtils,
+  HTTP_CODE,
+  DownloadStatus,
+  SourceType,
+  ResourceSourceExtended,
+  DownloadResource,
+} from './ResourceFetcherUtils';
 
 export class ResourceFetcher {
+  static downloads = new Map<ResourceSource, DownloadResource>(); //map of currently downloading (or paused) files, if the download was started by .fetch() method.
+
   static async fetch(
-    source: ResourceSource,
-    callback: (downloadProgress: number) => void = () => {}
+    callback: (downloadProgress: number) => void = () => {},
+    ...sources: ResourceSource[]
   ) {
-    if (typeof source === 'object') {
-      return this.handleObject(source);
+    if (sources.length === 0) {
+      throw new Error('Empty list given as an argument!');
     }
+    const { results: info, totalLength } =
+      await ResourceFetcherUtils.getFilesSizes(sources);
+    const head: ResourceSourceExtended = {
+      source: info[0]!.source,
+      sourceType: info[0]!.type,
+      callback:
+        info[0]!.type === SourceType.REMOTE_FILE
+          ? ResourceFetcherUtils.calculateDownloadProgress(
+              totalLength,
+              info[0]!.previousFilesTotalLength,
+              info[0]!.length,
+              callback
+            )
+          : () => {},
+      results: [],
+    };
 
-    const uri =
-      typeof source === 'number' ? Asset.fromModule(source).uri : source;
+    let node = head;
+    for (let idx = 1; idx < sources.length; idx++) {
+      node.next = {
+        source: info[idx]!.source,
+        sourceType: info[idx]!.type,
+        callback:
+          info[idx]!.type === SourceType.REMOTE_FILE
+            ? ResourceFetcherUtils.calculateDownloadProgress(
+                totalLength,
+                info[idx]!.previousFilesTotalLength,
+                info[idx]!.length,
+                callback
+              )
+            : () => {},
+        results: [],
+      };
+      node = node.next;
+    }
+    return this.singleFetch(head);
+  }
 
-    // Handle local files
-    if (uri.startsWith('file://')) {
-      return this.removeFilePrefix(uri);
+  private static async singleFetch(
+    sourceExtended: ResourceSourceExtended
+  ): Promise<string[] | null> {
+    const source = sourceExtended.source;
+    switch (sourceExtended.sourceType) {
+      case SourceType.OBJECT: {
+        return this.returnOrStartNext(
+          sourceExtended,
+          await this.handleObject(source)
+        );
+      }
+      case SourceType.LOCAL_FILE: {
+        return this.returnOrStartNext(
+          sourceExtended,
+          this.handleLocalFile(source)
+        );
+      }
+      case SourceType.RELEASE_MODE_FILE: {
+        return this.returnOrStartNext(
+          sourceExtended,
+          await this.handleReleaseModeFile(sourceExtended)
+        );
+      }
+      case SourceType.DEV_MODE_FILE: {
+        const result = await this.handleDevModeFile(sourceExtended);
+        if (result !== null) {
+          return this.returnOrStartNext(sourceExtended, result);
+        }
+        return null;
+      }
+      default: {
+        //case SourceType.REMOTE_FILE
+        const result = await this.handleRemoteFile(sourceExtended);
+        if (result !== null) {
+          return this.returnOrStartNext(sourceExtended, result);
+        }
+        return null;
+      }
     }
+  }
 
-    const filename = this.getFilenameFromUri(uri);
-    const fileUri = `${RNEDirectory}${filename}`;
+  //if any download ends successfully this function is called - it checks whether it should trigger next download or return list of paths.
+  private static returnOrStartNext(
+    sourceExtended: ResourceSourceExtended,
+    result: string
+  ) {
+    sourceExtended.results.push(result);
 
-    if (await this.checkFileExists(fileUri)) {
-      return this.removeFilePrefix(fileUri);
+    if (sourceExtended.next) {
+      const nextSource = sourceExtended.next;
+      nextSource.results.push(...sourceExtended.results);
+      return this.singleFetch(nextSource);
     }
-    await this.createDirectoryIfNoExists();
+    sourceExtended.callback!(1);
+    return sourceExtended.results;
+  }
 
-    // Handle local asset files in release mode
-    if (!uri.includes('://')) {
-      const asset = Asset.fromModule(source);
-      const fileUriWithType = `${fileUri}.${asset.type}`;
-      await asset.downloadAsync();
-      if (!asset.localUri) {
-        throw new Error(`Asset local URI is not available for ${source}`);
+  private static async pause(source: ResourceSource) {
+    const resource = this.downloads.get(source)!;
+    switch (resource.status) {
+      case DownloadStatus.PAUSED:
+        throw new Error(
+          "The file download is currently paused. Can't pause the download of the same file twice."
+        );
+      default: {
+        resource.status = DownloadStatus.PAUSED;
+        await resource.downloadResumable.pauseAsync();
       }
-      await moveAsync({ from: asset.localUri, to: fileUriWithType });
-      return this.removeFilePrefix(fileUriWithType);
     }
+  }
 
-    // Handle remote file download
-    const cacheFileUri = `${cacheDirectory}${filename}`;
-    const downloadResumable = createDownloadResumable(
-      uri,
-      cacheFileUri,
-      { sessionType: FileSystemSessionType.BACKGROUND },
-      ({ totalBytesWritten, totalBytesExpectedToWrite }) => {
-        callback(totalBytesWritten / totalBytesExpectedToWrite);
+  private static async resume(source: ResourceSource) {
+    const resource = this.downloads.get(source)!;
+    if (
+      !resource.extendedInfo.fileUri ||
+      !resource.extendedInfo.cacheFileUri ||
+      !resource.extendedInfo.uri
+    ) {
+      throw new Error('Something went wrong. File uri info is not specified!');
+    }
+    switch (resource.status) {
+      case DownloadStatus.ONGOING:
+        throw new Error(
+          "The file download is currently ongoing. Can't resume the ongoing download."
+        );
+      default: {
+        resource.status = DownloadStatus.ONGOING;
+        const result = await resource.downloadResumable.resumeAsync();
+        if (
+          !this.downloads.has(source) ||
+          this.downloads.get(source)!.status === DownloadStatus.PAUSED
+        ) {
+          //if canceled or paused after earlier resuming.
+          return null;
+        }
+        if (
+          !result ||
+          (result.status !== HTTP_CODE.OK &&
+            result.status !== HTTP_CODE.PARTIAL_CONTENT)
+        ) {
+          throw new Error(
+            `Failed to fetch resource from '${resource.extendedInfo.uri}'`
+          );
+        }
+        await moveAsync({
+          from: resource.extendedInfo.cacheFileUri,
+          to: resource.extendedInfo.fileUri,
+        });
+        this.downloads.delete(source);
+        ResourceFetcherUtils.triggerHuggingFaceDownloadCounter(
+          resource.extendedInfo.uri
+        );
+
+        return this.returnOrStartNext(
+          resource.extendedInfo,
+          ResourceFetcherUtils.removeFilePrefix(resource.extendedInfo.fileUri)
+        );
       }
-    );
-    const result = await downloadResumable.downloadAsync();
-    if (!result || result.status !== 200) {
-      throw new Error(`Failed to fetch resource from '${uri}'`);
     }
-    await moveAsync({ from: cacheFileUri, to: fileUri });
+  }
 
-    this.triggerHuggingFaceDownloadCounter(uri);
+  private static async cancel(source: ResourceSource) {
+    const resource = this.downloads.get(source)!;
+    await resource.downloadResumable.cancelAsync();
+    this.downloads.delete(source);
+  }
 
-    return this.removeFilePrefix(fileUri);
+  static async pauseFetching(...sources: ResourceSource[]) {
+    const source = this.findActive(sources);
+    await this.pause(source);
   }
 
-  static async fetchMultipleResources(
-    callback: (downloadProgress: number) => void = () => {},
-    ...sources: ResourceSource[]
-  ) {
-    const paths = [];
-
-    for (let idx = 0; idx < sources.length; idx++) {
-      paths.push(
-        await this.fetch(
-          sources[idx]!,
-          this.calculateDownloadProgress(sources.length, idx, callback)
-        )
-      );
-    }
+  static async resumeFetching(...sources: ResourceSource[]) {
+    const source = this.findActive(sources);
+    await this.resume(source);
+  }
 
-    return paths;
+  static async cancelFetching(...sources: ResourceSource[]) {
+    const source = this.findActive(sources);
+    await this.cancel(source);
   }
 
-  static async deleteMultipleResources(...sources: ResourceSource[]) {
+  private static findActive(sources: ResourceSource[]) {
     for (const source of sources) {
-      const filename = this.getFilenameFromUri(source as string);
-      const fileUri = `${RNEDirectory}${filename}`;
-      if (await this.checkFileExists(fileUri)) {
-        await deleteAsync(fileUri);
+      if (this.downloads.has(source)) {
+        return source;
       }
     }
-  }
-
-  private static calculateDownloadProgress(
-    numberOfFiles: number,
-    currentFileIndex: number,
-    setProgress: (downloadProgress: number) => void
-  ) {
-    return (progress: number) => {
-      if (progress === 1 && currentFileIndex === numberOfFiles - 1) {
-        setProgress(1);
-        return;
-      }
-      const contributionPerFile = 1 / numberOfFiles;
-      const baseProgress = contributionPerFile * currentFileIndex;
-      const scaledProgress = progress * contributionPerFile;
-      const updatedProgress = baseProgress + scaledProgress;
-      setProgress(updatedProgress);
-    };
+    throw new Error(
+      'None of given sources are currently during downloading process.'
+    );
   }
 
   static async listDownloadedFiles() {
@@ -128,69 +263,156 @@ export class ResourceFetcher {
     return files.filter((file) => file.endsWith('.pte'));
   }
 
-  private static async handleObject(source: object) {
+  static async deleteResources(...sources: ResourceSource[]) {
+    for (const source of sources) {
+      const filename = ResourceFetcherUtils.getFilenameFromUri(
+        source as string
+      );
+      const fileUri = `${RNEDirectory}${filename}`;
+      if (await ResourceFetcherUtils.checkFileExists(fileUri)) {
+        await deleteAsync(fileUri);
+      }
+    }
+  }
+
+  static async getFilesTotalSize(...sources: ResourceSource[]) {
+    return (await ResourceFetcherUtils.getFilesSizes(sources)).totalLength;
+  }
+
+  private static async handleObject(source: ResourceSource) {
+    if (typeof source !== 'object') {
+      throw new Error('Source is expected to be object!');
+    }
     const jsonString = JSON.stringify(source);
-    const digest = this.hashObject(jsonString);
+    const digest = ResourceFetcherUtils.hashObject(jsonString);
     const filename = `${digest}.json`;
     const path = `${RNEDirectory}${filename}`;
 
-    if (await this.checkFileExists(path)) {
-      return this.removeFilePrefix(path);
+    if (await ResourceFetcherUtils.checkFileExists(path)) {
+      return ResourceFetcherUtils.removeFilePrefix(path);
     }
 
-    await this.createDirectoryIfNoExists();
+    await ResourceFetcherUtils.createDirectoryIfNoExists();
     await writeAsStringAsync(path, jsonString, {
       encoding: EncodingType.UTF8,
     });
 
-    return this.removeFilePrefix(path);
+    return ResourceFetcherUtils.removeFilePrefix(path);
   }
 
-  private static getFilenameFromUri(uri: string) {
-    let cleanUri = uri.replace(/^https?:\/\//, '');
-    cleanUri = cleanUri.split('?')?.[0]?.split('#')?.[0] ?? cleanUri;
-    return cleanUri.replace(/[^a-zA-Z0-9._-]/g, '_');
+  private static handleLocalFile(source: ResourceSource) {
+    if (typeof source !== 'string') {
+      throw new Error('Source is expected to be string.');
+    }
+    return ResourceFetcherUtils.removeFilePrefix(source);
   }
 
-  private static removeFilePrefix(uri: string) {
-    return uri.startsWith('file://') ? uri.slice(7) : uri;
+  private static async handleReleaseModeFile(
+    sourceExtended: ResourceSourceExtended
+  ) {
+    const source = sourceExtended.source;
+    if (typeof source !== 'number') {
+      throw new Error('Source is expected to be string.');
+    }
+    const asset = Asset.fromModule(source);
+    const uri = asset.uri;
+    const filename = ResourceFetcherUtils.getFilenameFromUri(uri);
+    const fileUri = `${RNEDirectory}${filename}`;
+    // On Android, file uri does not contain file extension, so we add it manually
+    const fileUriWithType =
+      Platform.OS === 'android' ? `${fileUri}.${asset.type}` : fileUri;
+    if (await ResourceFetcherUtils.checkFileExists(fileUri)) {
+      return ResourceFetcherUtils.removeFilePrefix(fileUri);
+    }
+    await ResourceFetcherUtils.createDirectoryIfNoExists();
+    await copyAsync({
+      from: asset.uri,
+      to: fileUriWithType,
+    });
+    return ResourceFetcherUtils.removeFilePrefix(fileUriWithType);
   }
 
-  private static hashObject(jsonString: string) {
-    let hash = 0;
-    for (let i = 0; i < jsonString.length; i++) {
-      // eslint-disable-next-line no-bitwise
-      hash = (hash << 5) - hash + jsonString.charCodeAt(i);
-      // eslint-disable-next-line no-bitwise
-      hash |= 0;
+  private static async handleDevModeFile(
+    sourceExtended: ResourceSourceExtended
+  ) {
+    const source = sourceExtended.source;
+    if (typeof source !== 'number') {
+      throw new Error('Source is expected to be a number.');
     }
-    // eslint-disable-next-line no-bitwise
-    return (hash >>> 0).toString();
+    sourceExtended.uri = Asset.fromModule(source).uri;
+    return await this.handleRemoteFile(sourceExtended);
   }
 
-  /*
-   * Increments the Hugging Face download counter if the URI points to a Software Mansion Hugging Face repo.
-   * More information: https://huggingface.co/docs/hub/models-download-stats
-   */
-  private static triggerHuggingFaceDownloadCounter(uri: string) {
-    const url = new URL(uri);
-    if (
-      url.host === 'huggingface.co' &&
-      url.pathname.startsWith('/software-mansion/')
-    ) {
-      const baseUrl = `${url.protocol}//${url.host}${url.pathname.split('resolve')[0]}`;
-      fetch(`${baseUrl}resolve/main/config.json`, { method: 'HEAD' });
+  private static async handleRemoteFile(
+    sourceExtended: ResourceSourceExtended
+  ) {
+    const source = sourceExtended.source;
+    if (typeof source === 'object') {
+      throw new Error('Source is expected to be a string or a number.');
     }
-  }
+    if (this.downloads.has(source)) {
+      const resource = this.downloads.get(source)!;
+      if (resource.status === DownloadStatus.PAUSED) {
+        // if the download is paused, `fetch` is treated like `resume`
+        this.resume(source);
+      }
+      // if the download is ongoing, throw error.
+      throw new Error('Already downloading this file.');
+    }
+    if (typeof source === 'number' && !sourceExtended.uri) {
+      throw new Error('Source Uri is expected to be available here.');
+    }
+    if (typeof source === 'string') {
+      sourceExtended.uri = source;
+    }
+    const uri = sourceExtended.uri!;
+    const filename = ResourceFetcherUtils.getFilenameFromUri(uri);
+    sourceExtended.fileUri = `${RNEDirectory}${filename}`;
+    sourceExtended.cacheFileUri = `${cacheDirectory}${filename}`;
 
-  private static async createDirectoryIfNoExists() {
-    if (!(await this.checkFileExists(RNEDirectory))) {
-      await makeDirectoryAsync(RNEDirectory, { intermediates: true });
+    if (await ResourceFetcherUtils.checkFileExists(sourceExtended.fileUri)) {
+      return ResourceFetcherUtils.removeFilePrefix(sourceExtended.fileUri);
     }
-  }
+    await ResourceFetcherUtils.createDirectoryIfNoExists();
 
-  private static async checkFileExists(fileUri: string) {
-    const fileInfo = await getInfoAsync(fileUri);
-    return fileInfo.exists;
+    const downloadResumable = createDownloadResumable(
+      uri,
+      sourceExtended.cacheFileUri,
+      { sessionType: FileSystemSessionType.BACKGROUND },
+      ({ totalBytesWritten, totalBytesExpectedToWrite }) => {
+        if (totalBytesExpectedToWrite === -1) {
+          // If totalBytesExpectedToWrite is -1, it means the server does not provide content length.
+          sourceExtended.callback!(0);
+          return;
+        }
+        sourceExtended.callback!(totalBytesWritten / totalBytesExpectedToWrite);
+      }
+    );
+    //create value for the this.download Map
+    const downloadResource: DownloadResource = {
+      downloadResumable: downloadResumable,
+      status: DownloadStatus.ONGOING,
+      extendedInfo: sourceExtended,
+    };
+    //add key-value pair to map
+    this.downloads.set(source, downloadResource);
+    const result = await downloadResumable.downloadAsync();
+    if (
+      !this.downloads.has(source) ||
+      this.downloads.get(source)!.status === DownloadStatus.PAUSED
+    ) {
+      // if canceled or paused during the download
+      return null;
+    }
+    if (!result || result.status !== HTTP_CODE.OK) {
+      throw new Error(`Failed to fetch resource from '${source}'`);
+    }
+    await moveAsync({
+      from: sourceExtended.cacheFileUri,
+      to: sourceExtended.fileUri,
+    });
+    this.downloads.delete(source);
+    ResourceFetcherUtils.triggerHuggingFaceDownloadCounter(uri);
+    return ResourceFetcherUtils.removeFilePrefix(sourceExtended.fileUri);
   }
 }