diff --git a/HISTORY.rst b/HISTORY.rst index ffa8a35..8e2c226 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -1,7 +1,6 @@ Version History --------------- -0.0.0 -~~~~~ - - Nothing to see here - +Next Release +~~~~~~~~~~~~ + - Adds ``sprockets.mixins.correlation.HandlerMixin`` diff --git a/sprockets/mixins/correlation/__init__.py b/sprockets/mixins/correlation/__init__.py index 9969ce6..876a2b8 100644 --- a/sprockets/mixins/correlation/__init__.py +++ b/sprockets/mixins/correlation/__init__.py @@ -1,2 +1,5 @@ +from .mixins import HandlerMixin + + version_info = (0, 0, 0) __version__ = '.'.join(str(v) for v in version_info[:3]) diff --git a/sprockets/mixins/correlation/mixins.py b/sprockets/mixins/correlation/mixins.py new file mode 100644 index 0000000..87986ac --- /dev/null +++ b/sprockets/mixins/correlation/mixins.py @@ -0,0 +1,83 @@ +import uuid + + +class HandlerMixin(object): + """ + Mix this in over a ``RequestHandler`` for a correlating header. + + :keyword str correlation_header: the name of the header to use + for correlation. If this keyword is omitted, then the header + is named ``Correlation-ID``. + + This mix-in ensures that responses include a header that correlates + requests and responses. If there header is set on the incoming + request, then it will be copied to the outgoing response. Otherwise, + a new UUIDv4 will be generated and inserted. The value can be + examined or modified via the ``correlation_id`` property. + + The MRO needs to contain something that resembles a standard + :class:`tornado.web.RequestHandler`. Specifically, we need the + following things to be available: + + - :meth:`~tornado.web.RequestHandler.prepare` needs to be called + appropriately + - :meth:`~tornado.web.RequestHandler.set_header` needs to exist in + the MRO and it needs to overwrite the header value + - :meth:`~tornado.web.RequestHandler.set_default_headers` should be + called to establish the default header values + - ``self.request`` is a object that has a ``headers`` property that + contains the request headers as a ``dict``. + + """ + + def __init__(self, *args, **kwargs): + # correlation_id is used from within set_default_headers + # which is called from within super().__init__() so we need + # to make sure that it is set *BEFORE* we call super. + self.__header_name = kwargs.pop( + 'correlation_header', 'Correlation-ID') + self.__correlation_id = str(uuid.uuid4()) + super(HandlerMixin, self).__init__(*args, **kwargs) + + def prepare(self): + # Here we want to copy an incoming Correlation-ID header if + # one exists. We also want to set it in the outgoing response + # which the property setter does for us. + super(HandlerMixin, self).prepare() + correlation_id = self.get_request_header(self.__header_name, None) + if correlation_id is not None: + self.correlation_id = correlation_id + + def set_default_headers(self): + # This is called during initialization as well as *AFTER* + # calling clear() when an error occurs so we need to make + # sure that our header is set again... + super(HandlerMixin, self).set_default_headers() + self.set_header(self.__header_name, self.correlation_id) + + @property + def correlation_id(self): + """Correlation header value.""" + return self.__correlation_id + + @correlation_id.setter + def correlation_id(self, value): + self.__correlation_id = value + self.set_header(self.__header_name, self.__correlation_id) + + def get_request_header(self, name, default): + """ + Retrieve the value of a request header. + + :param str name: the name of the header to retrieve + :param default: the value to return if the header is not set + + This method abstracts the act of retrieving a header value out + from the implementation. This makes it possible to implement + a *RequestHandler* that is something other than a + :class:`tornado.web.RequestHandler` by simply implementing this + method and ``set_header`` over the underlying implementation, + for example, say AMQP message properties. + + """ + return self.request.headers.get(name, default) diff --git a/tests.py b/tests.py index e69de29..9abe799 100644 --- a/tests.py +++ b/tests.py @@ -0,0 +1,40 @@ +import uuid +import unittest + +from tornado import testing, web + +from sprockets.mixins import correlation + + +class CorrelatedRequestHandler(correlation.HandlerMixin, web.RequestHandler): + + def get(self, status_code): + status_code = int(status_code) + if status_code >= 300: + raise web.HTTPError(status_code) + self.write('status {0}'.format(status_code)) + + +class CorrelationMixinTests(testing.AsyncHTTPTestCase): + + def get_app(self): + return web.Application([ + (r'/status/(?P\d+)', CorrelatedRequestHandler), + ]) + + def test_that_correlation_id_is_returned_when_successful(self): + self.http_client.fetch(self.get_url('/status/200'), self.stop) + response = self.wait() + self.assertIsNotNone(response.headers.get('Correlation-ID')) + + def test_that_correlation_id_is_returned_in_error(self): + self.http_client.fetch(self.get_url('/status/500'), self.stop) + response = self.wait() + self.assertIsNotNone(response.headers.get('Correlation-ID')) + + def test_that_correlation_id_is_copied_from_request(self): + correlation_id = uuid.uuid4().hex + self.http_client.fetch(self.get_url('/status/200'), self.stop, + headers={'Correlation-Id': correlation_id}) + response = self.wait() + self.assertEqual(response.headers['correlation-id'], correlation_id)