[译]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

扫描二维码关注公众号,回复: 2677418 查看本文章

响应

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

扩展协议

待补充

猜你喜欢

转载自www.cnblogs.com/850391642c/p/tus-Protocol.html