原文地址: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
扩展协议
待补充