slidge 0.1.0b2__py3-none-any.whl → 0.1.1__py3-none-any.whl

slidge/core/session.py

@@ -1,55 +1,66 @@
-import functools
+import asyncio
 import logging
-from typing import TYPE_CHECKING, Any, Generic, Literal, Optional, Type, TypeVar
-
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Generic,
+    Iterable,
+    NamedTuple,
+    Optional,
+    Union,
+    cast,
+)
+
+import aiohttp
 from slixmpp import JID, Message
 from slixmpp.exceptions import XMPPError
+from slixmpp.types import PresenceShows
 
-from ..core.contact import LegacyContactType, LegacyRoster, LegacyRosterType
-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.types import LegacyMessageType
+from ..util.sql import SQLBiDict
+from ..util.types import (
+    LegacyGroupIdType,
+    LegacyMessageType,
+    LegacyThreadType,
+    LinkPreview,
+    Mention,
+    PseudoPresenceShow,
+    RecipientType,
+    ResourceDict,
+)
+from ..util.util import deprecated
 
 if TYPE_CHECKING:
-    from slidge import SearchResult
-    from slidge.core.gateway import GatewayType
-else:
-    GatewayType = TypeVar("GatewayType")
-
-
-def ignore_message_to_component_and_sent_carbons(func):
-    @functools.wraps(func)
-    async def wrapped(self: T, msg: Message):
-        if msg.get_to() != self.xmpp.boundjid.bare:
-            if (i := msg.get_id()) in self.ignore_messages:
-                self.log.debug("Ignored message: %s", i)
-                self.ignore_messages.remove(i)
-            else:
-                log.debug("FUNC: %s", func)
-                return await func(self, msg)
-        else:
-            log.debug("Ignoring message to component: %s %s", self, msg)
-
-    return wrapped
+    from ..group.participant import LegacyParticipant
+    from ..util.types import Sender
+    from .gateway import BaseGateway
 
 
-T = TypeVar("T", bound="BaseSession")
+class CachedPresence(NamedTuple):
+    status: Optional[str]
+    show: Optional[str]
+    kwargs: dict[str, Any]
 
 
 class BaseSession(
-    Generic[LegacyContactType, LegacyRosterType, GatewayType],
-    metaclass=ABCSubclassableOnceAtMost,
+    Generic[LegacyMessageType, RecipientType], metaclass=ABCSubclassableOnceAtMost
 ):
     """
-    Represents a gateway user logged in to the network and performing actions.
+    The session of a registered :term:`User`.
 
-    Will be instantiated automatically when a user sends an online presence to the gateway
-    component, as per :xep:`0100`.
+    Represents a gateway user logged in to the legacy network and performing actions.
 
-    Must be subclassed for a functional slidge plugin.
+    Will be instantiated automatically on slidge startup for each registered user,
+    or upon registration for new (validated) users.
+
+    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
@@ -57,489 +68,701 @@ 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
-        ] = BiDict()  # 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 = 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.post_init()
+        self.contacts: LegacyRoster = LegacyRoster.get_self_or_unique_subclass()(self)
+        self._logged = False
+        self.__reset_ready()
 
-    @staticmethod
-    def legacy_msg_id_to_xmpp_msg_id(legacy_msg_id: Any) -> str:
-        """
-        Convert a legacy msg ID to a valid XMPP msg ID.
-        Needed for read marks and message corrections.
-
-        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.bookmarks: LegacyBookmarks = LegacyBookmarks.get_self_or_unique_subclass()(
+            self
+        )
 
-        :param legacy_msg_id:
-        :return: Should return a string that is usable as an XMPP stanza ID
-        """
-        return str(legacy_msg_id)
+        self.http = self.xmpp.http
 
-    @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.threads = SQLBiDict[str, LegacyThreadType](  # type:ignore
+            "session_thread_sent_muc", "legacy_id", "xmpp_id", self.user
+        )
+        self.thread_creation_lock = asyncio.Lock()
 
-        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.__cached_presence: Optional[CachedPresence] = None
 
-        The default implementation is an identity function
+        self.avatar_hash: Optional[str] = None
 
-        :param i: The XMPP stanza ID
-        :return: An ID that can be used to identify a message on the legacy network
-        """
-        return i
+        self.__tasks = set[asyncio.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 __remove_task(self, fut):
+        self.log.debug("Removing fut %s", fut)
+        self.__tasks.remove(fut)
 
-        session = _sessions.get(user)
-        if session is None:
-            _sessions[user] = session = cls(user)
-        return session
+    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(cls, user):
-        return cls._from_user_or_none(user)
+    def cancel_all_tasks(self):
+        for task in self.__tasks:
+            task.cancel()
 
-    @classmethod
-    def from_stanza(cls: Type[T], s) -> T:
+    async def login(self) -> Optional[str]:
         """
-        Get a user's :class:`.LegacySession` using the "from" field of a stanza
+        Logs in the gateway user to the legacy network.
 
-        Meant to be called from :class:`BaseGateway` only.
+        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.
 
-        :param s:
-        :return:
+        :return: Optionally, a text to use as the gateway status, e.g., "Connected as 'dude@legacy.network'"
         """
-        return cls._from_user_or_none(user_store.get_by_stanza(s))
+        raise NotImplementedError
 
-    @classmethod
-    def from_jid(cls: Type[T], jid: JID) -> T:
+    async def logout(self):
         """
-        Get a user's :class:`.LegacySession` using its jid
+        Logs out the gateway user from the legacy network.
 
-        Meant to be called from :class:`BaseGateway` only.
-
-        :param jid:
-        :return:
+        Called on gateway shutdown.
         """
-        return cls._from_user_or_none(user_store.get_by_jid(jid))
+        raise NotImplementedError
 
-    @classmethod
-    async def kill_by_jid(cls, jid: JID):
+    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]:
         """
-        Terminate a user session.
+        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:
-        """
-        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
+        :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:
 
-    @ignore_message_to_component_and_sent_carbons
-    async def send_from_msg(self, m: Message):
+        :return: An ID of some sort that can be used later to ack and mark the message
+            as read by the user
         """
-        Meant to be called from :class:`BaseGateway` only.
+        raise NotImplementedError
 
-        :param m:
-        :return:
+    send_text = deprecated("BaseSession.send_text", on_text)
+
+    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]:
         """
-        if m["replace"]["id"] or m["apply_to"]["id"]:
-            # ignore last message correction and retraction (handled by a specific method)
-            return
+        Triggered when the user sends a file using HTTP Upload (:xep:`0363`)
 
-        contact: LegacyContactType = self.contacts.by_stanza(m)
+        :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:
 
-        url = m["oob"]["url"]
-        text = m["body"]
-        if (
-            m["feature_fallback"]["for"] == self.xmpp["xep_0461"].namespace
-            and contact.REPLIES
-        ):
-            text = m["feature_fallback"].get_stripped_body()
+        :return: An ID of some sort that can be used later to ack and mark the message
+            as read by the user
+        """
+        raise NotImplementedError
 
-        if url:
-            legacy_msg_id = await self.send_file(
-                url, contact, reply_to_msg_id=m["reply"]["id"] or None
-            )
-        elif text:
-            legacy_msg_id = await self.send_text(
-                text, contact, reply_to_msg_id=m["reply"]["id"] or None
-            )
-        else:
-            log.debug("Ignoring %s", m)
-            return
-        if legacy_msg_id is not None:
-            self.sent[legacy_msg_id] = m.get_id()
+    send_file = deprecated("BaseSession.send_file", on_file)
 
-    @ignore_message_to_component_and_sent_carbons
-    async def active_from_msg(self, m: Message):
+    async def on_active(
+        self, chat: RecipientType, thread: Optional[LegacyThreadType] = None
+    ):
         """
-        Meant to be called from :class:`BaseGateway` only.
+        Triggered when the user sends an 'active' chat state (:xep:`0085`)
 
-        :param m:
-        :return:
+        :param chat: See :meth:`.BaseSession.on_text`
+        :param thread:
         """
-        if m.get_to() != self.xmpp.boundjid.bare:
-            await self.active(self.contacts.by_stanza(m))
+        raise NotImplementedError
 
-    @ignore_message_to_component_and_sent_carbons
-    async def inactive_from_msg(self, m: Message):
-        """
-        Meant to be called from :class:`BaseGateway` only.
+    active = deprecated("BaseSession.active", on_active)
 
-        :param m:
-        :return:
+    async def on_inactive(
+        self, chat: RecipientType, thread: Optional[LegacyThreadType] = None
+    ):
         """
-        if m.get_to() != self.xmpp.boundjid.bare:
-            await self.inactive(self.contacts.by_stanza(m))
+        Triggered when the user sends an 'inactive' chat state (:xep:`0085`)
 
-    @ignore_message_to_component_and_sent_carbons
-    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:
-        """
-        if m.get_to() != self.xmpp.boundjid.bare:
-            log.debug("COMPOSING: %s", self.contacts.by_stanza(m))
-            await self.composing(self.contacts.by_stanza(m))
+    inactive = deprecated("BaseSession.inactive", on_inactive)
 
-    @ignore_message_to_component_and_sent_carbons
-    async def paused_from_msg(self, m: Message):
+    async def on_composing(
+        self, chat: RecipientType, thread: Optional[LegacyThreadType] = None
+    ):
         """
-        Meant to be called from :class:`BaseGateway` only.
+        Triggered when the user starts typing in a legacy chat (:xep:`0085`)
 
-        :param m:
-        :return:
+        :param chat: See :meth:`.BaseSession.on_text`
+        :param thread:
         """
-        if m.get_to() != self.xmpp.boundjid.bare:
-            await self.paused(self.contacts.by_stanza(m))
+        raise NotImplementedError
 
-    @ignore_message_to_component_and_sent_carbons
-    async def displayed_from_msg(self, m: Message):
-        """
-        Meant to be called from :class:`BaseGateway` only.
+    composing = deprecated("BaseSession.composing", on_composing)
 
-        :param m:
-        :return:
+    async def on_paused(
+        self, chat: RecipientType, thread: Optional[LegacyThreadType] = None
+    ):
         """
-        displayed_msg_id = m["displayed"]["id"]
-        try:
-            legacy_msg_id = self.xmpp_msg_id_to_legacy_msg_id(displayed_msg_id)
-        except NotImplementedError:
-            log.debug("Couldn't convert xmpp msg ID to legacy ID, ignoring read mark")
-            return
+        Triggered when the user pauses typing in a legacy chat (:xep:`0085`)
 
-        await self.displayed(legacy_msg_id, self.contacts.by_stanza(m))
-
-    @ignore_message_to_component_and_sent_carbons
-    async def correct_from_msg(self, m: Message):
-        xmpp_id = m["replace"]["id"]
-        legacy_id = self.sent.inverse.get(xmpp_id)
-        if legacy_id is None:
-            log.debug("Did not find legacy ID to correct")
-            new_legacy_msg_id = await self.send_text(
-                m["body"], self.contacts.by_stanza(m)
-            )
-        else:
-            new_legacy_msg_id = await self.correct(
-                m["body"], legacy_id, self.contacts.by_stanza(m)
-            )
-        if new_legacy_msg_id is not None:
-            self.sent[new_legacy_msg_id] = m.get_id()
-
-    @ignore_message_to_component_and_sent_carbons
-    async def react_from_msg(self, m: Message):
-        react_to = m["reactions"]["id"]
-        if (legacy_id := self.sent.inverse.get(react_to)) is None:
-            log.debug("Cannot find the XMPP ID of this msg: %s", react_to)
-            try:
-                legacy_id = self.xmpp_msg_id_to_legacy_msg_id(react_to)
-            except ValueError:
-                log.warning(
-                    "Could not convert legacy ID, xmpp reaction was not sent: %s", m
-                )
-                return
-        await self.react(
-            legacy_id, [r["value"] for r in m["reactions"]], self.contacts.by_stanza(m)
-        )
+        :param chat: See :meth:`.BaseSession.on_text`
+        :param thread:
+        """
+        raise NotImplementedError
 
-    @ignore_message_to_component_and_sent_carbons
-    async def retract_from_msg(self, m: Message):
-        xmpp_id = m["apply_to"]["id"]
-        if (legacy_id := self.sent.inverse.get(xmpp_id)) is None:
-            log.debug(
-                "Cannot find the XMPP ID of this msg: %s, cannot retract", xmpp_id
-            )
-            return
-        await self.retract(legacy_id, self.contacts.by_stanza(m))
+    paused = deprecated("BaseSession.paused", on_paused)
 
-    def send_gateway_status(
+    async def on_displayed(
         self,
-        status: Optional[str] = None,
-        show=Optional[Literal["away", "chat", "dnd", "xa"]],
-        **kwargs,
+        chat: RecipientType,
+        legacy_msg_id: LegacyMessageType,
+        thread: Optional[LegacyThreadType] = None,
     ):
         """
-        Send a presence from the gateway to the user.
+        Triggered when the user reads a message in a legacy chat. (:xep:`0333`)
 
-        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
-        """
-        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 legacy chat to the user, eg in
+        :meth:`slidge.contact.LegacyContact.send_text`
+        or
+        :meth:`slidge.group.LegacyParticipant.send_text`.
 
-    def send_gateway_message(self, text, **msg_kwargs):
+        :param chat: See :meth:`.BaseSession.on_text`
+        :param legacy_msg_id: Identifier of the message/
+        :param thread:
         """
-        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", …
+    displayed = deprecated("BaseSession.displayed", on_displayed)
 
-        :param text: A text
+    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]:
         """
-        self.xmpp.send_message(
-            mto=self.user.jid, mbody=text, mfrom=self.xmpp.boundjid, **msg_kwargs
-        )
+        Triggered when the user corrects a message using :xep:`0308`
 
-    async def input(self, text: str, **msg_kwargs):
+        This is only possible if a valid ``legacy_msg_id`` was returned by
+        :meth:`.on_text`.
+
+        :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.
         """
-        Request user input via direct messages.
+        raise NotImplementedError
 
-        Wraps call to :meth:`.BaseSession.input`
+    correct = deprecated("BaseSession.correct", on_correct)
 
-        :param text: The prompt to send to the user
-        :param msg_kwargs: Extra attributes
-        :return:
+    async def on_react(
+        self,
+        chat: RecipientType,
+        legacy_msg_id: LegacyMessageType,
+        emojis: list[str],
+        thread: Optional[LegacyThreadType] = None,
+    ):
         """
-        return await self.xmpp.input(self.user.jid, text, **msg_kwargs)
+        Triggered when the user sends message reactions (:xep:`0444`).
 
-    async def send_qr(self, text: str):
+        :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
         """
-        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
-        """
-        await self.xmpp.send_qr(text, mto=self.user.jid)
+    react = deprecated("BaseSession.react", on_react)
 
-    def post_init(self):
+    async def on_retract(
+        self,
+        chat: RecipientType,
+        legacy_msg_id: LegacyMessageType,
+        thread: Optional[LegacyThreadType] = None,
+    ):
         """
-        Add useful attributes for your session here, if you wish.
+        Triggered when the user retracts (:xep:`0424`) a message.
 
-        In most cases, this is the right place to add a legacy network-specific
-        ``LegacyClient``-like instance attached to this gateway user.
+        :param chat: See :meth:`.BaseSession.on_text`
+        :param thread:
+        :param legacy_msg_id: Legacy ID of the retracted message
         """
-        pass
+        raise NotImplementedError
 
-    async def login(self) -> Optional[str]:
-        """
-        Login the gateway user to the legacy network.
+    retract = deprecated("BaseSession.retract", on_retract)
 
-        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.
+    async def on_presence(
+        self,
+        resource: str,
+        show: PseudoPresenceShow,
+        status: str,
+        resources: dict[str, ResourceDict],
+        merged_resource: Optional[ResourceDict],
+    ):
+        """
+        Called when the gateway component receives a presence, ie, when
+        one of the user's clients goes online of offline, or changes its
+        status.
 
-        :return: Optionally, a text to use as the gateway status, e.g., "Connected as 'dude@legacy.network'"
+        :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`
         """
         raise NotImplementedError
 
-    async def logout(self):
+    presence = deprecated("BaseSession.presence", on_presence)
+
+    async def on_search(self, form_values: dict[str, str]) -> Optional[SearchResult]:
         """
-        Logout the gateway user from the legacy network.
+        Triggered when the user uses Jabber Search (:xep:`0055`) on the component
 
-        Called on user unregistration and gateway shutdown.
+        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:
         """
         raise NotImplementedError
 
-    def re_login(self):
-        """
-        Logout then re-login
+    search = deprecated("BaseSession.search", on_search)
 
-        No reason to override this
+    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.
         """
-        self.xmpp.re_login(self)
+        raise NotImplementedError
 
-    async def send_text(
-        self,
-        t: str,
-        c: LegacyContactType,
-        *,
-        reply_to_msg_id: Optional[LegacyMessageType] = None,
-    ) -> Optional[LegacyMessageType]:
+    async def on_moderate(
+        self, muc: LegacyMUC, legacy_msg_id: LegacyMessageType, reason: Optional[str]
+    ):
         """
-        Triggered when the user sends a text message from xmpp to a bridged contact, e.g.
-        to ``translated_user_name@slidge.example.com``.
+        Triggered when the user attempts to retract a message that was sent in
+        a MUC using :xep:`0425`.
 
-        Override this and implement sending a message to the legacy network in this method.
+        If retraction is not possible, this should raise the appropriate
+        XMPPError with a human-readable message.
 
-        :param t: Content of the message
-        :param c: Recipient of the message
-        :param reply_to_msg_id:
-        :return: An ID of some sort that can be used later to ack and mark the message
-            as read by the user
+        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 send_file(
-        self,
-        u: str,
-        c: LegacyContactType,
-        *,
-        reply_to_msg_id: Optional[LegacyMessageType] = None,
-    ) -> Optional[LegacyMessageType]:
+    async def on_create_group(
+        self, name: str, contacts: list[LegacyContact]
+    ) -> LegacyGroupIdType:
         """
-        Triggered when the user has sends a file using HTTP Upload (:xep:`0363`)
+        Triggered when the user request the creation of a group via the
+        dedicated :term:`Command`.
 
-        :param u: URL of the file
-        :param c: Recipient of the file
-        :param reply_to_msg_id:
-        :return: An ID of some sort that can be used later to ack and mark the message
-            as read by the user
+        :param name: Name of the group
+        :param contacts: list of contacts that should be members of the group
         """
         raise NotImplementedError
 
-    async def active(self, c: LegacyContactType):
+    async def on_invitation(
+        self, contact: LegacyContact, muc: LegacyMUC, reason: Optional[str]
+    ):
         """
-        Triggered when the user sends an 'active' chat state to the legacy network (:xep:`0085`)
+        Triggered when the user invites a :term:`Contact` to a legacy MUC via
+        :xep:`0249`.
 
-        :param c: Recipient of the active chat state
-        """
-        raise NotImplementedError
+        The default implementation calls :meth:`LegacyMUC.on_set_affiliation`
+        with the 'member' affiliation. Override if you want to customize this
+        behaviour.
 
-    async def inactive(self, c: LegacyContactType):
+        :param contact: The invitee
+        :param muc: The group
+        :param reason: Optionally, a reason
         """
-        Triggered when the user sends an 'inactive' chat state to the legacy network (:xep:`0085`)
+        await muc.on_set_affiliation(contact, "member", reason, None)
 
-        :param c:
+    def __reset_ready(self):
+        self.ready = self.xmpp.loop.create_future()
+
+    @property
+    def logged(self):
+        return self._logged
+
+    @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)
+
+    def __repr__(self):
+        return f"<Session of {self.user}>"
+
+    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())
+
+    @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.
+
+        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.
 
-    async def composing(self, c: LegacyContactType):
+        :param legacy_msg_id:
+        :return: A string that is usable as an XMPP stanza ID
         """
-        Triggered when the user starts typing in the window of a legacy contact (:xep:`0085`)
+        return str(legacy_msg_id)
+
+    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.
+
+        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.
+
+        The default implementation is an identity function.
 
-    async def paused(self, c: LegacyContactType):
+        :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)
+
+    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
 
-        :param c:
+    @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.
+
+        Can be used to indicate the user session status, ie "SMS code required", "connected", …
 
-    async def displayed(self, legacy_msg_id: Any, c: LegacyContactType):
+        :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: Any, c: LegacyContactType
-    ) -> 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]) -> "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: Any, emojis: list[str], c: LegacyContactType):
+    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 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: Any, c: LegacyContactType):
-        """
-        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)
+
+    @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",
+            )
 
-SessionType = TypeVar("SessionType", bound=BaseSession)
 
 _sessions: dict[GatewayUser, BaseSession] = {}
 log = logging.getLogger(__name__)