[tor-commits] [stem/master] Add cell metadata

[atagar at torproject.org]

commit 309cb3f1200bce50134b653c18b182d107f5ef08
Author: Damian Johnson <atagar at torproject.org>
Date:   Wed Jan 3 13:50:49 2018 -0800

    Add cell metadata
    
    Adding the CELL_COMMAND table from endosome.
---
 stem/client.py        | 54 +++++++++++++++++++++++++++++++++++++++++++++++++++
 test/settings.cfg     |  1 +
 test/unit/__init__.py |  1 +
 test/unit/client.py   | 24 +++++++++++++++++++++++
 4 files changed, 80 insertions(+)

diff --git a/stem/client.py b/stem/client.py
index 8c5ad506..73c91ef5 100644
--- a/stem/client.py
+++ b/stem/client.py
@@ -31,6 +31,7 @@ providing higher level functions in much the same way as our
   Relay - Connection with a relay's ORPort.
 """
 
+import collections
 import struct
 
 from stem.util import enum
@@ -43,6 +44,41 @@ PackType = enum.Enum(
 )
 
 
+class CellAttributes(collections.namedtuple('CellAttributes', ['name', 'value', 'fixed_length', 'for_circuit'])):
+  """
+  Metadata for cells tor will accept on its ORPort.
+
+  :var str name: name of the cell type
+  :var int value: integer value of the command on the wire
+  :var bool fixed_length: **True** if cells have a fixed length,
+    **False** if variable
+  :var bool for_circuit: **True** if command is for a circuit, **False**
+    otherwise
+  """
+
+
+CELL_ATTR = (
+  CellAttributes('PADDING', 0, True, False),              # Padding                  (section 7.2)
+  CellAttributes('CREATE', 1, True, True),                # Create a circuit         (section 5.1)
+  CellAttributes('CREATED', 2, True, True),               # Acknowledge create       (section 5.1)
+  CellAttributes('RELAY', 3, True, True),                 # End-to-end data          (section 5.5 and 6)
+  CellAttributes('DESTROY', 4, True, True),               # Stop using a circuit     (section 5.4)
+  CellAttributes('CREATE_FAST', 5, True, True),           # Create a circuit, no PK  (section 5.1)
+  CellAttributes('CREATED_FAST', 6, True, True),          # Circuit created, no PK   (section 5.1)
+  CellAttributes('VERSIONS', 7, False, False),            # Negotiate proto version  (section 4)
+  CellAttributes('NETINFO', 8, True, False),              # Time and address info    (section 4.5)
+  CellAttributes('RELAY_EARLY', 9, True, True),           # End-to-end data; limited (section 5.6)
+  CellAttributes('CREATE2', 10, True, True),              # Extended CREATE cell     (section 5.1)
+  CellAttributes('CREATED2', 11, True, True),             # Extended CREATED cell    (section 5.1)
+  CellAttributes('PADDING_NEGOTIATE', 12, True, False),   # Padding negotiation      (section 7.2)
+  CellAttributes('VPADDING', 128, False, False),          # Variable-length padding  (section 7.2)
+  CellAttributes('CERTS', 129, False, False),             # Certificates             (section 4.2)
+  CellAttributes('AUTH_CHALLENGE', 130, False, False),    # Challenge value          (section 4.3)
+  CellAttributes('AUTHENTICATE', 131, False, False),      # Client authentication    (section 4.5)
+  CellAttributes('AUTHORIZE', 132, False, False),         # Client authorization     (not yet used)
+)
+
+
 class Relay(object):
   """
   Connection with a `Tor relay's ORPort
@@ -50,6 +86,24 @@ class Relay(object):
   """
 
 
+def cell_attributes(cell_type):
+  """
+  Provides attributes of the given cell type.
+
+  :parm str,int cell_type: cell type as either a string or integer
+
+  :raise: **ValueError** if cell type is invalid
+  """
+
+  param = 'value' if isinstance(cell_type, int) else 'name'
+
+  for attr in CELL_ATTR:
+    if getattr(attr, param) == cell_type:
+      return attr
+
+  raise ValueError("'%s' isn't a valid cell type" % cell_type)
+
+
 def serialize_versions(versions):
   """
   Provides the payload for a series of link versions.
diff --git a/test/settings.cfg b/test/settings.cfg
index 4e9b2ab9..501dff9c 100644
--- a/test/settings.cfg
+++ b/test/settings.cfg
@@ -229,6 +229,7 @@ test.unit_tests
 |test.unit.response.authchallenge.TestAuthChallengeResponse
 |test.unit.response.protocolinfo.TestProtocolInfoResponse
 |test.unit.response.mapaddress.TestMapAddressResponse
+|test.unit.client.TestClient
 |test.unit.connection.authentication.TestAuthenticate
 |test.unit.connection.connect.TestConnect
 |test.unit.control.controller.TestControl
diff --git a/test/unit/__init__.py b/test/unit/__init__.py
index 6cdbe98b..34fcbb19 100644
--- a/test/unit/__init__.py
+++ b/test/unit/__init__.py
@@ -6,6 +6,7 @@ import os
 import test
 
 __all__ = [
+  'client',
   'connection',
   'control',
   'descriptor',
diff --git a/test/unit/client.py b/test/unit/client.py
new file mode 100644
index 00000000..4761cf8e
--- /dev/null
+++ b/test/unit/client.py
@@ -0,0 +1,24 @@
+"""
+Unit tests for the stem.client.
+"""
+
+import unittest
+
+import stem.client
+
+
+class TestClient(unittest.TestCase):
+  def test_cell_attributes(self):
+    attr = stem.client.cell_attributes('NETINFO')
+
+    self.assertEqual('NETINFO', attr.name)
+    self.assertEqual(8, attr.value)
+    self.assertEqual(True, attr.fixed_length)
+    self.assertEqual(False, attr.for_circuit)
+
+    self.assertEqual(10, stem.client.cell_attributes('CREATE2').value)
+    self.assertEqual('CREATE2', stem.client.cell_attributes(10).name)
+
+    self.assertRaises(ValueError, stem.client.cell_attributes, 'NOPE')
+    self.assertRaises(ValueError, stem.client.cell_attributes, 85)
+    self.assertRaises(ValueError, stem.client.cell_attributes, None)