Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

feat(desktop): stream folder-zip assembly into a main-process temp file (R1-H2)

M7a16fe756820
diff --git a/desktop-app/src/__tests__/gfsZipStream.test.ts b/desktop-app/src/__tests__/gfsZipStream.test.ts
new file mode 100644
index 000000000..98027bd75
--- /dev/null
+++ b/desktop-app/src/__tests__/gfsZipStream.test.ts
@@ -0,0 +1,174 @@
+/**
+ * R1-H2 — the streamed, file-backed zip assembly. These tests run the REAL
+ * writer against real temp files and verify the SAVED ARCHIVE with an
+ * independent reader (walking the central directory the same way an extractor
+ * does), not by re-reading the writer's own inputs.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { ZipStreamDeps } from '../gfs/zipStream.js'
+import {
+ abortZipJob,
+ activeZipJobCount,
+ appendZipEntry,
+ finishZipJob,
+ startZipJob,
+} from '../gfs/zipStream.js'
+
+const savedFiles: string[] = []
+const tempRoots: string[] = []
+
+async function makeDeps(
+ savePath: string,
+ options: { cancelDialog?: boolean; failRename?: boolean } = {}
+): Promise<ZipStreamDeps & { tempDir: string }> {
+ const tempDir = await mkdtemp(join(tmpdir(), 'evenfire-zip-test-'))
+ tempRoots.push(tempDir)
+ return {
+ tempDir,
+ showSaveDialog: vi.fn(async () => ({
+ canceled: Boolean(options.cancelDialog),
+ filePath: options.cancelDialog ? undefined : savePath,
+ })),
+ renameFile: options.failRename
+ ? async () => {
+ throw new Error('EXDEV: cross-device link not permitted')
+ }
+ : undefined,
+ }
+}
+
+afterEach(async () => {
+ for (const dir of tempRoots.splice(0)) await rm(dir, { recursive: true, force: true })
+})
+
+interface ReadEntry {
+ name: string
+ bytes: Uint8Array
+ crc: number
+}
+
+/** Independent central-directory reader (an extractor's view of the file). */
+function readZipArchive(archive: Uint8Array): { entries: ReadEntry[]; entryCount: number } {
+ const view = new DataView(archive.buffer, archive.byteOffset, archive.byteLength)
+ const decoder = new TextDecoder()
+ const eocdOffset = archive.length - 22
+ expect(view.getUint32(eocdOffset, true)).toBe(0x06054b50)
+ const entryCount = view.getUint16(eocdOffset + 10, true)
+ const centralDirectoryOffset = view.getUint32(eocdOffset + 16, true)
+ const entries: ReadEntry[] = []
+ let cursor = centralDirectoryOffset
+ for (let index = 0; index < entryCount; index += 1) {
+ expect(view.getUint32(cursor, true)).toBe(0x02014b50)
+ const crc = view.getUint32(cursor + 16, true)
+ const size = view.getUint32(cursor + 20, true)
+ const nameLength = view.getUint16(cursor + 28, true)
+ const localHeaderOffset = view.getUint32(cursor + 42, true)
+ const name = decoder.decode(archive.subarray(cursor + 46, cursor + 46 + nameLength))
+
+ expect(view.getUint32(localHeaderOffset, true)).toBe(0x04034b50)
+ expect(view.getUint16(localHeaderOffset + 8, true)).toBe(0) // STORED
+ const localNameLength = view.getUint16(localHeaderOffset + 26, true)
+ const dataOffset = localHeaderOffset + 30 + localNameLength
+ const bytes = archive.subarray(dataOffset, dataOffset + size)
+ expect(bytes.length).toBe(size)
+ entries.push({ name, bytes, crc })
+ cursor += 46 + nameLength
+ }
+ return { entries, entryCount }
+}
+
+function contentBytes(text: string): ArrayBuffer {
+ return new TextEncoder().encode(text).buffer as ArrayBuffer
+}
+
+describe('gfs zipStream (R1-H2)', () => {
+ it('assembles a file-backed archive that an independent reader verifies', async () => {
+ const savePath = join(tmpdir(), `saved-${Date.now()}.zip`)
+ savedFiles.push(savePath)
+ const deps = await makeDeps(savePath)
+ const jobId = await startZipJob(deps)
+
+ expect(await appendZipEntry(jobId, 'Docs/a.txt', contentBytes('alpha'))).toBe('Docs/a.txt')
+ expect(await appendZipEntry(jobId, 'Docs/b.bin', contentBytes('\u00ff\u00fe'))).toBe(
+ 'Docs/b.bin'
+ )
+ const result = await finishZipJob(jobId, 'Docs.zip', deps)
+
+ expect(result.saved).toBe(true)
+ expect(result.entryCount).toBe(2)
+ expect(activeZipJobCount()).toBe(0)
+
+ const archive = new Uint8Array(await readFile(savePath))
+ const { entries, entryCount } = readZipArchive(archive)
+ expect(entryCount).toBe(2)
+ expect(entries.map(entry => entry.name)).toEqual(['Docs/a.txt', 'Docs/b.bin'])
+ const decoder = new TextDecoder()
+ expect(decoder.decode(entries[0]!.bytes)).toBe('alpha')
+ expect(entries[1]!.bytes).toEqual(new Uint8Array([0xc3, 0xbf, 0xc3, 0xbe]))
+ // The stored CRC fields match the payload CRC-32 an extractor recomputes.
+ const { crc32 } = await import('../gfs/zipStream.js')
+ for (const entry of entries) expect(entry.crc).toBe(crc32(entry.bytes))
+ })
+
+ it('suffixes case-insensitive collisions in the written file (R1-L1 through the real writer)', async () => {
+ const savePath = join(tmpdir(), `collide-${Date.now()}.zip`)
+ savedFiles.push(savePath)
+ const deps = await makeDeps(savePath)
+ const jobId = await startZipJob(deps)
+ await appendZipEntry(jobId, 'Report.txt', contentBytes('upper'))
+ await appendZipEntry(jobId, 'report.txt', contentBytes('lower'))
+
+ await finishZipJob(jobId, 'Collide.zip', deps)
+ const { entries } = readZipArchive(new Uint8Array(await readFile(savePath)))
+ expect(entries.map(entry => entry.name)).toEqual(['Report.txt', 'report (2).txt'])
+ const decoder = new TextDecoder()
+ expect(entries.map(entry => decoder.decode(entry.bytes))).toEqual(['upper', 'lower'])
+ })
+
+ it('rejects an entry whose FINAL name cannot fit the 16-bit fields, before writing (R1-M2)', async () => {
+ const deps = await makeDeps(join(tmpdir(), 'unused.zip'))
+ const jobId = await startZipJob(deps)
+ const nearLimit = `${'a'.repeat(65530)}.txt`
+ // The pre-collision name fits exactly; a colliding second copy must not
+ // push a suffixed name past the field — the writer refuses the header.
+ await appendZipEntry(jobId, nearLimit, contentBytes('one'))
+ await expect(appendZipEntry(jobId, nearLimit, contentBytes('two'))).rejects.toThrow(
+ /not representable in a ZIP header/i
+ )
+ await abortZipJob(jobId, deps)
+ })
+
+ it('deletes the temp file when the save dialog is canceled', async () => {
+ const deps = await makeDeps('', { cancelDialog: true })
+ const jobId = await startZipJob(deps)
+ await appendZipEntry(jobId, 'x.txt', contentBytes('x'))
+ const result = await finishZipJob(jobId, 'Canceled.zip', deps)
+ expect(result.saved).toBe(false)
+ expect(result.filePath).toBeNull()
+ expect(activeZipJobCount()).toBe(0)
+ })
+
+ it('falls back to copy+unlink when the final rename crosses filesystems', async () => {
+ const savePath = join(tmpdir(), `exdev-${Date.now()}.zip`)
+ savedFiles.push(savePath)
+ const deps = await makeDeps(savePath, { failRename: true })
+ const jobId = await startZipJob(deps)
+ await appendZipEntry(jobId, 'x.txt', contentBytes('content'))
+ const result = await finishZipJob(jobId, 'Exdev.zip', deps)
+ expect(result.saved).toBe(true)
+ const { entries } = readZipArchive(new Uint8Array(await readFile(savePath)))
+ expect(entries).toHaveLength(1)
+ })
+
+ it('abort cleans the job and its temp file', async () => {
+ const deps = await makeDeps(join(tmpdir(), 'unused.zip'))
+ const jobId = await startZipJob(deps)
+ await appendZipEntry(jobId, 'x.txt', contentBytes('x'))
+ await abortZipJob(jobId, deps)
+ expect(activeZipJobCount()).toBe(0)
+ await expect(finishZipJob(jobId, 'Gone.zip', deps)).rejects.toThrow(/Unknown zip job/)
+ })
+})
diff --git a/desktop-app/src/gfs/zipEntryName.ts b/desktop-app/src/gfs/zipEntryName.ts
new file mode 100644
index 000000000..c5f8f1a6a
--- /dev/null
+++ b/desktop-app/src/gfs/zipEntryName.ts
@@ -0,0 +1,65 @@
+/**
+ * Shared, pure ZIP entry-name finalization (folder-zip export). Used by BOTH
+ * the renderer walk (which finalizes names before sending them, so overlong
+ * results are visible skips) and the main-process streaming writer (which
+ * re-validates defensively before writing headers). Pure TS, no Electron/DOM:
+ * safe to import from either bundle.
+ */
+
+/** A ZIP name field is a 16-bit byte count: names must stay strictly under it. */
+export const MAX_ZIP_ENTRY_NAME_BYTES = 65535
+
+export interface FinalizedEntryName {
+ /** The name to commit (unchanged, or carrying a ` (n)` collision suffix). */
+ name: string
+ /** The case-folded key that owns the name in the caller's set. */
+ folded: string
+}
+
+export const foldEntryName = (name: string): string => name.toLowerCase()
+
+/**
+ * Case-insensitive de-duplication for entry names (spec: name-collision
+ * policy): portable case-insensitive extractors (macOS, Windows) would
+ * silently overwrite `Report.txt` with `report.txt`, so a colliding name gets
+ * the ` (2)`, ` (3)`, ... suffix on its final segment. The caller registers
+ * `finalized.folded` in its used set.
+ */
+export function finalizeEntryName(
+ candidate: string,
+ usedFoldedNames: ReadonlySet<string>
+): FinalizedEntryName {
+ const fold = foldEntryName(candidate)
+ if (!usedFoldedNames.has(fold)) return { name: candidate, folded: fold }
+ const slash = candidate.lastIndexOf('/')
+ const directory = slash >= 0 ? candidate.slice(0, slash + 1) : ''
+ const base = slash >= 0 ? candidate.slice(slash + 1) : candidate
+ const dot = base.lastIndexOf('.')
+ const stem = dot > 0 ? base.slice(0, dot) : base
+ const extension = dot > 0 ? base.slice(dot) : ''
+ let counter = 2
+ let name = `${directory}${stem} (${counter})${extension}`
+ let folded = foldEntryName(name)
+ while (usedFoldedNames.has(folded)) {
+ counter += 1
+ name = `${directory}${stem} (${counter})${extension}`
+ folded = foldEntryName(name)
+ }
+ return { name, folded }
+}
+
+/**
+ * True when the FINALIZED name's UTF-8 encoding fits the 16-bit ZIP name
+ * fields. Runs on the post-suffix name (R1-M2): a near-limit name whose
+ * collision suffix pushes it past the bound must be rejected here, not
+ * truncated by the writer.
+ */
+export function entryNameFitsZipFields(name: string): boolean {
+ let bytes = 0
+ for (const character of name) {
+ if (character.charCodeAt(0) < 0x80) bytes += 1
+ else if (character.charCodeAt(0) < 0x800) bytes += 2
+ else bytes += character.codePointAt(0)! > 0xffff ? 4 : 3
+ }
+ return bytes > 0 && bytes < MAX_ZIP_ENTRY_NAME_BYTES
+}
diff --git a/desktop-app/src/gfs/zipStream.ts b/desktop-app/src/gfs/zipStream.ts
new file mode 100644
index 000000000..7c8ae27a9
--- /dev/null
+++ b/desktop-app/src/gfs/zipStream.ts
@@ -0,0 +1,256 @@
+/**
+ * File-backed ZIP assembly for the folder-zip export (R1-H2, spec: round-2
+ * extensions). The renderer streams one downloaded file at a time to
+ * `gfs:zipStream:append`; entries (local header + payload) are appended to a
+ * temp file, only central-directory metadata stays in memory, and `finish`
+ * appends the directory + EOCD in place, then moves the temp file to the
+ * user-chosen save location. Renderer peak memory is independent of folder
+ * size; main keeps ~76 + name bytes per entry plus one chunk.
+ *
+ * Format reference: APPNOTE.TXT — local file header (4.3.7), central directory
+ * (4.3.12), EOCD (4.3.19). Entries are STORED (see the renderer-era decision:
+ * already-encoded payloads, exact byte-budget reasoning); names are UTF-8 with
+ * general-purpose flag bit 11 set; DOS timestamps are zero (deterministic).
+ */
+import { dialog } from 'electron'
+import { randomUUID } from 'node:crypto'
+import { copyFile, open, rename, unlink } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { entryNameFitsZipFields, finalizeEntryName, foldEntryName } from './zipEntryName.js'
+
+const LOCAL_FILE_HEADER_SIGNATURE = 0x04034b50
+const CENTRAL_DIRECTORY_SIGNATURE = 0x02014b50
+const END_OF_CENTRAL_DIRECTORY_SIGNATURE = 0x06054b50
+const VERSION_NEEDED = 20
+const UTF8_FLAG = 0x0800
+const STORED_METHOD = 0
+
+const CRC32_POLYNOMIAL = 0xedb88320
+
+let crc32Table: Uint32Array | null = null
+
+function crc32TableFor(): Uint32Array {
+ if (crc32Table) return crc32Table
+ const table = new Uint32Array(256)
+ for (let index = 0; index < 256; index += 1) {
+ let value = index
+ for (let bit = 0; bit < 8; bit += 1) {
+ value = value & 1 ? (value >>> 1) ^ CRC32_POLYNOMIAL : value >>> 1
+ }
+ table[index] = value >>> 0
+ }
+ crc32Table = table
+ return table
+}
+
+export function crc32(bytes: Uint8Array): number {
+ const table = crc32TableFor()
+ let crc = 0xffffffff
+ for (let index = 0; index < bytes.length; index += 1) {
+ crc = (crc >>> 8) ^ table[(crc ^ bytes[index]!) & 0xff]!
+ }
+ return (crc ^ 0xffffffff) >>> 0
+}
+
+interface DirectoryEntry {
+ nameBytes: Uint8Array
+ crc: number
+ size: number
+ localHeaderOffset: number
+}
+
+interface ZipStreamJob {
+ tempPath: string
+ handle: Awaited<ReturnType<typeof open>>
+ /** Serializes temp-file writes across append calls. */
+ writeChain: Promise<void>
+ entries: DirectoryEntry[]
+ usedFoldedNames: Set<string>
+ byteCount: number
+}
+
+export interface ZipStreamDeps {
+ openFile?: typeof open
+ unlinkFile?: typeof unlink
+ renameFile?: typeof rename
+ showSaveDialog?: typeof dialog.showSaveDialog
+ tempDir?: string
+}
+
+const jobs = new Map<string, ZipStreamJob>()
+
+export class ZipStreamNameError extends Error {
+ constructor(name: string) {
+ super(
+ `Entry name is not representable in a ZIP header (encoded length must stay under 65535 bytes): ${name.slice(0, 64)}…`
+ )
+ this.name = 'ZipStreamNameError'
+ }
+}
+
+export async function startZipJob(deps: ZipStreamDeps = {}): Promise<string> {
+ const jobId = randomUUID()
+ const tempPath = join(deps.tempDir ?? tmpdir(), `evenfire-zip-${jobId}.part`)
+ const handle = await (deps.openFile ?? open)(tempPath, 'w', 0o600)
+ jobs.set(jobId, {
+ tempPath,
+ handle,
+ writeChain: Promise.resolve(),
+ entries: [],
+ usedFoldedNames: new Set(),
+ byteCount: 0,
+ })
+ return jobId
+}
+
+function localHeader(nameBytes: Uint8Array, crc: number, size: number): Uint8Array {
+ const header = new Uint8Array(30 + nameBytes.length)
+ const view = new DataView(header.buffer)
+ view.setUint32(0, LOCAL_FILE_HEADER_SIGNATURE, true)
+ view.setUint16(4, VERSION_NEEDED, true)
+ view.setUint16(6, UTF8_FLAG, true)
+ view.setUint16(8, STORED_METHOD, true)
+ view.setUint16(10, 0, true) // mod time
+ view.setUint16(12, 0, true) // mod date
+ view.setUint32(14, crc, true)
+ view.setUint32(18, size, true) // compressed size (stored)
+ view.setUint32(22, size, true) // uncompressed size
+ view.setUint16(26, nameBytes.length, true)
+ view.setUint16(28, 0, true) // extra length
+ header.set(nameBytes, 30)
+ return header
+}
+
+/**
+ * Appends one STORED entry. The name is finalized case-insensitively against
+ * the job's used set and validated against the 16-bit name fields BEFORE any
+ * header is written (R1-M2): an unrepresentable name is an error, never a
+ * truncated corrupt header.
+ */
+export async function appendZipEntry(
+ jobId: string,
+ rawName: string,
+ bytes: ArrayBuffer
+): Promise<string> {
+ const job = jobs.get(jobId)
+ if (!job) throw new Error(`Unknown zip job ${jobId}`)
+ const { name } = finalizeEntryName(rawName, job.usedFoldedNames)
+ if (!entryNameFitsZipFields(name)) throw new ZipStreamNameError(name)
+ job.usedFoldedNames.add(foldEntryName(name))
+ const nameBytes = new TextEncoder().encode(name)
+ const data = new Uint8Array(bytes)
+ const crc = crc32(data)
+ const header = localHeader(nameBytes, crc, data.length)
+ const localHeaderOffset = job.byteCount
+ job.byteCount += header.length + data.length
+ job.entries.push({ nameBytes, crc, size: data.length, localHeaderOffset })
+ job.writeChain = job.writeChain.then(async () => {
+ await job.handle.write(header)
+ await job.handle.write(data, 0, data.length)
+ })
+ await job.writeChain
+ return name
+}
+
+export interface FinishZipJobResult {
+ saved: boolean
+ filePath: string | null
+ entryCount: number
+}
+
+/** Finalizes the archive and saves it through a native dialog. */
+export async function finishZipJob(
+ jobId: string,
+ suggestedName: string,
+ deps: ZipStreamDeps = {}
+): Promise<FinishZipJobResult> {
+ const job = jobs.get(jobId)
+ if (!job) throw new Error(`Unknown zip job ${jobId}`)
+ const centralDirectoryOffset = job.byteCount
+ const parts: Uint8Array[] = []
+ for (const entry of job.entries) {
+ const record = new Uint8Array(46 + entry.nameBytes.length)
+ const view = new DataView(record.buffer)
+ view.setUint32(0, CENTRAL_DIRECTORY_SIGNATURE, true)
+ view.setUint16(4, VERSION_NEEDED, true) // made by
+ view.setUint16(6, VERSION_NEEDED, true) // needed
+ view.setUint16(8, UTF8_FLAG, true)
+ view.setUint16(10, STORED_METHOD, true)
+ view.setUint16(12, 0, true) // mod time
+ view.setUint16(14, 0, true) // mod date
+ view.setUint32(16, entry.crc, true)
+ view.setUint32(20, entry.size, true)
+ view.setUint32(24, entry.size, true)
+ view.setUint16(28, entry.nameBytes.length, true)
+ view.setUint16(30, 0, true) // extra length
+ view.setUint16(32, 0, true) // comment length
+ view.setUint16(34, 0, true) // disk start
+ view.setUint16(36, 0, true) // internal attributes
+ view.setUint32(38, 0, true) // external attributes
+ view.setUint32(42, entry.localHeaderOffset, true)
+ record.set(entry.nameBytes, 46)
+ parts.push(record)
+ }
+ const centralDirectorySize = parts.reduce((sum, part) => sum + part.length, 0)
+ const eocd = new Uint8Array(22)
+ const view = new DataView(eocd.buffer)
+ view.setUint32(0, END_OF_CENTRAL_DIRECTORY_SIGNATURE, true)
+ view.setUint16(4, 0, true)
+ view.setUint16(6, 0, true)
+ view.setUint16(8, job.entries.length, true)
+ view.setUint16(10, job.entries.length, true)
+ view.setUint32(12, centralDirectorySize, true)
+ view.setUint32(16, centralDirectoryOffset, true)
+ view.setUint16(20, 0, true)
+ parts.push(eocd)
+
+ const entryCount = job.entries.length
+ const tempPath = job.tempPath
+ try {
+ job.writeChain = job.writeChain.then(async () => {
+ for (const part of parts) await job.handle.write(part)
+ await job.handle.close()
+ })
+ await job.writeChain
+ } finally {
+ jobs.delete(jobId)
+ }
+
+ const saveDialog = deps.showSaveDialog ?? dialog.showSaveDialog
+ const result = await saveDialog({
+ defaultPath: suggestedName,
+ title: 'Save folder zip',
+ })
+ if (result.canceled || !result.filePath) {
+ await (deps.unlinkFile ?? unlink)(tempPath).catch(() => undefined)
+ return { saved: false, filePath: null, entryCount }
+ }
+ // rename fails across filesystems (EXDEV: /tmp tmpfs vs home) — fall back
+ // to copy+unlink so the save works wherever the OS keeps its temp dir.
+ try {
+ await (deps.renameFile ?? rename)(tempPath, result.filePath)
+ } catch {
+ await copyFile(tempPath, result.filePath)
+ await (deps.unlinkFile ?? unlink)(tempPath).catch(() => undefined)
+ }
+ return { saved: true, filePath: result.filePath, entryCount }
+}
+
+/** Aborts a job: closes the temp file and deletes it. */
+export async function abortZipJob(jobId: string, deps: ZipStreamDeps = {}): Promise<void> {
+ const job = jobs.get(jobId)
+ if (!job) return
+ jobs.delete(jobId)
+ job.writeChain = job.writeChain
+ .then(async () => {
+ await job.handle.close()
+ })
+ .catch(() => undefined)
+ await job.writeChain
+ await (deps.unlinkFile ?? unlink)(job.tempPath).catch(() => undefined)
+}
+
+export function activeZipJobCount(): number {
+ return jobs.size
+}
diff --git a/desktop-app/src/ipc.ts b/desktop-app/src/ipc.ts
index b4a7f8b3d..5fc3f970e 100644
--- a/desktop-app/src/ipc.ts
+++ b/desktop-app/src/ipc.ts
@@ -19,6 +19,7 @@ import {
} from './chatStoreBinding.js'
import { GFS_DOWNLOAD_MAX_BYTES_CEILING } from './gfs/downloadLimits.js'
import { GFS_PREVIEW_MAX_BYTES } from './gfs/previewLimits.js'
+import { abortZipJob, appendZipEntry, finishZipJob, startZipJob } from './gfs/zipStream.js'
import { assertSafeRouteSegment } from './pathSafety.js'
import {
PLUGIN_SDK_CAPABILITIES_CHANNEL,
@@ -577,6 +578,42 @@ export function registerIpcHandlers(service: AppService): void {
return service.gfsAffordances(sanitizeString(payload?.resourceId), drive)
}
)
+ // Streamed, file-backed folder-zip assembly (R1-H2): entries append to a
+ // main-process temp file, finish saves through a native dialog. All four
+ // channels trust-check; append validates the entry name before any header is
+ // written (R1-M2 defense in depth).
+ ipcMain.handle('gfs:zipStream:start', async event => {
+ assertTrustedSender(event)
+ return { jobId: await startZipJob() }
+ })
+ ipcMain.handle(
+ 'gfs:zipStream:append',
+ async (event, payload: { jobId: string; name: string; bytes: ArrayBuffer }) => {
+ assertTrustedSender(event)
+ const name = sanitizeString(payload?.name)
+ if (!name) throw new Error('zipStream append requires an entry name')
+ if (!(payload?.bytes instanceof ArrayBuffer)) {
+ throw new Error('zipStream append requires entry bytes')
+ }
+ if (payload.bytes.byteLength > GFS_DOWNLOAD_MAX_BYTES_CEILING) {
+ throw new Error('zip entry exceeds the allowed maximum')
+ }
+ const writtenName = await appendZipEntry(sanitizeString(payload.jobId), name, payload.bytes)
+ return { name: writtenName }
+ }
+ )
+ ipcMain.handle(
+ 'gfs:zipStream:finish',
+ async (event, payload: { jobId: string; suggestedName: string }) => {
+ assertTrustedSender(event)
+ return finishZipJob(sanitizeString(payload.jobId), sanitizeString(payload.suggestedName))
+ }
+ )
+ ipcMain.handle('gfs:zipStream:abort', async (event, payload: { jobId: string }) => {
+ assertTrustedSender(event)
+ await abortZipJob(sanitizeString(payload.jobId))
+ return { aborted: true }
+ })
ipcMain.handle(
'gfs:createFolder',
async (event, payload: { parentResourceId: string; name: string; drive?: string }) => {
diff --git a/desktop-app/src/preload.ts b/desktop-app/src/preload.ts
index 784501baf..41c6bcfde 100644
--- a/desktop-app/src/preload.ts
+++ b/desktop-app/src/preload.ts
@@ -177,6 +177,14 @@ const clerum = Object.freeze({
) => cancellableGfsInvoke('gfs:listChildren', { resourceId, drive, cursor }, options?.signal),
affordances: (resourceId: string, drive?: string) =>
ipcRenderer.invoke('gfs:affordances', { resourceId, drive }),
+ zipStream: {
+ start: () => ipcRenderer.invoke('gfs:zipStream:start'),
+ append: (jobId: string, name: string, bytes: ArrayBuffer) =>
+ ipcRenderer.invoke('gfs:zipStream:append', { jobId, name, bytes }),
+ finish: (jobId: string, suggestedName: string) =>
+ ipcRenderer.invoke('gfs:zipStream:finish', { jobId, suggestedName }),
+ abort: (jobId: string) => ipcRenderer.invoke('gfs:zipStream:abort', { jobId }),
+ },
createFolder: (parentResourceId: string, name: string, drive?: string) =>
ipcRenderer.invoke('gfs:createFolder', { parentResourceId, name, drive }),
createFile: (parentResourceId: string, name: string, encodedData: string, drive?: string) =>
diff --git a/desktop-app/src/renderer.d.ts b/desktop-app/src/renderer.d.ts
index 5d71ccae3..fdbb7c69f 100644
--- a/desktop-app/src/renderer.d.ts
+++ b/desktop-app/src/renderer.d.ts
@@ -225,6 +225,15 @@ declare global {
grantableBits: string[]
canCreateShare: boolean
}>
+ zipStream: {
+ start: () => Promise<{ jobId: string }>
+ append: (jobId: string, name: string, bytes: ArrayBuffer) => Promise<{ name: string }>
+ finish: (
+ jobId: string,
+ suggestedName: string
+ ) => Promise<{ saved: boolean; filePath: string | null; entryCount: number }>
+ abort: (jobId: string) => Promise<{ aborted: boolean }>
+ }
createFolder: (
parentResourceId: string,
name: string,
diff --git a/desktop-app/ui/src/hooks/domain/__tests__/composerMergeZipProperties.test.tsx b/desktop-app/ui/src/hooks/domain/__tests__/composerMergeZipProperties.test.tsx
index 26a7bfc27..6ca31d094 100644
--- a/desktop-app/ui/src/hooks/domain/__tests__/composerMergeZipProperties.test.tsx
+++ b/desktop-app/ui/src/hooks/domain/__tests__/composerMergeZipProperties.test.tsx
@@ -10,8 +10,8 @@ import fc from 'fast-check'
import { FILE_REFERENCE_MAX_COUNT } from '@clerum/gfs-interaction-policy'
import { COMPOSER_MAX_IMAGE_ATTACHMENTS } from '@constants/attachments'
import { GFS_ZIP_MAX_SEGMENT_NAME_BYTES, sanitizeZipSegment } from '@lib/gfsFolderZip'
-import { createZipWriter } from '@lib/zipWriter'
import type { ComposerImageAttachment, ComposerReferenceAttachment } from '@/uiTypes'
+import { entryNameFitsZipFields, finalizeEntryName } from '../../../../../src/gfs/zipEntryName'
import {
mergeComposerImageAttachments,
mergeComposerReferenceAttachments,
@@ -125,37 +125,25 @@ describe('zip path normalization invariants (R1-M6)', () => {
)
})
- it('built archives never contain case-folded duplicate entry names', () => {
+ it('finalized entry names never collide case-folded and always fit the 16-bit fields', () => {
fc.assert(
fc.property(
fc.array(fc.string({ minLength: 1, maxLength: 24 }), { maxLength: 30 }),
names => {
- const writer = createZipWriter()
- for (const [index, name] of names.entries()) writer.addFile(name, new Uint8Array([index]))
- const written = archiveEntryNames(writer.build())
+ const usedFolded = new Set<string>()
+ const written: string[] = []
+ for (const name of names) {
+ const finalized = finalizeEntryName(name, usedFolded)
+ usedFolded.add(finalized.folded)
+ written.push(finalized.name)
+ }
const folded = new Set(written.map(name => name.toLowerCase()))
expect(folded.size).toBe(written.length)
expect(written).toHaveLength(names.length)
+ for (const name of written) expect(entryNameFitsZipFields(name)).toBe(true)
}
),
{ numRuns: 60 }
)
})
})
-
-/** Minimal central-directory reader (name column only). */
-function archiveEntryNames(archive: Uint8Array): string[] {
- const view = new DataView(archive.buffer, archive.byteOffset, archive.byteLength)
- const decoder = new TextDecoder()
- const eocdOffset = archive.length - 22
- const entryCount = view.getUint16(eocdOffset + 10, true)
- const centralDirectoryOffset = view.getUint32(eocdOffset + 16, true)
- const names: string[] = []
- let cursor = centralDirectoryOffset
- for (let index = 0; index < entryCount; index += 1) {
- const nameLength = view.getUint16(cursor + 28, true)
- names.push(decoder.decode(archive.subarray(cursor + 46, cursor + 46 + nameLength)))
- cursor += 46 + nameLength
- }
- return names
-}
diff --git a/desktop-app/ui/src/lib/__tests__/gfsFolderZip.test.ts b/desktop-app/ui/src/lib/__tests__/gfsFolderZip.test.ts
index 3137cd698..6976f645c 100644
--- a/desktop-app/ui/src/lib/__tests__/gfsFolderZip.test.ts
+++ b/desktop-app/ui/src/lib/__tests__/gfsFolderZip.test.ts
@@ -52,13 +52,58 @@ function folder(
}
}
+export interface RecordedZipStream {
+ appended: Array<{ name: string; bytes: ArrayBuffer }>
+ finishedWith: Array<{ suggestedName: string }>
+ abortedJobs: string[]
+ deps: import('../gfsFolderZip').GfsZipStreamDeps
+}
+
+/** File-backed stream fake: records appends, finishes "saved" to a path. */
+function recordedZipStream(options: { saved?: boolean } = {}): RecordedZipStream {
+ const appended: Array<{ name: string; bytes: ArrayBuffer }> = []
+ const finishedWith: Array<{ suggestedName: string }> = []
+ const abortedJobs: string[] = []
+ let jobCounter = 0
+ return {
+ appended,
+ finishedWith,
+ abortedJobs,
+ deps: {
+ start: vi.fn(async () => ({ jobId: `job-${++jobCounter}` })),
+ append: vi.fn(async (jobId: string, name: string, bytes: ArrayBuffer) => {
+ void jobId
+ appended.push({ name, bytes })
+ }),
+ finish: vi.fn(async (jobId: string, suggestedName: string) => {
+ void jobId
+ finishedWith.push({ suggestedName })
+ return {
+ saved: options.saved ?? true,
+ filePath: options.saved === false ? null : `/saved/${suggestedName}`,
+ entryCount: appended.length,
+ }
+ }),
+ abort: vi.fn(async (jobId: string) => {
+ abortedJobs.push(jobId)
+ }),
+ },
+ }
+}
+
+function streamEntryNames(stream: RecordedZipStream): string[] {
+ return stream.appended.map(entry => entry.name)
+}
+
function depsFor(
pages: Record<string, Array<{ items: GfsZipChildItem[]; nextCursor: string | null }>>,
downloads: Record<
string,
(uri: string, options?: { maxBytes?: number }) => Promise<{ bytes: ArrayBuffer }>
- > = {}
-): GfsFolderZipDeps {
+ > = {},
+ streamOptions: { saved?: boolean } = {}
+): GfsFolderZipDeps & { zipStreamRecord: RecordedZipStream } {
+ const stream = recordedZipStream(streamOptions)
return {
listChildren: vi.fn(async (resourceId: string, _drive: string, cursor?: string) => {
const pageList = pages[resourceId]
@@ -73,10 +118,12 @@ function depsFor(
if (produce) return produce(uri, options)
return { bytes: bytesOf(uri) }
}),
+ zipStream: stream.deps,
// Spacing itself has a dedicated manual-clock test below the walk; here it
// is a no-op so the orchestration tests run instantly.
throttle: { acquire: async () => undefined },
sleep: async () => undefined,
+ zipStreamRecord: stream,
}
}
@@ -143,8 +190,11 @@ describe('createGfsFolderZip', () => {
})
expect(deps.listChildren).toHaveBeenCalledWith('sub', 'main', undefined, { signal: undefined })
- const names = zipEntryNames(result.bytes)
- expect(names.sort()).toEqual(['Docs/a.txt', 'Docs/b.png', 'Docs/sub/c.md'].sort())
+ expect(result.saved).toBe(true)
+ expect(result.savedPath).toBe('/saved/Docs.zip')
+ expect(streamEntryNames(deps.zipStreamRecord).sort()).toEqual(
+ ['Docs/a.txt', 'Docs/b.png', 'Docs/sub/c.md'].sort()
+ )
expect(progress.map(value => value.phase)).toContain('downloading')
expect(progress.at(-1)?.phase).toBe('assembling')
// The "downloading N of M" copy is 1-based: file 1 reports filesAdded 1.
@@ -192,7 +242,7 @@ describe('createGfsFolderZip', () => {
{ path: 'Mixed/hidden.txt', reason: 'No access' },
{ path: 'Mixed/denied.txt', reason: 'Permission denied' },
])
- expect(zipEntryNames(result.bytes)).toEqual(['Mixed/ok.txt'])
+ expect(streamEntryNames(deps.zipStreamRecord)).toEqual(['Mixed/ok.txt'])
})
it('skips a subfolder whose listing itself is denied and continues the walk', async () => {
@@ -208,6 +258,7 @@ describe('createGfsFolderZip', () => {
download: async () => ({ bytes: bytesOf('x') }),
throttle: { acquire: async () => undefined },
sleep: async () => undefined,
+ zipStream: recordedZipStream().deps,
}
const result = await createGfsFolderZip(
@@ -332,6 +383,52 @@ describe('createGfsFolderZip', () => {
}
})
+ it('aborts the stream job on any failure path so no temp file survives (R1-H2)', async () => {
+ const stream = recordedZipStream()
+ const deps: GfsFolderZipDeps = {
+ listChildren: vi.fn(async () => ({
+ items: [folder({ resourceId: 'doomed', name: 'doomed.txt' })],
+ nextCursor: null,
+ })),
+ download: async () => {
+ throw new Error('gfs download failed: 500 httpStatus=500')
+ },
+ zipStream: stream.deps,
+ throttle: { acquire: async () => undefined },
+ sleep: async () => undefined,
+ }
+ await expect(
+ createGfsFolderZip({ resourceId: 'root', drive: 'main', name: 'Broken' }, { deps })
+ ).rejects.toThrow(/500/)
+ // The job was started, nothing was appended, and the temp file was told
+ // to clean up through the abort channel.
+ expect(stream.deps.start).toHaveBeenCalledTimes(1)
+ expect(stream.appended).toHaveLength(0)
+ expect(stream.abortedJobs).toHaveLength(1)
+
+ // Stop mid-walk takes the same cleanup path.
+ const stopStream = recordedZipStream()
+ const controller = new AbortController()
+ const stopDeps: GfsFolderZipDeps = {
+ listChildren: vi.fn(async () => ({
+ items: [folder({ resourceId: 'first', name: 'first.txt' })],
+ nextCursor: null,
+ })),
+ download: () => new Promise<{ bytes: ArrayBuffer }>(() => undefined),
+ zipStream: stopStream.deps,
+ throttle: { acquire: async () => undefined },
+ sleep: async () => undefined,
+ }
+ const walk = createGfsFolderZip(
+ { resourceId: 'root', drive: 'main', name: 'Stopped' },
+ { deps: stopDeps, signal: controller.signal }
+ )
+ const rejection = expect(walk).rejects.toMatchObject({ name: 'AbortError' })
+ controller.abort()
+ await rejection
+ expect(stopStream.abortedJobs).toHaveLength(1)
+ })
+
it('skips entries whose complete path would overflow the 16-bit ZIP name field (R1-M2)', async () => {
// A 110-deep chain of 700-byte segment names crosses 65535 assembled
// bytes around depth ~93: the overlong child is skipped (visible notice,
@@ -485,7 +582,7 @@ describe('createGfsFolderZip', () => {
{ path: 'Exact/after-a.bin', reason: 'Zip byte limit reached' },
{ path: 'Exact/after-b.bin', reason: 'Zip byte limit reached' },
])
- expect(zipEntryNames(result.bytes)).toEqual(['Exact/fill.bin'])
+ expect(streamEntryNames(deps.zipStreamRecord)).toEqual(['Exact/fill.bin'])
})
it('carries a near-limit folder through download, zip and save-sized output (R1-H2)', async () => {
@@ -522,8 +619,8 @@ describe('createGfsFolderZip', () => {
)
expect(result.fileCount).toBe(2)
expect(seenMaxBytes).toEqual([1024, 512])
- // The archive itself exists and parses back.
- expect(zipEntryNames(result.bytes).length).toBe(2)
+ expect(result.saved).toBe(true)
+ expect(streamEntryNames(deps.zipStreamRecord)).toHaveLength(2)
})
it('backs off once on a 429 using the server-provided retry hint', async () => {
@@ -538,6 +635,7 @@ describe('createGfsFolderZip', () => {
download: async () => ({ bytes: new ArrayBuffer(0) }),
throttle: { acquire: async () => undefined },
sleep: async () => undefined,
+ zipStream: recordedZipStream().deps,
}
// The retry succeeds but finds nothing archivable → empty short-circuit.
@@ -553,6 +651,7 @@ describe('createGfsFolderZip', () => {
const deps: GfsFolderZipDeps = {
listChildren,
download: async () => ({ bytes: new ArrayBuffer(0) }),
+ zipStream: recordedZipStream().deps,
// The first slot never frees: the walk parks here until the stop lands.
throttle: { acquire: () => new Promise<void>(() => undefined) },
sleep: async () => undefined,
@@ -578,6 +677,7 @@ describe('createGfsFolderZip', () => {
download: () => new Promise<{ bytes: ArrayBuffer }>(() => undefined),
throttle: { acquire: async () => undefined },
sleep: async () => undefined,
+ zipStream: recordedZipStream().deps,
}
const walk = createGfsFolderZip(
@@ -604,6 +704,7 @@ describe('createGfsFolderZip', () => {
download: async () => ({ bytes: new ArrayBuffer(0) }),
throttle: { acquire: async () => undefined },
sleep: async () => undefined,
+ zipStream: recordedZipStream().deps,
}
const walk = createGfsFolderZip(
@@ -630,6 +731,7 @@ describe('createGfsFolderZip', () => {
},
throttle: { acquire: async () => undefined },
sleep: async () => undefined,
+ zipStream: recordedZipStream().deps,
}
await expect(
@@ -662,7 +764,7 @@ describe('createGfsFolderZip', () => {
{ resourceId: 'root', drive: 'main', name: 'Weird/Name:' },
{ deps }
)
- expect(zipEntryNames(result.bytes).sort()).toEqual(
+ expect(streamEntryNames(deps.zipStreamRecord).sort()).toEqual(
[
'Weird_Name_/.._escape.txt',
'Weird_Name_/a_b.txt',
@@ -695,12 +797,11 @@ describe('createGfsFolderZip', () => {
)
expect(result.fileCount).toBe(1)
- const names = zipEntryNames(result.bytes)
+ const names = streamEntryNames(deps.zipStreamRecord)
expect(names).toHaveLength(1)
const written = names[0]!
- // The archive parses back (zipEntryNames reads the real central
- // directory); the written name is well inside the uint16 field and the
- // SEGMENT was cut under the documented ceiling.
+ // The name handed to the streaming writer is well inside the uint16 field
+ // and the SEGMENT was cut under the documented ceiling.
expect(written.startsWith('Long/')).toBe(true)
expect(new TextEncoder().encode(written).length).toBeLessThan(65536)
expect(new TextEncoder().encode(written.slice('Long/'.length)).length).toBeLessThanOrEqual(1024)
@@ -718,7 +819,7 @@ describe('createGfsFolderZip', () => {
{ resourceId: 'root', drive: 'main', name: 'Emoji' },
{ deps: emojiDeps }
)
- const emojiName = zipEntryNames(emojiResult.bytes)[0]!
+ const emojiName = streamEntryNames(emojiDeps.zipStreamRecord)[0]!
expect(emojiName.endsWith('\uFFFD')).toBe(false)
expect(new TextEncoder().encode(emojiName.slice('Emoji/'.length)).length).toBeLessThanOrEqual(
1024
@@ -782,6 +883,7 @@ describe('createGfsFolderZip', () => {
return { items: [], nextCursor: null }
}),
download: async () => ({ bytes: new ArrayBuffer(0) }),
+ zipStream: recordedZipStream().deps,
throttle: { acquire },
sleep: async () => undefined,
}
@@ -822,20 +924,3 @@ describe('createGfsFolderZip', () => {
])
})
})
-
-/** Minimal central-directory name reader for assertions. */
-function zipEntryNames(archive: Uint8Array): string[] {
- const view = new DataView(archive.buffer, archive.byteOffset, archive.byteLength)
- const decoder = new TextDecoder()
- const eocdOffset = archive.length - 22
- const entryCount = view.getUint16(eocdOffset + 10, true)
- const centralDirectoryOffset = view.getUint32(eocdOffset + 16, true)
- const names: string[] = []
- let cursor = centralDirectoryOffset
- for (let index = 0; index < entryCount; index += 1) {
- const nameLength = view.getUint16(cursor + 28, true)
- names.push(decoder.decode(archive.subarray(cursor + 46, cursor + 46 + nameLength)))
- cursor += 46 + nameLength
- }
- return names
-}
diff --git a/desktop-app/ui/src/lib/__tests__/zipWriter.test.ts b/desktop-app/ui/src/lib/__tests__/zipWriter.test.ts
deleted file mode 100644
index 6d391f9f9..000000000
--- a/desktop-app/ui/src/lib/__tests__/zipWriter.test.ts
+++ /dev/null
@@ -1,172 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { crc32, createZipWriter } from '../zipWriter'
-
-/** Reads a STORED zip back through its end-of-central-directory record. */
-function readStoredZip(archive: Uint8Array): Array<{ name: string; bytes: Uint8Array }> {
- const view = new DataView(archive.buffer, archive.byteOffset, archive.byteLength)
- const decoder = new TextDecoder()
-
- // EOCD is the last structure; comment length is 0, so it is the final 22 bytes.
- const eocdOffset = archive.length - 22
- expect(view.getUint32(eocdOffset, true)).toBe(0x06054b50)
- const entryCount = view.getUint16(eocdOffset + 10, true)
- const centralDirectoryOffset = view.getUint32(eocdOffset + 16, true)
-
- const entries: Array<{ name: string; bytes: Uint8Array }> = []
- let cursor = centralDirectoryOffset
- for (let index = 0; index < entryCount; index += 1) {
- expect(view.getUint32(cursor, true)).toBe(0x02014b50)
- const crc = view.getUint32(cursor + 16, true)
- const size = view.getUint32(cursor + 20, true)
- const nameLength = view.getUint16(cursor + 28, true)
- const localHeaderOffset = view.getUint32(cursor + 42, true)
- const name = decoder.decode(archive.subarray(cursor + 46, cursor + 46 + nameLength))
-
- expect(view.getUint32(localHeaderOffset, true)).toBe(0x04034b50)
- expect(view.getUint16(localHeaderOffset + 8, true)).toBe(0) // STORED
- const localNameLength = view.getUint16(localHeaderOffset + 26, true)
- const dataOffset = localHeaderOffset + 30 + localNameLength
- const bytes = archive.subarray(dataOffset, dataOffset + size)
- expect(bytes.length).toBe(size)
- expect(crc32(bytes)).toBe(crc)
-
- entries.push({ name, bytes })
- cursor += 46 + nameLength
- }
- return entries
-}
-
-function textBytes(text: string): Uint8Array {
- return new TextEncoder().encode(text)
-}
-
-describe('crc32', () => {
- it('matches the known CRC-32 check vector', () => {
- expect(crc32(textBytes('123456789'))).toBe(0xcbf43926)
- })
-
- it('is empty-input stable', () => {
- expect(crc32(new Uint8Array(0))).toBe(0)
- })
-})
-
-describe('createZipWriter', () => {
- it('writes a single stored entry that reads back byte-identical', () => {
- const writer = createZipWriter()
- writer.addFile('folder/hello.txt', textBytes('hello evenfire'))
- const archive = writer.build()
-
- expect(readStoredZip(archive)).toEqual([
- { name: 'folder/hello.txt', bytes: textBytes('hello evenfire') },
- ])
- })
-
- it('writes multiple nested entries in add order', () => {
- const writer = createZipWriter()
- const payloadA = textBytes('aaa')
- const payloadB = new Uint8Array([0, 1, 2, 250, 251, 255])
- const payloadC = new Uint8Array(0)
- writer.addFile('root/b.bin', payloadB)
- writer.addFile('root/sub/deep/a.txt', payloadA)
- writer.addFile('root/empty.dat', payloadC)
-
- expect(writer.entryCount()).toBe(3)
- expect(readStoredZip(writer.build())).toEqual([
- { name: 'root/b.bin', bytes: payloadB },
- { name: 'root/sub/deep/a.txt', bytes: payloadA },
- { name: 'root/empty.dat', bytes: payloadC },
- ])
- })
-
- it('de-duplicates repeated entry names instead of colliding', () => {
- const writer = createZipWriter()
- writer.addFile('docs/plan.md', textBytes('first'))
- writer.addFile('docs/plan.md', textBytes('second'))
-
- const names = readStoredZip(writer.build()).map(entry => entry.name)
- expect(names).toEqual(['docs/plan.md', 'docs/plan (2).md'])
- expect(writer.has('docs/plan.md')).toBe(true)
- expect(writer.has('docs/plan (2).md')).toBe(true)
- })
-
- it('de-duplicates case-insensitive collisions so portable extractors never overwrite (R1-L1)', () => {
- const writer = createZipWriter()
- writer.addFile('Report.txt', textBytes('upper'))
- writer.addFile('report.txt', textBytes('lower'))
- writer.addFile('REPORT.TXT', textBytes('shout'))
-
- const entries = readStoredZip(writer.build())
- expect(entries.map(entry => entry.name)).toEqual([
- 'Report.txt',
- 'report (2).txt',
- 'REPORT (3).TXT',
- ])
- // Distinct content survives the rename, byte-identical.
- const contentDecoder = new TextDecoder()
- expect(entries.map(entry => contentDecoder.decode(entry.bytes))).toEqual([
- 'upper',
- 'lower',
- 'shout',
- ])
- expect(writer.has('report.txt')).toBe(true)
- // Case-insensitive membership: the shout-case original collides with the
- // set even though it was renamed on write.
- expect(writer.has('REPORT.TXT')).toBe(true)
- expect(writer.has('report (4).txt')).toBe(false)
- })
-
- it('marks names as UTF-8 in both header sets', () => {
- const writer = createZipWriter()
- writer.addFile('报告/tafel-übe.png', textBytes('x'))
- const archive = writer.build()
- const view = new DataView(archive.buffer, archive.byteOffset, archive.byteLength)
-
- const eocdOffset = archive.length - 22
- const centralDirectoryOffset = view.getUint32(eocdOffset + 16, true)
- expect(view.getUint32(centralDirectoryOffset, true)).toBe(0x02014b50)
- expect(view.getUint16(centralDirectoryOffset + 8, true) & 0x0800).toBe(0x0800)
-
- const localHeaderOffset = view.getUint32(centralDirectoryOffset + 42, true)
- expect(view.getUint32(localHeaderOffset, true)).toBe(0x04034b50)
- expect(view.getUint16(localHeaderOffset + 6, true) & 0x0800).toBe(0x0800)
- })
-
- it('produces an empty but valid archive with no entries', () => {
- const writer = createZipWriter()
- const archive = writer.build()
- expect(archive.length).toBe(22)
- expect(readStoredZip(archive)).toEqual([])
- })
-
- it('emits exactly the declared structure — no slack, no assembly copy (M2)', () => {
- const writer = createZipWriter()
- const a = textBytes('first-entry')
- const b = textBytes('b')
- writer.addFile('root/a.txt', a)
- writer.addFile('root/nested/b.bin', b)
-
- const archive = writer.build()
- // 30+name+size local records, 46+name central records, 22-byte EOCD.
- const expected =
- 30 +
- 'root/a.txt'.length +
- a.length +
- (30 + 'root/nested/b.bin'.length + b.length) +
- (46 + 'root/a.txt'.length) +
- (46 + 'root/nested/b.bin'.length) +
- 22
- expect(archive.length).toBe(expected)
- })
-
- it('accepts a caller-provided capacity and keeps the same bytes', () => {
- const payload = textBytes('pre-sized payload')
- const writer = createZipWriter({ initialCapacityBytes: 1 })
- writer.addFile('docs/plan.md', payload)
-
- const archive = writer.build()
- expect(archive.length).toBe(
- 30 + 'docs/plan.md'.length + payload.length + 46 + 'docs/plan.md'.length + 22
- )
- expect(readStoredZip(archive)).toEqual([{ name: 'docs/plan.md', bytes: payload }])
- })
-})
diff --git a/desktop-app/ui/src/lib/gfsDownload.ts b/desktop-app/ui/src/lib/gfsDownload.ts
index f56cd5735..298660e93 100644
--- a/desktop-app/ui/src/lib/gfsDownload.ts
+++ b/desktop-app/ui/src/lib/gfsDownload.ts
@@ -9,11 +9,6 @@
*/
export async function saveGfsFileToDisk(uri: string, name: string): Promise<void> {
const { bytes } = await window.clerum.gfs.download(uri)
- saveBytesToDisk(bytes, name)
-}
-
-/** Anchor-save already downloaded bytes (used by the in-memory zip assembly). */
-export function saveBytesToDisk(bytes: BlobPart, name: string): void {
const url = URL.createObjectURL(new Blob([bytes]))
const anchor = document.createElement('a')
anchor.href = url
diff --git a/desktop-app/ui/src/lib/gfsFolderZip.ts b/desktop-app/ui/src/lib/gfsFolderZip.ts
index e08ff6039..5b809a38d 100644
--- a/desktop-app/ui/src/lib/gfsFolderZip.ts
+++ b/desktop-app/ui/src/lib/gfsFolderZip.ts
@@ -1,6 +1,10 @@
/**
- * BUG-175 — recursive "Download as zip" for a GFS folder, assembled fully in
- * the renderer from the existing `window.clerum.gfs` read plane.
+ * BUG-175 — recursive "Download as zip" for a GFS folder. The walk runs in the
+ * renderer over the existing `window.clerum.gfs` read plane; the ARCHIVE is
+ * assembled streamed in the main process (temp file + native save dialog, see
+ * gfs/zipStream.ts), so the renderer never holds archive bytes and its peak
+ * memory is one in-flight transfer, independent of folder size (R1-H2, spec:
+ * round-2 extensions).
*
* Budget contract: the producer meters this walk's request classes per actor —
* resource reads (children, affordances, resolve) and proxy reads (downloads)
@@ -17,7 +21,11 @@
* archive.
*/
import { isRateLimited, parseHttpStatus, parseRetryAfterSeconds } from '@lib/gfsGrantErrors'
-import { createZipWriter } from '@lib/zipWriter'
+import {
+ entryNameFitsZipFields,
+ finalizeEntryName,
+ foldEntryName,
+} from '../../../src/gfs/zipEntryName'
/**
* Client-side pacing for the walk, a deliberate conservative margin: the
@@ -27,11 +35,10 @@ import { createZipWriter } from '@lib/zipWriter'
*/
export const GFS_ZIP_READS_PER_MINUTE = 120
/**
- * Refuse before buffering: total bytes across the folder. 512 MiB is the
- * documented end-to-end bound (spec: ZIP budget model): with the producer-side
- * per-transfer maxBytes and the single pre-sized archive buffer, peak renderer
- * memory at the ceiling is ~2x this cap (archive + save-time Blob) plus one
- * bounded in-flight transfer.
+ * Refuse before buffering: total bytes across the folder. 512 MiB bounds the
+ * streamed archive's temp-file size and each transfer's producer-side bound;
+ * renderer peak memory is ONE in-flight transfer (≤ this cap), independent of
+ * folder size (spec: round-2 extensions, streamed assembly).
*/
export const GFS_ZIP_MAX_TOTAL_BYTES = 512 * 1024 * 1024
/** Refuse before buffering: total file entries across the folder. */
@@ -52,7 +59,9 @@ export interface GfsFolderZipProgress {
}
export interface GfsFolderZipResult {
- bytes: Uint8Array<ArrayBuffer>
+ /** False when the user canceled the native save dialog (temp file deleted). */
+ saved: boolean
+ savedPath: string | null
fileName: string
fileCount: number
skipped: GfsZipSkippedEntry[]
@@ -119,6 +128,16 @@ export interface GfsZipChildrenPage {
nextCursor: string | null
}
+export interface GfsZipStreamDeps {
+ start(): Promise<{ jobId: string }>
+ append(jobId: string, name: string, bytes: ArrayBuffer): Promise<unknown>
+ finish(
+ jobId: string,
+ suggestedName: string
+ ): Promise<{ saved: boolean; filePath: string | null; entryCount: number }>
+ abort(jobId: string): Promise<unknown>
+}
+
export interface GfsFolderZipDeps {
/**
* Lists one folder page. `options.signal` propagates the walk's stop to the
@@ -139,6 +158,12 @@ export interface GfsFolderZipDeps {
uri: string,
options?: { maxBytes?: number; signal?: AbortSignal }
): Promise<{ bytes: ArrayBuffer }>
+ /**
+ * Streamed, file-backed archive assembly in the main process (R1-H2): one
+ * append per downloaded file, one finish at the end, abort cleans the temp
+ * file on any failure path.
+ */
+ zipStream: GfsZipStreamDeps
throttle: GfsReadThrottle
sleep: (ms: number) => Promise<void>
}
@@ -273,6 +298,14 @@ export async function createGfsFolderZip(
maxBytes: requestOptions?.maxBytes,
signal: requestOptions?.signal ?? options.signal,
}))
+ // Default lazily reaches the bridge so a walk that never appends (aborted
+ // early, refused at planning) does not require window.clerum to exist.
+ const zipStream: GfsFolderZipDeps['zipStream'] = options.deps?.zipStream ?? {
+ start: () => window.clerum.gfs.zipStream.start(),
+ append: (jobId, name, bytes) => window.clerum.gfs.zipStream.append(jobId, name, bytes),
+ finish: (jobId, suggestedName) => window.clerum.gfs.zipStream.finish(jobId, suggestedName),
+ abort: jobId => window.clerum.gfs.zipStream.abort(jobId),
+ }
const sleep =
options.deps?.sleep ?? ((ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms)))
const throttle = options.deps?.throttle ?? createGfsReadThrottle()
@@ -409,94 +442,111 @@ export async function createGfsFolderZip(
// can still explain why nothing was archivable.
if (files.length === 0) throw new GfsFolderZipEmptyError(folder.name, skipped)
- // Pre-size the single archive buffer (M2): local header (30) + payload +
- // central record (46), each carrying the UTF-8 name, plus the 22-byte EOCD.
- // With server-provided sizes this allocates once; without them the writer
- // falls back to doubling.
- const nameEncoder = new TextEncoder()
- const estimatedArchiveBytes =
- plannedBytes +
- files.reduce((sum, file) => sum + 76 + 2 * nameEncoder.encode(file.path).length, 22)
- const writer = createZipWriter({ initialCapacityBytes: estimatedArchiveBytes })
-
- // ── Phase 2: throttled downloads, skipping per-resource denials. ──
+ // ── Phase 2: throttled downloads streamed into the main-process archive. ──
+ // The renderer holds ONE in-flight transfer at a time (R1-H2); any failure
+ // aborts the stream job so the temp file never outlives the walk.
+ const { jobId } = await zipStream.start()
+ let archivedCount = 0
+ const usedFoldedNames = new Set<string>()
let addedBytes = 0
- for (const [index, file] of files.entries()) {
- throwIfAborted()
- // R2-L2 — exact budget exhaustion: stop BEFORE the next transfer so a
- // zero-or-negative bound is never requested; the un-fetched files are
- // reported as visible skips and the archive finishes cleanly with what it
- // holds (spec: round-2 extensions).
- const remainingBytes = maxTotalBytes - addedBytes
- if (remainingBytes <= 0) {
- for (const remainingFile of files.slice(index)) {
- skipped.push({ path: remainingFile.path, reason: 'Zip byte limit reached' })
+ try {
+ for (const [index, file] of files.entries()) {
+ throwIfAborted()
+ // R2-L2 — exact budget exhaustion: stop BEFORE the next transfer so a
+ // zero-or-negative bound is never requested; the un-fetched files are
+ // reported as visible skips and the archive finishes cleanly with what
+ // it holds (spec: round-2 extensions).
+ const remainingBytes = maxTotalBytes - addedBytes
+ if (remainingBytes <= 0) {
+ for (const remainingFile of files.slice(index)) {
+ skipped.push({ path: remainingFile.path, reason: 'Zip byte limit reached' })
+ }
+ break
}
- break
- }
- // 1-based: the copy says "downloading N of M" while file N is fetched.
- report({
- phase: 'downloading',
- filesFound: files.length,
- filesAdded: index + 1,
- currentPath: file.path,
- })
- await withAbort(throttle.acquire())
- let bytes: ArrayBuffer
- try {
- // R1-H2: bound the transfer producer-side by the remaining budget so an
- // over-limit body (dishonest or missing declared size) is rejected
- // before it materializes in the renderer; the receipt check below stays
- // as the backstop.
- bytes = (await withRateLimitRetry(() => download(file.uri, { maxBytes: remainingBytes })))
- .bytes
- } catch (error) {
- if (isFolderZipAbortError(error)) throw error
- const message = toMessage(error)
- if (parseHttpStatus(message) === 413) {
- // The remaining budget cannot hold this body: skip it visibly and let
- // the walk terminate cleanly (later files hit the remaining-0 rule).
- skipped.push({ path: file.path, reason: 'Zip byte limit reached' })
- continue
+ // 1-based: the copy says "downloading N of M" while file N is fetched.
+ report({
+ phase: 'downloading',
+ filesFound: files.length,
+ filesAdded: index + 1,
+ currentPath: file.path,
+ })
+ await withAbort(throttle.acquire())
+ let bytes: ArrayBuffer
+ try {
+ // R1-H2: bound the transfer producer-side by the remaining budget so
+ // an over-limit body (dishonest or missing declared size) is rejected
+ // before it materializes in the renderer; the receipt check below
+ // stays as the backstop.
+ bytes = (await withRateLimitRetry(() => download(file.uri, { maxBytes: remainingBytes })))
+ .bytes
+ } catch (error) {
+ if (isFolderZipAbortError(error)) throw error
+ const message = toMessage(error)
+ if (parseHttpStatus(message) === 413) {
+ // The remaining budget cannot hold this body: skip it visibly and
+ // let the walk terminate cleanly (later files hit remaining-0).
+ skipped.push({ path: file.path, reason: 'Zip byte limit reached' })
+ continue
+ }
+ if (isAccessDenied(message)) {
+ skipped.push({ path: file.path, reason: 'Permission denied' })
+ continue
+ }
+ throw error
+ }
+ const data = new Uint8Array(bytes)
+ addedBytes += data.length
+ if (addedBytes > maxTotalBytes) {
+ // Defensive backstop: the producer-side bound makes this unreachable
+ // unless the bound itself was ignored — fail loudly, not silently.
+ throw new GfsFolderZipLimitError(
+ `"${folder.name}" exceeded the ${formatZipBytes(maxTotalBytes)} folder-zip limit while downloading. Download smaller subfolders individually.`
+ )
}
- if (isAccessDenied(message)) {
- skipped.push({ path: file.path, reason: 'Permission denied' })
+ // Finalize the entry name HERE (case-insensitive collision suffix) and
+ // validate the FINALIZED name against the 16-bit ZIP fields before any
+ // header is written: a name that only overflows after suffixing is a
+ // visible skip, never a truncated header (R1-M2, spec: round-2).
+ const finalized = finalizeEntryName(file.path, usedFoldedNames)
+ if (!entryNameFitsZipFields(finalized.name)) {
+ skipped.push({ path: shortenForNotice(file.path), reason: 'Path too long' })
continue
}
- throw error
+ usedFoldedNames.add(finalized.folded)
+ await zipStream.append(jobId, finalized.name, bytes)
+ archivedCount += 1
}
- const data = new Uint8Array(bytes)
- addedBytes += data.length
- if (addedBytes > maxTotalBytes) {
- // Defensive backstop: the producer-side bound makes this unreachable
- // unless the bound itself was ignored — fail loudly, not silently.
- throw new GfsFolderZipLimitError(
- `"${folder.name}" exceeded the ${formatZipBytes(maxTotalBytes)} folder-zip limit while downloading. Download smaller subfolders individually.`
- )
- }
- writer.addFile(file.path, data)
- }
- // Downloads can skip every file (permissions, exhausted budget): the empty
- // short-circuit applies to the archived result, not only the planned list.
- if (writer.entryCount() === 0) throw new GfsFolderZipEmptyError(folder.name, skipped)
-
- // ── Phase 3: assemble the archive. ──
- report({
- phase: 'assembling',
- filesFound: files.length,
- filesAdded: writer.entryCount(),
- currentPath: null,
- })
- const archive = writer.build()
- return {
- bytes: archive,
- fileName: `${sanitizeFileName(folder.name)}.zip`,
- fileCount: writer.entryCount(),
- skipped,
+ // Downloads can skip every file (permissions, exhausted budget): the
+ // empty short-circuit applies to the archived result, not only the
+ // planned list.
+ if (archivedCount === 0) throw new GfsFolderZipEmptyError(folder.name, skipped)
+
+ // ── Phase 3: finalize and save through the native dialog. ──
+ report({
+ phase: 'assembling',
+ filesFound: files.length,
+ filesAdded: archivedCount,
+ currentPath: null,
+ })
+ const fileName = `${sanitizeFileName(folder.name)}.zip`
+ const saved = await zipStream.finish(jobId, fileName)
+ return {
+ saved: saved.saved,
+ savedPath: saved.filePath,
+ fileName,
+ fileCount: saved.entryCount,
+ skipped,
+ }
+ } catch (error) {
+ // Any failure (abort included) must not leave a temp file behind.
+ await zipStream.abort(jobId).catch(() => undefined)
+ throw error
}
}
+export { foldEntryName }
+
function formatZipBytes(bytes: number): string {
if (bytes >= 1024 * 1024 * 1024) return `${Math.round(bytes / (1024 * 1024 * 1024))} GiB`
if (bytes >= 1024 * 1024) return `${Math.round(bytes / (1024 * 1024))} MiB`
diff --git a/desktop-app/ui/src/lib/zipWriter.ts b/desktop-app/ui/src/lib/zipWriter.ts
deleted file mode 100644
index 86a28dc43..000000000
--- a/desktop-app/ui/src/lib/zipWriter.ts
+++ /dev/null
@@ -1,220 +0,0 @@
-/**
- * Minimal ZIP writer used by the client-side folder export (BUG-175).
- *
- * Entries are written with the STORED method (no compression): the archived
- * GFS payloads are already-encoded documents and media, an in-memory writer in
- * the renderer must stay small and deterministic, and a stored archive remains
- * a fully valid ZIP for every standard extractor. No compression also means
- * the total size guard can reason about byte budgets exactly.
- *
- * Memory contract (review M2): entries stream into ONE growable buffer as they
- * arrive — `addFile` copies the caller's bytes in and hands ownership back, so
- * per-entry buffers are released immediately instead of being retained until
- * assembly. `build()` appends the central directory in place and returns a
- * VIEW over the buffer, never a second copy. Callers that know the planned
- * content size (the zip walk does) pass `initialCapacityBytes` so the buffer
- * is allocated once; without it the buffer grows by doubling, whose last
- * reallocation transiently holds old + new buffers.
- *
- * Format reference: APPNOTE.TXT (PKWARE) — local file header (4.3.7), central
- * directory (4.3.12), end-of-central-directory (4.3.19). Names are UTF-8 with
- * the general-purpose flag bit 11 set. DOS timestamps are zero (deterministic
- * output; the source of truth for content dates is the GFS listing).
- */
-
-const LOCAL_FILE_HEADER_SIGNATURE = 0x04034b50
-const CENTRAL_DIRECTORY_SIGNATURE = 0x02014b50
-const END_OF_CENTRAL_DIRECTORY_SIGNATURE = 0x06054b50
-const VERSION_NEEDED = 20
-const UTF8_FLAG = 0x0800
-const STORED_METHOD = 0
-const EOCD_SIZE = 22
-const LOCAL_HEADER_FIXED_SIZE = 30
-const CENTRAL_HEADER_FIXED_SIZE = 46
-const DEFAULT_INITIAL_CAPACITY_BYTES = 64 * 1024
-
-const CRC32_POLYNOMIAL = 0xedb88320
-
-let crc32Table: Uint32Array | null = null
-
-function crc32TableFor(): Uint32Array {
- if (crc32Table) return crc32Table
- const table = new Uint32Array(256)
- for (let index = 0; index < 256; index += 1) {
- let value = index
- for (let bit = 0; bit < 8; bit += 1) {
- value = value & 1 ? (value >>> 1) ^ CRC32_POLYNOMIAL : value >>> 1
- }
- table[index] = value >>> 0
- }
- crc32Table = table
- return table
-}
-
-/** Standard CRC-32 (IEEE 802.3, reflected), as stored in ZIP headers. */
-export function crc32(bytes: Uint8Array): number {
- const table = crc32TableFor()
- let crc = 0xffffffff
- for (let index = 0; index < bytes.length; index += 1) {
- crc = (crc >>> 8) ^ table[(crc ^ bytes[index]!) & 0xff]!
- }
- return (crc ^ 0xffffffff) >>> 0
-}
-
-interface DirectoryEntry {
- nameBytes: Uint8Array
- crc: number
- size: number
- localHeaderOffset: number
-}
-
-export interface CreateZipWriterOptions {
- /** Expected final archive size, when the caller can compute it up front. */
- initialCapacityBytes?: number
-}
-
-export interface ZipWriter {
- /** Adds one entry; returns the path actually written (see `addFile`). */
- addFile(path: string, bytes: Uint8Array): string
- /** True once any entry with this exact path was added. */
- has(path: string): boolean
- entryCount(): number
- /** Finalizes the archive and returns its bytes (a view — do not mutate). */
- build(): Uint8Array<ArrayBuffer>
-}
-
-function encodeName(path: string): Uint8Array {
- return new TextEncoder().encode(path)
-}
-
-export function createZipWriter(options: CreateZipWriterOptions = {}): ZipWriter {
- const entries: DirectoryEntry[] = []
- const usedNames = new Set<string>()
-
- let capacity = Math.max(1, options.initialCapacityBytes ?? DEFAULT_INITIAL_CAPACITY_BYTES)
- let buffer = new Uint8Array(capacity)
- let length = 0
-
- const ensureCapacity = (extra: number) => {
- if (length + extra <= capacity) return
- let next = capacity
- while (next < length + extra) next *= 2
- const grown = new Uint8Array(next)
- grown.set(buffer.subarray(0, length))
- buffer = grown
- capacity = next
- }
-
- const write = (source: Uint8Array) => {
- ensureCapacity(source.length)
- buffer.set(source, length)
- length += source.length
- }
-
- return {
- addFile(path, bytes) {
- const writtenPath = ensureUniqueName(path, usedNames)
- // The set holds case-folded keys: collisions are matched case-insensitively.
- usedNames.add(writtenPath.toLowerCase())
- const nameBytes = encodeName(writtenPath)
- const crc = crc32(bytes)
- const localHeaderOffset = length
-
- const header = new Uint8Array(LOCAL_HEADER_FIXED_SIZE + nameBytes.length)
- const view = new DataView(header.buffer)
- view.setUint32(0, LOCAL_FILE_HEADER_SIGNATURE, true)
- view.setUint16(4, VERSION_NEEDED, true)
- view.setUint16(6, UTF8_FLAG, true)
- view.setUint16(8, STORED_METHOD, true)
- view.setUint16(10, 0, true) // mod time
- view.setUint16(12, 0, true) // mod date
- view.setUint32(14, crc, true)
- view.setUint32(18, bytes.length, true) // compressed size (stored)
- view.setUint32(22, bytes.length, true) // uncompressed size
- view.setUint16(26, nameBytes.length, true)
- view.setUint16(28, 0, true) // extra length
- header.set(nameBytes, LOCAL_HEADER_FIXED_SIZE)
- write(header)
- // Copy the payload into the archive buffer; after this returns the
- // caller's per-entry buffer is no longer referenced (M2).
- write(bytes)
-
- entries.push({ nameBytes, crc, size: bytes.length, localHeaderOffset })
- return writtenPath
- },
-
- has(path) {
- return usedNames.has(path.toLowerCase())
- },
-
- entryCount() {
- return entries.length
- },
-
- build() {
- const centralDirectoryOffset = length
- for (const entry of entries) {
- const record = new Uint8Array(CENTRAL_HEADER_FIXED_SIZE + entry.nameBytes.length)
- const view = new DataView(record.buffer)
- view.setUint32(0, CENTRAL_DIRECTORY_SIGNATURE, true)
- view.setUint16(4, VERSION_NEEDED, true) // made by
- view.setUint16(6, VERSION_NEEDED, true) // needed
- view.setUint16(8, UTF8_FLAG, true)
- view.setUint16(10, STORED_METHOD, true)
- view.setUint16(12, 0, true) // mod time
- view.setUint16(14, 0, true) // mod date
- view.setUint32(16, entry.crc, true)
- view.setUint32(20, entry.size, true)
- view.setUint32(24, entry.size, true)
- view.setUint16(28, entry.nameBytes.length, true)
- view.setUint16(30, 0, true) // extra length
- view.setUint16(32, 0, true) // comment length
- view.setUint16(34, 0, true) // disk start
- view.setUint16(36, 0, true) // internal attributes
- view.setUint32(38, 0, true) // external attributes
- view.setUint32(42, entry.localHeaderOffset, true)
- record.set(entry.nameBytes, CENTRAL_HEADER_FIXED_SIZE)
- write(record)
- }
- const centralDirectorySize = length - centralDirectoryOffset
-
- const eocd = new Uint8Array(EOCD_SIZE)
- const view = new DataView(eocd.buffer)
- view.setUint32(0, END_OF_CENTRAL_DIRECTORY_SIGNATURE, true)
- view.setUint16(4, 0, true) // this disk
- view.setUint16(6, 0, true) // central directory disk
- view.setUint16(8, entries.length, true)
- view.setUint16(10, entries.length, true)
- view.setUint32(12, centralDirectorySize, true)
- view.setUint32(16, centralDirectoryOffset, true)
- view.setUint16(20, 0, true) // comment length
- write(eocd)
- return buffer.subarray(0, length)
- },
- }
-}
-
-/**
- * De-duplication for repeated zip entry names: `a/b.txt` → `a/b (2).txt`.
- * Matching is case-insensitive across the WHOLE path (`Report.txt` collides
- * with `report.txt`): portable case-insensitive extractors (macOS, Windows)
- * would otherwise silently overwrite one of the two during extraction, so the
- * second colliding name is suffixed instead (spec: name-collision policy).
- */
-function ensureUniqueName(path: string, usedNames: Set<string>): string {
- const fold = (candidate: string) => candidate.toLowerCase()
- if (!usedNames.has(fold(path))) return path
- const slash = path.lastIndexOf('/')
- const directory = slash >= 0 ? path.slice(0, slash + 1) : ''
- const base = slash >= 0 ? path.slice(slash + 1) : path
- const dot = base.lastIndexOf('.')
- const stem = dot > 0 ? base.slice(0, dot) : base
- const extension = dot > 0 ? base.slice(dot) : ''
- let counter = 2
- let candidate = `${directory}${stem} (${counter})${extension}`
- while (usedNames.has(fold(candidate))) {
- counter += 1
- candidate = `${directory}${stem} (${counter})${extension}`
- }
- return candidate
-}
diff --git a/desktop-app/ui/src/pages/FilesPage.tsx b/desktop-app/ui/src/pages/FilesPage.tsx
index 3d294671b..a49485a86 100644
--- a/desktop-app/ui/src/pages/FilesPage.tsx
+++ b/desktop-app/ui/src/pages/FilesPage.tsx
@@ -41,7 +41,7 @@ import {
useGfsBrowserController,
} from '@hooks/domain/useGfsBrowserController'
import { isEventFromNestedInteractive } from '@lib/clickableRowProps'
-import { saveBytesToDisk, saveGfsFileToDisk } from '@lib/gfsDownload'
+import { saveGfsFileToDisk } from '@lib/gfsDownload'
import { assertGfsFileUploadSize } from '@lib/gfsFileUpload'
import {
GfsFolderZipEmptyError,
@@ -867,11 +867,16 @@ export function FilesPage({
signal: abortController.signal,
}
)
- saveBytesToDisk(result.bytes, result.fileName)
- pushToast?.(
- `Downloaded ${result.fileName} (${result.fileCount} ${result.fileCount === 1 ? 'file' : 'files'})`,
- 'success'
- )
+ if (result.saved) {
+ pushToast?.(
+ `Downloaded ${result.fileName} (${result.fileCount} ${result.fileCount === 1 ? 'file' : 'files'})`,
+ 'success'
+ )
+ } else {
+ // The native save dialog was canceled: the temp archive is already
+ // deleted by the stream's finish path — nothing was saved, by choice.
+ pushToast?.(`${folder.name}.zip was not saved — the save dialog was canceled.`, 'info')
+ }
if (result.skipped.length) {
pushToast?.(describeZipSkips(result.skipped), 'warn', { durationMs: 10_000 })
}
diff --git a/desktop-app/ui/src/pages/__tests__/FilesPage.test.tsx b/desktop-app/ui/src/pages/__tests__/FilesPage.test.tsx
index 8bf85f978..4ac307697 100644
--- a/desktop-app/ui/src/pages/__tests__/FilesPage.test.tsx
+++ b/desktop-app/ui/src/pages/__tests__/FilesPage.test.tsx
@@ -3313,16 +3313,23 @@ describe('FilesPage', () => {
)
const download = vi.fn(async () => ({ bytes: new Uint8Array([1, 2, 3, 4]).buffer }))
const pushToast = vi.fn()
- const createObjectURL = vi.fn(() => 'blob:folder-zip')
const click = vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => {})
- Object.defineProperty(URL, 'createObjectURL', { configurable: true, value: createObjectURL })
- Object.defineProperty(URL, 'revokeObjectURL', {
- configurable: true,
- value: vi.fn(),
- })
+ const appendedNames: string[] = []
+ const zipStream = {
+ start: vi.fn(async () => ({ jobId: 'job-1' })),
+ append: vi.fn(async (_jobId: string, name: string) => {
+ appendedNames.push(name)
+ }),
+ finish: vi.fn(async (_jobId: string, suggestedName: string) => ({
+ saved: true,
+ filePath: `/saved/${suggestedName}`,
+ entryCount: appendedNames.length,
+ })),
+ abort: vi.fn(async () => ({ aborted: true })),
+ }
Object.defineProperty(window, 'clerum', {
configurable: true,
- value: { gfs: { listChildren, download } },
+ value: { gfs: { listChildren, download, zipStream } },
})
hookMock.useGfsBrowserController.mockReturnValue({
...baseController(),
@@ -3371,10 +3378,12 @@ describe('FilesPage', () => {
maxBytes: 512 * 1024 * 1024,
signal: expect.any(AbortSignal),
})
- expect(createObjectURL).toHaveBeenCalledWith(expect.any(Blob))
- expect(click).toHaveBeenCalled()
- const savedName = (click.mock.instances[0] as HTMLAnchorElement | undefined)?.download
- expect(savedName).toBe('Assets.zip')
+ // The streamed save path: the entry reached the main-process writer and
+ // finish saved the archive — no renderer anchor download for zips.
+ expect(appendedNames).toEqual(['Assets/plan.md'])
+ expect(zipStream.finish).toHaveBeenCalledWith('job-1', 'Assets.zip')
+ expect(zipStream.abort).not.toHaveBeenCalled()
+ expect(click).not.toHaveBeenCalled()
expect(pushToast).toHaveBeenCalledWith('Downloaded Assets.zip (1 file)', 'success')
expect(pushToast).toHaveBeenCalledWith(
'Skipped 1 entry: Assets/secret.txt (No access)',
@@ -3508,9 +3517,15 @@ describe('FilesPage', () => {
const download = vi.fn(async () => ({ bytes: new Uint8Array([1, 2, 3, 4]).buffer }))
const pushToast = vi.fn()
const click = vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => {})
+ const zipStream = {
+ start: vi.fn(async () => ({ jobId: 'job-1' })),
+ append: vi.fn(async () => undefined),
+ finish: vi.fn(async () => ({ saved: true, filePath: '/saved/x.zip', entryCount: 1 })),
+ abort: vi.fn(async () => ({ aborted: true })),
+ }
Object.defineProperty(window, 'clerum', {
configurable: true,
- value: { gfs: { listChildren, download } },
+ value: { gfs: { listChildren, download, zipStream } },
})
const folderRow = {
resourceId: 'folder-1',
@@ -3558,6 +3573,9 @@ describe('FilesPage', () => {
expect(pushToast).toHaveBeenCalledWith('Stopped preparing Assets.zip.', 'info')
expect(pushToast).not.toHaveBeenCalledWith(expect.stringContaining('Downloaded'), 'success')
expect(click).not.toHaveBeenCalled()
+ // Stopping also tells the main process to drop the temp archive.
+ expect(zipStream.abort).toHaveBeenCalledWith('job-1')
+ expect(zipStream.finish).not.toHaveBeenCalled()
// A replacement walk starts cleanly once the stopped one has settled —
// one job at a time, no overlap (R1-M1).