Skip to content

Commit f263796

Browse files
ixxieixxie
committed
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.
1 parent e6b9a98 commit f263796

File tree

1 file changed

+262
-1
lines changed

1 file changed

+262
-1
lines changed

‎protocol.md‎

Lines changed: 262 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,10 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
5050
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
5151
interpreted as described in [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt).
5252

53+
The main text of this document specificies the normative definition of the
54+
protocol, but we offer an [overview table appendix](#appendix-overview-table)
55+
the visualizes the headers and endpoints of the core protocol and its extensions.
56+
5357
## Status
5458

5559
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
223227
the upload resource.
224228

225229
The Client SHOULD send all the remaining bytes of an upload in a single `PATCH`
226-
request, but MAY also use multiple small requests successively for scenarios
230+
request, but MAY also use multipl requests successively for scenarios
227231
where this is desirable. One example for these situations is when the
228232
[Checksum](#checksum) extension is used.
229233

@@ -742,6 +746,263 @@ Upload-Length: 11
742746
Upload-Concat: final;/files/a /files/b
743747
```
744748

749+
## Appendix: Overview Table
750+
751+
> [!important]
752+
> This section is non-normative, and is only included the clarify the primary protocol definition above.
753+
754+
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.
755+
756+
<table>
757+
<thead>
758+
<tr>
759+
<th>Methods ➡️</th>
760+
<th><strong>💚 HEAD</strong></th>
761+
<th><strong>💚 PATCH</strong></th>
762+
<th><strong>💚 OPTIONS</strong></th>
763+
<th><strong>✨ POST</strong></th>
764+
<th><strong>🗑️ DELETE</strong></th>
765+
</tr>
766+
</thead>
767+
<tbody>
768+
<tr>
769+
<td>⬇️ Headers</td>
770+
<td>Retrieve current state for resuming</td>
771+
<td>Upload a data chunk</td>
772+
<td>Discover server capabilities</td>
773+
<td>Create new upload</td>
774+
<td>Terminate an existing upload</td>
775+
</tr>
776+
<tr>
777+
<td>
778+
<strong>💚 Tus-Resumable</strong>
779+
<br>Protocol version
780+
</td>
781+
<td>
782+
✅ Req<br>
783+
✅ Resp
784+
</td>
785+
<td>
786+
✅ Req<br>
787+
✅ Resp
788+
</td>
789+
<td>
790+
</td>
791+
<td>
792+
✅ Req<br>
793+
✅ Resp
794+
</td>
795+
<td>
796+
✅ Req<br>
797+
✅ Resp
798+
</td>
799+
</tr>
800+
<tr>
801+
<td>
802+
<strong>💚 Upload-Offset</strong>
803+
<br>Byte offset within upload
804+
</td>
805+
<td>✅ Resp</td>
806+
<td>
807+
✅ Req<br>
808+
✅ Resp
809+
</td>
810+
<td></td>
811+
<td>☑️ Resp<sup>1</sup></td>
812+
<td></td>
813+
</tr>
814+
<tr>
815+
<td>
816+
<strong>💚 Upload-Length</strong>
817+
<br>Total upload size in bytes
818+
</td>
819+
<td>☑️ Resp<sup>2</sup></td>
820+
<td>☑️ Req<sup>3</sup></td>
821+
<td></td>
822+
<td>☑️ Req<sup>4</sup></td>
823+
<td></td>
824+
</tr>
825+
<tr>
826+
<td><strong>💚 Tus-Version</strong><br>Supported protocol versions</td>
827+
<td>☑️ Resp <sup>5</sup></td>
828+
<td>☑️ Resp <sup>5</sup></td>
829+
<td>✅ Resp</td>
830+
<td>☑️ Resp <sup>5</sup></td>
831+
<td>☑️ Resp <sup>5</sup></td>
832+
</tr>
833+
<tr>
834+
<td><strong>💚 Tus-Extension</strong><br>Supported extensions</td>
835+
<td>☑️ Resp</td>
836+
<td>☑️ Resp</td>
837+
<td>☑️ Resp</td>
838+
<td>☑️ Resp</td>
839+
<td>☑️ Resp</td>
840+
</tr>
841+
<tr>
842+
<td><strong>💚 Tus-Max-Size</strong><br>Maximum upload size</td>
843+
<td>☑️ Resp</td>
844+
<td>☑️ Resp</td>
845+
<td>☑️ Resp</td>
846+
<td>☑️ Resp</td>
847+
<td>☑️ Resp</td>
848+
</tr>
849+
<tr>
850+
<td><strong>💚 X-HTTP-Method-Override</strong><br>Method override for limited clients</td>
851+
<td>☑️ Req</td>
852+
<td>☑️ Req</td>
853+
<td>☑️ Req</td>
854+
<td>☑️ Req</td>
855+
<td>☑️ Req</td>
856+
</tr>
857+
<tr>
858+
<td><strong>💚 Content-Type</strong><br>Media type of request body</td>
859+
<td></td>
860+
<td>
861+
✅ Req<sup>12</sup><br>
862+
✅ Resp<sup>12</sup>
863+
</td>
864+
<td></td>
865+
<td>
866+
☑️ Req<sup>13</sup><br>
867+
☑️ Resp<sup>13</sup>
868+
</td>
869+
<td></td>
870+
</tr>
871+
<tr>
872+
<td>
873+
<strong>💚 Cache-Control</strong>
874+
<br>Caching directive
875+
</td>
876+
<td>✅ Resp <sup>14</sup></td>
877+
<td></td>
878+
<td></td>
879+
<td></td>
880+
<td></td>
881+
</tr>
882+
<tr>
883+
<td>
884+
<strong>✨ Upload-Defer-Length</strong>
885+
<br>Size not yet known
886+
</td>
887+
<td>☑️ Resp<sup>6</sup></td>
888+
<td>☑️ Req<sup>3</sup></td>
889+
<td></td>
890+
<td>☑️ Req<sup>4</sup></td>
891+
<td></td>
892+
</tr>
893+
<tr>
894+
<td>
895+
<strong>✨ Upload-Metadata</strong>
896+
<br>Key-value pairs
897+
</td>
898+
<td>☑️ Resp<sup>7</sup></td>
899+
<td></td>
900+
<td></td>
901+
<td>☑️ Req</td>
902+
<td></td>
903+
</tr>
904+
<tr>
905+
<td>
906+
<strong>✨ Location</strong>
907+
<br>URL of created resource
908+
</td>
909+
<td></td>
910+
<td></td>
911+
<td></td>
912+
<td>✅ Resp</td>
913+
<td></td>
914+
</tr>
915+
<tr>
916+
<td>
917+
<strong>⏳ Upload-Expires</strong>
918+
<br>Expiration time
919+
</td>
920+
<td></td>
921+
<td>☑️ Resp<sup>8</sup></td>
922+
<td></td>
923+
<td>☑️ Resp<sup>8</sup></td>
924+
<td></td>
925+
</tr>
926+
<tr>
927+
<td>
928+
<strong>🔍 Upload-Checksum</strong>
929+
<br>Data integrity
930+
</td>
931+
<td></td>
932+
<td>☑️ Req</td>
933+
<td></td>
934+
<td></td>
935+
<td></td>
936+
</tr>
937+
<tr>
938+
<td>
939+
<strong>🔍 Tus-Checksum-Algorithm</strong>
940+
<br>Supported algorithms
941+
</td>
942+
<td></td>
943+
<td></td>
944+
<td>☑️ Resp<sup>9</sup></td>
945+
<td></td>
946+
<td></td>
947+
</tr>
948+
<tr>
949+
<td>
950+
<strong>⛓️ Upload-Concat</strong>
951+
<br>Concatenation info
952+
</td>
953+
<td>☑️ Resp<sup>10</sup></td>
954+
<td></td>
955+
<td></td>
956+
<td>☑️ Req<sup>11</sup></td>
957+
<td></td>
958+
</tr>
959+
<tr>
960+
<td colspan="6"><br><br><strong>Legend</strong></td>
961+
</tr>
962+
<tr>
963+
<td colspan="3">
964+
<strong>Requirements:</strong>
965+
<ul>
966+
<li>✅ Required</li>
967+
<li>☑️ Optional</li>
968+
</ul>
969+
</td>
970+
<td rowspan="2" colspan="3">
971+
<strong>Notes:</strong>
972+
<ol>
973+
<li> Only included when using Creation With Upload extension</li>
974+
<li> Included if size is known</li>
975+
<li> Required if length was deferred in creation</li>
976+
<li> Either Upload-Length or Upload-Defer-Length must be included</li>
977+
<li> Required only for 412 Precondition Failed responses</li>
978+
<li> Included if length was deferred</li>
979+
<li> Included if metadata was provided during creation</li>
980+
<li> Included if upload has expiration (requires Expiration extension)</li>
981+
<li> Included if Checksum extension is supported</li>
982+
<li> Included if upload is partial or final (requires Concatenation extension)</li>
983+
<li> Required for partial/final uploads (requires Concatenation extension)</li>
984+
<li> Must be `application/offset+octet-stream`</li>
985+
<li> Must be `application/offset+octet-stream` when body contains upload data</li>
986+
<li> Must be `no-store`</li>
987+
</ol>
988+
</td>
989+
</tr>
990+
<tr>
991+
<td colspan="3">
992+
<strong>Modules:</strong>
993+
<ul>
994+
<li>💚 Core protocol</li>
995+
<li>⏳ Expiration extension </li>
996+
<li>✨ Creation extension</li>
997+
<li>🗑️ Termination extension</li>
998+
<li>🔍 Checksum extension</li>
999+
<li>⛓️ Concatanation extension</li>
1000+
</ul>
1001+
</td>
1002+
</tr>
1003+
</tbody>
1004+
</table>
1005+
7451006
## FAQ
7461007

7471008
The FAQ is available online at <https://tus.io/faq.html>.

0 commit comments

Comments
 (0)