diff --git a/libervia/backend/core/core_types.py b/libervia/backend/core/core_types.py
index c3cd5dd8..0e796300 100644
--- a/libervia/backend/core/core_types.py
+++ b/libervia/backend/core/core_types.py
@@ -16,8 +16,11 @@
# You should have received a copy of the GNU Affero General Public License
# along with this program. If not, see .
+from abc import ABC, abstractmethod
from collections import namedtuple
from typing import Dict, Callable, Optional
+from twisted.internet import defer
+from twisted.python import failure
from typing_extensions import TypedDict
from twisted.words.protocols.jabber import jid as t_jid
@@ -25,22 +28,7 @@ from twisted.words.protocols.jabber import xmlstream
from twisted.words.xish import domish
from wokkel import disco
-
-class SatXMPPEntity:
-
- profile: str
- jid: t_jid.JID
- is_admin: bool
- is_component: bool
- server_jid: t_jid.JID
- IQ: Callable[[Optional[str], Optional[int]], xmlstream.IQ]
- identities: list[disco.DiscoIdentity]
-
-
-class SatXMPPComponent(SatXMPPEntity):
-
- def is_local(self, jid_: t_jid.JID) -> bool:
- ...
+from libervia.backend.core import exceptions
EncryptionPlugin = namedtuple(
@@ -74,3 +62,205 @@ MessageData = TypedDict(
},
total=False,
)
+
+
+class SatXMPPEntity(ABC):
+ """Base class for Client and Component."""
+
+ profile: str
+ jid: t_jid.JID
+ is_component: bool
+ server_jid: t_jid.JID
+ identities: list[disco.DiscoIdentity]
+ xmlstream: xmlstream.XmlStream
+
+ @classmethod
+ @abstractmethod
+ async def start_connection(cls, host, profile, max_retries):
+ raise NotImplementedError
+
+ @abstractmethod
+ def disconnect_profile(self, reason: failure.Failure | None) -> None:
+ """Disconnect the profile."""
+ raise NotImplementedError
+
+ @abstractmethod
+ def is_connected(self) -> bool:
+ """Return True is client is fully connected
+
+ client is considered fully connected if transport is started and all plugins
+ are initialised
+ """
+ raise NotImplementedError
+
+ @abstractmethod
+ def entity_disconnect(self) -> defer.Deferred[None]:
+ raise NotImplementedError
+
+ ## sending ##
+
+ @abstractmethod
+ def IQ(self, type_="set", timeout=60) -> xmlstream.IQ:
+ """shortcut to create an IQ element managing deferred
+
+ @param type_(unicode): IQ type ('set' or 'get')
+ @param timeout(None, int): timeout in seconds
+ @return((D)domish.Element: result stanza
+ errback is called if an error stanza is returned
+ """
+ raise NotImplementedError
+
+ @abstractmethod
+ def sendError(
+ self,
+ iq_elt: domish.Element,
+ condition: str,
+ text: str | None = None,
+ appCondition: str | None = None,
+ ) -> None:
+ """Send error stanza build from iq_elt
+
+ @param iq_elt(domish.Element): initial IQ element
+ @param condition(unicode): error condition
+ """
+ raise NotImplementedError
+
+ @abstractmethod
+ def generate_message_xml(
+ self,
+ data: MessageData,
+ post_xml_treatments: Optional[defer.Deferred] = None,
+ ) -> MessageData:
+ """Generate stanza from message data
+
+ @param data: message data
+ domish element will be put in data['xml']
+ following keys are needed:
+ - from
+ - to
+ - uid: can be set to '' if uid attribute is not wanted
+ - message
+ - type
+ - subject
+ - extra
+ @param post_xml_treatments: a Deferred which will be called with data once XML is
+ generated
+ @return: message data
+ """
+ raise NotImplementedError
+
+ @property
+ @abstractmethod
+ def is_admin(self) -> bool:
+ """True if a client is an administrator with extra privileges"""
+ raise NotImplementedError
+
+ @abstractmethod
+ def add_post_xml_callbacks(self, post_xml_treatments) -> None:
+ """Used to add class level callbacks at the end of the workflow
+
+ @param post_xml_treatments(D): the same Deferred as in sendMessage trigger
+ """
+ raise NotImplementedError
+
+ @abstractmethod
+ async def a_send(self, obj: domish.Element) -> None:
+ raise NotImplementedError
+
+ @abstractmethod
+ def send(self, obj: domish.Element) -> None:
+ # We need to call super() due to mulitple inheritance: Wokkel XMPPClient or
+ # Component's `send` needs to be called.
+ super().send(obj) # type: ignore
+
+ @abstractmethod
+ async def send_message_data(self, mess_data: MessageData) -> MessageData:
+ """Convenient method to send message data to stream
+
+ This method will send mess_data[u'xml'] to stream, but a trigger is there
+ The trigger can't be cancelled, it's a good place for e2e encryption which
+ don't handle full stanza encryption
+ This trigger can return a Deferred (it's an async_point)
+ @param mess_data(dict): message data as constructed by onMessage workflow
+ @return (dict): mess_data (so it can be used in a deferred chain)
+ """
+ raise NotImplementedError
+
+ @abstractmethod
+ def sendMessage(
+ self,
+ to_jid,
+ message,
+ subject=None,
+ mess_type="auto",
+ extra=None,
+ uid=None,
+ no_trigger=False,
+ ):
+ """Send a message to an entity
+
+ @param to_jid(jid.JID): destinee of the message
+ @param message(dict): message body, key is the language (use '' when unknown)
+ @param subject(dict): message subject, key is the language (use '' when unknown)
+ @param mess_type(str): one of standard message type (cf RFC 6121 §5.2.2) or:
+ - auto: for automatic type detection
+ - info: for information ("info_type" can be specified in extra)
+ @param extra(dict, None): extra data. Key can be:
+ - info_type: information type, can be
+ TODO
+ @param uid(unicode, None): unique id:
+ should be unique at least in this XMPP session
+ if None, an uuid will be generated
+ @param no_trigger (bool): if True, sendMessage[suffix] trigger will no be used
+ useful when a message need to be sent without any modification
+ ⚠ this will also skip encryption methods!
+ """
+ raise NotImplementedError
+
+ @abstractmethod
+ def is_message_printable(self, mess_data: MessageData) -> bool:
+ """Return True if a message contain payload to show in frontends"""
+ raise NotImplementedError
+
+ @abstractmethod
+ async def message_add_to_history(self, data):
+ """Store message into database (for local history)
+
+ @param data: message data dictionnary
+ @param client: profile's client
+ """
+ raise NotImplementedError
+
+ @abstractmethod
+ def message_get_bridge_args(self, data):
+ """Generate args to use with bridge from data dict"""
+ raise NotImplementedError
+
+ @abstractmethod
+ def message_send_to_bridge(self, data):
+ """Send message to bridge, so frontends can display it
+
+ @param data: message data dictionnary
+ """
+ raise NotImplementedError
+
+ ## helper methods ##
+
+ @abstractmethod
+ def p(self, plugin_name, missing=exceptions.MissingModule):
+ """Get a plugin if available
+
+ @param plugin_name(str): name of the plugin
+ @param missing(object): value to return if plugin is missing
+ if it is a subclass of Exception, it will be raised with a helping str as
+ argument.
+ @return (object): requested plugin wrapper, or default value
+ The plugin wrapper will return the method with client set as first
+ positional argument
+ """
+ raise NotImplementedError
+
+
+class SatXMPPComponent(SatXMPPEntity):
+
+ def is_local(self, jid_: t_jid.JID) -> bool: ...
diff --git a/libervia/backend/core/xmpp.py b/libervia/backend/core/xmpp.py
index d7b76a19..95982a07 100644
--- a/libervia/backend/core/xmpp.py
+++ b/libervia/backend/core/xmpp.py
@@ -518,7 +518,7 @@ class SatXMPPEntity(core_types.SatXMPPEntity):
xs.add_hook(C.STREAM_HOOK_SEND, hook)
super(SatXMPPEntity, self)._connected(xs)
- def disconnect_profile(self, reason):
+ def disconnect_profile(self, reason: failure.Failure|None) -> None:
if self._connected_d is not None:
self.host_app.bridge.disconnected(
self.profile
@@ -581,7 +581,7 @@ class SatXMPPEntity(core_types.SatXMPPEntity):
if disconnected_cb is not None:
yield disconnected_cb(self)
- def is_connected(self):
+ def is_connected(self) -> bool:
"""Return True is client is fully connected
client is considered fully connected if transport is started and all plugins
@@ -594,7 +594,7 @@ class SatXMPPEntity(core_types.SatXMPPEntity):
return self._connected_d is not None and transport_connected
- def entity_disconnect(self):
+ def entity_disconnect(self) -> defer.Deferred[None]:
if not self.host_app.trigger.point("disconnecting", self):
return
log.info(_("Disconnecting..."))
@@ -606,7 +606,7 @@ class SatXMPPEntity(core_types.SatXMPPEntity):
## sending ##
- def IQ(self, type_="set", timeout=60):
+ def IQ(self, type_="set", timeout=60) -> xmlstream.IQ:
"""shortcut to create an IQ element managing deferred
@param type_(unicode): IQ type ('set' or 'get')
@@ -618,7 +618,13 @@ class SatXMPPEntity(core_types.SatXMPPEntity):
iq_elt.timeout = timeout
return iq_elt
- def sendError(self, iq_elt, condition, text=None, appCondition=None):
+ def sendError(
+ self,
+ iq_elt: domish.Element,
+ condition: str,
+ text: str|None = None,
+ appCondition: str|None = None
+ ) -> None:
"""Send error stanza build from iq_elt
@param iq_elt(domish.Element): initial IQ element
@@ -854,9 +860,9 @@ class SatXMPPEntity(core_types.SatXMPPEntity):
"""A message sending can be cancelled by a plugin treatment"""
failure.trap(exceptions.CancelError)
- def is_message_printable(self, mess_data):
+ def is_message_printable(self, mess_data: MessageData) -> bool:
"""Return True if a message contain payload to show in frontends"""
- return (
+ return bool(
mess_data["message"]
or mess_data["subject"]
or mess_data["extra"].get(C.KEY_ATTACHMENTS)
diff --git a/libervia/backend/memory/disco.py b/libervia/backend/memory/disco.py
index c8ddebce..da1d59da 100755
--- a/libervia/backend/memory/disco.py
+++ b/libervia/backend/memory/disco.py
@@ -204,12 +204,18 @@ class Discovery(object):
disco_infos = await self.get_infos(client, jid_, node)
return (category, type_) in disco_infos.identities
- def get_infos(self, client, jid_=None, node="", use_cache=True):
+ def get_infos(
+ self,
+ client: SatXMPPEntity,
+ jid_: jid.JID|None=None,
+ node: str="",
+ use_cache: bool=True
+ ) -> defer.Deferred[disco.DiscoInfo]:
"""get disco infos from jid_, filling capability hash if needed
@param jid_: jid of the target, or None for profile's server
- @param node(unicode): optional node to use for disco request
- @param use_cache(bool): if True, use cached data if available
+ @param node: optional node to use for disco request
+ @param use_cache: if True, use cached data if available
@return: a Deferred which fire disco.DiscoInfo
"""
if jid_ is None:
diff --git a/libervia/backend/memory/encryption.py b/libervia/backend/memory/encryption.py
index a0666d4a..13cb5ad5 100644
--- a/libervia/backend/memory/encryption.py
+++ b/libervia/backend/memory/encryption.py
@@ -77,7 +77,14 @@ class EncryptionHandler:
log.info(_("encryption sessions restored"))
@classmethod
- def register_plugin(cls, plg_instance, name, namespace, priority=0, directed=False):
+ def register_plugin(
+ cls,
+ plg_instance,
+ name: str,
+ namespace: str,
+ priority: int=0,
+ directed: bool=False
+ ) -> None:
"""Register a plugin handling an encryption algorithm
@param plg_instance(object): instance of the plugin
@@ -92,12 +99,12 @@ class EncryptionHandler:
entity(jid.JID): entity to stop encrypted session with
if they don't exists, those 2 methods will be ignored.
- @param name(unicode): human readable name of the encryption algorithm
- @param namespace(unicode): namespace of the encryption algorithm
- @param priority(int): priority of this plugin to encrypt an message when not
+ @param name: human readable name of the encryption algorithm
+ @param namespace: namespace of the encryption algorithm
+ @param priority: priority of this plugin to encrypt an message when not
selected manually
- @param directed(bool): True if this plugin is directed (if it works with one
- device only at a time)
+ @param directed: True if this plugin is directed (if it works with one
+ device only at a time)
"""
existing_ns = set()
existing_names = set()