[译]Tus 协议

原文地址：https://tus.io/protocols/resumable-upload.html

摘要

该协议提供一种基于 HTTP/1.1 和 HTTP/2 机制用于文件断点续传。

核心协议

核心协议描述如何继续中断的上传。这里假定你已经有一个用于上传的 RUL ，这个 URL 通常是由扩展协议 Creation创建。

所有客户端和服务端必须实现核心协议。

协议没有描述 RUL 的结构，而是留给协议的实现来决定。本文中所有展示的 URL 仅用于举例。

此外，认证和授权的实现也留给服务端来决定。

示例

用一个请求头指明应当从什么地方开始续传上传。

以下示例展示中断位置由70变为100

请求

HEAD /files/24e533e02ec3bc40c387f1a0e460e216 HTTP/1.1

Host: tus.example.org

Tus-Resumable: 1.0.0

响应

HTTP/1.1 200 OK

Upload-Offset: 70

Tus-Resumable: 1.0.0

对于给定的中断位置，客户端使用 PATCH 方法来续传。

请求

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]

响应

HTTP/1.1 204 No Content

Tus-Resumable: 1.0.0

Upload-Offset: 100

报文头

Upload-Offset【上传偏移位置】

请求和响应中的上传便宜位置表明资源的字节偏移量。该值必须是一个非负整数。

Upload-Length【上传长度】

请求和响应中的上传长度表明资源的字节数【不是一次请求上传的字节数】，该值必须是非负整数。

Tus-Version【协议版本】

响应头中的协议版本值必须是由逗号分隔的服务器支持的协议列表，列表中的第一个必须是服务器最希望的版本。

Tus-Resumable

Tus-Resumable 头除了 OPTIONS 请求外，每次请求和响应必须指明。Tus-Resumable

值必须是客户端和服务器正在使用的协议版本。【更具体的说就是当前请求和响应使用的协议版本】

如果服务端不支持客户端发过来的协议版本，服务端必须响应 412 Precondition Failed 状态，并且响应头中必须包括 Tus-Resumable，另外，服务端必须不处理这个请求。

Tus-Extension【扩展协议】

响应头中的 Tus-Extension 值必须是有逗号分隔服务端支持的扩展协议的列表。如果服务端不支持扩展协议，则这个头应当去掉。

Tus-Max-Size

协议头中的 Tus-Max-Size 值必须是非负整数用以表明整个上传最大允许的字节数【原文字面理解是上传资源的最大限制字节数，不是一次请求的最大限制字节数】，服务端如果有硬性限制应当在这个头中表明。

X-HTTP-Method-Override

如果这个请求头有值，则服务端必须使用这个值当做请求方法【Method】，而当前请求的实际请求方法必须忽略。客户端应当在其不支持 PATCH 或 DELETE 方法时使用该请求头。【这个头不是tus 创建的，http 原本就有，举个例子：客户端不能发生 PATCH 请求，于是发送一个 Get 请求，在 X-HTTP-Method-Override 头中设置值为 PATCH ，这个服务端就知道客户端想发的是 PATCH 请求】

请求

HEAD

服务端在接收到 HEAD 请求后，其必须总是在响应头中包含 Upload-Offset 表明上传偏移位置，即便偏移位置是 0，或上传已经完成。如果知道上传资源的长度，服务端必须在 Upload-Length 指明长度。如果服务端没有找到上传的资源，服务端应当返回 404 Not Found、410 Gone 或 403 Forbidden，且没有 Upload-Offset 头。

服务端必须在响应头中包含 Cache-Control: no-store 来阻止客户端或客户端代理从缓存中获取响应。

PATCH

服务端应当接受任何 PATCH 上传请求，并且将请求体中的内容放在 Upload-Offse 头指示的位置后。使用 PATCH 请求必须使用 Content-Type: application/offset+octet-stream 请求头，否则服务端应当响应 415 Unsupported Media Type 状态。

Upload-Offset 报文头的值必须与资源的偏移量相等。出于并行上传考虑，可以使用 Concatenation 扩展协议。如果上传偏移量与资源实际偏移不相同，服务端应当返回 409 Conflict 状态，且不修改资源。

如果 PATCH 请求没有包含 Content-Length 头，或者 Content-Length 值不是非负整数，服务端应当返回 400 Bad Request 状态。

客户端应当在一个 PATCH 请求中发送所有未发送的字节，但是可能存在发送多个较小的请求的场景。一个这样的示例是使用了 Checksum 扩展协议。

服务端必须响应 204 No Content 状态来表明成功处理 PATCH 请求。响应必须包含 Upload-Offset 报文头，当然必须使用更新后的值。更新后的值必须是上一个请求偏移量和接收内容的和。

如果服务端接收到一个不存在资源的 PATCH 请求，应当返回 404 Not Found 状态。

客户端和服务器应当尝试检测和处理可预见的网络错误，比如读写 socket 错误和读写超时，当连接超时应当关闭底层连接。

服务端应当总是尝试存储尽可能多接收数据。

OPTIONS

一个 OPTIONS 请求可能被用于收集服务端当前的配置，一个成功的响应应当返回 204 No Content 或 200 OK 状态，并且必须包含 Tus-Version 响应头，它可能包含 Tus-Extension 和 Tus-Max-Size 头。

示例

请求

OPTIONS /files HTTP/1.1

Host: tus.example.org

响应

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-Extension: creation,expiration

扩展协议

待补充