From 3701d4e92c6e580afd337ac45efbc9d12b70c5c1 Mon Sep 17 00:00:00 2001 From: Alan Grainger <16197738+alangrainger@users.noreply.github.com> Date: Fri, 4 Sep 2026 23:27:28 +1200 Subject: [PATCH] Add no-store cache header for zip downloads --- app/src/stream/download.ts | 1 + app/tests/downloadAssets.test.ts | 3 +++ docs/config/ipp-options.md | 4 +++- docs/installation.md | 5 +++-- docs/troubleshooting.md | 10 ++++++++++ 5 files changed, 20 insertions(+), 3 deletions(-) diff --git a/app/src/stream/download.ts b/app/src/stream/download.ts index edc35f3..09f7591 100644 --- a/app/src/stream/download.ts +++ b/app/src/stream/download.ts @@ -136,6 +136,7 @@ function startZipResponse (res: Response, share: SharedLink, archive: Archiver) 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') + res.setHeader('Cache-Control', 'no-store') archive.pipe(res) } diff --git a/app/tests/downloadAssets.test.ts b/app/tests/downloadAssets.test.ts index e7be438..de4122e 100644 --- a/app/tests/downloadAssets.test.ts +++ b/app/tests/downloadAssets.test.ts @@ -161,6 +161,9 @@ describe('downloadAssets', () => { await downloadAssets(asResponse(res), share, [makeAsset('a1'), makeAsset('a2')]) expect(res.writableFinished).toBe(true) expect(res.headers['Content-Type']).toBe('application/zip') + // A CDN must never store the zip; Cloudflare's cache fill aborts large + // downloads partway through otherwise #94 + expect(res.headers['Cache-Control']).toBe('no-store') 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 diff --git a/docs/config/ipp-options.md b/docs/config/ipp-options.md index af984b3..8e19ef8 100644 --- a/docs/config/ipp-options.md +++ b/docs/config/ipp-options.md @@ -19,7 +19,9 @@ Serve full-resolution images both when zooming in the lightbox and when download **Type:** `object` -Change the headers sent with your web responses. The default is a 30-day `Cache-Control` and a permissive CORS header: +Change the headers sent with your web responses. The default is a 30-day `Cache-Control` and a permissive CORS header. +These apply to photos, videos and static files. The "download all" zip is always sent with `Cache-Control: no-store` +to prevent CDN issues, and the gallery page uses its own [`gallery.cacheTime`](/config/gallery#cachetime). ```json { diff --git a/docs/installation.md b/docs/installation.md index fb2d98a..fc6d36c 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -31,8 +31,9 @@ Now whenever you share an image or gallery through Immich, it will automatically you. > [!WARNING] -> If you're using Cloudflare, please make sure to set your `/share/video/*` path to Bypass Cache, otherwise you may -> run into video playback issues. See [Troubleshooting](/troubleshooting) for more information. +> If you're using Cloudflare, please make sure to set your `/share/video/*` and `/share/*/download` paths to Bypass +> Cache, otherwise you may run into video playback issues and failed zip downloads. See +> [Troubleshooting](/troubleshooting) for more information. Those two variables are all most people need. The port and the config file location are covered under [Environment variables](/config/environment-variables), and everything about how galleries look and behave under diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 5d5e3cb..9369eef 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -8,6 +8,16 @@ set to bypass cache. I ran into this issue myself, and found Cloudflare cache bypass rule for video paths +## "Download all" fails partway through + +If you use Cloudflare with a "cache everything" rule and large zip downloads stop with a browser error after a few +seconds, add a cache rule that bypasses cache for `/share/*/download`, the same as for `/share/video/*` above. From +v3.3.0 the zip is streamed as it is fetched from Immich, and Cloudflare's cache cuts those downloads short. + +Versions after v3.3.0 send the zip with `Cache-Control: no-store`, which is enough on its own if your cache rule's Edge +TTL is set to respect the origin. If the rule overrides the Edge TTL, Cloudflare ignores that header and you need the +bypass rule. + I use Linux/Android, so this project is tested with BrowserStack for Apple/Windows devices. ## Link previews show `http://` or a private IP