slidge 0.1.0rc1__py3-none-any.whl → 0.1.2__py3-none-any.whl

slidge/core/session.py

@@ -1,75 +1,66 @@
-import functools
+import asyncio
 import logging
-from typing import Generic, Optional, Type, Union, cast
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Generic,
+    Iterable,
+    NamedTuple,
+    Optional,
+    Union,
+    cast,
+)
 
-from slixmpp import JID, Message, Presence
+import aiohttp
+from slixmpp import JID, Message
 from slixmpp.exceptions import XMPPError
+from slixmpp.types import PresenceShows
 
-from ..util import ABCSubclassableOnceAtMost, BiDict
+from ..command import SearchResult
+from ..contact import LegacyContact, LegacyRoster
+from ..group.bookmarks import LegacyBookmarks
+from ..group.room import LegacyMUC
+from ..util import ABCSubclassableOnceAtMost
 from ..util.db import GatewayUser, user_store
+from ..util.sql import SQLBiDict
 from ..util.types import (
-    BookmarksType,
-    Chat,
-    GatewayType,
-    LegacyContactType,
+    LegacyGroupIdType,
     LegacyMessageType,
-    LegacyMUCType,
-    LegacyParticipantType,
-    LegacyRosterType,
-    PresenceShow,
-    SessionType,
+    LegacyThreadType,
+    LinkPreview,
+    Mention,
+    PseudoPresenceShow,
+    RecipientType,
+    ResourceDict,
 )
-from ..util.util import SearchResult
-from .contact import LegacyRoster
-from .muc.bookmarks import LegacyBookmarks
-from .muc.room import LegacyMUC
-
-
-def ignore_sent_carbons(func):
-    @functools.wraps(func)
-    async def wrapped(self: SessionType, msg: Message):
-        if (i := msg.get_id()) in self.ignore_messages:
-            self.log.debug("Ignored sent carbon: %s", i)
-            self.ignore_messages.remove(i)
-        else:
-            return await func(self, msg)
+from ..util.util import deprecated
 
-    return wrapped
+if TYPE_CHECKING:
+    from ..group.participant import LegacyParticipant
+    from ..util.types import Sender
+    from .gateway import BaseGateway
 
 
-def ignore_message_to_component(func):
-    @functools.wraps(func)
-    async def wrapped(self: SessionType, msg: Message):
-        if msg.get_to() != self.xmpp.boundjid.bare:
-            return await func(self, msg)
-        else:
-            log.debug("Ignoring message to component: %s %s", self, msg)
-
-    return wrapped
+class CachedPresence(NamedTuple):
+    status: Optional[str]
+    show: Optional[str]
+    kwargs: dict[str, Any]
 
 
 class BaseSession(
-    Generic[
-        GatewayType,
-        LegacyMessageType,
-        LegacyRosterType,
-        LegacyContactType,
-        BookmarksType,
-        LegacyMUCType,
-        LegacyParticipantType,
-    ],
-    metaclass=ABCSubclassableOnceAtMost,
+    Generic[LegacyMessageType, RecipientType], metaclass=ABCSubclassableOnceAtMost
 ):
     """
+    The session of a registered :term:`User`.
+
     Represents a gateway user logged in to the legacy network and performing actions.
 
-    Will be instantiated automatically when a user sends an online presence to the gateway
-    component, as per :xep:`0100`.
+    Will be instantiated automatically on slidge startup for each registered user,
+    or upon registration for new (validated) users.
 
-    Must be subclassed for a functional slidge plugin.
+    Must be subclassed for a functional :term:`Legacy Module`.
     """
 
-    sent: BiDict[LegacyMessageType, str]
     """
     Since we cannot set the XMPP ID of messages sent by XMPP clients, we need to keep a mapping
     between XMPP IDs and legacy message IDs if we want to further refer to a message that was sent
@@ -77,623 +68,700 @@ class BaseSession(
     the official client of a legacy network.
     """
 
-    xmpp: "GatewayType"
+    xmpp: "BaseGateway"
     """
     The gateway instance singleton. Use it for low-level XMPP calls or custom methods that are not
     session-specific.
     """
 
-    def __init__(self, user: GatewayUser):
-        self._roster_cls: Type[
-            LegacyRosterType
-        ] = LegacyRoster.get_self_or_unique_subclass()
+    http: aiohttp.ClientSession
 
+    MESSAGE_IDS_ARE_THREAD_IDS = False
+    """
+    Set this to True if the legacy service uses message IDs as thread IDs,
+    eg Mattermost, where you can only 'create a thread' by replying to the message,
+    in which case the message ID is also a thread ID (and all messages are potential
+    threads).
+    """
+    SPECIAL_MSG_ID_PREFIX: Optional[str] = None
+    """
+    If you set this, XMPP message IDs starting with this won't be converted to legacy ID,
+    but passed as is to :meth:`.on_react`, and usual checks for emoji restriction won't be
+    applied.
+    This can be used to implement voting in polls in a hacky way.
+    """
+
+    def __init__(self, user: GatewayUser):
         self.log = logging.getLogger(user.bare_jid)
 
         self.user = user
-        self.sent = BiDict[LegacyMessageType, str]()  # TODO: set a max size for this
+        self.sent = SQLBiDict[LegacyMessageType, str](
+            "session_message_sent", "legacy_id", "xmpp_id", self.user
+        )
         # message ids (*not* stanza-ids), needed for last msg correction
-        self.muc_sent_msg_ids = BiDict[LegacyMessageType, str]()
+        self.muc_sent_msg_ids = SQLBiDict[LegacyMessageType, str](
+            "session_message_sent_muc", "legacy_id", "xmpp_id", self.user
+        )
 
         self.ignore_messages = set[str]()
 
-        self.contacts: LegacyRosterType = self._roster_cls(self)
-        self.never_logged = True
+        self.contacts: LegacyRoster = LegacyRoster.get_self_or_unique_subclass()(self)
+        self._logged = False
+        self.__reset_ready()
 
-        self.bookmarks: BookmarksType = LegacyBookmarks.get_self_or_unique_subclass()(
+        self.bookmarks: LegacyBookmarks = LegacyBookmarks.get_self_or_unique_subclass()(
             self
         )
 
-    def shutdown(self):
-        for c in self.contacts:
-            c.offline()
-        for m in self.bookmarks:
-            m.shutdown()
-        self.xmpp.loop.create_task(self.logout())
-
-    @staticmethod
-    def legacy_msg_id_to_xmpp_msg_id(legacy_msg_id: LegacyMessageType) -> str:
-        """
-        Convert a legacy msg ID to a valid XMPP msg ID.
-        Needed for read marks and message corrections.
+        self.http = self.xmpp.http
 
-        The default implementation just converts the legacy ID to a :class:`str`,
-        but this should be overridden in case some characters needs to be escaped,
-        or to add some additional, legacy network-specific logic.
+        self.threads = SQLBiDict[str, LegacyThreadType](  # type:ignore
+            "session_thread_sent_muc", "legacy_id", "xmpp_id", self.user
+        )
+        self.thread_creation_lock = asyncio.Lock()
 
-        :param legacy_msg_id:
-        :return: Should return a string that is usable as an XMPP stanza ID
-        """
-        return str(legacy_msg_id)
+        self.__cached_presence: Optional[CachedPresence] = None
 
-    @staticmethod
-    def xmpp_msg_id_to_legacy_msg_id(i: str) -> LegacyMessageType:
-        """
-        Convert a legacy XMPP ID to a valid XMPP msg ID.
-        Needed for read marks and message corrections.
+        self.avatar_hash: Optional[str] = None
 
-        The default implementation just converts the legacy ID to a :class:`str`,
-        but this should be overridden in case some characters needs to be escaped,
-        or to add some additional, legacy network-specific logic.
+        self.__tasks = set[asyncio.Task]()
 
-        The default implementation is an identity function
+    def __remove_task(self, fut):
+        self.log.debug("Removing fut %s", fut)
+        self.__tasks.remove(fut)
 
-        :param i: The XMPP stanza ID
-        :return: An ID that can be used to identify a message on the legacy network
-        """
-        return cast(LegacyMessageType, i)
+    def create_task(self, coro) -> None:
+        task = self.xmpp.loop.create_task(coro)
+        self.__tasks.add(task)
+        self.log.debug("Creating task %s", task)
+        task.add_done_callback(lambda _: self.__remove_task(task))
 
-    @classmethod
-    def _from_user_or_none(cls, user):
-        if user is None:
-            raise XMPPError(
-                text="User not found", condition="subscription-required", etype="auth"
-            )
+    def cancel_all_tasks(self):
+        for task in self.__tasks:
+            task.cancel()
 
-        session = _sessions.get(user)
-        if session is None:
-            _sessions[user] = session = cls(user)
-        return session
+    async def login(self) -> Optional[str]:
+        """
+        Logs in the gateway user to the legacy network.
 
-    @classmethod
-    def from_user(cls, user):
-        return cls._from_user_or_none(user)
+        Triggered when the gateway start and on user registration.
+        It is recommended that this function returns once the user is logged in,
+        so if you need to await forever (for instance to listen to incoming events),
+        it's a good idea to wrap your listener in an asyncio.Task.
 
-    @classmethod
-    def from_stanza(cls: Type[SessionType], s) -> SessionType:
+        :return: Optionally, a text to use as the gateway status, e.g., "Connected as 'dude@legacy.network'"
         """
-        Get a user's :class:`.LegacySession` using the "from" field of a stanza
+        raise NotImplementedError
 
-        Meant to be called from :class:`BaseGateway` only.
+    async def logout(self):
+        """
+        Logs out the gateway user from the legacy network.
 
-        :param s:
-        :return:
+        Called on gateway shutdown.
         """
-        return cls._from_user_or_none(user_store.get_by_stanza(s))
+        raise NotImplementedError
 
-    @classmethod
-    def from_jid(cls: Type[SessionType], jid: JID) -> SessionType:
+    async def on_text(
+        self,
+        chat: RecipientType,
+        text: str,
+        *,
+        reply_to_msg_id: Optional[LegacyMessageType] = None,
+        reply_to_fallback_text: Optional[str] = None,
+        reply_to: Optional["Sender"] = None,
+        thread: Optional[LegacyThreadType] = None,
+        link_previews: Iterable[LinkPreview] = (),
+        mentions: Optional[list[Mention]] = None,
+    ) -> Optional[LegacyMessageType]:
         """
-        Get a user's :class:`.LegacySession` using its jid
+        Triggered when the user sends a text message from XMPP to a bridged entity, e.g.
+        to ``translated_user_name@slidge.example.com``, or ``translated_group_name@slidge.example.com``
 
-        Meant to be called from :class:`BaseGateway` only.
+        Override this and implement sending a message to the legacy network in this method.
 
-        :param jid:
-        :return:
-        """
-        return cls._from_user_or_none(user_store.get_by_jid(jid))
+        :param text: Content of the message
+        :param chat: Recipient of the message. :class:`.LegacyContact` instance for 1:1 chat,
+            :class:`.MUC` instance for groups.
+        :param reply_to_msg_id: A legacy message ID if the message references (quotes)
+            another message (:xep:`0461`)
+        :param reply_to_fallback_text: Content of the quoted text. Not necessarily set
+            by XMPP clients
+        :param reply_to: Author of the quoted message. :class:`LegacyContact` instance for
+            1:1 chat, :class:`LegacyParticipant` instance for groups.
+            If `None`, should be interpreted as a self-reply if reply_to_msg_id is not None.
+        :param link_previews: A list of sender-generated link previews.
+            At the time of writing, only `Cheogram <https://wiki.soprani.ca/CheogramApp/LinkPreviews>`_
+            supports it.
+        :param mentions: (only for groups) A list of Contacts mentioned by their
+            nicknames.
+        :param thread:
 
-    @classmethod
-    async def kill_by_jid(cls, jid: JID):
+        :return: An ID of some sort that can be used later to ack and mark the message
+            as read by the user
         """
-        Terminate a user session.
+        raise NotImplementedError
 
-        Meant to be called from :class:`BaseGateway` only.
+    send_text = deprecated("BaseSession.send_text", on_text)
 
-        :param jid:
-        :return:
+    async def on_file(
+        self,
+        chat: RecipientType,
+        url: str,
+        *,
+        http_response: aiohttp.ClientResponse,
+        reply_to_msg_id: Optional[LegacyMessageType] = None,
+        reply_to_fallback_text: Optional[str] = None,
+        reply_to: Optional[Union["LegacyContact", "LegacyParticipant"]] = None,
+        thread: Optional[LegacyThreadType] = None,
+    ) -> Optional[LegacyMessageType]:
         """
-        log.debug("Killing session of %s", jid)
-        for user, session in _sessions.items():
-            if user.jid == jid.bare:
-                break
-        else:
-            log.debug("Did not find a session for %s", jid)
-            return
-        for c in session.contacts:
-            c.unsubscribe()
-        await session.logout()
-        await cls.xmpp.unregister(user)
-        del _sessions[user]
-        del user
-        del session
+        Triggered when the user sends a file using HTTP Upload (:xep:`0363`)
 
-    @ignore_message_to_component
-    @ignore_sent_carbons
-    async def send_from_msg(self, m: Message):
-        """
-        Meant to be called from :class:`BaseGateway` only.
+        :param url: URL of the file
+        :param chat: See :meth:`.BaseSession.on_text`
+        :param http_response: The HTTP GET response object on the URL
+        :param reply_to_msg_id: See :meth:`.BaseSession.on_text`
+        :param reply_to_fallback_text: See :meth:`.BaseSession.on_text`
+        :param reply_to: See :meth:`.BaseSession.on_text`
+        :param thread:
 
-        :param m:
-        :return:
+        :return: An ID of some sort that can be used later to ack and mark the message
+            as read by the user
         """
-        # we MUST not use `if m["replace"]["id"]` because it adds the tag if not
-        # present. this is a problem for MUC echoed messages
-        if m.xml.find("{urn:xmpp:message-correct:0}replace") is not None:
-            # ignore last message correction (handled by a specific method)
-            return
-        if m.xml.find("{urn:xmpp:fasten:0}apply-to") is not None:
-            # ignore message retraction (handled by a specific method)
-            return
-
-        e = await self.__get_entity(m)
-        self.log.debug("Entity %r", e)
+        raise NotImplementedError
 
-        if m.xml.find("{jabber:x:oob}x") is not None:
-            url = m["oob"]["url"]
-        else:
-            url = None
-
-        text = m["body"]
-        if m.xml.find("{urn:xmpp:fallback:0}fallback") is not None and (
-            isinstance(e, LegacyMUC) or e.REPLIES  # type: ignore
-        ):
-            text = m["feature_fallback"].get_stripped_body()
-            reply_fallback = m["feature_fallback"].get_fallback_body()
-        else:
-            reply_fallback = None
-
-        # Testing with `is None` is mandatory since a reply element have no
-        # 'data' but only attributes, so the ElementTree is "false-ish".
-        # Grrrrr this took me some time to figure out.
-        reply_to = None
-        if m.xml.find("{urn:xmpp:reply:0}reply") is not None:
-            reply_to_msg_xmpp_id = self.__xmpp_msg_id_to_legacy(m["reply"]["id"])
-            reply_to_jid = JID(m["reply"]["to"])
-            if m["type"] == "chat":
-                if reply_to_jid.bare != self.user.jid.bare:
-                    try:
-                        reply_to = await self.contacts.by_jid(reply_to_jid)
-                    except XMPPError:
-                        pass
-            elif m["type"] == "groupchat":
-                nick = reply_to_jid.resource
-                try:
-                    muc = await self.bookmarks.by_jid(reply_to_jid)
-                except XMPPError:
-                    pass
-                else:
-                    if nick != muc.user_nick:
-                        reply_to = await muc.get_participant(reply_to_jid.resource)
-        else:
-            reply_to_msg_xmpp_id = None
-            reply_to = None
+    send_file = deprecated("BaseSession.send_file", on_file)
 
-        kwargs = dict(
-            reply_to_msg_id=reply_to_msg_xmpp_id,
-            reply_to_fallback_text=reply_fallback,
-            reply_to=reply_to,
-        )
+    async def on_active(
+        self, chat: RecipientType, thread: Optional[LegacyThreadType] = None
+    ):
+        """
+        Triggered when the user sends an 'active' chat state (:xep:`0085`)
 
-        if url:
-            legacy_msg_id = await self.send_file(url, e, **kwargs)
-        elif text:
-            legacy_msg_id = await self.send_text(text, e, **kwargs)
-        else:
-            log.debug("Ignoring %s", m)
-            return
+        :param chat: See :meth:`.BaseSession.on_text`
+        :param thread:
+        """
+        raise NotImplementedError
 
-        if isinstance(e, LegacyMUC):
-            await e.echo(m, legacy_msg_id)
-            if legacy_msg_id is not None:
-                self.muc_sent_msg_ids[legacy_msg_id] = m.get_id()
-        else:
-            if legacy_msg_id is not None:
-                self.sent[legacy_msg_id] = m.get_id()
-
-    async def __get_entity(self, m: Message) -> Union[LegacyContactType, LegacyMUCType]:
-        if m.get_type() == "groupchat":
-            muc = await self.bookmarks.by_jid(m.get_to())
-            if m.get_from().resource not in muc.user_resources:
-                raise XMPPError("not-acceptable", "You are not connected to this chat")
-            return muc
-        else:
-            return await self.contacts.by_jid(m.get_to())
+    active = deprecated("BaseSession.active", on_active)
 
-    @ignore_message_to_component
-    async def active_from_msg(self, m: Message):
+    async def on_inactive(
+        self, chat: RecipientType, thread: Optional[LegacyThreadType] = None
+    ):
         """
-        Meant to be called from :class:`BaseGateway` only.
+        Triggered when the user sends an 'inactive' chat state (:xep:`0085`)
 
-        :param m:
-        :return:
+        :param chat: See :meth:`.BaseSession.on_text`
+        :param thread:
         """
-        await self.active(await self.__get_entity(m))
+        raise NotImplementedError
 
-    @ignore_message_to_component
-    async def inactive_from_msg(self, m: Message):
-        """
-        Meant to be called from :class:`BaseGateway` only.
+    inactive = deprecated("BaseSession.inactive", on_inactive)
 
-        :param m:
-        :return:
+    async def on_composing(
+        self, chat: RecipientType, thread: Optional[LegacyThreadType] = None
+    ):
         """
-        await self.inactive(await self.__get_entity(m))
+        Triggered when the user starts typing in a legacy chat (:xep:`0085`)
 
-    @ignore_message_to_component
-    async def composing_from_msg(self, m: Message):
+        :param chat: See :meth:`.BaseSession.on_text`
+        :param thread:
         """
-        Meant to be called from :class:`BaseGateway` only.
+        raise NotImplementedError
 
-        :param m:
-        :return:
-        """
-        await self.composing(await self.__get_entity(m))
+    composing = deprecated("BaseSession.composing", on_composing)
 
-    @ignore_message_to_component
-    async def paused_from_msg(self, m: Message):
+    async def on_paused(
+        self, chat: RecipientType, thread: Optional[LegacyThreadType] = None
+    ):
         """
-        Meant to be called from :class:`BaseGateway` only.
+        Triggered when the user pauses typing in a legacy chat (:xep:`0085`)
 
-        :param m:
-        :return:
+        :param chat: See :meth:`.BaseSession.on_text`
+        :param thread:
         """
-        await self.paused(await self.__get_entity(m))
+        raise NotImplementedError
 
-    def __xmpp_msg_id_to_legacy(self, xmpp_id: str):
-        sent = self.sent.inverse.get(xmpp_id)
-        if sent:
-            return sent
+    paused = deprecated("BaseSession.paused", on_paused)
 
-        try:
-            return self.xmpp_msg_id_to_legacy_msg_id(xmpp_id)
-        except Exception as e:
-            log.debug(
-                "Couldn't convert xmpp msg ID to legacy ID, ignoring: %r, %s",
-                e,
-                e.args,
-            )
+    async def on_displayed(
+        self,
+        chat: RecipientType,
+        legacy_msg_id: LegacyMessageType,
+        thread: Optional[LegacyThreadType] = None,
+    ):
+        """
+        Triggered when the user reads a message in a legacy chat. (:xep:`0333`)
 
-    @ignore_message_to_component
-    @ignore_sent_carbons
-    async def displayed_from_msg(self, m: Message):
+        This is only possible if a valid ``legacy_msg_id`` was passed when
+        transmitting a message from a legacy chat to the user, eg in
+        :meth:`slidge.contact.LegacyContact.send_text`
+        or
+        :meth:`slidge.group.LegacyParticipant.send_text`.
+
+        :param chat: See :meth:`.BaseSession.on_text`
+        :param legacy_msg_id: Identifier of the message/
+        :param thread:
         """
-        Meant to be called from :class:`BaseGateway` only.
+        raise NotImplementedError
 
-        :param m:
-        :return:
+    displayed = deprecated("BaseSession.displayed", on_displayed)
+
+    async def on_correct(
+        self,
+        chat: RecipientType,
+        text: str,
+        legacy_msg_id: LegacyMessageType,
+        *,
+        thread: Optional[LegacyThreadType] = None,
+        link_previews: Iterable[LinkPreview] = (),
+        mentions: Optional[list[Mention]] = None,
+    ) -> Optional[LegacyMessageType]:
         """
-        e = await self.__get_entity(m)
-        displayed_msg_id = m["displayed"]["id"]
-        if not isinstance(e, LegacyMUC) and self.xmpp.MARK_ALL_MESSAGES:
-            to_mark = e.get_msg_xmpp_id_up_to(displayed_msg_id)  # type: ignore
-            if to_mark is None:
-                log.debug("Can't mark all messages up to %s", displayed_msg_id)
-                to_mark = [displayed_msg_id]
-        else:
-            to_mark = [displayed_msg_id]
-        for xmpp_id in to_mark:
-            if legacy := self.__xmpp_msg_id_to_legacy(xmpp_id):
-                await self.displayed(legacy, e)
-                if isinstance(e, LegacyMUC):
-                    await e.echo(m, None)
-            else:
-                log.debug("Ignored displayed marker for msg: %r", xmpp_id)
-
-    @ignore_message_to_component
-    @ignore_sent_carbons
-    async def correct_from_msg(self, m: Message):
-        e = await self.__get_entity(m)
-        xmpp_id = m["replace"]["id"]
-        if isinstance(e, LegacyMUC):
-            legacy_id = self.muc_sent_msg_ids.inverse.get(xmpp_id)
-        else:
-            legacy_id = self.__xmpp_msg_id_to_legacy(xmpp_id)
+        Triggered when the user corrects a message using :xep:`0308`
 
-        if legacy_id is None:
-            log.debug("Did not find legacy ID to correct")
-            new_legacy_msg_id = await self.send_text(m["body"], e)
-        else:
-            new_legacy_msg_id = await self.correct(m["body"], legacy_id, e)
-        if isinstance(e, LegacyMUC):
-            if new_legacy_msg_id is not None:
-                self.muc_sent_msg_ids[new_legacy_msg_id] = m.get_id()
-            await e.echo(m, new_legacy_msg_id)
-        else:
-            if new_legacy_msg_id is not None:
-                self.sent[new_legacy_msg_id] = m.get_id()
-
-    @ignore_message_to_component
-    @ignore_sent_carbons
-    async def react_from_msg(self, m: Message):
-        e = await self.__get_entity(m)
-        react_to: str = m["reactions"]["id"]
-        legacy_id = self.__xmpp_msg_id_to_legacy(react_to)
-
-        if not legacy_id:
-            log.debug("Ignored reaction from user")
-            raise XMPPError("internal-server-error")
-
-        emojis = [
-            remove_emoji_variation_selector_16(r["value"]) for r in m["reactions"]
-        ]
-        error_msg = None
-
-        if e.REACTIONS_SINGLE_EMOJI and len(emojis) > 1:
-            error_msg = "Maximum 1 emoji/message"
-
-        if not error_msg and (subset := await e.available_emojis(legacy_id)):
-            log.debug("%s %s %s", set(emojis), subset, set(emojis).issubset(subset))
-            if not set(emojis).issubset(subset):
-                error_msg = (
-                    f"You can only react with the following emojis: {''.join(subset)}"
-                )
+        This is only possible if a valid ``legacy_msg_id`` was returned by
+        :meth:`.on_text`.
 
-        if error_msg:
-            self.send_gateway_message(error_msg)
-            if not isinstance(e, LegacyMUC):
-                # no need to carbon for groups, we just don't echo the stanza
-                e.react(legacy_id, carbon=True)  # type: ignore
-            await self.react(legacy_id, [], e)
-            raise XMPPError("not-acceptable", text=error_msg)
-
-        await self.react(legacy_id, emojis, e)
-        if isinstance(e, LegacyMUC):
-            await e.echo(m, None)
-
-    @ignore_message_to_component
-    @ignore_sent_carbons
-    async def retract_from_msg(self, m: Message):
-        e = await self.__get_entity(m)
-        xmpp_id: str = m["apply_to"]["id"]
-        legacy_id = self.__xmpp_msg_id_to_legacy(xmpp_id)
-        if legacy_id:
-            await self.retract(legacy_id, e)
-            if isinstance(e, LegacyMUC):
-                await e.echo(m, None)
-        else:
-            log.debug("Ignored retraction from user")
+        :param chat: See :meth:`.BaseSession.on_text`
+        :param text: The new text
+        :param legacy_msg_id: Identifier of the edited message
+        :param thread:
+        :param link_previews: A list of sender-generated link previews.
+            At the time of writing, only `Cheogram <https://wiki.soprani.ca/CheogramApp/LinkPreviews>`_
+            supports it.
+        :param mentions: (only for groups) A list of Contacts mentioned by their
+            nicknames.
+        """
+        raise NotImplementedError
 
-    async def join_groupchat(self, p: Presence):
-        if not self.xmpp.GROUPS:
-            raise XMPPError(
-                "not-implemented", "This gateway does not implement multi-user chats."
-            )
-        muc = await self.bookmarks.by_jid(p.get_to())
-        log.debug("BOOKMARKS: %r", self.bookmarks.__class__)
-        log.debug("JOIN MUC: %r -- %r -- %r", muc, muc.join, muc.__class__)
-        await muc.join(p)
+    correct = deprecated("BaseSession.correct", on_correct)
 
-    def send_gateway_status(
+    async def on_react(
         self,
-        status: Optional[str] = None,
-        show=Optional[PresenceShow],
-        **kwargs,
+        chat: RecipientType,
+        legacy_msg_id: LegacyMessageType,
+        emojis: list[str],
+        thread: Optional[LegacyThreadType] = None,
     ):
         """
-        Send a presence from the gateway to the user.
+        Triggered when the user sends message reactions (:xep:`0444`).
 
-        Can be used to indicate the user session status, ie "SMS code required", "connected", …
+        :param chat: See :meth:`.BaseSession.on_text`
+        :param thread:
+        :param legacy_msg_id: ID of the message the user reacts to
+        :param emojis: Unicode characters representing reactions to the message ``legacy_msg_id``.
+            An empty string means "no reaction", ie, remove all reactions if any were present before
+        """
+        raise NotImplementedError
 
-        :param status: A status message
-        :param show: Presence stanza 'show' element. I suggest using "dnd" to show
-            that the gateway is not fully functional
+    react = deprecated("BaseSession.react", on_react)
+
+    async def on_retract(
+        self,
+        chat: RecipientType,
+        legacy_msg_id: LegacyMessageType,
+        thread: Optional[LegacyThreadType] = None,
+    ):
         """
-        self.xmpp.send_presence(
-            pto=self.user.bare_jid, pstatus=status, pshow=show, **kwargs
-        )
+        Triggered when the user retracts (:xep:`0424`) a message.
 
-    def send_gateway_message(self, text, **msg_kwargs):
+        :param chat: See :meth:`.BaseSession.on_text`
+        :param thread:
+        :param legacy_msg_id: Legacy ID of the retracted message
         """
-        Send a message from the gateway component to the user.
+        raise NotImplementedError
 
-        Can be used to indicate the user session status, ie "SMS code required", "connected", …
+    retract = deprecated("BaseSession.retract", on_retract)
 
-        :param text: A text
+    async def on_presence(
+        self,
+        resource: str,
+        show: PseudoPresenceShow,
+        status: str,
+        resources: dict[str, ResourceDict],
+        merged_resource: Optional[ResourceDict],
+    ):
         """
-        self.xmpp.send_message(
-            mto=self.user.jid, mbody=text, mfrom=self.xmpp.boundjid, **msg_kwargs
-        )
+        Called when the gateway component receives a presence, ie, when
+        one of the user's clients goes online of offline, or changes its
+        status.
 
-    async def input(self, text: str, **msg_kwargs):
+        :param resource: The XMPP client identifier, arbitrary string.
+        :param show: The presence ``<show>``, if available. If the resource is
+            just 'available' without any ``<show>`` element, this is an empty
+            str.
+        :param status: A status message, like a deeply profound quote, eg,
+            "Roses are red, violets are blue, [INSERT JOKE]".
+        :param resources: A summary of all the resources for this user.
+        :param merged_resource: A global presence for the user account,
+            following rules described in :meth:`merge_resources`
         """
-        Request user input via direct messages.
+        raise NotImplementedError
 
-        Wraps call to :meth:`.BaseSession.input`
+    presence = deprecated("BaseSession.presence", on_presence)
 
-        :param text: The prompt to send to the user
-        :param msg_kwargs: Extra attributes
-        :return:
+    async def on_search(self, form_values: dict[str, str]) -> Optional[SearchResult]:
         """
-        return await self.xmpp.input(self.user.jid, text, **msg_kwargs)
+        Triggered when the user uses Jabber Search (:xep:`0055`) on the component
 
-    async def send_qr(self, text: str):
+        Form values is a dict in which keys are defined in :attr:`.BaseGateway.SEARCH_FIELDS`
+
+        :param form_values: search query, defined for a specific plugin by overriding
+            in :attr:`.BaseGateway.SEARCH_FIELDS`
+        :return:
         """
-        Sends a QR code generated from 'text' via HTTP Upload and send the URL to
-        ``self.user``
+        raise NotImplementedError
 
-        :param text: Text to encode as a QR code
+    search = deprecated("BaseSession.search", on_search)
+
+    async def on_avatar(
+        self,
+        bytes_: Optional[bytes],
+        hash_: Optional[str],
+        type_: Optional[str],
+        width: Optional[int],
+        height: Optional[int],
+    ) -> None:
+        """
+        Triggered when the user uses modifies their avatar via :xep:`0084`.
+
+        :param bytes_: The data of the avatar. According to the spec, this
+            should always be a PNG, but some implementations do not respect
+            that. If `None` it means the user has unpublished their avatar.
+        :param hash_: The SHA1 hash of the avatar data. This is an identifier of
+            the avatar.
+        :param type_: The MIME type of the avatar.
+        :param width: The width of the avatar image.
+        :param height: The height of the avatar image.
         """
-        await self.xmpp.send_qr(text, mto=self.user.jid)
+        raise NotImplementedError
 
-    async def login(self) -> Optional[str]:
+    async def on_moderate(
+        self, muc: LegacyMUC, legacy_msg_id: LegacyMessageType, reason: Optional[str]
+    ):
         """
-        Login the gateway user to the legacy network.
+        Triggered when the user attempts to retract a message that was sent in
+        a MUC using :xep:`0425`.
 
-        Triggered when the gateway start and on user registration.
-        It is recommended that this function returns once the user is logged in,
-        so if you need to await forever (for instance to listen to incoming events),
-        it's a good idea to wrap your listener in an asyncio.Task.
+        If retraction is not possible, this should raise the appropriate
+        XMPPError with a human-readable message.
 
-        :return: Optionally, a text to use as the gateway status, e.g., "Connected as 'dude@legacy.network'"
+        NB: the legacy module is responsible for calling
+        :method:`LegacyParticipant.moderate` when this is successful, because
+        slidge will acknowledge the moderation IQ, but will not send the
+        moderation message from the MUC automatically.
+
+        :param muc: The MUC in which the message was sent
+        :param legacy_msg_id: The legacy ID of the message to be retracted
+        :param reason: Optionally, a reason for the moderation, given by the
+            user-moderator.
         """
         raise NotImplementedError
 
-    async def logout(self):
+    async def on_create_group(
+        self, name: str, contacts: list[LegacyContact]
+    ) -> LegacyGroupIdType:
         """
-        Logout the gateway user from the legacy network.
+        Triggered when the user request the creation of a group via the
+        dedicated :term:`Command`.
 
-        Called on user unregistration and gateway shutdown.
+        :param name: Name of the group
+        :param contacts: list of contacts that should be members of the group
         """
         raise NotImplementedError
 
-    def re_login(self):
+    async def on_invitation(
+        self, contact: LegacyContact, muc: LegacyMUC, reason: Optional[str]
+    ):
         """
-        Logout then re-login
+        Triggered when the user invites a :term:`Contact` to a legacy MUC via
+        :xep:`0249`.
 
-        No reason to override this
-        """
-        self.xmpp.re_login(self)
+        The default implementation calls :meth:`LegacyMUC.on_set_affiliation`
+        with the 'member' affiliation. Override if you want to customize this
+        behaviour.
 
-    async def send_text(
-        self,
-        text: str,
-        chat: Chat,
-        *,
-        reply_to_msg_id: Optional[LegacyMessageType] = None,
-        reply_to_fallback_text: Optional[str] = None,
-        reply_to: Optional[Union["LegacyContactType", "LegacyParticipantType"]] = None,
-    ) -> Optional[LegacyMessageType]:
+        :param contact: The invitee
+        :param muc: The group
+        :param reason: Optionally, a reason
         """
-        Triggered when the user sends a text message from XMPP to a bridged entity, e.g.
-        to ``translated_user_name@slidge.example.com``, or ``translated_group_name@slidge.example.com``
+        await muc.on_set_affiliation(contact, "member", reason, None)
 
-        Override this and implement sending a message to the legacy network in this method.
+    def __reset_ready(self):
+        self.ready = self.xmpp.loop.create_future()
 
-        :param text: Content of the message
-        :param chat: Recipient of the message. :class:`.LegacyContact` instance for 1:1 chat,
-            :class:`.MUC` instance for groups.
-        :param reply_to_msg_id: A legacy message ID if the message references (quotes)
-            another message (:xep:`0461`)
-        :param reply_to_fallback_text: Content of the quoted text. Not necessarily set
-            by XMPP clients
-        :param reply_to: Author of the quoted message. :class:`LegacyContact` instance for
-            1:1 chat, :class:`LegacyParticipant` instance for groups.
+    @property
+    def logged(self):
+        return self._logged
 
-        :return: An ID of some sort that can be used later to ack and mark the message
-            as read by the user
-        """
-        raise NotImplementedError
+    @logged.setter
+    def logged(self, v: bool):
+        self._logged = v
+        if self.ready.done():
+            if v:
+                return
+            self.__reset_ready()
+        else:
+            if v:
+                self.ready.set_result(True)
 
-    async def send_file(
-        self,
-        url: str,
-        chat: Chat,
-        *,
-        reply_to_msg_id: Optional[LegacyMessageType] = None,
-        reply_to_fallback_text: Optional[str] = None,
-        reply_to: Optional[Union[LegacyContactType, "LegacyParticipantType"]] = None,
-    ) -> Optional[LegacyMessageType]:
-        """
-        Triggered when the user has sends a file using HTTP Upload (:xep:`0363`)
+    def __repr__(self):
+        return f"<Session of {self.user}>"
 
-        :param url: URL of the file
-        :param chat: See :meth:`.BaseSession.send_text`
-        :param reply_to_msg_id: See :meth:`.BaseSession.send_text`
-        :param reply_to_fallback_text: See :meth:`.BaseSession.send_text`
-        :param reply_to: See :meth:`.BaseSession.send_text`
+    def shutdown(self) -> asyncio.Task:
+        for c in self.contacts:
+            c.offline()
+        for m in self.bookmarks:
+            m.shutdown()
+        return self.xmpp.loop.create_task(self.logout())
 
-        :return: An ID of some sort that can be used later to ack and mark the message
-            as read by the user
+    @staticmethod
+    def legacy_to_xmpp_msg_id(legacy_msg_id: LegacyMessageType) -> str:
         """
-        raise NotImplementedError
+        Convert a legacy msg ID to a valid XMPP msg ID.
+        Needed for read marks, retractions and message corrections.
 
-    async def active(self, c: Chat):
-        """
-        Triggered when the user sends an 'active' chat state to the legacy network (:xep:`0085`)
+        The default implementation just converts the legacy ID to a :class:`str`,
+        but this should be overridden in case some characters needs to be escaped,
+        or to add some additional,
+        :term:`legacy network <Legacy Network`>-specific logic.
 
-        :param c: Recipient of the active chat state
+        :param legacy_msg_id:
+        :return: A string that is usable as an XMPP stanza ID
         """
-        raise NotImplementedError
+        return str(legacy_msg_id)
 
-    async def inactive(self, c: Chat):
-        """
-        Triggered when the user sends an 'inactive' chat state to the legacy network (:xep:`0085`)
+    legacy_msg_id_to_xmpp_msg_id = staticmethod(
+        deprecated("BaseSession.legacy_msg_id_to_xmpp_msg_id", legacy_to_xmpp_msg_id)
+    )
 
-        :param c:
+    @staticmethod
+    def xmpp_to_legacy_msg_id(i: str) -> LegacyMessageType:
         """
-        raise NotImplementedError
+        Convert a legacy XMPP ID to a valid XMPP msg ID.
+        Needed for read marks and message corrections.
 
-    async def composing(self, c: Chat):
-        """
-        Triggered when the user starts typing in the window of a legacy contact (:xep:`0085`)
+        The default implementation just converts the legacy ID to a :class:`str`,
+        but this should be overridden in case some characters needs to be escaped,
+        or to add some additional,
+        :term:`legacy network <Legacy Network`>-specific logic.
 
-        :param c:
-        """
-        raise NotImplementedError
+        The default implementation is an identity function.
 
-    async def paused(self, c: Chat):
+        :param i: The XMPP stanza ID
+        :return: An ID that can be used to identify a message on the legacy network
         """
-        Triggered when the user pauses typing in the window of a legacy contact (:xep:`0085`)
+        return cast(LegacyMessageType, i)
 
-        :param c:
+    xmpp_msg_id_to_legacy_msg_id = staticmethod(
+        deprecated("BaseSession.xmpp_msg_id_to_legacy_msg_id", xmpp_to_legacy_msg_id)
+    )
+
+    def raise_if_not_logged(self):
+        if not self.logged:
+            raise XMPPError(
+                "internal-server-error",
+                text="You are not logged to the legacy network",
+            )
+
+    @classmethod
+    def _from_user_or_none(cls, user):
+        if user is None:
+            log.debug("user not found", stack_info=True)
+            raise XMPPError(text="User not found", condition="subscription-required")
+
+        session = _sessions.get(user)
+        if session is None:
+            _sessions[user] = session = cls(user)
+        return session
+
+    @classmethod
+    def from_user(cls, user):
+        return cls._from_user_or_none(user)
+
+    @classmethod
+    def from_stanza(cls, s) -> "BaseSession":
+        # """
+        # Get a user's :class:`.LegacySession` using the "from" field of a stanza
+        #
+        # Meant to be called from :class:`BaseGateway` only.
+        #
+        # :param s:
+        # :return:
+        # """
+        return cls._from_user_or_none(user_store.get_by_stanza(s))
+
+    @classmethod
+    def from_jid(cls, jid: JID) -> "BaseSession":
+        # """
+        # Get a user's :class:`.LegacySession` using its jid
+        #
+        # Meant to be called from :class:`BaseGateway` only.
+        #
+        # :param jid:
+        # :return:
+        # """
+        return cls._from_user_or_none(user_store.get_by_jid(jid))
+
+    @classmethod
+    async def kill_by_jid(cls, jid: JID):
+        # """
+        # Terminate a user session.
+        #
+        # Meant to be called from :class:`BaseGateway` only.
+        #
+        # :param jid:
+        # :return:
+        # """
+        log.debug("Killing session of %s", jid)
+        for user, session in _sessions.items():
+            if user.jid == jid.bare:
+                break
+        else:
+            log.debug("Did not find a session for %s", jid)
+            return
+        for c in session.contacts:
+            c.unsubscribe()
+        await cls.xmpp.unregister(user)
+        del _sessions[user]
+        del user
+        del session
+
+    def __ack(self, msg: Message):
+        if not self.xmpp.PROPER_RECEIPTS:
+            self.xmpp.delivery_receipt.ack(msg)
+
+    def send_gateway_status(
+        self,
+        status: Optional[str] = None,
+        show=Optional[PresenceShows],
+        **kwargs,
+    ):
         """
-        raise NotImplementedError
+        Send a presence from the gateway to the user.
 
-    async def displayed(self, legacy_msg_id: LegacyMessageType, c: Chat):
+        Can be used to indicate the user session status, ie "SMS code required", "connected", …
+
+        :param status: A status message
+        :param show: Presence stanza 'show' element. I suggest using "dnd" to show
+            that the gateway is not fully functional
         """
-        Triggered when the user reads a message sent by a legacy contact.  (:xep:`0333`)
+        self.__cached_presence = CachedPresence(status, show, kwargs)
+        self.xmpp.send_presence(
+            pto=self.user.bare_jid, pstatus=status, pshow=show, **kwargs
+        )
 
-        This is only possible if a valid ``legacy_msg_id`` was passed when transmitting a message
-        from a contact to the user in :meth:`.LegacyContact.sent_text` or :meth:`slidge.LegacyContact.send_file`.
+    def send_cached_presence(self, to: JID):
+        if not self.__cached_presence:
+            self.xmpp.send_presence(pto=to, ptype="unavailable")
+            return
+        self.xmpp.send_presence(
+            pto=to,
+            pstatus=self.__cached_presence.status,
+            pshow=self.__cached_presence.show,
+            **self.__cached_presence.kwargs,
+        )
 
-        :param legacy_msg_id: Identifier of the message, passed to :meth:`slidge.LegacyContact.send_text`
-            or :meth:`slidge.LegacyContact.send_file`
-        :param c:
+    def send_gateway_message(self, text: str, **msg_kwargs):
         """
-        raise NotImplementedError
+        Send a message from the gateway component to the user.
 
-    async def correct(
-        self, text: str, legacy_msg_id: LegacyMessageType, c: Chat
-    ) -> Optional[LegacyMessageType]:
+        Can be used to indicate the user session status, ie "SMS code required", "connected", …
+
+        :param text: A text
         """
-        Triggered when the user corrected a message using :xep:`0308`
+        self.xmpp.send_text(text, mto=self.user.jid, **msg_kwargs)
 
-        This is only possible if a valid ``legacy_msg_id`` was passed when transmitting a message
-        from a contact to the user in :meth:`.LegacyContact.send_text` or :meth:`slidge.LegacyContact.send_file`.
+    def send_gateway_invite(
+        self,
+        muc: LegacyMUC,
+        reason: Optional[str] = None,
+        password: Optional[str] = None,
+    ):
+        """
+        Send an invitation to join a MUC, emanating from the gateway component.
 
-        :param text:
-        :param legacy_msg_id:
-        :param c:
+        :param muc:
+        :param reason:
+        :param password:
         """
-        raise NotImplementedError
+        self.xmpp.invite_to(muc, reason=reason, password=password, mto=self.user.jid)
 
-    async def search(self, form_values: dict[str, str]) -> Optional["SearchResult"]:
+    async def input(self, text: str, **msg_kwargs):
         """
-        Triggered when the user uses Jabber Search (:xep:`0055`) on the component
+        Request user input via direct messages from the gateway component.
 
-        Form values is a dict in which keys are defined in :attr:`.BaseGateway.SEARCH_FIELDS`
+        Wraps call to :meth:`.BaseSession.input`
 
-        :param form_values: search query, defined for a specific plugin by overriding
-            in :attr:`.BaseGateway.SEARCH_FIELDS`
+        :param text: The prompt to send to the user
+        :param msg_kwargs: Extra attributes
         :return:
         """
-        raise NotImplementedError
+        return await self.xmpp.input(self.user.jid, text, **msg_kwargs)
 
-    async def react(self, legacy_msg_id: LegacyMessageType, emojis: list[str], c: Chat):
+    async def send_qr(self, text: str):
         """
-        Triggered when the user sends message reactions (:xep:`0444`).
+        Sends a QR code generated from 'text' via HTTP Upload and send the URL to
+        ``self.user``
 
-        :param legacy_msg_id: ID of the message the user reacts to
-        :param emojis: Unicode characters representing reactions to the message ``legacy_msg_id``.
-            An empty string means "no reaction", ie, remove all reactions if any were present before
-        :param c: Contact or MUC the reaction refers to
+        :param text: Text to encode as a QR code
         """
-        raise NotImplementedError
+        await self.xmpp.send_qr(text, mto=self.user.jid)
 
-    async def retract(self, legacy_msg_id: LegacyMessageType, c: Chat):
-        """
-        Triggered when the user retracts (:xep:`0424`) a message.
+    def re_login(self):
+        # Logout then re-login
+        #
+        # No reason to override this
+        self.xmpp.re_login(self)
 
-        :param legacy_msg_id: Legacy ID of the retracted message
-        :param c: The contact this retraction refers to
-        """
-        raise NotImplementedError
+    async def get_contact_or_group_or_participant(self, jid: JID):
+        if jid.bare in (contacts := self.contacts.known_contacts(only_friends=False)):
+            return contacts[jid.bare]
+        if jid.bare in (mucs := self.bookmarks._mucs_by_bare_jid):
+            return await self.__get_muc_or_participant(mucs[jid.bare], jid)
+        else:
+            muc = None
 
+        try:
+            return await self.contacts.by_jid(jid)
+        except XMPPError:
+            if muc is None:
+                try:
+                    muc = await self.bookmarks.by_jid(jid)
+                except XMPPError:
+                    return
+            return await self.__get_muc_or_participant(muc, jid)
 
-def remove_emoji_variation_selector_16(emoji: str):
-    # this is required for compatibility with dino, and maybe other future clients?
-    return bytes(emoji, encoding="utf-8").replace(b"\xef\xb8\x8f", b"").decode()
+    @staticmethod
+    async def __get_muc_or_participant(muc: LegacyMUC, jid: JID):
+        if nick := jid.resource:
+            try:
+                return await muc.get_participant(
+                    nick, raise_if_not_found=True, fill_first=True
+                )
+            except XMPPError:
+                return None
+        return muc
+
+    async def wait_for_ready(self, timeout: Optional[Union[int, float]] = 10):
+        # """
+        # Wait until session, contacts and bookmarks are ready
+        #
+        # (slidge internal use)
+        #
+        # :param timeout:
+        # :return:
+        # """
+        try:
+            await asyncio.wait_for(asyncio.shield(self.ready), timeout)
+            await asyncio.wait_for(asyncio.shield(self.contacts.ready), timeout)
+            await asyncio.wait_for(asyncio.shield(self.bookmarks.ready), timeout)
+        except asyncio.TimeoutError:
+            raise XMPPError(
+                "recipient-unavailable",
+                "Legacy session is not fully initialized, retry later",
+            )
 
 
 _sessions: dict[GatewayUser, BaseSession] = {}