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

clarify Content-Type / Content-Encoding / Content-Language handling #160

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

clarify Content-Type / Content-Encoding / Content-Language handling #160

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9f96286
clarify Content-Type / Content-Encoding / Content-Language handling
nigoroll Sep 9, 2020
5b307ae
Adjust phrasing of recommended metadata keys
Acconut Sep 29, 2020
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
31 changes: 30 additions & 1 deletion protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ Kleidl](https://twitter.com/Acconut_)<br>
[J. Ryan Stinnett](https://convolv.es),
[Ifedapo Olarewaju](https://github.com/ifedapoolarewaju)
[Robert Nagy](https://github.com/ronag)
[Nils Goroll](https://github.com/nigoroll)

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
Expand Down Expand Up @@ -299,7 +300,7 @@ Host: tus.example.org
Content-Length: 0
Upload-Length: 100
Tus-Resumable: 1.0.0
Upload-Metadata: filename d29ybGRfZG9taW5hdGlvbl9wbGFuLnBkZg==,is_confidential
Upload-Metadata: filename d29ybGRfZG9taW5hdGlvbl9wbGFuLnBkZg==,filetype YXBwbGljYXRpb24vcGRm,is_confidential
```

**Response:**
Expand Down Expand Up @@ -334,6 +335,34 @@ Since metadata can contain arbitrary binary values, Servers SHOULD
carefully validate metadata values or sanitize them before using them
as header values to avoid header smuggling.

Clients and servers SHOULD implement the metadata key ``filetype``
with the value containing the actual ``Content-Type`` of the Upload
(because the ``Content-Type`` header is formally required to be set to
``application/offset+octet-stream`` for [Creation with
Upload](#creation-with-upload)).

Clients and servers MAY support additional well known metadata keys:

* ``filename`` for a common file name

The specific metadata keys documented herein are reserved for the
respective use and MUST NOT be used for other purposes.
Copy link
Member

Choose a reason for hiding this comment

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

I agree with @smatsson that this sentence is too restrictive. It would be a breaking change and there are no plans to make a major release for tus. I don't think this would serve the ecosystem well.

That being said, I am happy to recommend (not force) the usage of the filename and filetype metadata keys for the purposes as laid out here.


##### [Content-Encoding](https://httpwg.org/specs/rfc7231.html#header.content-encoding)

Clients MUST set the ``Content-Encoding`` header correctly IFF a
content encoding is used.

As per RFC7231, Servers MUST respond with status 415 if they can not
accept the ``Content-Encoding`` chosen by the client.

Servers MUST either store the ``Content-Encoding`` and deliver it with
subsequent requests, or properly decode the content before storing it.
Copy link
Member

Choose a reason for hiding this comment

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

deliver it with subsequent requests

Does this mean that the Content-Encoding header must be present in the response for every PATCH, DELETE and HEAD request?


##### [Content-Language](https://httpwg.org/specs/rfc7231.html#header.content-language)

Clients and Servers SHOULD support the ``Content-Language`` header.
Copy link
Member

Choose a reason for hiding this comment

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

Can you elaborate more what "supporting the Content-Language header" means? To be concrete: Can you say what behavior a typical tus server (e.g. tusd) must have to support this header?


#### Requests

##### POST
Expand Down