[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [stem/master] Implementing Controller.get_info



commit 717c5aaecc8e61cee5ca8f1bae80b3eade5f6985
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
Date:   Sun May 27 20:29:51 2012 -0700

    Implementing Controller.get_info
    
    Implementation and testing (both unit and a little integ) for GETINFO queries.
    There's still several todo notes to clean up, but the method itself is done.
---
 run_tests.py                            |    2 +
 stem/control.py                         |  129 +++++++++++++++++++++++++++++++
 test/integ/connection/authentication.py |    2 +-
 test/integ/control/controller.py        |   37 +++++++++
 test/integ/socket/control_message.py    |    4 -
 test/runner.py                          |   23 ++++--
 test/unit/control/__init__.py           |    6 ++
 test/unit/control/getinfo.py            |  119 ++++++++++++++++++++++++++++
 8 files changed, 308 insertions(+), 14 deletions(-)

diff --git a/run_tests.py b/run_tests.py
index d123081..13fb027 100755
--- a/run_tests.py
+++ b/run_tests.py
@@ -17,6 +17,7 @@ import test.runner
 import test.check_whitespace
 import test.unit.connection.authentication
 import test.unit.connection.protocolinfo
+import test.unit.control.getinfo
 import test.unit.socket.control_line
 import test.unit.socket.control_message
 import test.unit.descriptor.reader
@@ -103,6 +104,7 @@ UNIT_TESTS = (
   test.unit.socket.control_line.TestControlLine,
   test.unit.connection.authentication.TestAuthenticate,
   test.unit.connection.protocolinfo.TestProtocolInfoResponse,
+  test.unit.control.getinfo.TestGetInfoResponse,
 )
 
 INTEG_TESTS = (
diff --git a/stem/control.py b/stem/control.py
index e2d3d90..ccb57f4 100644
--- a/stem/control.py
+++ b/stem/control.py
@@ -36,6 +36,12 @@ import stem.util.log as log
 
 State = stem.util.enum.Enum("INIT", "RESET", "CLOSED")
 
+# Constant to indicate an undefined argument default. Usually we'd use None for
+# this, but users will commonly provide None as the argument so need something
+# else very, very unique...
+
+UNDEFINED = "<Undefined>" * 10
+
 class BaseController:
   """
   Controller for the tor process. This is a minimal base class for other
@@ -429,4 +435,127 @@ class Controller(BaseController):
   
   from_port = staticmethod(from_port)
   from_socket_file = staticmethod(from_socket_file)
+  
+  def get_info(self, param, default = UNDEFINED):
+    """
+    Queries the control socket for the given GETINFO option. If provided a
+    default then that's returned if the GETINFO option is undefined or the
+    call fails for any reason (error response, control port closed, initiated,
+    etc).
+    
+    Arguments:
+      param (str, list) - GETINFO option or options to be queried
+      default (object)  - response if the query fails
+    
+    Returns:
+      Response depends upon how we were called as follows...
+      - str with the response if our param was a str
+      - dict with the param => response mapping if our param was a list
+      - default if one was provided and our call failed
+    
+    Raises:
+      stem.socket.ControllerError if the call fails, and we weren't provided a
+      default response
+    """
+    
+    # TODO: add caching?
+    # TODO: special geoip handling?
+    # TODO: add logging, including call runtime
+    
+    if isinstance(param, str):
+      is_multiple = False
+      param = [param]
+    else:
+      is_multiple = True
+    
+    try:
+      response = self.msg("GETINFO %s" % " ".join(param))
+      
+      # TODO: replace with is_ok() check when we've merged it in
+      if response.content()[0][0] != "250":
+        raise stem.socket.ControllerError(str(response))
+      
+      GetInfoResponse.convert(response)
+      
+      # error if we got back different parameters than we requested
+      requested_params = set(param)
+      reply_params = set(response.values.keys())
+      
+      if requested_params != reply_params:
+        requested_label = ", ".join(requested_params)
+        reply_label = ", ".join(reply_params)
+        
+        raise stem.socket.ProtocolError("GETINFO reply doesn't match the parameters that we requested. Queried '%s' but got '%s'." % (requested_label, reply_label))
+      
+      if is_multiple:
+        return response.values
+      else:
+        return response.values[param[0]]
+    except stem.socket.ControllerError, exc:
+      if default == UNDEFINED: raise exc
+      else: return default
+
+class GetInfoResponse(stem.socket.ControlMessage):
+  """
+  Reply for a GETINFO query.
+  
+  Attributes:
+    values (dict) - mapping between the queried options and their values
+  """
+  
+  def convert(control_message):
+    """
+    Parses a ControlMessage, performing an in-place conversion of it into a
+    GetInfoResponse.
+    
+    Arguments:
+      control_message (stem.socket.ControlMessage) -
+        message to be parsed as a GETINFO reply
+    
+    Raises:
+      stem.socket.ProtocolError the message isn't a proper GETINFO response
+      TypeError if argument isn't a ControlMessage
+    """
+    
+    if isinstance(control_message, stem.socket.ControlMessage):
+      control_message.__class__ = GetInfoResponse
+      control_message._parse_message()
+      return control_message
+    else:
+      raise TypeError("Only able to convert stem.socket.ControlMessage instances")
+  
+  convert = staticmethod(convert)
+  
+  def _parse_message(self):
+    # Example:
+    # 250-version=0.2.3.11-alpha-dev (git-ef0bc7f8f26a917c)
+    # 250+config-text=
+    # ControlPort 9051
+    # DataDirectory /home/atagar/.tor
+    # ExitPolicy reject *:*
+    # Log notice stdout
+    # Nickname Unnamed
+    # ORPort 9050
+    # .
+    # 250 OK
+    
+    self.values = {}
+    
+    for line in self:
+      if line == "OK": break
+      elif not "=" in line:
+        raise stem.socket.ProtocolError("GETINFO replies should only contain parameter=value mappings: %s" % line)
+      
+      key, value = line.split("=", 1)
+      
+      # if the value is a multiline value then it *must* be of the form
+      # '<key>=\n<value>'
+      
+      if "\n" in value:
+        if value.startswith("\n"):
+          value = value[1:]
+        else:
+          raise stem.socket.ProtocolError("GETINFO response contained a multiline value that didn't start with a newline: %s" % line)
+      
+      self.values[key] = value
 
diff --git a/test/integ/connection/authentication.py b/test/integ/connection/authentication.py
index 9d912b3..5875a80 100644
--- a/test/integ/connection/authentication.py
+++ b/test/integ/connection/authentication.py
@@ -274,7 +274,7 @@ class TestAuthenticate(unittest.TestCase):
     """
     
     auth_type = stem.connection.AuthMethod.COOKIE
-    auth_value = test.runner.get_runner().get_torrc_path()
+    auth_value = test.runner.get_runner().get_torrc_path(True)
     
     if os.path.getsize(auth_value) == 32:
       # Weird coincidence? Fail so we can pick another file to check against.
diff --git a/test/integ/control/controller.py b/test/integ/control/controller.py
index 4bf8284..1b743e1 100644
--- a/test/integ/control/controller.py
+++ b/test/integ/control/controller.py
@@ -33,4 +33,41 @@ class TestController(unittest.TestCase):
         self.assertTrue(isinstance(controller, stem.control.Controller))
     else:
       self.assertRaises(stem.socket.SocketError, stem.control.Controller.from_socket_file, test.runner.CONTROL_SOCKET_PATH)
+  
+  def test_getinfo(self):
+    """
+    Exercises GETINFO with valid and invalid queries.
+    """
+    
+    runner = test.runner.get_runner()
+    
+    with runner.get_tor_controller() as controller:
+      # successful single query
+      
+      torrc_path = runner.get_torrc_path()
+      self.assertEqual(torrc_path, controller.get_info("config-file"))
+      self.assertEqual(torrc_path, controller.get_info("config-file", "ho hum"))
+      
+      expected = {"config-file": torrc_path}
+      self.assertEqual(expected, controller.get_info(["config-file"]))
+      self.assertEqual(expected, controller.get_info(["config-file"], "ho hum"))
+      
+      # successful batch query, we don't know the values so just checking for
+      # the keys
+      
+      getinfo_params = set(["version", "config-file", "config/names"])
+      self.assertEqual(getinfo_params, set(controller.get_info(["version", "config-file", "config/names"]).keys()))
+      
+      # non-existant option
+      
+      self.assertRaises(stem.socket.ControllerError, controller.get_info, "blarg")
+      self.assertEqual("ho hum", controller.get_info("blarg", "ho hum"))
+      
+      # empty input
+      
+      self.assertRaises(stem.socket.ControllerError, controller.get_info, "")
+      self.assertEqual("ho hum", controller.get_info("", "ho hum"))
+      
+      self.assertEqual({}, controller.get_info([]))
+      self.assertEqual({}, controller.get_info([], {}))
 
diff --git a/test/integ/socket/control_message.py b/test/integ/socket/control_message.py
index 255e66d..72f9174 100644
--- a/test/integ/socket/control_message.py
+++ b/test/integ/socket/control_message.py
@@ -86,10 +86,6 @@ class TestControlMessage(unittest.TestCase):
     
     runner = test.runner.get_runner()
     torrc_dst = runner.get_torrc_path()
-    chroot_path = runner.get_chroot()
-    
-    if chroot_path and torrc_dst.startswith(chroot_path):
-      torrc_dst = torrc_dst[len(chroot_path):]
     
     with runner.get_tor_socket() as control_socket:
       control_socket.send("GETINFO config-file")
diff --git a/test/runner.py b/test/runner.py
index 286d4a8..ebbd55b 100644
--- a/test/runner.py
+++ b/test/runner.py
@@ -148,10 +148,7 @@ def exercise_controller(test_case, controller):
   """
   
   runner = get_runner()
-  torrc_path, chroot_path = runner.get_torrc_path(), runner.get_chroot()
-  
-  if chroot_path and torrc_path.startswith(chroot_path):
-    torrc_path = torrc_path[len(chroot_path):]
+  torrc_path = runner.get_torrc_path()
   
   if isinstance(controller, stem.socket.ControlSocket):
     controller.send("GETINFO config-file")
@@ -384,10 +381,14 @@ class Runner:
     else:
       return self._get("_test_dir")
   
-  def get_torrc_path(self):
+  def get_torrc_path(self, ignore_chroot = False):
     """
     Provides the absolute path for where our testing torrc resides.
     
+    Arguments:
+      ignore_chroot (bool) - provides the real path, rather than the one that
+                             tor expects if True
+    
     Returns:
       str with our torrc path
     
@@ -396,7 +397,12 @@ class Runner:
     """
     
     test_dir = self._get("_test_dir")
-    return os.path.join(test_dir, "torrc")
+    torrc_path = os.path.join(test_dir, "torrc")
+    
+    if not ignore_chroot and self._chroot_path and torrc_path.startswith(self._chroot_path):
+      torrc_path = torrc_path[len(self._chroot_path):]
+    
+    return torrc_path
   
   def get_torrc_contents(self):
     """
@@ -492,15 +498,14 @@ class Runner:
       authenticate (bool) - if True then the socket is authenticated
     
     Returns:
-      stem.socket.BaseController connected with our testing instance
+      stem.socket.Controller connected with our testing instance
     
     Raises:
       TorInaccessable if tor can't be connected to
     """
     
-    # TODO: replace with our general controller when we have one
     control_socket = self.get_tor_socket(authenticate)
-    return stem.control.BaseController(control_socket)
+    return stem.control.Controller(control_socket)
   
   def get_tor_version(self):
     """
diff --git a/test/unit/control/__init__.py b/test/unit/control/__init__.py
new file mode 100644
index 0000000..448a597
--- /dev/null
+++ b/test/unit/control/__init__.py
@@ -0,0 +1,6 @@
+"""
+Unit tests for stem.control.
+"""
+
+__all__ = ["controller"]
+
diff --git a/test/unit/control/getinfo.py b/test/unit/control/getinfo.py
new file mode 100644
index 0000000..3fc9fd3
--- /dev/null
+++ b/test/unit/control/getinfo.py
@@ -0,0 +1,119 @@
+"""
+Unit tests for the stem.control.GetInfoResponse class.
+"""
+
+import unittest
+
+import stem.connection
+import test.mocking as mocking
+
+EMPTY_RESPONSE = "250 OK"
+
+SINGLE_RESPONSE = """\
+250-version=0.2.3.11-alpha-dev
+250 OK"""
+
+BATCH_RESPONSE = """\
+250-version=0.2.3.11-alpha-dev
+250-address=67.137.76.214
+250-fingerprint=5FDE0422045DF0E1879A3738D09099EB4A0C5BA0
+250 OK"""
+
+MULTILINE_RESPONSE = """\
+250-version=0.2.3.11-alpha-dev (git-ef0bc7f8f26a917c)
+250+config-text=
+ControlPort 9051
+DataDirectory /home/atagar/.tor
+ExitPolicy reject *:*
+Log notice stdout
+Nickname Unnamed
+ORPort 9050
+.
+250 OK"""
+
+NON_KEY_VALUE_ENTRY = """\
+250-version=0.2.3.11-alpha-dev
+250-address 67.137.76.214
+250 OK"""
+
+MISSING_MULTILINE_NEWLINE = """\
+250+config-text=ControlPort 9051
+DataDirectory /home/atagar/.tor
+.
+250 OK"""
+
+class TestGetInfoResponse(unittest.TestCase):
+  def test_empty_response(self):
+    """
+    Parses a GETINFO reply without options (just calling "GETINFO").
+    """
+    
+    control_message = mocking.get_message(EMPTY_RESPONSE)
+    stem.control.GetInfoResponse.convert(control_message)
+    
+    # now this should be a GetInfoResponse (ControlMessage subclass)
+    self.assertTrue(isinstance(control_message, stem.socket.ControlMessage))
+    self.assertTrue(isinstance(control_message, stem.control.GetInfoResponse))
+    
+    self.assertEqual({}, control_message.values)
+  
+  def test_single_response(self):
+    """
+    Parses a GETINFO reply response for a single parameter.
+    """
+    
+    control_message = mocking.get_message(SINGLE_RESPONSE)
+    stem.control.GetInfoResponse.convert(control_message)
+    self.assertEqual({"version": "0.2.3.11-alpha-dev"}, control_message.values)
+  
+  def test_batch_response(self):
+    """
+    Parses a GETINFO reply for muiltiple parameters.
+    """
+    
+    control_message = mocking.get_message(BATCH_RESPONSE)
+    stem.control.GetInfoResponse.convert(control_message)
+    
+    expected = {
+      "version": "0.2.3.11-alpha-dev",
+      "address": "67.137.76.214",
+      "fingerprint": "5FDE0422045DF0E1879A3738D09099EB4A0C5BA0",
+    }
+    
+    self.assertEqual(expected, control_message.values)
+  
+  def test_multiline_response(self):
+    """
+    Parses a GETINFO reply for multiple parameters including a multi-line
+    value.
+    """
+    
+    control_message = mocking.get_message(MULTILINE_RESPONSE)
+    stem.control.GetInfoResponse.convert(control_message)
+    
+    expected = {
+      "version": "0.2.3.11-alpha-dev (git-ef0bc7f8f26a917c)",
+      "config-text": "\n".join(MULTILINE_RESPONSE.splitlines()[2:8]),
+    }
+    
+    self.assertEqual(expected, control_message.values)
+  
+  def test_invalid_non_mapping_content(self):
+    """
+    Parses a malformed GETINFO reply containing a line that isn't a key=value
+    entry.
+    """
+    
+    control_message = mocking.get_message(NON_KEY_VALUE_ENTRY)
+    self.assertRaises(stem.socket.ProtocolError, stem.control.GetInfoResponse.convert, control_message)
+  
+  def test_invalid_multiline_content(self):
+    """
+    Parses a malformed GETINFO reply with a multi-line entry missing a newline
+    between its key and value. This is a proper controller message, but
+    malformed according to the GETINFO's spec.
+    """
+    
+    control_message = mocking.get_message(MISSING_MULTILINE_NEWLINE)
+    self.assertRaises(stem.socket.ProtocolError, stem.control.GetInfoResponse.convert, control_message)
+

_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits