tus-一个可续传文件上传的开放协议

Posted 2022-04-07 pangjianxin

tus

tus是一个可续穿文件上传协议，它以Http协议为载体，统一了一个文件断点续传的标准。

这篇文章翻译自https://tus.io/

目前该协议版本信息如下：

Version: 1.0.0 (SemVer)
Date: 2016-03-25
Authors: Felix Geisendörfer, Kevin van Zonneveld, Tim Koschützki, Naren Venkataraman, Marius Kleidl
Collaborators: Bruno de Carvalho, James Butler, Øystein Steimler, Sam Rijs, Khang Toh, Jacques Boscq, Jérémy FRERE, Pieter Hintjens, Stephan Seidt, Aran Wilkinson, Svein Ove Aas, Oliver Anan, Tim, j4james, Julian Reschke, Evert Pot, Jochen Kupperschmidt, Andrew Fenn, Kevin Swiber, Jan Kohlhof, eno, Luke Arduini, Jim Schmid, Jeffrey ‘jf’ Lim, Daniel Lopretto, Mark Murphy, Peter Darrow, Gargaj, Tomasz Rydzyński, Tino de Bruijn, Jonas mg, Christian Ulbrich, Jon Gjengset, Michael Elovskikh, Rick Olson, J. Ryan Stinnett, Ifedapo Olarewaju Robert Nagy

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

状态

在SemVer（https://semver.org/）之后，从1.0.0开始，tus就可以被广泛采用了。我们不期望做出破坏性的更改，但是如果我们这样做了，这些更改就必须在2.0.0中。引入一个新的扩展或任何向后兼容的更改，添加新的功能，都会导致一个意外的次要版本。

SemVer：Semantic Versioning 2.0.0是一个语义版本控制，Tus协议采用了这个协议，我也不知道这个协议到底他妈的是干啥的。困惑中。

贡献

这个协议由Tus社区创建，并归属于Tus社区，欢迎通过Github来提交协议的补丁和反馈意见，所有的作者和贡献者的名字都会在协议的开头列出。

如果你有开源的或者商业的任何关于该协议的实现想要列在我们的官方网站上（implementations），请一定让我们知道（let us know）。

摘要

协议通过 HTTP/1.1 (RFC 7230) 和 HTTP/2 (RFC 7540)提供了支持文件断点恢复上传的机制和原理。

注意

被方括号包起来的字符表示一个占位符（例如[size])。

术语空格、逗号和分号指的是它们的ASCII表示形式。

核心协议

核心协议描述了如何恢复一个中断了的上传操作。它假设你已经有了一个上传的URL，这个URl通常是由Creation扩展来创建的。（Creation扩展会在下面介绍）

客户端协议和服务端协议必须（MUST)实现核心协议。

这个规范没有描述url的结构，因为这是留给特定实现来决定的。本文档中显示的所有url仅用于示例目的。

另外，认证和授权的部分也由服务端实现来决定。

例子

HEAD请求用于确定应该继续上传的偏移量。

下面的例子展示了100字节的内容在上传了70之后被中断然后续传的情形

Request:

HEAD /files/24e533e02ec3bc40c387f1a0e460e216 HTTP/1.1
Host: tus.example.org
Tus-Resumable: 1.0.0

Response:

HTTP/1.1 200 OK
Upload-Offset: 70
Tus-Resumable: 1.0.0

给定偏移量，客户端使用PATCH Method恢复上传:

Request:

PATCH /files/24e533e02ec3bc40c387f1a0e460e216 HTTP/1.1
Host: tus.example.org
Content-Type: application/offset+octet-stream
Content-Length: 30
Upload-Offset: 70
Tus-Resumable: 1.0.0

[remaining 30 bytes]

Response:

HTTP/1.1 204 No Content
Tus-Resumable: 1.0.0
Upload-Offset: 100

HEADERS 头

Upload-Offset

通用头，可以用在请求和响应中，它必须（MUST）是一个非负的整数。它指示上传资源中的字节偏移量。

Upload-Length

通用头，可以用在请求或响应中，它必须（MUST）是一个非负整数，它指示所要上传的资源的大小。

Tus-Version

响应头，它必须是一个服务端支持的以逗号分隔的协议版本列表。这个列表必须（MUST）按照服务端推荐程序排序，其中，列表中所列出的第一项是最为推荐的协议版本。

Tus-Resumable

通用头，这个头是除了OPTION Method请求之外必须包含在每一个请求和响应中的头。它的值必须（MUST）是客户端和服务端都使用的一个版本号。

如果客户端中指定的版本号不被服务端支持，服务端必须（MUST）返回412 Precondition Failed状态码并且必须（MUST）包含Tus-Resumable头。此外，服务端必须不能（MUST NOT）处理请求。

Tus-Extension

响应头，这个头必须（MUST）是一个服务端支持的逗号分隔的可扩展功能的列表，如果服务端没有任何扩展功能支持，那么这个头必须（MUST）省略。

Tus-Max-Size

响应头，它必须是一个非负整数，以字节为单位指示整个上载的最大允许大小。如果存在已知的硬性限制，服务器应该（SHOULD）设置此头。

X-HTTP-Method-Override

请求头,如果该请求头出现了，它必须(MUST)是一个字符串，服务器必须(MUST)将其解释为请求的方法。而真正的请求方法必须被忽略。当客户端环境不允许使用PATCH 或 DELETE 等方法时，客户端应该（SHOULD）使用这个头。

请求

HEAD

对于HEAD请求，服务端相应必须（MUST）包含Upload-Offset头，甚至当Upload-Offset是0或者上传过程已结束的情况下也应该包含。在上传大小已知的情况下，服务端响应必须（MUST）包含Upload-Length头。如果资源未发现（意味着Upload-Offset无效），服务端响应应该（SHOULD）返回404 Not Found, 410 Gone 或 403 Forbidden状态码中的一个。

服务端必须（MUST）通过添加Cache-Control: no-store头来防止客户端和/或代理缓存响应。

PATCH

服务端应该（SHOULD）支持任何使用上传URL的path method请求并应用请求消息中Upload-Offset头指定的偏移量。所有的PATCH请求必须包含Content-Type: application/offset+octet-stream，否则服务端会返回415 Unsupported Media Type状态码。

Upload-Offset头的值必须和当前上传资源的偏移量相等，为了实现并行上传，可以使用连接扩展（Concatenation）。如果偏移量不匹配，服务器必须以409 Conflict状态响应，而不修改上载资源。

客户机应该在单个补丁请求中发送上载的所有剩余字节，但也可以在需要的情况下连续使用多个小请求。这些情况的一个例子是使用Checksum扩展。

服务器必须以204 No Content状态确认成功的PATCH请求。它必须包含Upload-Offset头用于表示的新的偏移量。新偏移量必须是PATCH请求之前的偏移量和当前PATCH请求期间接收和处理或存储的字节数之和。

如果服务器接收到针对不存在资源的PATCH请求，它应该返回404 Not Found状态。

客户机和服务器都应该尝试检测和处理可预测的网络错误。他们可以通过检查读/写socket(套接字)错误，以及设置读/写超时来做到这一点。应该（SHOULD）通过关闭底层连接来处理超时。

服务器应该总是尝试存储尽可能多的接收数据。