glossary: define cell, message, etc.

Part of #253.

1 files changed, 35 insertions, 5 deletions

diff --git a/spec/glossary.md b/spec/glossary.md
index a8c7940..aa68699 100644
--- a/spec/glossary.md
+++ b/spec/glossary.md
@@ -144,6 +144,36 @@ an internal circuit.
 
 <a id="glossary.txt-3.1"></a>
 
+## Messages and cells
+
+Cell: A message sent over a channel. Every cell has an associated
+command.  A cell may be fixed-length or variable-length, depending on
+its command.  Cells are sometimes referred to by their command types:
+for example, a cell whose command is `DESTROY` is called a
+DESTROY cell.
+
+Relay cell: A cell that tells a relay or client about instructions sent
+over a circuit.  The command of a relay cell may be `RELAY` or `RELAY_EARLY`.
+If we need to refer to a cell whose command is specifically `RELAY`,
+we call it a "RELAY" cell.
+
+Enveloped relay message: The results of decrypting a relay cell:
+a relay message plus an associated (optional) StreamID.
+(If the StreamID is not present, or zero,
+then the relay message is addressed to the circuit itself
+rather than to any particular stream on the circuit.)
+
+Relay message: A message sent over a circuit to an individual stream,
+or to the circuit itself. Relay messages are sometimes referred to
+by their command types: for example, a message whose command is
+`DATA` is sometimes called a DATA message.
+Sometimes, relay messages are just called "Messages"
+if no ambiguity would result.
+
+> Note that when [prop340](proposals/340-packed-and-fragmented.md) is implemented,
+> the relationship between relay cells and (enveloped) relay messages
+> will no longer be 1:1.
+
 ## Link handshake
 
 The link handshake establishes the TLS connection over which two
@@ -167,19 +197,19 @@ CREATE cell: First part of a handshake, sent by the initiator.
 
 CREATED cell: Second part of a handshake, sent by the responder.
 
-EXTEND cell: (also known as a RELAY_EXTEND cell) First part of a
+EXTEND message: (also known as a RELAY_EXTEND message) First part of a
 handshake, tunneled through an existing circuit.  The last relay
 in the circuit so far will decrypt this cell and send the
 payload in a CREATED cell to the chosen next hop relay.
 
-EXTENDED cell: (also known as a RELAY_EXTENDED cell) Second part
+EXTENDED cell: (also known as a RELAY_EXTENDED message) Second part
 of a handshake, tunneled through an existing circuit.  The last
 relay in the circuit so far receives the CREATED cell from the
-new last hop relay and encrypts the payload in an EXTENDED cell
+new last hop relay and encrypts the payload in an EXTENDED message
 to tunnel back to the client.
 
-Onion skin: A CREATE/CREATE2 or EXTEND/EXTEND2 payload that
-contains the first part of the TAP or ntor key establishment
+Onion skin: The body of a CREATE/CREATE2 cell or an EXTEND/EXTEND2 message.
+It contains the first part of the TAP or ntor key establishment
 handshake.
 
 <a id="glossary.txt-3.3"></a>