[Deeds67]

Adds chunked / resumable upload across the server and all four clients, so a large file no longer has to fit in a single HTTP request.

Closes the long-standing gap tracked upstream in immich-1674 (locked since 2024, never implemented; upstream/main still carries no tus or chunked upload code as of today).

Why

Two problems, one cause — every client uploads an asset as a single POST /assets whose body is the whole file:

1. Reverse-proxy body limits. Cloudflare caps request bodies at 100 MB and it cannot be raised. Our own FAQ documents this as a hard wall, and the reverse-proxy guide tells self-hosters to set client_max_body_size 50000M, which is a workaround and is unavailable behind a managed proxy.
2. No resumption. A failure at 95% of a 4 GB video discards 4 GB of transfer.

Design

A tus-shaped subset, hand-rolled inside Nest — POST create-session, HEAD offset, PATCH with application/offset+octet-stream, DELETE abort. Full design in specs/2026-09-08-chunked-upload-design.md.

The two decisions that shape everything else:

• Finalize hands an UploadFile to the existing AssetMediaService.uploadAsset(). Asset creation, dedupe, quota, live-photo linking, shared links and spaces all run the existing code unchanged.
• Session state is a JSON sidecar in the upload folder, and the partial file is the final file. No fork migration, so no revert-to-immich.sql blocks and no guard-spec update; no assembly copy, which matters at multi-gigabyte sizes. Uploads already land on local disk before the S3 backend sees them, so S3 multipart never enters the picture.

Chunks are written positionally, and the committed offset is derived from fs.stat().size rather than stored — so a replayed chunk rewrites identical bytes and there is no offset record to race.

The bug this nearly shipped

The design originally claimed unlink was atomic enough to serve as the finalize claim, so exactly one of two concurrent final chunks would win. That is false in practice. Measured on Node v24.15.0 / darwin, 200 runs of three concurrent claims:

Mechanism	Result
fsPromises.unlink, concurrent	ok, ok, ok — all three win, every time
fsPromises.rename, concurrent	ok, ENOENT, ENOENT — exactly one winner, every time
unlinkSync, sequential (control)	ok, ENOENT, ENOENT — confirms the harness

With unlink as the claim, two concurrent final chunks would both finalize — one upload becoming two assets, or one asset plus an orphaned file. The claim is now rename, the measurement is recorded in the spec so nobody swaps it back, and the sweeper reclaims the .finalizing files a crashed finaliser leaves behind.

It was caught because a test was failing and the failure was investigated rather than retried.

Other corrections made during implementation

• The create DTO could not have worked. AssetMediaCreateSchema is built for multipart strings — isFavorite is z.stringbool (rejects a JSON false) and metadata is JsonParsed (rejects a real array). A JSON body would have failed validation on every request while tsc stayed green. The session endpoint gets its own JSON-native schema; §4.3 of the spec spells out the field-by-field mapping.
• operationId collision. The controller's create generated createSession, colliding with SessionController's POST /sessions, and the Dart generator rejects duplicates outright — mise open-api failed. Renamed; the generated Dart is verified with dart analyze --fatal-infos because the OpenAPI check does not compile Dart.
• The generated client cannot type the chunk PATCH. oazapfts emits it as Promise<unknown> and drops status and headers, so no client can tell 204 from 200/201 from 409 through it. Every client hand-rolls the PATCH; create/HEAD/DELETE still use the SDK.
• A blanket as AssetMediaCreateDto cast in finalize was disabling type checking; removing it immediately surfaced a genuine missing field.

Test coverage

49 numbered edge cases in the spec, each mapped to a named test in a coverage table. Highlights:

• The three storage invariants are mutation-proven: making writeChunkAt land 64 KiB past the intended offset fails all three, including the sparse-file check — which is the only direct test that the exact-offset rule is intact.
• The route-collision test builds a Nest module with both AssetController and UploadSessionController in production order and asserts HEAD resolves correctly, since Express resolves HEAD against GET handlers.
• The auth-kind check asserts all four combinations, not just the two failing ones — testing only the failures would pass against an implementation that rejects everything.
• e2e uploads identical bytes through both protocols as two different users and asserts the checksums match, which is what catches a dropped, doubled or misplaced chunk.

Rebase cost

This fork rebases onto upstream regularly, so the coupling surface was measured rather than guessed. The contracts this depends on are near-frozen: uploadAsset()'s signature took 1 upstream commit in 12 months, the UploadFile type 0, the canUploadFile/getUploadFilename/getUploadFolder trio 2 (both small bugfixes).

Verified in this branch: server/src/middleware/file-upload.interceptor.ts is still byte-identical to upstream/main, and neither asset-media.service.ts nor app.common.ts was modified at all. The server side is new files plus about a dozen union lines.

The real recurring cost is mobile — background_upload.service.dart and foreground_upload.service.dart take ~19 and ~21 upstream commits a year, and the latter had zero fork edits before this.

Known gaps, stated plainly

• Resumption is within-session only. Closing the tab or losing the Dart isolate abandons the upload; the server session is swept after 24h. Mobile background gets restart survival incidentally because the chain state rides in a field background_downloader already persists.
• The database-backed medium test is not implemented — the medium harness mocks StorageRepository, so it would not add real-filesystem coverage, and the behaviour is already covered three ways. Reasoned in the spec rather than left as a silent hole.
• The e2e specs have not been run locally. The shared e2e stack on :2285 has been up for two days on an image without these routes, and rebuilding it would disrupt other sessions. CI runs them in a clean environment.
• Mobile has not been exercised on a real device — unit tests only (3,591 passing, dart analyze --fatal-infos clean). The native iOS Range-enqueue failure path, background_downloader's real persistence semantics, and an actual app-kill-and-restart were not exercised.
• Background progress aggregation is not wired to any UI. Nothing in the repo currently consumes BackgroundUploadService.taskProgressStream, so the aggregation is implemented and unit-tested in isolation rather than observed end to end. The foreground path, which does feed the UI, is unaffected by chunking.

Docs

The reverse-proxy guide now explains that a generous body limit is no longer required, with a warning not to tighten it until every client is updated — an older mobile app still uploads single-shot and would start failing with 413. Three genuinely stale CLAUDE.md items were fixed along the way: the documented single-test command silently ran the whole suite, make open-api has been removed in favour of mise open-api, and the stated base version was six weeks out of date.

https://claude.ai/code/session_01Rkzj87UgmFKFXKX5QNmSxo