From 8514ca190296dd2446f35a49988ec037aabb2cff Mon Sep 17 00:00:00 2001 From: Marius Date: Thu, 30 Jun 2016 22:29:27 +0200 Subject: [PATCH 1/5] Add first draft of the Creation With Chunk functionality --- protocol.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/protocol.md b/protocol.md index c0cda48..8df7b56 100644 --- a/protocol.md +++ b/protocol.md @@ -351,6 +351,20 @@ If the length of the upload exceeds the maximum, which MAY be specified using the `Tus-Max-Size` header, the Server MUST respond with the `413 Request Entity Too Large` status. +The Client MAY include the entire or a chunk of the data, which is meant to be +uploaded, in the body of the `POST` request. In this case, similar rules as for +the `PATCH` request and response apply. The Client MUST include the +`Content-Type: application/offset+octet-stream` header. The Server SHOULD accept +as many bytes as possible and MUST include the `Upload-Offset` in the response +and MUST set its value to the offset of the upload after applying the accepted +bytes. If the Server supports the functionality described in this paragraph, it +MUST advertise this by including the `creation-with-chunk` value to the +`Tus-Extension` header. The Client SHOULD verify that the Server is capable of +handling this cases before sending the `POST` request. In addition, the Client +SHOULD include the `Expect: 100-continue` header in the request to receive +early feedback from the Server whether it will accept the creation request +before attempting to transfer the first chunk. + The Server MUST acknowledge a successful upload creation with the `201 Created` status. The Server MUST set the `Location` header to the URL of the created resource. This URL MAY be absolute or relative. From e9fdbd491b53891bcc77dcb09a27a164e2d54f77 Mon Sep 17 00:00:00 2001 From: Marius Date: Fri, 22 Jul 2016 09:57:45 +0200 Subject: [PATCH 2/5] Improve wording of Create With Upload extension --- protocol.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/protocol.md b/protocol.md index 8df7b56..ef93bf9 100644 --- a/protocol.md +++ b/protocol.md @@ -351,18 +351,18 @@ If the length of the upload exceeds the maximum, which MAY be specified using the `Tus-Max-Size` header, the Server MUST respond with the `413 Request Entity Too Large` status. -The Client MAY include the entire or a chunk of the data, which is meant to be -uploaded, in the body of the `POST` request. In this case, similar rules as for -the `PATCH` request and response apply. The Client MUST include the +The Client MAY include the entire upload data or a chunk of it in the body of +the `POST` request. In this case, similar rules as for the `PATCH` request and +response apply. The Client MUST include the `Content-Type: application/offset+octet-stream` header. The Server SHOULD accept as many bytes as possible and MUST include the `Upload-Offset` in the response and MUST set its value to the offset of the upload after applying the accepted bytes. If the Server supports the functionality described in this paragraph, it MUST advertise this by including the `creation-with-chunk` value to the -`Tus-Extension` header. The Client SHOULD verify that the Server is capable of -handling this cases before sending the `POST` request. In addition, the Client +`Tus-Extension` header. The Client SHOULD verify that the Server supports this +extension before sending the `POST` request. In addition, the Client SHOULD include the `Expect: 100-continue` header in the request to receive -early feedback from the Server whether it will accept the creation request +early feedback from the Server, whether it will accept the creation request, before attempting to transfer the first chunk. The Server MUST acknowledge a successful upload creation with the `201 Created` From e31012e6efd9ee53d9c489ed6b8232c22defb6db Mon Sep 17 00:00:00 2001 From: Marius Date: Sun, 28 Aug 2016 21:59:41 +0200 Subject: [PATCH 3/5] Move Creation With Upload into own section --- protocol.md | 61 +++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 50 insertions(+), 11 deletions(-) diff --git a/protocol.md b/protocol.md index ef93bf9..6c1f3ec 100644 --- a/protocol.md +++ b/protocol.md @@ -351,25 +351,64 @@ If the length of the upload exceeds the maximum, which MAY be specified using the `Tus-Max-Size` header, the Server MUST respond with the `413 Request Entity Too Large` status. +The Server MUST acknowledge a successful upload creation with the `201 Created` +status. The Server MUST set the `Location` header to the URL of the created +resource. This URL MAY be absolute or relative. + +The Client MUST perform the actual upload using the core protocol. + +### Creation With Upload + +The Client MAY want to include parts of the upload in the initial Creation +request. This MAY be achieved using the Creation With Upload extension. + +If the Server supports this extension, it MUST advertise this by including +`creation-with-chunk` in the `Tus-Extension` header. Furthermore, this extension +depends directly on the Creation extension. Therefore, if the Server does not +offer the Creation extension, it MUST NOT offer the Creation With Upload +extension either. + The Client MAY include the entire upload data or a chunk of it in the body of the `POST` request. In this case, similar rules as for the `PATCH` request and response apply. The Client MUST include the `Content-Type: application/offset+octet-stream` header. The Server SHOULD accept as many bytes as possible and MUST include the `Upload-Offset` in the response and MUST set its value to the offset of the upload after applying the accepted -bytes. If the Server supports the functionality described in this paragraph, it -MUST advertise this by including the `creation-with-chunk` value to the -`Tus-Extension` header. The Client SHOULD verify that the Server supports this -extension before sending the `POST` request. In addition, the Client -SHOULD include the `Expect: 100-continue` header in the request to receive -early feedback from the Server, whether it will accept the creation request, -before attempting to transfer the first chunk. +bytes. -The Server MUST acknowledge a successful upload creation with the `201 Created` -status. The Server MUST set the `Location` header to the URL of the created -resource. This URL MAY be absolute or relative. +The Client SHOULD verify that the Server supports this extension before sending +the `POST` request. In addition, the Client SHOULD include the +`Expect: 100-continue` header in the request to receive early feedback from the +Server, whether it will accept the creation request, before attempting to +transfer the first chunk. + +#### Example + +A non-empty `POST` request is used to create a new upload resource. The +`Upload-Offset` header in the response indicates how much data has been accepted. + +**Request:** + +``` +POST /files HTTP/1.1 +Host: tus.example.org +Content-Length: 5 +Upload-Length: 100 +Tus-Resumable: 1.0.0 +Content-Type: application/offset+octet-stream + +hello +``` + +**Response:** + +``` +HTTP/1.1 201 Created +Location: https://tus.example.org/files/24e533e02ec3bc40c387f1a0e460e216 +Tus-Resumable: 1.0.0 +Upload-Offset: 5 +``` -The Client MUST perform the actual upload using the core protocol. ### Expiration From 2cf1ec953d46fbd1e5826d8c19bcebd5d2e54ecd Mon Sep 17 00:00:00 2001 From: Marius Date: Sun, 28 Aug 2016 22:01:18 +0200 Subject: [PATCH 4/5] Rename Creation With Upload value in Tus-Extension --- protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/protocol.md b/protocol.md index 6c1f3ec..a3f50ab 100644 --- a/protocol.md +++ b/protocol.md @@ -363,7 +363,7 @@ The Client MAY want to include parts of the upload in the initial Creation request. This MAY be achieved using the Creation With Upload extension. If the Server supports this extension, it MUST advertise this by including -`creation-with-chunk` in the `Tus-Extension` header. Furthermore, this extension +`creation-with-upload` in the `Tus-Extension` header. Furthermore, this extension depends directly on the Creation extension. Therefore, if the Server does not offer the Creation extension, it MUST NOT offer the Creation With Upload extension either. From 0ed3a96dd8006cf6148716fd4b0ea556fd9790b1 Mon Sep 17 00:00:00 2001 From: Marius Date: Fri, 2 Sep 2016 22:29:33 +0200 Subject: [PATCH 5/5] Apply suggestions from @kvz and @AJvanLoon --- protocol.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/protocol.md b/protocol.md index a3f50ab..d5e5e9c 100644 --- a/protocol.md +++ b/protocol.md @@ -359,8 +359,8 @@ The Client MUST perform the actual upload using the core protocol. ### Creation With Upload -The Client MAY want to include parts of the upload in the initial Creation -request. This MAY be achieved using the Creation With Upload extension. +The Client MAY include parts of the upload in the initial Creation request +using the Creation With Upload extension. If the Server supports this extension, it MUST advertise this by including `creation-with-upload` in the `Tus-Extension` header. Furthermore, this extension @@ -368,19 +368,19 @@ depends directly on the Creation extension. Therefore, if the Server does not offer the Creation extension, it MUST NOT offer the Creation With Upload extension either. -The Client MAY include the entire upload data or a chunk of it in the body of +The Client MAY include either the entirety or a chunk of the upload data in the body of the `POST` request. In this case, similar rules as for the `PATCH` request and response apply. The Client MUST include the `Content-Type: application/offset+octet-stream` header. The Server SHOULD accept -as many bytes as possible and MUST include the `Upload-Offset` in the response -and MUST set its value to the offset of the upload after applying the accepted -bytes. - -The Client SHOULD verify that the Server supports this extension before sending -the `POST` request. In addition, the Client SHOULD include the -`Expect: 100-continue` header in the request to receive early feedback from the -Server, whether it will accept the creation request, before attempting to -transfer the first chunk. +as many bytes as possible and MUST include the `Upload-Offset` header in the +response and MUST set its value to the offset of the upload after applying the +accepted bytes. + +If the Client wants to use this extension, the Client SHOULD verify that it is +supported by the Server before sending the `POST` request. +In addition, the Client SHOULD include the `Expect: 100-continue` header in +the request to receive early feedback from the Server on whether it will accept +the creation request, before attempting to transfer the first chunk. #### Example