feat(fs): add bounded byte-range reads

src/fileSystem/externalFs.js

@@ -2,6 +2,7 @@ import loader from "dialogs/loader";
 import { decode, encode, getEncodingName } from "utils/encodings";
 import helpers from "utils/helpers";
 import Url from "utils/Url";
+import { decodeReadRange, validateReadRange } from "./readRange";
 
 const externalFs = {
 	async readFile(url) {
@@ -11,6 +12,21 @@ const externalFs = {
 		});
 	},
 
+	async readFileRange(url, start, end) {
+		const range = validateReadRange(start, end);
+		if (range.length === 0) return { data: new ArrayBuffer(0) };
+		url = await this.formatUri(url);
+		return new Promise((resolve, reject) => {
+			sdcard.readRange(
+				url,
+				range.start,
+				range.end,
+				(data) => resolve({ data }),
+				reject,
+			);
+		});
+	},
+
 	async readAsText(url, encoding) {
 		url = await this.formatUri(url);
 		return new Promise((resolve, reject) => {
@@ -203,6 +219,10 @@ function createFs(url) {
 			let { data } = await externalFs.readFile(url);
 			return data;
 		},
+		async readFileRange(start, end, encoding) {
+			const { data } = await externalFs.readFileRange(url, start, end);
+			return decodeReadRange(data, encoding);
+		},
 		async writeFile(content, encoding) {
 			if (typeof content === "string" && encoding) {
 				const charset = getEncodingName(

src/fileSystem/index.js

@@ -4,6 +4,7 @@ import Url from "utils/Url";
 import externalFs from "./externalFs";
 import Ftp from "./ftp";
 import internalFs from "./internalFs";
+import { decodeReadRange, validateReadRange } from "./readRange";
 import Sftp from "./sftp";
 
 const fsList = [];
@@ -39,6 +40,7 @@ const fsList = [];
  * @property {() => Promise<boolean>} exists Check if file or directory exists
  * @property {() => Promise<Stat>} stat Get file or directory stat
  * @property {(encoding:string) => Promise<FileContent>} readFile Read file
+ * @property {(start:number, end:number, encoding?:string) => Promise<FileContent>} [readFileRange] Read a half-open byte range without loading the whole file
  * @property {(data:FileContent, encoding: string) => Promise<void>} writeFile Write file content
  * @property {(name:string, data:FileContent) => Promise<string>} createFile Create file and return url of the created file
  * @property {(name:string) => Promise<string>} createDirectory Create directory and return url of the created directory
@@ -94,6 +96,47 @@ fsOperation.extend(
 
 				return data;
 			},
+			async readFileRange(start, end, encoding) {
+				const range = validateReadRange(start, end);
+				if (range.length === 0) {
+					return decodeReadRange(new ArrayBuffer(0), encoding);
+				}
+
+				const response = await fetch(url, {
+					headers: {
+						Range: `bytes=${range.start}-${range.end - 1}`,
+					},
+				});
+
+				if (response.status !== 206) {
+					await response.body?.cancel();
+					throw new Error("HTTP server does not support byte-range reads");
+				}
+
+				const contentRange = response.headers.get("content-range");
+				const returnedRange = contentRange?.match(/^bytes (\d+)-(\d+)\//i);
+				if (
+					returnedRange &&
+					(Number(returnedRange[1]) !== range.start ||
+						Number(returnedRange[2]) >= range.end)
+				) {
+					await response.body?.cancel();
+					throw new Error("HTTP server returned a different byte range");
+				}
+
+				const contentLength = Number(response.headers.get("content-length"));
+				if (Number.isFinite(contentLength) && contentLength > range.length) {
+					await response.body?.cancel();
+					throw new Error("HTTP server returned more data than requested");
+				}
+
+				const data = await response.arrayBuffer();
+				if (data.byteLength > range.length) {
+					throw new Error("HTTP server returned more data than requested");
+				}
+
+				return decodeReadRange(data, encoding);
+			},
 			async writeFile(content, progress) {
 				return ajax.post(url, {
 					data: content,

src/fileSystem/internalFs.js

@@ -3,6 +3,7 @@ import ajax from "lib/ajax";
 import { decode, encode } from "utils/encodings";
 import helpers from "utils/helpers";
 import Url from "utils/Url";
+import { decodeReadRange, validateReadRange } from "./readRange";
 
 const internalFs = {
 	/**
@@ -122,6 +123,35 @@ const internalFs = {
 		});
 	},
 
+	/**
+	 * Read a half-open byte range without loading the complete file.
+	 * @param {string} filename
+	 * @param {number} start Inclusive byte offset
+	 * @param {number} end Exclusive byte offset
+	 * @returns {Promise<{data: ArrayBuffer}>}
+	 */
+	readFileRange(filename, start, end) {
+		const range = validateReadRange(start, end);
+		if (range.length === 0) {
+			return Promise.resolve({ data: new ArrayBuffer(0) });
+		}
+		return new Promise((resolve, reject) => {
+			reject = setMessage(reject);
+			window.resolveLocalFileSystemURL(
+				filename,
+				(fileEntry) => {
+					fileEntry.file((file) => {
+						const fileReader = new FileReader();
+						fileReader.onerror = () => reject(fileReader.error);
+						fileReader.onload = () => resolve({ data: fileReader.result });
+						fileReader.readAsArrayBuffer(file.slice(range.start, range.end));
+					}, reject);
+				},
+				reject,
+			);
+		});
+	},
+
 	/**
 	 * Rename a file or directory
 	 * @param {string} url
@@ -413,6 +443,10 @@ function createFs(url) {
 
 			return data;
 		},
+		async readFileRange(start, end, encoding) {
+			const { data } = await internalFs.readFileRange(url, start, end);
+			return decodeReadRange(data, encoding);
+		},
 		async writeFile(content, encoding) {
 			if (typeof content === "string" && encoding) {
 				content = await encode(content, encoding);

src/fileSystem/readRange.js

@@ -0,0 +1,43 @@
+import { decode } from "utils/encodings";
+
+// Native bridges return byte arrays, whose length is limited to a signed int.
+export const MAX_READ_RANGE_LENGTH = 0x7fffffff;
+
+/**
+ * Validate a half-open byte range used by filesystem implementations.
+ *
+ * @param {number} start Inclusive byte offset
+ * @param {number} end Exclusive byte offset
+ * @returns {{start: number, end: number, length: number}}
+ */
+export function validateReadRange(start, end) {
+	if (!Number.isSafeInteger(start) || start < 0) {
+		throw new RangeError("Range start must be a non-negative safe integer");
+	}
+
+	if (!Number.isSafeInteger(end) || end < start) {
+		throw new RangeError(
+			"Range end must be a safe integer greater than or equal to start",
+		);
+	}
+
+	const length = end - start;
+	if (length > MAX_READ_RANGE_LENGTH) {
+		throw new RangeError(
+			`Range length must not exceed ${MAX_READ_RANGE_LENGTH} bytes`,
+		);
+	}
+
+	return { start, end, length };
+}
+
+/**
+ * Decode range data only after the backend has performed a bounded byte read.
+ *
+ * @param {ArrayBuffer} data
+ * @param {string} [encoding]
+ * @returns {Promise<ArrayBuffer|string|object>}
+ */
+export async function decodeReadRange(data, encoding) {
+	return encoding ? decode(data, encoding) : data;
+}

src/fileSystem/sftp.js

@@ -5,6 +5,7 @@ import helpers from "utils/helpers";
 import Path from "utils/Path";
 import Url from "utils/Url";
 import internalFs from "./internalFs";
+import { decodeReadRange, validateReadRange } from "./readRange";
 
 let pendingConnection = null;
 let pendingConnectionID = null;
@@ -210,6 +211,22 @@ class SftpClient {
 		});
 	}
 
+	/** Read a half-open byte range directly from the remote file. */
+	async readFileRange(start, end) {
+		const range = validateReadRange(start, end);
+		if (range.length === 0) return { data: new ArrayBuffer(0) };
+		await this.#connectIfNotConnected();
+		return new Promise((resolve, reject) => {
+			sftp.getFileRange(
+				this.#safeName(this.#path),
+				range.start,
+				range.end,
+				(data) => resolve({ data }),
+				reject,
+			);
+		});
+	}
+
 	async copyTo(dest) {
 		const src = this.#path;
 		return new Promise((resolve, reject) => {
@@ -585,6 +602,19 @@ class SftpClient {
 		);
 	}
 
+	async #connectIfNotConnected() {
+		return new Promise((resolve, reject) => {
+			sftp.isConnected(async (connectionID) => {
+				try {
+					if (this.#notConnected(connectionID)) await this.connect();
+					resolve();
+				} catch (error) {
+					reject(error);
+				}
+			}, reject);
+		});
+	}
+
 	async #setStat() {
 		if (!this.#stat) {
 			this.#stat = await this.stat();
@@ -635,6 +665,10 @@ function createFs(sftp) {
 
 			return data;
 		},
+		async readFileRange(start, end, encoding) {
+			const { data } = await sftp.readFileRange(start, end);
+			return decodeReadRange(data, encoding);
+		},
 		async writeFile(content, encoding) {
 			if (typeof content === "string" && encoding) {
 				content = await encode(content, encoding);

src/plugins/sdcard/index.d.ts

@@ -115,6 +115,14 @@ interface SDcard {
     onSuccess: (url: string) => void,
     onFail: (err: any) => void,
   ): void;
+  /** Reads the half-open byte range [start, end) without loading the whole file. */
+  readRange(
+    src: string,
+    start: number,
+    end: number,
+    onSuccess: (data: ArrayBuffer) => void,
+    onFail: (err: any) => void,
+  ): void;
   /**
    * Checks if given file/directory
    * @param src File/Directory url

src/plugins/sdcard/src/android/SDcard.java

@@ -111,6 +111,14 @@ public boolean execute(
       case "read":
         readFile(arg1, callback);
         break;
+      case "readRange":
+        readFileRange(
+          arg1,
+          args.optLong(1, -1),
+          args.optLong(2, -1),
+          callback
+        );
+        break;
       case "readAsText":
         readAsText(arg1, arg2, callback);
         break;
@@ -497,6 +505,83 @@ public void run() {
       );
   }
 
+  private void readFileRange(
+    String filename,
+    long start,
+    long end,
+    CallbackContext callback
+  ) {
+    cordova
+      .getThreadPool()
+      .execute(
+        new Runnable() {
+          public void run() {
+            if (start < 0 || end < start || end - start > Integer.MAX_VALUE) {
+              callback.error("Invalid byte range");
+              return;
+            }
+
+            Uri uri = Uri.parse(formatUri(filename));
+            try (
+              InputStream input = context
+                .getContentResolver()
+                .openInputStream(uri)
+            ) {
+              if (input == null) {
+                callback.error("File not found");
+                return;
+              }
+
+              if (!skipFully(input, start)) {
+                callback.success(new byte[0]);
+                return;
+              }
+
+              callback.success(readAtMost(input, end - start));
+            } catch (Exception e) {
+              callback.error(e.toString());
+            }
+          }
+        }
+      );
+  }
+
+  private static boolean skipFully(InputStream input, long count)
+    throws IOException {
+    long remaining = count;
+    while (remaining > 0) {
+      long skipped = input.skip(remaining);
+      if (skipped > 0) {
+        remaining -= skipped;
+      } else if (input.read() == -1) {
+        return false;
+      } else {
+        remaining--;
+      }
+    }
+    return true;
+  }
+
+  private static byte[] readAtMost(InputStream input, long count)
+    throws IOException {
+    ByteArrayOutputStream output = new ByteArrayOutputStream(
+      (int) Math.min(count, 32768)
+    );
+    byte[] buffer = new byte[32768];
+    long remaining = count;
+    while (remaining > 0) {
+      int bytesRead = input.read(
+        buffer,
+        0,
+        (int) Math.min(buffer.length, remaining)
+      );
+      if (bytesRead == -1) break;
+      output.write(buffer, 0, bytesRead);
+      remaining -= bytesRead;
+    }
+    return output.toByteArray();
+  }
+
   private void readAsText(final String filename, final String encoding, final CallbackContext callback) {
     cordova
       .getThreadPool()

src/plugins/sdcard/www/plugin.js

@@ -44,6 +44,9 @@ module.exports = {
   read: function (filename, onSuccess, onFail) {
     cordova.exec(onSuccess, onFail, 'SDcard', 'read', [filename]);
   },
+  readRange: function (filename, start, end, onSuccess, onFail) {
+    cordova.exec(onSuccess, onFail, 'SDcard', 'readRange', [filename, String(start), String(end)]);
+  },
   readAsText: function (filename, encoding, onSuccess, onFail) {
     cordova.exec(onSuccess, onFail, 'SDcard', 'readAsText', [filename, encoding]);
   },