[tor-commits] [stem/master] Supporting ORCONN event's new ID attribute

[atagar at torproject.org]

commit dfa171070607c3c21667998d03dde7ad92c7625d
Author: Damian Johnson <atagar at torproject.org>
Date:   Sat Nov 2 22:43:57 2013 -0700

    Supporting ORCONN event's new ID attribute
    
    New event attribute in tor version 0.2.5.2-alpha. This is from...
    
    https://gitweb.torproject.org/torspec.git/commitdiff/6f2919a
---
 docs/change_log.rst          |    4 ++++
 stem/response/events.py      |   11 ++++++++++-
 stem/util/tor_tools.py       |   12 ++++++++++++
 test/unit/response/events.py |    8 +++++++-
 4 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/docs/change_log.rst b/docs/change_log.rst
index 64114cb..4184635 100644
--- a/docs/change_log.rst
+++ b/docs/change_log.rst
@@ -39,6 +39,10 @@ Unreleased
 The following are only available within stem's `git repository
 <download.html>`_.
 
+ * **Controller**
+
+  * Added the id attribute to the :class:`~stem.response.events.ORConnEvent` (:spec:`6f2919a`)
+
 .. _version_1.1:
 
 Version 1.1
diff --git a/stem/response/events.py b/stem/response/events.py
index 3a5cf41..d01d6db 100644
--- a/stem/response/events.py
+++ b/stem/response/events.py
@@ -670,8 +670,13 @@ class ORConnEvent(Event):
   The derived 'endpoint_*' attributes are generally more useful.
 
   The ORCONN event was one of the first Control Protocol V1 events and was
-  introduced in tor version 0.1.1.1-alpha.
+  introduced in tor version 0.1.1.1-alpha. Its id attribute was added in
+  version 0.2.5.2-alpha.
+
+  .. versionchanged:: 1.1.0-dev
+     Added the id attribute.
 
+  :var str id: connection identifier
   :var str endpoint: relay that the event concerns
   :var str endpoint_fingerprint: endpoint's finterprint if it was provided
   :var str endpoint_nickname: endpoint's nickname if it was provided
@@ -686,6 +691,7 @@ class ORConnEvent(Event):
   _KEYWORD_ARGS = {
     "REASON": "reason",
     "NCIRCS": "circ_count",
+    "ID": "id",
   }
 
   def _parse(self):
@@ -715,6 +721,9 @@ class ORConnEvent(Event):
 
       self.circ_count = int(self.circ_count)
 
+    if self.id and not tor_tools.is_valid_connection_id(self.id):
+      raise stem.ProtocolError("Connection IDs must be one to sixteen alphanumeric characters, got '%s': %s" % (self.id, self))
+
     self._log_if_unrecognized('status', stem.ORStatus)
     self._log_if_unrecognized('reason', stem.ORClosureReason)
 
diff --git a/stem/util/tor_tools.py b/stem/util/tor_tools.py
index 510bff1..e4d1e0c 100644
--- a/stem/util/tor_tools.py
+++ b/stem/util/tor_tools.py
@@ -15,6 +15,7 @@ future, use them at your own risk.**
   is_valid_nickname - checks if a string is a valid tor relay nickname
   is_valid_circuit_id - checks if a string is a valid tor circuit id
   is_valid_stream_id - checks if a string is a valid tor stream id
+  is_valid_connection_id - checks if a string is a valid tor connection id
   is_hex_digits - checks if a string is only made up of hex digits
 """
 
@@ -101,6 +102,17 @@ def is_valid_stream_id(entry):
   return is_valid_circuit_id(entry)
 
 
+def is_valid_connection_id(entry):
+  """
+  Checks if a string is a valid format for being a connection identifier.
+  Currently, this is just an alias to :func:`~stem.util.tor_tools.is_valid_circuit_id`.
+
+  :returns: **True** if the string could be a connection id, **False** otherwise
+  """
+
+  return is_valid_circuit_id(entry)
+
+
 def is_hex_digits(entry, count):
   """
   Checks if a string is the given number of hex digits. Digits represented by
diff --git a/test/unit/response/events.py b/test/unit/response/events.py
index 281dbec..aa13b5f 100644
--- a/test/unit/response/events.py
+++ b/test/unit/response/events.py
@@ -222,12 +222,13 @@ s Fast HSDir Named Stable V2Dir Valid
 # ORCONN events from starting tor 0.2.2.39 via TBB
 
 ORCONN_CLOSED = "650 ORCONN $A1130635A0CDA6F60C276FBF6994EFBD4ECADAB1~tama CLOSED REASON=DONE"
-ORCONN_CONNECTED = "650 ORCONN 127.0.0.1:9000 CONNECTED NCIRCS=20"
+ORCONN_CONNECTED = "650 ORCONN 127.0.0.1:9000 CONNECTED NCIRCS=20 ID=18"
 ORCONN_LAUNCHED = "650 ORCONN $7ED90E2833EE38A75795BA9237B0A4560E51E1A0=GreenDragon LAUNCHED"
 
 ORCONN_BAD_1 = "650 ORCONN $7ED90E2833EE38A75795BA9237B0A4560E5=GreenD LAUNCHED"
 ORCONN_BAD_2 = "650 ORCONN 127.0.0.1:001 CONNECTED"
 ORCONN_BAD_3 = "650 ORCONN 127.0.0.1:9000 CONNECTED NCIRCS=too_many"
+ORCONN_BAD_4 = "650 ORCONN 127.0.0.1:9000 CONNECTED NCIRCS=20 ID=30635A0CDA6F60C276FBF6994EFBD4ECADA"
 
 # STATUS_* events that I was able to easily trigger. Most came from starting
 # TBB, then listening while it bootstrapped.
@@ -752,6 +753,7 @@ class TestEvents(unittest.TestCase):
     self.assertEqual(ORStatus.CLOSED, event.status)
     self.assertEqual(ORClosureReason.DONE, event.reason)
     self.assertEqual(None, event.circ_count)
+    self.assertEqual(None, event.id)
 
     event = _get_event(ORCONN_CONNECTED)
 
@@ -765,6 +767,7 @@ class TestEvents(unittest.TestCase):
     self.assertEqual(ORStatus.CONNECTED, event.status)
     self.assertEqual(None, event.reason)
     self.assertEqual(20, event.circ_count)
+    self.assertEqual('18', event.id)
 
     event = _get_event(ORCONN_LAUNCHED)
 
@@ -788,6 +791,9 @@ class TestEvents(unittest.TestCase):
     # non-numeric NCIRCS
     self.assertRaises(ProtocolError, _get_event, ORCONN_BAD_3)
 
+    # invalid connection id
+    self.assertRaises(ProtocolError, _get_event, ORCONN_BAD_4)
+
   def test_signal_event(self):
     event = _get_event("650 SIGNAL DEBUG")
     self.assertTrue(isinstance(event, stem.response.events.SignalEvent))