Mercurial > libervia-backend
changeset 3683:a1eff4e32848
doc (components): base documentation for AP Gateway:
fix: 362
author | Goffi <goffi@goffi.org> |
---|---|
date | Sun, 26 Sep 2021 16:41:58 +0200 (2021-09-26) |
parents | 7c990aaa49d3 |
children | 8353cc3b8db9 |
files | doc/components.rst doc/libervia-cli/debug.rst |
diffstat | 2 files changed, 105 insertions(+), 1 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/components.rst Sun Sep 26 16:41:55 2021 +0200 +++ b/doc/components.rst Sun Sep 26 16:41:58 2021 +0200 @@ -151,3 +151,107 @@ } .. _SI prefixes and binary prefixes: https://en.wikipedia.org/wiki/Octet_(computing)#Unit_multiples + + +ActivityPub Gateway +------------------- + +**entry_point:** ``ap-gateway`` + +.. note:: + + this component is currently in active development, and not yet usable for end-user. This + documentation will be updated during evolution of component. + + You can follow the development by reading `Libervia Progress Notes`_. + + .. _Libervia Progress Notes: https://www.goffi.org/tag/Libervia%20progress + +This gateway will provide a bidirectional gateway between XMPP and `ActivityPub`_ (or AP +below). That means that user from XMPP will be able to follow actors or comments messages +from any software compatible with ActivityPub protocol, and vice versa. + +.. _ActivityPub: https://activitypub.rocks/ + +.. note:: + + this component is mostly tested with Prosody as XMPP server reference, and Mastodon as + AP server reference, but it should work with any XMPP or AP server. + +The component launches a HTTP server (necessary to communicate with AP software). This +server needs to handle HTTP requests made at paths ``/.well-known/webfinger`` and ``/_ap`` +(or the ``ap_path`` set in configuration, see below). If the component is not directly +facing internet (e.g. integrated in an existing website though a proxy), you'll have to +redirect the requests made to those path to the HTTP server (i.e. to component host at the +port set at ``http_port``, see configuration below). Please check your HTTP server +documentation to find how this must be done. + +how to address an AP actor from XMPP +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When addressing an ActivityPub actor from XMPP, you must use a JID corresponding to the +actor. The domain part of the JID correspond to the gateway JID (the one set in gateway +profile), while the local part (before the ``@``) is used to specify the AP actor. + +`XEP-0106`_ (JID Escaping) is used to indicate the AP actor identifier, thus the ``@`` +must be escaped with ``\40``. + +.. _XEP-0106: JID Escaping + +**example** + +If Louise wants to talk to Pierre which is on the ``example.net`` AP server, she can use +her XMPP AP gateway which is at ``ap.example.org``. Pierre AP's actor identifier is +``pierre@example.net``, Louise can access it via the JID +``pierre\40example.net@ap.example.org``. + +Of course, this is a bit cumbersome to do by hand, it is expected that XMPP clients will +do the (un)escaping automatically for end-user, in a way that Louise could enter +``pierre@example.net`` directly, with an indicator to show that this is an ActivityPub +actor identifier rather than an XMPP JID. + +how to address an XMPP entity from AP +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To access an XMPP entity, just use its bare JID as AP actor. + +**example** + +If Pierre wants to talk Louise, he can directly use the JID which is the same as the AP +actor identifier, i.e. ``louise@example.org`` (note that on AP software, a ``@`` prefix is +often required, thus Pierre will look for ``@louise@example.org``). + +.. note:: + + Currently the gateway only uses bare JID, and character set must be recognised by the + AP software to be used. This will evolve in the close future to have a way to access + various XMPP Pubsub nodes. + + 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``). + + +using the component +~~~~~~~~~~~~~~~~~~~ + +The component is currently only usable for development purpose, and it can be used with +the following method (with can be accessed through the ``APSend`` bridge method, client is +then replaced by the ``profile`` name, as last argument): + +.. automethod:: sat.plugins.plugin_comp_ap_gateway.APGateway.publishMessage + +The method can be used either with CLI's :ref:`debug bridge method +<li_debug_bridge_method>` or with any D-Bus tool like ``qdbus`` or ``d-feet`` (only if you +use the D-Bus bridge). + +example +~~~~~~~ + +On its ``example.net`` Mastodon instance, Pierre has published a message with the id +``https://example.net/@pierre/106986412193109832``. To send a reply to this message, +Louise can use the following command:: + + $ li debug bridge method -c APSend '"{\"node\": \"https://example.net/@pierre/106986412193109832\", \"content\": \"A lille hello from XMPP\"}","pierre\\40example.net@ap.example.org", "louise"' + +Note the double escaping, one for the shell argument, and the other to specify JSON +object.
--- a/doc/libervia-cli/debug.rst Sun Sep 26 16:41:55 2021 +0200 +++ b/doc/libervia-cli/debug.rst Sun Sep 26 16:41:58 2021 +0200 @@ -4,7 +4,7 @@ ``debug`` groups commands to monitor or manipulate Libervia and XMPP stream. -.. _libervia-cli_debug_bridge_method: +.. _li_debug_bridge_method: bridge method =============