'''
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.

'''


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 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']