matridge.gateway
================

.. py:module:: matridge.gateway


Attributes
----------

.. autoapisummary::

   matridge.gateway.log


Classes
-------

.. autoapisummary::

   matridge.gateway.Gateway


Module Contents
---------------

.. py:class:: Gateway

   Bases: :py:obj:`slidge.BaseGateway`


   The gateway component, handling registrations and un-registrations.

   On slidge launch, a singleton is instantiated, and it will be made available
   to public classes such :class:`.LegacyContact` or :class:`.BaseSession` as the
   ``.xmpp`` attribute.

   Must be subclassed by a legacy module to set up various aspects of the XMPP
   component behaviour, such as its display name or welcome message, via
   class attributes :attr:`.COMPONENT_NAME` :attr:`.WELCOME_MESSAGE`.

   Abstract methods related to the registration process must be overriden
   for a functional :term:`Legacy Module`:

   - :meth:`.validate`
   - :meth:`.validate_two_factor_code`
   - :meth:`.get_qr_text`
   - :meth:`.confirm_qr`

   NB: Not all of these must be overridden, it depends on the
   :attr:`REGISTRATION_TYPE`.

   The other methods, such as :meth:`.send_text` or :meth:`.react` are the same
   as those of :class:`.LegacyContact` and :class:`.LegacyParticipant`, because
   the component itself is also a "messaging actor", ie, an :term:`XMPP Entity`.
   For these methods, you need to specify the JID of the recipient with the
   `mto` parameter.

   Since it inherits from :class:`slixmpp.componentxmpp.ComponentXMPP`,you also
   have a hand on low-level XMPP interactions via slixmpp methods, e.g.:

   .. code-block:: python

       self.send_presence(
           pfrom="somebody@component.example.com",
           pto="someonwelse@anotherexample.com",
       )

   However, you should not need to do so often since the classes of the plugin
   API provides higher level abstractions around most commonly needed use-cases, such
   as sending messages, or displaying a custom status.



   .. py:attribute:: REGISTRATION_FIELDS

      Iterable of fields presented to the gateway user when registering using :xep:`0077`
      `extended <https://xmpp.org/extensions/xep-0077.html#extensibility>`_ by :xep:`0004`.



   .. py:attribute:: REGISTRATION_INSTRUCTIONS
      :type:  str
      :value: 'Enter your credentials'


      The text presented to a user that wants to register (or modify) their legacy account
      configuration.



   .. py:attribute:: COMPONENT_NAME
      :value: 'Matrix (slidge)'


      Name of the component, as seen in service discovery by XMPP clients



   .. py:attribute:: COMPONENT_TYPE
      :value: 'matrix'


      Type of the gateway, should follow https://xmpp.org/registrar/disco-categories.html



   .. py:attribute:: COMPONENT_AVATAR
      :value: 'https://upload.wikimedia.org/wikipedia/commons/thumb/7/7c/Matrix_icon.svg/209px-Matrix_icon.svg.png'


      Path, bytes or URL used by the component as an avatar.



   .. py:attribute:: ROSTER_GROUP
      :type:  str
      :value: 'matrix'


      Name of the group assigned to a :class:`.LegacyContact` automagically
      added to the :term:`User`'s roster with :meth:`.LegacyContact.add_to_roster`.



   .. py:attribute:: MARK_ALL_MESSAGES
      :value: False


      Set this to True for :term:`legacy networks <Legacy Network>` that expects
      read marks for *all* messages and not just the latest one that was read
      (as most XMPP clients will only send a read mark for the latest msg).



   .. py:attribute:: PROPER_RECEIPTS
      :value: True


      Set this to True if the legacy service provides a real equivalent of message delivery receipts
      (:xep:`0184`), meaning that there is an event thrown when the actual device of a contact receives
      a message. Make sure to call Contact.received() adequately if this is set to True.



   .. py:attribute:: GROUPS
      :value: True



   .. py:method:: validate(user_jid, registration_form)
      :async:


      Validate a user's initial registration form.

      Should raise the appropriate :class:`slixmpp.exceptions.XMPPError`
      if the registration does not allow to continue the registration process.

      If :py:attr:`REGISTRATION_TYPE` is a
      :attr:`.RegistrationType.SINGLE_STEP_FORM`,
      this method should raise something if it wasn't possible to successfully
      log in to the legacy service with the registration form content.

      It is also used for other types of :py:attr:`REGISTRATION_TYPE` too, since
      the first step is always a form. If :attr:`.REGISTRATION_FIELDS` is an
      empty list (ie, it declares no :class:`.FormField`), the "form" is
      effectively a confirmation dialog displaying
      :attr:`.REGISTRATION_INSTRUCTIONS`.

      :param user_jid: JID of the user that has just registered
      :param registration_form: A dict where keys are the :attr:`.FormField.var` attributes
          of the :attr:`.BaseGateway.REGISTRATION_FIELDS` iterable.
          This dict can be modified and will be accessible as the ``legacy_module_data``
          of the

      :return : A dict that will be stored as the persistent "legacy_module_data"
          for this user. If you don't return anything here, the whole registration_form
          content will be stored.



   .. py:method:: unregister(user)
      :async:


      Optionally override this if you need to clean additional
      stuff after a user has been removed from the persistent user store.

      By default, this just calls :meth:`BaseSession.logout`.

      :param user:



.. py:data:: log

