fix(download): prevent Android crash and create missing folders on download (#178)

Downloading an episode buffered the whole file via requestUrl, wrapped it in
a Blob, then round-tripped back to an ArrayBuffer before writing — holding ~3x
the episode size in the JS heap. On Android's constrained WebView this OOM-
crashed Obsidian mid-download with no file created (#113).

Thread a single ArrayBuffer from requestUrl straight into vault.createBinary,
dropping the Blob and the Blob->ArrayBuffer round-trip, and read audio-signature
bytes from a zero-copy Uint8Array view instead of Blob.slice + FileReader. This
removes every full-file copy PodNotes controls (peak ~3x -> ~1x). The remaining
peak is inside requestUrl's native base64 decode, which no plugin can reduce, so
this is a mitigation rather than a guaranteed cure for the very largest files.

Also create missing parent folders before createBinary (mirroring
createPodcastNote), so templated paths like podcast/{{podcast}}/{{title}} no
longer fail to write (#86), and harden the file-name sanitizer to preserve dots
(e.g. "Episode 1.5"), strip control characters, and collapse whitespace globally.

Closes #113
Closes #86

Author: chhoumann

src/TemplateEngine.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { DownloadPathTemplateEngine } from "./TemplateEngine";
+import type { Episode } from "./types/Episode";
+
+// The illegal-character sanitizer is private; exercise it through
+// DownloadPathTemplateEngine, which applies it to {{title}} and {{podcast}}.
+function sanitizeTitle(title: string): string {
+	const episode = {
+		title,
+		streamUrl: "https://example.com/a.mp3",
+		url: "https://example.com",
+		description: "",
+		content: "",
+		podcastName: "Pod",
+		episodeDate: undefined,
+		artworkUrl: "",
+	} as unknown as Episode;
+
+	return DownloadPathTemplateEngine("{{title}}", episode);
+}
+
+describe("replaceIllegalFileNameCharactersInString (via DownloadPathTemplateEngine)", () => {
+	it("preserves dots in titles (no more 'Episode 1.5' -> 'Episode 15')", () => {
+		expect(sanitizeTitle("Episode 1.5")).toBe("Episode 1.5");
+	});
+
+	it("still strips filesystem-illegal and wikilink-hostile characters", () => {
+		expect(sanitizeTitle('a/b\\c:d*e?f"g<h>i|j')).toBe("abcdefghij");
+		expect(sanitizeTitle("a#b%c&d{e}f")).toBe("abcdef");
+	});
+
+	it("replaces every control character with a space (global), not just the first", () => {
+		expect(sanitizeTitle("a\nb\nc")).toBe("a b c");
+		expect(sanitizeTitle("a\tb\rc")).toBe("a b c");
+	});
+
+	it("collapses every run of whitespace, not just the first", () => {
+		expect(sanitizeTitle("a  b  c")).toBe("a b c");
+	});
+
+	it("drops leading and trailing dots", () => {
+		expect(sanitizeTitle("...hidden")).toBe("hidden");
+		expect(sanitizeTitle("trailing...")).toBe("trailing");
+	});
+
+	it("does not strip hyphens or ordinary letters", () => {
+		expect(sanitizeTitle("Part 1 - The Beginning")).toBe(
+			"Part 1 - The Beginning",
+		);
+	});
+});

src/TemplateEngine.ts

@@ -243,8 +243,24 @@ export function TranscriptTemplateEngine(
 }
 
 function replaceIllegalFileNameCharactersInString(string: string) {
-	return string
-		.replace(/[\\,#%&{}/*<>$'":@\u2023|\\.?]/g, "") // Replace illegal file name characters with empty string
-		.replace(/\n/, " ") // replace newlines with spaces
-		.replace("  ", " "); // replace multiple spaces with single space to make sure we don't have double spaces in the file name
+	return (
+		string
+			// Strip characters that are illegal in file names on major platforms,
+			// plus a few the plugin removes for clean paths/wikilinks. Dots are
+			// intentionally preserved so titles like "Episode 1.5" are not mangled
+			// into "Episode 15".
+			.replace(/[\\,#%&{}/*<>$'":@\u2023|?]/g, "")
+			// Replace any control characters (newlines, tabs, carriage returns)
+			// with spaces so they can never end up in a file name.
+			// eslint-disable-next-line no-control-regex
+			.replace(/[\u0000-\u001f]/g, " ")
+			// Collapse every run of whitespace into a single space.
+			.replace(/\s+/g, " ")
+			.trim()
+			// Avoid leading/trailing dots, which create hidden files or "."/".."
+			// segments and are rejected on Windows/Android.
+			.replace(/^\.+/, "")
+			.replace(/\.+$/, "")
+			.trim()
+	);
 }

src/downloadEpisode.test.ts

@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { get } from "svelte/store";
+import { requestUrl, TFile } from "obsidian";
+import {
+	detectAudioFileExtension,
+	downloadEpisode,
+} from "./downloadEpisode";
+import { downloadedEpisodes } from "./store";
+import type { Episode } from "./types/Episode";
+
+vi.mock("obsidian", async (importOriginal) => {
+	const actual = await importOriginal<typeof import("obsidian")>();
+	return { ...actual, requestUrl: vi.fn() };
+});
+
+const requestUrlMock = vi.mocked(requestUrl);
+
+function bytes(...values: number[]): ArrayBuffer {
+	return new Uint8Array(values).buffer;
+}
+
+function setupVault() {
+	const present = new Set<string>();
+	const createdFolders: string[] = [];
+
+	const createBinary = vi.fn(async (path: string, _data: ArrayBuffer) => {
+		present.add(path);
+		return new TFile();
+	});
+	const createFolder = vi.fn(async (path: string) => {
+		present.add(path);
+		createdFolders.push(path);
+	});
+
+	(globalThis as { app?: unknown }).app = {
+		vault: {
+			getAbstractFileByPath: (path: string) =>
+				present.has(path) ? new TFile() : null,
+			createBinary,
+			createFolder,
+		},
+	};
+
+	return { present, createdFolders, createBinary, createFolder };
+}
+
+function makeEpisode(overrides: Partial<Episode> = {}): Episode {
+	return {
+		title: "My Title",
+		streamUrl: "https://example.com/ep.mp3",
+		url: "https://example.com/ep",
+		description: "",
+		content: "",
+		podcastName: "Pod",
+		episodeDate: undefined,
+		artworkUrl: "",
+		...overrides,
+	} as unknown as Episode;
+}
+
+beforeEach(() => {
+	requestUrlMock.mockReset();
+	downloadedEpisodes.set({});
+});
+
+afterEach(() => {
+	(globalThis as { app?: unknown }).app = undefined;
+});
+
+describe("detectAudioFileExtension", () => {
+	it("matches exact signatures (ID3 -> mp3, RIFF -> wav, m4a)", () => {
+		expect(detectAudioFileExtension(bytes(0x49, 0x44, 0x33, 0x04))).toBe("mp3");
+		expect(detectAudioFileExtension(bytes(0x52, 0x49, 0x46, 0x46))).toBe("wav");
+		expect(detectAudioFileExtension(bytes(0x4d, 0x34, 0x41, 0x20))).toBe("m4a");
+	});
+
+	it("applies the masked MPEG frame-sync signature", () => {
+		expect(detectAudioFileExtension(bytes(0xff, 0xfb, 0x90, 0x00))).toBe("mp3");
+	});
+
+	it("returns null for unknown content", () => {
+		expect(detectAudioFileExtension(bytes(0x00, 0x01, 0x02, 0x03))).toBeNull();
+	});
+
+	it("does not crash on a buffer shorter than the longest signature", () => {
+		expect(detectAudioFileExtension(bytes(0xff))).toBeNull();
+		expect(detectAudioFileExtension(new ArrayBuffer(0))).toBeNull();
+	});
+});
+
+describe("downloadEpisode (API path)", () => {
+	it("threads a single ArrayBuffer straight to createBinary (no Blob copy) and creates folders", async () => {
+		const { createBinary, createdFolders } = setupVault();
+		const buffer = bytes(0x49, 0x44, 0x33, 0x01, 0x02, 0x03);
+		requestUrlMock.mockResolvedValue({
+			status: 200,
+			headers: { "content-type": "audio/mpeg" },
+			arrayBuffer: buffer,
+		} as unknown as Awaited<ReturnType<typeof requestUrl>>);
+
+		const episode = makeEpisode();
+		const path = await downloadEpisode(episode, "podcast/{{podcast}}/{{title}}");
+
+		expect(path).toBe("podcast/Pod/My Title.mp3");
+		expect(createdFolders).toEqual(["podcast", "podcast/Pod"]);
+		expect(createBinary).toHaveBeenCalledTimes(1);
+
+		const [writtenPath, writtenData] = createBinary.mock.calls[0];
+		expect(writtenPath).toBe("podcast/Pod/My Title.mp3");
+		// The exact buffer returned by requestUrl must reach createBinary — proving
+		// no Blob round-trip / extra full-file copy is made (issue #113).
+		expect(writtenData).toBe(buffer);
+
+		const recorded = get(downloadedEpisodes)["Pod"]?.[0];
+		expect(recorded?.filePath).toBe("podcast/Pod/My Title.mp3");
+		expect(recorded?.size).toBe(buffer.byteLength);
+	});
+
+	it("returns the existing path without downloading when the file already exists", async () => {
+		const { present, createBinary } = setupVault();
+		present.add("My Title.mp3");
+
+		const path = await downloadEpisode(makeEpisode(), "{{title}}");
+
+		expect(path).toBe("My Title.mp3");
+		expect(requestUrlMock).not.toHaveBeenCalled();
+		expect(createBinary).not.toHaveBeenCalled();
+	});
+});