From df5e915527f9532786d89679445baf3e3815ceb5 Mon Sep 17 00:00:00 2001 From: Marius Kleidl Date: Tue, 18 Feb 2025 10:21:13 +0100 Subject: [PATCH] Clarify resumption of multi-request upload --- draft-ietf-httpbis-resumable-upload.md | 50 +++++++++++++++++++++----- 1 file changed, 42 insertions(+), 8 deletions(-) diff --git a/draft-ietf-httpbis-resumable-upload.md b/draft-ietf-httpbis-resumable-upload.md index 110878024..cf3ef06cd 100644 --- a/draft-ietf-httpbis-resumable-upload.md +++ b/draft-ietf-httpbis-resumable-upload.md @@ -98,7 +98,7 @@ Resumable uploads are supported in HTTP through use of a temporary resource, an The remainder of this section uses examples to illustrate different interactions with the upload resource. HTTP message exchanges, and thereby resumable uploads, use representation data (see {{Section 8.1 of HTTP}}). This means that resumable uploads can be used with many forms of content, such as static files, in-memory buffers, data from streaming sources, or on-demand generated data. -## Example 1: Complete upload of representation data with known size +## Example 1: Complete upload of representation data with known size {#example-1} In this example, the client first attempts to upload representation data with a known size in a single HTTP request to the target resource. An interruption occurs and the client then attempts to resume the upload using subsequent HTTP requests to the upload resource. @@ -122,9 +122,7 @@ Client Server | with upload resource URL | |<-------------------------------------------| | | -| Flow Interrupted | -|------------------------------------------->| -| | +X--------------Flow Interrupted--------------X ~~~ {: #fig-upload-creation title="Upload Creation"} @@ -170,7 +168,7 @@ Client Server ~~~ {: #fig-upload-cancellation title="Upload Cancellation"} -## Example 2: Upload as a series of parts +## Example 2: Upload as a series of parts {#example-2} In some cases, clients might prefer to upload a representation as a series of parts sent serially across multiple HTTP messages. One use case is to overcome server limits on HTTP message content size. Another use case is where the client does not know the final size of the representation data, such as when the data originates from a streaming source. @@ -189,9 +187,45 @@ Client Server |<------------------------------------------------| | | ~~~ -{: #fig-upload-creation-incomplete title="Incomplete Upload Creation"} +{: #fig-upload-creation-incomplete title="Upload creation with partial representation data"} + +2) Subsequent, intermediate parts are appended ({{upload-appending}}) with the `Upload-Complete` field value set to false, indicating that they are not the last part of the representation data. The offset value in the `Upload-Offset` header field is taken from the previous response when creating the upload or appending to it. + +~~~ aasvg +Client Server +| | +| PATCH to upload resource URL with Upload-Offset | +| and Upload-Complete: ?0 | +|------------------------------------------------>| +| | +| 204 No Content | +|<------------------------------------------------| +| | +~~~ +{: #fig-upload-appending-incomplete title="Appending partial representation data to upload"} + +3) If the connection was interrupted, the client might want to resume the upload, similar to the previous example ({{example-1}}). The client retrieves the offset ({{offset-retrieving}}) to learn the amount of representation data received by the server and then continues appending the remaining parts to the upload as in the previous step. + +~~~ aasvg +Client Server +| | +| HEAD to upload resource URL | +|------------------------------------------------>| +| | +| 204 No Content with Upload-Offset | +|<------------------------------------------------| +| | +| PATCH to upload resource URL with Upload-Offset | +| and Upload-Complete: ?0 | +|------------------------------------------------>| +| | +| 204 No Content | +|<------------------------------------------------| +| | +~~~ +{: #fig-upload-resume-incomplete title="Resuming an interrupted upload"} -2) Subsequently, parts are appended ({{upload-appending}}). The last part of the upload has a `Upload-Complete` field value set to true to indicate the complete transfer. +4) The request to append the last part of the representation data has a `Upload-Complete` field value set to true to indicate the complete transfer. ~~~ aasvg Client Server @@ -204,7 +238,7 @@ Client Server |<------------------------------------------------| | | ~~~ -{: #fig-upload-appending-last-chunk title="Upload Append Last Chunk"} +{: #fig-upload-appending-last-chunk title="Appending remaining representation data"} # Upload Creation {#upload-creation}