From 7441bc1a60d87d627cc09f97808d4350e5c03107 Mon Sep 17 00:00:00 2001 From: Marius Date: Tue, 30 Aug 2016 15:23:01 +0200 Subject: [PATCH] Add Tus-Min/Max-Chunk-Size headers See #89 for the underlying discussion --- protocol.md | 33 +++++++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/protocol.md b/protocol.md index 3cfc9ee..103e603 100644 --- a/protocol.md +++ b/protocol.md @@ -182,6 +182,29 @@ The `Tus-Max-Size` response header MUST be a non-negative integer indicating the allowed size of an entire upload in bytes. The Server SHOULD set this header if there is a known hard limit. +#### Tus-Min-Chunk-Size + +The `Tus-Min-Chunk-Size` response header MUST be a non-negative integer indicating the +recommended minimum size of a single chunk uploaded in a single `PATCH` request in bytes. +The Server MAY set this recommendation if the underlying storage engine has a lower limit +on how much data can be stored in a single take. The Client SHOULD use this number to +determine in conjunction with other factors, such as the available bandwidth and the +`Tus-Max-Chunk-Size` header, how much data SHOULD be transfered in one request. Furthermore, +this header's value MAY represent a hard limit but also MAY be a recommendation. The Server +SHOULD only set this header if it has this recommendation. + +#### Tus-Max-Chunk-Size + +The `Tus-Max-Chunk-Size` response header MUST be a non-negative integer indicating the +recommended maximum size of a single chunk uploaded in a single `PATCH` request in bytes. +The Server MAY set this recommendation if the underlying storage engine has an upper limit +on how much data can be stored in a single take or if the used architecture does not allow +streaming the body of the `PATCH` request. The Client SHOULD use this number to determine +in conjunction with other factors, such as the available bandwidth and the +`Tus-Min-Chunk-Size` header, how much data SHOULD be transfered in one request. Furthermore, +this header's value MAY represent a hard limit but also MAY be a recommendation. The Server +SHOULD only set this header if it has this recommendation. + #### X-HTTP-Method-Override The `X-HTTP-Method-Override` request header MUST be a string which MUST be @@ -237,8 +260,8 @@ The Server SHOULD always attempt to store as much of the received data as possib An `OPTIONS` request MAY be used to gather information about the Server's current configuration. A successful response indicated by the `204 No Content` status -MUST contain the `Tus-Version` header. It MAY include the `Tus-Extension` and -`Tus-Max-Size` headers. +MUST contain the `Tus-Version` header. It MAY include the `Tus-Extension`, +`Tus-Max-Size`, `Tus-Min-Chunk-Size` and `Tus-Max-Chunk-Size` headers. The Client SHOULD NOT include the `Tus-Resumable` header in the request and the Server MUST ignore the header. @@ -248,8 +271,9 @@ Server MUST ignore the header. This example clarifies the response for an `OPTIONS` request. The version used in both, request and response, is `1.0.0` while the Server is also capable of handling `0.2.2` and `0.2.1`. Uploads with a total size of up to 1GB are -allowed and the extensions for [Creation](#creation) and -[Expiration](#expiration) are enabled. +allowed and the Server recommends that a single chunk should be smaller than +500MB. Furthermore, the [Creation](#creation) and [Expiration](#expiration) +extensions are enabled. **Request:** @@ -266,6 +290,7 @@ HTTP/1.1 204 No Content Tus-Resumable: 1.0.0 Tus-Version: 1.0.0,0.2.2,0.2.1 Tus-Max-Size: 1073741824 +Tus-Max-Chunk-Size: 524288000 Tus-Extension: creation,expiration ```