Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
// @vitest-environment jsdom
import { describe, expect, it, vi } from 'vitest'
import {
GFS_ZIP_MAX_ENTRIES,
type GfsFolderZipDeps,
GfsFolderZipEmptyError,
GfsFolderZipLimitError,
type GfsFolderZipProgress,
type GfsZipChildItem,
type GfsZipChildrenPage,
createGfsFolderZip,
createGfsReadThrottle,
} from '../gfsFolderZip'
interface ManualClock {
now: () => number
sleep: (ms: number) => Promise<void>
/** Resolves one pending sleep and advances the clock by its delay. */
advanceOne: () => boolean
pending: () => number
}
function manualClock(): ManualClock {
let current = 1_000_000
const wakeups: Array<{ delayMs: number; wake: () => void }> = []
return {
now: () => current,
sleep: ms =>
new Promise<void>(resolve => {
wakeups.push({ delayMs: ms, wake: () => resolve() })
}),
advanceOne: () => {
const next = wakeups.shift()
if (!next) return false
current += next.delayMs
next.wake()
return true
},
pending: () => wakeups.length,
}
}
function folder(
overrides: Partial<GfsZipChildItem> & { resourceId: string; name: string }
): GfsZipChildItem {
return {
gfsUri: `gfs://main/${overrides.resourceId}`,
kind: 'file',
bytes: 4,
drive: 'main',
...overrides,
}
}
/**
* A producer for one resource: it answers with the entry's byte count, or
* throws the way the real producer would (a 403, a 413, a 500).
*/
type ZipProducer = (uri: string, options?: { maxBytes?: number }) => Promise<{ bytes: number }>
export interface RecordedZipStream {
appended: Array<{ name: string; uri: string; bytes: number }>
finishedWith: Array<{ suggestedName: string }>
abortedJobs: string[]
deps: import('../gfsFolderZip').GfsZipStreamDeps
}
/**
* File-backed stream fake: records appends, finishes "saved" to a path. The
* archive is assembled in the MAIN process in production; the renderer only
* hands over a name and a URI, so the fake records the same two things.
*/
function recordedZipStream(
options: { saved?: boolean; producers?: Record<string, ZipProducer> } = {}
): RecordedZipStream {
const appended: Array<{ name: string; uri: string; bytes: number }> = []
const finishedWith: Array<{ suggestedName: string }> = []
const abortedJobs: string[] = []
let jobCounter = 0
return {
appended,
finishedWith,
abortedJobs,
deps: {
start: vi.fn(async () => ({ jobId: `job-${++jobCounter}` })),
appendFromUri: vi.fn(
async (
jobId: string,
name: string,
uri: string,
requestOptions?: { maxBytes?: number }
) => {
void jobId
const producer = options.producers?.[uri]
const result = producer ? await producer(uri, requestOptions) : { bytes: uri.length }
appended.push({ name, uri, bytes: result.bytes })
return { name, bytes: result.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 }>>,
producers: Record<string, ZipProducer> = {},
streamOptions: { saved?: boolean } = {}
): GfsFolderZipDeps & { zipStreamRecord: RecordedZipStream } {
const stream = recordedZipStream({ ...streamOptions, producers })
return {
listChildren: vi.fn(async (resourceId: string, _drive: string, cursor?: string) => {
const pageList = pages[resourceId]
if (!pageList) throw new Error(`unexpected listChildren for ${resourceId}`)
const index = cursor ? Number(cursor) : 0
const page = pageList[index]
if (!page) throw new Error(`no page ${index} for ${resourceId}`)
return { items: page.items, nextCursor: page.nextCursor }
}),
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,
}
}
describe('createGfsReadThrottle', () => {
it('spaces requests to the 120/min budget with the injected clock', async () => {
const clock = manualClock()
const throttle = createGfsReadThrottle({ now: clock.now, sleep: clock.sleep })
const timings: number[] = []
const job = (async () => {
for (let index = 0; index < 4; index += 1) {
await throttle.acquire()
timings.push(clock.now())
}
})()
// Drive the clock until the job is done: resolve a pending sleep when one
// exists, otherwise let microtasks run so the job can arm the next one.
while (timings.length < 4) {
if (!clock.advanceOne()) await Promise.resolve()
}
await job
expect(timings).toEqual([1_000_000, 1_000_500, 1_001_000, 1_001_500])
})
})
describe('createGfsFolderZip', () => {
it('walks nested folders with pagination and archives every readable file', async () => {
const deps = depsFor({
'folder-root': [
{ items: [folder({ resourceId: 'a', name: 'a.txt' })], nextCursor: '1' },
{
items: [
folder({ resourceId: 'sub', name: 'sub', kind: 'directory' }),
folder({ resourceId: 'b', name: 'b.png' }),
],
nextCursor: null,
},
],
sub: [{ items: [folder({ resourceId: 'c', name: 'c.md' })], nextCursor: null }],
})
const progress: GfsFolderZipProgress[] = []
const result = await createGfsFolderZip(
{ resourceId: 'folder-root', drive: 'main', name: 'Docs' },
{
deps,
onProgress: value => progress.push(value),
}
)
expect(result.fileName).toBe('Docs.zip')
expect(result.fileCount).toBe(3)
expect(result.skipped).toEqual([])
expect(deps.listChildren).toHaveBeenCalledWith('folder-root', 'main', undefined, {
signal: undefined,
})
expect(deps.listChildren).toHaveBeenCalledWith('folder-root', 'main', '1', {
signal: undefined,
})
expect(deps.listChildren).toHaveBeenCalledWith('sub', 'main', undefined, { signal: undefined })
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.
expect(
progress.filter(value => value.phase === 'downloading').map(value => value.filesAdded)
).toEqual([1, 2, 3])
})
it('never carries payload bytes through the renderer (R1-H2)', async () => {
// The renderer hands the main process a NAME and a URI; the payload is
// fetched and written in main, chunk by chunk. The walk therefore never
// asks the renderer for bytes at all.
const deps = depsFor({
root: [{ items: [folder({ resourceId: 'big', name: 'big.bin' })], nextCursor: null }],
})
await createGfsFolderZip({ resourceId: 'root', drive: 'main', name: 'Docs' }, { deps })
const append = deps.zipStreamRecord.deps.appendFromUri as ReturnType<typeof vi.fn>
expect(append).toHaveBeenCalledTimes(1)
const [jobId, name, uri, options] = append.mock.calls[0] as [
string,
string,
string,
{ maxBytes?: number; signal?: AbortSignal } | undefined,
]
expect(name).toBe('Docs/big.bin')
expect(uri).toBe('gfs://main/big')
expect(options?.maxBytes).toBeGreaterThan(0)
// No ArrayBuffer anywhere in the call: the payload stays in main.
expect(JSON.stringify(append.mock.calls)).not.toContain('ArrayBuffer')
expect(jobId).toMatch(/^job-/)
})
it('keeps the renderer free of payload bytes at the near-limit ceiling (R1-H2)', async () => {
// The near-limit memory claim: even at the full ceiling the renderer only
// hands over a NAME and a URI. The producer's byte count is the biggest
// number the renderer ever sees, and it is a COUNT, not a payload.
const seenBounds: Array<number | undefined> = []
const deps = depsFor(
{
root: [
{
items: [
folder({ resourceId: 'big', name: 'big.bin', bytes: undefined as unknown as number }),
],
nextCursor: null,
},
],
},
{
'gfs://main/big': async (_uri: string, options?: { maxBytes?: number }) => {
seenBounds.push(options?.maxBytes)
return { bytes: 64 * 1024 * 1024 }
},
}
)
const result = await createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Big' },
{ deps }
)
// The transfer was bounded by the WHOLE remaining budget, and the walk
// finished with the archive saved.
expect(seenBounds).toEqual([512 * 1024 * 1024])
expect(result.fileCount).toBe(1)
expect(result.saved).toBe(true)
expect(result.savedPath).toBe('/saved/Big.zip')
// The renderer never received the bytes: the only thing it passed on is
// the name, the URI and the bound.
const append = deps.zipStreamRecord.deps.appendFromUri as ReturnType<typeof vi.fn>
const [, , , options] = append.mock.calls[0] as [
string,
string,
string,
{ maxBytes?: number } | undefined,
]
expect(options?.maxBytes).toBe(512 * 1024 * 1024)
expect(JSON.stringify(append.mock.calls)).not.toContain('ArrayBuffer')
})
it('skips unreadable rows and 403 downloads with visible reasons', async () => {
const deps = depsFor(
{
root: [
{
items: [
folder({
resourceId: 'hidden-dir',
name: 'hidden-dir',
kind: 'directory',
readable: false,
}),
folder({ resourceId: 'hidden', name: 'hidden.txt', readable: false }),
folder({ resourceId: 'denied', name: 'denied.txt' }),
folder({ resourceId: 'ok', name: 'ok.txt' }),
],
nextCursor: null,
},
],
},
{
'gfs://main/denied': async () => {
throw new Error('gfs download failed: 403 httpStatus=403 forbidden')
},
}
)
const result = await createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Mixed' },
{ deps }
)
expect(result.fileCount).toBe(1)
expect(result.skipped).toEqual([
{ path: 'Mixed/hidden-dir', reason: 'No access' },
{ path: 'Mixed/hidden.txt', reason: 'No access' },
{ path: 'Mixed/denied.txt', reason: 'Permission denied' },
])
expect(streamEntryNames(deps.zipStreamRecord)).toEqual(['Mixed/ok.txt'])
})
it('skips a subfolder whose listing itself is denied and continues the walk', async () => {
const deps: GfsFolderZipDeps = {
listChildren: vi.fn(async (resourceId: string) => {
if (resourceId === 'root')
return {
items: [folder({ resourceId: 'locked', name: 'locked', kind: 'directory' })],
nextCursor: null,
}
throw new Error("Error invoking remote method 'gfs:listChildren': Error: httpStatus=403")
}),
throttle: { acquire: async () => undefined },
sleep: async () => undefined,
zipStream: recordedZipStream().deps,
}
const result = await createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Root' },
{ deps }
).catch(error => error)
// Nothing archivable: the walk short-circuits as empty (L8), carrying the
// skip so the caller can still explain why.
expect(result).toBeInstanceOf(GfsFolderZipEmptyError)
expect((result as GfsFolderZipEmptyError).skipped).toEqual([
{ path: 'Root/locked', reason: 'Permission denied' },
])
})
it('refuses over the declared byte ceiling with a clear message', async () => {
const deps = depsFor({
root: [
{
items: [
folder({ resourceId: 'big', name: 'big.bin', bytes: 600 }),
folder({ resourceId: 'big2', name: 'big2.bin', bytes: 600 }),
],
nextCursor: null,
},
],
})
await expect(
createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Huge' },
{ deps, limits: { maxTotalBytes: 1024 } }
)
).rejects.toBeInstanceOf(GfsFolderZipLimitError)
await expect(
createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Huge' },
{ deps, limits: { maxTotalBytes: 1024 } }
)
).rejects.toThrow(/exceeds the 1 KiB folder-zip limit/)
})
it('refuses over the declared entry ceiling', async () => {
expect(GFS_ZIP_MAX_ENTRIES).toBeGreaterThan(0)
const deps = depsFor({
root: [
{
items: [
folder({ resourceId: 'one', name: 'one.txt' }),
folder({ resourceId: 'two', name: 'two.txt' }),
folder({ resourceId: 'three', name: 'three.txt' }),
],
nextCursor: null,
},
],
})
await expect(
createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Many' },
{ deps, limits: { maxEntries: 2 } }
)
).rejects.toThrow(/more than 2 entries/)
})
it('counts DIRECTORIES against the entry budget, bounding folder-only walks (R1-M3)', async () => {
// 2001 empty folders used to pass the file-only budget: every one of them
// would then cost a listing request against the shared read budget.
const deps = depsFor({
root: [
{
items: Array.from({ length: GFS_ZIP_MAX_ENTRIES + 1 }, (_, index) =>
folder({ resourceId: `empty-${index}`, name: `empty-${index}`, kind: 'directory' })
),
nextCursor: null,
},
],
})
await expect(
createGfsFolderZip({ resourceId: 'root', drive: 'main', name: 'Hive' }, { deps })
).rejects.toThrow(
new RegExp(`more than ${GFS_ZIP_MAX_ENTRIES} entries \\(files and folders\\)`)
)
// Bounded work: the refusal fires inside the FIRST listing page.
expect(deps.listChildren).toHaveBeenCalledTimes(1)
expect(deps.zipStreamRecord.deps.appendFromUri).not.toHaveBeenCalled()
})
it('forwards the stop signal to the producer bridge on both call kinds (R1-M1)', async () => {
const controller = new AbortController()
const listChildren = vi.fn(
(
_resourceId: string,
_drive?: string,
_cursor?: string,
_options?: { signal?: AbortSignal }
) => new Promise<GfsZipChildrenPage>(() => undefined)
)
const appendFromUri = vi.fn(
async () => new Promise<{ name: string; bytes: number }>(() => undefined)
)
const previousClerum = (window as { clerum?: unknown }).clerum
;(window as { clerum?: unknown }).clerum = {
gfs: { listChildren, zipStream: { appendFromUri } },
}
try {
const walk = createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Bridge' },
{ signal: controller.signal }
)
const rejection = expect(walk).rejects.toMatchObject({ name: 'AbortError' })
for (let index = 0; index < 200 && listChildren.mock.calls.length === 0; index += 1)
await Promise.resolve()
const bridgeOptions = listChildren.mock.calls[0]?.[3] as { signal?: AbortSignal } | undefined
// The default wiring hands the walk's signal to the bridge, so the
// producer fetch dies with the walk instead of outliving the Stop.
expect(bridgeOptions?.signal).toBeInstanceOf(AbortSignal)
expect(bridgeOptions?.signal?.aborted).toBe(false)
controller.abort()
await rejection
expect(bridgeOptions?.signal?.aborted).toBe(true)
} finally {
;(window as { clerum?: unknown }).clerum = previousClerum
}
})
it('aborts the stream job on any failure path so no temp file survives (R1-H2)', async () => {
const stream = recordedZipStream({
producers: {
'gfs://main/doomed': async () => {
throw new Error('gfs download failed: 500 httpStatus=500')
},
},
})
const deps: GfsFolderZipDeps = {
listChildren: vi.fn(async () => ({
items: [folder({ resourceId: 'doomed', name: 'doomed.txt' })],
nextCursor: null,
})),
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({
producers: {
'gfs://main/first': () => new Promise<{ bytes: number }>(() => undefined),
},
})
const controller = new AbortController()
const stopDeps: GfsFolderZipDeps = {
listChildren: vi.fn(async () => ({
items: [folder({ resourceId: 'first', name: 'first.txt' })],
nextCursor: null,
})),
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('validates the FINAL name after collision suffixing, not the pre-collision path (R1-M2)', async () => {
// A path at 65533 encoded bytes fits the 16-bit field; a colliding twin
// whose ` (2)` suffix pushes it to 65537 must be a visible skip, never a
// truncated header. Built with legal 1000-byte segments (each under the
// 1024-byte segment cap) down a 65-deep chain.
const chainName = 'f'.repeat(1000)
const depth = 65
const leafName = 'x'.repeat(65533 - 2 - depth * 1001)
const pages: Record<string, Array<{ items: GfsZipChildItem[]; nextCursor: null }>> = {}
pages.root = [
{
items: [folder({ resourceId: 'n0', name: chainName, kind: 'directory' })],
nextCursor: null,
},
]
for (let index = 0; index < depth - 1; index += 1) {
pages[`n${index}`] = [
{
items: [folder({ resourceId: `n${index + 1}`, name: chainName, kind: 'directory' })],
nextCursor: null,
},
]
}
// The deepest folder holds TWO children with the same near-limit name.
pages[`n${depth - 1}`] = [
{
items: [
folder({ resourceId: 'twin-a', name: leafName }),
folder({ resourceId: 'twin-b', name: leafName }),
],
nextCursor: null,
},
]
const deps = depsFor(pages)
const result = await createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'D' },
{ deps }
)
const written = streamEntryNames(deps.zipStreamRecord)
expect(written).toHaveLength(1)
expect(new TextEncoder().encode(written[0]!).length).toBeLessThan(65535)
expect(result.fileCount).toBe(1)
expect(result.skipped).toEqual([
{ path: expect.stringContaining('…'), reason: 'Path too long' },
])
})
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,
// shortened path) and its subtree is pruned, so the walk stays bounded.
const longName = 'a'.repeat(700)
const depth = 110
const pages: Record<string, Array<{ items: GfsZipChildItem[]; nextCursor: null }>> = {}
const chainChild = (index: number) =>
index === depth - 1
? folder({ resourceId: 'leaf', name: 'leaf.txt', kind: 'file' })
: folder({ resourceId: `f${index}`, name: longName, kind: 'directory' })
pages.root = [{ items: [chainChild(0)], nextCursor: null }]
for (let index = 0; index < depth - 1; index += 1) {
pages[`f${index}`] = [{ items: [chainChild(index + 1)], nextCursor: null }]
}
const deps = depsFor(pages)
const result = await createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Deep' },
{ deps }
).catch(error => error)
// The only file lived under the pruned subtree: nothing archivable, and the
// skip notice explains why with a path a human can read.
expect(result).toBeInstanceOf(GfsFolderZipEmptyError)
const skipped = (result as GfsFolderZipEmptyError).skipped
expect(skipped[0]?.reason).toBe('Path too long')
expect(skipped[0]?.path.length).toBeLessThan(120)
// The walk terminated at the overflow depth instead of chasing all 110
// levels: bounded listing work, no downloads.
const listingCalls = vi.mocked(deps.listChildren).mock.calls.length
expect(listingCalls).toBeLessThanOrEqual(110)
expect(listingCalls).toBeGreaterThanOrEqual(90)
expect(deps.zipStreamRecord.deps.appendFromUri).not.toHaveBeenCalled()
})
it('refuses when the actual downloaded bytes exceed the ceiling', async () => {
const deps = depsFor(
{
root: [
{
items: [folder({ resourceId: 'lied', name: 'lied.bin', bytes: 1 })],
nextCursor: null,
},
],
},
{ 'gfs://main/lied': async () => ({ bytes: 2048 }) }
)
await expect(
createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Sneaky' },
{ deps, limits: { maxTotalBytes: 1024 } }
)
).rejects.toThrow(/exceeded the 1 KiB folder-zip limit while downloading/)
})
it('bounds each transfer producer-side by the remaining budget (R1-H2)', async () => {
// Declared size missing (older server) + a dishonestly large body: the
// bounded fetch must refuse BEFORE the body materializes — the walk's
// only obligation after that is mapping the refusal to the limit error.
const deps = depsFor(
{
root: [
{
items: [
folder({
resourceId: 'ghost',
name: 'ghost.bin',
bytes: undefined as unknown as number,
}),
],
nextCursor: null,
},
],
},
{
'gfs://main/ghost': async (_uri: string, options?: { maxBytes?: number }) => {
expect(options?.maxBytes).toBe(1024)
throw new Error('gfs download exceeds the 1024-byte limit httpStatus=413')
},
}
)
const result = await createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Ghost' },
{ deps, limits: { maxTotalBytes: 1024 } }
).catch(error => error)
// R2-L2: a producer-refused body no longer kills the job — the file is
// skipped with a visible reason and the walk terminates cleanly.
expect(result).toBeInstanceOf(GfsFolderZipEmptyError)
expect((result as GfsFolderZipEmptyError).skipped).toEqual([
{ path: 'Ghost/ghost.bin', reason: 'Zip byte limit reached' },
])
})
it('stops before the next transfer at exact budget exhaustion, never maxBytes 0 (R2-L2)', async () => {
// Missing declared sizes: the first file honestly consumes the whole
// budget; the two behind it must never be requested (a zero bound is an
// invalid IPC), and the archive finishes with a visible notice per file.
const seenBounds: Array<number | undefined> = []
const deps = depsFor(
{
root: [
{
items: [
folder({
resourceId: 'fill',
name: 'fill.bin',
bytes: undefined as unknown as number,
}),
folder({
resourceId: 'after-a',
name: 'after-a.bin',
bytes: undefined as unknown as number,
}),
folder({
resourceId: 'after-b',
name: 'after-b.bin',
bytes: undefined as unknown as number,
}),
],
nextCursor: null,
},
],
},
{
'gfs://main/fill': async (_uri: string, options?: { maxBytes?: number }) => {
seenBounds.push(options?.maxBytes)
return { bytes: 1024 }
},
'gfs://main/after-a': async (_uri: string, options?: { maxBytes?: number }) => {
seenBounds.push(options?.maxBytes)
return { bytes: 1 }
},
'gfs://main/after-b': async (_uri: string, options?: { maxBytes?: number }) => {
seenBounds.push(options?.maxBytes)
return { bytes: 1 }
},
}
)
// R1-M6: the walk's outcome is CAPTURED, so a regression fails as an
// assertion ("the walk did not finish cleanly") instead of as an
// unhandled rejection thrown before the first expectation.
const outcome = await createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Exact' },
{ deps, limits: { maxTotalBytes: 1024 } }
).then(
value => ({ ok: true as const, value }),
error => ({ ok: false as const, error })
)
expect(outcome.ok).toBe(true)
if (!outcome.ok) return
const result = outcome.value
expect(seenBounds).toEqual([1024])
expect(result.fileCount).toBe(1)
expect(result.skipped).toEqual([
{ path: 'Exact/after-a.bin', reason: 'Zip byte limit reached' },
{ path: 'Exact/after-b.bin', reason: 'Zip byte limit reached' },
])
expect(streamEntryNames(deps.zipStreamRecord)).toEqual(['Exact/fill.bin'])
})
it('carries a near-limit folder through download, zip and save-sized output (R1-H2)', async () => {
// Two honest files at half the ceiling each: the second transfer is
// bounded by exactly the remaining budget and both land in the archive.
const seenMaxBytes: Array<number | undefined> = []
const deps = depsFor(
{
root: [
{
items: [
folder({ resourceId: 'half-a', name: 'half-a.bin', bytes: 512 }),
folder({ resourceId: 'half-b', name: 'half-b.bin', bytes: 512 }),
],
nextCursor: null,
},
],
},
{
'gfs://main/half-a': async (_uri: string, options?: { maxBytes?: number }) => {
seenMaxBytes.push(options?.maxBytes)
return { bytes: 512 }
},
'gfs://main/half-b': async (_uri: string, options?: { maxBytes?: number }) => {
seenMaxBytes.push(options?.maxBytes)
return { bytes: 512 }
},
}
)
const result = await createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Brink' },
{ deps, limits: { maxTotalBytes: 1024 } }
)
expect(result.fileCount).toBe(2)
expect(seenMaxBytes).toEqual([1024, 512])
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 () => {
let attempts = 0
const deps: GfsFolderZipDeps = {
listChildren: vi.fn(async () => {
attempts += 1
if (attempts === 1)
throw new Error('gfs children failed: 429 httpStatus=429 retryAfterSeconds=2')
return { items: [], nextCursor: null }
}),
throttle: { acquire: async () => undefined },
sleep: async () => undefined,
zipStream: recordedZipStream().deps,
}
// The retry succeeds but finds nothing archivable → empty short-circuit.
await expect(
createGfsFolderZip({ resourceId: 'root', drive: 'main', name: 'Throttled' }, { deps })
).rejects.toThrow(/no downloadable files/)
expect(attempts).toBe(2)
})
it('stops before the first request when the signal is aborted mid-wait (M3)', async () => {
const listChildren = vi.fn(async () => ({ items: [], nextCursor: null }))
const controller = new AbortController()
const deps: GfsFolderZipDeps = {
listChildren,
throttle: { acquire: () => new Promise<void>(() => undefined) },
sleep: async () => undefined,
zipStream: recordedZipStream().deps,
}
const walk = createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Stopped' },
{ deps, signal: controller.signal }
)
const expectation = expect(walk).rejects.toMatchObject({ name: 'AbortError' })
controller.abort()
await expectation
expect(listChildren).not.toHaveBeenCalled()
})
it('stops during a hung download instead of waiting out the request (M3)', async () => {
const controller = new AbortController()
const deps = depsFor(
{
root: [
{
items: [folder({ resourceId: 'hung', name: 'hung.txt' })],
nextCursor: null,
},
],
},
{ 'gfs://main/hung': () => new Promise<{ bytes: number }>(() => undefined) }
)
const walk = createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Stopped' },
{ deps, signal: controller.signal }
)
const expectation = expect(walk).rejects.toMatchObject({ name: 'AbortError' })
controller.abort()
await expectation
})
it('stops during the RETRIED listing, not only its first attempt (review L3)', async () => {
const controller = new AbortController()
let attempts = 0
const deps: GfsFolderZipDeps = {
listChildren: vi.fn(() => {
attempts += 1
if (attempts === 1)
return Promise.reject(new Error('429 httpStatus=429 retryAfterSeconds=0'))
// The retried listing hangs: without the abort race on the retry the
// walk would park here forever and a Stop could never land.
return new Promise<GfsZipChildrenPage>(() => undefined)
}),
throttle: { acquire: async () => undefined },
sleep: async () => undefined,
zipStream: recordedZipStream().deps,
}
const walk = createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Stopped' },
{ deps, signal: controller.signal }
)
const expectation = expect(walk).rejects.toMatchObject({ name: 'AbortError' })
// Let the first attempt reject, the backoff elapse and the retry fire
// (each await in the retry chain is its own microtask tick).
for (let index = 0; index < 200 && attempts < 2; index += 1) await Promise.resolve()
expect(attempts).toBe(2)
controller.abort()
await expectation
})
it('aborts on a non-permission download failure instead of a holey archive', async () => {
const deps = depsFor(
{
root: [
{
items: [folder({ resourceId: 'flaky', name: 'flaky.txt' })],
nextCursor: null,
},
],
},
{
'gfs://main/flaky': async () => {
throw new Error('gfs download failed: 500 httpStatus=500')
},
}
)
await expect(
createGfsFolderZip({ resourceId: 'root', drive: 'main', name: 'Broken' }, { deps })
).rejects.toThrow(/500/)
})
it('sanitizes hostile names into safe in-archive paths', async () => {
const deps = depsFor({
root: [
{
items: [
// Traversal needs separators — only exact `.`/`..` segments drop,
// so a leading-dot filename keeps its name (L5).
folder({ resourceId: 'n1', name: '../escape.txt' }),
folder({ resourceId: 'n2', name: 'a/b.txt' }),
folder({ resourceId: 'n3', name: '' }),
folder({ resourceId: 'n4', name: '.env' }),
// Windows-forbidden characters and trailing dots map away (L6).
folder({ resourceId: 'n5', name: 're:port*?"<>|.txt' }),
folder({ resourceId: 'n6', name: 'ends...' }),
folder({ resourceId: 'n7', name: '.' }),
folder({ resourceId: 'n8', name: '..' }),
],
nextCursor: null,
},
],
})
const result = await createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Weird/Name:' },
{ deps }
)
expect(streamEntryNames(deps.zipStreamRecord).sort()).toEqual(
[
'Weird_Name_/.._escape.txt',
'Weird_Name_/a_b.txt',
'Weird_Name_/unnamed',
'Weird_Name_/.env',
'Weird_Name_/re_port______.txt',
'Weird_Name_/ends',
'Weird_Name_/unnamed (2)',
'Weird_Name_/unnamed (3)',
].sort()
)
expect(result.fileName).toBe('Weird_Name_.zip')
})
it('escapes Windows device names so the archive extracts on Windows', async () => {
// `CON`, `NUL` and `COM1` are the console device on Windows: an entry
// with that name either fails to extract or writes to the device.
const deps = depsFor({
root: [
{
items: [
folder({ resourceId: 'd1', name: 'CON' }),
folder({ resourceId: 'd2', name: 'nul.txt' }),
folder({ resourceId: 'd3', name: 'COM1' }),
folder({ resourceId: 'd4', name: 'ordinary.txt' }),
],
nextCursor: null,
},
],
})
const result = await createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Devices' },
{ deps }
)
const names = streamEntryNames(deps.zipStreamRecord)
expect(names.sort()).toEqual(
['Devices/_COM1', 'Devices/_CON', 'Devices/_nul.txt', 'Devices/ordinary.txt'].sort()
)
// The SAVED archive's own name is escaped too: `CON.zip` is the device.
expect(result.fileName).toBe('Devices.zip')
})
it('resolves a case-insensitive file/directory conflict (R3-M5)', async () => {
// `Report/child.txt` and a sibling FILE named `report` conflict at a path
// COMPONENT on a case-insensitive filesystem, even though their full
// names differ.
const deps = depsFor({
root: [
{
items: [
folder({ resourceId: 'dir', name: 'Report', kind: 'directory' }),
folder({ resourceId: 'file', name: 'report' }),
],
nextCursor: null,
},
],
dir: [{ items: [folder({ resourceId: 'child', name: 'child.txt' })], nextCursor: null }],
})
const result = await createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Root' },
{ deps }
)
const names = streamEntryNames(deps.zipStreamRecord)
expect(names).toHaveLength(2)
// The sibling file was renamed away from the directory's name.
expect(names).toContain('Root/Report/child.txt')
expect(names).toContain('Root/report (2)')
expect(result.skipped).toEqual([])
})
it('caps entry-name length so the 16-bit ZIP name fields cannot truncate (L4)', async () => {
// 70 000 ASCII bytes would overflow ZIP's uint16 name length and corrupt
// the archive; the segment must be cut under the documented ceiling.
const overlong = `${'a'.repeat(70_000)}.txt`
const deps = depsFor({
root: [
{
items: [folder({ resourceId: 'huge', name: overlong })],
nextCursor: null,
},
],
})
const result = await createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Long' },
{ deps }
)
expect(result.fileCount).toBe(1)
const names = streamEntryNames(deps.zipStreamRecord)
expect(names).toHaveLength(1)
const written = names[0]!
// 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)
// Truncation keeps whole code points: a multi-byte character near the cut
// is never split.
const emojiDeps = depsFor({
root: [
{
items: [folder({ resourceId: 'emoji', name: `${'\u{1F600}'.repeat(600)}x` })],
nextCursor: null,
},
],
})
const emojiResult = await createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Emoji' },
{ deps: emojiDeps }
)
expect(emojiResult.fileCount).toBe(1)
const emojiName = streamEntryNames(emojiDeps.zipStreamRecord)[0]!
expect(emojiName.endsWith('\uFFFD')).toBe(false)
expect(new TextEncoder().encode(emojiName.slice('Emoji/'.length)).length).toBeLessThanOrEqual(
1024
)
})
it('treats a missing byte count as zero instead of NaN-poisoning the size guard (M1)', async () => {
const deps = depsFor({
root: [
{
items: [
folder({
resourceId: 'unknown',
name: 'unknown.bin',
bytes: undefined as unknown as number,
}),
folder({ resourceId: 'small', name: 'small.bin', bytes: 512 }),
],
nextCursor: null,
},
],
})
const result = await createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Legacy' },
// 1 KiB ceiling: NaN accumulation would disable the guard; 0 + 512 must
// still leave room, and a real overage must still refuse.
{ deps, limits: { maxTotalBytes: 1024 } }
)
expect(result.fileCount).toBe(2)
const overDeps = depsFor({
root: [
{
items: [
folder({
resourceId: 'unknown',
name: 'unknown.bin',
bytes: undefined as unknown as number,
}),
folder({ resourceId: 'big', name: 'big.bin', bytes: 2048 }),
],
nextCursor: null,
},
],
})
await expect(
createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Legacy' },
{ deps: overDeps, limits: { maxTotalBytes: 1024 } }
)
).rejects.toThrow(/exceeds the 1 KiB folder-zip limit/)
})
it('re-enters the throttle budget after a 429 backoff before retrying (L1)', async () => {
let attempts = 0
const acquire = vi.fn(async () => undefined)
const deps: GfsFolderZipDeps = {
listChildren: vi.fn(async () => {
attempts += 1
if (attempts === 1) throw new Error('429 httpStatus=429 retryAfterSeconds=0')
return { items: [], nextCursor: null }
}),
throttle: { acquire },
sleep: async () => undefined,
zipStream: recordedZipStream().deps,
}
// An empty retry answer short-circuits as "no downloadable files"; the
// witness here is the budget: initial acquire + one post-backoff acquire.
await expect(
createGfsFolderZip({ resourceId: 'root', drive: 'main', name: 'Throttled' }, { deps })
).rejects.toThrow(/no downloadable files/)
expect(attempts).toBe(2)
expect(acquire).toHaveBeenCalledTimes(2)
})
it('refuses to save an empty archive and reports skips (L8)', async () => {
const emptyDeps = depsFor({ root: [{ items: [], nextCursor: null }] })
await expect(
createGfsFolderZip({ resourceId: 'root', drive: 'main', name: 'Empty' }, { deps: emptyDeps })
).rejects.toMatchObject({
name: 'GfsFolderZipEmptyError',
message: '"Empty" has no downloadable files.',
})
const allSkipped = depsFor({
root: [
{
items: [folder({ resourceId: 'hidden', name: 'hidden.txt', readable: false })],
nextCursor: null,
},
],
})
const failure = await createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Mixed' },
{ deps: allSkipped }
).catch(error => error)
expect(failure).toBeInstanceOf(GfsFolderZipEmptyError)
expect((failure as GfsFolderZipEmptyError).skipped).toEqual([
{ path: 'Mixed/hidden.txt', reason: 'No access' },
])
})
})