From 9c72829c4fda679e3ee279ba3a8c3a13a0f6ea68 Mon Sep 17 00:00:00 2001 From: Alan Grainger <16197738+alangrainger@users.noreply.github.com> Date: Fri, 4 Sep 2026 11:20:45 +1200 Subject: [PATCH] #289 stream downloads rather than staging to temp disk --- app/config.json | 1 - app/src/index.ts | 9 +- app/src/stream/download.ts | 327 +++++++++++------------- app/tests/downloadAbort.test.ts | 192 -------------- app/tests/downloadAssets.test.ts | 276 ++++++++++++++++++++ app/tests/sweepStaleStagingDirs.test.ts | 63 ----- docs/config/ipp-options.md | 6 - 7 files changed, 428 insertions(+), 446 deletions(-) delete mode 100644 app/tests/downloadAbort.test.ts create mode 100644 app/tests/downloadAssets.test.ts delete mode 100644 app/tests/sweepStaleStagingDirs.test.ts diff --git a/app/config.json b/app/config.json index 86d6464..242b11e 100644 --- a/app/config.json +++ b/app/config.json @@ -8,7 +8,6 @@ "maxZoomQuality": "preview", "downloadedFilename": 0, "allowDownload": 0, - "downloadFromImmichConcurrencyLimit": 20, "allowSlugLinks": true, "showHomePage": true, "showMetadata": { diff --git a/app/src/index.ts b/app/src/index.ts index 7805638..f342f67 100644 --- a/app/src/index.ts +++ b/app/src/index.ts @@ -16,7 +16,7 @@ import { import { buildAssetMetadata } from './gallery/metadata' import crypto from 'crypto' import { assetBuffer } from './stream/asset' -import { downloadAssets, sweepStaleStagingDirs } from './stream/download' +import { downloadAssets } from './stream/download' import dayjs from 'dayjs' import { NextFunction, Request, Response } from 'express-serve-static-core' import { Asset, AssetType, ImageSize, KeyType, SharedLink } from './types' @@ -342,8 +342,8 @@ process.on('uncaughtException', (err) => { process.exit(1) }) // Log-only: with asyncHandler routing request errors into errorHandler, a -// stray rejection from a background task (version check, staging-dir sweep, -// etc.) is not worth killing every in-flight request for. +// stray rejection from a background task (the version check, etc.) is not +// worth killing every in-flight request for. process.on('unhandledRejection', (reason, promise) => { console.error('Unhandled Rejection at:', promise, 'reason:', reason) }) @@ -361,7 +361,4 @@ const server = app.listen(port, () => { // than silently serving broken album shares. Unknown/unreachable is // tolerated (logs a warning and continues) - see enforceMinimumImmichVersion. enforceMinimumImmichVersion().catch(e => console.error('Immich version check failed:', e)) - // Clean up any zip-download staging dirs left behind by a previous - // run that crashed before its finally block could run - sweepStaleStagingDirs().catch(e => console.error('sweepStaleStagingDirs failed:', e)) }) diff --git a/app/src/stream/download.ts b/app/src/stream/download.ts index ce2535f..edc35f3 100644 --- a/app/src/stream/download.ts +++ b/app/src/stream/download.ts @@ -1,22 +1,19 @@ import { assetFetchUrl, authHeadersForAsset } from '../immich' import { Response } from 'express-serve-static-core' import { Asset, SharedLink } from '../types' -import { getNumericConfigOption } from '../config/access' import { log } from '../utils/log' import archiver, { Archiver } from 'archiver' import { sanitize } from '../utils/sanitize' -import { pipeline } from 'stream/promises' -import { promises as fs, createWriteStream } from 'fs' -import { tmpdir } from 'os' -import { join } from 'path' import { resolveDownloadEndpoint, ImageEndpoint } from '../gallery/sizing' import { title } from '../share' import { getFilename } from '../gallery/filename' -import { createLimiter } from '../utils/limiter' -import { createIdleTimeoutStream } from '../utils/idleTimeoutStream' import { readableFromWeb } from '../utils/webStream' +import { respondToInvalidRequest } from '../invalidRequestHandler' -const STAGING_DIR_PREFIX = 'ipp-zip-' +/** Attempts to get response headers from Immich for one asset before giving up. */ +const MAX_ATTEMPTS = 3 +/** How long to wait for Immich's response headers on each attempt. */ +const HEADER_TIMEOUT_MS = 20_000 /** * Download all assets in a share as a zip file. @@ -25,173 +22,171 @@ export async function downloadAll (res: Response, share: SharedLink) { await downloadAssets(res, share, share.assets) } -/** - * Delete staging directories left over from a prior run that crashed before - * its `finally` block could clean up. Intended to run once at startup. - * - * A live download holds its staging dir open for the duration of the zip; - * `maxAgeMs` should comfortably exceed any realistic download time so we - * never delete a dir from a still-running download in another worker. - */ -export async function sweepStaleStagingDirs (maxAgeMs = 60 * 60 * 1000) { - const root = tmpdir() - const cutoff = Date.now() - maxAgeMs - const entries = await fs.readdir(root).catch(() => [] as string[]) - for (const name of entries) { - if (!name.startsWith(STAGING_DIR_PREFIX)) continue - const path = join(root, name) - const stat = await fs.stat(path).catch(() => null) - if (!stat || stat.mtimeMs >= cutoff) continue - await fs.rm(path, { recursive: true, force: true }).catch(e => { - log.warn(`Failed to sweep stale staging dir ${path}: ${e instanceof Error ? e.message : String(e)}`) - }) - } -} - -type StagedAsset = { tempfile: string, asset: Asset, endpoint: ImageEndpoint, servedMime?: string } +type FetchedAsset = { response: globalThis.Response, asset: Asset, endpoint: ImageEndpoint, servedMime?: string, url: string } type Failure = { asset: Asset, url: string, status?: number, error?: unknown } -type StageOutcome = StagedAsset | { failure: Failure } | null - -type StagingOptions = { - stagingDir: string - concurrency: number - maxAttempts: number - headerTimeoutMs: number - idleTimeoutMs: number -} +type FetchOutcome = FetchedAsset | { failure: Failure } | null /** * Stream the given assets back as a zip file. * * Immich's own download service (server/src/services/download.service.ts) - * zips files directly from local disk - no HTTP, retries, or timeouts needed. - * We're a proxy fetching over HTTP, so the shape diverges: + * zips files straight off local disk. We're a proxy fetching over HTTP, so + * each asset is fetched from Immich and its body piped directly into the + * archive - nothing is staged to disk or held in memory, so a zip of any + * size needs only a few stream buffers #289. * - * - Bounded concurrency against the upstream Immich server. - * - Two-phase fetch per asset: get headers (retried with linear backoff, - * bounded by a 20s header-receipt timeout), then stream the body to a - * temp file under an idle timeout that resets on every chunk - - * slow-but-steady downloads survive, truly stalled ones fail fast. - * - Stage everything to disk first so we can detect failure BEFORE any - * bytes hit the client. Once we've started streaming the zip we can't - * recover gracefully; aborting means killing the response socket and - * leaving a visibly broken download. This is the alternative to silently - * omitting failed assets - the user gets a clear "broken" signal instead - * of a zip quietly missing files. + * Assets are fetched strictly one at a time. Archiver writes entries + * serially anyway, and an unread response body would hold an idle + * connection open on Immich for as long as the current entry takes to reach + * the visitor - long enough for a reverse proxy to close it. The cost is + * Immich's per-request overhead between entries, which is negligible next + * to the visitor's link speed. * - * The only thing we share with Immich here is using zip STORE (no - * compression), since photos and videos are already compressed. + * Failure handling: + * - Headers fail (after retries) before anything has been sent: an + * ordinary 404, so the visitor sees an error page rather than an empty + * download. The real reason goes to the server log. + * - Anything fails once the zip is on the wire: the socket is destroyed + * and the visitor gets a visibly broken download. That's deliberate; the + * alternative is a zip quietly missing files. + * - Visitor disconnects: the upstream fetch is aborted so Immich stops + * streaming, and the archive is torn down so it releases the in-flight + * entry #284. + * + * There is no body-level idle timeout: with the visitor as the sink, a slow + * or paused client stalls the flow just like a stalled upstream would, so a + * timer on the body can't tell them apart. The header timeout still bounds + * how long Immich may take to start answering. + * + * Zip entries use STORE (no compression), since photos and videos are + * already compressed. */ export async function downloadAssets (res: Response, share: SharedLink, assets: Asset[]) { + const archive = archiver('zip', { store: true }) + // Without a listener, an archiver 'error' emission would crash the process. + archive.on('error', e => log(`Archiver error for share ${share.key}: ${e.message}`)) + + const controller = new AbortController() + let clientGone = false + let resolveClosed!: () => void + const resClosed = new Promise(resolve => { resolveClosed = resolve }) + const onClose = () => { + if (res.writableFinished) return + clientGone = true + controller.abort() + resolveClosed() + } + res.once('close', onClose) + if (res.closed) onClose() + + // Headers and piping are deferred until the first asset has arrived, so a + // failure before then can still be answered with a normal error response. + let piped = false + + for (const asset of assets) { + if (controller.signal.aborted) break + const fetched = await fetchOne(share, asset, controller.signal) + if (fetched === null) break // aborted while waiting on Immich + if ('failure' in fetched) { + if (!piped) { + archive.abort() + respondToInvalidRequest(res, 404, describeFailure(share, fetched.failure)) + return + } + abortDownload(archive, res, share, fetched.failure) + return + } + if (!piped) { + startZipResponse(res, share, archive) + piped = true + } + const entry = await appendEntry(archive, fetched) + if (entry !== 'done') { + if (clientGone) break + controller.abort() + abortDownload(archive, res, share, { asset: fetched.asset, url: fetched.url, error: entry.error }) + return + } + } + + if (clientGone) { + log(`Zip download for share ${share.key} cancelled by client`) + teardownArchive(archive, res) + return + } + if (!piped) startZipResponse(res, share, archive) // empty selection: still a valid (empty) zip + + // finalize() resolves when archiver has finished writing the zip output. + // Raced against client disconnect because finalize() never settles once + // the response is destroyed. The inline rejection handler also stops a + // late finalize failure becoming an unhandled rejection after a lost race. + const finished = archive.finalize().then(() => 'done' as const, () => 'error' as const) + const outcome = await Promise.race([finished, resClosed.then(() => 'closed' as const)]) + if (outcome !== 'done') { + if (outcome === 'closed') log(`Zip download for share ${share.key} cancelled by client`) + // 'error' was already logged by the archiver error listener + teardownArchive(archive, res) + } +} + +function startZipResponse (res: Response, share: SharedLink, archive: Archiver) { res.setHeader('Content-Type', 'application/zip') let filename = (sanitize(title(share)) || 'photos') + '.zip' filename = encodeURI(filename) res.setHeader('Content-Disposition', `attachment; filename*=UTF-8''${filename}`) // Hint to intermediate proxies (Nginx, etc.) not to buffer this response. res.setHeader('X-Accel-Buffering', 'no') - const archive = archiver('zip', { store: true }) - // Without a listener, an archiver 'error' emission would crash the process. - archive.on('error', e => log(`Archiver error for share ${share.key}: ${e.message}`)) archive.pipe(res) +} - const options: StagingOptions = { - stagingDir: await fs.mkdtemp(join(tmpdir(), STAGING_DIR_PREFIX)), - concurrency: Math.max(1, getNumericConfigOption('ipp.downloadFromImmichConcurrencyLimit', 20)), - maxAttempts: 3, - headerTimeoutMs: 20_000, - idleTimeoutMs: 20_000 - } - - const controller = new AbortController() - let clientGone = false - let resolveClosed!: () => void - const resClosed = new Promise(resolve => { resolveClosed = resolve }) - res.once('close', () => { - if (res.writableFinished) return - clientGone = true - controller.abort() - resolveClosed() +/** + * Pipe one fetched body into the archive and wait for the entry to be fully + * written (archiver's 'entry' event fires after the data descriptor, which + * is later than the body's own end). + * + * On a body error compress-commons forwards the error to archiver's 'error' + * event and then moves on to the next queued entry, so the caller must abort + * the download itself. The body listener covers the tick between append() + * and archiver attaching its own handler, when an unhandled 'error' would + * otherwise crash the process. + */ +function appendEntry (archive: Archiver, fetched: FetchedAsset): Promise<'done' | { error: unknown }> { + return new Promise(resolve => { + if (!fetched.response.body) { + resolve({ error: new Error('Upstream response has no body') }) + return + } + const body = readableFromWeb(fetched.response.body) + const cleanup = () => { + archive.off('entry', onEntry) + archive.off('error', onError) + body.off('error', onError) + } + const onEntry = () => { cleanup(); resolve('done') } + const onError = (error: unknown) => { cleanup(); resolve({ error }) } + archive.once('entry', onEntry) + archive.once('error', onError) + body.once('error', onError) + archive.append(body, { name: getFilename(fetched.asset, fetched.endpoint.servedSize, fetched.servedMime) }) }) - - try { - const stages = stageAssetsToDisk(share, assets, options, controller.signal) - const failure = await archiveStaged(archive, stages, controller) - if (clientGone) { - log(`Zip download for share ${share.key} cancelled by client`) - teardownArchive(archive, res) - return - } - if (failure) { - abortDownload(archive, res, share, failure) - return - } - // finalize() resolves when archiver has finished writing the zip output, - // which means every queued tempfile has been read. Safe to delete after. - // Raced against client disconnect because finalize() never settles once - // the response is destroyed. The inline rejection handler also stops a - // late finalize failure becoming an unhandled rejection after a lost race. - const finished = archive.finalize().then(() => 'done' as const, () => 'error' as const) - const outcome = await Promise.race([finished, resClosed.then(() => 'closed' as const)]) - if (outcome !== 'done') { - if (outcome === 'closed') log(`Zip download for share ${share.key} cancelled by client`) - // 'error' was already logged by the archiver error listener - teardownArchive(archive, res) - } - } finally { - await fs.rm(options.stagingDir, { recursive: true, force: true }).catch(() => { /* best effort */ }) - } } -/** - * Kick off staging for every asset at once; the limiter caps how many run - * concurrently. Returns the promise array in input order so the consumer can - * archive in order. - */ -function stageAssetsToDisk (share: SharedLink, assets: Asset[], options: StagingOptions, signal: AbortSignal): Promise[] { - const limit = createLimiter(options.concurrency) - return assets.map((asset, index) => limit(() => stageOne(share, asset, index, options, signal))) -} - -/** - * Walk the staged assets in input order, adding each to the archive as soon - * as it lands. The first failure aborts the download signal (so unstarted - * stages bail out and in-flight fetches are cancelled) and is returned to the - * caller. We wait for in-flight stages to settle before returning so the - * staging dir is safe to delete. - */ -async function archiveStaged (archive: Archiver, stages: Promise[], controller: AbortController): Promise { - let failure: Failure | null = null - for (const stage of stages) { - const result = await stage - if (result === null) break // aborted by an earlier stage - if ('failure' in result) { - controller.abort() - failure = result.failure - break - } - // archive.file queues the entry; archiver lazily opens and reads it. - archive.file(result.tempfile, { name: getFilename(result.asset, result.endpoint.servedSize, result.servedMime) }) - } - - // After abort, wait for any in-flight stages to settle before we delete - // the staging dir. stageOne never rejects (errors become failure objects), - // so a plain Promise.all is safe. - if (controller.signal.aborted) await Promise.all(stages) - return failure -} - -function abortDownload (archive: Archiver, res: Response, share: SharedLink, failure: Failure) { +function describeFailure (share: SharedLink, failure: Failure): string { const detail = failure.status !== undefined ? `HTTP ${failure.status}` : (failure.error instanceof Error ? failure.error.message : String(failure.error)) - log(`Aborting zip download for share ${share.key}: failed to fetch asset ${failure.asset.id} from ${failure.url} (${detail})`) + return `Zip download for share ${share.key}: failed to fetch asset ${failure.asset.id} from ${failure.url} (${detail})` +} + +function abortDownload (archive: Archiver, res: Response, share: SharedLink, failure: Failure) { + log('Aborting ' + describeFailure(share, failure)) teardownArchive(archive, res) } /** * Tear down an aborted archive so it releases its resources. `abort()` alone * is not enough; it kills the queue but leaves any in-flight entry paused, - * holding an open read fd on its tempfile forever #284 + * holding its source stream open forever #284 */ function teardownArchive (archive: Archiver, res: Response) { archive.abort() @@ -201,22 +196,20 @@ function teardownArchive (archive: Archiver, res: Response) { } /** - * Fetch one asset's upstream bytes into a temp file. Two phases: - * 1. fetchHeadersWithRetry - get the response headers, retried on - * transient failure. - * 2. streamBodyToTempFile - drain the body to disk under an idle timeout. + * Fetch one asset's response headers from Immich, retried on transient + * failure. The body is left unread for the caller to pipe. * - * Returns the staged asset on success, a wrapped Failure on error, or null - * if we observed the abort flag and bailed without doing work. + * Returns the fetched asset on success, a wrapped Failure on error, or null + * if the download was aborted before we got an answer. */ -async function stageOne (share: SharedLink, asset: Asset, index: number, options: StagingOptions, signal: AbortSignal): Promise { +async function fetchOne (share: SharedLink, asset: Asset, signal: AbortSignal): Promise { if (signal.aborted) return null const endpoint = resolveDownloadEndpoint(asset, share.allowDownload !== false) const url = assetFetchUrl(asset, endpoint.subpath, endpoint.sizeQueryParam) const reqAuthHeaders = await authHeadersForAsset(asset) - const fetched = await fetchHeadersWithRetry(url, reqAuthHeaders, options.maxAttempts, options.headerTimeoutMs, signal, asset) + const fetched = await fetchHeadersWithRetry(url, reqAuthHeaders, MAX_ATTEMPTS, HEADER_TIMEOUT_MS, signal, asset) if (fetched === null) return null if ('failure' in fetched) return { failure: { ...fetched.failure, asset, url } } @@ -224,7 +217,7 @@ async function stageOne (share: SharedLink, asset: Asset, index: number, options // getFilename would fall back to an id-based name. The `/original` response // carries the real name in Content-Disposition and the mime in Content-Type, // so recover them from the headers we already fetched - no extra calls. - const stagedAsset = asset.originalFileName ? asset : enrichFromHeaders(asset, fetched.response) + const namedAsset = asset.originalFileName ? asset : enrichFromHeaders(asset, fetched.response) // Playback-fallback downloads serve Immich's transcode; carry the response // content-type so the zip entry's extension matches the actual bytes. @@ -232,12 +225,7 @@ async function stageOne (share: SharedLink, asset: Asset, index: number, options ? (fetched.response.headers.get('content-type') || '').split(';')[0].trim() || undefined : undefined - // Use the array index in the path so we never collide on duplicate IDs. - const tempfile = join(options.stagingDir, `${index}-${asset.id}`) - const streamed = await streamBodyToTempFile(fetched.response, tempfile, options.idleTimeoutMs) - if ('failure' in streamed) return { failure: { asset, url, error: streamed.failure } } - - return { tempfile, asset: stagedAsset, endpoint, servedMime } + return { response: fetched.response, asset: namedAsset, endpoint, servedMime, url } } /** @@ -290,8 +278,7 @@ type HeaderFetchOutcome = * because the signal we pass to fetch stays bound to the response body - if * the timeout fires after headers arrive but while the body is still * streaming, the body read errors out. We clear the header timer as soon - * as we have a response; downstream the idle-timeout transform guards - * against stalled bodies. + * as we have a response. * * The download-wide `signal` is combined into the fetch signal so that an * aborted download (asset failure or client disconnect) cancels the header @@ -333,19 +320,3 @@ async function fetchHeadersWithRetry ( } return { failure: { status: lastStatus, error: lastError } } } - -/** - * Stream `response.body` to `tempfile`, guarded by an idle timeout. The - * idle stream destroys itself if no chunk arrives within `idleMs`, killing - * the pipeline with a clear error. - */ -async function streamBodyToTempFile (response: globalThis.Response, tempfile: string, idleMs: number): Promise<{ ok: true } | { failure: unknown }> { - if (!response.body) return { failure: new Error('Upstream response has no body') } - const body = readableFromWeb(response.body) - try { - await pipeline(body, createIdleTimeoutStream(idleMs), createWriteStream(tempfile)) - return { ok: true } - } catch (e) { - return { failure: e } - } -} diff --git a/app/tests/downloadAbort.test.ts b/app/tests/downloadAbort.test.ts deleted file mode 100644 index 55182c4..0000000 --- a/app/tests/downloadAbort.test.ts +++ /dev/null @@ -1,192 +0,0 @@ -import { describe, it, expect, vi, beforeAll, afterAll, afterEach } from 'vitest' -import { promises as fs } from 'fs' -import { Writable } from 'stream' -import type { Response } from 'express-serve-static-core' -import { downloadAssets } from '../src/stream/download' -import { Asset, AssetType, KeyType, SharedLink } from '../src/types' - -/* -Isolate this suite's staging dirs in a dedicated tmp dir so the -before/after assertions can't race other test files that also create -ipp-zip-* dirs under the real os.tmpdir(). -*/ -const { TEST_TMP } = vi.hoisted(() => { - return { TEST_TMP: (process.env.TMPDIR || '/tmp') + '/ipp-download-abort-test-' + process.pid } -}) -vi.mock('os', async importOriginal => { - const orig = await importOriginal() - return { ...orig, tmpdir: () => TEST_TMP } -}) - -beforeAll(async () => { - await fs.mkdir(TEST_TMP, { recursive: true }) -}) - -afterAll(async () => { - await fs.rm(TEST_TMP, { recursive: true, force: true }) -}) - -afterEach(() => { - vi.unstubAllGlobals() -}) - -async function stagingDirs (): Promise { - const entries = await fs.readdir(TEST_TMP).catch(() => [] as string[]) - return entries.filter(name => name.startsWith('ipp-zip-')) -} - -/** - * Open fds pointing at deleted staging tempfiles. An aborted archiver used to - * keep the in-flight entry's read stream open forever; on tmpfs that pins the - * deleted file's space (issue #284). Linux-only introspection - returns [] - * elsewhere, making the assertions no-ops. - */ -async function deletedStagingFds (): Promise { - const fds = await fs.readdir('/proc/self/fd').catch(() => [] as string[]) - const leaked: string[] = [] - for (const fd of fds) { - const target = await fs.readlink('/proc/self/fd/' + fd).catch(() => '') - if (target.includes('ipp-zip-') && target.includes('(deleted)')) leaked.push(target) - } - return leaked -} - -/** Wait for archiver's post-abort drain to release fds, then return leftovers. */ -async function settledDeletedStagingFds (timeoutMs = 3000): Promise { - const deadline = Date.now() + timeoutMs - let leaked = await deletedStagingFds() - while (leaked.length > 0 && Date.now() < deadline) { - await new Promise(resolve => setTimeout(resolve, 100)) - leaked = await deletedStagingFds() - } - return leaked -} - -function makeAsset (id: string): Asset { - return { - id, - key: 'testkey', - keyType: KeyType.key, - type: AssetType.image, - isTrashed: false, - originalFileName: id + '.jpg', - originalMimeType: 'image/jpeg' - } -} - -const share: SharedLink = { - key: 'testkey', - keyType: KeyType.key, - type: 'ALBUM', - description: 'Test album', - assets: [] -} - -/* -Minimal stand-in for the Express response: a real Writable (so 'close', -writableFinished and destroy behave like the real thing) plus the header -setters downloadAssets calls. -*/ -class FakeRes extends Writable { - received = 0 - - constructor () { - super() - // Node's http stack handles response stream errors internally; a bare - // Writable would crash the test process on destroy(err) instead. - this.on('error', () => { /* swallowed, like http.ServerResponse */ }) - } - - setHeader (_name: string, _value: string) { return this } - - _write (chunk: Buffer, _enc: string, cb: (error?: Error | null) => void) { - this.received += chunk.length - cb() - } -} - -function asResponse (res: FakeRes): Response { - return res as unknown as Response -} - -/** Fetch stub that returns the full body immediately. */ -function instantFetch (bytes: number) { - return vi.fn(async () => new globalThis.Response(new Uint8Array(bytes), { status: 200 })) -} - -/** - * Fetch stub whose body sends one chunk then stays open forever, erroring - * only when the passed-in signal aborts - like a real streaming download - * that gets cancelled. Records each request's signal for assertions. - */ -function trickleFetch (signals: AbortSignal[]) { - return vi.fn(async (_url: unknown, init?: RequestInit) => { - const signal = init?.signal as AbortSignal - signals.push(signal) - const stream = new ReadableStream({ - start (controller) { - controller.enqueue(new Uint8Array(1024)) - signal.addEventListener('abort', () => { - try { controller.error(signal.reason ?? new Error('aborted')) } catch { /* already errored */ } - }) - } - }) - return new globalThis.Response(stream, { status: 200 }) - }) -} - -describe('downloadAssets abort handling', () => { - it('streams a zip and cleans up the staging dir on the happy path', async () => { - vi.stubGlobal('fetch', instantFetch(2048)) - const res = new FakeRes() - await downloadAssets(asResponse(res), share, [makeAsset('a1'), makeAsset('a2')]) - expect(res.received).toBeGreaterThan(0) - expect(res.writableFinished).toBe(true) - expect(await stagingDirs()).toEqual([]) - }) - - it('resolves, cleans up and cancels upstream fetches when the client aborts mid-staging', async () => { - const signals: AbortSignal[] = [] - vi.stubGlobal('fetch', trickleFetch(signals)) - const res = new FakeRes() - const done = downloadAssets(asResponse(res), share, [makeAsset('a1'), makeAsset('a2')]) - // Give staging a moment to start, then drop the client connection - await new Promise(resolve => setTimeout(resolve, 50)) - res.destroy(new Error('client aborted')) - await done - expect(signals.length).toBeGreaterThan(0) - expect(signals.every(s => s.aborted)).toBe(true) - expect(await stagingDirs()).toEqual([]) - expect(await settledDeletedStagingFds()).toEqual([]) - }, 10_000) - - it('resolves and cleans up when the client aborts while the zip is streaming', async () => { - // Large enough that archiver can't flush everything into a destroyed - // response; without disconnect handling finalize() would hang forever. - vi.stubGlobal('fetch', instantFetch(5 * 1024 * 1024)) - const res = new FakeRes() - const origWrite = res._write.bind(res) - let first = true - res._write = (chunk, enc, cb) => { - origWrite(chunk, enc, cb) - if (first) { - first = false - setImmediate(() => res.destroy(new Error('client aborted'))) - } - } - await downloadAssets(asResponse(res), share, [makeAsset('a1'), makeAsset('a2')]) - expect(await stagingDirs()).toEqual([]) - // The regression from issue #284's follow-up: the staging dir was removed - // but archiver still held an open fd on a deleted tempfile. - expect(await settledDeletedStagingFds()).toEqual([]) - }, 10_000) - - it('cleans up and destroys the response when an upstream fetch keeps failing', async () => { - vi.stubGlobal('fetch', vi.fn(async () => new globalThis.Response('nope', { status: 500 }))) - const res = new FakeRes() - await downloadAssets(asResponse(res), share, [makeAsset('a1')]) - expect(res.destroyed).toBe(true) - expect(await stagingDirs()).toEqual([]) - expect(await settledDeletedStagingFds()).toEqual([]) - }, 10_000) -}) diff --git a/app/tests/downloadAssets.test.ts b/app/tests/downloadAssets.test.ts new file mode 100644 index 0000000..e7be438 --- /dev/null +++ b/app/tests/downloadAssets.test.ts @@ -0,0 +1,276 @@ +import { describe, it, expect, vi, afterEach } from 'vitest' +import { Writable } from 'stream' +import { once } from 'events' +import type { Response } from 'express-serve-static-core' +import { downloadAssets } from '../src/stream/download' +import { Asset, AssetType, KeyType, SharedLink } from '../src/types' + +/* +"Download all" streams each asset from Immich straight into the zip on the +wire - no disk staging, no buffering of whole files (issue #289). These tests +cover the shape of that pipeline: backpressure, one upstream body at a time, +and the three ways it can end early (visitor leaves, Immich refuses, body +dies mid-stream). +*/ + +afterEach(() => { + vi.unstubAllGlobals() + vi.restoreAllMocks() +}) + +function makeAsset (id: string): Asset { + return { + id, + key: 'testkey', + keyType: KeyType.key, + type: AssetType.image, + isTrashed: false, + originalFileName: id + '.jpg', + originalMimeType: 'image/jpeg' + } +} + +const share: SharedLink = { + key: 'testkey', + keyType: KeyType.key, + type: 'ALBUM', + description: 'Test album', + assets: [] +} + +/* +Minimal stand-in for the Express response: a real Writable (so 'close', +writableFinished and destroy behave like the real thing) plus the header +and status helpers downloadAssets and respondToInvalidRequest call. +*/ +class FakeRes extends Writable { + received = 0 + chunks: Buffer[] = [] + statusCode = 200 + headers: Record = {} + /** Delay applied to every write, to simulate a slow visitor. */ + writeDelayMs = 0 + + constructor () { + super() + // Node's http stack handles response stream errors internally; a bare + // Writable would crash the test process on destroy(err) instead. + this.on('error', () => { /* swallowed, like http.ServerResponse */ }) + } + + setHeader (name: string, value: string) { this.headers[name] = value; return this } + status (code: number) { this.statusCode = code; return this } + send () { this.end(); return this } + + _write (chunk: Buffer, _enc: string, cb: (error?: Error | null) => void) { + this.received += chunk.length + this.chunks.push(chunk) + if (this.writeDelayMs > 0) setTimeout(cb, this.writeDelayMs) + else cb() + } + + get output () { return Buffer.concat(this.chunks) } +} + +function asResponse (res: FakeRes): Response { + return res as unknown as Response +} + +/** Fetch stub that returns the full body immediately. */ +function instantFetch (bytes: number) { + return vi.fn(async () => new globalThis.Response(new Uint8Array(bytes), { status: 200 })) +} + +/** + * Fetch stub whose body sends one chunk then stays open forever, erroring + * only when the passed-in signal aborts - like a real streaming download + * that gets cancelled. Records each request's signal for assertions. + */ +function trickleFetch (signals: AbortSignal[]) { + return vi.fn(async (_url: unknown, init?: RequestInit) => { + const signal = init?.signal as AbortSignal + signals.push(signal) + const stream = new ReadableStream({ + start (controller) { + controller.enqueue(new Uint8Array(1024)) + signal.addEventListener('abort', () => { + try { controller.error(signal.reason ?? new Error('aborted')) } catch { /* already errored */ } + }) + } + }) + return new globalThis.Response(stream, { status: 200 }) + }) +} + +/** + * Fetch stub with a pull-based body: chunks are only produced on demand, and + * `pulled` counts how many bytes have been handed over so far. + */ +function pullFetch (totalBytes: number, chunkBytes: number, counter: { pulled: number }) { + return vi.fn(async () => { + let sent = 0 + const stream = new ReadableStream({ + pull (controller) { + if (sent >= totalBytes) { + controller.close() + return + } + const size = Math.min(chunkBytes, totalBytes - sent) + controller.enqueue(new Uint8Array(size)) + sent += size + counter.pulled = sent + } + }) + return new globalThis.Response(stream, { status: 200 }) + }) +} + +/** + * Parse the central directory of a zip buffer: one {name, size} per entry. + * Just enough of the format to check the output is a real zip with the + * expected entries; extractors read the central directory, so it's the part + * that matters. + */ +function centralDirectory (zip: Buffer): Array<{ name: string, size: number }> { + const entries: Array<{ name: string, size: number }> = [] + let offset = zip.indexOf('PK\x01\x02', 0, 'binary') + while (offset !== -1) { + const size = zip.readUInt32LE(offset + 24) + const nameLength = zip.readUInt16LE(offset + 28) + const name = zip.subarray(offset + 46, offset + 46 + nameLength).toString('utf8') + entries.push({ name, size }) + offset = zip.indexOf('PK\x01\x02', offset + 46 + nameLength, 'binary') + } + return entries +} + +function countOf (zip: Buffer, signature: string): number { + let count = 0 + let offset = zip.indexOf(signature, 0, 'binary') + while (offset !== -1) { + count++ + offset = zip.indexOf(signature, offset + 1, 'binary') + } + return count +} + +describe('downloadAssets', () => { + it('streams a valid zip with one entry per asset', async () => { + vi.stubGlobal('fetch', instantFetch(2048)) + const res = new FakeRes() + await downloadAssets(asResponse(res), share, [makeAsset('a1'), makeAsset('a2')]) + expect(res.writableFinished).toBe(true) + expect(res.headers['Content-Type']).toBe('application/zip') + const zip = res.output + expect(countOf(zip, 'PK\x03\x04')).toBe(2) // local file headers + expect(countOf(zip, 'PK\x05\x06')).toBe(1) // end of central directory + expect(centralDirectory(zip)).toEqual([ + { name: 'a1.jpg', size: 2048 }, + { name: 'a2.jpg', size: 2048 } + ]) + }) + + it('honours backpressure from a slow visitor instead of buffering the body', async () => { + const total = 32 * 1024 * 1024 + const counter = { pulled: 0 } + vi.stubGlobal('fetch', pullFetch(total, 64 * 1024, counter)) + const res = new FakeRes() + res.writeDelayMs = 1 + let worstLead = 0 + const origWrite = res._write.bind(res) + res._write = (chunk, enc, cb) => { + worstLead = Math.max(worstLead, counter.pulled - res.received) + origWrite(chunk, enc, cb) + } + await downloadAssets(asResponse(res), share, [makeAsset('a1')]) + if (!res.writableFinished) await once(res, 'finish') + expect(counter.pulled).toBe(total) + // The lead is bounded by the stream buffers between the fetch body and + // the response: archiver and zip-stream each hold up to 1 MB per side, + // so roughly 4 MB in total. Without backpressure it would approach the + // whole 32 MB. + expect(worstLead).toBeLessThan(8 * 1024 * 1024) + }, 20_000) + + it('fetches one asset at a time and cancels the upstream fetch when the client aborts mid-body', async () => { + const signals: AbortSignal[] = [] + const fetchMock = trickleFetch(signals) + vi.stubGlobal('fetch', fetchMock) + const res = new FakeRes() + const done = downloadAssets(asResponse(res), share, [makeAsset('a1'), makeAsset('a2'), makeAsset('a3')]) + // Give the first body a moment to start; nothing else should be in flight + await new Promise(resolve => setTimeout(resolve, 50)) + expect(fetchMock).toHaveBeenCalledTimes(1) + res.destroy(new Error('client aborted')) + await done + expect(fetchMock).toHaveBeenCalledTimes(1) + expect(signals.every(s => s.aborted)).toBe(true) + }, 10_000) + + it('resolves when the client aborts while the zip is streaming', async () => { + // Large enough that archiver can't flush everything into a destroyed + // response; without disconnect handling finalize() would hang forever. + vi.stubGlobal('fetch', instantFetch(5 * 1024 * 1024)) + const res = new FakeRes() + const origWrite = res._write.bind(res) + let first = true + res._write = (chunk, enc, cb) => { + origWrite(chunk, enc, cb) + if (first) { + first = false + setImmediate(() => res.destroy(new Error('client aborted'))) + } + } + await downloadAssets(asResponse(res), share, [makeAsset('a1'), makeAsset('a2')]) + expect(res.destroyed).toBe(true) + }, 10_000) + + it('answers 404 (not a broken zip) when the first asset fails before anything is sent', async () => { + vi.spyOn(console, 'log').mockImplementation(() => {}) + vi.stubGlobal('fetch', vi.fn(async () => new globalThis.Response('nope', { status: 500 }))) + const res = new FakeRes() + await downloadAssets(asResponse(res), share, [makeAsset('a1'), makeAsset('a2')]) + expect(res.statusCode).toBe(404) + expect(res.destroyed).toBe(false) + expect(res.writableEnded).toBe(true) + expect(res.received).toBe(0) + expect(res.headers['Content-Type']).toBeUndefined() + }, 10_000) + + it('destroys the response when a later asset keeps failing', async () => { + vi.spyOn(console, 'log').mockImplementation(() => {}) + let calls = 0 + vi.stubGlobal('fetch', vi.fn(async () => { + calls++ + return calls === 1 + ? new globalThis.Response(new Uint8Array(2048), { status: 200 }) + : new globalThis.Response('nope', { status: 500 }) + })) + const res = new FakeRes() + await downloadAssets(asResponse(res), share, [makeAsset('a1'), makeAsset('a2')]) + expect(res.received).toBeGreaterThan(0) + expect(res.destroyed).toBe(true) + expect(res.writableFinished).toBe(false) + }, 10_000) + + it('destroys the response and stops fetching when a body errors mid-stream', async () => { + vi.spyOn(console, 'log').mockImplementation(() => {}) + const signals: AbortSignal[] = [] + const fetchMock = vi.fn(async (_url: unknown, init?: RequestInit) => { + signals.push(init?.signal as AbortSignal) + const stream = new ReadableStream({ + start (controller) { + controller.enqueue(new Uint8Array(1024)) + setTimeout(() => controller.error(new Error('upstream died')), 20) + } + }) + return new globalThis.Response(stream, { status: 200 }) + }) + vi.stubGlobal('fetch', fetchMock) + const res = new FakeRes() + await downloadAssets(asResponse(res), share, [makeAsset('a1'), makeAsset('a2'), makeAsset('a3')]) + expect(res.destroyed).toBe(true) + expect(fetchMock).toHaveBeenCalledTimes(1) + expect(signals.every(s => s.aborted)).toBe(true) + }, 10_000) +}) diff --git a/app/tests/sweepStaleStagingDirs.test.ts b/app/tests/sweepStaleStagingDirs.test.ts deleted file mode 100644 index 4d3311f..0000000 --- a/app/tests/sweepStaleStagingDirs.test.ts +++ /dev/null @@ -1,63 +0,0 @@ -import { describe, it, expect, afterEach } from 'vitest' -import { promises as fs } from 'fs' -import { tmpdir } from 'os' -import { join } from 'path' -import { sweepStaleStagingDirs } from '../src/stream/download' - -const PREFIX = 'ipp-zip-' - -async function makeDir (name: string, mtimeMsAgo: number) { - const path = join(tmpdir(), name) - await fs.mkdir(path, { recursive: true }) - await fs.writeFile(join(path, 'inside.bin'), 'x') - const mtime = new Date(Date.now() - mtimeMsAgo) - await fs.utimes(path, mtime, mtime) - return path -} - -async function exists (path: string) { - try { - await fs.access(path) - return true - } catch { - return false - } -} - -const created: string[] = [] - -afterEach(async () => { - await Promise.all(created.splice(0).map(p => fs.rm(p, { recursive: true, force: true }).catch(() => { /* best effort */ }))) -}) - -describe('sweepStaleStagingDirs', () => { - it('deletes stale staging dirs older than the cutoff', async () => { - const stale = await makeDir(PREFIX + 'stale-' + process.pid + '-' + Math.random().toString(36).slice(2), 2 * 60 * 60 * 1000) - created.push(stale) - await sweepStaleStagingDirs(60 * 60 * 1000) - expect(await exists(stale)).toBe(false) - }) - - it('preserves staging dirs younger than the cutoff', async () => { - const fresh = await makeDir(PREFIX + 'fresh-' + process.pid + '-' + Math.random().toString(36).slice(2), 10 * 60 * 1000) - created.push(fresh) - await sweepStaleStagingDirs(60 * 60 * 1000) - expect(await exists(fresh)).toBe(true) - }) - - it('ignores directories that do not match the staging prefix', async () => { - const unrelated = await makeDir('not-ipp-zip-' + process.pid + '-' + Math.random().toString(36).slice(2), 24 * 60 * 60 * 1000) - created.push(unrelated) - await sweepStaleStagingDirs(60 * 60 * 1000) - expect(await exists(unrelated)).toBe(true) - }) - - it('uses its default 1h cutoff when called with no argument', async () => { - const stale = await makeDir(PREFIX + 'default-' + process.pid + '-' + Math.random().toString(36).slice(2), 2 * 60 * 60 * 1000) - const fresh = await makeDir(PREFIX + 'default2-' + process.pid + '-' + Math.random().toString(36).slice(2), 30 * 60 * 1000) - created.push(stale, fresh) - await sweepStaleStagingDirs() - expect(await exists(stale)).toBe(false) - expect(await exists(fresh)).toBe(true) - }) -}) diff --git a/docs/config/ipp-options.md b/docs/config/ipp-options.md index d9fefe8..980d6e0 100644 --- a/docs/config/ipp-options.md +++ b/docs/config/ipp-options.md @@ -75,12 +75,6 @@ The bulk-zip and per-asset buttons can be toggled independently once downloads a > > To guarantee full-quality downloads of everything, leave the share's download permission on in Immich. -## `downloadFromImmichConcurrencyLimit` - -**Type:** `int` ยท **Default:** `20` - -Maximum number of assets IPP will fetch from your Immich server in parallel when building a "download all" zip. Lower this if your Immich server is slow or you see download timeouts on large albums; raise it for faster downloads if your server can handle the load. - ## `allowSlugLinks` **Type:** `bool`