Create section for bittorrent book chapters

type: documentation
casey · Apr 8, 2020 · 83ee172 · 83ee172
1 parent 2ba24bb
commit 83ee172
Show file tree

Hide file tree

Showing 6 changed files with 39 additions and 24 deletions.
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -3,7 +3,8 @@ Summary
 
 [Intermodal](./introduction.md)
 
-- [BitTorrent BEP Support](./bep-support.md)
-- [Alternatives & Prior Art](./prior-art.md)
-- [BitTorrent References](./bittorrent-references.md)
-- [UDP Tracker Protocol](./udp-tracker-protocol.md)
+- [Bittorrent](./bittorrent.md)
+  - [BEP Support](./bittorrent/bep-support.md)
+  - [Alternatives & Prior Art](./bittorrent/prior-art.md)
+  - [UDP Tracker Protocol](./bittorrent/udp-tracker-protocol.md)
+  - [References](./bittorrent/references.md)
diff --git a/book/src/bittorrent.md b/book/src/bittorrent.md
@@ -0,0 +1,4 @@
+Bittorrent
+==========
+
+This page intentionally left blank.
diff --git a/book/src/bep-support.md → book/src/bittorrent/bep-support.md b/book/src/bep-support.md → book/src/bittorrent/bep-support.md
diff --git a/book/src/prior-art.md → book/src/bittorrent/prior-art.md b/book/src/prior-art.md → book/src/bittorrent/prior-art.md
@@ -1,5 +1,5 @@
 Alternatives & Prior Art
-------------------------
+========================
 
 | Name                                                                              | UI                      | Language   | Notes                                                                                                                                     |
 |-----------------------------------------------------------------------------------|-------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------|

diff --git a/book/src/bittorrent-references.md → book/src/bittorrent/references.md b/book/src/bittorrent-references.md → book/src/bittorrent/references.md
@@ -1,5 +1,5 @@
-BitTorrent References
----------------------
+References
+==========
 
 | URL                                                         | Description                                                                                       |
 |:------------------------------------------------------------|:--------------------------------------------------------------------------------------------------|
@@ -8,3 +8,4 @@ BitTorrent References
 | https://wiki.theory.org/index.php/Main_Page                 | Wiki with lots of information about all aspects of the BitTorrent protocol and implementations.   |
 | https://archive.org/details/2014_torrent_archive_organized) | Massive 158 GiB archive containing 5.5 million torrents, assembled in 2014.                       |
 | https://github.com/internetarchive/dweb-transport           | Github repository hosting The Internet Archive's distributed web and BitTorrent-related software. |
+| https://libtorrent.org/udp_tracker_protocol.html            | UDP tracker protocol description.                                                                 |
diff --git a/book/src/udp-tracker-protocol.md → book/src/bittorrent/udp-tracker-protocol.md b/book/src/udp-tracker-protocol.md → book/src/bittorrent/udp-tracker-protocol.md
@@ -1,5 +1,5 @@
-Bittorrent UDP-tracker protocol
-===============================
+UDP Tracker Protocol
+====================
 
 This description of the UDP tracker protocol is adapted from
 [this page](https://libtorrent.org/udp_tracker_protocol.html) by Arvid Norberg.
@@ -24,6 +24,15 @@ table.
 When a message is followed by a structure labeled _repeating:_, the rest of the
 message is zero or more of that structure.
 
+Fields with type `[T; N]` are `N` instances of values of type `T` with no extra
+padding.
+
+Fields with type `[T; NAME]` are `NAME` instances of values of type `T` with no
+extra padding, where `NAME` is an integer field of the same message.
+
+Files with type `[T]` are zero or more instances of values of type `T` with no
+extra padding, which make up any trailing bytes of the message.
+
 
 Actions
 -------
@@ -48,11 +57,11 @@ Events
 Error
 ------
 
-| size | name           | description                               |
+| type | name           | description                               |
 |------|----------------|-------------------------------------------|
 | i32  | action         |                                           |
 | i32  | transaction_id |                                           |
-| i8[] | error_string   | rest of packet is string describing error |
+| [i8] | error_string   | rest of packet is string describing error |
 
 Connect
 -------
@@ -117,28 +126,28 @@ Scrape
 
 ### Request
 
-| size | name           |
+| type | name           |
 |------|----------------|
 | i64  | connection_id  |
 | i32  | action         |
 | i32  | transaction_id |
 
 _repeating:_
 
-| size     | name      |
+| type     | name      |
 |----------|-----------|
 | [i8; 20] | info_hash |
 
 ### Response
 
-| size | name           |
+| type | name           |
 |------|----------------|
 | i32  | action         |
 | i32  | transaction_id |
 
 _repeating:_
 
-| size | name       | description                                  |
+| type | name       | description                                  |
 |------|------------|----------------------------------------------|
 | i32  | complete   | peers in swarm that have finished downloding |
 | i32  | downloaded | times torrent has been downloaded            |
@@ -167,11 +176,11 @@ The packet will have authentication information appended to it.
 where `packet` is the bytes of the packet, less the final 8 bytes that are
 `passwd_hash`.
 
-| size  | name            | description                       |
-|-------|-----------------|-----------------------------------|
-| i8    | username_length |                                   |
-| i8[]  | username        | length given by `username_length` |
-| u8[8] | passwd_hash     |                                   |
+| type                   | name            |
+|------------------------|-----------------|
+| i8                     | username_length |
+| [i8; `username_length` | username        |
+| [u8; 8]                | passwd_hash     |
 
 ### Request String
 
@@ -181,10 +190,10 @@ torrent is allowed to be tracked by a tracker for instance. It could also be
 used to authenticate users by generating torrents with unique tokens in the
 tracker URL for each user. The extension body has the following format:
 
-| size | name           | description                      |
-|------|----------------|----------------------------------|
-| i8   | request_length |                                  |
-| i8[] | request_string | length given by `request_length` |
+| type                   | name           |
+|------------------------|----------------|
+| i8                     | request_length |
+| [i8; `request_length`] | request_string |
 
 `request_string` is the string that comes after the hostname and port in the
 UDP tracker URL. Typically this starts with "/announce" The bittorrent client