[tor-commits] [stem/master] Support for NEWDESC events

[atagar at torproject.org]

commit 54f81be931196e92870b09119fa7e02a7a62cdbf
Author: Damian Johnson <atagar at torproject.org>
Date:   Sun Nov 18 21:06:29 2012 -0800

    Support for NEWDESC events
    
    Implementing and testing NEWDESC events. Got test data by listning for events
    right after starting a TBB instance...
    
    650 NEWDESC $9C2007BE0D3785D5BAB204F0CFE07CF29F4B75EB~Unnamed
    650 NEWDESC $A10C4F666D27364036B562823E5830BC448E046A=DFRI1
    650 NEWDESC $A1130635A0CDA6F60C276FBF6994EFBD4ECADAB1~tama
    650 NEWDESC $A4E3D4A42E68D8302E4A3EA5D117EDCF0B157F72=tor1rufus
    650 NEWDESC $B3BE230EEA146002C4A2A436B4EF7D897DE6C9B6~WombleNode01
    650 NEWDESC $B3FA3110CC6F42443F039220C134CBD2FC4F0493=Sakura
    650 NEWDESC $B4BE08B22D4D2923EDC3970FD1B93D0448C6D8FF~Unnamed
    650 NEWDESC $B839D6CCC5438A21E547DB62043CB0192C068F51=brajah1
    650 NEWDESC $B8B29766ACFADF832ABD1BCAA86497A20F54B584=stillhavenoipinfo
    650 NEWDESC $BBE409F5791DAA52C2C3C9117CBA5AA55F3E2E88=Rarity
    650 NEWDESC $BE938957B2CA5F804B3AFC2C1EE6673170CDBBF8=Moonshine
    650 NEWDESC $C863FB2A6109C9CE2993C8855BAC59583B15475B=coinet
    650 NEWDESC $CA37697301883DE9E895F642D76F3CD31E855434=Bitcoin
    650 NEWDESC $CBC5F626F16052B2B987106D4845DF0B5197901D=mergeslittletornode
    650 NEWDESC $CC19411EDD0BE139E8828EECE2F11E5DFE5F5C09~RadiantPickle
    650 NEWDESC $CF334A712B78A84C6E8F2FF71987122E17951176=skye
    ...
---
 docs/api/response.rst        |    3 +++
 stem/control.py              |    2 ++
 stem/response/events.py      |   22 +++++++++++++++++++---
 test/unit/response/events.py |   23 +++++++++++++++++++++++
 4 files changed, 47 insertions(+), 3 deletions(-)

diff --git a/docs/api/response.rst b/docs/api/response.rst
index 043cae4..2f71256 100644
--- a/docs/api/response.rst
+++ b/docs/api/response.rst
@@ -19,4 +19,7 @@ Events
 .. autoclass:: stem.response.events.LogEvent
 .. autoclass:: stem.response.events.BandwidthEvent
 .. autoclass:: stem.response.events.CircuitEvent
+.. autoclass:: stem.response.events.NewDescEvent
+.. autoclass:: stem.response.events.ORConnEvent
+.. autoclass:: stem.response.events.StreamEvent
 
diff --git a/stem/control.py b/stem/control.py
index 4a91129..3e0a61c 100644
--- a/stem/control.py
+++ b/stem/control.py
@@ -79,6 +79,8 @@ providing its own for interacting at a higher level.
   **ERR**     :class:`stem.response.events.LogEvent`
   **BW**      :class:`stem.response.events.BandwidthEvent`
   **CIRC**    :class:`stem.response.events.CircuitEvent`
+  **NEWDESC** :class:`stem.response.events.NewDescEvent`
+  **ORCONN**  :class:`stem.response.events.ORConnEvent`
   **STREAM**  :class:`stem.response.events.StreamEvent`
   =========== ===========
 """
diff --git a/stem/response/events.py b/stem/response/events.py
index 6a98ef6..3df5430 100644
--- a/stem/response/events.py
+++ b/stem/response/events.py
@@ -107,9 +107,9 @@ class CircuitEvent(Event):
   """
   Event that indicates that a circuit has changed.
   
-  The fingerprint or nickname values in our path may be **None** if the
-  VERBOSE_NAMES feature is unavailable. The option was first introduced in tor
-  version 0.1.2.2.
+  The fingerprint or nickname values in our 'path' may be **None** if the
+  VERBOSE_NAMES feature isn't enabled. The option was first introduced in tor
+  version 0.1.2.2, and on by default after 0.2.2.1.
   
   :var str id: circuit identifier
   :var stem.CircStatus status: reported status for the circuit
@@ -199,6 +199,21 @@ class LogEvent(Event):
     
     self.message = str(self)[len(self.runlevel) + 1:].rstrip("\nOK")
 
+class NewDescEvent(Event):
+  """
+  Event that indicates that a new descriptor is available.
+  
+  The fingerprint or nickname values in our 'relays' may be **None** if the
+  VERBOSE_NAMES feature isn't enabled. The option was first introduced in tor
+  version 0.1.2.2, and on by default after 0.2.2.1.
+  
+  :param tuple relays: **(fingerprint, nickname)** tuples for the relays with
+    new descriptors
+  """
+  
+  def _parse(self):
+    self.relays = tuple([stem.control._parse_circ_entry(entry) for entry in str(self).split()[1:]])
+
 class ORConnEvent(Event):
   """
   Event that indicates a change in a relay connection. The 'endpoint' could be
@@ -354,6 +369,7 @@ EVENT_TYPE_TO_CLASS = {
   "ERR": LogEvent,
   "BW": BandwidthEvent,
   "CIRC": CircuitEvent,
+  "NEWDESC": NewDescEvent,
   "ORCONN": ORConnEvent,
   "STREAM": StreamEvent,
 }
diff --git a/test/unit/response/events.py b/test/unit/response/events.py
index 5836498..733d826 100644
--- a/test/unit/response/events.py
+++ b/test/unit/response/events.py
@@ -59,6 +59,13 @@ STREAM_CLOSED_DONE = "650 STREAM 25 CLOSED 26 199.7.52.72:80 REASON=DONE"
 ORCONN_CONNECTED = "650 ORCONN $7ED90E2833EE38A75795BA9237B0A4560E51E1A0=GreenDragon CONNECTED"
 ORCONN_CLOSED = "650 ORCONN $A1130635A0CDA6F60C276FBF6994EFBD4ECADAB1~tama CLOSED REASON=DONE"
 
+# NEWDESC events. I've never actually seen multiple descriptors in an event,
+# but the spec allows for it.
+
+NEWDESC_SINGLE = "650 NEWDESC $B3FA3110CC6F42443F039220C134CBD2FC4F0493=Sakura"
+NEWDESC_MULTIPLE = "650 NEWDESC $BE938957B2CA5F804B3AFC2C1EE6673170CDBBF8=Moonshine \
+$B4BE08B22D4D2923EDC3970FD1B93D0448C6D8FF~Unnamed"
+
 def _get_event(content):
   controller_event = mocking.get_message(content)
   stem.response.convert("EVENT", controller_event, arrived_at = 25)
@@ -231,6 +238,22 @@ class TestEvents(unittest.TestCase):
     self.assertEqual(None, event.reason)
     self.assertEqual(None, event.remote_reason)
   
+  def test_newdesc_event(self):
+    event = _get_event(NEWDESC_SINGLE)
+    expected_relays = (("B3FA3110CC6F42443F039220C134CBD2FC4F0493", "Sakura"),)
+    
+    self.assertTrue(isinstance(event, stem.response.events.NewDescEvent))
+    self.assertEqual(NEWDESC_SINGLE.lstrip("650 "), str(event))
+    self.assertEqual(expected_relays, event.relays)
+    
+    event = _get_event(NEWDESC_MULTIPLE)
+    expected_relays = (("BE938957B2CA5F804B3AFC2C1EE6673170CDBBF8", "Moonshine"),
+                       ("B4BE08B22D4D2923EDC3970FD1B93D0448C6D8FF", "Unnamed"))
+    
+    self.assertTrue(isinstance(event, stem.response.events.NewDescEvent))
+    self.assertEqual(NEWDESC_MULTIPLE.lstrip("650 "), str(event))
+    self.assertEqual(expected_relays, event.relays)
+  
   def test_orconn_event(self):
     event = _get_event(ORCONN_CONNECTED)