Add chunked upload documentation for rx.upload_files_chunk

[FarhanAliRaza]

Document the new rx.upload_files_chunk API for incremental large file uploads, including handler requirements, chunk properties, and a complete code example. Update the progress section and API routes overview to cover both upload methods.

All Submissions:

• Have you followed the guidelines stated in CONTRIBUTING.md file?
• Have you checked to ensure there aren't any other open Pull Requests for the desired changed?

Type of change

New Feature Submission:

• Does your submission pass the tests?
• Have you linted your code locally prior to submission?

closes #6207

[codspeed-hq]

Merging this PR will not alter performance

✅ 8 untouched benchmarks

---

_{Comparing FarhanAliRaza:chunked-upload-docs (dfafc86) with main (57119bc)}

[greptile-apps]

Greptile Summary

This PR documents the new rx.upload_files_chunk / rx.UploadChunkIterator API for streaming large-file uploads incrementally. It adds a "Chunked Uploads" section to the upload reference page, updates the Progress section to cover both upload methods (the simplified three-key progress dict is correct per the current XHR-based frontend), and amends the API-routes overview to mention both upload helpers.

Key changes:

• New "Chunked Uploads for Large Files" sub-section with step-by-step requirements (@rx.event(background=True), rx.UploadChunkIterator, full-consumption rule) and a complete working code example.
• Progress-dictionary example correctly simplified to loaded, total, progress — matching the actual xhr.upload.onprogress payload in upload.js.
• /_upload route documentation updated to list both rx.upload_files and rx.upload_files_chunk.

Issues found:

• Unintended reflex-web submodule — a broken gitlink is being added at the repository root with no .gitmodules entry. This is unrelated to the docs change and must be removed before merging.
• \"r+b\" open mode in example code — if the same filename is uploaded more than once, existing bytes beyond the new upload size are not truncated, producing a silently corrupt file. The simpler \"wb\" mode is safer for a documentation example.

Confidence Score: 4/5

Not safe to merge as-is: the broken reflex-web submodule must be removed before merging.

One P1 finding (broken orphan submodule with no .gitmodules) must be fixed before merging. The P2 finding (stale bytes in example code) is a documentation-quality issue that should ideally also be addressed. Once both are resolved the PR is ready.

The reflex-web submodule entry at the repo root must be removed with git rm --cached reflex-web. The reflex/docs/library/forms/upload.md example should also switch from "r+b" to "wb".

Important Files Changed

Filename	Overview
reflex-web	Broken git submodule entry (mode 160000) added without a .gitmodules file — unrelated to the docs change and should be removed.
reflex/docs/library/forms/upload.md	Main documentation update adding chunked-upload section; chunk properties and lifecycle are accurate, but the file-open example uses "r+b" mode which can leave stale bytes when the same filename is re-uploaded with shorter content.
reflex/docs/api-routes/overview.md	Small, correct update noting that the /_upload route now covers both rx.upload_files and rx.upload_files_chunk.

Sequence Diagram

sequenceDiagram
    participant Browser
    participant UploadJS as upload.js (XHR)
    participant UploadRoute as /_upload route
    participant ChunkParser as _UploadChunkMultipartParser
    participant ChunkIter as UploadChunkIterator
    participant Handler as handle_large_upload (background)

    Browser->>UploadJS: on_click → rx.upload_files_chunk(upload_id)
    UploadJS->>UploadRoute: POST multipart/form-data (streaming)
    UploadRoute->>ChunkIter: create UploadChunkIterator
    UploadRoute->>Handler: dispatch @rx.event(background=True) with chunk_iter
    UploadRoute->>ChunkParser: parse(stream, chunk_iter)

    loop for each network packet
        ChunkParser->>ChunkIter: push(UploadChunk{filename, offset, content_type, data})
        ChunkIter-->>Handler: yield chunk
        Handler->>Handler: seek(chunk.offset) + write(chunk.data)
    end

    ChunkParser->>ChunkIter: finish()
    Handler->>Handler: close file handles
    Handler->>Handler: async with self → update state

    UploadJS-->>Browser: on_upload_progress({loaded, total, progress})

Loading

_{Reviews (1): Last reviewed commit: "Add chunked upload documentation for rx...." | Re-trigger Greptile}

[masenf]

while we're in here, lets change this to Starlette's UploadFile, since that's closer to what we're using.

but probably should include the generated docs for our UploadFile class eventually, since that is what we actually use

[FarhanAliRaza]

updated.

[masenf]

i know you say "large" here, but i would explicitly mention something about memory consumption being higher when buffering files

[FarhanAliRaza]

updated.