Skip to content

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

TypeScript

fix(desktop): serialize zip entry lifecycles and reserve the limits atomically (R3-M2, R4-M1)

M144339c958cb
diff --git a/desktop-app/src/__tests__/gfsZipStream.test.ts b/desktop-app/src/__tests__/gfsZipStream.test.ts
index a78257ccd..b905a5854 100644
--- a/desktop-app/src/__tests__/gfsZipStream.test.ts
+++ b/desktop-app/src/__tests__/gfsZipStream.test.ts
@@ -50,11 +50,12 @@ async function makeDeps(
failDialog?: boolean
openFile?: ZipStreamDeps['openFile']
} = {}
-): Promise<ZipStreamDeps & { tempDir: string }> {
+): Promise<ZipStreamDeps & { tempDir: string; savePath: string }> {
const tempDir = await mkdtemp(join(tmpdir(), 'evenfire-zip-test-'))
tempRoots.push(tempDir)
return {
tempDir,
+ savePath,
openFile: options.openFile,
showSaveDialog: vi.fn(async () => {
if (options.failDialog) throw new Error('save dialog failed')
@@ -319,6 +320,218 @@ describe('gfs zipStream — streamed payload (R1-H2)', () => {
})
})
+/**
+ * R4-M1 / R3-M2 — CONCURRENCY. The writer used to serialize individual
+ * WRITES, not complete ENTRY LIFECYCLES, so two concurrent appends could
+ * interleave: the second entry's local header landed inside the first
+ * entry's payload. The aggregate ceilings were likewise checked against
+ * committed state only, so concurrent appends could collectively exceed
+ * them.
+ */
+describe('gfs zipStream — concurrent entries (R4-M1, R3-M2)', () => {
+ /** Yields to the event loop, so concurrent appends really do interleave. */
+ const yieldToLoop = () => new Promise<void>(resolve => setTimeout(resolve, 0))
+
+ it('keeps concurrent streaming appends from interleaving entries (R4-M1)', async () => {
+ const savePath = join(tmpdir(), `concurrent-${Date.now()}.zip`)
+ savedFiles.push(savePath)
+ const deps = await makeDeps(savePath)
+ const jobId = await openJob(OWNER, deps)
+
+ const sources = [
+ { name: 'a.txt', chunks: ['aaa-1', 'aaa-2', 'aaa-3'] },
+ { name: 'b.txt', chunks: ['bbb-1', 'bbb-2', 'bbb-3'] },
+ { name: 'c.txt', chunks: ['ccc-1', 'ccc-2', 'ccc-3'] },
+ ]
+ // All three appends are ACCEPTED before any of them completes.
+ const results = await Promise.all(
+ sources.map(source =>
+ appendZipEntryStreaming(
+ jobId,
+ OWNER,
+ source.name,
+ async sink => {
+ for (const chunk of source.chunks) {
+ await sink.write(new TextEncoder().encode(chunk))
+ await yieldToLoop()
+ }
+ },
+ deps
+ )
+ )
+ )
+ expect(results.map(result => result.bytes)).toEqual([15, 15, 15])
+
+ await finishZipJob(jobId, OWNER, 'Concurrent.zip', deps)
+
+ // An INDEPENDENT reader sees three complete entries whose payloads are
+ // exactly what the producers wrote.
+ const { entries } = readZipArchive(new Uint8Array(await readFile(savePath)))
+ expect(entries.map(entry => entry.name).sort()).toEqual(['a.txt', 'b.txt', 'c.txt'])
+ for (const entry of entries) {
+ const source = sources.find(candidate => candidate.name === entry.name)!
+ expect(new TextDecoder().decode(entry.bytes)).toBe(source.chunks.join(''))
+ expect(entry.crc).toBe(crc32(entry.bytes))
+ }
+
+ // The SYSTEM extractor agrees — a corrupted archive does not extract.
+ const extracted = await extractWithSystemUnzip(savePath)
+ if (extracted) {
+ expect(extracted['a.txt']).toBe('aaa-1aaa-2aaa-3')
+ expect(extracted['b.txt']).toBe('bbb-1bbb-2bbb-3')
+ expect(extracted['c.txt']).toBe('ccc-1ccc-2ccc-3')
+ }
+ })
+
+ it('keeps a failed concurrent append from corrupting its neighbours (R4-M1)', async () => {
+ const savePath = join(tmpdir(), `concurrent-rollback-${Date.now()}.zip`)
+ savedFiles.push(savePath)
+ const deps = await makeDeps(savePath)
+ const jobId = await openJob(OWNER, deps)
+
+ const good = appendZipEntryStreaming(
+ jobId,
+ OWNER,
+ 'good.txt',
+ async sink => {
+ await sink.write(new TextEncoder().encode('good-1'))
+ await yieldToLoop()
+ await sink.write(new TextEncoder().encode('good-2'))
+ await yieldToLoop()
+ },
+ deps
+ )
+ const doomed = appendZipEntryStreaming(
+ jobId,
+ OWNER,
+ 'doomed.txt',
+ async sink => {
+ await sink.write(new TextEncoder().encode('partial'))
+ await yieldToLoop()
+ throw new Error('producer failed mid-stream')
+ },
+ deps
+ )
+
+ await expect(doomed).rejects.toThrow(/producer failed/)
+ await expect(good).resolves.toMatchObject({ name: 'good.txt', bytes: 12 })
+
+ await finishZipJob(jobId, OWNER, 'ConcurrentRollback.zip', deps)
+ const { entries } = readZipArchive(new Uint8Array(await readFile(savePath)))
+ expect(entries.map(entry => entry.name)).toEqual(['good.txt'])
+ expect(new TextDecoder().decode(entries[0]!.bytes)).toBe('good-1good-2')
+ })
+
+ it('reserves job slots atomically across concurrent starts (R3-M2)', async () => {
+ const deps = await makeDeps(join(tmpdir(), 'batch.zip'))
+ // Every start is fired WITHOUT awaiting, so they all race for the slots.
+ // DIFFERENT owners race for the PROCESS-wide ceiling.
+ const attempts = Array.from({ length: MAX_ACTIVE_ZIP_JOBS + 3 }, (_, index) =>
+ startZipJob(`window-${index}`, deps).then(
+ jobId => ({ ok: true as const, jobId }),
+ error => ({ ok: false as const, error })
+ )
+ )
+ const settled = await Promise.all(attempts)
+ const opened = settled.filter(result => result.ok)
+ const refused = settled.filter(result => !result.ok)
+ // Register the opened jobs for cleanup BEFORE asserting, so a failing
+ // expectation cannot leak a job into the next test.
+ settled.forEach((result, index) => {
+ if (result.ok) openJobs.push({ jobId: result.jobId, owner: `window-${index}`, deps })
+ })
+
+ expect(opened).toHaveLength(MAX_ACTIVE_ZIP_JOBS)
+ expect(refused).toHaveLength(3)
+ for (const result of refused) {
+ expect((result as { error: Error }).error).toBeInstanceOf(ZipStreamLimitError)
+ }
+ })
+
+ it('reserves per-window job slots atomically across concurrent starts (R3-M2)', async () => {
+ const deps = await makeDeps(join(tmpdir(), 'owner-batch.zip'))
+ // ONE window racing for its own ceiling.
+ const attempts = Array.from({ length: MAX_ACTIVE_ZIP_JOBS_PER_OWNER + 3 }, () =>
+ startZipJob(OWNER, deps).then(
+ jobId => ({ ok: true as const, jobId }),
+ error => ({ ok: false as const, error })
+ )
+ )
+ const settled = await Promise.all(attempts)
+ // Register the opened jobs for cleanup BEFORE asserting.
+ for (const result of settled.filter(result => result.ok)) {
+ openJobs.push({ jobId: result.jobId, owner: OWNER, deps })
+ }
+ expect(settled.filter(result => result.ok)).toHaveLength(MAX_ACTIVE_ZIP_JOBS_PER_OWNER)
+ expect(settled.filter(result => !result.ok)).toHaveLength(3)
+ for (const result of settled.filter(result => !result.ok)) {
+ expect((result as { error: Error }).error).toBeInstanceOf(ZipStreamLimitError)
+ }
+ })
+
+ it('reserves the payload budget atomically across concurrent appends (R3-M2)', async () => {
+ const deps = await makeDeps(join(tmpdir(), 'budget.zip'))
+ const jobId = await openJob(OWNER, { ...deps, limits: { maxTotalBytes: 64 } })
+
+ // Three appends of 32 bytes each: only TWO fit in a 64-byte archive.
+ const attempts = Array.from({ length: 3 }, (_, index) =>
+ appendZipEntryStreaming(
+ jobId,
+ OWNER,
+ `entry-${index}.bin`,
+ async sink => {
+ await sink.write(new Uint8Array(32).fill(index + 1))
+ await yieldToLoop()
+ },
+ deps
+ ).then(
+ () => ({ ok: true as const }),
+ error => ({ ok: false as const, error })
+ )
+ )
+ const settled = await Promise.all(attempts)
+ const accepted = settled.filter(result => result.ok)
+ const refused = settled.filter(result => !result.ok)
+
+ // The ceiling is not bypassed: the archive never exceeds 64 payload bytes.
+ expect(accepted).toHaveLength(2)
+ expect(refused).toHaveLength(1)
+ expect((refused[0] as { error: Error }).error).toBeInstanceOf(ZipStreamLimitError)
+
+ await finishZipJob(jobId, OWNER, 'Budget.zip', deps)
+ const { entries } = readZipArchive(new Uint8Array(await readFile(deps.savePath)))
+ const total = entries.reduce((sum, entry) => sum + entry.bytes.length, 0)
+ expect(total).toBeLessThanOrEqual(64)
+ })
+
+ it('reserves the entry count atomically across concurrent appends (R3-M2)', async () => {
+ const deps = await makeDeps(join(tmpdir(), 'entries.zip'))
+ const jobId = await openJob(OWNER, { ...deps, limits: { maxEntries: 2 } })
+
+ const attempts = Array.from({ length: 4 }, (_, index) =>
+ appendZipEntryStreaming(
+ jobId,
+ OWNER,
+ `entry-${index}.bin`,
+ async sink => {
+ await sink.write(new TextEncoder().encode('x'))
+ await yieldToLoop()
+ },
+ deps
+ ).then(
+ () => ({ ok: true as const }),
+ error => ({ ok: false as const, error })
+ )
+ )
+ const settled = await Promise.all(attempts)
+ expect(settled.filter(result => result.ok)).toHaveLength(2)
+ expect(settled.filter(result => !result.ok)).toHaveLength(2)
+ for (const result of settled.filter(result => !result.ok)) {
+ expect((result as { error: Error }).error).toBeInstanceOf(ZipStreamLimitError)
+ }
+ })
+})
+
describe('gfs zipStream — path safety (R3-M1)', () => {
const unsafeNames = [
'../outside.txt',
diff --git a/desktop-app/src/gfs/zipStream.ts b/desktop-app/src/gfs/zipStream.ts
index 7a6ee312c..d44362e9b 100644
--- a/desktop-app/src/gfs/zipStream.ts
+++ b/desktop-app/src/gfs/zipStream.ts
@@ -1,11 +1,11 @@
/**
- * File-backed ZIP assembly for the folder-zip export (R1-H2, spec: round-2
- * extensions). The renderer walks the folder and hands each entry to the main
- * process; 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. Peak renderer memory is independent of folder size; main keeps
- * ~76 + name bytes per entry plus one chunk.
+ * File-backed ZIP assembly for the folder-zip export (R1-H2, R3-M1, R3-M2,
+ * R3-M3, R3-M5, R4-M1). The renderer walks the folder and hands each entry to
+ * the main process; 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. Peak renderer memory is independent of folder
+ * size; main keeps ~76 + name bytes per entry plus one chunk.
*
* The main process is the TRUST BOUNDARY, not a helper. A renderer is a web
* page: it must not be able to write outside the directory the user chose, to
@@ -16,17 +16,44 @@
* - PATH SAFETY (R3-M1): every entry name is validated as a canonical
* relative path BEFORE a byte of entry data is written.
* - RESOURCE LIMITS (R3-M2): aggregate payload bytes, entry count, the ZIP32
- * format bounds, job ownership and concurrency are all enforced here.
+ * format bounds, job ownership and concurrency are all enforced here, and
+ * every one of them is RESERVED ATOMICALLY before the asynchronous work
+ * that consumes it.
* - CLEANUP OWNERSHIP (R3-M3): the job owns its handle and its temp file until
* the save has completed; every unsuccessful path closes the handle and
* removes the file.
* - STREAMED PAYLOAD (R1-H2): the payload is written chunk by chunk, so a
* large file never materializes as one contiguous buffer.
*
+ * ## Concurrency (R4-M1)
+ *
+ * The writer serializes COMPLETE ENTRY LIFECYCLES, not individual WRITES.
+ * An entry's local header, payload and CRC patch are written by ONE task, so
+ * two concurrent appends can never interleave: the second entry's header
+ * cannot land inside the first entry's payload. Finalization waits for every
+ * accepted append to settle before the central directory is written, so an
+ * in-flight entry can never land after the directory.
+ *
+ * ## Reservations (R3-M2)
+ *
+ * A ceiling that is CHECKED but not RESERVED is a ceiling two concurrent
+ * operations can both slip past. Every limit below is therefore taken as a
+ * reservation in ONE synchronous step, before the first `await`:
+ *
+ * - a job slot, held from before the temp file is opened until the job is
+ * registered;
+ * - an entry slot, held from admission until the entry commits or fails;
+ * - payload bytes, held per chunk until the entry commits or fails.
+ *
+ * The reservations are taken against the COMMITTED state plus everything
+ * other accepted appends already reserved, so the aggregate ceilings include
+ * in-flight work. A rejected append releases everything it reserved and
+ * changes nothing: not the file size, not the entry list, not the counters.
+ *
* 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).
+ * the payload is streamed, not compressed, so the CRC is computed over the
+ * bytes as they are written).
*/
import { dialog } from 'electron'
import { randomUUID } from 'node:crypto'
@@ -97,28 +124,40 @@ interface ZipStreamJob {
ownerId: string
tempPath: string
handle: Awaited<ReturnType<typeof open>>
- /** Serializes temp-file writes across append calls. Never rejects. */
- writeChain: Promise<void>
+ /**
+ * Serializes COMPLETE ENTRY LIFECYCLES: one at a time, in acceptance
+ * order. Never rejects.
+ */
+ lifecycleChain: Promise<void>
+ /** The entries committed to the central directory. */
entries: DirectoryEntry[]
+ /**
+ * Entry slots held by accepted appends that have not committed yet. Counted
+ * against the entry ceiling together with the committed entries (R3-M2).
+ */
+ reservedEntries: number
allocator: ZipEntryNameAllocator
/** Payload bytes committed to the archive (the archive's data size). */
payloadBytes: number
+ /**
+ * Payload bytes reserved by accepted appends that have not committed yet.
+ * Counted against the payload ceiling together with the committed bytes
+ * (R3-M2).
+ */
+ reservedPayloadBytes: number
/** Bytes written to the temp file: payload + local headers. */
byteCount: number
/** The archive's ceilings, resolved when the job was opened. */
limits: ZipStreamLimits
- /** Appends currently in flight for this job. */
+ /** Appends accepted and not yet finished (queued or running). */
inFlight: number
- closed: boolean
+ /** The archive is being finalized: no further append is accepted. */
+ finishing: boolean
+ /** The job is dead: no further lifecycle may start. */
destroyed: boolean
-}
-
-/** An entry whose local header has been written and whose payload follows. */
-interface PreparedEntry {
- plan: PlannedEntryName
- nameBytes: Uint8Array
- header: Uint8Array
- localHeaderOffset: number
+ /** The handle and the temp file have been released. */
+ cleaned: boolean
+ closed: boolean
}
export interface ZipStreamLimits {
@@ -151,6 +190,14 @@ export const MAX_ACTIVE_ZIP_JOBS_PER_OWNER = 2
export const MAX_CONCURRENT_APPENDS_PER_JOB = 4
const jobs = new Map<string, ZipStreamJob>()
+/**
+ * Jobs being opened RIGHT NOW. Their slot is held from before the temp file
+ * is opened until the job is registered, so two concurrent starts cannot
+ * both observe the same free capacity (R3-M2).
+ */
+let pendingJobStarts = 0
+/** The same, per window, so one window cannot bypass its own ceiling. */
+const pendingJobStartsByOwner = new Map<string, number>()
/** The entry name is unsafe: it could escape the extraction directory. */
export class ZipStreamNameError extends Error {
@@ -188,13 +235,17 @@ function requireJob(jobId: string, ownerId: string): ZipStreamJob {
}
/**
- * Serializes one write onto the job's chain. A failed write belongs to the
- * append that caused it: the chain stays usable so a later append is not
- * silently skipped, and the job's cleanup path owns the broken handle.
+ * Runs one complete entry lifecycle, strictly in acceptance order.
+ *
+ * The WHOLE lifecycle — local header, payload, CRC patch — runs inside ONE
+ * task, so an entry's bytes are always contiguous and never interleaved with
+ * another entry's (R4-M1). A failed lifecycle belongs to the append that
+ * caused it: the chain stays usable so a later append is not silently
+ * skipped.
*/
-function enqueue<T>(job: ZipStreamJob, task: () => Promise<T>): Promise<T> {
- const result = job.writeChain.then(task, task)
- job.writeChain = result.then(
+function enqueueLifecycle<T>(job: ZipStreamJob, task: () => Promise<T>): Promise<T> {
+ const result = job.lifecycleChain.then(task, task)
+ job.lifecycleChain = result.then(
() => undefined,
() => undefined
)
@@ -202,15 +253,63 @@ function enqueue<T>(job: ZipStreamJob, task: () => Promise<T>): Promise<T> {
}
/**
- * Closes the handle and removes the temp file, and drops the job. The job
+ * Reserves an entry slot and its payload bytes, in ONE synchronous step,
+ * BEFORE any asynchronous work (R3-M2).
+ *
+ * The check and the reservation are not separated by an `await`, so two
+ * concurrent appends cannot both observe the same free capacity and
+ * collectively exceed a ceiling. Everything reserved here is released again
+ * when the append fails.
+ */
+function reserveAppend(job: ZipStreamJob, payloadBytes: number): void {
+ const maxEntries = Math.min(job.limits.maxEntries, ZIP32_MAX_ENTRIES)
+ if (job.entries.length + job.reservedEntries >= maxEntries) {
+ throw new ZipStreamLimitError(
+ `A ZIP archive holds at most ${maxEntries} entries, which this archive would exceed`
+ )
+ }
+ if (job.payloadBytes + job.reservedPayloadBytes + payloadBytes > job.limits.maxTotalBytes) {
+ throw new ZipStreamLimitError(
+ `The archive would exceed the ${job.limits.maxTotalBytes}-byte folder-zip limit`
+ )
+ }
+ job.reservedEntries += 1
+ job.reservedPayloadBytes += payloadBytes
+}
+
+/**
+ * Reserves one payload chunk against the archive's ceilings, in ONE
+ * synchronous step (R3-M2).
+ *
+ * The aggregate ceiling includes the bytes other accepted appends already
+ * reserved, so in-flight work counts against the budget.
+ */
+function reservePayload(job: ZipStreamJob, bytes: number): void {
+ if (job.payloadBytes + job.reservedPayloadBytes + bytes > job.limits.maxTotalBytes) {
+ throw new ZipStreamLimitError(
+ `The archive would exceed the ${job.limits.maxTotalBytes}-byte folder-zip limit`
+ )
+ }
+ if (job.byteCount + bytes > ZIP32_MAX_BYTES) {
+ throw new ZipStreamLimitError('The archive would exceed the ZIP32 size limit')
+ }
+ job.reservedPayloadBytes += bytes
+}
+
+/**
+ * Releases the handle and removes the temp file, and drops the job. The job
* OWNS both resources until the save completes, so this is the single place
* that releases them (R3-M3).
+ *
+ * This does NOT wait for the lifecycle chain: it is called from INSIDE a
+ * lifecycle when a rollback fails, and awaiting the chain from within the
+ * chain would deadlock.
*/
async function destroyJob(job: ZipStreamJob, deps: ZipStreamDeps): Promise<void> {
jobs.delete(job.jobId)
- if (job.destroyed) return
job.destroyed = true
- await job.writeChain.catch(() => undefined)
+ if (job.cleaned) return
+ job.cleaned = true
if (!job.closed) {
job.closed = true
await job.handle.close().catch(() => undefined)
@@ -219,36 +318,54 @@ async function destroyJob(job: ZipStreamJob, deps: ZipStreamDeps): Promise<void>
}
export async function startZipJob(ownerId: string, deps: ZipStreamDeps = {}): Promise<string> {
- if (jobs.size >= MAX_ACTIVE_ZIP_JOBS) {
- throw new ZipStreamLimitError('Too many ZIP jobs are already open')
- }
+ // ── ADMISSION (synchronous, atomic) ─────────────────────────────────────
+ // The slot is taken BEFORE the first await, so two concurrent starts
+ // cannot both observe the same free capacity and collectively exceed the
+ // ceiling (R3-M2).
+ const pendingOwned = pendingJobStartsByOwner.get(ownerId) ?? 0
let owned = 0
for (const job of jobs.values()) if (job.ownerId === ownerId) owned += 1
- if (owned >= MAX_ACTIVE_ZIP_JOBS_PER_OWNER) {
+ if (jobs.size + pendingJobStarts >= MAX_ACTIVE_ZIP_JOBS) {
+ throw new ZipStreamLimitError('Too many ZIP jobs are already open')
+ }
+ if (owned + pendingOwned >= MAX_ACTIVE_ZIP_JOBS_PER_OWNER) {
throw new ZipStreamLimitError('This window already has too many ZIP jobs open')
}
- 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, {
- jobId,
- ownerId,
- tempPath,
- handle,
- writeChain: Promise.resolve(),
- entries: [],
- allocator: new ZipEntryNameAllocator(),
- payloadBytes: 0,
- byteCount: 0,
- limits: {
- maxTotalBytes: deps.limits?.maxTotalBytes ?? ZIP_MAX_TOTAL_BYTES,
- maxEntries: deps.limits?.maxEntries ?? ZIP_MAX_ENTRIES,
- },
- inFlight: 0,
- closed: false,
- destroyed: false,
- })
- return jobId
+ pendingJobStarts += 1
+ pendingJobStartsByOwner.set(ownerId, pendingOwned + 1)
+ try {
+ 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, {
+ jobId,
+ ownerId,
+ tempPath,
+ handle,
+ lifecycleChain: Promise.resolve(),
+ entries: [],
+ reservedEntries: 0,
+ allocator: new ZipEntryNameAllocator(),
+ payloadBytes: 0,
+ reservedPayloadBytes: 0,
+ byteCount: 0,
+ limits: {
+ maxTotalBytes: deps.limits?.maxTotalBytes ?? ZIP_MAX_TOTAL_BYTES,
+ maxEntries: deps.limits?.maxEntries ?? ZIP_MAX_ENTRIES,
+ },
+ inFlight: 0,
+ finishing: false,
+ destroyed: false,
+ cleaned: false,
+ closed: false,
+ })
+ return jobId
+ } finally {
+ pendingJobStarts -= 1
+ const current = pendingJobStartsByOwner.get(ownerId) ?? 1
+ if (current <= 1) pendingJobStartsByOwner.delete(ownerId)
+ else pendingJobStartsByOwner.set(ownerId, current - 1)
+ }
}
function localHeader(nameBytes: Uint8Array, crc: number, size: number): Uint8Array {
@@ -270,22 +387,18 @@ function localHeader(nameBytes: Uint8Array, crc: number, size: number): Uint8Arr
}
/**
- * Validates the entry and reserves its name, WITHOUT touching the archive.
+ * Validates the entry and plans its name, WITHOUT touching the archive and
+ * WITHOUT reserving anything.
*
- * Every check here runs before the caller writes a byte, so a rejected append
- * leaves the file size, the entry list and the byte counters exactly as they
- * were (R3-M2).
+ * The name is planned INSIDE the entry lifecycle, so it is planned against
+ * the names already committed: two concurrent appends of the same name get
+ * two different names, never one duplicated entry.
*/
function prepareEntry(job: ZipStreamJob, rawName: string): PlannedEntryName {
const rejection = validateZipEntryPath(rawName)
if (rejection) throw new ZipStreamNameError(rawName, rejection)
const plan = job.allocator.plan(rawName)
if (!plan.fits) throw new ZipStreamNameTooLongError(plan.name)
- if (job.entries.length >= Math.min(job.limits.maxEntries, ZIP32_MAX_ENTRIES)) {
- throw new ZipStreamLimitError(
- `A ZIP archive holds at most ${Math.min(job.limits.maxEntries, ZIP32_MAX_ENTRIES)} entries, which this archive would exceed`
- )
- }
return plan
}
@@ -302,39 +415,53 @@ export async function appendZipEntry(
): Promise<string> {
const job = requireJob(jobId, ownerId)
const data = new Uint8Array(bytes)
- const plan = prepareEntry(job, rawName)
- if (job.payloadBytes + data.byteLength > job.limits.maxTotalBytes) {
- throw new ZipStreamLimitError(
- `The archive would exceed the ${job.limits.maxTotalBytes}-byte folder-zip limit`
- )
- }
- const nameBytes = new TextEncoder().encode(plan.name)
- const header = localHeader(nameBytes, 0, 0)
- if (job.byteCount + header.length + data.byteLength > ZIP32_MAX_BYTES) {
- throw new ZipStreamLimitError('The archive would exceed the ZIP32 size limit')
+ // ── ADMISSION (synchronous, atomic) ─────────────────────────────────────
+ if (job.finishing) throw new Error('The ZIP archive is being finalized')
+ if (job.inFlight + 1 > MAX_CONCURRENT_APPENDS_PER_JOB) {
+ throw new ZipStreamLimitError('Too many ZIP appends are in flight for this job')
}
- const localHeaderOffset = job.byteCount
+ reserveAppend(job, data.byteLength)
+ job.inFlight += 1
try {
- await enqueue(job, async () => {
- await job.handle.write(header, 0, header.length, localHeaderOffset)
- await job.handle.write(data, 0, data.byteLength, localHeaderOffset + header.length)
- const crc = crc32(data)
- const patch = new Uint8Array(12)
- const view = new DataView(patch.buffer)
- view.setUint32(0, crc, true)
- view.setUint32(4, data.byteLength, true)
- view.setUint32(8, data.byteLength, true)
- await job.handle.write(patch, 0, patch.length, localHeaderOffset + 14)
- job.allocator.commit(plan)
- job.entries.push({ nameBytes, crc, size: data.byteLength, localHeaderOffset })
- job.payloadBytes += data.byteLength
- job.byteCount = localHeaderOffset + header.length + data.byteLength
+ return await enqueueLifecycle(job, async () => {
+ let localHeaderOffset: number | undefined
+ try {
+ if (job.destroyed) throw new Error('The ZIP job was destroyed')
+ const plan = prepareEntry(job, rawName)
+ const nameBytes = new TextEncoder().encode(plan.name)
+ const header = localHeader(nameBytes, 0, 0)
+ if (job.byteCount + header.length + data.byteLength > ZIP32_MAX_BYTES) {
+ throw new ZipStreamLimitError('The archive would exceed the ZIP32 size limit')
+ }
+ localHeaderOffset = job.byteCount
+ await job.handle.write(header, 0, header.length, localHeaderOffset)
+ await job.handle.write(data, 0, data.byteLength, localHeaderOffset + header.length)
+ const crc = crc32(data)
+ const patch = new Uint8Array(12)
+ const view = new DataView(patch.buffer)
+ view.setUint32(0, crc, true)
+ view.setUint32(4, data.byteLength, true)
+ view.setUint32(8, data.byteLength, true)
+ await job.handle.write(patch, 0, patch.length, localHeaderOffset + 14)
+ job.byteCount = localHeaderOffset + header.length + data.byteLength
+ job.allocator.commit(plan)
+ job.entries.push({ nameBytes, crc, size: data.byteLength, localHeaderOffset })
+ job.payloadBytes += data.byteLength
+ job.reservedPayloadBytes -= data.byteLength
+ job.reservedEntries -= 1
+ return plan.name
+ } catch (error) {
+ job.reservedPayloadBytes -= data.byteLength
+ job.reservedEntries -= 1
+ if (localHeaderOffset !== undefined) {
+ await rollBackEntry(job, localHeaderOffset, deps)
+ }
+ throw error
+ }
})
- } catch (error) {
- await rollBackEntry(job, localHeaderOffset, deps)
- throw error
+ } finally {
+ job.inFlight -= 1
}
- return plan.name
}
/**
@@ -343,6 +470,9 @@ export async function appendZipEntry(
* the job can still serve the next one. A failed rollback means the handle is
* no longer trustworthy, so the job is destroyed (its handle closed and its
* temp file removed).
+ *
+ * This runs INSIDE the failing entry's own lifecycle, so no other entry can
+ * be written between the failure and the truncation (R4-M1).
*/
async function rollBackEntry(
job: ZipStreamJob,
@@ -350,10 +480,8 @@ async function rollBackEntry(
deps: ZipStreamDeps
): Promise<void> {
try {
- await enqueue(job, async () => {
- await job.handle.truncate(localHeaderOffset)
- job.byteCount = localHeaderOffset
- })
+ await job.handle.truncate(localHeaderOffset)
+ job.byteCount = localHeaderOffset
} catch {
await destroyJob(job, deps)
}
@@ -380,6 +508,9 @@ export interface ZipStreamEntryResult {
* CRC and writes it straight to the temp file. The local header is written
* first with placeholder CRC/size fields and patched in place once the
* payload is complete, so the entry stays a valid STORED entry.
+ *
+ * The WHOLE entry — header, payload, patch — is one lifecycle, so a
+ * concurrent append cannot interleave with it (R4-M1).
*/
export async function appendZipEntryStreaming(
jobId: string,
@@ -389,77 +520,80 @@ export async function appendZipEntryStreaming(
deps: ZipStreamDeps = {}
): Promise<ZipStreamEntryResult> {
const job = requireJob(jobId, ownerId)
+ // ── ADMISSION (synchronous, atomic) ─────────────────────────────────────
+ if (job.finishing) throw new Error('The ZIP archive is being finalized')
if (job.inFlight + 1 > MAX_CONCURRENT_APPENDS_PER_JOB) {
throw new ZipStreamLimitError('Too many ZIP appends are in flight for this job')
}
+ reserveAppend(job, 0)
job.inFlight += 1
- let preparedEntryOffset: number | undefined
try {
- const prepared: PreparedEntry = await enqueue(job, async () => {
- const plan = prepareEntry(job, rawName)
- const nameBytes = new TextEncoder().encode(plan.name)
- const header = localHeader(nameBytes, 0, 0)
- if (job.byteCount + header.length > ZIP32_MAX_BYTES) {
- throw new ZipStreamLimitError('The archive would exceed the ZIP32 size limit')
- }
- const localHeaderOffset = job.byteCount
- preparedEntryOffset = localHeaderOffset
- await job.handle.write(header, 0, header.length, localHeaderOffset)
- job.byteCount = localHeaderOffset + header.length
- return { plan, nameBytes, header, localHeaderOffset }
- })
-
- let crc = CRC32_INIT
- let size = 0
- const sink: ZipEntrySink = {
- write: async (chunk: Uint8Array) => {
- if (chunk.byteLength === 0) return
- if (job.payloadBytes + size + chunk.byteLength > job.limits.maxTotalBytes) {
- throw new ZipStreamLimitError(
- `The archive would exceed the ${job.limits.maxTotalBytes}-byte folder-zip limit`
- )
- }
- if (job.byteCount + chunk.byteLength > ZIP32_MAX_BYTES) {
+ return await enqueueLifecycle(job, async () => {
+ let localHeaderOffset: number | undefined
+ let reservedPayload = 0
+ try {
+ if (job.destroyed) throw new Error('The ZIP job was destroyed')
+ const plan = prepareEntry(job, rawName)
+ const nameBytes = new TextEncoder().encode(plan.name)
+ const header = localHeader(nameBytes, 0, 0)
+ if (job.byteCount + header.length > ZIP32_MAX_BYTES) {
throw new ZipStreamLimitError('The archive would exceed the ZIP32 size limit')
}
- size += chunk.byteLength
- crc = crc32Update(crc, chunk)
- await enqueue(job, async () => {
- await job.handle.write(chunk, 0, chunk.byteLength, job.byteCount)
- job.byteCount += chunk.byteLength
- })
- },
- }
-
- await produce(sink)
+ localHeaderOffset = job.byteCount
+ await job.handle.write(header, 0, header.length, localHeaderOffset)
+ job.byteCount = localHeaderOffset + header.length
+
+ let crc = CRC32_INIT
+ let size = 0
+ const sink: ZipEntrySink = {
+ write: async (chunk: Uint8Array) => {
+ if (chunk.byteLength === 0) return
+ // ATOMIC reservation: the chunk's bytes are claimed before the
+ // write, against the aggregate ceiling that includes every other
+ // accepted append's reservation (R3-M2).
+ reservePayload(job, chunk.byteLength)
+ reservedPayload += chunk.byteLength
+ size += chunk.byteLength
+ crc = crc32Update(crc, chunk)
+ await job.handle.write(chunk, 0, chunk.byteLength, job.byteCount)
+ job.byteCount += chunk.byteLength
+ },
+ }
- const finalCrc = (crc ^ CRC32_INIT) >>> 0
- await enqueue(job, async () => {
- const patch = new Uint8Array(12)
- const view = new DataView(patch.buffer)
- view.setUint32(0, finalCrc, true)
- view.setUint32(4, size, true)
- view.setUint32(8, size, true)
- await job.handle.write(patch, 0, patch.length, prepared.localHeaderOffset + 14)
- })
- job.allocator.commit(prepared.plan)
- job.entries.push({
- nameBytes: prepared.nameBytes,
- crc: finalCrc,
- size,
- localHeaderOffset: prepared.localHeaderOffset,
+ await produce(sink)
+
+ const finalCrc = (crc ^ CRC32_INIT) >>> 0
+ const patch = new Uint8Array(12)
+ const view = new DataView(patch.buffer)
+ view.setUint32(0, finalCrc, true)
+ view.setUint32(4, size, true)
+ view.setUint32(8, size, true)
+ await job.handle.write(patch, 0, patch.length, localHeaderOffset + 14)
+
+ job.allocator.commit(plan)
+ job.entries.push({
+ nameBytes,
+ crc: finalCrc,
+ size,
+ localHeaderOffset,
+ })
+ job.payloadBytes += size
+ job.reservedPayloadBytes -= reservedPayload
+ job.reservedEntries -= 1
+ return { name: plan.name, bytes: size }
+ } catch (error) {
+ // The entry is incomplete. Release everything it reserved and roll it
+ // back so the archive stays a valid sequence of complete entries and
+ // the job can still serve the next one; a failed rollback destroys the
+ // job instead of leaving an unowned resource behind (R3-M3).
+ job.reservedPayloadBytes -= reservedPayload
+ job.reservedEntries -= 1
+ if (localHeaderOffset !== undefined) {
+ await rollBackEntry(job, localHeaderOffset, deps)
+ }
+ throw error
+ }
})
- job.payloadBytes += size
- return { name: prepared.plan.name, bytes: size }
- } catch (error) {
- // The entry is incomplete. Roll it back so the archive stays a valid
- // sequence of complete entries and the job can still serve the next one;
- // a failed rollback destroys the job (its handle closed, its temp file
- // removed) instead of leaving an unowned resource behind (R3-M3).
- if (preparedEntryOffset !== undefined) {
- await rollBackEntry(job, preparedEntryOffset, deps)
- }
- throw error
} finally {
job.inFlight -= 1
}
@@ -477,6 +611,11 @@ export interface FinishZipJobResult {
* The job stays REGISTERED until the save has completed: the cleanup
* ownership must not end while the temp file is still on disk, or a failure
* here would leave an unowned `.part` file behind (R3-M3).
+ *
+ * No further append is accepted once the archive is being finalized, and the
+ * central directory is written only after every ACCEPTED append has settled
+ * — otherwise an in-flight entry could land after the directory and produce
+ * an invalid archive (R4-M1).
*/
export async function finishZipJob(
jobId: string,
@@ -485,58 +624,61 @@ export async function finishZipJob(
deps: ZipStreamDeps = {}
): Promise<FinishZipJobResult> {
const job = requireJob(jobId, ownerId)
+ // No further append is accepted from here on.
+ job.finishing = true
+ // Wait for every accepted append to settle before the directory is built.
+ await job.lifecycleChain.catch(() => undefined)
+
const entryCount = job.entries.length
try {
- await enqueue(job, async () => {
- 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)
- // Every write carries an EXPLICIT position: the writer must survive a
- // rollback that truncates the file, and a truncated file leaves the
- // handle's own position pointing past the new end.
- let writeOffset = job.byteCount
- for (const part of parts) {
- await job.handle.write(part, 0, part.length, writeOffset)
- writeOffset += part.length
- }
- job.byteCount = writeOffset
- await job.handle.close()
- job.closed = true
- })
+ 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)
+ // Every write carries an EXPLICIT position: the writer must survive a
+ // rollback that truncates the file, and a truncated file leaves the
+ // handle's own position pointing past the new end.
+ let writeOffset = job.byteCount
+ for (const part of parts) {
+ await job.handle.write(part, 0, part.length, writeOffset)
+ writeOffset += part.length
+ }
+ job.byteCount = writeOffset
+ await job.handle.close()
+ job.closed = true
} catch (error) {
await destroyJob(job, deps)
throw error
@@ -580,6 +722,10 @@ export async function abortZipJob(
if (job.ownerId !== ownerId) {
throw new Error(`ZIP job ${jobId} belongs to another window`)
}
+ // A queued append must not start against a closing handle.
+ job.destroyed = true
+ // Wait for the in-flight entry to settle, so no write races the close.
+ await job.lifecycleChain.catch(() => undefined)
await destroyJob(job, deps)
}