doc (components): base documentation for AP Gateway:
fix: 362
This commit is contained in:
Goffi
parent
76c98da073
commit
aa4e6004e8
2 changed files with 105 additions and 1 deletions
|
|
@ -151,3 +151,107 @@ All options are to be set in ``[component file-sharing]`` section.
|
|||
}
|
||||
|
||||
.. _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.
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ debug: tools to help debugging/monitoring Libervia
|
|||
|
||||
``debug`` groups commands to monitor or manipulate Libervia and XMPP stream.
|
||||
|
||||
.. _libervia-cli_debug_bridge_method:
|
||||
.. _li_debug_bridge_method:
|
||||
|
||||
bridge method
|
||||
=============
|
||||
|
|
|
|||
Loading…
Reference in a new issue