Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add Tus-Min/Max-Chunk-Size headers #93

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add Tus-Min/Max-Chunk-Size headers #93

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 29 additions & 4 deletions protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would place "in bytes" more to the front: indicating the recommended minimum size in bytes of a single chunk... Remove 'in bytes' at the end.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MAY represent a hard limit but also MAY be a recommendation is there a way we can be less ambiguous? As an implementor, I would be confused what to do here. Could the protocol make a recommendation, e.g. via SHOULD/but MAY

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hard limit, but also MAY

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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See first note. ... recommended minimum size 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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or if the used architecture does not allow the body of the 'PATCH' request to be streamed.

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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hard limit, but also

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
Expand Down Expand Up @@ -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.
Expand All @@ -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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should is in lower case here. Intended?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's intentional, because it's just a description of an example, not part of the specification.

500MB. Furthermore, the [Creation](#creation) and [Expiration](#expiration)
extensions are enabled.

**Request:**

Expand All @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume the Min is left out on purpose here to indicate these are options, correct?

Tus-Extension: creation,expiration
```

Expand Down