Release: 44bfc23658

__init__.py

@@ -0,0 +1,485 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+"""
+socket_protocol (Socket Protocol)
+=================================
+
+**Author:**
+
+* Dirk Alders <sudo-dirk@mount-mockery.de>
+
+**Description:**
+
+    This Module supports point to point communication for client-server issues.
+
+**Submodules:**
+
+* :class:`socket_protocol.struct_json_protocol`
+* :class:`socket_protocol.pure_json_protocol`
+
+**Unittest:**
+
+        See also the :download:`unittest <../../socket_protocol/_testresults_/unittest.pdf>` documentation.
+"""
+__DEPENDENCIES__ = ['stringtools']
+
+import stringtools
+
+import binascii
+import hashlib
+import json
+import logging
+import os
+import struct
+import sys
+import time
+
+
+logger_name = 'SOCKET_PROTOCOL'
+logger = logging.getLogger(logger_name)
+
+
+__DESCRIPTION__ = """The Module {\\tt %s} is designed to pack and unpack data for serial transportation.
+For more Information read the sphinx documentation.""" % __name__.replace('_', '\_')
+"""The Module Description"""
+__INTERPRETER__ = (2, 3)
+"""The Tested Interpreter-Versions"""
+
+
+class RegistrationError(BaseException):
+    pass
+
+
+class callback_storage(dict):
+    def __init__(self):
+        dict.__init__(self)
+
+    def get(self, service_id, data_id):
+        if service_id is not None and data_id is not None:
+            try:
+                return self[service_id][data_id]
+            except KeyError:
+                pass  # nothing to append
+        if data_id is not None:
+            try:
+                return self[None][data_id]
+            except KeyError:
+                pass  # nothing to append
+        if service_id is not None:
+            try:
+                return self[service_id][None]
+            except KeyError:
+                pass  # nothing to append
+        try:
+            return self[None][None]
+        except KeyError:
+            pass  # nothing to append
+        return None
+
+    def add(self, service_id, data_id, callback):
+        if self.get(service_id, data_id) is not None:
+            raise RegistrationError("Callback for service_id (%s) and data_id (%s) already exists" % (repr(service_id), repr(data_id)))
+        if service_id not in self:
+            self[service_id] = {}
+        self[service_id][data_id] = callback
+
+
+class data_storage(dict):
+    KEY_STATUS = 'status'
+    KEY_SERVICE_ID = 'service_id'
+    KEY_DATA_ID = 'data_id'
+    KEY_DATA = 'data'
+
+    def __init__(self, *args, **kwargs):
+        dict.__init__(self, *args, **kwargs)
+
+    def get_status(self, default=None):
+        return self.get(self.KEY_STATUS, default)
+
+    def get_service_id(self, default=None):
+        return self.get(self.KEY_SERVICE_ID, default)
+
+    def get_data_id(self, default=None):
+        return self.get(self.KEY_DATA_ID, default)
+
+    def get_data(self, default=None):
+        return self.get(self.KEY_DATA, default)
+
+
+class struct_json_protocol(object):
+    """
+    :param comm_instance: a communication instance supportin at least these functions: :func:`register_callback`, :func:`register_disconnect_callback`, :func:`send`.
+    :type comm_instance: instance
+    :param secret: A secret (e.g. created by ``binascii.hexlify(os.urandom(24))``).
+    :type secret: str
+
+    This communication protocol supports to transfer a Service-ID, Data-ID and Data. The transmitted data is shorter than :class:`pure_json_protocol`.
+
+    .. note::
+        This class is here for compatibility reasons. Usage of :class:`pure_json_protocol` is recommended.
+
+    **Example:**
+
+    Server:
+
+    .. literalinclude:: ../../socket_protocol/_examples_/socket_protocol__struct_json_protocol_server.py
+
+    .. literalinclude:: ../../socket_protocol/_examples_/socket_protocol__struct_json_protocol_server.log
+
+
+    Client:
+
+    .. literalinclude:: ../../socket_protocol/_examples_/socket_protocol__struct_json_protocol_client.py
+
+    .. literalinclude:: ../../socket_protocol/_examples_/socket_protocol__struct_json_protocol_client.log
+    """
+    LOG_PREFIX = 'SJP:'
+
+    SID_AUTH_SEED_REQUEST = 1
+    SID_AUTH_KEY_REQUEST = 2
+    SID_AUTH_KEY_CHECK_REQUEST = 3
+    SID_AUTH_KEY_CHECK_RESPONSE = 4
+    SID_READ_REQUEST = 10
+    SID_READ_RESPONSE = 11
+    SID_WRITE_REQUEST = 20
+    SID_WRITE_RESPONSE = 21
+    SID_EXECUTE_REQUEST = 30
+    SID_EXECUTE_RESPONSE = 31
+
+    SID_RESPONSE_DICT = {SID_AUTH_SEED_REQUEST: SID_AUTH_KEY_REQUEST,
+                         SID_AUTH_KEY_REQUEST: SID_AUTH_KEY_CHECK_REQUEST,
+                         SID_AUTH_KEY_CHECK_REQUEST: SID_AUTH_KEY_CHECK_RESPONSE,
+                         SID_READ_REQUEST: SID_READ_RESPONSE,
+                         SID_WRITE_REQUEST: SID_WRITE_RESPONSE,
+                         SID_EXECUTE_REQUEST: SID_EXECUTE_RESPONSE}
+
+    SID_AUTH_LIST = [SID_AUTH_SEED_REQUEST, SID_AUTH_KEY_REQUEST, SID_AUTH_KEY_CHECK_REQUEST, SID_AUTH_KEY_CHECK_RESPONSE]
+
+    STATUS_OKAY = 0
+    STATUS_BUFFERING_UNHANDLED_REQUEST = 1
+    STATUS_AUTH_REQUIRED = 2
+    STATUS_SERVICE_OR_DATA_UNKNOWN = 3
+    STATUS_CHECKSUM_ERROR = 4
+    STATUS_OPERATION_NOT_PERMITTED = 5
+    STATUS_NAMES = {STATUS_OKAY: 'Okay',
+                    STATUS_BUFFERING_UNHANDLED_REQUEST: 'Request has no callback. Data buffered.',
+                    STATUS_AUTH_REQUIRED: 'Authentification required',
+                    STATUS_SERVICE_OR_DATA_UNKNOWN: 'Service or Data unknown',
+                    STATUS_CHECKSUM_ERROR: 'Checksum Error',
+                    STATUS_OPERATION_NOT_PERMITTED: 'Operation not permitted'}
+
+    AUTH_STATE_UNKNOWN_CLIENT = 0
+    AUTH_STATE_SEED_REQUESTED = 1
+    AUTH_STATE_SEED_TRANSFERRED = 2
+    AUTH_STATE_KEY_TRANSFERRED = 3
+    AUTH_STATE_TRUSTED_CLIENT = 4
+    AUTH_STATUS_NAMES = {AUTH_STATE_UNKNOWN_CLIENT: 'Unknown Client',
+                         AUTH_STATE_SEED_REQUESTED: 'Seed was requested',
+                         AUTH_STATE_SEED_TRANSFERRED: 'Seed has been sent',
+                         AUTH_STATE_KEY_TRANSFERRED: 'Key has been sent',
+                         AUTH_STATE_TRUSTED_CLIENT: 'Trusted Client'}
+
+    def __init__(self, comm_instance, secret=None):
+        self.__secret__ = secret
+        self.__clean_receive_buffer__()
+        self.__callbacks__ = callback_storage()
+        self.__callbacks__.add(self.SID_AUTH_SEED_REQUEST, 0, self.__authentificate_create_seed__)
+        self.__callbacks__.add(self.SID_AUTH_KEY_REQUEST, 0, self.__authentificate_create_key__)
+        self.__callbacks__.add(self.SID_AUTH_KEY_CHECK_REQUEST, 0, self.__authentificate_check_key__)
+        self.__callbacks__.add(self.SID_AUTH_KEY_CHECK_RESPONSE, 0, self.__authentificate_process_feedback__)
+        self.__authentification_state_reset__()
+        self.__seed__ = None
+        self.__comm_inst__ = comm_instance
+        self.__comm_inst__.register_callback(self.__data_available_callback__)
+        self.__comm_inst__.register_connect_callback(self.__clean_receive_buffer__)
+        self.__comm_inst__.register_disconnect_callback(self.__authentification_state_reset__)
+
+    def __authentification_state_reset__(self):
+        logger.info("%s Resetting authentification state to AUTH_STATE_UNKNOWN_CLIENT", self.LOG_PREFIX)
+        self.__authentification_state__ = self.AUTH_STATE_UNKNOWN_CLIENT
+
+    def __analyse_frame__(self, frame):
+        status, service_id, data_id = struct.unpack('>III', frame[0:12])
+        if sys.version_info >= (3, 0):
+            data = json.loads(frame[12:-1].decode('utf-8'))
+        else:
+            data = json.loads(frame[12:-1])
+        return self.__mk_msg__(status, service_id, data_id, data)
+
+    def __build_frame__(self, service_id, data_id, data, status=STATUS_OKAY):
+        frame = struct.pack('>III', status, service_id, data_id)
+        if sys.version_info >= (3, 0):
+            frame += bytes(json.dumps(data), 'utf-8')
+            frame += self.__calc_chksum__(frame)
+        else:
+            frame += json.dumps(data)
+            frame += self.__calc_chksum__(frame)
+        return frame
+
+    def __calc_chksum__(self, raw_data):
+        chksum = 0
+        for b in raw_data:
+            if sys.version_info >= (3, 0):
+                chksum ^= b
+            else:
+                chksum ^= ord(b)
+        if sys.version_info >= (3, 0):
+            return bytes([chksum])
+        else:
+            return chr(chksum)
+
+    def __check_frame_checksum__(self, frame):
+        return self.__calc_chksum__(frame[:-1]) == frame[-1:]
+
+    def __data_available_callback__(self, comm_inst):
+        frame = comm_inst.receive()
+        if not self.__check_frame_checksum__(frame):
+            logger.warning("%s Received message has a wrong checksum and will be ignored: %s.", self.LOG_PREFIX, stringtools.hexlify(frame))
+        else:
+            msg = self.__analyse_frame__(frame)
+            logger.info(
+                '%s RX <- status: %s, service_id: %s, data_id: %s, data: "%s"',
+                self.LOG_PREFIX,
+                repr(msg.get_status()),
+                repr(msg.get_service_id()),
+                repr(msg.get_data_id()),
+                repr(msg.get_data())
+            )
+            callback = self.__callbacks__.get(msg.get_service_id(), msg.get_data_id())
+            if msg.get_service_id() in self.SID_RESPONSE_DICT.keys():
+                #
+                # REQUEST RECEIVED
+                #
+                if self.__secret__ is not None and not self.check_authentification_state() and msg.get_service_id() not in self.SID_AUTH_LIST:
+                    status = self.STATUS_AUTH_REQUIRED
+                    data = None
+                    logger.warning("%s Received message needs authentification: %s. Sending negative response.", self.LOG_PREFIX, self.AUTH_STATUS_NAMES.get(self.__authentification_state__, 'Unknown authentification status!'))
+                elif callback is None:
+                    logger.warning("%s Received message with no registered callback. Sending negative response.", self.LOG_PREFIX)
+                    status = self.STATUS_BUFFERING_UNHANDLED_REQUEST
+                    data = None
+                else:
+                    try:
+                        logger.debug("%s Executing callback %s to process received data", self.LOG_PREFIX, callback.__name__)
+                        status, data = callback(msg)
+                    except TypeError:
+                        raise TypeError('Check return value of callback function {callback_name} for service_id  {service_id} and data_id {data_id}'.format(callback_name=callback.__name__, service_id=repr(msg.get_service_id()), data_id=repr(msg.get_data_id())))
+                self.send(self.SID_RESPONSE_DICT[msg.get_service_id()], msg.get_data_id(), data, status=status)
+            else:
+                #
+                # RESPONSE RECEIVED
+                #
+                if msg.get_status() not in [self.STATUS_OKAY]:
+                    logger.warning("%s Received message has a peculiar status: %s", self.LOG_PREFIX, self.STATUS_NAMES.get(msg.get_status(), 'Unknown status response!'))
+                if callback is None:
+                    status = self.STATUS_OKAY
+                    data = None
+                    self.__buffer_received_data__(msg)
+                else:
+                    try:
+                        logger.debug("%s Executing callback %s to process received data", self.LOG_PREFIX, callback.__name__)
+                        status, data = callback(msg)
+                    except TypeError:
+                        raise TypeError('Check return value of callback function {callback_name} for service_id  {service_id} and data_id {data_id}'.format(callback_name=callback.__name__, service_id=repr(msg.get_service_id()), data_id=repr(msg.get_data_id())))
+
+    def __buffer_received_data__(self, msg):
+        if not msg.get_service_id() in self.__msg_buffer__:
+            self.__msg_buffer__[msg.get_service_id()] = {}
+        if not msg.get_data_id() in self.__msg_buffer__[msg.get_service_id()]:
+            self.__msg_buffer__[msg.get_service_id()][msg.get_data_id()] = []
+        self.__msg_buffer__[msg.get_service_id()][msg.get_data_id()].append(msg)
+        logger.debug("%s Message data is stored in buffer and is now ready to be retrieved by receive method", self.LOG_PREFIX)
+
+    def __clean_receive_buffer__(self):
+        logger.debug("%s Cleaning up receive-buffer", self.LOG_PREFIX)
+        self.__msg_buffer__ = {}
+
+    def receive(self, service_id, data_id, timeout=1):
+        data = None
+        cnt = 0
+        while data is None and cnt < timeout * 10:
+            try:
+                data = self.__msg_buffer__.get(service_id, {}).get(data_id, []).pop(0)
+            except IndexError:
+                data = None
+            cnt += 1
+            time.sleep(0.1)
+        if data is None and cnt >= timeout * 10:
+            logger.warning('%s TIMEOUT (%ss): Requested data (service_id: %s; data_id: %s) not in buffer.', self.LOG_PREFIX, repr(timeout), repr(service_id), repr(data_id))
+        return data
+
+    def __mk_msg__(self, status, service_id, data_id, data):
+        return data_storage({data_storage.KEY_DATA_ID: data_id, data_storage.KEY_SERVICE_ID: service_id, data_storage.KEY_STATUS: status, data_storage.KEY_DATA: data})
+
+    def send(self, service_id, data_id, data, status=STATUS_OKAY, timeout=2, log_lvl=logging.INFO):
+        """
+        :param service_id: The Service-ID for the message. See class definitions starting with ``SERVICE_``.
+        :type service_id: int
+        :param data_id: The Data-ID for the message.
+        :type data_id: int
+        :param data: The data to be transfered. The data needs to be json compatible.
+        :type data: str
+        :param status: The Status for the message. All requests should have ``STATUS_OKAY``.
+        :type status: int
+        :param timeout: The timeout for sending data (e.g. time to establish new connection).
+        :type timeout: float
+        :param rx_log_lvl: The log level to log outgoing TX-data
+        :type rx_log_lvl: int
+        :return: True if data had been sent, otherwise False.
+        :rtype: bool
+
+        This methods sends out a message with the given content.
+        """
+        logger.log(log_lvl, '%s TX -> status: %d, service_id: %d, data_id: %d, data: "%s"', self.LOG_PREFIX, status, service_id, data_id, repr(data))
+        return self.__comm_inst__.send(self.__build_frame__(service_id, data_id, data, status), timeout=timeout, log_lvl=logging.DEBUG)
+
+    def register_callback(self, service_id, data_id, callback):
+        """
+        :param service_id: The Service-ID for the message. See class definitions starting with ``SID_``.
+        :type service_id: int
+        :param data_id: The Data-ID for the message.
+        :type data_id: int
+        :returns: True, if registration was successfull; False, if registration failed (e.g. existance of a callback for this configuration)
+        :rtype: bool
+
+        This method registers a callback for the given parameters. Givin ``None`` means, that all Service-IDs or all Data-IDs are used.
+        If a message hitting these parameters has been received, the callback will be executed.
+
+        .. note:: The :func:`callback` is priorised in the following order:
+
+            * Callbacks with defined Service-ID and Data-ID.
+            * Callbacks with a defined Data-ID.
+            * Callbacks with a defined Service-ID.
+            * Unspecific Callbacks
+
+        .. note:: The :func:`callback` is executed with these arguments:
+
+            :param msg: A :class:`dict` containing all message information.
+            :returns: status (see class definition starting with ``STATUS_``), response_data (JSON compatible object)
+        """
+        self.__callbacks__.add(service_id, data_id, callback)
+
+    def authentificate(self, timeout=2):
+        """
+        :param timeout: The timeout for the authentification (requesting seed, sending key and getting authentification_feedback).
+        :type timeout: float
+        :returns: True, if authentification was successfull; False, if not.
+        :rtype: bool
+
+        This method authetificates the client at the server.
+
+        .. note:: An authentification will only processed, if a secret had been given on initialisation.
+
+        .. note:: Client and Server needs to use the same secret.
+        """
+        if self.__secret__ is not None:
+            self.__authentification_state__ = self.AUTH_STATE_SEED_REQUESTED
+            logger.info("%s Requesting seed for authentification", self.LOG_PREFIX)
+            self.send(self.SID_AUTH_SEED_REQUEST, 0, None)
+            cnt = 0
+            while cnt < timeout * 10:
+                time.sleep(0.1)
+                if self.__authentification_state__ == self.AUTH_STATE_TRUSTED_CLIENT:
+                    return True
+                elif self.__authentification_state__ == self.AUTH_STATE_UNKNOWN_CLIENT:
+                    break
+                cnt += 1
+        return False
+
+    def check_authentification_state(self):
+        """
+        :return: True, if authentification state is okay, otherwise False
+        :rtype: bool
+        """
+        return self.__authentification_state__ == self.AUTH_STATE_TRUSTED_CLIENT
+
+    def __authentificate_salt_and_hash__(self, seed):
+        if sys.version_info >= (3, 0):
+            return hashlib.sha512(bytes(seed, 'utf-8') + self.__secret__).hexdigest()
+        else:
+            return hashlib.sha512(seed.encode('utf-8') + self.__secret__.encode('utf-8')).hexdigest()
+
+    def __authentificate_create_seed__(self, msg):
+        logger.info("%s Got seed request, sending seed for authentification", self.LOG_PREFIX)
+        self.__authentification_state__ = self.AUTH_STATE_SEED_TRANSFERRED
+        if sys.version_info >= (3, 0):
+            self.__seed__ = binascii.hexlify(os.urandom(32)).decode('utf-8')
+        else:
+            self.__seed__ = binascii.hexlify(os.urandom(32))
+        return self.STATUS_OKAY, self.__seed__
+
+    def __authentificate_create_key__(self, msg):
+        logger.info("%s Got seed, sending key for authentification", self.LOG_PREFIX)
+        self.__authentification_state__ = self.AUTH_STATE_KEY_TRANSFERRED
+        seed = msg.get_data()
+        key = self.__authentificate_salt_and_hash__(seed)
+        return self.STATUS_OKAY, key
+
+    def __authentificate_check_key__(self, msg):
+        key = msg.get_data()
+        if key == self.__authentificate_salt_and_hash__(self.__seed__):
+            self.__authentification_state__ = self.AUTH_STATE_TRUSTED_CLIENT
+            logger.info("%s Got correct key, sending positive authentification feedback", self.LOG_PREFIX)
+            return self.STATUS_OKAY, True
+        else:
+            self.__authentification_state__ = self.AUTH_STATE_UNKNOWN_CLIENT
+            logger.info("%s Got incorrect key, sending negative authentification feedback", self.LOG_PREFIX)
+            return self.STATUS_OKAY, False
+
+    def __authentificate_process_feedback__(self, msg):
+        feedback = msg.get_data()
+        if feedback:
+            self.__authentification_state__ = self.AUTH_STATE_TRUSTED_CLIENT
+            logger.info("%s Got positive authentification feedback", self.LOG_PREFIX)
+        else:
+            self.__authentification_state__ = self.AUTH_STATE_UNKNOWN_CLIENT
+            logger.warning("%s Got negative authentification feedback", self.LOG_PREFIX)
+        return self.STATUS_OKAY, None
+
+
+class pure_json_protocol(struct_json_protocol):
+    """
+    :param comm_instance: a communication instance supportin at least these functions: :func:`register_callback`, :func:`register_disconnect_callback`, :func:`send`.
+    :type comm_instance: instance
+    :param secret: A secret (e.g. created by ``binascii.hexlify(os.urandom(24))``).
+    :type secret: str
+
+    This communication protocol supports to transfer a Service-ID, Data-ID and Data.
+
+    **Example:**
+
+    Server:
+
+    .. literalinclude:: ../../socket_protocol/_examples_/socket_protocol__pure_json_protocol_server.py
+
+    .. literalinclude:: ../../socket_protocol/_examples_/socket_protocol__pure_json_protocol_server.log
+
+
+    Client:
+
+    .. literalinclude:: ../../socket_protocol/_examples_/socket_protocol__pure_json_protocol_client.py
+
+    .. literalinclude:: ../../socket_protocol/_examples_/socket_protocol__pure_json_protocol_client.log
+    """
+    def __init__(self, comm_instance, secret=None):
+        struct_json_protocol.__init__(self, comm_instance, secret)
+
+    def __build_frame__(self, service_id, data_id, data, status=struct_json_protocol.STATUS_OKAY):
+        data_frame = json.dumps(self.__mk_msg__(status, service_id, data_id, data))
+        if sys.version_info >= (3, 0):
+            data_frame = bytes(data_frame, 'utf-8')
+        checksum = self.__calc_chksum__(data_frame)
+        return data_frame + checksum
+
+    def __analyse_frame__(self, frame):
+        if sys.version_info >= (3, 0):
+            return data_storage(json.loads(frame[:-4].decode('utf-8')))
+        else:
+            return data_storage(json.loads(frame[:-4]))
+
+    def __calc_chksum__(self, raw_data):
+        return struct.pack('>I', binascii.crc32(raw_data) & 0xffffffff)
+
+    def __check_frame_checksum__(self, frame):
+        return self.__calc_chksum__(frame[:-4]) == frame[-4:]