DRAFT: SERV-1404: adaptive multipart chunk size + resumable /data uploads (client)

[jim-fal]

SERV-1404 — client side: adaptive chunks + resumable /data uploads

Large model-checkpoint uploads to /data (~200GB) failed out of the box, so customers (e.g. BFL) built their own uploaders. Root cause: the client used a fixed 10MB chunk, which overflows the server's 10,000-part cap at ~100GB.

Changes

• Adaptive chunk size (compute_multipart_chunk_size) — scales the chunk so any file up to the server ceiling (~976 GiB) stays within 10k parts.
• Resumable uploads — the client sends the file identity (content_md5, size, chunk_size) to initiate; the server returns parts it already has, and the client skips them (seek-based, only-missing parts read). It also no longer auto-cancels on failure, so an interrupted upload resumes on re-run.

Testing

Run: cd projects/fal && uv run --extra test python -m pytest tests/unit/test_multipart_upload.py -v → 10 passed.

test_adaptive_chunk_size_stays_within_limits[1]                PASSED
test_adaptive_chunk_size_stays_within_limits[1048576]          PASSED
test_adaptive_chunk_size_stays_within_limits[52428800]         PASSED
test_adaptive_chunk_size_stays_within_limits[107374182400]     PASSED  # 100 GB
test_adaptive_chunk_size_stays_within_limits[214748364800]     PASSED  # 200 GB
test_adaptive_chunk_size_stays_within_limits[966367641600]     PASSED  # 900 GB
test_small_file_keeps_default_chunk                            PASSED
test_200gb_would_exceed_cap_with_old_fixed_chunk               PASSED
test_file_over_ceiling_raises                                  PASSED
test_resume_skips_already_uploaded_parts                       PASSED
============================ 10 passed in 3.08s ============================

Adaptive chunk sizing (old fixed 10MB overflows the 10k-part cap at ≥100GB):

File size	Chunk	Parts (new)	Parts (old 10MB)	Within 10k cap
1 GB	10 MB	103	103	✅
50 GB	10 MB	5,120	5,120	✅
100 GB	11 MB	9,310	10,240 ✗	✅
200 GB	21 MB	9,753	20,480 ✗	✅
500 GB	52 MB	9,847	51,200 ✗	✅
900 GB	93 MB	9,910	92,160 ✗	✅

Resume is exercised by test_resume_skips_already_uploaded_parts: a mock server stores parts, the upload is failed after 4 parts, and the re-run uploads only the 7 missing parts with zero overlap. Ruff: 0 new findings on changed files.

Artifacts

Full test report & runbook (all suites, commands, captured output): https://claude.ai/code/artifact/ef3068d9-0344-4fb9-aa6a-ad94861490fe — private Claude artifact; ping me and I'll share it.

Paired PRs

• Server: fal-ai/isolate-cloud#8646 · CronJob: fal-ai/infra#12590

Draft: depends on the isolate-cloud server PR for end-to-end resume.

🤖 Generated with Claude Code

[linear-code]

SERV-1404

[jim-fal]

Test report & runbook — full test matrix, commands, and captured output are in the PR description above; this is the summary view of the published report.