Mercurial > libervia-backend

comparison doc/components.rst @ 3838:9a53b513ae55

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc (components/AP): Mention: fix 369
author Goffi <goffi@goffi.org>
date Sun, 10 Jul 2022 16:15:44 +0200
parents 23b53ac87e0f
children c2b292d30c66
comparison
equal deleted inserted replaced
3837:56720561f45f 3838:9a53b513ae55
234 **default**: ``_ap`` 234 **default**: ``_ap``
235 235
236 ``comments_max_depth`` 236 ``comments_max_depth``
237 An integer value indicating the maximum number of comment nodes that can be created. See 237 An integer value indicating the maximum number of comment nodes that can be created. See
238 :ref:`ap-xmpp-threads-conversion` 238 :ref:`ap-xmpp-threads-conversion`
239
240 ``auto_mentions``
241 A boolean value indicating if received XMPP pubsub blog items bodies must be scanned to
242 find ``@user@server.tld`` type mentions. If mentions are found, they'll be added to the
243 resulting AP items.
244
245 **default**: ``true``
239 246
240 247
241 .. _ap-actor-from-xmpp: 248 .. _ap-actor-from-xmpp:
242 249
243 How to Address an AP Actor from XMPP 250 How to Address an AP Actor from XMPP
587 Identity and Avatar 594 Identity and Avatar
588 ~~~~~~~~~~~~~~~~~~~ 595 ~~~~~~~~~~~~~~~~~~~
589 596
590 The gateway does the conversion between XMPP identity and AP actor metadata. 597 The gateway does the conversion between XMPP identity and AP actor metadata.
591 598
592 XMPP "identity" is actually a compilaton of data coming from various locations and in 599 XMPP "identity" is actually a compilation of data coming from various locations and in
593 particular `XEP-0292 (vCard4 Over XMPP)`_. In those data, vCard's ``nickname`` (first 600 particular `XEP-0292 (vCard4 Over XMPP)`_. In those data, vCard's ``nickname`` (first
594 found) is used as AP ``name`` field, and vCard's ``note`` is used as AP's ``summary`` 601 found) is used as AP ``name`` field, and vCard's ``note`` is used as AP's ``summary``
595 (it's generally a self-description of users). 602 (it's generally a self-description of users).
596 603
597 For avatars, `XEP-0084 (User Avatar)`_ is used (and actor's ``icon`` field is used on AP 604 For avatars, `XEP-0084 (User Avatar)`_ is used (and actor's ``icon`` field is used on AP
603 610
604 .. _XEP-0292 (vCard4 Over XMPP): https://xmpp.org/extensions/xep-0292.html 611 .. _XEP-0292 (vCard4 Over XMPP): https://xmpp.org/extensions/xep-0292.html
605 .. _XEP-0084 (User Avatar): https://xmpp.org/extensions/xep-0084.html 612 .. _XEP-0084 (User Avatar): https://xmpp.org/extensions/xep-0084.html
606 .. _XEP-0054 (vcard-temp): https://xmpp.org/extensions/xep-0054.html 613 .. _XEP-0054 (vcard-temp): https://xmpp.org/extensions/xep-0054.html
607 614
615 Mentions
616 ~~~~~~~~
617
618 Mentions are converted by the gateway under some conditions explained below.
619
620 When receiving an AP item which converts to a pubsub item (i.e. not a direct message), for
621 any local user mentioned (using a tag of type ``Mention``) or directly specified in a
622 target field (``to``, ``bto``, ``cc`` or ``bcc``), a `XEP-0372 (References)`_ type mention
623 will be emitted.
624
625 This is not done for direct message as the recipients are already specified, and sending
626 reference is most probably not desired for a private message.
627
628 In the direction XMPP 🠞 ActivityPub, it's more complicated because XMPP sends references
629 separately from the pubsub item, while ActivityPub links them in the same item.
630
631 If a XEP-0372 reference targeting an AP actor is received and anchor a pubsub item, the
632 item will be looked after in cache. If found, it will be converted to an AP item, a
633 mention will be added, and the item will be delivered to the mentioned entity.
634
635 This only works if the mentioned actor is on a server which has not already received the
636 original item, because otherwise the AP implementation will most probably ignore the new
637 item which has the same ID.
638
639 It is hard to avoid sending first published item, then the same item with the reference,
640 because XEP-0372 references are received after the published items.
641
642 To work around that, when an XMPP blog item is received, its body is scanned to find
643 ``@user@server.tld`` type mention, and if found a mention is automatically added to the
644 resulting AP item.
645
646 It is not ideal to parse the body, but that's an acceptable trade-off to make mention
647 working. This behaviour is activated by default, but can be deactivated by setting
648 ``auto_mentions`` option to ``false``. Auto mentions are only used for pubsub items, and
649 not for direct messages for the same reason as mention are not checked in AP direct
650 messages (see above).
651
652 .. note::
653
654 For auto mentions, it's the AP actor handle which must be used, not the corresponding
655 virtual JID.
656
657 If you want to mention ``louise@example.org`` then you must use directly
658 ``@louise@example.org``, and NOT something like
659 ``@louise\40example.org@ap.example.net``.
660
661 To mention XMPP entities, your client must use XEP-0372 references directly.
662
663 .. _XEP-0372 (References): https://xmpp.org/extensions/xep-0372.html
664
608 Using the Component (for developers) 665 Using the Component (for developers)
609 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 666 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
610 667
611 Publication of AP items can be tested using the following method (with can be accessed 668 Publication of AP items can be tested using the following method (with can be accessed
612 through the ``APSend`` bridge method, client is then replaced by the ``profile`` name, as 669 through the ``APSend`` bridge method, client is then replaced by the ``profile`` name, as