Auto-chunk large wheels in add_wheels() / install_uploaded_wheels() - #2667

Summary

Follow-up to #2652 (bring your own wheels). A wheel larger than the gateway's per-request upload limit (MAX_REQUEST_BODY_SIZE_MB, default 50MB) is refused with a 413, so users have had to hand-split large wheels (e.g. CUDA torch-*+cu121*.whl) and rejoin them in the entrypoint. This makes that automatic and verified, almost entirely client-side.

What changes

• add_wheels() splits any wheel over WHEEL_CHUNK_THRESHOLD_MB (default 40, under the 50 limit; override with WHEEL_CHUNK_THRESHOLD_MB_OVERRIDE) into ordered parts named <wheel>.whl.part-0001-of-000N, uploads each as its own request, and writes a combined .wheel-chunks-manifest.json (per-wheel sha256 + ordered part list) into the wheels/ dir. Smaller wheels upload whole exactly as before.
• install_uploaded_wheels() reassembles each chunked wheel into a temp dir (the mount is read-only), verifies it against the manifest sha256, and only then pip installs it alongside any whole wheels. A missing part or checksum mismatch raises rather than installing a corrupt wheel. With no manifest present, behavior is byte-for-byte unchanged.
• Transparent API: add_wheels() returns logical wheel names; list_wheels() hides parts + manifest and surfaces chunked wheels by their logical name; remove_wheels() deletes a chunked wheel's parts and prunes the manifest. Re-uploading a wheel clears its stale parts first so a smaller rebuild can't leave orphans.

Supporting change: sub_path on download

Reading the manifest back from wheels/ needs download-by-sub_path, which #2652 did not add (it added sub_path to upload/list/delete only). This threads sub_path through the whole download path — client file_download / GatewayFilesClient.download, the download view + use-case, and get_public_file_stream in both storage backends — making download symmetric with the others. This is the only gateway change.

Part naming & manifest

Parts: <wheel>.whl.part-0001-of-000N (only -/digits/. added; a part never ends in .whl, so the runtime's existing wheel scan skips it). Manifest: .wheel-chunks-manifest.json, {"schema":1,"chunked_wheels":[{wheel, sha256, size, part_size, part_count, parts:[…]}]}; the runtime rejects an unknown schema loudly.

Caveats (documented in the guide)

• Chunk uploads rely on the deployment accepting application/octet-stream (parts) and application/json (manifest), which the default config does; a hardened allowlist could reject them.
• Reassembly uses transient /tmp space during function start-up (bounded, cleaned up after install).
• sha256 is over the whole reassembled wheel (per-part digests could be added later under a schema bump).

Testing

• Client runtime (test_wheels.py): reassemble+verify, sha mismatch raises before pip, missing part raises, mixed whole+chunked, unknown schema rejected, workdir cleaned up, lone part ignored — plus the existing no-manifest tests as a regression guard.
• Client API (test_serverless_client_functions.py): small→whole/no-manifest, at-threshold→whole, large→N parts + manifest with round-trip + sha256 check, re-upload cleans stale parts, partial-failure cleanup, list_wheels hides parts/manifest and shows logical names, remove_wheels deletes parts + prunes manifest.
• Gateway storage (test_file_storage.py): get_public_file_stream(sub_path="wheels") round trip.
• Ran locally (client venv): client suites green (108 passing across the touched files); black clean; pylint 10/10 on the client source. The gateway Django suite and gateway lint could not run in my environment — please confirm CI (tox -e py312, lint) before un-drafting.

Checklist

• I have added tests to cover my changes.
• I have updated the documentation accordingly.
• I have added a release note.

🤖 Generated with Claude Code