Mercurial > libervia-backend

comparison doc/components.rst @ 3910:199598223f82

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc (components/AP Gateway): Ad-Hoc and Events: New Ad-Hoc command is explained, and `Events` section specify how the conversion is done between the 2 protocols. fix 372
author Goffi <goffi@goffi.org>
date Thu, 22 Sep 2022 12:03:12 +0200
parents ba78cc0c8d59
children 97fbe11c4476
comparison
equal deleted inserted replaced
3909:3c3275a6dc8f 3910:199598223f82
331 .. note:: 331 .. note::
332 332
333 The actor endpoint can also be used directly in AP software (in the example above, it 333 The actor endpoint can also be used directly in AP software (in the example above, it
334 would be by default ``https://example.org/_ap/actor/louise%40example.org``). 334 would be by default ``https://example.org/_ap/actor/louise%40example.org``).
335 335
336 .. _ap-ad-hoc:
337
338 Ad-Hoc Commands
339 ~~~~~~~~~~~~~~~
340
341 The gateway supports `XEP-0050 (Ad-Hoc Commands)`_. For now, only the following node is
342 provided:
343
344 ``https://libervia.org/ap_gateway/xmpp_jid_node_2_ap_actor``
345 Convert XMPP JID and Node to corresponding virtual actor. Node is optional.
346
347 .. _XEP-0050 (Ad-Hoc Commands): https://xmpp.org/extensions/xep-0050.html
336 348
337 Getting AP Message from XMPP 349 Getting AP Message from XMPP
338 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 350 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
339 351
340 To retrieve ActivityPub messages of an actor from an XMPP client with blogging 352 To retrieve ActivityPub messages of an actor from an XMPP client with blogging
703 715
704 .. _base ActivityPub specification: https://www.w3.org/TR/activitypub/ 716 .. _base ActivityPub specification: https://www.w3.org/TR/activitypub/
705 .. _Pleroma: https://pleroma.social/ 717 .. _Pleroma: https://pleroma.social/
706 .. _XEP-0444 (Message Reactions): https://xmpp.org/extensions/xep-0444.html 718 .. _XEP-0444 (Message Reactions): https://xmpp.org/extensions/xep-0444.html
707 719
720 Events
721 ~~~~~~
722
723 This gateway manages events. On the XMPP side, the ``Events`` protoXEP is used, on AP side
724 ``Event`` objects are used. `Mobilizon`_ is used as reference implementation here.
725
726 .. note::
727
728 The ``Events`` protoXEP has been proposed but not published or reviewed by XMPP council
729 yet. The current version is availale at https://github.com/xsf/xeps/pull/1206 and
730 hopefully it will eventually become an official experimental XEP. The code and this
731 documentation will be updated as the standard evolves.
732
733 To retrieve AP events from XMPP, use the corresponding virtual JID as explained in
734 :ref:`ap-actor-from-xmpp` with the event node (which is ``urn:xmpp:events:0``).
735
736 *example:*
737
738 To retrieve events from AP actor with the handle ``somebody@mobilizon.example``, throught
739 the ``ap.example.org`` gateway, the ``somebody\40mobilizon.example@ap.example.org`` JID
740 can be used with the ``urn:xmpp:events:0`` node.
741
742
743 To retrieve XMPP events from AP, you need to the virtual actor corresponding to the JID
744 of the pubsub/PEP service with the event node (starting with ``urn:xmpp:events:0``), as
745 explained in :ref:`xmpp-node-from-ap`. You can use :ref:`ap-ad-hoc` to easily convert your
746 JID/node combination to a virtual AP actor. Note that the resulting virtual actor is
747 unaesthetic due to the presence of event node and the constraints explained in
748 :ref:`xmpp-node-from-ap`.
749
750 To retrieve the link to the XMPP item from AP, you can use the ID from the generated AP
751 object. The ID can also be constructed by hand by using the URL
752 ``https://<ap_gateway_public_domain>/_ap/<virtual_actor>/<event_item_id>``.
753
754 *example:*
755
756 to retrieve from AP the XMPP event at pubsub service ``pubsub.example.net`` on node
757 ``urn:xmpp:events:0/party`` with item ID ``picnic_abd1``, and using the AP gateway with
758 public url ``https://ap.example.net``, the following link can be used::
759
760 https://ap.example.net/_ap/___urn.3Axmpp.3Aevents.3A0.2Fparty---pubsub.2eexample.2enet@ap.tazar3.int/picnic_abd1
761
762 If you paste it in an AP implementation featuring events (e.g. Mobilizon), the event
763 should appear and you should be able to comment it and participate to it.
764
765 Event comments are supported, the node to use is indicated in the event XMPP item as
766 specified in the protoXEP, this should be transparent to end-user.
767
768 Participation to an event is supported through the RSVP mechanism on XMPP and with
769 ``Join`` and ``Leave`` activities on AP. Note that XMPP allows more nuances with its RSVP
770 mechanism (it's possible to say if someone will "maybe" attend an event, and to request
771 any kind of extra informations) while AP only indicates if one will attend or not an
772 event.
773
774
775 .. _Mobilizon: https://joinmobilizon.org/
776
708 Using the Component (for developers) 777 Using the Component (for developers)
709 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 778 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
710 779
711 Publication of AP items can be tested using the following method (with can be accessed 780 Publication of AP items can be tested using the following method (with can be accessed
712 through the ``APSend`` bridge method, client is then replaced by the ``profile`` name, as 781 through the ``APSend`` bridge method, client is then replaced by the ``profile`` name, as