commit 2585969d6efbd8b1a6660d5de1ede437792dc22b Author: Damian Johnson atagar@torproject.org Date: Sun Dec 2 14:02:21 2012 -0800
Support for GUARD events
Implementation and testing for GUARD events. The spec is a little vauge, so we're missing enum descriptions and a good understanding of the 'Name' attribute...
https://trac.torproject.org/7619
Got the test data by listening for GUARD events while bootstrapping...
650 GUARD ENTRY $5D0034A368E0ABAF663D21847E1C9B6CFA09752A BAD 650 GUARD ENTRY $071C2D9D0E03D75FF30DCCA850BB29CA4A4BB383 BAD 650 GUARD ENTRY $36B5DBA788246E8369DBAF58577C6BC044A9A374 NEW 650 GUARD ENTRY $071C2D9D0E03D75FF30DCCA850BB29CA4A4BB383 GOOD 650 GUARD ENTRY $5D0034A368E0ABAF663D21847E1C9B6CFA09752A GOOD --- stem/__init__.py | 46 ++++++++++++++++++++++++++++++++++++++++++ stem/control.py | 1 + stem/response/events.py | 17 +++++++++++++++ test/unit/response/events.py | 25 ++++++++++++++++++++++ 4 files changed, 89 insertions(+), 0 deletions(-)
diff --git a/stem/__init__.py b/stem/__init__.py index c0b47fd..815e82c 100644 --- a/stem/__init__.py +++ b/stem/__init__.py @@ -260,6 +260,37 @@ Library for working with the tor process. **CLIENT** related to our activity as a tor client **SERVER** related to our activity as a tor relay ============= =========== + +.. data:: GuardType (enum) + + Use a guard relay can be for. Tor may provide types not in this enum. + + Enum descriptions are pending... + https://trac.torproject.org/7619 + + =========== =========== + GuardType Description + =========== =========== + **ENTRY** unknown + =========== =========== + +.. data:: GuardStatus (enum) + + Status a guard relay can have. Tor may provide types not in this enum. + + Enum descriptions are pending... + https://trac.torproject.org/7619 + + ============= =========== + GuardStatus Description + ============= =========== + **NEW** unknown + **UP** unknown + **DOWN** unknown + **BAD** unknown + **GOOD** unknown + **DROPPED** unknown + ============= =========== """
__version__ = '0.0.1' @@ -301,6 +332,8 @@ __all__ = [ "ORClosureReason", "AuthDescriptorAction", "StatusType", + "GuardType", + "GuardStatus", ]
import stem.util.enum @@ -496,3 +529,16 @@ StatusType = stem.util.enum.UppercaseEnum( "SERVER", )
+GuardType = stem.util.enum.UppercaseEnum( + "ENTRY", +) + +GuardStatus = stem.util.enum.UppercaseEnum( + "NEW", + "UP", + "DOWN", + "BAD", + "GOOD", + "DROPPED", +) + diff --git a/stem/control.py b/stem/control.py index 45b7df8..c2c014d 100644 --- a/stem/control.py +++ b/stem/control.py @@ -85,6 +85,7 @@ providing its own for interacting at a higher level. **DEBUG** :class:`stem.response.events.LogEvent` **DESCCHANGED** :class:`stem.response.events.DescChangedEvent` **ERR** :class:`stem.response.events.LogEvent` + **GUARD** :class:`stem.response.events.GuardEvent` **INFO** :class:`stem.response.events.LogEvent` **NEWDESC** :class:`stem.response.events.NewDescEvent` **NOTICE** :class:`stem.response.events.LogEvent` diff --git a/stem/response/events.py b/stem/response/events.py index 598f8d1..bca9557 100644 --- a/stem/response/events.py +++ b/stem/response/events.py @@ -317,6 +317,22 @@ class DescChangedEvent(Event):
pass
+class GuardEvent(Event): + """ + Event that indicates that our guard relays have changed. + + :var stem.GuardType guard_type: purpose the guard relay is for + :var str name: nickname or fingerprint of the guard relay + :var stem.GuardStatus status: status of the guard relay + """ + + # TODO: We should replace the 'name' field with a fingerprint or nickname + # attribute once we know what it can be... + # + # https://trac.torproject.org/7619 + + _POSITIONAL_ARGS = ("guard_type", "name", "status") + class LogEvent(Event): """ Tor logging event. These are the most visible kind of event since, by @@ -547,6 +563,7 @@ EVENT_TYPE_TO_CLASS = { "DEBUG": LogEvent, "DESCCHANGED": DescChangedEvent, "ERR": LogEvent, + "GUARD": GuardEvent, "INFO": LogEvent, "NEWDESC": NewDescEvent, "NOTICE": LogEvent, diff --git a/test/unit/response/events.py b/test/unit/response/events.py index 57a3f58..2a64a27 100644 --- a/test/unit/response/events.py +++ b/test/unit/response/events.py @@ -41,6 +41,12 @@ $E57A476CD4DFBD99B4EE52A100A58610AD6E80B9,hamburgerphone" CIRC_BUILT_OLD = "650 CIRC 1 BUILT \ $E57A476CD4DFBD99B4EE52A100A58610AD6E80B9,hamburgerphone,PrivacyRepublic14"
+# GUARD events from tor v0.2.1.30. + +GUARD_NEW = "650 GUARD ENTRY $36B5DBA788246E8369DBAF58577C6BC044A9A374 NEW" +GUARD_GOOD = "650 GUARD ENTRY $5D0034A368E0ABAF663D21847E1C9B6CFA09752A GOOD" +GUARD_BAD = "650 GUARD ENTRY $5D0034A368E0ABAF663D21847E1C9B6CFA09752A BAD" + # STATUS_* events that I was able to easily trigger. Most came from starting # TBB, then listening while it bootstrapped.
@@ -339,6 +345,25 @@ class TestEvents(unittest.TestCase): self.assertEqual([], event.positional_args) self.assertEqual({}, event.keyword_args)
+ def test_guard_event(self): + event = _get_event(GUARD_NEW) + + self.assertTrue(isinstance(event, stem.response.events.GuardEvent)) + self.assertEqual(GUARD_NEW.lstrip("650 "), str(event)) + self.assertEqual(GuardType.ENTRY, event.guard_type) + self.assertEqual("$36B5DBA788246E8369DBAF58577C6BC044A9A374", event.name) + self.assertEqual(GuardStatus.NEW, event.status) + + event = _get_event(GUARD_GOOD) + self.assertEqual(GuardType.ENTRY, event.guard_type) + self.assertEqual("$5D0034A368E0ABAF663D21847E1C9B6CFA09752A", event.name) + self.assertEqual(GuardStatus.GOOD, event.status) + + event = _get_event(GUARD_BAD) + self.assertEqual(GuardType.ENTRY, event.guard_type) + self.assertEqual("$5D0034A368E0ABAF663D21847E1C9B6CFA09752A", event.name) + self.assertEqual(GuardStatus.BAD, event.status) + def test_newdesc_event(self): event = _get_event(NEWDESC_SINGLE) expected_relays = (("B3FA3110CC6F42443F039220C134CBD2FC4F0493", "Sakura"),)