skip to content

File Upload Flows

A browser upload slices a File into chunks, sends them to a pre-signed URL with progress, retry and a concurrency cap, and resumes from the server's offset. Design rounds want the whole flow.

on this pageshow

questions

6

In a real-estate listing portal's web uploader handling 60 photos and a 3 GB video, how should per-file progress, total progress, retry and cancel work?

level: middleimportance: must knowfreq 56%

answer

  1. a state per file, not one spinner
  2. weight the total by bytes
  3. confirmed plus in flight, never twice
  4. retry the transient, stop on the permanent
  5. cancel aborts one file's requests only

basics

~20 s

Track each file's state and bytes; total progress is confirmed plus in-flight bytes over all bytes. Retry transient failures with backoff, stop a file on permanent ones, and cancel by aborting only that file's requests.

solid answer

~50 s

Give each file an entry with a state (uploading, retrying, failed, finishing, done…), its size, confirmed bytes and in-flight bytes; its bar is their sum over size. The total bar weighs by bytes: sixty 1 MB photos are about 2% of the work beside a 3 GB video, so counting files would show 98% with hours left. Progress events (from `XMLHttpRequest`'s `upload` object) count bytes sent, not stored, so when a chunk fails its in-flight bytes come off and the bar steps back by at most that chunk instead of counting them twice. Retry network errors, timeouts, 5xx and 429 with capped exponential backoff and jitter; fetch a fresh URL after an expiry 403; stop a file on a 4xx a retry cannot change and show why. Cancel aborts that file's request, drops its queued chunks, tells the API to discard the upload and removes its bytes from the total; the rest carry on.

code

json · 28 lines
json
[
  {
    "fileId": "f-031",
    "listingId": "88214",
    "name": "kitchen-02.jpg",
    "kind": "photo",
    "size": 912384,
    "state": "retrying",
    "confirmedBytes": 0,
    "inFlightBytes": 0,
    "attempt": 2,
    "lastError": "timeout",
    "nextAttemptAt": "2026-10-07T09:14:05Z"
  },
  {
    "fileId": "f-061",
    "listingId": "88214",
    "name": "walkthrough.mp4",
    "kind": "video",
    "size": 3221225472,
    "state": "uploading",
    "confirmedBytes": 1879048192,
    "inFlightBytes": 3145728,
    "attempt": 1,
    "lastError": null,
    "nextAttemptAt": null
  }
]

go deeper

for a junior

Recall that each file needs its own state and progress, that the total is weighted by bytes, and that progress events count bytes sent rather than bytes stored.

for a middle

Explain the queue entry, how the total combines confirmed and in-flight bytes without double counting, which statuses retry and which stop a file, and the five steps of cancelling one file.

for a senior

Show production judgment: backoff with jitter so retries do not stampede, a finishing state until the server confirms, pause instead of cancel for a large video, and one bad file never stalling the rest.

for a principal

Weigh honesty against smoothness: a confirmed-only total never goes backwards but lags; an in-flight total is current but can dip. Pick per file size and make the rule the same in every upload surface.

## One entry per file, one scheduler for all A listing portal's agent drops 60 photos and a 3 GB walkthrough video onto a listing. A single spinner for "the upload" cannot say which photo failed or how long the video has left, so the page keeps an **upload queue**: one entry per file and one scheduler that decides what to send next. Each entry holds: - an id, the listing id, name, size and kind (photo or video); - a **state**: `queued`, `uploading`, `retrying`, `paused`, `failed`, `finishing`, `done` or `cancelled`; - `confirmedBytes`, what the server has acknowledged, and `inFlightBytes`, what the current request has sent so far; - the attempt count, the last error and when the next attempt is due. The interface renders straight from these entries, so every row and the total bar always agree. ## Progress that tells the truth Progress events come from `XMLHttpRequest`'s `upload` object; why `fetch` cannot provide them is a question about the network clients, not this design. What matters here is what those events measure: **bytes handed to the network**, not bytes the server stored. | How the total is computed | What the agent sees with 60 photos done and the video 10% sent | |---|---| | files done / files chosen | about 98%, with hours still to go | | average of each file's percentage | also about 98%, for the same reason | | (confirmed + in-flight bytes) / total bytes | about 12%, which is the truth | Three rules keep the bar honest: 1. **Weigh by bytes.** The video is about 98% of the work, and the bar should say so. 2. **Never count bytes twice.** When a chunk fails, its in-flight bytes are subtracted; when it is resent they count again from zero. The bar may step back by one chunk; it must never pass 100% or creep ahead of reality. 3. **Sent is not finished.** A file whose bytes are all sent sits in `finishing` until the server confirms it. Showing "done" early is how agents publish listings with missing photos. A time estimate from a smoothed recent rate helps more than a percentage on a 3 GB file; show it with a range, not to the second. ## Which failures retry and which stop the file - **Network error or timeout:** retry with capped exponential backoff and jitter, so a dropped uplink does not turn into a burst of simultaneous retries when it returns. - **5xx:** retry the same way. - **429:** wait, honouring `Retry-After` when it is sent. - **403 after the file waited a while:** usually an expired pre-signed URL; fetch a fresh one for the same upload and retry once. - **Other 4xx** (a rejected type, a malformed request): a retry cannot change the answer, so stop the file and show the reason. Cap the attempts, then mark the file `failed` with a retry button; one bad photo must never stall the other 59. The browser's `offline` event is a useful hint to pause and say "waiting for network", but `navigator.onLine` being true does not prove the storage host is reachable, so the real signal is still whether requests succeed. ## Cancel one file without stopping the rest 1. Abort that file's in-flight request (`xhr.abort()`, or an `AbortController` for a `fetch`). 2. Remove its queued chunks from the scheduler. 3. Tell the portal's API to discard the upload, so partial bytes do not linger. 4. Remove its size from the total, so the bar does not stall short of 100%. 5. Release its preview's object URL, and let the scheduler start the next file. Offer **pause** next to cancel for the video: pause stops sending but keeps the server's partial upload, so resuming continues from the server's offset. Cancelling 2 GB by accident on a weak uplink is an hour lost, so ask before cancelling a large file. ## What the agent sees - One row per file with its state, bytes and, on failure, the reason in plain words. - A total bar by bytes, with a range for the time left. - Retry on failed rows, pause and cancel on active ones. - A publish button that stays disabled until the server has confirmed every upload, because that gate is the server's and the page only reflects it.

  • Why does the total bar sometimes step backwards, and is that acceptable?
    A failed chunk's in-flight bytes are subtracted before it is resent, so the bar drops by at most one chunk. That small honest step is acceptable; double-counting is not. If even that looks bad, compute the total from confirmed bytes only: it never moves backwards but lags the truth by the chunks in flight, which suits a long video better than a batch of small photos.
  • The agent cancels the video at 2.1 GB, then changes their mind. What happens, and what should the design offer?
    Cancel told the API to discard the partial upload, so starting again means byte zero. That is why the video row should offer pause as the default action and confirm before cancelling a large file: pause stops sending but keeps the server's partial upload, so resuming asks the server for its offset and continues from 2.1 GB.
  • How do you stop retries from flooding a weak uplink when the connection returns?
    Retries obey the same overall concurrency cap as first attempts, and each waits a backoff with random jitter, so files that failed together do not all fire in the same second. On the `online` event or a successful probe, release them gradually rather than resetting every timer to zero.

Reporting progress by file count is like a removals crew saying "60 of 61 items loaded" when the 61st is the piano: weigh the load, not the number of items.

  • Total progress is the number of files done divided by the files chosen
  • Upload progress reaching 100% means the server has stored the file
  • Retry every failed request immediately until it succeeds
  • Every 4xx response deserves a few retries, just like a timeout
  • Cancelling one file should abort the whole batch to keep state simple
  • A resent chunk's bytes are added to the total again on each attempt
open as a page

When an agent's 3 GB walkthrough upload in a real-estate listing portal stops at 1.8 GB after a dropped uplink, an expired URL or a reload, how does the page resume?

level: seniorimportance: must knowfreq 47%

basics

~20 s

Ask the server how many bytes it holds and send the rest from that offset with Blob.slice. Surviving a reload also needs the saved upload id and file fingerprint, a fresh URL, and the agent choosing the file again.

open as a page

In a real-estate listing portal's web uploader, what steps does the page take to send one photo straight to storage with a pre-signed URL?

level: juniorimportance: should knowfreq 48%

basics

~20 s

The page asks the portal's API for an upload id and a short-lived pre-signed URL, sends the photo's bytes straight to that URL, then tells the API the upload finished so the server can verify and attach it.

open as a page

In a real-estate listing portal's web uploader, which checks and previews should run before any byte is sent, and what do they cost the page?

level: middleimportance: should knowfreq 42%

basics

~20 s

Check count, size, type and, for photos, decoded dimensions before sending, to spare the agent's uplink, as feedback only because the server checks again. Preview with object URLs or small thumbnails, and revoke each URL when its tile goes.

open as a page

In a real-estate listing portal's web uploader sending 60 photos and a 3 GB video over a phone's weak uplink, how many uploads should run at once, and why?

level: seniorimportance: should knowfreq 38%

basics

~20 s

Run a small overall cap, about two requests on a weak phone uplink and three or four on office broadband, with the video in one lane and photos in the rest. More parallel requests split a thin uplink without adding bandwidth.

open as a page

Should a real-estate listing portal's web uploader resize and re-encode an agent's 12-megapixel phone photos before uploading them on a weak uplink, and what does that cost a low-end phone?

level: seniorimportance: should knowfreq 33%

basics

~20 s

Usually yes: a resized, re-encoded photo is a fraction of the original's bytes and leaves its location metadata behind. The cost is decode memory and CPU on the phone, so process one photo at a time in a worker.

open as a page