core (types): improve SatXMPPEntity core type and type hints.
This commit is contained in:
parent
4326d01956
commit
54654b65ed
4 changed files with 241 additions and 32 deletions
|
|
@ -16,8 +16,11 @@
|
|||
# You should have received a copy of the GNU Affero General Public License
|
||||
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
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 <message/> 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: ...
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
|
|
|
|||
Loading…
Reference in a new issue