A capability stays maintainable only when the team can explain every state, retry, and piece of residual data—not merely show one successful run. Application goodput excludes headers, retransmission, and unacknowledged buffers. Small files are dominated by setup and belong in separate cohorts.
Observability should locate the failing stage, affected sessions, and whether impact is growing. Events use allowlisted low-cardinality dimensions; payloads, secrets, and complete network identity stay out.
Questions the design must answer
Turn the important choices into durable contracts: validate inputs, assign state ownership, define cleanup, and specify fallback for older peers. Later optimization must not change those semantics.
- Compute acknowledged-byte deltas each second into exponential buckets, mark the first three seconds as warmup, and label only path, size band, browser major, and result.
- Give state one owner, a version, and terminal states; callbacks may mutate only the version that created them.
- Ship conservative defaults, server-side ceilings, and a rollout switch instead of trusting browser-provided numbers as resource budgets.
The delivery standard for File Throughput Histograms: Goodput, Wire Rate, and Small Files is a usable normal path, convergent failures, bounded resources, and a state users can understand. The result is a production capability that can be explained, degraded safely, and rolled back—not a demo that works once.
Edge cases are part of the feature
An abnormal path is more than an error banner. It decides how in-flight work stops, how the peer learns the outcome, what residue remains, and whether the next operation inherits it.
- Size divided by duration mixes pauses and user wait, while successful-large-file-only metrics hide survivor bias from slow users cancelling.
- A boolean failure cannot distinguish retryable, user-action, and permanent refusal, producing an endless loop.
- User or task IDs in metric labels create high-cardinality cost and leak unnecessary identity into diagnostics.
Prove that it works with evidence
Write the expected state trace before injecting faults. At every phase, reconcile user-visible outcome, both protocol endpoints, persistent records, and resource counts to prove the loop.
- Transfer 1 KB, 1 MB, and 1 GB at known shaping rates with pauses, retransmission, and cancel; histograms must distinguish startup, steady state, and failure.
- Drive the state machine with reordered, duplicate, and delayed messages, proving stale versions are ignored and explicit stop survives recovery.
- Cover direct, relayed, weak-network, background-tab, and mobile paths; do not rely on averages or one successful screenshot.
The release bar is clear: users understand the current state, failures stop or recover, resources stay bounded, and operators can identify the phase from minimum necessary evidence.