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_ ]*$')
[docs]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
[docs] 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])
[docs] 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)
[docs] 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
[docs] 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
[docs] 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()
[docs] 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
[docs] 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)
[docs] 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)
[docs] 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)
[docs] 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
[docs] 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
[docs] 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
[docs] 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)
[docs] 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
[docs] def recv_error(self, packet):
"""Override this function to handle the errors we get from the client.
:param packet: the full packet.
"""
pass
[docs] 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)
[docs] 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)
[docs] 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)
[docs] 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
[docs] 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()
[docs] 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 = []