libervia-backend: doc/components.rst comparison

comparison doc/components.rst @ 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
parents	ba4ef64a6938
children	643622ff1492

comparison

equal deleted inserted replaced

-:7c990aaa49d3
+:a1eff4e32848
 "users": "50 Mio",
 "jids": {"pierre@example.org": "1 Gio"}
 }
 .. _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.

Mercurial > libervia-backend

comparison doc/components.rst @ 3683:a1eff4e32848