draft-ietf-httpbis-resumable-upload-03.txt		draft-ietf-httpbis-resumable-upload-latest.txt
	HTTP Working Group M. Kleidl, Ed.		HTTP Working Group M. Kleidl, Ed.
	Internet-Draft Transloadit		Internet-Draft Transloadit
	Intended status: Standards Track G. Zhang, Ed.		Intended status: Standards Track G. Zhang, Ed.
	Expires: September 5, 2024 Apple Inc.		Expires: September 26, 2024 Apple Inc.
	L. Pardue, Ed.		L. Pardue, Ed.
	Cloudflare		Cloudflare
	March 4, 2024		March 25, 2024
	Resumable Uploads for HTTP		Resumable Uploads for HTTP
	draft-ietf-httpbis-resumable-upload-03		draft-ietf-httpbis-resumable-upload-latest
	Abstract		Abstract
	HTTP clients often encounter interrupted data transfers as a result		HTTP clients often encounter interrupted data transfers as a result
	of canceled requests or dropped connections. Prior to interruption,		of canceled requests or dropped connections. Prior to interruption,
	part of a representation may have been exchanged. To complete the		part of a representation may have been exchanged. To complete the
	data transfer of the entire representation, it is often desirable to		data transfer of the entire representation, it is often desirable to
	issue subsequent requests that transfer only the remainder of the		issue subsequent requests that transfer only the remainder of the
	representation. HTTP range requests support this concept of		representation. HTTP range requests support this concept of
	resumable downloads from server to client. This document describes a		resumable downloads from server to client. This document describes a
	skipping to change at page 2, line 12 ¶		skipping to change at page 2, line 12 ¶
	Internet-Drafts are working documents of the Internet Engineering		Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF). Note that other groups may also distribute		Task Force (IETF). Note that other groups may also distribute
	working documents as Internet-Drafts. The list of current Internet-		working documents as Internet-Drafts. The list of current Internet-
	Drafts is at https://datatracker.ietf.org/drafts/current/.		Drafts is at https://datatracker.ietf.org/drafts/current/.
	Internet-Drafts are draft documents valid for a maximum of six months		Internet-Drafts are draft documents valid for a maximum of six months
	and may be updated, replaced, or obsoleted by other documents at any		and may be updated, replaced, or obsoleted by other documents at any
	time. It is inappropriate to use Internet-Drafts as reference		time. It is inappropriate to use Internet-Drafts as reference
	material or to cite them other than as "work in progress."		material or to cite them other than as "work in progress."
	This Internet-Draft will expire on September 5, 2024.		This Internet-Draft will expire on September 26, 2024.
	Copyright Notice		Copyright Notice
	Copyright (c) 2024 IETF Trust and the persons identified as the		Copyright (c) 2024 IETF Trust and the persons identified as the
	document authors. All rights reserved.		document authors. All rights reserved.
	This document is subject to BCP 78 and the IETF Trust's Legal		This document is subject to BCP 78 and the IETF Trust's Legal
	Provisions Relating to IETF Documents		Provisions Relating to IETF Documents
	(https://trustee.ietf.org/license-info) in effect on the date of		(https://trustee.ietf.org/license-info) in effect on the date of
	publication of this document. Please review these documents		publication of this document. Please review these documents
	skipping to change at page 3, line 9 ¶		skipping to change at page 3, line 9 ¶
	11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17		11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
	12. References . . . . . . . . . . . . . . . . . . . . . . . . . 17		12. References . . . . . . . . . . . . . . . . . . . . . . . . . 17
	12.1. Normative References . . . . . . . . . . . . . . . . . . 18		12.1. Normative References . . . . . . . . . . . . . . . . . . 18
	12.2. Informative References . . . . . . . . . . . . . . . . . 18		12.2. Informative References . . . . . . . . . . . . . . . . . 18
	Appendix A. Informational Response . . . . . . . . . . . . . . . 18		Appendix A. Informational Response . . . . . . . . . . . . . . . 18
	Appendix B. Feature Detection . . . . . . . . . . . . . . . . . 19		Appendix B. Feature Detection . . . . . . . . . . . . . . . . . 19
	Appendix C. Upload Metadata . . . . . . . . . . . . . . . . . . 21		Appendix C. Upload Metadata . . . . . . . . . . . . . . . . . . 21
	Appendix D. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 21		Appendix D. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 21
	Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 21		Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 21
	Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22		Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
	F.1. Since draft-ietf-httpbis-resumable-upload-02 . . . . . . 22		F.1. Since draft-ietf-httpbis-resumable-upload-03 . . . . . . 22
	F.2. Since draft-ietf-httpbis-resumable-upload-01 . . . . . . 22		F.2. Since draft-ietf-httpbis-resumable-upload-02 . . . . . . 22
	F.3. Since draft-ietf-httpbis-resumable-upload-00 . . . . . . 22		F.3. Since draft-ietf-httpbis-resumable-upload-01 . . . . . . 22
	F.4. Since draft-tus-httpbis-resumable-uploads-protocol-02 . . 23		F.4. Since draft-ietf-httpbis-resumable-upload-00 . . . . . . 22
	F.5. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 23		F.5. Since draft-tus-httpbis-resumable-uploads-protocol-02 . . 23
	F.6. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 23		F.6. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 23
			F.7. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 23
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23
	1. Introduction		1. Introduction
	HTTP clients often encounter interrupted data transfers as a result		HTTP clients often encounter interrupted data transfers as a result
	of canceled requests or dropped connections. Prior to interruption,		of canceled requests or dropped connections. Prior to interruption,
	part of a representation (see Section 3.2 of [HTTP]) might have been		part of a representation (see Section 3.2 of [HTTP]) might have been
	exchanged. To complete the data transfer of the entire		exchanged. To complete the data transfer of the entire
	representation, it is often desirable to issue subsequent requests		representation, it is often desirable to issue subsequent requests
	that transfer only the remainder of the representation. HTTP range		that transfer only the remainder of the representation. HTTP range
	skipping to change at page 5, line 19 ¶		skipping to change at page 5, line 19 ¶
	| POST |		| POST |
	|------------------------------------------->|		|------------------------------------------->|
	| |		| |
	| | Reserve resources		| | Reserve resources
	| | for upload		| | for upload
	| |-----------------.		| |-----------------.
	| | |		| | |
	| |<----------------'		| |<----------------'
	| |		| |
	| 104 Upload Resumption Supported |		| 104 Upload Resumption Supported |
	| with upload resouce URL |		| with upload resource URL |
	|<-------------------------------------------|		|<-------------------------------------------|
	| |		| |
	| Flow Interrupted |		| Flow Interrupted |
	|------------------------------------------->|		|------------------------------------------->|
	| |		| |
	Figure 1: Upload Creation		Figure 1: Upload Creation
	2) If the connection to the server is interrupted, the client might		2) If the connection to the server is interrupted, the client might
	want to resume the upload. However, before this is possible the		want to resume the upload. However, before this is possible the
	skipping to change at page 8, line 38 ¶		skipping to change at page 8, line 38 ¶
	success (e.g. "201 (Created)"), or when the response is a failure		success (e.g. "201 (Created)"), or when the response is a failure
	(e.g. "409 (Conflict)"). The "Upload-Offset" field value MUST be		(e.g. "409 (Conflict)"). The "Upload-Offset" field value MUST be
	equal to the end offset of the entire upload, or the begin offset of		equal to the end offset of the entire upload, or the begin offset of
	the next chunk if the upload is still incomplete. The client SHOULD		the next chunk if the upload is still incomplete. The client SHOULD
	consider the upload failed if the response has a status code that		consider the upload failed if the response has a status code that
	indicates a success but the offset indicated in the "Upload-Offset"		indicates a success but the offset indicated in the "Upload-Offset"
	field value does not equal the total of begin offset plus the number		field value does not equal the total of begin offset plus the number
	of bytes uploaded in the request.		of bytes uploaded in the request.
	If the request completes successfully and the entire upload is		If the request completes successfully and the entire upload is
	complete, the server MUST acknowledge it by responding with a		complete, the server MUST acknowledge it by responding with a 2xx
	successful status code between 200 and 299 (inclusive). Servers are		(Successful) status code. Servers are RECOMMENDED to use "201
	RECOMMENDED to use "201 (Created)" unless otherwise specified. The		(Created)" unless otherwise specified. The response MUST NOT include
	response MUST NOT include the "Upload-Complete" header field with the		the "Upload-Complete" header field with the value of false.
	value of false.
	If the request completes successfully but the entire upload is not		If the request completes successfully but the entire upload is not
	yet complete, as indicated by an "Upload-Complete" field value of		yet complete, as indicated by an "Upload-Complete" field value of
	false in the request, the server MUST acknowledge it by responding		false in the request, the server MUST acknowledge it by responding
	with the "201 (Created)" status code and an "Upload-Complete" header		with the "201 (Created)" status code and an "Upload-Complete" header
	value set to false.		value set to false.
	If the request includes an "Upload-Complete" field value set to true		If the request includes an "Upload-Complete" field value set to true
	and a valid "Content-Length" header field, the client attempts to		and a valid "Content-Length" header field, the client attempts to
	upload a fixed-length resource in one request. In this case, the		upload a fixed-length resource in one request. In this case, the
	upload's final size is the "Content-Length" field value and the		upload's final size is the "Content-Length" field value and the
	server MUST record it to ensure its consistency.		server MUST record it to ensure its consistency.
	The request content MAY be empty. If the "Upload-Complete" header		The request content MAY be empty. If the "Upload-Complete" header
	field is then set to true, the client intends to upload an empty		field is then set to true, the client intends to upload an empty
	entity. An "Upload-Complete" header field is set to false is also		resource representation. An "Upload-Complete" header field is set to
	valid. This can be used to create an upload resource URL before		false is also valid. This can be used to create an upload resource
	transferring data, which can save client or server resources. Since		URL before transferring data, which can save client or server
	informational responses are optional, this technique provides another		resources. Since informational responses are optional, this
	mechanism to learn the URL, at the cost of an additional round-trip		technique provides another mechanism to learn the URL, at the cost of
	before data upload can commence.		an additional round-trip before data upload can commence.
	The following example shows an upload creation. The client transfers		The following example shows an upload creation. The client transfers
	the entire 100 bytes in the first request. The server generates two		the entire 100 bytes in the first request. The server generates two
	informational responses to transmit the upload resource's URL and		informational responses to transmit the upload resource's URL and
	progress information, and one final response to acknowledge the		progress information, and one final response to acknowledge the
	completed upload:		completed upload:
	POST /upload HTTP/1.1		POST /upload HTTP/1.1
	Host: example.com		Host: example.com
	Upload-Draft-Interop-Version: 5		Upload-Draft-Interop-Version: 5
	skipping to change at page 10, line 28 ¶		skipping to change at page 10, line 28 ¶
	If the client received an informational response with the upload URL		If the client received an informational response with the upload URL
	in the Location field value, it MAY automatically attempt upload		in the Location field value, it MAY automatically attempt upload
	resumption when the connection is terminated unexpectedly, or if a		resumption when the connection is terminated unexpectedly, or if a
	5xx status is received. The client SHOULD NOT automatically retry if		5xx status is received. The client SHOULD NOT automatically retry if
	it receives a 4xx status code.		it receives a 4xx status code.
	File metadata can affect how servers might act on the uploaded file.		File metadata can affect how servers might act on the uploaded file.
	Clients can send representation metadata (see Section 8.3 of [HTTP])		Clients can send representation metadata (see Section 8.3 of [HTTP])
	in the request that starts an upload. Servers MAY interpret this		in the request that starts an upload. Servers MAY interpret this
	metadata or MAY ignore it. The "Content-Type" header field		metadata or MAY ignore it. The "Content-Type" header field
	(Section 8.3 of [HTTP]) can be used to indicate the MIME type of the		(Section 8.3 of [HTTP]) can be used to indicate the media type of the
	file. The "Content-Disposition" header field ([RFC6266]) can be used		file. The "Content-Disposition" header field ([RFC6266]) can be used
	to transmit a filename; if included, the parameters SHOULD be either		to transmit a filename; if included, the parameters SHOULD be either
	"filename", "filename*" or "boundary".		"filename", "filename*" or "boundary".
	4.1. Feature Detection		4.1. Feature Detection
	If the client has no knowledge of whether the resource supports		If the client has no knowledge of whether the resource supports
	resumable uploads, a resumable request can be used with some		resumable uploads, a resumable request can be used with some
	additional constraints. In particular, the "Upload-Complete" field		additional constraints. In particular, the "Upload-Complete" field
	value (Section 8.2) MUST NOT be false if the server support is		value (Section 8.2) MUST NOT be false if the server support is
	skipping to change at page 12, line 20 ¶		skipping to change at page 12, line 20 ¶
	successfully received a corresponding creation request (Section 4) or		successfully received a corresponding creation request (Section 4) or
	append request (Section 6) with the "Upload-Complete" header value		append request (Section 6) with the "Upload-Complete" header value
	set to true.		set to true.
	The client MUST NOT perform offset retrieval while creation		The client MUST NOT perform offset retrieval while creation
	(Section 4) or append (Section 6) is in progress.		(Section 4) or append (Section 6) is in progress.
	The offset MUST be accepted by a subsequent append (Section 6). Due		The offset MUST be accepted by a subsequent append (Section 6). Due
	to network delay and reordering, the server might still be receiving		to network delay and reordering, the server might still be receiving
	data from an ongoing transfer for the same upload resource, which in		data from an ongoing transfer for the same upload resource, which in
	the client perspective has failed. The server MAY terminate any		the client's perspective has failed. The server MAY terminate any
	transfers for the same upload resource before sending the response by		transfers for the same upload resource before sending the response by
	abruptly terminating the HTTP connection or stream. Alternatively,		abruptly terminating the HTTP connection or stream. Alternatively,
	the server MAY keep the ongoing transfer alive but ignore further		the server MAY keep the ongoing transfer alive but ignore further
	bytes received past the offset.		bytes received past the offset.
	The client MUST NOT start more than one append (Section 6) based on		The client MUST NOT start more than one append (Section 6) based on
	the resumption offset from a single offset retrieving (Section 5)		the resumption offset from a single offset retrieving (Section 5)
	request.		request.
	In order to prevent HTTP caching, the response SHOULD include a		In order to prevent HTTP caching, the response SHOULD include a
	skipping to change at page 13, line 9 ¶		skipping to change at page 13, line 9 ¶
	indicates the new offset and that the upload is not complete yet:		indicates the new offset and that the upload is not complete yet:
	HEAD /upload/b530ce8ff HTTP/1.1		HEAD /upload/b530ce8ff HTTP/1.1
	Host: example.com		Host: example.com
	Upload-Draft-Interop-Version: 5		Upload-Draft-Interop-Version: 5
	HTTP/1.1 204 No Content		HTTP/1.1 204 No Content
	Upload-Offset: 100		Upload-Offset: 100
	Upload-Complete: ?0		Upload-Complete: ?0
	Cache-Control: no-store		Cache-Control: no-store
	The client SHOULD NOT automatically retry if a client error status		The client SHOULD NOT automatically retry if a 4xx (Client Error)
	code between 400 and 499 (inclusive) is received.		status code is received.
	6. Upload Append		6. Upload Append
	Upload appending is used for resuming an existing upload.		Upload appending is used for resuming an existing upload.
	The request MUST use the "PATCH" method and be sent to the upload		The request MUST use the "PATCH" method and be sent to the upload
	resource. The "Upload-Offset" field value (Section 8.1) MUST be set		resource. The "Upload-Offset" field value (Section 8.1) MUST be set
	to the resumption offset.		to the resumption offset.
	If the end of the request content is not the end of the upload, the		If the end of the request content is not the end of the upload, the
	skipping to change at page 14, line 20 ¶		skipping to change at page 14, line 20 ¶
	if it considers the upload active, either when the response is a		if it considers the upload active, either when the response is a
	success (e.g. "201 (Created)"), or when the response is a failure		success (e.g. "201 (Created)"), or when the response is a failure
	(e.g. "409 (Conflict)"). The value MUST be equal to the end offset		(e.g. "409 (Conflict)"). The value MUST be equal to the end offset
	of the entire upload, or the begin offset of the next chunk if the		of the entire upload, or the begin offset of the next chunk if the
	upload is still incomplete. The client SHOULD consider the upload		upload is still incomplete. The client SHOULD consider the upload
	failed if the status code indicates a success but the offset		failed if the status code indicates a success but the offset
	indicated by the "Upload-Offset" field value does not equal the total		indicated by the "Upload-Offset" field value does not equal the total
	of begin offset plus the number of bytes uploaded in the request.		of begin offset plus the number of bytes uploaded in the request.
	If the request completes successfully and the entire upload is		If the request completes successfully and the entire upload is
	complete, the server MUST acknowledge it by responding with a		complete, the server MUST acknowledge it by responding with a 2xx
	successful status code between 200 and 299 (inclusive). Servers are		(Successful) status code. Servers are RECOMMENDED to use a "201
	RECOMMENDED to use a "201 (Created)" response if not otherwise		(Created)" response if not otherwise specified. The response MUST
	specified. The response MUST NOT include the "Upload-Complete"		NOT include the "Upload-Complete" header field with the value set to
	header field with the value set to false.		false.
	If the request completes successfully but the entire upload is not		If the request completes successfully but the entire upload is not
	yet complete indicated by the "Upload-Complete" field value set to		yet complete indicated by the "Upload-Complete" field value set to
	false, the server MUST acknowledge it by responding with a "201		false, the server MUST acknowledge it by responding with a "201
	(Created)" status code and the "Upload-Complete" field value set to		(Created)" status code and the "Upload-Complete" field value set to
	true.		true.
	If the request includes the "Upload-Complete" field value set to true		If the request includes the "Upload-Complete" field value set to true
	and a valid "Content-Length" header field, the client attempts to		and a valid "Content-Length" header field, the client attempts to
	upload the remaining resource in one request. In this case, the		upload the remaining resource in one request. In this case, the
	skipping to change at page 15, line 17 ¶		skipping to change at page 15, line 17 ¶
	Upload-Offset: 100		Upload-Offset: 100
	Upload-Draft-Interop-Version: 5		Upload-Draft-Interop-Version: 5
	Content-Length: 100		Content-Length: 100
	[content (100 bytes)]		[content (100 bytes)]
	HTTP/1.1 201 Created		HTTP/1.1 201 Created
	Upload-Offset: 200		Upload-Offset: 200
	The client MAY automatically attempt upload resumption when the		The client MAY automatically attempt upload resumption when the
	connection is terminated unexpectedly, or if a server error status		connection is terminated unexpectedly, or if a 5xx (Server Error)
	code between 500 and 599 (inclusive) is received. The client SHOULD		status code is received. The client SHOULD NOT automatically retry
	NOT automatically retry if a client error status code between 400 and		if a 4xx (Client Error) status code is received.
	499 (inclusive) is received.
	7. Upload Cancellation		7. Upload Cancellation
	If the client wants to terminate the transfer without the ability to		If the client wants to terminate the transfer without the ability to
	resume, it can send a "DELETE" request to the upload resource. Doing		resume, it can send a "DELETE" request to the upload resource. Doing
	so is an indication that the client is no longer interested in		so is an indication that the client is no longer interested in
	continuing the upload, and that the server can release any resources		continuing the upload, and that the server can release any resources
	associated with it.		associated with it.
	The client MUST NOT initiate cancellation without the knowledge of		The client MUST NOT initiate cancellation without the knowledge of
	skipping to change at page 22, line 14 ¶		skipping to change at page 22, line 14 ¶
	protocol. Members of the tus community helped significantly in the		protocol. Members of the tus community helped significantly in the
	process of bringing this work to the IETF.		process of bringing this work to the IETF.
	The authors would like to thank Mark Nottingham for substantive		The authors would like to thank Mark Nottingham for substantive
	contributions to the text.		contributions to the text.
	Changes		Changes
	This section is to be removed before publishing as an RFC.		This section is to be removed before publishing as an RFC.
	F.1. Since draft-ietf-httpbis-resumable-upload-02		F.1. Since draft-ietf-httpbis-resumable-upload-03
			None yet.
			F.2. Since draft-ietf-httpbis-resumable-upload-02
	o Add upload progress notifications via informational responses.		o Add upload progress notifications via informational responses.
	o Add security consideration regarding request filtering.		o Add security consideration regarding request filtering.
	o Explain the use of empty requests for creation uploads and		o Explain the use of empty requests for creation uploads and
	appending.		appending.
	o Extend security consideration to include resource exhaustion		o Extend security consideration to include resource exhaustion
	attacks.		attacks.
	o Allow 200 status codes for offset retrieval.		o Allow 200 status codes for offset retrieval.
	o Increase the draft interop version.		o Increase the draft interop version.
	F.2. Since draft-ietf-httpbis-resumable-upload-01		F.3. Since draft-ietf-httpbis-resumable-upload-01
	o Replace Upload-Incomplete header with Upload-Complete.		o Replace Upload-Incomplete header with Upload-Complete.
	o Replace terminology about procedures with HTTP resources.		o Replace terminology about procedures with HTTP resources.
	o Increase the draft interop version.		o Increase the draft interop version.
	F.3. Since draft-ietf-httpbis-resumable-upload-00		F.4. Since draft-ietf-httpbis-resumable-upload-00
	o Remove Upload-Token and instead use Server-generated upload URL		o Remove Upload-Token and instead use Server-generated upload URL
	for upload identification.		for upload identification.
	o Require the Upload-Incomplete header field in Upload Creation		o Require the Upload-Incomplete header field in Upload Creation
	Procedure.		Procedure.
	o Increase the draft interop version.		o Increase the draft interop version.
	F.4. Since draft-tus-httpbis-resumable-uploads-protocol-02		F.5. Since draft-tus-httpbis-resumable-uploads-protocol-02
	None		None
	F.5. Since draft-tus-httpbis-resumable-uploads-protocol-01		F.6. Since draft-tus-httpbis-resumable-uploads-protocol-01
	o Clarifying backtracking and preventing skipping ahead during the		o Clarifying backtracking and preventing skipping ahead during the
	Offset Receiving Procedure.		Offset Receiving Procedure.
	o Clients auto-retry 404 is no longer allowed.		o Clients auto-retry 404 is no longer allowed.
	F.6. Since draft-tus-httpbis-resumable-uploads-protocol-00		F.7. Since draft-tus-httpbis-resumable-uploads-protocol-00
	o Split the Upload Transfer Procedure into the Upload Creation		o Split the Upload Transfer Procedure into the Upload Creation
	Procedure and the Upload Appending Procedure.		Procedure and the Upload Appending Procedure.
	Authors' Addresses		Authors' Addresses
	Marius Kleidl (editor)		Marius Kleidl (editor)
	Transloadit		Transloadit
	Email: marius@transloadit.com		Email: marius@transloadit.com
End of changes. 19 change blocks.
	41 lines changed or deleted		44 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/