[tor-commits] [stem/master] Enumerate RELAY cell commands

[atagar at torproject.org]

commit dfa5fe1efe6ef62a278c6d7ee642a24018931eef
Author: Damian Johnson <atagar at torproject.org>
Date:   Tue Jan 23 11:26:56 2018 -0800

    Enumerate RELAY cell commands
---
 stem/client/__init__.py | 51 +++++++++++++++++++++++++++++++++++++++++++++++++
 stem/client/cell.py     | 30 +++++++++++++++++++++++++++--
 2 files changed, 79 insertions(+), 2 deletions(-)

diff --git a/stem/client/__init__.py b/stem/client/__init__.py
index 01c6b749..fcd0a238 100644
--- a/stem/client/__init__.py
+++ b/stem/client/__init__.py
@@ -37,6 +37,38 @@ a wrapper for :class:`~stem.socket.RelaySocket`, much the same way as
   **UNKNOWN**           unrecognized address type
   ===================== ===========
 
+.. data:: RelayCommand (enum)
+
+  Command concerning streams and circuits we've established with a relay.
+  Commands have two characteristics...
+
+  * **forward/backward**: **forward** commands are issued from the orgin,
+    whereas **backward** come from the relay
+
+  * **stream/circuit**: **steam** commands concern an individual steam, whereas
+    **circuit** concern the entire circuit we've established with a relay
+
+  ===================== ===========
+  RelayCommand          Description
+  ===================== ===========
+  **BEGIN**             begin a stream (**forward**, **stream**)
+  **DATA**              transmit data (**forward/backward**, **stream**)
+  **END**               end a stream (**forward/backward**, **stream**)
+  **CONNECTED**         BEGIN reply (**backward**, **stream**)
+  **SENDME**            ready to accept more cells (**forward/backward**, **stream/circuit**)
+  **EXTEND**            extend the circuit through another relay (**forward**, **circuit**)
+  **EXTENDED**          EXTEND reply (**backward**, **circuit**)
+  **TRUNCATE**          remove last circuit hop (**forward**, **circuit**)
+  **TRUNCATED**         TRUNCATE reply (**backward**, **circuit**)
+  **DROP**              ignorable no-op (**forward/backward**, **circuit**)
+  **RESOLVE**           request DNS resolution (**forward**, **stream**)
+  **RESOLVED**          RESOLVE reply (**backward**, **stream**)
+  **BEGIN_DIR**         request descriptor (**forward**, **steam**)
+  **EXTEND2**           ntor EXTEND request (**forward**, **circuit**)
+  **EXTENDED2**         EXTEND2 reply (**backward**, **circuit**)
+  **UNKNOWN**           unrecognized command
+  ===================== ===========
+
 .. data:: CertType (enum)
 
   Relay certificate type.
@@ -97,6 +129,25 @@ AddrType = stem.util.enum.UppercaseEnum(
   'UNKNOWN',
 )
 
+RelayCommand = stem.util.enum.Enum(
+  ('BEGIN', 'RELAY_BEGIN'),
+  ('DATA', 'RELAY_DATA'),
+  ('END', 'RELAY_END'),
+  ('CONNECTED', 'RELAY_CONNECTED'),
+  ('SENDME', 'RELAY_SENDME'),
+  ('EXTEND', 'RELAY_EXTEND'),
+  ('EXTENDED', 'RELAY_EXTENDED'),
+  ('TRUNCATE', 'RELAY_TRUNCATE'),
+  ('TRUNCATED', 'RELAY_TRUNCATED'),
+  ('DROP', 'RELAY_DROP'),
+  ('RESOLVE', 'RELAY_RESOLVE'),
+  ('RESOLVED', 'RELAY_RESOLVED'),
+  ('BEGIN_DIR', 'RELAY_BEGIN_DIR'),
+  ('EXTEND2', 'RELAY_EXTEND2'),
+  ('EXTENDED2', 'RELAY_EXTENDED2'),
+  ('UNKNOWN', 'UNKNOWN'),
+)
+
 CertType = stem.util.enum.UppercaseEnum(
   'LINK',
   'IDENTITY',
diff --git a/stem/client/cell.py b/stem/client/cell.py
index 76a75108..0f292c10 100644
--- a/stem/client/cell.py
+++ b/stem/client/cell.py
@@ -14,7 +14,7 @@ Messages communicated over a Tor relay's ORPort.
     |- CircuitCell - Circuit management.
     |  |- CreateCell - Create a circuit.              (section 5.1)
     |  |- CreatedCell - Acknowledge create.           (section 5.1)
-    |  |- RelayCell - End-to-end data.                (section 5.5 and 6)
+    |  |- RelayCell - End-to-end data.                (section 6.1)
     |  |- DestroyCell - Stop using a circuit.         (section 5.4)
     |  |- CreateFastCell - Create a circuit, no PK.   (section 5.1)
     |  |- CreatedFastCell - Circuit created, no PK.   (section 5.1)
@@ -44,7 +44,7 @@ import random
 import sys
 
 from stem import UNDEFINED
-from stem.client import ZERO, Address, Certificate, CloseReason, Size, split
+from stem.client import ZERO, Address, Certificate, CloseReason, RelayCommand, Size, split
 from stem.util import _hash_attr, datetime_to_unix
 
 FIXED_PAYLOAD_LEN = 509
@@ -255,10 +255,36 @@ class CreatedCell(CircuitCell):
 
 
 class RelayCell(CircuitCell):
+  """
+  Command concerning a relay circuit.
+
+  :var stem.client.RelayCommand command: reason the circuit is being closed
+  """
+
   NAME = 'RELAY'
   VALUE = 3
   IS_FIXED_SIZE = True
 
+  COMMAND_FOR_INT = {
+    1: RelayCommand.BEGIN,
+    2: RelayCommand.DATA,
+    3: RelayCommand.END,
+    4: RelayCommand.CONNECTED,
+    5: RelayCommand.SENDME,
+    6: RelayCommand.EXTEND,
+    7: RelayCommand.EXTENDED,
+    8: RelayCommand.TRUNCATE,
+    9: RelayCommand.TRUNCATED,
+    10: RelayCommand.DROP,
+    11: RelayCommand.RESOLVE,
+    12: RelayCommand.RESOLVED,
+    13: RelayCommand.BEGIN_DIR,
+    14: RelayCommand.EXTEND2,
+    15: RelayCommand.EXTENDED2,
+  }
+
+  INT_FOR_COMMANDS = dict((v, k) for k, v in COMMAND_FOR_INT.items())
+
 
 class DestroyCell(CircuitCell):
   """