Feature Proposal: Resume File Upload

[o-nnerb]

Overview

Full protocol-agnostic "resumable upload" isn't something this package can implement, and this discussion is scoped down to the one piece that actually is transport-agnostic: starting a file upload's byte stream at an arbitrary offset.

Why full resume support doesn't belong here

Standard HTTP has no universal "resume a POST/PUT" mechanism — unlike downloads, where Range / 206 Partial Content is a real, standardized GET mechanism. Every resumable-upload scheme that exists (tus.io's HEAD + Upload-Offset protocol, S3's Multipart Upload API, Google Cloud's resumable sessions, Azure Block Blob) is a vendor/application-level negotiation bolted on top of plain HTTP. Confirmed neither of this package's dependencies help here either: grepping both AsyncHTTPClient and NIOCore for resume/tus/Upload-Offset/Content-Range turns up nothing but generic Swift-concurrency "resume the continuation" hits, unrelated to file uploads. A generic HTTP client has no way to know which of these protocols (if any) the server on the other end speaks, so RequestDL can't bake in a real resume handshake without picking a specific backend to support.

What's actually in scope: Payload(url:from:)

The one piece that is transport-agnostic is starting a file upload's byte stream at an arbitrary offset instead of from the start — and this is nearly free given what already exists. The file-backed stream buffer behind FilePayloadFactory already does absolute-offset pread/pwrite with a seek(to offset:) method (every syscall addresses an absolute offset, so nothing needs to scan from the start to reach a given position). Adding a Payload(url: fileURL, from: byteOffset) initializer that seeks there before streaming is a small, self-contained addition — no new I/O primitive required.

Combined with UploadStep (already public, already reports chunkSize/totalSize per step via AsyncResponse), a consumer can track bytes sent, and on failure, start a fresh UploadTask with a payload beginning at that offset.

Out of scope

• Any built-in negotiation with a specific resumable-upload backend (tus.io, S3, GCS, Azure) — that stays userland code, the same way Feature Proposal: Routing Request #199's retry-on-401 pattern stayed a .map-based consumer responsibility rather than a bespoke library feature.
• Automatic retry/resume orchestration — the consumer decides when and how to retry; this package only provides the byte-offset starting point.

Milestone: 4.1.0

[o-nnerb]

Scoped down from "resumable upload" (which would require picking a specific vendor protocol — tus.io, S3, GCS — none of which AsyncHTTPClient/NIO have any support for) to the one transport-agnostic piece that's actually useful: Payload(url:from:), letting a file upload start at an arbitrary byte offset by seeking the existing file-backed stream buffer, which already supports absolute-offset reads. The actual resume handshake with whichever backend an app uses stays consumer-orchestrated. Ready to be picked up as an implementation task.

[o-nnerb]

Implementado em #266 — Payload(url:from:) disponível na main. Fechando como resolvido.