From f263796f7f1e1f58ac85521a27ebf4ba655f7e0c Mon Sep 17 00:00:00 2001 From: Matan Bendix Shenhav Date: Tue, 24 Jun 2025 17:20:27 +0300 Subject: [PATCH] Add html table to provide a protocol overview The protocol specification is complex, and I found that as an implementer I benefited from a visual overview. --- protocol.md | 263 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 262 insertions(+), 1 deletion(-) diff --git a/protocol.md b/protocol.md index adfc433..15c4ebc 100644 --- a/protocol.md +++ b/protocol.md @@ -50,6 +50,10 @@ 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](http://www.ietf.org/rfc/rfc2119.txt). +The main text of this document specificies the normative definition of the +protocol, but we offer an [overview table appendix](#appendix-overview-table) +the visualizes the headers and endpoints of the core protocol and its extensions. + ## Status Following [SemVer](http://semver.org), as of 1.0.0 tus is ready for general @@ -223,7 +227,7 @@ match, the Server MUST respond with the `409 Conflict` status without modifying the upload resource. The Client SHOULD send all the remaining bytes of an upload in a single `PATCH` -request, but MAY also use multiple small requests successively for scenarios +request, but MAY also use multipl requests successively for scenarios where this is desirable. One example for these situations is when the [Checksum](#checksum) extension is used. @@ -742,6 +746,263 @@ Upload-Length: 11 Upload-Concat: final;/files/a /files/b ``` +## Appendix: Overview Table + +> [!important] +> This section is non-normative, and is only included the clarify the primary protocol definition above. + +The following table summarizes which headers are required or optional for each HTTP method in the core protocol and its extensions; scroll to the bottom of the table for a legend. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Methods ➡️💚 HEAD💚 PATCH💚 OPTIONS✨ POST🗑️ DELETE
⬇️ HeadersRetrieve current state for resumingUpload a data chunkDiscover server capabilitiesCreate new uploadTerminate an existing upload
+ 💚 Tus-Resumable +
Protocol version + 		+ ✅ Req
+ ✅ Resp + 		+ ✅ Req
+ ✅ Resp + 		+ + ✅ Req
+ ✅ Resp + 		+ ✅ Req
+ ✅ Resp +
+ 💚 Upload-Offset +
Byte offset within upload + 		✅ Resp + ✅ Req
+ ✅ Resp + 		☑️ Resp1
+ 💚 Upload-Length +
Total upload size in bytes + 		☑️ Resp2☑️ Req3☑️ Req4
💚 Tus-Version
Supported protocol versions		☑️ Resp 5☑️ Resp 5✅ Resp☑️ Resp 5☑️ Resp 5
💚 Tus-Extension
Supported extensions		☑️ Resp☑️ Resp☑️ Resp☑️ Resp☑️ Resp
💚 Tus-Max-Size
Maximum upload size		☑️ Resp☑️ Resp☑️ Resp☑️ Resp☑️ Resp
💚 X-HTTP-Method-Override
Method override for limited clients		☑️ Req☑️ Req☑️ Req☑️ Req☑️ Req
💚 Content-Type
Media type of request body		 + ✅ Req12
+ ✅ Resp12 + 		+ ☑️ Req13
+ ☑️ Resp13 +
+ 💚 Cache-Control +
Caching directive + 		✅ Resp 14
+ ✨ Upload-Defer-Length +
Size not yet known + 		☑️ Resp6☑️ Req3☑️ Req4
+ ✨ Upload-Metadata +
Key-value pairs + 		☑️ Resp7☑️ Req
+ ✨ Location +
URL of created resource + 		✅ Resp
+ ⏳ Upload-Expires +
Expiration time + 		☑️ Resp8☑️ Resp8
+ 🔍 Upload-Checksum +
Data integrity + 		☑️ Req
+ 🔍 Tus-Checksum-Algorithm +
Supported algorithms + 		☑️ Resp9
+ ⛓️ Upload-Concat +
Concatenation info + 		☑️ Resp10☑️ Req11


Legend
+ Requirements: +
    +
  • ✅ Required
    • +
  • ☑️ Optional
    • +
+ 		+ Notes: +
    +
  1. Only included when using Creation With Upload extension
    2. +
  2. Included if size is known
    3. +
  3. Required if length was deferred in creation
    4. +
  4. Either Upload-Length or Upload-Defer-Length must be included
    5. +
  5. Required only for 412 Precondition Failed responses
    6. +
  6. Included if length was deferred
    7. +
  7. Included if metadata was provided during creation
    8. +
  8. Included if upload has expiration (requires Expiration extension)
    9. +
  9. Included if Checksum extension is supported
    10. +
  10. Included if upload is partial or final (requires Concatenation extension)
    11. +
  11. Required for partial/final uploads (requires Concatenation extension)
    12. +
  12. Must be `application/offset+octet-stream`
    13. +
  13. Must be `application/offset+octet-stream` when body contains upload data
    14. +
  14. Must be `no-store`
    15. +
+
+ Modules: +
    +
  • 💚 Core protocol
    • +
  • ⏳ Expiration extension
    • +
  • ✨ Creation extension
    • +
  • 🗑️ Termination extension
    • +
  • 🔍 Checksum extension
    • +
  • ⛓️ Concatanation extension
    • +
+
+ ## FAQ The FAQ is available online at .