__init__.py

""" Protocols can be binded on a specific label of a :class:`RpcConnection`
    (see `Multiplexing & protocols`_ for more informations).

Following protocols are provided with standard distribution of sjRpc, but you
can create yours if you needs:

- :class:`RpcProtocol`: the standard rpc protocol
- :class:`TunnelProtocol`: a protocol which allow to tunnel a socket traffic
  through the sjRpc connection
- :class:`VpnProtocol` (experimental): like :class:`TunnelProtocol` but work
  with a network interface instead of a socket.
"""

from __future__ import absolute_import

import logging

class Protocol(object):

    """ Base class for all protocols.
    """

    def __init__(self, connection, label, logger=None):
        self._connection = connection
        self._label = label
        if logger is None:
            logger_name = '%s.protos.%s' % (connection.logger.name, label)
            self.logger = logging.getLogger(logger_name)
        else:
            self.logger = logger

    @property
    def connection(self):
        """ The :class:`~sjrpc.core.RpcConnection` instance which handle
            this protocol.
        """
        return self._connection

    @property
    def label(self):
        """ The label binded to this protocol in
            the :class:`~sjrpc.core.RpcConnection` instance.
        """
        return self._label

    def create_watcher(self, watcher_class, **kwargs):
        """ Create a new pyev watcher for this protocol and return it.
        """
        kwargs['loop'] = self._connection.loop
        watcher = watcher_class(**kwargs)
        return watcher

    def send(self, payload):
        """ Send a message through the sjRpc connection.
        """
        self._connection.send(self._label, payload)

    def start_message(self, payload_size):
        """ Start a new incoming message receipt. By default, this method create
            a new empty buffer on self._incoming_buf variable.
        """
        self._incoming_buf = ''

    def feed(self, data):
        """ Handle a chunk of data received from the tunnel.

        By default, this method append this chunk to the end of the incoming
        buffer created by default by :meth:`start_message` method.
        """
        self._incoming_buf += data

    def end_of_message(self):
        """ Signal the end of the currently received message.

        With default :meth:`start_message` and :meth:`feed` methods, it's a
        good place to implements the processing of the incoming message.
        """
        pass

    def handle_control(self, payload):
        """ Handle a control message received from the Rpc0.
        """
        pass

    def shutdown(self):
        pass


from sjrpc.core.protocols.rpc import RpcProtocol
from sjrpc.core.protocols.tunnel import TunnelProtocol
from sjrpc.core.protocols.vpn import VpnProtocol

__all__ = ['Protocol', 'RpcProtocol', 'TunnelProtocol', 'VpnProtocol']