Skip to content

Commit 6c46a5b

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 6c46a5b

File tree

1 file changed

+258
-1
lines changed

1 file changed

+258
-1
lines changed

‎protocol.md‎

Lines changed: 258 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -223,7 +223,7 @@ match, the Server MUST respond with the `409 Conflict` status without modifying
223223
the upload resource.
224224

225225
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
226+
request, but MAY also use multipl requests successively for scenarios
227227
where this is desirable. One example for these situations is when the
228228
[Checksum](#checksum) extension is used.
229229

@@ -742,6 +742,263 @@ Upload-Length: 11
742742
Upload-Concat: final;/files/a /files/b
743743
```
744744

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

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

0 commit comments

Comments
 (0)