xaal.lib 0.7.2__py3-none-any.whl

xaal/lib/engine.py

@@ -0,0 +1,231 @@
+#
+#  Copyright 2014, Jérôme Colin, Jérôme Kerdreux, Philippe Tanguy,
+#  Telecom Bretagne.
+#
+#  This file is part of xAAL.
+#
+#  xAAL is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  xAAL is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with xAAL. If not, see <http://www.gnu.org/licenses/>.
+#
+
+from . import core
+from .network  import NetworkConnector
+from .exceptions  import *
+from . import config
+
+import time
+import collections
+from enum import Enum
+
+import logging
+logger = logging.getLogger(__name__)
+
+class EngineState(Enum):
+    started  = 1
+    running  = 2
+    halted   = 3
+
+class Engine(core.EngineMixin):
+
+    __slots__ = ['__last_timer','__txFifo','state','network']
+
+    def __init__(self,address=config.address,port=config.port,hops=config.hops,key=config.key):
+        core.EngineMixin.__init__(self,address,port,hops,key)
+
+        self.__last_timer = 0                    # last timer check
+        self.__txFifo = collections.deque()      # tx msg fifo
+
+        # message receive workflow
+        self.subscribe(self.handle_request)
+        # ready to go
+        self.state = EngineState.halted
+        # start network
+        self.network = NetworkConnector(address, port, hops)
+
+    #####################################################
+    # xAAL messages Tx handling
+    #####################################################
+    # Fifo for msg to send
+    def queue_msg(self, msg):
+        """queue an encoded / cyphered message"""
+        self.__txFifo.append(msg)
+
+    def send_msg(self, msg):
+        """Send an encoded message to the bus, use queue_msg instead"""
+        self.network.send(msg)
+
+    def process_tx_msg(self):
+        """ Process (send) message in tx queue called from the loop()"""
+        cnt = 0
+        while self.__txFifo:
+            temp = self.__txFifo.popleft()
+            self.send_msg(temp)
+            # try to limit rate
+            cnt = cnt + 1
+            if cnt > config.queue_size:
+                time.sleep(0.2)
+                break
+
+    #####################################################
+    # xAAL messages subscribers
+    #####################################################
+    def receive_msg(self):
+        """return new received message or None"""
+        result = None
+        data = self.network.get_data()
+        if data:
+            try:
+                msg = self.msg_factory.decode_msg(data,self.msg_filter)
+            except MessageParserError as e:
+                logger.warning(e)
+                msg = None
+            result = msg
+        return result
+
+    def process_subscribers(self):
+        """process incomming messages"""
+        msg = self.receive_msg()
+        if msg:
+            for func in self.subscribers:
+                func(msg)
+            self.process_attributes_change()
+            
+    def handle_request(self, msg):
+        """
+        Filter msg for devices according default xAAL API then process the
+        request for each targets identied in the engine
+        """
+        if not msg.is_request():
+            return 
+        
+        targets = core.filter_msg_for_devices(msg, self.devices)
+        for target in targets:
+            if msg.action == 'is_alive':
+                self.send_alive(target)
+            else:
+                self.handle_action_request(msg, target)
+
+    def handle_action_request(self, msg, target):
+        """
+        Run method (xAAL exposed method) on device:
+            - None is returned if device method do not return anything
+            - result is returned if device method gives a response
+            - Errors are raised if an error occured:
+                * Internal error
+                * error returned on the xAAL bus
+        """
+        try:
+            result = run_action(msg, target)
+            if result != None:
+                self.send_reply(dev=target,targets=[msg.source],action=msg.action,body=result)
+        except CallbackError as e:
+            self.send_error(target, e.code, e.description)
+        except XAALError as e:
+            logger.error(e)
+
+    #####################################################
+    # timers
+    #####################################################
+    def process_timers(self):
+        """Process all timers to find out which ones should be run"""
+        expire_list = []
+        
+        if len(self.timers)!=0 :
+            now = time.time()
+            # little hack to avoid to check timer to often.
+            # w/ this enable timer precision is bad, but far enougth
+            if (now - self.__last_timer) < 0.4: return
+
+            for t in self.timers:
+                if t.deadline < now:
+                    try:
+                        t.func()
+                    except CallbackError as e:
+                        logger.error(e.description)
+                    if t.counter != -1:
+                        t.counter-= 1
+                        if t.counter == 0:
+                            expire_list.append(t)
+                    t.deadline = now + t.period
+            # delete expired timers
+            for t in expire_list:
+                self.remove_timer(t)
+                    
+            self.__last_timer = now
+
+    #####################################################
+    # Mainloops & run ..
+    #####################################################
+    def loop(self):
+        """
+        Process incomming xAAL msg
+        Process timers
+        Process attributes change for devices
+        Process is_alive for device
+        Send msgs from the Tx Buffer
+        """
+        # Process xAAL msg received, filter msg and process request
+        self.process_subscribers()
+        # Process timers
+        self.process_timers()
+        # Process attributes change for devices due to timers
+        self.process_attributes_change()
+        # Process Alives
+        self.process_alives()
+        # Process xAAL msgs to send
+        self.process_tx_msg()
+
+    def start(self):
+        """Start the core engine: send queue alive msg"""
+        if self.state in [EngineState.started,EngineState.running]:
+            return
+        self.network.connect()
+        for dev in self.devices:
+            self.send_alive(dev)
+        self.state = EngineState.started
+
+    def stop(self):
+        self.state = EngineState.halted
+
+    def shutdown(self):
+        self.stop()
+
+    def run(self):
+        self.start()
+        self.state = EngineState.running
+        while self.state == EngineState.running:
+            self.loop()
+
+    def is_running(self):
+        if self.state == EngineState.running:
+            return True
+        return False
+
+def run_action(msg,device):
+    """ 
+    Extract an action & launch it
+    Return:
+        - action result
+        - None if no result
+
+    Note: If an exception raised, it's logged, and raise an XAALError.
+    """
+    method,params = core.search_action(msg,device)
+    result = None
+    try:
+        result = method(**params)
+    except Exception as e:
+        logger.error(e)
+        raise XAALError("Error in method:%s params:%s" % (msg.action,params))
+    return result
+

xaal/lib/exceptions.py

@@ -0,0 +1,20 @@
+
+# devices.py
+class DeviceError(Exception):pass
+
+# core.py
+class EngineError(Exception):pass
+class XAALError(Exception):pass
+class CallbackError(Exception):
+    def __init__(self, code, desc):
+        self.code = code
+        self.description = desc
+
+# messages.py
+class MessageParserError(Exception):pass
+class MessageError(Exception):pass
+
+# binding.py
+class UUIDError(Exception):pass
+
+__all__ = ["DeviceError","EngineError","XAALError","CallbackError","MessageParserError","MessageError","UUIDError"]

xaal/lib/helpers.py

@@ -0,0 +1,80 @@
+""" 
+This file contains some helpers functions. This functions aren't used in the lib itself
+but can be usefull for xaal packages developpers
+"""
+
+import logging
+import logging.handlers
+import os
+import time
+import coloredlogs
+from decorator import decorator
+
+from . import config
+
+def singleton(class_):
+  instances = {}
+  def getinstance(*args, **kwargs):
+    if class_ not in instances:
+        instances[class_] = class_(*args, **kwargs)
+    return instances[class_]
+  return getinstance
+
+
+@decorator
+def timeit(method,*args,**kwargs):
+    logger = logging.getLogger(__name__)
+    ts = time.time()
+    result = method(*args, **kwargs)
+    te = time.time()
+    logger.debug('%r (%r, %r) %2.6f sec' % (method.__name__, args, kwargs, te-ts))
+    return result
+
+def set_console_title(value):
+    # set xterm title
+    print("\x1B]0;xAAL => %s\x07" % value,end='\r')
+
+def setup_console_logger(level=config.log_level):
+    fmt = '%(asctime)s %(name)-25s %(funcName)-18s %(levelname)-8s %(message)s'
+    #fmt = '[%(name)s] %(funcName)s %(levelname)s: %(message)s'
+    coloredlogs.install(level=level,fmt=fmt)
+
+def setup_file_logger(name,level=config.log_level,filename = None):
+    filename = filename or os.path.join(config.log_path,'%s.log' % name)
+    formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(name)s - %(message)s')
+    handler = logging.handlers.RotatingFileHandler(filename, 'a', 10000, 1, 'utf8')
+    handler.setLevel(level)
+    handler.setFormatter(formatter)
+    # register the new handler
+    logger = logging.getLogger(name)
+    logger.root.addHandler(handler)
+    logger.root.setLevel('DEBUG')
+
+# ---------------------------------------------------------------------------
+# TBD: We should merge this stuffs, and add support for default config file 
+#      and commnand line parsing. 
+# 
+# Default arguments console_log and file_log are (and should) never be used.
+# ---------------------------------------------------------------------------
+def run_package(pkg_name,pkg_setup,console_log = True,file_log=False):
+    if console_log:
+        set_console_title(pkg_name)
+        setup_console_logger()
+    if file_log:
+        setup_file_logger(pkg_name)
+    logger = logging.getLogger(pkg_name)
+    logger.info('starting xaal package: %s'% pkg_name )
+
+    from .engine import Engine
+    eng = Engine()
+    result = pkg_setup(eng)
+
+    if result != True:
+        logger.critical("something goes wrong with package: %s" % pkg_name)
+    try:
+        eng.run()
+    except KeyboardInterrupt:
+        eng.shutdown()
+        logger.info("exit")
+
+__all__ = ['singleton','timeit','set_console_title','setup_console_logger','setup_file_logger','run_package']

xaal/lib/messages.py

@@ -0,0 +1,336 @@
+#
+#  Copyright 2014, Jérôme Colin, Jérôme Kerdreux, Philippe Tanguy,
+# Telecom Bretagne.
+#
+#  This file is part of xAAL.
+#
+#  xAAL is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  xAAL is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with xAAL. If not, see <http://www.gnu.org/licenses/>.
+#
+
+from . import tools
+from . import config
+from .bindings import UUID
+from .exceptions import MessageError, MessageParserError
+from . import cbor
+
+from enum import Enum
+from tabulate import tabulate
+import pprint
+import datetime
+import pysodium
+import struct
+import sys
+
+import logging
+logger = logging.getLogger(__name__)
+
+ALIVE_ADDR = UUID("00000000-0000-0000-0000-000000000000")
+
+
+class MessageFactory(object):
+    """Message Factory:
+    - Build xAAL message
+    - Apply security layer, Ciphering/De-Ciphering chacha20 poly1305
+    - Serialize/Deserialize data in CBOR"""
+
+    def __init__(self, cipher_key):
+        self.cipher_key = cipher_key    # key encode / decode message built from passphrase
+
+    def encode_msg(self, msg):
+        """Apply security layer and return encode MSG in CBOR
+        :param msg: xAAL msg instance
+        :type msg: Message
+        :return: return an xAAL msg ciphered and serialized in CBOR
+        :rtype: CBOR
+        """
+
+        # Format security layer
+        result = []
+        result.append(msg.version)
+        result.append(msg.timestamp[0])
+        result.append(msg.timestamp[1])
+        # list of UUID in bytes format (no Tag here)
+        result.append(cbor.dumps([t.bytes for t in msg.targets]))
+
+        # Format payload & ciphering
+        buf = []
+        buf.append(msg.source.bytes)
+        buf.append(msg.dev_type)
+        buf.append(msg.msg_type.value)
+        buf.append(msg.action)
+        if msg.body:
+            buf.append(msg.body)
+        clear = cbor.dumps(buf)
+        # Additionnal Data == cbor serialization of the targets array
+        ad      = result[3]
+        nonce   = build_nonce(msg.timestamp)
+        payload = pysodium.crypto_aead_chacha20poly1305_ietf_encrypt(clear, ad, nonce, self.cipher_key)
+
+        # Final CBOR serialization
+        result.append(payload)
+        pkt = cbor.dumps(result)
+        return pkt
+
+    def decode_msg(self, data, filter_func=None):
+        """Decode incoming CBOR data and De-Ciphering
+        :param data: data received from the multicast bus
+        :type data: cbor
+        :filter_func: function to filter incoming messages
+        :type filter_func: function
+        :return: xAAL msg
+        :rtype: Message
+        """
+        # Decode cbor incoming data
+        try:
+            data_rx = cbor.loads(data)
+        except:
+            raise MessageParserError("Unable to parse CBOR data")
+
+        # Instanciate Message, parse the security layer
+        msg = Message()
+        try:
+            msg.version   = data_rx[0]
+            msg_time      = data_rx[1]
+            targets       = cbor.loads(data_rx[3])
+            msg.targets   = [UUID(bytes=t) for t in targets]
+            msg.timestamp = [data_rx[1], data_rx[2]]
+        except IndexError:
+            raise MessageParserError("Bad Message, wrong fields")
+
+        # filter some messages
+        if filter_func is not None:
+            if not filter_func(msg):
+                return None  # filter out the message
+
+        # Replay attack, window fixed to CIPHER_WINDOW in seconds
+        now = build_timestamp()[0]  # test done only on seconds ...
+        if msg_time < (now - config.cipher_window):
+            raise MessageParserError("Potential replay attack, message too old: %d sec" % round(now - msg_time) )
+
+        if msg_time > (now + config.cipher_window):
+            raise MessageParserError("Potential replay attack, message too young: %d sec" % round(now - msg_time))
+
+        # Payload De-Ciphering
+        try:
+            ciph = data_rx[4]
+        except IndexError:
+            raise MessageParserError("Bad Message, no payload found!")
+
+        # chacha20 deciphering
+        ad = data_rx[3]
+        nonce = build_nonce(msg.timestamp)
+        try:
+            clear = pysodium.crypto_aead_chacha20poly1305_ietf_decrypt(ciph, ad, nonce, self.cipher_key)
+        except :
+            raise MessageParserError("Unable to decrypt msg")
+
+        # Decode application layer (payload)
+        try:
+            payload = cbor.loads(clear)
+        except:
+            raise MessageParserError("Unable to parse CBOR data in payload after decrypt")
+        try:
+            msg.source  = UUID(bytes=payload[0])
+            msg.dev_type = payload[1]
+            msg.msg_type = payload[2]
+            msg.action   = payload[3]
+        except IndexError:
+            raise MessageParserError("Unable to parse payload headers")
+        if len(payload) == 5:
+            msg.body = payload[4]
+
+        # Sanity check incomming message
+        if not tools.is_valid_address(msg.source):
+            raise MessageParserError("Wrong message source [%s]" % msg.source)
+        if not tools.is_valid_dev_type(msg.dev_type):
+            raise MessageParserError("Wrong message dev_type [%s]" % msg.dev_type)
+        return msg
+
+    #####################################################
+    # MSG builder
+    #####################################################
+    def build_msg(self, dev=None, targets=[], msg_type=None, action=None, body=None):
+        """the build method takes in parameters :
+        -A device
+        -The list of targets of the message
+        -The type of the message
+        -The action of the message
+        -A body if it's necessary (None if not)
+        it will return a message encoded in CBOR and ciphered.
+        """
+        message = Message()
+        if dev:
+            message.source = dev.address
+            message.dev_type = dev.dev_type
+
+        message.targets = targets
+        message.timestamp = build_timestamp()
+
+        if msg_type:
+            message.msg_type = msg_type
+        if action:
+            message.action = action
+        if body is not None and body != {}:
+            message.body = body
+
+        data = self.encode_msg(message)
+        return data
+
+    def build_alive_for(self, dev, timeout=0):
+        """Build Alive message for a given device
+        timeout = 0 is the minimum value
+        """
+        body = {}
+        body['timeout'] = timeout
+        message = self.build_msg(dev=dev, targets=[], msg_type=MessageType.NOTIFY, action=MessageAction.ALIVE.value, body=body)
+        return message
+
+    def build_error_msg(self, dev, errcode, description=None):
+        """Build a Error message"""
+        message = Message()
+        body = {}
+        body['code'] = errcode
+        if description:
+            body['description'] = description
+        message = self.build_msg(dev, [], MessageType.NOTIFY, "error", body)
+        return message
+
+
+class MessageType(Enum):
+    NOTIFY  = 0
+    REQUEST = 1
+    REPLY   = 2 
+
+
+class MessageAction(Enum):
+    ALIVE             = "alive"
+    IS_ALIVE          = "is_alive"
+    ATTRIBUTES_CHANGE = "attributes_change"
+    GET_ATTRIBUTES    = "get_attributes"
+    GET_DESCRIPTION   = "get_description"
+
+
+class Message(object):
+    """Message object used for incomming & outgoint message"""
+
+    __slots__ = ['version', 'timestamp', 'source', 'dev_type', 'msg_type', 'action', 'body', '__targets']
+
+    def __init__(self):
+        self.version = config.STACK_VERSION  # message API version
+        self.__targets = []                  # target property
+        self.timestamp = None                # message timestamp
+        self.source = None                   # message source
+        self.dev_type = None                 # message dev_type
+        self.msg_type = None                 # message type
+        self.action  = None                  # message action
+        self.body = {}                       # message body
+
+    @property
+    def targets(self):
+        return self.__targets
+
+    @targets.setter
+    def targets(self, values):
+        if not isinstance(values, list):
+            raise MessageError("Expected a list for targetsList, got %s" % (type(values),))
+        for uid in values:
+            if not tools.is_valid_address(uid):
+                raise MessageError("Bad target addr: %s" % uid)
+        self.__targets = values
+
+    def targets_as_string(self):
+        return [str(k) for k in self.targets]
+
+    def dump(self):
+        r = []
+        r.append(["version", self.version])
+        r.append(["targets", str(self.targets)])
+        r.append(["timestamp", str(self.timestamp)])
+        r.append(["source", self.source])
+        r.append(["dev_type", self.dev_type])
+        r.append(["msg_type", MessageType(self.msg_type)])
+        r.append(["action", self.action])
+        if self.body:
+            tmp=""
+            for  k,v in self.body.items():
+                k = k + ':'
+                v = pprint.pformat(v,width=55)
+                tmp = tmp+"- %-12s %s\n" % (k,v)
+            #tmp = tmp.strip()
+            r.append(["body", tmp])
+        print(tabulate(r, headers=["Fied", "Value"], tablefmt="psql"))
+
+    def __repr__(self):
+        return f"<xaal.Message {id(self):x} {self.source} {self.dev_type} {self.msg_type} {self.action}>"
+
+    def is_request(self):
+        if MessageType(self.msg_type) == MessageType.REQUEST:
+            return True
+        return False
+
+    def is_reply(self):
+        if MessageType(self.msg_type) == MessageType.REPLY:
+            return True
+        return False
+
+    def is_notify(self):
+        if MessageType(self.msg_type) == MessageType.NOTIFY:
+            return True
+        return False
+
+    def is_alive(self):
+        if self.is_notify() and self.action == MessageAction.ALIVE.value:
+            return True
+        return False
+
+    def is_request_isalive(self):
+        if self.is_request() and self.action == MessageAction.IS_ALIVE.value:
+            return True
+        return False
+
+    def is_attributes_change(self):
+        if self.is_notify() and self.action == MessageAction.ATTRIBUTES_CHANGE.value:
+            return True
+        return False
+
+    def is_get_attribute_reply(self):
+        if self.is_reply() and self.action == MessageAction.GET_ATTRIBUTES.value:
+            return True
+        return False
+
+    def is_get_description_reply(self):
+        if self.is_reply() and self.action == MessageAction.GET_DESCRIPTION.value:
+            return True
+        return False
+
+
+def build_nonce(data):
+    """ Big-Endian, time in seconds and time in microseconds """
+    nonce = struct.pack('>QL', data[0], data[1])
+    return nonce
+
+
+def build_timestamp():
+    """Return array [seconds since epoch, microseconds since last seconds] Time = UTC+0000"""
+    epoch = datetime.datetime.utcfromtimestamp(0)
+    timestamp = datetime.datetime.utcnow() - epoch
+    return _packtimestamp(timestamp.total_seconds(), timestamp.microseconds)
+
+
+# for better performance, I choose to use this trick to fix the change in size for Py3.
+# only test once.
+if sys.version_info.major == 2:
+    _packtimestamp = lambda t1,t2: [long(t1),int(t2)]
+else:
+    _packtimestamp = lambda t1,t2: [int(t1),int(t2)]