Mercurial > libervia-backend
changeset 3910:199598223f82
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 (2022-09-22) |
parents | 3c3275a6dc8f |
children | 8289ac1b34f4 |
files | doc/components.rst |
diffstat | 1 files changed, 69 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/components.rst Thu Sep 22 12:01:44 2022 +0200 +++ b/doc/components.rst Thu Sep 22 12:03:12 2022 +0200 @@ -333,6 +333,18 @@ The actor endpoint can also be used directly in AP software (in the example above, it would be by default ``https://example.org/_ap/actor/louise%40example.org``). +.. _ap-ad-hoc: + +Ad-Hoc Commands +~~~~~~~~~~~~~~~ + +The gateway supports `XEP-0050 (Ad-Hoc Commands)`_. For now, only the following node is +provided: + +``https://libervia.org/ap_gateway/xmpp_jid_node_2_ap_actor`` + Convert XMPP JID and Node to corresponding virtual actor. Node is optional. + +.. _XEP-0050 (Ad-Hoc Commands): https://xmpp.org/extensions/xep-0050.html Getting AP Message from XMPP ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -705,6 +717,63 @@ .. _Pleroma: https://pleroma.social/ .. _XEP-0444 (Message Reactions): https://xmpp.org/extensions/xep-0444.html +Events +~~~~~~ + +This gateway manages events. On the XMPP side, the ``Events`` protoXEP is used, on AP side +``Event`` objects are used. `Mobilizon`_ is used as reference implementation here. + +.. note:: + + The ``Events`` protoXEP has been proposed but not published or reviewed by XMPP council + yet. The current version is availale at https://github.com/xsf/xeps/pull/1206 and + hopefully it will eventually become an official experimental XEP. The code and this + documentation will be updated as the standard evolves. + +To retrieve AP events from XMPP, use the corresponding virtual JID as explained in +:ref:`ap-actor-from-xmpp` with the event node (which is ``urn:xmpp:events:0``). + +*example:* + +To retrieve events from AP actor with the handle ``somebody@mobilizon.example``, throught +the ``ap.example.org`` gateway, the ``somebody\40mobilizon.example@ap.example.org`` JID +can be used with the ``urn:xmpp:events:0`` node. + + +To retrieve XMPP events from AP, you need to the virtual actor corresponding to the JID +of the pubsub/PEP service with the event node (starting with ``urn:xmpp:events:0``), as +explained in :ref:`xmpp-node-from-ap`. You can use :ref:`ap-ad-hoc` to easily convert your +JID/node combination to a virtual AP actor. Note that the resulting virtual actor is +unaesthetic due to the presence of event node and the constraints explained in +:ref:`xmpp-node-from-ap`. + +To retrieve the link to the XMPP item from AP, you can use the ID from the generated AP +object. The ID can also be constructed by hand by using the URL +``https://<ap_gateway_public_domain>/_ap/<virtual_actor>/<event_item_id>``. + +*example:* + +to retrieve from AP the XMPP event at pubsub service ``pubsub.example.net`` on node +``urn:xmpp:events:0/party`` with item ID ``picnic_abd1``, and using the AP gateway with +public url ``https://ap.example.net``, the following link can be used:: + + https://ap.example.net/_ap/___urn.3Axmpp.3Aevents.3A0.2Fparty---pubsub.2eexample.2enet@ap.tazar3.int/picnic_abd1 + +If you paste it in an AP implementation featuring events (e.g. Mobilizon), the event +should appear and you should be able to comment it and participate to it. + +Event comments are supported, the node to use is indicated in the event XMPP item as +specified in the protoXEP, this should be transparent to end-user. + +Participation to an event is supported through the RSVP mechanism on XMPP and with +``Join`` and ``Leave`` activities on AP. Note that XMPP allows more nuances with its RSVP +mechanism (it's possible to say if someone will "maybe" attend an event, and to request +any kind of extra informations) while AP only indicates if one will attend or not an +event. + + +.. _Mobilizon: https://joinmobilizon.org/ + Using the Component (for developers) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~