matrix
/
matrix-doc
mirror of https://github.com/matrix-org/matrix-doc.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
matrix-doc/proposals/2701-media-content-type.md

3.5 KiB
Raw Permalink Blame History

MSC2701: Media and the Content-Type relationship

The specification currently does not outline in great detail how Content-Type should be handled with respect to media, particularly around uploads. The POST /upload and PUT /upload/:serverName/:mediaId endpoints mention that Content-Type is a header that can be set, but does not list it as required, for example. Similarly, the Content-Type seems to entirely disappear when talking about downloads.

This proposal clarifies how the Content-Type header is used on upload and download, in line with current best practices among server implementations.

Proposal

For POST and PUT /upload, the Content-Type header becomes explicitly optional, defaulting to application/octet-stream. Synapse and MMR both implement this behaviour. Clients SHOULD always supply a Content-Type header though, as this may change in future iterations of the endpoints.

Note: Synapse's behaviour was changed in October 2021 with PR #11200. Previously, Synapse required the header.

For GET /download, the server MUST return a Content-Type which is either exactly the same as the original upload, or reasonably close. The bounds of "reasonable" are:

  • Adding a charset to text/* content types.
  • Detecting HTML and using text/html instead of text/plain.
  • Using application/octet-stream when the server determines the content type is obviously wrong. For example, an encrypted file being claimed as image/png.
  • Returning application/octet-stream when the media has an unknown/unprovided Content-Type. For example, being uploaded before the server tracked content types or when the remote server is non-compliantly omitting the header entirely.

Actions not in the spirit of the above are not considered "reasonable". Existing server implementations are encouraged to downgrade their behaviour to be in line with this guidance. Synapse already does very minimal post-processing while MMR actively ignores the uploaded Content-Type (the incorrect thing to do under this MSC).

Potential issues

Some media may have already been uploaded to a server without a content type. Such media items are returned as application/octet-stream under this proposal.

Alternatives

No significant alternatives.

Security considerations

No relevant security considerations, though server authors are encouraged to consider the impact of MSC2702 in their threat model.

Unstable prefix

This MSC is backwards compatible with existing specification and requires no particular unstable prefix. Servers are already able to implement this proposal's behaviour legally.

Additionally, cited in the proposal are examples of the behaviour being used in production today.