Merge edf49db6e9 into 6abd86fd86

docs/index.rst

@@ -213,6 +213,138 @@ methods in the :class:`socketio.Server` class.
 When the ``namespace`` argument is omitted, set to ``None`` or to ``'/'``, the
 default namespace, representing the physical connection, is used.
 
+Event handler middlewares
+-------------------------
+
+Event handler middlewares are objects with the following methods or a
+subset of them:
+
+* ``before_event(*args)`` is called before the event handler is executed
+  with the event name, the namespace and the list of arguments the event
+  handler will be called with. It may alter the arguments in that list
+  eventually.
+* ``after_event(*args)`` is called after the event handler with the
+  event name, the namespace and the list of values the event handler
+  returned. It may alter that values eventually.
+* ``ignore_event`` is called before the middleware is applied to an
+  event handler with the event name and namespace as arguments. If its
+  return value resolves to ``True`` the middleware is not applied to that
+  particular event handler.
+
+If one of these methods returns something else than ``None``, execution
+is stopped at that point and the returned value is treated as if it was
+returned by the event handler.
+
+Event handler middlewares can be chained. The ``before_event`` methods
+will be executed in the same order the middlewares were added, the
+``after_event`` methods are called in reversed order.
+
+Note that you can also use classes (objects of type ``type``) instead
+of instances as event handler middlewares. If you do so, they are
+instantiated with no arguments every time they are used to process
+an event.
+
+Example:
+
+::
+
+    from socketio import server
+
+    class MyMiddleware(object):
+        def before_event(self, event, namespace, args):
+            print("before_event called with:", args)
+            if len(args) >= 2 or args[1] != "secret":
+                return "Ha, you don't know the password!"
+
+        def after_event(self, event, namespace, args):
+            args[0] = "I faked the response!"
+
+    sio = socketio.server.Server()
+
+    @sio.on("/foo")
+    def foo(sid, data):
+        print("foo executed")
+        return "foo executed"
+
+    sio.middlewares.append(MyMiddleware())
+
+In this example, the middleware would be applied to every event
+handler. There is also a decorator available to add it to specific
+handlers only. Given the middleware class from above, it would be used
+as follows:
+
+::
+
+    from socketio import util
+
+    sio = socketio.server.Server()
+
+    @sio.on("/foo")
+    @util.apply_middleware(MyMiddleware)
+    def foo(sid, data):
+        print("foo executed")
+        return "foo executed"
+
+Middlewares added by the decorator are treated as if they were added
+*after* the server-wide or namespace-wide middlewares. Naturally,
+decorators are applied from bottom to top. Hence the following will
+first add ``MW1`` and then ``MW2``.
+
+::
+
+    @util.apply_middleware(MW2)
+    @util.apply_middleware(MW1)
+    def foo(sid):
+        # ...
+
+Class-based namespaces
+----------------------
+
+Event handlers for a specific namespace can be grouped together in a
+sub class of the ``Namespace`` class.
+
+A method of this class named ``on_xxx`` is considered as the event handler
+for the event ``'xxx'`` in the namespace this class is registered to.
+
+There are also the following methods available that insert the current
+namespace automatically when none is given before they call their matching
+method of the ``Server`` instance:
+
+    ``emit``, ``send``, ``enter_room``, ``leave_room``, ``close_room``,
+    ``rooms``, ``disconnect``
+
+Example:
+
+::
+
+    from socketio import Namespace, Server
+
+    class ChatNamespace(Namespace):
+        def on_msg(self, sid, msg):
+            # self.server references to the socketio.Server object
+            data = "[%s]: %s" \
+                   % (self.server.environ[sid].get("REMOTE_ADDR"), msg)
+            # Note that we don't pass namespace="/chat" to the emit method.
+            # It is done automatically for us.
+            self.emit("msg", data, skip_sid=sid)
+            return "received your message: %s" % msg
+
+            # Here we set the event name explicitly by decorator.
+            @Namespace.event_name("event name with spaces")
+            def foo(self, sid):
+                # ...
+
+    sio = socketio.Server()
+    ns = sio.register_namespace("/chat", ChatNamespace)
+    # ns now holds the instantiated ChatNamespace object
+
+``Namespace`` objects do also support middlewares that are applied on
+all event handlers in that namespace:
+
+::
+
+    ns.middlewares.append(MyMiddleware())
+
 Using a Message Queue
 ---------------------
 

socketio/__init__.py

@@ -1,9 +1,11 @@
 from .middleware import Middleware
+from .namespace import Namespace
 from .base_manager import BaseManager
 from .pubsub_manager import PubSubManager
 from .kombu_manager import KombuManager
 from .redis_manager import RedisManager
 from .server import Server
+from .util import apply_middleware
 
-__all__ = [Middleware, Server, BaseManager, PubSubManager, KombuManager,
-           RedisManager]
+__all__ = [Middleware, Namespace, Server, BaseManager, PubSubManager,
+           KombuManager, RedisManager, apply_middleware]

socketio/namespace.py

@@ -0,0 +1,95 @@
+import types
+
+from . import util
+
+
+class Namespace(object):
+    """A container for a set of event handlers for a specific namespace.
+
+    A method of this class named ``on_xxx`` is considered as the event handler
+    for the event ``'xxx'`` in the namespace this class is registered to.
+
+    There are also the following methods available that insert the current
+    namespace automatically when none is given before they call their matching
+    method of the ``Server`` instance:
+
+    ``emit``, ``send``, ``enter_room``, ``leave_room``, ``close_room``,
+    ``rooms``, ``disconnect``
+
+    Example:
+
+        from socketio import Namespace, Server
+
+        class ChatNamespace(Namespace):
+            def on_msg(self, sid, msg):
+                # self.server references to the socketio.Server object
+                data = "[%s]: %s" \
+                       % (self.server.environ[sid].get("REMOTE_ADDR"), msg)
+                # Note that we don't pass namespace="/chat" to the emit method.
+                # It is done automatically for us.
+                self.emit("msg", data, skip_sid=sid)
+                return "received your message: %s" % msg
+
+            # Here we set the event name explicitly by decorator.
+            @Namespace.event_name("event name with spaces")
+            def foo(self, sid):
+                # ...
+
+        sio = socketio.Server()
+        ns = sio.register_namespace("/chat", ChatNamespace)
+        # ns now holds the instantiated ChatNamespace object
+    """
+
+    def __init__(self, name, server):
+        self.name = name
+        self.server = server
+        self.middlewares = []
+
+        # wrap methods of Server object
+        def get_wrapped_method(func_name):
+            def wrapped_func(self, *args, **kwargs):
+                """If namespace is None, it is automatically set to this
+                object's one before the original method is called.
+                """
+                if kwargs.get('namespace') is None:
+                    kwargs['namespace'] = self.name
+                return getattr(self.server, func_name)(*args, **kwargs)
+            return types.MethodType(wrapped_func, self)
+        for func_name in ('emit', 'send', 'enter_room', 'leave_room',
+                          'close_room', 'rooms', 'disconnect'):
+            setattr(self, func_name, get_wrapped_method(func_name))
+
+    def _get_event_handler(self, event_name):
+        """Returns the event handler for given ``event`` in this namespace or
+        ``None``, if none exists.
+
+        :param event: The event name the handler is required for.
+        """
+        for attr_name in dir(self):
+            attr = getattr(self, attr_name)
+            if hasattr(attr, '_sio_event_name'):
+                _event_name = getattr(attr, '_sio_event_name')
+            elif attr_name.startswith('on_'):
+                _event_name = attr_name[3:]
+            else:
+                continue
+            if _event_name == event_name:
+                return attr
+
+    @staticmethod
+    def event_name(name):
+        """Decorator to overwrite event names:
+
+            @Namespace.event_name("event name with spaces")
+            def foo(self, sid, data):
+                return "received: %s" % data
+
+        Ensure that you only add well-behaving decorators after this one
+        (meaning such that preserve attributes) because you'll loose them
+        otherwise.
+        """
+        @util._simple_decorator
+        def wrapper(handler):
+            handler._sio_event_name = name
+            return handler
+        return wrapper

socketio/server.py

@@ -4,6 +4,7 @@ import engineio
 import six
 
 from . import base_manager
+from . import namespace as sio_namespace
 from . import packet
 
 
@@ -77,6 +78,7 @@ class Server(object):
 
         self.environ = {}
         self.handlers = {}
+        self.middlewares = []
 
         self._binary_packet = []
 
@@ -141,6 +143,10 @@ class Server(object):
         namespace = namespace or '/'
 
         def set_handler(handler):
+            if isinstance(self.handlers.get(namespace),
+                          sio_namespace.Namespace):
+                raise ValueError('A Namespace object has been registered '
+                                 'for this namespace.')
             if namespace not in self.handlers:
                 self.handlers[namespace] = {}
             self.handlers[namespace][event] = handler
@@ -150,6 +156,22 @@ class Server(object):
             return set_handler
         set_handler(handler)
 
+    def register_namespace(self, name, namespace_class):
+        """Register the given ``namespace_class`` under the namespace named
+        by ``name``.
+
+        :param name: The namespace's name. It can be any string.
+        :param namespace_class: The sub class of ``Namespace`` to register
+                                handlers of. Don't pass an instance instead.
+
+        This function returns the instance of ``namespace_class`` created.
+
+        See documentation of ``Namespace`` class for an example.
+        """
+        namespace = namespace_class(name, self)
+        self.handlers[name] = namespace
+        return namespace
+
     def emit(self, event, data=None, room=None, skip_sid=None, namespace=None,
              callback=None):
         """Emit a custom event to one or more connected clients.
@@ -424,8 +446,61 @@ class Server(object):
 
     def _trigger_event(self, event, namespace, *args):
         """Invoke an application event handler."""
-        if namespace in self.handlers and event in self.handlers[namespace]:
-            return self.handlers[namespace][event](*args)
+        handler = None
+        middlewares = list(self.middlewares)
+        ns = self.handlers.get(namespace)
+        if isinstance(ns, sio_namespace.Namespace):
+            middlewares.extend(ns.middlewares)
+            handler = ns._get_event_handler(event)
+        elif isinstance(ns, dict):
+            handler = ns.get(event)
+        if handler is not None:
+            middlewares.extend(getattr(handler, '_sio_middlewares', []))
+            handler = self._apply_middlewares(middlewares, event, namespace,
+                                              handler)
+            return handler(*args)
+
+    @staticmethod
+    def _apply_middlewares(middlewares, event, namespace, handler):
+        """Wraps the given handler with a wrapper that executes middlewares
+        before and after the real event handler."""
+
+        _middlewares = []
+        for middleware in middlewares:
+            if isinstance(middleware, type):
+                middleware = middleware()
+            if not hasattr(middleware, 'ignore_event') or \
+               not middleware.ignore_event(event, namespace):
+                _middlewares.append(middleware)
+        if not _middlewares:
+            return handler
+
+        def wrapped(*args):
+            args = list(args)
+
+            for middleware in _middlewares:
+                if hasattr(middleware, 'before_event'):
+                    result = middleware.before_event(event, namespace, args)
+                    if result is not None:
+                        return result
+
+            result = handler(*args)
+            if result is None:
+                data = []
+            elif isinstance(result, tuple):
+                data = list(result)
+            else:
+                data = [result]
+
+            for middleware in reversed(_middlewares):
+                if hasattr(middleware, 'after_event'):
+                    result = middleware.after_event(event, namespace, data)
+                    if result is not None:
+                        return result
+
+            return tuple(data)
+
+        return wrapped
 
     def _handle_eio_connect(self, sid, environ):
         """Handle the Engine.IO connection event."""

socketio/util.py

@@ -0,0 +1,49 @@
+def _simple_decorator(decorator):
+    """This decorator can be used to turn simple functions
+    into well-behaved decorators, so long as the decorators
+    are fairly simple. If a decorator expects a function and
+    returns a function (no descriptors), and if it doesn't
+    modify function attributes or docstring, then it is
+    eligible to use this. Simply apply @_simple_decorator to
+    your decorator and it will automatically preserve the
+    docstring and function attributes of functions to which
+    it is applied.
+
+    Also preserves all properties starting with ``'_sio'``.
+    """
+    def copy_attrs(a, b):
+        """Copies attributes from a to b."""
+        for attr_name in ('__name__', '__doc__'):
+            if hasattr(a, attr_name):
+                setattr(b, attr_name, getattr(a, attr_name))
+        if hasattr(a, '__dict__') and hasattr(b, '__dict__'):
+            b.__dict__.update(a.__dict__)
+
+    def new_decorator(f):
+        g = decorator(f)
+        copy_attrs(f, g)
+        return g
+
+    # Now a few lines needed to make _simple_decorator itself
+    # be a well-behaved decorator.
+    copy_attrs(decorator, new_decorator)
+    return new_decorator
+
+
+def apply_middleware(middleware):
+    """Returns a decorator for event handlers that adds the given
+    middleware to the handler decorated with it.
+
+    :param middleware: The middleware to add
+
+    Ensure that you only add well-behaving decorators after this one
+    (meaning such that preserve attributes) because you'll loose them
+    otherwise.
+    """
+    @_simple_decorator
+    def wrapper(handler):
+        if not hasattr(handler, '_sio_middlewares'):
+            handler._sio_middlewares = []
+        handler._sio_middlewares.append(middleware)
+        return handler
+    return wrapper

tests/test_server.py

@@ -8,8 +8,10 @@ if six.PY3:
 else:
     import mock
 
+from socketio import namespace
 from socketio import packet
 from socketio import server
+from socketio import util
 
 
 @mock.patch('engineio.Server')
@@ -45,6 +47,113 @@ class TestServer(unittest.TestCase):
         self.assertEqual(s.handlers['/']['disconnect'], bar)
         self.assertEqual(s.handlers['/foo']['disconnect'], bar)
 
+    def test_register_namespace(self, eio):
+        class NS(namespace.Namespace):
+            def on_foo(self, sid):
+                self.emit("bar")
+
+            @namespace.Namespace.event_name('foo bar')
+            def abc(self, sid):
+                self.emit("foo bar")
+
+        s = server.Server()
+        s.register_namespace('/ns', NS)
+
+        self.assertIsNotNone(s.handlers['/ns']._get_event_handler('foo'))
+        self.assertIsNotNone(s.handlers['/ns']._get_event_handler('foo bar'))
+        self.assertIsNone(s.handlers['/ns']._get_event_handler('abc'))
+
+    def test_middleware(self, eio):
+        class MW:
+            def __init__(self):
+                self.ignore_event = mock.MagicMock(side_effect=100 * [False])
+                self.before_event = mock.MagicMock(side_effect=100 * [None])
+                self.after_event = mock.MagicMock(side_effect=100 * [None])
+
+        mw1 = MW()
+        mw2 = MW()
+        mw3 = MW()
+        mw4 = MW()
+        mw4.ignore_event = mock.MagicMock(side_effect=[True] + 100 * [False])
+        mw4.before_event = mock.MagicMock(side_effect=['x'] + 100 * [None])
+        mw4.after_event = mock.MagicMock(side_effect=['x'] + 100 * [None])
+
+        class NS(namespace.Namespace):
+            def on_foo(self, sid):
+                pass
+
+            @namespace.Namespace.event_name('foo bar')
+            @util.apply_middleware(mw4)
+            def some_name(self, sid):
+                pass
+
+        s = server.Server()
+        s.middlewares.append(mw1)
+
+        @s.on('abc')
+        @util.apply_middleware(mw2)
+        def abc(sid):
+            pass
+
+        ns = s.register_namespace('/ns', NS)
+        ns.middlewares.append(mw3)
+
+        # only mw1 and mw3 should run completely
+        s._trigger_event('foo', '/ns', '123')
+        self.assertEqual(mw1.before_event.call_count, 1)
+        self.assertEqual(mw1.after_event.call_count, 1)
+        self.assertEqual(mw2.before_event.call_count, 0)
+        self.assertEqual(mw2.after_event.call_count, 0)
+        self.assertEqual(mw3.before_event.call_count, 1)
+        self.assertEqual(mw3.after_event.call_count, 1)
+        self.assertEqual(mw4.before_event.call_count, 0)
+        self.assertEqual(mw4.after_event.call_count, 0)
+
+        # only mw1 and mw3 should run completely, mw4 is enabled but ignored
+        s._trigger_event('foo bar', '/ns', '123')
+        self.assertEqual(mw1.before_event.call_count, 2)
+        self.assertEqual(mw1.after_event.call_count, 2)
+        self.assertEqual(mw2.before_event.call_count, 0)
+        self.assertEqual(mw2.after_event.call_count, 0)
+        self.assertEqual(mw3.before_event.call_count, 2)
+        self.assertEqual(mw3.after_event.call_count, 2)
+        self.assertEqual(mw4.before_event.call_count, 0)
+        self.assertEqual(mw4.after_event.call_count, 0)
+
+        # again, this time mw4 before_event should be triggered
+        s._trigger_event('foo bar', '/ns', '123')
+        self.assertEqual(mw1.before_event.call_count, 3)
+        self.assertEqual(mw1.after_event.call_count, 2)
+        self.assertEqual(mw2.before_event.call_count, 0)
+        self.assertEqual(mw2.after_event.call_count, 0)
+        self.assertEqual(mw3.before_event.call_count, 3)
+        self.assertEqual(mw3.after_event.call_count, 2)
+        self.assertEqual(mw4.before_event.call_count, 1)
+        self.assertEqual(mw4.after_event.call_count, 0)
+
+        # again, this time mw4 before + after_event should be triggered
+        # but after_event should abort execution
+        s._trigger_event('foo bar', '/ns', '123')
+        self.assertEqual(mw1.before_event.call_count, 4)
+        self.assertEqual(mw1.after_event.call_count, 2)
+        self.assertEqual(mw2.before_event.call_count, 0)
+        self.assertEqual(mw2.after_event.call_count, 0)
+        self.assertEqual(mw3.before_event.call_count, 4)
+        self.assertEqual(mw3.after_event.call_count, 2)
+        self.assertEqual(mw4.before_event.call_count, 2)
+        self.assertEqual(mw4.after_event.call_count, 1)
+
+        # only mw1 and mw2 should run completely
+        s._trigger_event('abc', '/', '123')
+        self.assertEqual(mw1.before_event.call_count, 5)
+        self.assertEqual(mw1.after_event.call_count, 3)
+        self.assertEqual(mw2.before_event.call_count, 1)
+        self.assertEqual(mw2.after_event.call_count, 1)
+        self.assertEqual(mw3.before_event.call_count, 4)
+        self.assertEqual(mw3.after_event.call_count, 2)
+        self.assertEqual(mw4.before_event.call_count, 2)
+        self.assertEqual(mw4.after_event.call_count, 1)
+
     def test_on_bad_event_name(self, eio):
         s = server.Server()
         self.assertRaises(ValueError, s.on, 'two-words')
@@ -198,6 +307,7 @@ class TestServer(unittest.TestCase):
         mgr = mock.MagicMock()
         s = server.Server(client_manager=mgr)
         handler = mock.MagicMock(return_value=False)
+        del handler._sio_middlewares
         s.on('connect', handler)
         s._handle_eio_connect('123', 'environ')
         handler.assert_called_once_with('123', 'environ')
@@ -209,6 +319,7 @@ class TestServer(unittest.TestCase):
         mgr = mock.MagicMock()
         s = server.Server(client_manager=mgr)
         handler = mock.MagicMock(return_value=False)
+        del handler._sio_middlewares
         s.on('connect', handler, namespace='/foo')
         s._handle_eio_connect('123', 'environ')
         s._handle_eio_message('123', '0/foo')