@octane-xplat/files 0.10.0 → 0.11.1

package/src/files.ts

@@ -2,10 +2,26 @@
 // are still used for writes; picked Android SAF references may be content://
 // URIs and must be read through ContentResolver.
 import { openFilePicker } from '@nativescript-community/ui-document-picker'
-import { Application, File, knownFolders, path } from '@nativescript/core'
-import type { FileRef } from './types'
+import { Application, File, knownFolders, path, Utils } from '@nativescript/core'
+import {
+	assertSafeFileName,
+	exactBuffer,
+	exportBusy,
+	fileTooLarge,
+	throwIfAborted,
+} from './file-bytes'
+
+import type {
+	FileExportOptions,
+	FileExportResult,
+	FileReadBytesOptions,
+	FileRef,
+	Files,
+} from './types'
 
 const docs = () => knownFolders.documents()
+const READ_CHUNK = 64 * 1024
+const ANDROID_EXPORT_REQUEST_CODE = 1241
 
 function pickerTypes(accept: string): { extensions: string[]; mimeTypes: string[] } {
 	const values = accept
@@ -106,12 +122,270 @@ async function pickFiles(
 	}))
 }
 
-export const files = {
-	/** Opens the platform document picker and returns selected opaque URIs. */
+// openInputStream accepts content:// and file:// schemes; bare paths go
+// through FileInputStream. Returns null when the resolver cannot open the URI.
+function openAndroidInput(uri: string): any {
+	const activity = Application.android?.foregroundActivity ?? Application.android?.startActivity
+	if (uri.startsWith('content://') || uri.startsWith('file://')) {
+		return activity?.getContentResolver()?.openInputStream(android.net.Uri.parse(uri))
+	}
+
+	return new java.io.FileInputStream(uri)
+}
+
+function readAndroidBytes(uri: string, opts?: FileReadBytesOptions): Uint8Array {
+	const input = openAndroidInput(uri)
+	if (!input) {
+		throw new Error(`Unable to open picked file: ${uri}`)
+	}
+
+	const out = new java.io.ByteArrayOutputStream()
+	const chunk = Array.create('byte', READ_CHUNK)
+	try {
+		let count: number
+		while ((count = input.read(chunk)) !== -1) {
+			throwIfAborted(opts?.signal)
+			out.write(chunk, 0, count)
+			if (opts?.maxBytes != null && out.size() > opts.maxBytes) {
+				throw fileTooLarge(uri, opts.maxBytes)
+			}
+		}
+	} finally {
+		input.close()
+	}
+
+	// ArrayBuffer.from is an NS Android runtime builtin that takes a
+	// java.nio.ByteBuffer — wrap the byte[] rather than marshalling per byte.
+	return new Uint8Array((ArrayBuffer as any).from(java.nio.ByteBuffer.wrap(out.toByteArray())))
+}
+
+// Picked iOS refs come from the picker's Import mode, so they are app-owned
+// copies — no security-scoped access needed. Single-pick URIs keep their
+// percent-encoding, so fall back to a decoded path when the literal misses.
+function iosFilePath(uri: string): string {
+	let p = uri.startsWith('file://') ? uri.slice('file://'.length) : uri
+	if (NSFileManager.defaultManager.fileExistsAtPath(p)) {
+		return p
+	}
+
+	try {
+		const decoded = decodeURIComponent(p)
+		if (decoded !== p && NSFileManager.defaultManager.fileExistsAtPath(decoded)) {
+			return decoded
+		}
+	} catch {}
+
+	return p
+}
+
+function readIosBytes(uri: string, opts?: FileReadBytesOptions): Uint8Array {
+	const p = iosFilePath(uri)
+	const handle = NSFileHandle.fileHandleForReadingAtPath(p)
+	if (!handle) {
+		throw new Error(`Unable to open picked file: ${uri}`)
+	}
+
+	const out = NSMutableData.new()
+	try {
+		while (true) {
+			throwIfAborted(opts?.signal)
+			const data = handle.readDataOfLength(READ_CHUNK)
+			if (!data || data.length === 0) {
+				break
+			}
+
+			out.appendData(data)
+			if (opts?.maxBytes != null && out.length > opts.maxBytes) {
+				throw fileTooLarge(uri, opts.maxBytes)
+			}
+		}
+	} finally {
+		handle.closeFile()
+	}
+
+	return new Uint8Array(interop.bufferFromData(out))
+}
+
+// ContentResolver.openOutputStream accepts content:// and file:// URIs; bare
+// paths go through FileOutputStream. The WritableByteChannel adapter writes
+// the full buffer per the OutputStream contract — no chunked short writes.
+function writeAndroidBytes(uri: string, bytes: Uint8Array): void {
+	const activity = Application.android?.foregroundActivity ?? Application.android?.startActivity
+	const out: java.io.OutputStream =
+		uri.startsWith('content://') || uri.startsWith('file://')
+			? activity?.getContentResolver()?.openOutputStream(android.net.Uri.parse(uri))
+			: new java.io.FileOutputStream(uri)
+
+	if (!out) {
+		throw new Error(`Unable to open destination: ${uri}`)
+	}
+
+	try {
+		java.nio.channels.Channels.newChannel(out).write(exactBuffer(bytes) as any)
+	} finally {
+		out.close()
+	}
+}
+
+function androidExport(
+	name: string,
+	bytes: Uint8Array,
+	opts?: FileExportOptions,
+): Promise<FileExportResult> {
+	const activity = Application.android?.foregroundActivity ?? Application.android?.startActivity
+	if (!activity) {
+		return Promise.resolve('unavailable')
+	}
+
+	const Intent = android.content.Intent
+	const intent = new Intent(Intent.ACTION_CREATE_DOCUMENT)
+	intent.addCategory(Intent.CATEGORY_OPENABLE)
+	intent.setType(opts?.mimeType ?? '*/*')
+	intent.putExtra(Intent.EXTRA_TITLE, name)
+	intent.addFlags(Intent.FLAG_GRANT_WRITE_URI_PERMISSION | Intent.FLAG_GRANT_READ_URI_PERMISSION)
+
+	return new Promise<FileExportResult>((resolve, reject) => {
+		const onEvent = (event: any) => {
+			if (event.requestCode !== ANDROID_EXPORT_REQUEST_CODE) {
+				return
+			}
+
+			Application.android.off(Application.android.activityResultEvent, onEvent)
+			const uri = event.intent?.getData?.()
+			if (event.resultCode !== android.app.Activity.RESULT_OK || !uri) {
+				resolve('cancelled')
+				return
+			}
+
+			try {
+				writeAndroidBytes(uri.toString(), bytes)
+				resolve('saved')
+			} catch (error) {
+				reject(error)
+			}
+		}
+
+		Application.android.on(Application.android.activityResultEvent, onEvent)
+		try {
+			activity.startActivityForResult(intent, ANDROID_EXPORT_REQUEST_CODE)
+		} catch (error) {
+			Application.android.off(Application.android.activityResultEvent, onEvent)
+			reject(error)
+		}
+	})
+}
+
+// One export UI at a time: Android listeners share the activity-result event,
+// and the iOS picker delegate below is kept alive in this slot (the
+// controller's `delegate` property is weak). A second concurrent export would
+// corrupt the first, so `files.export` fails fast instead.
+let activeExport: { delegate?: any; controller?: any } | null = null
+
+// Per-call delegate — defined lazily because NSObject and the picker symbols
+// only exist on iOS, while this module also loads on Android.
+let IosExportDelegate: any = null
+
+function iosExportDelegateClass(): any {
+	if (IosExportDelegate) {
+		return IosExportDelegate
+	}
+
+	IosExportDelegate = class extends NSObject {
+		static ObjCProtocols = [UIDocumentPickerDelegate]
+		finish: ((saved: boolean) => void) | null = null
+
+		documentPickerDidPickDocumentAtURL(controller: any, _url: any): void {
+			this.settle(controller, true)
+		}
+		documentPickerDidPickDocumentsAtURLs(controller: any, urls: any): void {
+			this.settle(controller, urls.count > 0)
+		}
+		documentPickerWasCancelled(controller: any): void {
+			this.settle(controller, false)
+		}
+		private settle(controller: any, saved: boolean): void {
+			const finish = this.finish
+			this.finish = null
+			controller.delegate = null
+			finish?.(saved)
+		}
+	}
+
+	return IosExportDelegate
+}
+
+function iosVisibleViewController(): any {
+	const app = UIApplication.sharedApplication
+	const keyWindow = app.keyWindow || (app.windows.count > 0 && app.windows[0])
+	// Utils.ios is only populated on iOS — typed as an empty bag elsewhere.
+	const getVisible = (Utils.ios as any)?.getVisibleViewController
+	return keyWindow && typeof getVisible === 'function'
+		? getVisible(keyWindow.rootViewController)
+		: null
+}
+
+// Own export picker rather than the upstream plugin's saveFile: that helper
+// runs an async promise executor (a failed temp write or a missing visible
+// controller leaves the promise unsettled) and holds the picker delegate in
+// one weak module slot, so overlapping calls drop the earlier request.
+async function iosExport(
+	name: string,
+	bytes: Uint8Array,
+	slot: { delegate?: any; controller?: any },
+): Promise<FileExportResult> {
+	const tempPath = path.join(knownFolders.temp().path, name)
+	const staged = NSData.dataWithBytesLength(bytes as any, bytes.byteLength).writeToFileAtomically(
+		tempPath,
+		true,
+	)
+
+	const removeTemp = () => {
+		try {
+			File.fromPath(tempPath).removeSync()
+		} catch {}
+	}
+
+	if (!staged) {
+		throw new Error(`Failed to stage export file: ${name}`)
+	}
+
+	const visibleVC = iosVisibleViewController()
+	if (!visibleVC) {
+		removeTemp()
+		throw new Error('No visible view controller to present the export picker')
+	}
+
+	return new Promise<FileExportResult>((resolve, reject) => {
+		try {
+			const controller = UIDocumentPickerViewController.alloc().initForExportingURLsAsCopy(
+				[NSURL.fileURLWithPath(tempPath)] as any,
+				true,
+			)
+
+			const delegate = iosExportDelegateClass().new()
+			// `saved` only after the system commits the export-as-copy to the
+			// chosen destination; dismissal settles as 'cancelled'.
+			delegate.finish = (saved: boolean) => {
+				removeTemp()
+				resolve(saved ? 'saved' : 'cancelled')
+			}
+
+			slot.delegate = delegate
+			slot.controller = controller
+			controller.delegate = delegate
+			controller.shouldShowFileExtensions = true
+			visibleVC.presentViewControllerAnimatedCompletion(controller, true, null)
+		} catch (error) {
+			removeTemp()
+			reject(error)
+		}
+	})
+}
+
+export const files: Files = {
 	async pickMultiple(accept = '*/*', opts?: { startingFolder?: string }): Promise<FileRef[]> {
 		return pickFiles(accept, true, opts)
 	},
-	/** Opens the platform document picker and returns its first opaque URI. */
 	async pick(accept = '*/*', opts?: { startingFolder?: string }): Promise<FileRef | null> {
 		return (await pickFiles(accept, false, opts))[0] ?? null
 	},
@@ -120,14 +394,63 @@ export const files = {
 			return readContentUri(ref.uri)
 		}
 
-		return File.fromPath(ref.uri).readText()
+		return File.fromPath(Application.android ? ref.uri : iosFilePath(ref.uri)).readText()
+	},
+	async readBytes(ref: FileRef, opts?: FileReadBytesOptions): Promise<Uint8Array> {
+		throwIfAborted(opts?.signal)
+		return Application.android ? readAndroidBytes(ref.uri, opts) : readIosBytes(ref.uri, opts)
 	},
 	async writeText(name: string, text: string): Promise<FileRef> {
+		assertSafeFileName(name)
 		const p = path.join(docs().path, name)
 		const f = File.fromPath(p)
 		f.writeTextSync(text)
 		return { name, uri: p }
 	},
+	async writeBytes(name: string, bytes: Uint8Array): Promise<FileRef> {
+		assertSafeFileName(name)
+		const p = path.join(docs().path, name)
+		if (Application.android) {
+			writeAndroidBytes(p, bytes)
+		} else {
+			// FileSystemAccess.writeBufferSync drops the writeToFileAtomically
+			// result and swallows errors without an onError callback, so a
+			// failed write would resolve with a ref to a missing file. Check
+			// the BOOL — it is the platform's overwrite confirmation.
+			const written = NSData.dataWithBytesLength(
+				bytes as any,
+				bytes.byteLength,
+			).writeToFileAtomically(p, true)
+
+			if (!written) {
+				throw new Error(`Failed to write file: ${p}`)
+			}
+		}
+
+		return { name, uri: p }
+	},
+	async export(
+		name: string,
+		bytes: Uint8Array,
+		opts?: FileExportOptions,
+	): Promise<FileExportResult> {
+		assertSafeFileName(name)
+		if (activeExport) {
+			throw exportBusy()
+		}
+
+		const slot: { delegate?: any; controller?: any } = {}
+		activeExport = slot
+		try {
+			return Application.android
+				? await androidExport(name, bytes, opts)
+				: await iosExport(name, bytes, slot)
+		} finally {
+			if (activeExport === slot) {
+				activeExport = null
+			}
+		}
+	},
 	release(ref: FileRef): void {
 		const cachePrefix = knownFolders.temp().path + '/'
 		if (!ref.uri.startsWith(cachePrefix)) {

package/src/files.web.test.ts

@@ -0,0 +1,117 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { files } from './files.web'
+
+beforeEach(() => {
+	let counter = 0
+	vi.stubGlobal('URL', {
+		...URL,
+		createObjectURL: (_blob: Blob) => `blob:mock/${counter++}`,
+		revokeObjectURL: vi.fn(),
+	})
+})
+
+afterEach(() => {
+	vi.unstubAllGlobals()
+	vi.restoreAllMocks()
+	delete (window as any).showSaveFilePicker
+})
+
+describe('files.writeBytes (web)', () => {
+	it('starts a download and returns a readable ref', async () => {
+		const ref = await files.writeBytes('report.bin', new Uint8Array([1, 2, 3, 255]))
+		expect(ref.name).toBe('report.bin')
+		expect(ref.uri).toMatch(/^blob:/)
+
+		const back = await files.readBytes(ref)
+		expect([...back]).toEqual([1, 2, 3, 255])
+	})
+
+	it('rejects path-traversal names', async () => {
+		await expect(files.writeBytes('../escape.bin', new Uint8Array(1))).rejects.toThrow(
+			/Unsafe file name/,
+		)
+	})
+})
+
+describe('files.readBytes (web)', () => {
+	it('enforces maxBytes without returning truncated data', async () => {
+		const ref = await files.writeBytes('big.bin', new Uint8Array(1024))
+		await expect(files.readBytes(ref, { maxBytes: 512 })).rejects.toThrow(/exceeds/)
+	})
+
+	it('rejects on an aborted signal', async () => {
+		const ref = await files.writeBytes('a.bin', new Uint8Array([1]))
+		const controller = new AbortController()
+		controller.abort()
+		await expect(files.readBytes(ref, { signal: controller.signal })).rejects.toThrowError(
+			expect.objectContaining({ name: 'AbortError' }),
+		)
+	})
+
+	it('rejects when the signal aborts during blob.arrayBuffer()', async () => {
+		const controller = new AbortController()
+		vi.spyOn(Blob.prototype, 'arrayBuffer').mockImplementation(async () => {
+			controller.abort()
+			return new Uint8Array([1]).buffer
+		})
+
+		const ref = await files.writeBytes('a.bin', new Uint8Array([1]))
+		await expect(files.readBytes(ref, { signal: controller.signal })).rejects.toThrowError(
+			expect.objectContaining({ name: 'AbortError' }),
+		)
+	})
+
+	it('reads foreign URLs through fetch with the cap applied', async () => {
+		const body = new Uint8Array([1, 2, 3, 4])
+		vi.stubGlobal(
+			'fetch',
+			vi.fn(async () => new Response(body)),
+		)
+
+		const back = await files.readBytes({ name: 'remote.bin', uri: 'https://x/remote.bin' })
+		expect([...back]).toEqual([1, 2, 3, 4])
+		expect(fetch).toHaveBeenCalledWith('https://x/remote.bin', { signal: undefined })
+
+		await expect(
+			files.readBytes({ name: 'remote.bin', uri: 'https://x/remote.bin' }, { maxBytes: 2 }),
+		).rejects.toThrow(/exceeds/)
+	})
+
+	it('revokes the object URL on release', async () => {
+		const ref = await files.writeBytes('gone.bin', new Uint8Array([1]))
+		files.release(ref)
+		expect(URL.revokeObjectURL).toHaveBeenCalledWith(ref.uri)
+	})
+})
+
+describe('files.export (web)', () => {
+	it('returns unavailable without the File System Access API', async () => {
+		expect(await files.export('a.bin', new Uint8Array([1]))).toBe('unavailable')
+	})
+
+	it('writes bytes through a save picker and reports saved', async () => {
+		const write = vi.fn()
+		const close = vi.fn(async () => {})
+		const showSaveFilePicker = vi.fn(async () => ({
+			createWritable: async () => ({ write, close }),
+		}))
+
+		;(window as any).showSaveFilePicker = showSaveFilePicker
+
+		const result = await files.export('dump.bin', new Uint8Array([7, 8]))
+		expect(result).toBe('saved')
+		expect(write).toHaveBeenCalledWith(new Uint8Array([7, 8]))
+		expect(close).toHaveBeenCalled()
+	})
+
+	it('maps picker dismissal to cancelled', async () => {
+		const showSaveFilePicker = vi.fn(async () => {
+			throw new DOMException('dismissed', 'AbortError')
+		})
+
+		;(window as any).showSaveFilePicker = showSaveFilePicker
+
+		expect(await files.export('dump.bin', new Uint8Array([7]))).toBe('cancelled')
+	})
+})

package/src/files.web.ts

@@ -1,7 +1,31 @@
 // Files — web leaf. Desktop webview hosts own real pickers and file:// refs;
 // outside a host this uses opaque object URLs and browser downloads.
 import { desktopHost } from '@octane-xplat/platform/host/web'
-import type { FileRef } from './types'
+import {
+	assertSafeFileName,
+	concatBytes,
+	exactBuffer,
+	fileTooLarge,
+	throwIfAborted,
+} from './file-bytes'
+
+import type {
+	FileExportOptions,
+	FileExportResult,
+	FileReadBytesOptions,
+	FileRef,
+	Files,
+} from './types'
+
+// Object URLs this leaf minted, keyed by URL, so readBytes returns exact bytes
+// without a fetch round-trip and release can drop the backing Blob.
+const objectBlobs = new Map<string, Blob>()
+
+function mintObjectUrl(blob: Blob): string {
+	const uri = URL.createObjectURL(blob)
+	objectBlobs.set(uri, blob)
+	return uri
+}
 
 function chooseFiles(accept: string, multiple: boolean): Promise<FileRef[]> {
 	return new Promise((resolve) => {
@@ -12,7 +36,7 @@ function chooseFiles(accept: string, multiple: boolean): Promise<FileRef[]> {
 		input.onchange = () => {
 			const refs: FileRef[] = []
 			for (const file of Array.from(input.files ?? [])) {
-				refs.push({ name: file.name, uri: URL.createObjectURL(file) })
+				refs.push({ name: file.name, uri: mintObjectUrl(file) })
 			}
 
 			resolve(refs)
@@ -23,7 +47,53 @@ function chooseFiles(accept: string, multiple: boolean): Promise<FileRef[]> {
 	})
 }
 
-export const files = {
+// Capped stream read: stop as soon as the cap is exceeded instead of
+// materializing the whole response.
+async function fetchBytes(uri: string, opts?: FileReadBytesOptions): Promise<Uint8Array> {
+	const response = await fetch(uri, { signal: opts?.signal })
+	if (!response.ok) {
+		throw new Error(`Unable to read file: ${uri}`)
+	}
+
+	if (opts?.maxBytes == null) {
+		return new Uint8Array(await response.arrayBuffer())
+	}
+
+	const reader = response.body?.getReader()
+	if (!reader) {
+		const bytes = new Uint8Array(await response.arrayBuffer())
+		if (bytes.byteLength > opts.maxBytes) {
+			throw fileTooLarge(uri, opts.maxBytes)
+		}
+
+		return bytes
+	}
+
+	const chunks: Uint8Array[] = []
+	let total = 0
+	try {
+		while (true) {
+			const { done, value } = await reader.read()
+			if (done) {
+				break
+			}
+
+			total += value.byteLength
+			if (total > opts.maxBytes) {
+				await reader.cancel().catch(() => {})
+				throw fileTooLarge(uri, opts.maxBytes)
+			}
+
+			chunks.push(value)
+		}
+	} finally {
+		reader.releaseLock()
+	}
+
+	return concatBytes(chunks, total)
+}
+
+export const files: Files = {
 	async pickMultiple(accept = '*/*', _opts?: { startingFolder?: string }): Promise<FileRef[]> {
 		return chooseFiles(accept, true)
 	},
@@ -48,8 +118,26 @@ export const files = {
 
 		return (await fetch(ref.uri)).text()
 	},
+	async readBytes(ref: FileRef, opts?: FileReadBytesOptions): Promise<Uint8Array> {
+		throwIfAborted(opts?.signal)
+		const blob = objectBlobs.get(ref.uri)
+		if (blob) {
+			if (opts?.maxBytes != null && blob.size > opts.maxBytes) {
+				throw fileTooLarge(ref.uri, opts.maxBytes)
+			}
+
+			const bytes = new Uint8Array(await blob.arrayBuffer())
+			throwIfAborted(opts?.signal)
+			return bytes
+		}
+
+		// Host file:// refs need a host binary read, which the desktop service
+		// contract does not provide; other URLs go through fetch.
+		return fetchBytes(ref.uri, opts)
+	},
 	/** Desktop hosts write the selected path; plain web starts a download. */
 	async writeText(name: string, text: string): Promise<FileRef> {
+		assertSafeFileName(name)
 		const host = desktopHost()
 		if (host && (await host.supports('files', 'writeText'))) {
 			const file = await host.files.writeText(name, text)
@@ -60,15 +148,56 @@ export const files = {
 			return file
 		}
 
-		const uri = URL.createObjectURL(new Blob([text], { type: 'text/plain' }))
+		const uri = mintObjectUrl(new Blob([text], { type: 'text/plain' }))
+		const a = document.createElement('a')
+		a.href = uri
+		a.download = name
+		a.click()
+		return { name, uri }
+	},
+	/** The desktop host contract is text-only, so bytes always download. */
+	async writeBytes(name: string, bytes: Uint8Array): Promise<FileRef> {
+		assertSafeFileName(name)
+		const uri = mintObjectUrl(new Blob([exactBuffer(bytes)], { type: 'application/octet-stream' }))
 		const a = document.createElement('a')
 		a.href = uri
 		a.download = name
 		a.click()
 		return { name, uri }
 	},
+	async export(
+		name: string,
+		bytes: Uint8Array,
+		opts?: FileExportOptions,
+	): Promise<FileExportResult> {
+		assertSafeFileName(name)
+		const picker = (window as any).showSaveFilePicker as ((opts: any) => Promise<any>) | undefined
+
+		if (typeof picker !== 'function') {
+			return 'unavailable'
+		}
+
+		const extension = name.includes('.') ? `.${name.split('.').pop()}` : null
+		const types =
+			opts?.mimeType && extension ? [{ accept: { [opts.mimeType]: [extension] } }] : undefined
+
+		try {
+			const handle = await picker.call(window, { suggestedName: name, types })
+			const writable = await handle.createWritable()
+			await writable.write(bytes)
+			await writable.close()
+			return 'saved'
+		} catch (error) {
+			if ((error as DOMException)?.name === 'AbortError') {
+				return 'cancelled'
+			}
+
+			throw error
+		}
+	},
 	release(ref: FileRef): void {
 		if (ref.uri.startsWith('blob:')) {
+			objectBlobs.delete(ref.uri)
 			URL.revokeObjectURL(ref.uri)
 		}
 	},