Merge branch 'commands_table' into 'main'

Beautify the table of relay commands

See merge request tpo/core/torspec!249

1 files changed, 73 insertions, 31 deletions

diff --git a/spec/tor-spec/relay-cells.md b/spec/tor-spec/relay-cells.md
index 346899b..3089d32 100644
--- a/spec/tor-spec/relay-cells.md
+++ b/spec/tor-spec/relay-cells.md
@@ -32,40 +32,82 @@ enveloped relay message, encoded as follows:
 
 The relay commands are:
 
-| Command | Identifier      | Direction           | Control?
-| ------- | ----------      | ---------           | --------
-|  1      | RELAY_BEGIN     | forward             |
-|  2      | RELAY_DATA      | forward or backward |
-|  3      | RELAY_END       | forward or backward |
-|  4      | RELAY_CONNECTED | backward            |
-|  5      | RELAY_SENDME    | forward or backward | sometimes control
-|  6      | RELAY_EXTEND    | forward             | control
-|  7      | RELAY_EXTENDED  | backward            | control
-|  8      | RELAY_TRUNCATE  | forward             | control
-|  9      | RELAY_TRUNCATED | backward            | control
-| 10      | RELAY_DROP      | forward or backward | control
-| 11      | RELAY_RESOLVE   | forward             |
-| 12      | RELAY_RESOLVED  | backward            |
-| 13      | RELAY_BEGIN_DIR | forward             |
-| 14      | RELAY_EXTEND2   | forward             | control
-| 15      | RELAY_EXTENDED2 | backward            | control
-| 16..18  | Reserved for UDP; Not yet in use, see [prop339].
-| 19..22  | Reserved for Conflux, see [prop329].
-| 32..40  | Used for hidden services; see the [rendezvous spec].
-| 41..42  | Used for circuit padding; see ["Circuit-level padding"] in the padding spec.
-| 43      | XON  (See Sec 4 of [prop324])  | forward or backward |
-| 44      | XOFF (See Sec 4 of [prop324])  | forward or backward |
+| Command | Identifier  | Type         | Description
+| ------- | ----------  | ----         | -----------
+| <th>Core protocol</th>
+|  1      | [BEGIN]     | **F**        | Open a stream
+|  2      | [DATA]      | **F**/**B**  | Transmit data
+|  3      | [END]       | **F**/**B**  | Close a stream
+|  4      | [CONNECTED] | **B**        | Stream has successfully opened
+|  5      | [SENDME]    | **F**/**B**, **C?** | Acknowledge traffic
+|  6      | [EXTEND]    | **F**, **C** | Extend a circuit with TAP (obsolete)
+|  7      | [EXTENDED]  | **B**, **C** | Finish extending a circuit with TAP (obsolete)
+|  8      | [TRUNCATE]  | **F**, **C** | Remove nodes from a circuit (unused)
+|  9      | [TRUNCATED] | **B**, **C** | Report circuit truncation (unused)
+| 10      | [DROP]      | **F**/**B**, **C** | Long-range padding
+| 11      | [RESOLVE]   | **F**        | Hostname lookup
+| 12      | [RESOLVED]  | **B**        | Hostname lookup reply
+| 13      | [BEGIN_DIR] | **F**        | Open stream to directory cache
+| 14      | [EXTEND2]   | **F**, **C** | Extend a circuit
+| 15      | [EXTENDED2] | **B**, **C** | Finish extending a circuit
+| 16..18  | Reserved    |              | For UDP; see [prop339].
+| <th>Conflux</th>
+| 19      | [CONFLUX_LINK][prop329]       | **F**, **C** | Link circuits into a bundle
+| 20      | [CONFLUX_LINKED][prop329]     | **B**, **C** | Acknowledge link request
+| 21      | [CONFLUX_LINKED_ACK][prop329] | **F**, **C** | Acknowledge CONFLUX_LINKED message (for timing)
+| 22      | [CONFLUX_SWITCH][prop329]     | **F**/**B**, **C** | Switch between circuits in a bundle
+| <th>Onion services</th>
+| 32      | [ESTABLISH_INTRO]      | **F**, **C** | Create introduction point
+| 33      | [ESTABLISH_RENDEZVOUS] | **F**, **C** | Create rendezvous point
+| 34      | [INTRODUCE1]           | **F**, **C** | Introduction request (to intro point)
+| 35      | [INTRODUCE2]           | **B**, **C** | Introduction request (to service)
+| 36      | [RENDEZVOUS1]          | **F**, **C** | Rendezvous request (to rendezvous point)
+| 37      | [RENDEZVOUS2]          | **B**, **C** | Rendezvous request (to client)
+| 38      | [INTRO_ESTABLISHED]    | **B**, **C** | Acknowledge ESTABLISH_INTRO
+| 39      | [RENDEZVOUS_ESTABLISHED] | **B**, **C** | Acknowledge ESTABLISH_RENDEZVOUS
+| 40      | [INTRODUCE_ACK]        | **B**, **C** | Acknowledge INTRODUCE1
+| <th>Circuit padding</th>
+| 41      | [PADDING_NEGOTIATE][circ-padding]  | **F**, **C** | Negotiate circuit padding
+| 42      | [PADDING_NEGOTIATED][circ-padding] | **B**, **C** | Negotiate circuit padding
+| <th>Flow control</th>
+| 43      | [XON][prop324]  | **F**/**B** | Stream-level flow control
+| 44      | [XOFF][prop324] | **F**/**B** | Stream-level flow control
 
 [prop324]: ../proposals/324-rtt-congestion-control.txt
 [prop329]: ../proposals/329-traffic-splitting.md
 [prop339]: ../proposals/339-udp-over-tor.md
-[rendezvous spec]: ../rend-spec/index.md
-["Circuit-level padding"]: ../padding-spec/circuit-level-padding.md#circuit-level-padding
-
-Commands labelled as "forward" must only be sent by the originator
-of the circuit. Commands labelled as "backward" must only be sent by
-other nodes in the circuit back to the originator. Commands marked
-as either can be sent either by the originator or other nodes.
+[circ-padding]: ../padding-spec/circuit-level-padding.md#circuit-level-padding
+[BEGIN]: ./opening-streams.md#opening
+[CONNECTED]: ./opening-streams.md#opening
+[DATA]: ./opening-streams.md#transmitting
+[DROP]: ./opening-streams.md#transmitting
+[BEGIN_DIR]: ./opening-streams.md#opening-a-directory-stream
+[END]: ./closing-streams.md#closing-streams
+[RESOLVE]: ./remote-hostname-lookup.md
+[RESOLVED]: ./remote-hostname-lookup.md
+[EXTEND]: ./create-created-cells.md#EXTEND
+[EXTEND2]: ./create-created-cells.md#EXTEND
+[EXTENDED]: ./create-created-cells.md#EXTEND
+[EXTENDED2]: ./create-created-cells.md#EXTEND
+[TRUNCATE]: ./tearing-down-circuits.md
+[TRUNCATED]: ./tearing-down-circuits.md
+[SENDME]: ./flow-control.md#sendme-message-format
+[ESTABLISH_INTRO]: ../rend-spec/introduction-protocol.md#EST_INTRO
+[INTRO_ESTABLISHED]: ../rend-spec/introduction-protocol.md#INTRO_ESTABLISHED
+[INTRODUCE1]: ../rend-spec/introduction-protocol.md#SEND_INTRO1
+[INTRODUCE2]: ../rend-spec/introduction-protocol.md#PROCESS_INTRO2
+[INTRODUCE_ACK]: ../rend-spec/introduction-protocol.md#SEND_INTRO1
+[ESTABLISH_RENDEZVOUS]: ../rend-spec/rendezvous-protocol.md#EST_REND_POINT
+[RENDEZVOUS_ESTABLISHED]: ../rend-spec/rendezvous-protocol.md#EST_REND_POINT
+[RENDEZVOUS1]: ../rend-spec/rendezvous-protocol.md#JOIN_REND
+[RENDEZVOUS2]: ../rend-spec/rendezvous-protocol.md#JOIN_REND
+
+- **F** (Forward): Must only be sent by the originator of the circuit.
+- **B** (Backward): Must only be sent by other nodes in the circuit
+  back towards the originator.
+- **F**/**B** (Forward or backward): May be sent in either direction.
+- **C**: (Control) must have a zero-valued stream ID.
+  (Other commands must have a nonzero stream ID.)
 
 The 'recognized' field is used as a simple indication that the cell
 is still encrypted. It is an optimization to avoid calculating
@@ -100,7 +142,7 @@ All relay messages pertaining to the same tunneled stream have the same
 stream ID.  StreamIDs are chosen arbitrarily by the OP.  No stream
 may have a StreamID of zero. Rather, relay messages that affect the
 entire circuit rather than a particular stream use a StreamID of zero
--- they are marked in the table above as "\[control\]" style
+-- they are marked in the table above as "**C**" ([control") style
 cells. (Sendme cells are marked as "sometimes control" because they
 can include a StreamID or not depending on their purpose -- see
 [Flow control](./flow-control.md#flow-control).)