commit 717c5aaecc8e61cee5ca8f1bae80b3eade5f6985 Author: Damian Johnson atagar@torproject.org 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) +