December 2012 - tor-commits - lists.torproject.org

[translation/vidalia_alpha] Update translations for vidalia_alpha
by translation＠torproject.org 03 Dec '12

03 Dec '12

commit 853413ac25e4b19f5ebb7874f708beb04dd6fac0 Author: Translation commit bot <translation(a)torproject.org> Date: Mon Dec 3 02:45:20 2012 +0000 Update translations for vidalia_alpha --- es/vidalia_es.po | 48 ++++++++++++++++++++++++------------------------ 1 files changed, 24 insertions(+), 24 deletions(-) diff --git a/es/vidalia_es.po b/es/vidalia_es.po index 02f5e9d..94e5261 100644 --- a/es/vidalia_es.po +++ b/es/vidalia_es.po @@ -9,7 +9,7 @@ msgstr "" "Project-Id-Version: The Tor Project\n" "Report-Msgid-Bugs-To: https://trac.torproject.org/projects/tor\n" "POT-Creation-Date: 2012-03-21 17:46+0000\n" -"PO-Revision-Date: 2012-12-01 22:34+0000\n" +"PO-Revision-Date: 2012-12-03 02:45+0000\n" "Last-Translator: strel <strelnic(a)gmail.com>\n" "Language-Team: Spanish (http://www.transifex.com/projects/p/torproject/language/es/)\n" "MIME-Version: 1.0\n" @@ -62,7 +62,7 @@ msgstr "%1 no existe. ¿Desea crearlo?" msgctxt "AdvancedPage" msgid "Failed to Create File" -msgstr "Error al Crear Archivo" +msgstr "Error al crear el archivo" msgctxt "AdvancedPage" msgid "Unable to create %1 [%2]" @@ -70,15 +70,15 @@ msgstr "No se pudo crear %1 [%2]" msgctxt "AdvancedPage" msgid "Select a Directory to Use for Tor Data" -msgstr "Seleccione una Carpeta para Almacenar Datos de Tor" +msgstr "Seleccione una carpeta para almacenar datos de Tor" msgctxt "AdvancedPage" msgid "Unable to remove Tor Service" -msgstr "No se pudo eliminar el Servicio Tor" +msgstr "No se pudo eliminar el servicio Tor" msgctxt "AdvancedPage" msgid "Unable to install Tor Service" -msgstr "No se pudo instalar el Servicio Tor" +msgstr "No se pudo instalar el servicio Tor" msgctxt "AdvancedPage" msgid "Vidalia was unable to install the Tor service." @@ -130,7 +130,7 @@ msgstr "Examinar" msgctxt "AdvancedPage" msgid "Data Directory" -msgstr "Carpeta de Datos" +msgstr "Carpeta de datos" msgctxt "AdvancedPage" msgid "Store data for the Tor software in the following directory" @@ -172,13 +172,13 @@ msgctxt "AdvancedPage" msgid "" "The specified Tor configuration file location contains characters that " "cannot be represented in your system's current 8-bit character encoding." -msgstr "La ubicación especificada para el archivo de configuración de Tor (torrc) contiene caracteres que no se pueden representar en la actual codificación de caracteres de 8 bits de su sistema." +msgstr "La ubicación especificada para el archivo de configuración de Tor (torrc) contiene caracteres que no se pueden representar con la actual codificación de caracteres de 8 bits de su sistema." msgctxt "AdvancedPage" msgid "" "The specified Tor data directory location contains characters that cannot be" " represented in your system's current 8-bit character encoding." -msgstr "La ubicación especificada para la carpeta de datos de Tor contiene caracteres que no se puede representar en la actual codificación de caracteres de 8 bits de su sistema." +msgstr "La ubicación especificada para la carpeta de datos de Tor contiene caracteres que no se puede representar con la actual codificación de caracteres de 8 bits de su sistema." msgctxt "AdvancedPage" msgid "Warning" @@ -190,7 +190,7 @@ msgstr "Ha cambiado la ruta de torrc, ¿le gustaría reiniciar Tor?" msgctxt "AdvancedPage" msgid "Tor Configuration File (torrc);;All Files (*)" -msgstr "Archivo de Configuración Tor (torrc);;Todos los Archivos (*)" +msgstr "Archivo de configuración Tor (torrc);;Todos los archivos (*)" msgctxt "AdvancedPage" msgid "Select a file to use for Tor socket path" @@ -235,7 +235,7 @@ msgid "" "Vidalia was unable to remove the Tor service.\n" "\n" "You may need to remove it manually." -msgstr "Vidalia no fue capaz de eliminar el servicio de Tor.\n\nPuede que sea necesario eliminarlo de manera manual." +msgstr "Vidalia no fue capaz de eliminar el servicio de Tor.\n\nPuede ser necesario que lo elimine manualmente." msgctxt "AdvancedPage" msgid "Select a Directory to Use for Panic" @@ -296,15 +296,15 @@ msgstr "Reiniciar" msgctxt "BandwidthGraph" msgid "Receive Rate" -msgstr "Tasa de Recepción" +msgstr "Tasa de recepción" msgctxt "BandwidthGraph" msgid "Send Rate" -msgstr "Tasa de Envío" +msgstr "Tasa de envío" msgctxt "BandwidthGraph" msgid "Always on Top" -msgstr "Siempre Encima" +msgstr "Mostrar siempre encima" msgctxt "BandwidthGraph" msgid "Style" @@ -312,7 +312,7 @@ msgstr "Estilo" msgctxt "BandwidthGraph" msgid "Changes the transparency of the Bandwidth Graph" -msgstr "Cambia la transparencia del Gráfico de Ancho de Banda" +msgstr "Cambia la transparencia del Gráfico de ancho de banda" msgctxt "BandwidthGraph" msgid "100" @@ -332,11 +332,11 @@ msgstr "Cancelar" msgctxt "BandwidthGraph" msgid "Bandwidth Graph" -msgstr "Gráfico de Ancho de Banda" +msgstr "Gráfico de ancho de banda" msgctxt "BridgeDownloader" msgid "Starting HTTPS bridge request..." -msgstr "Iniciando solicitud de bridges (repetidores puente, entradas a Tor de propagación restringida) por HTTPS..." +msgstr "Iniciando solicitud de bridges (repetidores puente, entradas a Tor de publicidad restringida) por HTTPS..." msgctxt "BridgeDownloader" msgid "Connecting to %1:%2..." @@ -352,7 +352,7 @@ msgstr "Descargando una lista de bridges..." msgctxt "BridgeDownloaderProgressDialog" msgid "Downloading Bridges" -msgstr "Descargando Bridges (repetidores puente, entradas a Tor de propagación restringida)" +msgstr "Descargando bridges (repetidores puente. entradas a Tor de publicidad restringida)" msgctxt "BridgeDownloaderProgressDialog" msgid "Unable to download bridges: %1" @@ -372,15 +372,15 @@ msgstr "Nº. de Clientes" msgctxt "BridgeUsageDialog" msgid "Clients from the following countries have used your relay since %1" -msgstr "Clientes de los siguientes países han usado su repetidor bridge desde %1" +msgstr "Clientes de los siguientes países han usado su repetidor puente desde %1" msgctxt "BridgeUsageDialog" msgid "Bridge Usage Summary" -msgstr "Resumen de Uso del Bridge (repetidor puente, entrada a Tor de propagación reducida)" +msgstr "Resumen de uso del bridge (repetidor puente, entrada a Tor de publicidad restringida)" msgctxt "BridgeUsageDialog" msgid "Client Summary" -msgstr "Resumen del Cliente" +msgstr "Resumen del cliente" msgctxt "Circuit" msgid "New" @@ -396,7 +396,7 @@ msgstr "Construyendo" msgctxt "Circuit" msgid "Failed" -msgstr "Fallido" +msgstr "Fallo" msgctxt "Circuit" msgid "Closed" @@ -408,7 +408,7 @@ msgstr "Desconocido" msgctxt "CircuitItem" msgid "<Path Empty>" -msgstr "<Ruta Vacía>" +msgstr "<Ruta vacía>" msgctxt "CircuitListWidget" msgid "Connection" @@ -424,11 +424,11 @@ msgstr "Zoom al circuito" msgctxt "CircuitListWidget" msgid "Close Circuit (Del)" -msgstr "Cerrar Circuito (Del)" +msgstr "Cerrar circuito (Del)" msgctxt "CircuitListWidget" msgid "Close Stream (Del)" -msgstr "Cerrar Flujo (Del)" +msgstr "Cerrar flujo (Del)" msgctxt "ConfigDialog" msgid "General"

1 0

[stem/master] Base class for events
by atagar＠torproject.org 03 Dec '12

03 Dec '12

commit cac0c434ca9a4ed1f9bb6aa940dba1e006b92471 Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Nov 4 18:38:28 2012 -0800 Base class for events Adding a base class for tor events which does the initial parsing of positional and keyword arguments. This is using a similar design to the TorCtl patch I wrote for #3679 (but a little better). --- stem/control.py | 4 +- stem/response/__init__.py | 3 ++ stem/response/events.py | 65 ++++++++++++++++++++++++++++++++++++++ test/integ/control/controller.py | 8 +++-- 4 files changed, 75 insertions(+), 5 deletions(-) diff --git a/stem/control.py b/stem/control.py index ca3730b..fdcf972 100644 --- a/stem/control.py +++ b/stem/control.py @@ -1410,11 +1410,11 @@ class Controller(BaseController): def _handle_event(self, event_message): # TODO: parse the event_message into a stem.response.events.Event class - event_message_type = str(event_message).split()[0] + stem.response.convert("EVENT", event_message, arrived_at=time.time()) with self._event_listeners_lock: for event_type, event_listeners in self._event_listeners.items(): - if event_type == event_message_type: + if event_type == event_message.type: for listener in event_listeners: listener(event_message) diff --git a/stem/response/__init__.py b/stem/response/__init__.py index 050ba02..2e9296d 100644 --- a/stem/response/__init__.py +++ b/stem/response/__init__.py @@ -26,6 +26,7 @@ Parses replies from the control socket. from __future__ import with_statement __all__ = [ + "events", "getinfo", "getconf", "protocolinfo", @@ -85,6 +86,7 @@ def convert(response_type, message, **kwargs): or response_type isn't supported """ + import stem.response.events import stem.response.getinfo import stem.response.getconf import stem.response.protocolinfo @@ -95,6 +97,7 @@ def convert(response_type, message, **kwargs): raise TypeError("Only able to convert stem.response.ControlMessage instances") response_types = { + "EVENT": stem.response.events.Event, "GETINFO": stem.response.getinfo.GetInfoResponse, "GETCONF": stem.response.getconf.GetConfResponse, "MAPADDRESS": stem.response.mapaddress.MapAddressResponse, diff --git a/stem/response/events.py b/stem/response/events.py new file mode 100644 index 0000000..32dd655 --- /dev/null +++ b/stem/response/events.py @@ -0,0 +1,65 @@ +import re + +import stem.response + +# Matches keyword=value arguments. This can't be a simple "(.*)=(.*)" pattern +# because some positional arguments, like circuit paths, can have an equal +# sign. + +KW_ARG = re.compile("([A-Za-z0-9_]+)=(.*)") + +class Event(stem.response.ControlMessage): + """ + Base for events we receive asynchronously, as described in section 4.1 of the + `control-spec + <https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt>`_. + """ + + _POSITIONAL_ARGS = () + _KEYWORD_ARGS = {} + + def _parse_message(self, arrived_at): + fields = str(self).split() + + if not fields: + raise stem.socket.ProtocolError("Received a blank tor event. Events must at the very least have a type.") + + self.type = fields.pop(0) + self.arrived_at = arrived_at + + # Tor events contain some number of positional arguments followed by + # key/value mappings. Parsing keyword arguments from the end until we hit + # something that isn't a key/value mapping. The rest are positional. + + self.positional_args = [] + self.keyword_args = {} + + while fields: + kw_match = KW_ARG.match(fields[-1]) + + if kw_match: + k, v = kw_match.groups() + self.keyword_args[k] = v + fields.pop() # remove the field + else: + # not a key/value mapping, the remaining fields are positional + self.positional_args = fields + break + + # Setting attributes for the fields that we recognize. Unrecognized fields + # only appear in our 'positional_args' and 'keyword_args' attributes. + + for i in xrange(len(self._POSITIONAL_ARGS)): + attr_name = self._POSITIONAL_ARGS[i] + attr_value = self.positional_args[i] if i < len(self.positional_args) else None + + setattr(self, attr_name, attr_value) + + for controller_attr_name, attr_name in self._KEYWORD_ARGS.items(): + setattr(self, attr_name, self.keyword_args.get(controller_attr_name)) + + # if we're a recognized event type then translate ourselves into that subclass + + #self.__class__ = response_class + #self._parse_message() + diff --git a/test/integ/control/controller.py b/test/integ/control/controller.py index e5d7782..8f93d53 100644 --- a/test/integ/control/controller.py +++ b/test/integ/control/controller.py @@ -74,9 +74,6 @@ class TestController(unittest.TestCase): # BW events occure at the rate of one per second, so wait a bit to let # some accumulate. - # TODO: check that the type of events in event_buffer1 are BandwidthEvent - # instances when we have proper event types - time.sleep(3) self.assertTrue(len(event_buffer1) >= 2) @@ -91,6 +88,11 @@ class TestController(unittest.TestCase): self.assertTrue(len(event_buffer1) >= 4) self.assertEqual(buffer2_size, len(event_buffer2)) + + for event in event_buffer1: + self.assertTrue(isinstance(event, stem.response.events.Event)) + self.assertEqual(2, len(event.positional_args)) + self.assertEqual({}, event.keyword_args) def test_getinfo(self): """

1 0

[stem/master] Unit test for add_event_listener() example
by atagar＠torproject.org 03 Dec '12

03 Dec '12

commit 1a6a4d55701aaa199c14e1ef1ee1b6455922d761 Author: Damian Johnson <atagar(a)torproject.org> Date: Mon Nov 5 08:02:15 2012 -0800 Unit test for add_event_listener() example Adding a unit test for the pydoc example in add_event_listener(). I really, really don't like how the tests for these documentation examples are turning out. The end result looks precious little like the example and is convoluted as hell. We should revisit how we do documentation example testing in the future, but that'll be a subproject in itself. --- run_tests.py | 2 + stem/control.py | 2 +- test/unit/response/__init__.py | 1 + test/unit/response/events.py | 43 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 47 insertions(+), 1 deletions(-) diff --git a/run_tests.py b/run_tests.py index b4f0c06..f490da7 100755 --- a/run_tests.py +++ b/run_tests.py @@ -27,6 +27,7 @@ import test.unit.descriptor.networkstatus.document_v2 import test.unit.descriptor.networkstatus.document_v3 import test.unit.response.control_line import test.unit.response.control_message +import test.unit.response.events import test.unit.response.getinfo import test.unit.response.getconf import test.unit.response.protocolinfo @@ -133,6 +134,7 @@ UNIT_TESTS = ( test.unit.tutorial.TestTutorial, test.unit.response.control_message.TestControlMessage, test.unit.response.control_line.TestControlLine, + test.unit.response.events.TestEvents, test.unit.response.getinfo.TestGetInfoResponse, test.unit.response.getconf.TestGetConfResponse, test.unit.response.singleline.TestSingleLineResponse, diff --git a/stem/control.py b/stem/control.py index e07658d..c2a94aa 100644 --- a/stem/control.py +++ b/stem/control.py @@ -1422,7 +1422,7 @@ class Controller(BaseController): return response.entries def _handle_event(self, event_message): - stem.response.convert("EVENT", event_message, arrived_at=time.time()) + stem.response.convert("EVENT", event_message, arrived_at = time.time()) with self._event_listeners_lock: for event_type, event_listeners in self._event_listeners.items(): diff --git a/test/unit/response/__init__.py b/test/unit/response/__init__.py index 530a5d3..51f3cd1 100644 --- a/test/unit/response/__init__.py +++ b/test/unit/response/__init__.py @@ -5,6 +5,7 @@ Unit tests for stem.response. __all__ = [ "control_message", "control_line", + "events", "getinfo", "getconf", "protocolinfo", diff --git a/test/unit/response/events.py b/test/unit/response/events.py new file mode 100644 index 0000000..b1111bc --- /dev/null +++ b/test/unit/response/events.py @@ -0,0 +1,43 @@ +""" +Unit tests for the stem.response.events classes. +""" + +import threading +import unittest + +import stem.response +import test.mocking as mocking + +class TestEvents(unittest.TestCase): + def test_example(self): + """ + Exercises the add_event_listener() pydoc example, but without the sleep(). + """ + + import time + from stem.control import Controller, EventType + + def print_bw(event): + msg = "sent: %i, received: %i" % (event.written, event.read) + self.assertEqual("sent: 25, received: 15", msg) + + def event_sender(): + for i in xrange(3): + controller_event = mocking.get_message("650 BW 15 25") + stem.response.convert("EVENT", controller_event, arrived_at = 25) + print_bw(controller_event) + time.sleep(0.05) + + controller = mocking.get_object(Controller, { + 'authenticate': mocking.no_op(), + 'add_event_listener': mocking.no_op(), + }) + + controller.authenticate() + controller.add_event_listener(print_bw, EventType.BW) + + events_thread = threading.Thread(target = event_sender) + events_thread.start() + time.sleep(0.2) + events_thread.join() +

1 0

[stem/master] Adding a add_event_listener() example
by atagar＠torproject.org 03 Dec '12

03 Dec '12

commit cc530bb2005f0e156c62fe322d5b43ffe16c3e99 Author: Damian Johnson <atagar(a)torproject.org> Date: Mon Nov 5 07:20:49 2012 -0800 Adding a add_event_listener() example On reflection the example that I included on ticket #7328 is pretty good at exemplifying the function's usage, so including it in our pydocs. --- stem/control.py | 16 +++++++++++++++- 1 files changed, 15 insertions(+), 1 deletions(-) diff --git a/stem/control.py b/stem/control.py index bfb907c..e07658d 100644 --- a/stem/control.py +++ b/stem/control.py @@ -563,7 +563,21 @@ class Controller(BaseController): """ Directs further tor controller events to a given function. The function is expected to take a single argument, which is a - :class:`~stem.response.events.Event` subclass. + :class:`~stem.response.events.Event` subclass. For instance the following + would would print the bytes sent and received by tor over five seconds... + + :: + + import time + from stem.control import Controller, EventType + + def print_bw(event): + print "sent: %i, received: %i" % (event.written, event.read) + + with Controller.from_port(control_port = 9051) as controller: + controller.authenticate() + controller.add_event_listener(print_bw, EventType.BW) + time.sleep(5) If a new control connection is initialized then this listener will be reattached.

1 0

[stem/master] BandwidthEvent class
by atagar＠torproject.org 03 Dec '12

03 Dec '12

commit c35a626af19a5d22b8cc1ca1cef5bae212e3a726 Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Nov 4 21:06:05 2012 -0800 BandwidthEvent class Adding a class to handle BW events. This is the easiest type of tor event to test because it's emitted every second. The other event types we'll probably need to go with unit tests. --- stem/control.py | 2 -- stem/response/events.py | 34 +++++++++++++++++++++++++++++++--- test/integ/control/controller.py | 4 ++++ 3 files changed, 35 insertions(+), 5 deletions(-) diff --git a/stem/control.py b/stem/control.py index fdcf972..bfb907c 100644 --- a/stem/control.py +++ b/stem/control.py @@ -1408,8 +1408,6 @@ class Controller(BaseController): return response.entries def _handle_event(self, event_message): - # TODO: parse the event_message into a stem.response.events.Event class - stem.response.convert("EVENT", event_message, arrived_at=time.time()) with self._event_listeners_lock: diff --git a/stem/response/events.py b/stem/response/events.py index 32dd655..7a2f9da 100644 --- a/stem/response/events.py +++ b/stem/response/events.py @@ -1,6 +1,7 @@ import re import stem.response +import stem.socket # Matches keyword=value arguments. This can't be a simple "(.*)=(.*)" pattern # because some positional arguments, like circuit paths, can have an equal @@ -27,6 +28,11 @@ class Event(stem.response.ControlMessage): self.type = fields.pop(0) self.arrived_at = arrived_at + # if we're a recognized event type then translate ourselves into that subclass + + if self.type in EVENT_TYPE_TO_CLASS: + self.__class__ = EVENT_TYPE_TO_CLASS[self.type] + # Tor events contain some number of positional arguments followed by # key/value mappings. Parsing keyword arguments from the end until we hit # something that isn't a key/value mapping. The rest are positional. @@ -58,8 +64,30 @@ class Event(stem.response.ControlMessage): for controller_attr_name, attr_name in self._KEYWORD_ARGS.items(): setattr(self, attr_name, self.keyword_args.get(controller_attr_name)) - # if we're a recognized event type then translate ourselves into that subclass + self._parse() + + # method overwritten by our subclasses for special handling that they do + def _parse(self): + pass + +class BandwidthEvent(Event): + """ + Event emitted every second with the bytes sent and received by tor. + + :var long read: bytes received by tor that second + :var long written: bytes sent by tor that second + """ + + _POSITIONAL_ARGS = ("read", "written") + + def _parse(self): + if (self.read and not self.read.isdigit()) or (self.written and not self.written.isdigit()): + raise stem.socket.ProtocolError("A BW event's bytes sent and received values should be numeric, received: %s" % self) - #self.__class__ = response_class - #self._parse_message() + self.read = long(self.read) + self.written = long(self.written) + +EVENT_TYPE_TO_CLASS = { + "BW": BandwidthEvent, +} diff --git a/test/integ/control/controller.py b/test/integ/control/controller.py index 8f93d53..496028c 100644 --- a/test/integ/control/controller.py +++ b/test/integ/control/controller.py @@ -93,6 +93,10 @@ class TestController(unittest.TestCase): self.assertTrue(isinstance(event, stem.response.events.Event)) self.assertEqual(2, len(event.positional_args)) self.assertEqual({}, event.keyword_args) + + self.assertTrue(isinstance(event, stem.response.events.BandwidthEvent)) + self.assertTrue(hasattr(event, 'read')) + self.assertTrue(hasattr(event, 'written')) def test_getinfo(self): """

1 0

[stem/master] BW event unit tests
by atagar＠torproject.org 03 Dec '12

03 Dec '12

commit 1d2d684e3975e0e55369485b3d75155e90ea6aef Author: Damian Johnson <atagar(a)torproject.org> Date: Mon Nov 5 08:36:05 2012 -0800 BW event unit tests Adding a few simple unit tests for the BandwidthEvent class. --- stem/response/events.py | 8 ++++++-- test/unit/response/events.py | 38 +++++++++++++++++++++++++++++++++++--- 2 files changed, 41 insertions(+), 5 deletions(-) diff --git a/stem/response/events.py b/stem/response/events.py index 7a2f9da..fa451c7 100644 --- a/stem/response/events.py +++ b/stem/response/events.py @@ -81,8 +81,12 @@ class BandwidthEvent(Event): _POSITIONAL_ARGS = ("read", "written") def _parse(self): - if (self.read and not self.read.isdigit()) or (self.written and not self.written.isdigit()): - raise stem.socket.ProtocolError("A BW event's bytes sent and received values should be numeric, received: %s" % self) + if not self.read: + raise stem.socket.ProtocolError("BW event is missing its read value") + elif not self.written: + raise stem.socket.ProtocolError("BW event is missing its written value") + elif not self.read.isdigit() or not self.written.isdigit(): + raise stem.socket.ProtocolError("A BW event's bytes sent and received should be a positive numeric value, received: %s" % self) self.read = long(self.read) self.written = long(self.written) diff --git a/test/unit/response/events.py b/test/unit/response/events.py index b1111bc..1dea7c7 100644 --- a/test/unit/response/events.py +++ b/test/unit/response/events.py @@ -6,8 +6,16 @@ import threading import unittest import stem.response +import stem.response.events import test.mocking as mocking +from stem.socket import ProtocolError + +def _get_event(content): + controller_event = mocking.get_message(content) + stem.response.convert("EVENT", controller_event, arrived_at = 25) + return controller_event + class TestEvents(unittest.TestCase): def test_example(self): """ @@ -23,9 +31,7 @@ class TestEvents(unittest.TestCase): def event_sender(): for i in xrange(3): - controller_event = mocking.get_message("650 BW 15 25") - stem.response.convert("EVENT", controller_event, arrived_at = 25) - print_bw(controller_event) + print_bw(_get_event("650 BW 15 25")) time.sleep(0.05) controller = mocking.get_object(Controller, { @@ -40,4 +46,30 @@ class TestEvents(unittest.TestCase): events_thread.start() time.sleep(0.2) events_thread.join() + + def test_bw_event(self): + event = _get_event("650 BW 15 25") + + self.assertTrue(isinstance(event, stem.response.events.BandwidthEvent)) + self.assertEqual(15, event.read) + self.assertEqual(25, event.written) + + event = _get_event("650 BW 0 0") + self.assertEqual(0, event.read) + self.assertEqual(0, event.written) + + # BW events are documented as possibly having various keywords including + # DIR, OR, EXIT, and APP in the future. This is kinda a pointless note + # since tor doesn't actually do it yet (and likely never will), but might + # as well sanity test that it'll be ok. + + event = _get_event("650 BW 10 20 OR=5 EXIT=500") + self.assertEqual(10, event.read) + self.assertEqual(20, event.written) + self.assertEqual({'OR': '5', 'EXIT': '500'}, event.keyword_args) + + self.assertRaises(ProtocolError, _get_event, "650 BW 15") + self.assertRaises(ProtocolError, _get_event, "650 BW -15 25") + self.assertRaises(ProtocolError, _get_event, "650 BW 15 -25") + self.assertRaises(ProtocolError, _get_event, "650 BW x 25")

1 0

[stem/master] Support for logging events
by atagar＠torproject.org 03 Dec '12

03 Dec '12

commit 7ba579494215a5353cff1db9fbf7e59d6b666af9 Author: Damian Johnson <atagar(a)torproject.org> Date: Mon Nov 5 09:14:07 2012 -0800 Support for logging events Adding an event class for DEBUG, INFO, NOTICE, WARN, and ERR. --- docs/api/response.rst | 1 + stem/control.py | 15 ++++++++++----- stem/response/events.py | 27 +++++++++++++++++++++++++++ test/unit/response/events.py | 19 +++++++++++++++++++ 4 files changed, 57 insertions(+), 5 deletions(-) diff --git a/docs/api/response.rst b/docs/api/response.rst index 6e23c91..fd6e2cc 100644 --- a/docs/api/response.rst +++ b/docs/api/response.rst @@ -16,5 +16,6 @@ Events ------ .. autoclass:: stem.response.events.Event +.. autoclass:: stem.response.events.LogEvent .. autoclass:: stem.response.events.BandwidthEvent diff --git a/stem/control.py b/stem/control.py index f9f7def..baeb96e 100644 --- a/stem/control.py +++ b/stem/control.py @@ -590,11 +590,16 @@ class Controller(BaseController): The EventType enumeration is mapped to event classes as follows... - ========= =========== - EventType Event Class - ========= =========== - **BW** :class:`stem.response.events.BandwidthEvent` - ========= =========== + =========== =========== + EventType Event Class + =========== =========== + **DEBUG** :class:`stem.response.events.LogEvent` + **INFO** :class:`stem.response.events.LogEvent` + **NOTICE** :class:`stem.response.events.LogEvent` + **WARN** :class:`stem.response.events.LogEvent` + **ERR** :class:`stem.response.events.LogEvent` + **BW** :class:`stem.response.events.BandwidthEvent` + =========== =========== :param functor listener: function to be called when an event is received :param stem.control.EventType events: event types to be listened for diff --git a/stem/response/events.py b/stem/response/events.py index fa451c7..93c3191 100644 --- a/stem/response/events.py +++ b/stem/response/events.py @@ -14,6 +14,11 @@ class Event(stem.response.ControlMessage): Base for events we receive asynchronously, as described in section 4.1 of the `control-spec <https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt>`_. + + :var str type: event type + :var int arrived_at: unix timestamp for when the message arrived + :var list positional_args: positional arguments of the event + :var dict keyword_args: key/value arguments of the event """ _POSITIONAL_ARGS = () @@ -91,7 +96,29 @@ class BandwidthEvent(Event): self.read = long(self.read) self.written = long(self.written) +class LogEvent(Event): + """ + Tor logging event. These are the most visible kind of event since, by + default, tor logs at the NOTICE runlevel to stdout. + + :var str runlevel: runlevel of the logged message + :var str message: logged message + """ + + def _parse(self): + self.runlevel = self.type + + # message is our content, minus the runlevel and ending "OK" if a + # multi-line message + + self.message = str(self)[len(self.runlevel) + 1:].rstrip("\nOK") + EVENT_TYPE_TO_CLASS = { "BW": BandwidthEvent, + "DEBUG": LogEvent, + "INFO": LogEvent, + "NOTICE": LogEvent, + "WARN": LogEvent, + "ERR": LogEvent, } diff --git a/test/unit/response/events.py b/test/unit/response/events.py index 1dea7c7..1942b69 100644 --- a/test/unit/response/events.py +++ b/test/unit/response/events.py @@ -72,4 +72,23 @@ class TestEvents(unittest.TestCase): self.assertRaises(ProtocolError, _get_event, "650 BW -15 25") self.assertRaises(ProtocolError, _get_event, "650 BW 15 -25") self.assertRaises(ProtocolError, _get_event, "650 BW x 25") + + def test_log_events(self): + event = _get_event("650 DEBUG connection_edge_process_relay_cell(): Got an extended cell! Yay.") + + self.assertTrue(isinstance(event, stem.response.events.LogEvent)) + self.assertEqual("DEBUG", event.runlevel) + self.assertEqual("connection_edge_process_relay_cell(): Got an extended cell! Yay.", event.message) + + event = _get_event("650 INFO circuit_finish_handshake(): Finished building circuit hop:") + + self.assertTrue(isinstance(event, stem.response.events.LogEvent)) + self.assertEqual("INFO", event.runlevel) + self.assertEqual("circuit_finish_handshake(): Finished building circuit hop:", event.message) + + event = _get_event("650+WARN\na multi-line\nwarning message\n.\n650 OK\n") + + self.assertTrue(isinstance(event, stem.response.events.LogEvent)) + self.assertEqual("WARN", event.runlevel) + self.assertEqual("a multi-line\nwarning message", event.message)

1 0

[stem/master] EventType to Event subclass table
by atagar＠torproject.org 03 Dec '12

03 Dec '12

commit 1d56eb59e256977d34f9d3d77e4e0b8c2df49f86 Author: Damian Johnson <atagar(a)torproject.org> Date: Mon Nov 5 08:21:30 2012 -0800 EventType to Event subclass table Adding a table that'll list the EventType enumerations and map them to Event subclasses. --- docs/api/response.rst | 6 ++++++ stem/control.py | 18 ++++++++++++++++-- 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/api/response.rst b/docs/api/response.rst index bf3b722..6e23c91 100644 --- a/docs/api/response.rst +++ b/docs/api/response.rst @@ -12,3 +12,9 @@ Responses .. autoclass:: stem.response.mapaddress.MapAddressResponse .. autoclass:: stem.response.protocolinfo.ProtocolInfoResponse +Events +------ + +.. autoclass:: stem.response.events.Event +.. autoclass:: stem.response.events.BandwidthEvent + diff --git a/stem/control.py b/stem/control.py index c2a94aa..f9f7def 100644 --- a/stem/control.py +++ b/stem/control.py @@ -543,6 +543,15 @@ class Controller(BaseController): self._event_listeners = {} self._event_listeners_lock = threading.RLock() + # TODO: We want the capability of taking post-authentication actions, for + # instance to call SETEVENTS so our event listeners will work on new + # connections. The trouble is that the user could do this by a variety of + # methods (authenticate(), msg(), stem.connection.authenticete(), etc)... + # + # When we get it figured out we should add the pydoc comment: + # If a new control connection is initialized then this listener will be + # reattached. + # number of sequential 'GETINFO ip-to-country/*' lookups that have failed self._geoip_failure_count = 0 self.enabled_features = [] @@ -579,8 +588,13 @@ class Controller(BaseController): controller.add_event_listener(print_bw, EventType.BW) time.sleep(5) - If a new control connection is initialized then this listener will be - reattached. + The EventType enumeration is mapped to event classes as follows... + + ========= =========== + EventType Event Class + ========= =========== + **BW** :class:`stem.response.events.BandwidthEvent` + ========= =========== :param functor listener: function to be called when an event is received :param stem.control.EventType events: event types to be listened for

1 0

[stem/master] Enum docs for stem.control.EventType
by atagar＠torproject.org 03 Dec '12

03 Dec '12

commit d7dc386533f0b7885f2966922b9cb051c1b89384 Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Nov 11 12:36:37 2012 -0800 Enum docs for stem.control.EventType I had been doing a table for the EventType enum under the add_event_listener() method. This made sense and matched with what I'm doing for enumeration documentation except that this should be a interlinkable :data: field in our header. --- stem/control.py | 45 +++++++++++++++++++++++++-------------------- 1 files changed, 25 insertions(+), 20 deletions(-) diff --git a/stem/control.py b/stem/control.py index 846aba7..1c1139f 100644 --- a/stem/control.py +++ b/stem/control.py @@ -54,13 +54,31 @@ providing its own for interacting at a higher level. Enumeration for states that a controller can have. - ====== =========== - State Description - ====== =========== - INIT new control connection - RESET received a reset/sighup signal - CLOSED control connection closed - ====== =========== + ========== =========== + State Description + ========== =========== + **INIT** new control connection + **RESET** received a reset/sighup signal + **CLOSED** control connection closed + ========== =========== + +.. data:: EventType (enum) + + Known types of events that the + :func:`~stem.control.Controller.add_event_listener` method of the + :class:`~stem.control.Controller` can listen for. Enums are mapped to + :class:`~stem.response.events.Event` subclasses as follows... + + =========== =========== + EventType Event Class + =========== =========== + **DEBUG** :class:`stem.response.events.LogEvent` + **INFO** :class:`stem.response.events.LogEvent` + **NOTICE** :class:`stem.response.events.LogEvent` + **WARN** :class:`stem.response.events.LogEvent` + **ERR** :class:`stem.response.events.LogEvent` + **BW** :class:`stem.response.events.BandwidthEvent` + =========== =========== """ from __future__ import with_statement @@ -596,19 +614,6 @@ class Controller(BaseController): controller.add_event_listener(print_bw, EventType.BW) time.sleep(5) - The EventType enumeration is mapped to event classes as follows... - - =========== =========== - EventType Event Class - =========== =========== - **DEBUG** :class:`stem.response.events.LogEvent` - **INFO** :class:`stem.response.events.LogEvent` - **NOTICE** :class:`stem.response.events.LogEvent` - **WARN** :class:`stem.response.events.LogEvent` - **ERR** :class:`stem.response.events.LogEvent` - **BW** :class:`stem.response.events.BandwidthEvent` - =========== =========== - :param functor listener: function to be called when an event is received :param stem.control.EventType events: event types to be listened for

1 0

[stem/master] Support for CIRC events
by atagar＠torproject.org 03 Dec '12

03 Dec '12

commit a349a01fece5534195a6619d72df4944065001b8 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Nov 17 18:49:23 2012 -0800 Support for CIRC events Implementation and testing for CIRC events. This work also concerns the 'GETINFO circuit-status' method, which is defined as providing the same output as CIRC events. This is part of the reason why I put the enums for the event attributes in 'stem.control'. --- docs/api/response.rst | 1 + run_tests.py | 2 + stem/control.py | 227 +++++++++++++++++++++++++++++++++++++++ stem/response/events.py | 92 +++++++++++++++- stem/util/str_tools.py | 36 ++++++ stem/util/tor_tools.py | 18 +++ test/unit/__init__.py | 1 + test/unit/control/__init__.py | 6 + test/unit/control/controller.py | 50 +++++++++ test/unit/response/events.py | 124 +++++++++++++++++++++- test/unit/util/str_tools.py | 31 ++++++ 11 files changed, 582 insertions(+), 6 deletions(-) diff --git a/docs/api/response.rst b/docs/api/response.rst index fd6e2cc..043cae4 100644 --- a/docs/api/response.rst +++ b/docs/api/response.rst @@ -18,4 +18,5 @@ Events .. autoclass:: stem.response.events.Event .. autoclass:: stem.response.events.LogEvent .. autoclass:: stem.response.events.BandwidthEvent +.. autoclass:: stem.response.events.CircuitEvent diff --git a/run_tests.py b/run_tests.py index f490da7..a9aebbe 100755 --- a/run_tests.py +++ b/run_tests.py @@ -16,6 +16,7 @@ import test.output import test.runner import test.check_whitespace import test.unit.connection.authentication +import test.unit.control.controller import test.unit.descriptor.export import test.unit.descriptor.reader import test.unit.descriptor.server_descriptor @@ -142,6 +143,7 @@ UNIT_TESTS = ( test.unit.response.protocolinfo.TestProtocolInfoResponse, test.unit.response.authchallenge.TestAuthChallengeResponse, test.unit.connection.authentication.TestAuthenticate, + test.unit.control.controller.TestControl, ) INTEG_TESTS = ( diff --git a/stem/control.py b/stem/control.py index 1c1139f..083082e 100644 --- a/stem/control.py +++ b/stem/control.py @@ -78,7 +78,110 @@ providing its own for interacting at a higher level. **WARN** :class:`stem.response.events.LogEvent` **ERR** :class:`stem.response.events.LogEvent` **BW** :class:`stem.response.events.BandwidthEvent` + **CIRC** :class:`stem.response.events.CircuitEvent` =========== =========== + +.. data:: CircStatus (enum) + + Statuses that a circuit can be in. Tor may provide statuses not in this enum. + + ============ =========== + CircStatus Description + ============ =========== + **LAUNCHED** new circuit was created + **BUILT** circuit finished being created and can accept traffic + **EXTENDED** circuit has been extended by a hop + **FAILED** circuit construction failed + **CLOSED** circuit has been closed + ============ =========== + +.. data:: CircBuildFlag (enum) + + Attributes about how a circuit is built. These were introduced in tor version + 0.2.3.11. Tor may provide flags not in this enum. + + ================= =========== + CircBuildFlag Description + ================= =========== + **ONEHOP_TUNNEL** single hop circuit to fetch directory information + **IS_INTERNAL** circuit that won't be used for client traffic + **NEED_CAPACITY** circuit only includes high capacity relays + **NEED_UPTIME** circuit only includes relays with a high uptime + ================= =========== + +.. data:: CircPurpose (enum) + + Description of what a circuit is intended for. These were introduced in tor + version 0.2.1.6. Tor may provide purposes not in this enum. + + ==================== =========== + CircPurpose Description + ==================== =========== + **GENERAL** client traffic or fetching directory information + **HS_CLIENT_INTRO** client side introduction point for a hidden service circuit + **HS_CLIENT_REND** client side hidden service rendezvous circuit + **HS_SERVICE_INTRO** server side introduction point for a hidden service circuit + **HS_SERVICE_REND** server side hidden service rendezvous circuit + **TESTING** testing to see if we're reachable, so we can be used as a relay + **CONTROLLER** circuit that was built by a controller + ==================== =========== + +.. data:: CircClosureReason (enum) + + Reason that a circuit is being closed or failed to be established. Tor may + provide purposes not in this enum. + + ========================= =========== + CircClosureReason Description + ========================= =========== + **NONE** no reason given + **TORPROTOCOL** violation in the tor protocol + **INTERNAL** internal error + **REQUESTED** requested by the client via a TRUNCATE command + **HIBERNATING** relay is presently hibernating + **RESOURCELIMIT** relay is out of memory, sockets, or circuit IDs + **CONNECTFAILED** unable to contact the relay + **OR_IDENTITY** relay had the wrong OR identification + **OR_CONN_CLOSED** connection failed after being established + **FINISHED** circuit has expired (see tor's MaxCircuitDirtiness config option) + **TIMEOUT** circuit construction timed out + **DESTROYED** circuit unexpectedly closed + **NOPATH** not enough relays to make a circuit + **NOSUCHSERVICE** requested hidden service does not exist + **MEASUREMENT_EXPIRED** unknown (https://trac.torproject.org/7506) + ========================= =========== + +.. data:: HiddenServiceState (enum) + + State that a hidden service circuit can have. These were introduced in tor + version 0.2.3.11. Tor may provide states not in this enum. + + Enumerations fall into four groups based on their prefix... + + ======= =========== + Prefix Description + ======= =========== + HSCI_* client-side introduction-point + HSCR_* client-side rendezvous-point + HSSI_* service-side introduction-point + HSSR_* service-side rendezvous-point + ======= =========== + + ============================= =========== + HiddenServiceState Description + ============================= =========== + **HSCI_CONNECTING** connecting to the introductory point + **HSCI_INTRO_SENT** sent INTRODUCE1 and awaiting a reply + **HSCI_DONE** received a reply, circuit is closing + **HSCR_CONNECTING** connecting to the introductory point + **HSCR_ESTABLISHED_IDLE** rendezvous-point established, awaiting an introduction + **HSCR_ESTABLISHED_WAITING** introduction received, awaiting a rend + **HSCR_JOINED** connected to the hidden service + **HSSI_CONNECTING** connecting to the introductory point + **HSSI_ESTABLISHED** established introductory point + **HSSR_CONNECTING** connecting to the introductory point + **HSSR_JOINED** connected to the rendezvous-point + ============================= =========== """ from __future__ import with_statement @@ -129,6 +232,63 @@ EventType = stem.util.enum.UppercaseEnum( "CIRC_MINOR", ) +CircStatus = stem.util.enum.UppercaseEnum( + "LAUNCHED", + "BUILT", + "EXTENDED", + "FAILED", + "CLOSED", +) + +CircBuildFlag = stem.util.enum.UppercaseEnum( + "ONEHOP_TUNNEL", + "IS_INTERNAL", + "NEED_CAPACITY", + "NEED_UPTIME", +) + +CircPurpose = stem.util.enum.UppercaseEnum( + "GENERAL", + "HS_CLIENT_INTRO", + "HS_CLIENT_REND", + "HS_SERVICE_INTRO", + "HS_SERVICE_REND", + "TESTING", + "CONTROLLER", +) + +CircClosureReason = stem.util.enum.UppercaseEnum( + "NONE", + "TORPROTOCOL", + "INTERNAL", + "REQUESTED", + "HIBERNATING", + "RESOURCELIMIT", + "CONNECTFAILED", + "OR_IDENTITY", + "OR_CONN_CLOSED", + "FINISHED", + "TIMEOUT", + "DESTROYED", + "NOPATH", + "NOSUCHSERVICE", + "MEASUREMENT_EXPIRED", +) + +HiddenServiceState = stem.util.enum.UppercaseEnum( + "HSCI_CONNECTING", + "HSCI_INTRO_SENT", + "HSCI_DONE", + "HSCR_CONNECTING", + "HSCR_ESTABLISHED_IDLE", + "HSCR_ESTABLISHED_WAITING", + "HSCR_JOINED", + "HSSI_CONNECTING", + "HSSI_ESTABLISHED", + "HSSR_CONNECTING", + "HSSR_JOINED", +) + # 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 fairly unique... @@ -521,6 +681,9 @@ class Controller(BaseController): BaseController and provides a more user friendly API for library users. """ + # TODO: We need a set_up() (and maybe tear_down()?) method, so we can + # reattach listeners and set VERBOSE_NAMES. + def from_port(control_addr = "127.0.0.1", control_port = 9051): """ Constructs a :class:`~stem.socket.ControlPort` based Controller. @@ -1462,6 +1625,70 @@ class Controller(BaseController): for listener in event_listeners: listener(event_message) +def _parse_circ_path(path): + """ + Parses a circuit path as a list of **(fingerprint, nickname)** tuples. Tor + circuit paths are defined as being of the form... + + :: + + Path = LongName *("," LongName) + LongName = Fingerprint [ ( "=" / "~" ) Nickname ] + + example: + $999A226EBED397F331B612FE1E4CFAE5C1F201BA=piyaz + + ... *unless* this is prior to tor version 0.2.2.1 with the VERBOSE_NAMES + feature turned off (or before version 0.1.2.2 where the feature was + introduced). In that case either the fingerprint or nickname in the tuple + will be **None**, depending on which is missing. + + :: + + Path = ServerID *("," ServerID) + ServerID = Nickname / Fingerprint + + example: + $E57A476CD4DFBD99B4EE52A100A58610AD6E80B9,hamburgerphone,PrivacyRepublic14 + + :param str path: circuit path to be parsed + + :returns: list of **(fingerprint, nickname)** tuples, fingerprints do not have a proceeding '$' + + :raises: :class:`stem.ProtocolError` if the path is malformed + """ + + if not path: return [] + + circ_path = [] + + for path_component in path.split(','): + if '=' in path_component: + # common case + fingerprint, nickname = path_component.split('=') + elif '~' in path_component: + # this is allowed for by the spec, but I've never seen it used + fingerprint, nickname = path_component.split('~') + elif path_component[0] == '$': + # old style, fingerprint only + fingerprint, nickname = path_component, None + else: + # old style, nickname only + fingerprint, nickname = None, path_component + + if fingerprint != None: + if not stem.util.tor_tools.is_valid_fingerprint(fingerprint, True): + raise stem.ProtocolError("Fingerprint in the circuit path is malformed (%s): %s" % (fingerprint, path)) + + fingerprint = fingerprint[1:] # strip off the leading '$' + + if nickname != None and not stem.util.tor_tools.is_valid_nickname(nickname): + raise stem.ProtocolError("Nickname in the circuit path is malformed (%s): %s" % (fingerprint, path)) + + circ_path.append((fingerprint, nickname)) + + return circ_path + def _case_insensitive_lookup(entries, key, default = UNDEFINED): """ Makes a case insensitive lookup within a list or dictionary, providing the diff --git a/stem/response/events.py b/stem/response/events.py index 93c3191..4c8d8bd 100644 --- a/stem/response/events.py +++ b/stem/response/events.py @@ -1,7 +1,9 @@ import re +import stem.control import stem.response -import stem.socket + +from stem.util import log, str_tools, tor_tools # Matches keyword=value arguments. This can't be a simple "(.*)=(.*)" pattern # because some positional arguments, like circuit paths, can have an equal @@ -28,7 +30,7 @@ class Event(stem.response.ControlMessage): fields = str(self).split() if not fields: - raise stem.socket.ProtocolError("Received a blank tor event. Events must at the very least have a type.") + raise stem.ProtocolError("Received a blank tor event. Events must at the very least have a type.") self.type = fields.pop(0) self.arrived_at = arrived_at @@ -75,6 +77,85 @@ class Event(stem.response.ControlMessage): def _parse(self): pass +class CircuitEvent(Event): + """ + Event that indicates that a circuit has changed. + + The fingerprint or nickname values in our path may be **None** if the + VERBOSE_NAMES feature is unavailable. The option was first introduced in tor + version 0.1.2.2. + + :var str id: circuit identifier + :var stem.control.CircStatus status: reported status for the circuit + :var tuple path: relays involved in the circuit, these are + **(fingerprint, nickname)** tuples + :var tuple build_flags: :data:`~stem.control.CircBuildFlag` attributes + governing how the circuit is built + :var stem.control.CircPurpose purpose: purpose that the circuit is intended for + :var stem.control.HiddenServiceState hs_state: status if this is a hidden service circuit + :var str rend_query: circuit's rendezvous-point if this is hidden service related + :var datetime created: time when the circuit was created or cannibalized + :var stem.control.CircClosureReason reason: reason for the circuit to be closed + :var stem.control.CircClosureReason remote_reason: remote side's reason for the circuit to be closed + """ + + _POSITIONAL_ARGS = ("id", "status", "path") + _KEYWORD_ARGS = { + "BUILD_FLAGS": "build_flags", + "PURPOSE": "purpose", + "HS_STATE": "hs_state", + "REND_QUERY": "rend_query", + "TIME_CREATED": "created", + "REASON": "reason", + "REMOTE_REASON": "remote_reason", + } + + def _parse(self): + self.path = tuple(stem.control._parse_circ_path(self.path)) + + if self.build_flags != None: + self.build_flags = tuple(self.build_flags.split(',')) + + if self.created != None: + try: + self.created = str_tools.parse_iso_timestamp(self.created) + except ValueError, exc: + raise stem.ProtocolError("Unable to parse create date (%s): %s" % (exc, self)) + + if self.id != None and not tor_tools.is_valid_circuit_id(self.id): + raise stem.ProtocolError("Circuit IDs must be one to sixteen alphanumeric characters, got '%s': %s" % (self.id, self)) + + # log if we have an unrecognized status, build flag, purpose, hidden + # service state, or closure reason + + unrecognized_msg = "CIRC event had an unrecognised %%s (%%s). Maybe a new addition to the control protocol? Full Event: '%s'" % self + + if self.status and (not self.status in stem.control.CircStatus): + log_id = "event.circ.unknown_status.%s" % self.status + log.log_once(log_id, log.INFO, unrecognized_msg % ('status', self.status)) + + if self.build_flags: + for flag in self.build_flags: + if not flag in stem.control.CircBuildFlag: + log_id = "event.circ.unknown_build_flag.%s" % flag + log.log_once(log_id, log.INFO, unrecognized_msg % ('build flag', flag)) + + if self.purpose and (not self.purpose in stem.control.CircPurpose): + log_id = "event.circ.unknown_purpose.%s" % self.purpose + log.log_once(log_id, log.INFO, unrecognized_msg % ('purpose', self.purpose)) + + if self.hs_state and (not self.hs_state in stem.control.HiddenServiceState): + log_id = "event.circ.unknown_hs_state.%s" % self.hs_state + log.log_once(log_id, log.INFO, unrecognized_msg % ('hidden service state', self.hs_state)) + + if self.reason and (not self.reason in stem.control.CircClosureReason): + log_id = "event.circ.unknown_reason.%s" % self.reason + log.log_once(log_id, log.INFO, unrecognized_msg % ('reason', self.reason)) + + if self.remote_reason and (not self.remote_reason in stem.control.CircClosureReason): + log_id = "event.circ.unknown_remote_reason.%s" % self.remote_reason + log.log_once(log_id, log.INFO, unrecognized_msg % ('remote reason', self.remote_reason)) + class BandwidthEvent(Event): """ Event emitted every second with the bytes sent and received by tor. @@ -87,11 +168,11 @@ class BandwidthEvent(Event): def _parse(self): if not self.read: - raise stem.socket.ProtocolError("BW event is missing its read value") + raise stem.ProtocolError("BW event is missing its read value") elif not self.written: - raise stem.socket.ProtocolError("BW event is missing its written value") + raise stem.ProtocolError("BW event is missing its written value") elif not self.read.isdigit() or not self.written.isdigit(): - raise stem.socket.ProtocolError("A BW event's bytes sent and received should be a positive numeric value, received: %s" % self) + raise stem.ProtocolError("A BW event's bytes sent and received should be a positive numeric value, received: %s" % self) self.read = long(self.read) self.written = long(self.written) @@ -114,6 +195,7 @@ class LogEvent(Event): self.message = str(self)[len(self.runlevel) + 1:].rstrip("\nOK") EVENT_TYPE_TO_CLASS = { + "CIRC": CircuitEvent, "BW": BandwidthEvent, "DEBUG": LogEvent, "INFO": LogEvent, diff --git a/stem/util/str_tools.py b/stem/util/str_tools.py index f444760..6c36cd0 100644 --- a/stem/util/str_tools.py +++ b/stem/util/str_tools.py @@ -11,8 +11,12 @@ Toolkit for various string activity. get_time_labels - human readable labels for each time unit get_short_time_label - condensed time label output parse_short_time_label - seconds represented by a short time label + + parse_iso_timestamp - parses an ISO timestamp as a datetime value """ +import datetime + # label conversion tuples of the form... # (bits / bytes / seconds, short label, long label) SIZE_UNITS_BITS = ( @@ -235,6 +239,38 @@ def parse_short_time_label(label): except ValueError: raise ValueError("Non-numeric value in time entry: %s" % label) +def parse_iso_timestamp(entry): + """ + Parses the ISO 8601 standard that provides for timestamps like... + + :: + + 2012-11-08T16:48:41.420251 + + :param str entry: timestamp to be parsed + + :returns: datetime for the time represented by the timestamp + + :raises: ValueError if the timestamp is malformed + """ + + if not isinstance(entry, str): + raise ValueError("parse_iso_timestamp() input must be a str, got a %s" % type(entry)) + + # based after suggestions from... + # http://stackoverflow.com/questions/127803/how-to-parse-iso-formatted-date-i… + + if '.' in entry: + timestamp_str, microseconds = entry.split('.') + else: + timestamp_str, microseconds = entry, '000000' + + if len(microseconds) != 6 or not microseconds.isdigit(): + raise ValueError("timestamp's microseconds should be six digits") + + timestamp = datetime.datetime.strptime(timestamp_str, "%Y-%m-%dT%H:%M:%S") + return timestamp + datetime.timedelta(microseconds = int(microseconds)) + def _get_label(units, count, decimal, is_long): """ Provides label corresponding to units of the highest significance in the diff --git a/stem/util/tor_tools.py b/stem/util/tor_tools.py index c70fbce..3673be9 100644 --- a/stem/util/tor_tools.py +++ b/stem/util/tor_tools.py @@ -7,16 +7,21 @@ Miscellaneous utility functions for working with tor. is_valid_fingerprint - checks if a string is a valid tor relay fingerprint is_valid_nickname - checks if a string is a valid tor relay nickname + is_valid_circuit_id - checks if a string is a valid tor circuit id is_hex_digits - checks if a string is only made up of hex digits """ import re # The control-spec defines the following as... +# # Fingerprint = "$" 40*HEXDIG # NicknameChar = "a"-"z" / "A"-"Z" / "0" - "9" # Nickname = 1*19 NicknameChar # +# CircuitID = 1*16 IDChar +# IDChar = ALPHA / DIGIT +# # HEXDIG is defined in RFC 5234 as being uppercase and used in RFC 5987 as # case insensitive. Tor doesn't define this in the spec so flipping a coin # and going with case insensitive. @@ -24,6 +29,7 @@ import re HEX_DIGIT = "[0-9a-fA-F]" FINGERPRINT_PATTERN = re.compile("^%s{40}$" % HEX_DIGIT) NICKNAME_PATTERN = re.compile("^[a-zA-Z0-9]{1,19}$") +CIRC_ID_PATTERN = re.compile("^[a-zA-Z0-9]{1,16}$") def is_valid_fingerprint(entry, check_prefix = False): """ @@ -59,6 +65,18 @@ def is_valid_nickname(entry): return bool(NICKNAME_PATTERN.match(entry)) +def is_valid_circuit_id(entry): + """ + Checks if a string is a valid format for being a circuit identifier. + + :returns: **True** if the string could be a circuit id, **False** otherwise + """ + + if not isinstance(entry, str): + return False + + return bool(CIRC_ID_PATTERN.match(entry)) + def is_hex_digits(entry, count): """ Checks if a string is the given number of hex digits. Digits represented by diff --git a/test/unit/__init__.py b/test/unit/__init__.py index 15a6b88..a57679c 100644 --- a/test/unit/__init__.py +++ b/test/unit/__init__.py @@ -4,6 +4,7 @@ Unit tests for the stem library. __all__ = [ "connection", + "control", "descriptor", "exit_policy", "socket", 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/controller.py b/test/unit/control/controller.py new file mode 100644 index 0000000..e25fbe0 --- /dev/null +++ b/test/unit/control/controller.py @@ -0,0 +1,50 @@ +""" +Unit tests for the stem.control module. The module's primarily exercised via +integ tests, but a few bits lend themselves to unit testing. +""" + +import unittest + +from stem import ProtocolError +from stem.control import _parse_circ_path + +class TestControl(unittest.TestCase): + def test_parse_circ_path(self): + """ + Exercises the _parse_circ_path() helper function. + """ + + # empty input + + self.assertEqual([], _parse_circ_path(None)) + self.assertEqual([], _parse_circ_path('')) + + # check the pydoc examples + + pydoc_examples = { + '$999A226EBED397F331B612FE1E4CFAE5C1F201BA=piyaz': + [('999A226EBED397F331B612FE1E4CFAE5C1F201BA', 'piyaz')], + '$E57A476CD4DFBD99B4EE52A100A58610AD6E80B9,hamburgerphone,PrivacyRepublic14': + [('E57A476CD4DFBD99B4EE52A100A58610AD6E80B9', None), + (None, 'hamburgerphone'), + (None, 'PrivacyRepublic14'), + ], + } + + for test_input, expected in pydoc_examples.items(): + self.assertEqual(expected, _parse_circ_path(test_input)) + + # exercise with some invalid inputs + + malformed_inputs = [ + '=piyaz', # no fingerprint + '999A226EBED397F331B612FE1E4CFAE5C1F201BA=piyaz', # fingerprint missing prefix + '$999A226EBED397F331B612FE1E4CFAE5C1F201BAA=piyaz', # fingerprint too long + '$999A226EBED397F331B612FE1E4CFAE5C1F201B=piyaz', # fingerprint too short + '$999A226EBED397F331B612FE1E4CFAE5C1F201Bz=piyaz', # invalid character in fingerprint + '$999A226EBED397F331B612FE1E4CFAE5C1F201BA=', # no nickname + ] + + for test_input in malformed_inputs: + self.assertRaises(ProtocolError, _parse_circ_path, test_input) + diff --git a/test/unit/response/events.py b/test/unit/response/events.py index 1942b69..d0c0b4e 100644 --- a/test/unit/response/events.py +++ b/test/unit/response/events.py @@ -2,6 +2,7 @@ Unit tests for the stem.response.events classes. """ +import datetime import threading import unittest @@ -9,7 +10,37 @@ import stem.response import stem.response.events import test.mocking as mocking -from stem.socket import ProtocolError +from stem import ProtocolError +from stem.control import CircStatus, CircBuildFlag, CircPurpose, CircClosureReason + +# CIRC events from tor v0.2.3.16 + +CIRC_LAUNCHED = "650 CIRC 7 LAUNCHED \ +BUILD_FLAGS=NEED_CAPACITY \ +PURPOSE=GENERAL \ +TIME_CREATED=2012-11-08T16:48:38.417238" + +CIRC_EXTENDED = "650 CIRC 7 EXTENDED \ +$999A226EBED397F331B612FE1E4CFAE5C1F201BA=piyaz \ +BUILD_FLAGS=NEED_CAPACITY \ +PURPOSE=GENERAL \ +TIME_CREATED=2012-11-08T16:48:38.417238" + +CIRC_FAILED = "650 CIRC 5 FAILED \ +$E57A476CD4DFBD99B4EE52A100A58610AD6E80B9=ergebnisoffen \ +BUILD_FLAGS=NEED_CAPACITY \ +PURPOSE=GENERAL \ +TIME_CREATED=2012-11-08T16:48:36.400959 \ +REASON=DESTROYED \ +REMOTE_REASON=OR_CONN_CLOSED" + +# CIRC events from tor v0.2.1.30 without the VERBOSE_NAMES feature + +CIRC_LAUNCHED_OLD = "650 CIRC 4 LAUNCHED" +CIRC_EXTENDED_OLD = "650 CIRC 1 EXTENDED \ +$E57A476CD4DFBD99B4EE52A100A58610AD6E80B9,hamburgerphone" +CIRC_BUILT_OLD = "650 CIRC 1 BUILT \ +$E57A476CD4DFBD99B4EE52A100A58610AD6E80B9,hamburgerphone,PrivacyRepublic14" def _get_event(content): controller_event = mocking.get_message(content) @@ -47,6 +78,97 @@ class TestEvents(unittest.TestCase): time.sleep(0.2) events_thread.join() + def test_circ_event(self): + event = _get_event(CIRC_LAUNCHED) + + self.assertTrue(isinstance(event, stem.response.events.CircuitEvent)) + self.assertEqual(CIRC_LAUNCHED.lstrip("650 "), str(event)) + self.assertEqual("7", event.id) + self.assertEqual(CircStatus.LAUNCHED, event.status) + self.assertEqual((), event.path) + self.assertEqual((CircBuildFlag.NEED_CAPACITY,), event.build_flags) + self.assertEqual(CircPurpose.GENERAL, event.purpose) + self.assertEqual(None, event.hs_state) + self.assertEqual(None, event.rend_query) + self.assertEqual(datetime.datetime(2012, 11, 8, 16, 48, 38, 417238), event.created) + self.assertEqual(None, event.reason) + self.assertEqual(None, event.remote_reason) + + event = _get_event(CIRC_EXTENDED) + + self.assertTrue(isinstance(event, stem.response.events.CircuitEvent)) + self.assertEqual(CIRC_EXTENDED.lstrip("650 "), str(event)) + self.assertEqual("7", event.id) + self.assertEqual(CircStatus.EXTENDED, event.status) + self.assertEqual((("999A226EBED397F331B612FE1E4CFAE5C1F201BA", "piyaz"),), event.path) + self.assertEqual((CircBuildFlag.NEED_CAPACITY,), event.build_flags) + self.assertEqual(CircPurpose.GENERAL, event.purpose) + self.assertEqual(None, event.hs_state) + self.assertEqual(None, event.rend_query) + self.assertEqual(datetime.datetime(2012, 11, 8, 16, 48, 38, 417238), event.created) + self.assertEqual(None, event.reason) + self.assertEqual(None, event.remote_reason) + + event = _get_event(CIRC_FAILED) + + self.assertTrue(isinstance(event, stem.response.events.CircuitEvent)) + self.assertEqual(CIRC_FAILED.lstrip("650 "), str(event)) + self.assertEqual("5", event.id) + self.assertEqual(CircStatus.FAILED, event.status) + self.assertEqual((("E57A476CD4DFBD99B4EE52A100A58610AD6E80B9", "ergebnisoffen"),), event.path) + self.assertEqual((CircBuildFlag.NEED_CAPACITY,), event.build_flags) + self.assertEqual(CircPurpose.GENERAL, event.purpose) + self.assertEqual(None, event.hs_state) + self.assertEqual(None, event.rend_query) + self.assertEqual(datetime.datetime(2012, 11, 8, 16, 48, 36, 400959), event.created) + self.assertEqual(CircClosureReason.DESTROYED, event.reason) + self.assertEqual(CircClosureReason.OR_CONN_CLOSED, event.remote_reason) + + event = _get_event(CIRC_LAUNCHED_OLD) + + self.assertTrue(isinstance(event, stem.response.events.CircuitEvent)) + self.assertEqual(CIRC_LAUNCHED_OLD.lstrip("650 "), str(event)) + self.assertEqual("4", event.id) + self.assertEqual(CircStatus.LAUNCHED, event.status) + self.assertEqual((), event.path) + self.assertEqual(None, event.build_flags) + self.assertEqual(None, event.purpose) + self.assertEqual(None, event.hs_state) + self.assertEqual(None, event.rend_query) + self.assertEqual(None, event.created) + self.assertEqual(None, event.reason) + self.assertEqual(None, event.remote_reason) + + event = _get_event(CIRC_EXTENDED_OLD) + + self.assertTrue(isinstance(event, stem.response.events.CircuitEvent)) + self.assertEqual(CIRC_EXTENDED_OLD.lstrip("650 "), str(event)) + self.assertEqual("1", event.id) + self.assertEqual(CircStatus.EXTENDED, event.status) + self.assertEqual((("E57A476CD4DFBD99B4EE52A100A58610AD6E80B9", None), (None,"hamburgerphone")), event.path) + self.assertEqual(None, event.build_flags) + self.assertEqual(None, event.purpose) + self.assertEqual(None, event.hs_state) + self.assertEqual(None, event.rend_query) + self.assertEqual(None, event.created) + self.assertEqual(None, event.reason) + self.assertEqual(None, event.remote_reason) + + event = _get_event(CIRC_BUILT_OLD) + + self.assertTrue(isinstance(event, stem.response.events.CircuitEvent)) + self.assertEqual(CIRC_BUILT_OLD.lstrip("650 "), str(event)) + self.assertEqual("1", event.id) + self.assertEqual(CircStatus.BUILT, event.status) + self.assertEqual((("E57A476CD4DFBD99B4EE52A100A58610AD6E80B9", None), (None,"hamburgerphone"), (None, "PrivacyRepublic14")), event.path) + self.assertEqual(None, event.build_flags) + self.assertEqual(None, event.purpose) + self.assertEqual(None, event.hs_state) + self.assertEqual(None, event.rend_query) + self.assertEqual(None, event.created) + self.assertEqual(None, event.reason) + self.assertEqual(None, event.remote_reason) + def test_bw_event(self): event = _get_event("650 BW 15 25") diff --git a/test/unit/util/str_tools.py b/test/unit/util/str_tools.py index 3d42154..e91e324 100644 --- a/test/unit/util/str_tools.py +++ b/test/unit/util/str_tools.py @@ -2,7 +2,9 @@ Unit tests for the stem.util.str_tools functions. """ +import datetime import unittest + from stem.util import str_tools class TestStrTools(unittest.TestCase): @@ -118,4 +120,33 @@ class TestStrTools(unittest.TestCase): self.assertRaises(ValueError, str_tools.parse_short_time_label, '05:') self.assertRaises(ValueError, str_tools.parse_short_time_label, '05a:00') self.assertRaises(ValueError, str_tools.parse_short_time_label, '-05:00') + + def test_parse_iso_timestamp(self): + """ + Checks the parse_iso_timestamp() function. + """ + + test_inputs = { + '2012-11-08T16:48:41.420251': + datetime.datetime(2012, 11, 8, 16, 48, 41, 420251), + '2012-11-08T16:48:41.000000': + datetime.datetime(2012, 11, 8, 16, 48, 41, 0), + '2012-11-08T16:48:41': + datetime.datetime(2012, 11, 8, 16, 48, 41, 0), + } + + for arg, expected in test_inputs.items(): + self.assertEqual(expected, str_tools.parse_iso_timestamp(arg)) + + invalid_input = [ + None, + 32, + 'hello world', + '2012-11-08T16:48:41.42025', # too few microsecond digits + '2012-11-08T16:48:41.4202511', # too many microsecond digits + '2012-11-08T16:48', + ] + + for arg in invalid_input: + self.assertRaises(ValueError, str_tools.parse_iso_timestamp, arg)

1 0