commit 2f90285dd88db3fdac5dc14441b7ffe19ce8da38 Author: Damian Johnson atagar@torproject.org Date: Sat Mar 16 09:05:22 2013 -0700
Chaning GuardEvent to match spec revisions
Nick has clarified GUARD events in...
https://trac.torproject.org/7619
Updating our enum docs to reflect the revisions and changing our 'name' attribute to reflect that it could contain either a fingerprint or fingerprint/nickname pair. This is a similar pattern to what we use for ORConnEvent. --- stem/__init__.py | 20 +++++++------------- stem/response/events.py | 29 ++++++++++++++++++++++------- test/unit/response/events.py | 14 ++++++++++---- 3 files changed, 39 insertions(+), 24 deletions(-)
diff --git a/stem/__init__.py b/stem/__init__.py index 3fee276..935ba00 100644 --- a/stem/__init__.py +++ b/stem/__init__.py @@ -332,31 +332,25 @@ Library for working with the tor process.
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 + **ENTRY** used to connect to the tor network =========== ===========
.. 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 + **NEW** new guard that we weren't previously using + **DROPPED** removed from use as one of our guards + **UP** guard is now reachable + **DOWN** guard is now unreachable + **BAD** consensus or relay considers this relay to be unusable as a guard + **GOOD** consensus or relay considers this relay to be usable as a guard ============= ===========
.. data:: TimeoutSetType (enum) diff --git a/stem/response/events.py b/stem/response/events.py index a2c43ff..d99b291 100644 --- a/stem/response/events.py +++ b/stem/response/events.py @@ -522,23 +522,38 @@ class DescChangedEvent(Event):
class GuardEvent(Event): """ - Event that indicates that our guard relays have changed. + Event that indicates that our guard relays have changed. The 'endpoint' could + be either a... + + * fingerprint + * 'fingerprint=nickname' pair + + The derived 'endpoint_*' attributes are generally more useful.
The GUARD event was introduced in tor version 0.1.2.5-alpha.
:var stem.GuardType guard_type: purpose the guard relay is for - :var str name: nickname or fingerprint of the guard relay + :var str endpoint: relay that the event concerns + :var str endpoint_fingerprint: endpoint's finterprint + :var str endpoint_nickname: endpoint's nickname if it was provided :var stem.GuardStatus status: status of the guard relay """
_VERSION_ADDED = stem.version.Requirement.EVENT_GUARD + _POSITIONAL_ARGS = ("guard_type", "endpoint", "status")
- # 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 + def _parse(self): + self.endpoint_fingerprint = None + self.endpoint_nickname = None + + try: + self.endpoint_fingerprint, self.endpoint_nickname = \ + stem.control._parse_circ_entry(self.endpoint) + except stem.ProtocolError: + raise stem.ProtocolError("ORCONN's endpoint doesn't match a ServerSpec: %s" % self)
- _POSITIONAL_ARGS = ("guard_type", "name", "status") + self._log_if_unrecognized('guard_type', stem.GuardType) + self._log_if_unrecognized('status', stem.GuardStatus)
class LogEvent(Event): diff --git a/test/unit/response/events.py b/test/unit/response/events.py index 803de0f..98e7f95 100644 --- a/test/unit/response/events.py +++ b/test/unit/response/events.py @@ -173,7 +173,7 @@ CONF_CHANGED_EVENT = """650-CONF_CHANGED
GUARD_NEW = "650 GUARD ENTRY $36B5DBA788246E8369DBAF58577C6BC044A9A374 NEW" GUARD_GOOD = "650 GUARD ENTRY $5D0034A368E0ABAF663D21847E1C9B6CFA09752A GOOD" -GUARD_BAD = "650 GUARD ENTRY $5D0034A368E0ABAF663D21847E1C9B6CFA09752A BAD" +GUARD_BAD = "650 GUARD ENTRY $5D0034A368E0ABAF663D21847E1C9B6CFA09752A=caerSidi BAD"
# NEWCONSENSUS event from v0.2.1.30.
@@ -636,17 +636,23 @@ class TestEvents(unittest.TestCase): 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("$36B5DBA788246E8369DBAF58577C6BC044A9A374", event.endpoint) + self.assertEqual("36B5DBA788246E8369DBAF58577C6BC044A9A374", event.endpoint_fingerprint) + self.assertEqual(None, event.endpoint_nickname) 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("$5D0034A368E0ABAF663D21847E1C9B6CFA09752A", event.endpoint) + self.assertEqual("5D0034A368E0ABAF663D21847E1C9B6CFA09752A", event.endpoint_fingerprint) + self.assertEqual(None, event.endpoint_nickname) 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("$5D0034A368E0ABAF663D21847E1C9B6CFA09752A=caerSidi", event.endpoint) + self.assertEqual("5D0034A368E0ABAF663D21847E1C9B6CFA09752A", event.endpoint_fingerprint) + self.assertEqual("caerSidi", event.endpoint_nickname) self.assertEqual(GuardStatus.BAD, event.status)
def test_newdesc_event(self):