[tor-commits] [stem/master] Adding DROPGUARDS support

[atagar at torproject.org]

commit 8ca253a974c7e6eec9038c2d39a98a245a1ff024
Author: Damian Johnson <atagar at torproject.org>
Date:   Wed May 28 09:18:31 2014 -0700

    Adding DROPGUARDS support
    
    Adding a Controller method for tor's DROPGUARDS function...
    
      https://trac.torproject.org/projects/tor/ticket/10032
      https://gitweb.torproject.org/torspec.git/commitdiff/7c6c7fc
---
 docs/change_log.rst             |    1 +
 stem/control.py                 |   22 +++++++++++++++++++---
 stem/version.py                 |    2 ++
 test/unit/control/controller.py |   13 +++++++++++++
 4 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/docs/change_log.rst b/docs/change_log.rst
index 0bff1b5..ac892d1 100644
--- a/docs/change_log.rst
+++ b/docs/change_log.rst
@@ -44,6 +44,7 @@ The following are only available within Stem's `git repository
   * New, better :func:`~stem.connection.connect` function that deprecates :func:`~stem.connection.connect_port` and :func:`~stem.connection.connect_socket_file`
   * Added :func:`~stem.control.Controller.is_newnym_available` and :func:`~stem.control.Controller.get_newnym_wait` methods to the :class:`~stem.control.Controller`
   * Added :func:`~stem.control.Controller.get_ports` and :func:`~stem.control.Controller.get_listeners` methods to the :class:`~stem.control.Controller`
+  * Added :func:`~stem.control.Controller.drop_guards` (:trac:`10032`, :spec:`7c6c7fc`)
   * Added the id attribute to the :class:`~stem.response.events.ORConnEvent` (:spec:`6f2919a`)
   * Added `support for CONN_BW events <api/response.html#stem.response.events.ConnectionBandwidthEvent>`_ (:spec:`6f2919a`)
   * Added `support for CIRC_BW events <api/response.html#stem.response.events.CircuitBandwidthEvent>`_ (:spec:`6f2919a`)
diff --git a/stem/control.py b/stem/control.py
index 27cce01..78e949c 100644
--- a/stem/control.py
+++ b/stem/control.py
@@ -122,7 +122,8 @@ If you're fine with allowing your script to raise exceptions then this can be mo
     |- is_newnym_available - true if tor would presently accept a NEWNYM signal
     |- get_newnym_wait - seconds until tor would accept a NEWNYM signal
     |- is_geoip_unavailable - true if we've discovered our geoip db to be unavailable
-    +- map_address - maps one address to another such that connections to the original are replaced with the other
+    |- map_address - maps one address to another such that connections to the original are replaced with the other
+    +- drop_guards - drops our set of guard relays and picks a new set
 
   BaseController - Base controller class asynchronous message handling
     |- msg - communicates with the tor process
@@ -2450,8 +2451,9 @@ class Controller(BaseController):
     :param stem.RelayEndReason reason: reason the stream is closing
     :param str flag: not currently used
 
-    :raises: :class:`stem.InvalidArguments` if the stream or reason are not recognized
-    :raises: :class:`stem.InvalidRequest` if the stream and/or reason are missing
+    :raises:
+      * :class:`stem.InvalidArguments` if the stream or reason are not recognized
+      * :class:`stem.InvalidRequest` if the stream and/or reason are missing
     """
 
     # there's a single value offset between RelayEndReason.index_of() and the
@@ -2560,6 +2562,20 @@ class Controller(BaseController):
 
     return response.entries
 
+  def drop_guards(self):
+    """
+    Drops our present guard nodes and picks a new set.
+
+    .. versionadded:: 1.2.0
+
+    :raises: :class:`stem.ControllerError` if Tor couldn't fulfill the request
+    """
+
+    if self.get_version() < stem.version.Requirement.DROPGUARDS:
+      raise stem.UnsatisfiableRequest('DROPGUARDS was added in tor version %s' % stem.version.Requirement.DROPGUARDS)
+
+    self.msg('DROPGUARDS')
+
   def _post_authentication(self):
     super(Controller, self)._post_authentication()
 
diff --git a/stem/version.py b/stem/version.py
index e3ba69b..791ce7b 100644
--- a/stem/version.py
+++ b/stem/version.py
@@ -30,6 +30,7 @@ easily parsed and compared, for instance...
   Requirement                           Description
   ===================================== ===========
   **AUTH_SAFECOOKIE**                   SAFECOOKIE authentication method
+  **DROPGUARDS**                        DROPGUARDS requests
   **EVENT_AUTHDIR_NEWDESCS**            AUTHDIR_NEWDESC events
   **EVENT_BUILDTIMEOUT_SET**            BUILDTIMEOUT_SET events
   **EVENT_CIRC_MINOR**                  CIRC_MINOR events
@@ -333,6 +334,7 @@ safecookie_req.greater_than(Version("0.2.3.13"))
 
 Requirement = stem.util.enum.Enum(
   ("AUTH_SAFECOOKIE", safecookie_req),
+  ("DROPGUARDS", Version('0.2.5.1-alpha')),
   ("EVENT_AUTHDIR_NEWDESCS", Version('0.1.1.10-alpha')),
   ("EVENT_BUILDTIMEOUT_SET", Version('0.2.2.7-alpha')),
   ("EVENT_CIRC_MINOR", Version('0.2.3.11-alpha')),
diff --git a/test/unit/control/controller.py b/test/unit/control/controller.py
index 7422430..bc6711b 100644
--- a/test/unit/control/controller.py
+++ b/test/unit/control/controller.py
@@ -525,3 +525,16 @@ class TestControl(unittest.TestCase):
 
     for test_input in malformed_inputs:
       self.assertRaises(ProtocolError, _parse_circ_path, test_input)
+
+  @patch('stem.control.Controller.get_version')
+  def test_drop_guards(self, get_version_mock):
+    """
+    Exercises the drop_guards() method.
+    """
+
+    get_version_mock.return_value = stem.version.Version('0.1.0.14')
+    self.assertRaises(UnsatisfiableRequest, self.controller.drop_guards)
+
+    with patch('stem.control.Controller.msg', Mock(return_value = None)):
+      get_version_mock.return_value = stem.version.Version('0.2.5.2')
+      self.controller.drop_guards()