python-socketio 0.3.6-2 / usr / share / pyshared / socketio / namespace.py

import gevent
import re
import logging
import inspect

log = logging.getLogger(__name__)

# regex to check the event name contains only alpha numerical characters
allowed_event_name_regex = re.compile(r'^[A-Za-z][A-Za-z0-9_ ]*$')


class BaseNamespace(object):
    """The **Namespace** is the primary interface a developer will use
    to create a gevent-socketio-based application.

    You should create your own subclass of this class, optionally using one
    of the :mod:`socketio.mixins` provided (or your own), and define methods
    such as:

    .. code-block:: python
      :linenos:

      def on_my_event(self, my_first_arg, my_second_arg):
          print "This is the my_first_arg object", my_first_arg
          print "This is the my_second_arg object", my_second_arg

      def on_my_second_event(self, whatever):
          print "This holds the first arg that was passed", whatever

    Handlers are automatically dispatched based on the name of the incoming
    event. For example, a 'user message' event will be handled by
    ``on_user_message()``. To change this, override :meth:`process_event`.
    
    We can also access the full packet directly by making an event handler
    that accepts a single argument named 'packet':

    .. code-block:: python
      :linenos:

      def on_third_event(self, packet):
          print "The full packet", packet
          print "See the BaseNamespace::call_method() method for details"
    """
    def __init__(self, environ, ns_name, request=None):
        self.environ = environ
        self.socket = environ['socketio']
        self.session = self.socket.session  # easily accessible session
        self.request = request
        self.ns_name = ns_name
        #: Store for ACL allowed methods.  Be careful as ``None`` means
        #: that all methods are allowed, while an empty list means every
        #: method is denied.  Value: list of strings or ``None``.  You
        #: can and should use the various ``acl`` methods to tweak this.
        self.allowed_methods = None
        self.jobs = []

        self.reset_acl()

        # Init the mixins if specified after.
        super(BaseNamespace, self).__init__()

    def is_method_allowed(self, method_name):
        """ACL system: this checks if you have access to that method_name,
        according to the set ACLs"""
        if self.allowed_methods is None:
            return True
        else:
            return method_name in self.allowed_methods

    def add_acl_method(self, method_name):
        """ACL system: make the method_name accessible to the current socket"""

        if isinstance(self.allowed_methods, set):
            self.allowed_methods.add(method_name)
        else:
            self.allowed_methods = set([method_name])

    def del_acl_method(self, method_name):
        """ACL system: ensure the user will not have access to that method."""
        if self.allowed_methods is None:
            raise ValueError(
                "Trying to delete an ACL method, but none were"
                + " defined yet! Or: No ACL restrictions yet, why would you"
                + " delete one?"
            )

        self.allowed_methods.remove(method_name)

    def lift_acl_restrictions(self):
        """ACL system: This removes restrictions on the Namespace's methods, so
        that all the ``on_*()`` and ``recv_*()`` can be accessed.
        """
        self.allowed_methods = None

    def get_initial_acl(self):
        """ACL system: If you define this function, you must return
        all the 'event' names that you want your User (the established
        virtual Socket) to have access to.

        If you do not define this function, the user will have free
        access to all of the ``on_*()`` and ``recv_*()`` functions,
        etc.. methods.

        Return something like: ``set(['recv_connect', 'on_public_method'])``

        You can later modify this list dynamically (inside
        ``on_connect()`` for example) using:

        .. code-block:: python

           self.add_acl_method('on_secure_method')

        ``self.request`` is available in here, if you're already ready to
        do some auth. check.

        The ACLs are checked by the :meth:`process_packet` and/or
        :meth:`process_event` default implementations, before calling
        the class's methods.

        **Beware**, returning ``None`` leaves the namespace completely
        accessible.

        The methods that are open are stored in the ``allowed_methods``
        attribute of the ``Namespace`` instance.
        """
        return None

    def reset_acl(self):
        """Resets ACL to its initial value (calling
        :meth:`get_initial_acl`` and applying that again).
        """
        self.allowed_methods = self.get_initial_acl()

    def process_packet(self, packet):
        """If you override this, NONE of the functions in this class
        will be called.  It is responsible for dispatching to
        :meth:`process_event` (which in turn calls ``on_*()`` and
        ``recv_*()`` methods).

        If the packet arrived here, it is because it belongs to this endpoint.

        For each packet arriving, the only possible path of execution, that is,
        the only methods that *can* be called are the following:

        * recv_connect()
        * recv_message()
        * recv_json()
        * recv_error()
        * recv_disconnect()
        * on_*()
        """
        packet_type = packet['type']

        if packet_type == 'event':
            return self.process_event(packet)
        elif packet_type == 'message':
            return self.call_method_with_acl('recv_message', packet,
                                             packet['data'])
        elif packet_type == 'json':
            return self.call_method_with_acl('recv_json', packet,
                                             packet['data'])
        elif packet_type == 'connect':
            self.socket.send_packet(packet)
            return self.call_method_with_acl('recv_connect', packet)
        elif packet_type == 'error':
            return self.call_method_with_acl('recv_error', packet)
        elif packet_type == 'ack':
            callback = self.socket._pop_ack_callback(packet['ackId'])
            if not callback:
                print "ERROR: No such callback for ackId %s" % packet['ackId']
                return
            return callback(*(packet['args']))
        elif packet_type == 'disconnect':
            # Force a disconnect on the namespace.
            return self.call_method_with_acl('recv_disconnect', packet)
        else:
            print "Unprocessed packet", packet
        # TODO: manage the other packet types: disconnect

    def process_event(self, packet):
        """This function dispatches ``event`` messages to the correct
        functions. You should override this method only if you are not
        satisfied with the automatic dispatching to
        ``on_``-prefixed methods.  You could then implement your own dispatch.
        See the source code for inspiration.

        There are two ways to deal with callbacks from the client side
        (meaning, the browser has a callback waiting for data that this
        server will be sending back):

        The first one is simply to return an object.  If the incoming
        packet requested has an 'ack' field set, meaning the browser is
        waiting for callback data, it will automatically be packaged
        and sent, associated with the 'ackId' from the browser. The
        return value must be a *sequence* of elements, that will be
        mapped to the positional parameters of the callback function
        on the browser side.

        If you want to *know* that you're dealing with a packet
        that requires a return value, you can do those things manually
        by inspecting the ``ack`` and ``id`` keys from the ``packet``
        object.  Your callback will behave specially if the name of
        the argument to your method is ``packet``.  It will fill it
        with the unprocessed ``packet`` object for your inspection,
        like this:

        .. code-block:: python

          def on_my_callback(self, packet):
              if 'ack' in packet:
                  self.emit('go_back', 'param1', id=packet['id'])
        """
        args = packet['args']
        name = packet['name']
        if not allowed_event_name_regex.match(name):
            self.error("unallowed_event_name",
                       "name must only contains alpha numerical characters")
            return

        method_name = 'on_' + name.replace(' ', '_')
        # This means the args, passed as a list, will be expanded to
        # the method arg and if you passed a dict, it will be a dict
        # as the first parameter.

        return self.call_method_with_acl(method_name, packet, *args)

    def call_method_with_acl(self, method_name, packet, *args):
        """You should always use this function to call the methods,
        as it checks if the user is allowed according to the ACLs.

        If you override :meth:`process_packet` or
        :meth:`process_event`, you should definitely want to use this
        instead of ``getattr(self, 'my_method')()``
        """
        if not self.is_method_allowed(method_name):
            self.error('method_access_denied',
                       'You do not have access to method "%s"' % method_name)
            return

        return self.call_method(method_name, packet, *args)

    def call_method(self, method_name, packet, *args):
        """This function is used to implement the two behaviors on dispatched
        ``on_*()`` and ``recv_*()`` method calls.

        Those are the two behaviors:

        * If there is only one parameter on the dispatched method and
          it is named ``packet``, then pass in the packet dict as the
          sole parameter.

        * Otherwise, pass in the arguments as specified by the
          different ``recv_*()`` methods args specs, or the
          :meth:`process_event` documentation.

        This method will also consider the
        ``exception_handler_decorator``.  See Namespace documentation
        for details and examples.

        """
        method = getattr(self, method_name, None)
        if method is None:
            self.error('no_such_method',
                       'The method "%s" was not found' % method_name)
            return

        specs = inspect.getargspec(method)
        func_args = specs.args
        if not len(func_args) or func_args[0] != 'self':
            self.error("invalid_method_args",
                "The server-side method is invalid, as it doesn't "
                "have 'self' as its first argument")
            return

        # Check if we need to decorate to handle exceptions
        if hasattr(self, 'exception_handler_decorator'):
            method = self.exception_handler_decorator(method)

        if len(func_args) == 2 and func_args[1] == 'packet':
            return method(packet)
        else:
            return method(*args)

    def initialize(self):
        """This is called right after ``__init__``, on the initial
        creation of a namespace so you may handle any setup job you
        need.

        Namespaces are created only when some packets arrive that ask
        for the namespace.  They are not created altogether when a new
        :class:`~socketio.virtsocket.Socket` connection is established,
        so you can have many many namespaces assigned (when calling
        :func:`~socketio.socketio_manage`) without clogging the
        memory.

        If you override this method, you probably want to initialize
        the variables you're going to use in the events handled by this
        namespace, setup ACLs, etc..

        This method is called on all base classes following the _`method resolution order <http://docs.python.org/library/stdtypes.html?highlight=mro#class.__mro__>`
        so you don't need to call super() to initialize the mixins or
        other derived classes.

        """
        pass

    def recv_message(self, data):
        """This is more of a backwards compatibility hack. This will be
        called for messages sent with the original send() call on the client
        side. This is NOT the 'message' event, which you will catch with
        'on_message()'. The data arriving here is a simple string, with no
        other info.

        If you want to handle those messages, you should override this method.
        """
        return data

    def recv_json(self, data):
        """This is more of a backwards compatibility hack. This will be
        called for JSON packets sent with the original json() call on the
        JavaScript side. This is NOT the 'json' event, which you will catch
        with 'on_json()'. The data arriving here is a python dict, with no
        event name.

        If you want to handle those messages, you should override this method.
        """
        return data

    def recv_disconnect(self):
        """Override this function if you want to do something when you get a
        *force disconnect* packet.

        By default, this function calls the :meth:`disconnect` clean-up
        function.  You probably want to call it yourself also, and put
        your clean-up routines in :meth:`disconnect` rather than here,
        because that :meth:`disconnect` function gets called
        automatically upon disconnection.  This function is a
        pre-handle for when you get the `disconnect packet`.
        """
        self.disconnect(silent=True)

    def recv_connect(self):
        """Called the first time a client connection is open on a
        Namespace. This *does not* fire on the global namespace.

        This allows you to do boilerplate stuff for
        the namespace like connecting to rooms, broadcasting events
        to others, doing authorization work, and tweaking the ACLs to open
        up the rest of the namespace (if it was closed at the
        beginning by having :meth:`get_initial_acl` return only
        ['recv_connect'])

        Also see the different :ref:`mixins <mixins_module>` (like
        `RoomsMixin`, `BroadcastMixin`).
        """
        pass

    def recv_error(self, packet):
        """Override this function to handle the errors we get from the client.

        :param packet: the full packet.
        """
        pass

    def error(self, error_name, error_message, msg_id=None, quiet=False):
        """Use this to use the configured ``error_handler`` yield an
        error message to your application.

        :param error_name: is a short string, to associate messages to recovery
                           methods
        :param error_message: is some human-readable text, describing the error
        :param msg_id: is used to associate with a request
        :param quiet: specific to error_handlers. The default doesn't send a
                      message to the user, but shows a debug message on the
                      developer console.
        """
        self.socket.error(error_name, error_message, endpoint=self.ns_name,
                          msg_id=msg_id, quiet=quiet)

    def send(self, message, json=False, callback=None):
        """Use send to send a simple string message.

        If ``json`` is True, the message will be encoded as a JSON object
        on the wire, and decoded on the other side.

        This is mostly for backwards compatibility.  ``emit()`` is more fun.

        :param callback: This is a callback function that will be
                         called automatically by the client upon
                         reception.  It does not verify that the
                         listener over there was completed with
                         success.  It just tells you that the browser
                         got a hold of the packet.
        :type callback: callable
        """
        pkt = dict(type="message", data=message, endpoint=self.ns_name)
        if json:
            pkt['type'] = "json"

        if callback:
            # By passing ack=True, we use the old behavior of being returned
            # an 'ack' packet, automatically triggered by the client-side
            # with no user-code being run.  The emit() version of the
            # callback is more useful I think :)  So migrate your code.
            pkt['ack'] = True
            pkt['id'] = msgid = self.socket._get_next_msgid()
            self.socket._save_ack_callback(msgid, callback)

        self.socket.send_packet(pkt)

    def emit(self, event, *args, **kwargs):
        """Use this to send a structured event, with a name and arguments, to
        the client.

        By default, it uses this namespace's endpoint. You can send messages on
        other endpoints with something like:

            ``self.socket['/other_endpoint'].emit()``.

        However, it is possible that the ``'/other_endpoint'`` was not
        initialized yet, and that would yield a ``KeyError``.

        The only supported ``kwargs`` is ``callback``.  All other parameters
        must be passed positionally.

        :param event: The name of the event to trigger on the other end.
        :param callback: Pass in the callback keyword argument to define a
                         call-back that will be called when the client acks.

                         This callback is slightly different from the one from
                         ``send()``, as this callback will receive parameters
                         from the explicit call of the ``ack()`` function
                         passed to the listener on the client side.

                         The remote listener will need to explicitly ack (by
                         calling its last argument, a function which is
                         usually called 'ack') with some parameters indicating
                         success or error.  The 'ack' packet coming back here
                         will then trigger the callback function with the
                         returned values.
        :type callback: callable
        """
        callback = kwargs.pop('callback', None)

        if kwargs:
            raise ValueError(
                "emit() only supports positional argument, to stay "
                "compatible with the Socket.IO protocol. You can "
                "however pass in a dictionary as the first argument")
        pkt = dict(type="event", name=event, args=args,
                   endpoint=self.ns_name)

        if callback:
            # By passing 'data', we indicate that we *want* an explicit ack
            # by the client code, not an automatic as with send().
            pkt['ack'] = 'data'
            pkt['id'] = msgid = self.socket._get_next_msgid()
            self.socket._save_ack_callback(msgid, callback)

        self.socket.send_packet(pkt)

    def spawn(self, fn, *args, **kwargs):
        """Spawn a new process, attached to this Namespace.

        It will be monitored by the "watcher" process in the Socket. If the
        socket disconnects, all these greenlets are going to be killed, after
        calling BaseNamespace.disconnect()

        This method uses the ``exception_handler_decorator``.  See
        Namespace documentation for more information.

        """
        # self.log.debug("Spawning sub-Namespace Greenlet: %s" % fn.__name__)
        if hasattr(self, 'exception_handler_decorator'):
            fn = self.exception_handler_decorator(fn)
        new = gevent.spawn(fn, *args, **kwargs)
        self.jobs.append(new)
        return new

    def disconnect(self, silent=False):
        """Send a 'disconnect' packet, so that the user knows it has been
        disconnected (booted actually).  This will trigger an onDisconnect()
        call on the client side.

        Over here, we will kill all ``spawn``ed processes and remove the
        namespace from the Socket object.

        :param silent: do not actually send the packet (if they asked for a
                       disconnect for example), but just kill all jobs spawned
                       by this Namespace, and remove it from the Socket.
        """
        if not silent:
            packet = {"type": "disconnect",
                      "endpoint": self.ns_name}
            self.socket.send_packet(packet)
        # remove_namespace might throw GreenletExit so
        # kill_local_jobs must be in finally
        try:
            self.socket.remove_namespace(self.ns_name)
        finally:
            self.kill_local_jobs()

    def kill_local_jobs(self):
        """Kills all the jobs spawned with BaseNamespace.spawn() on a namespace
        object.

        This will be called automatically if the ``watcher`` process detects
        that the Socket was closed.
        """
        gevent.killall(self.jobs)
        self.jobs = []