[tor-commits] [stem/master] Support for GUARD events
atagar at torproject.org
atagar at torproject.org
Mon Dec 3 02:35:44 UTC 2012
commit 2585969d6efbd8b1a6660d5de1ede437792dc22b
Author: Damian Johnson <atagar at 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"),)
More information about the tor-commits
mailing list