changeset 3734:643622ff1492

doc (components): update AP component documentation: - add `configuration` section - update instructions on AP actor handle <=> JID/node conversion - explain how to get AP messages from XMPP - explain how to get XMPP items for AP - notes to explain tricks and implementations details fix 363
author Goffi <>
date Mon, 31 Jan 2022 18:35:52 +0100
parents 6cc39a3b8c14
children 04ecc8eeb81a
files doc/components.rst
diffstat 1 files changed, 144 insertions(+), 14 deletions(-) [+]
line wrap: on
line diff
--- a/doc/components.rst	Mon Jan 31 18:35:52 2022 +0100
+++ b/doc/components.rst	Mon Jan 31 18:35:52 2022 +0100
@@ -160,7 +160,7 @@
 .. note::
-  this component is currently in active development, and not yet usable for end-user. This
+  this component is currently in active development, and not yet fully functional. This
   documentation will be updated during evolution of component.
   You can follow the development by reading `Libervia Progress Notes`_.
@@ -186,7 +186,57 @@
 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
+All options are to be set in ``[component ap-gateway]`` section.
+  Main user-facing domain of the HTTP server, this will be used to construct all AP URLs
+  **default**: if not set, ``xmpp_domain`` is used. If ``xmpp_domain`` is not set either,
+  an error is raised.
+  port where the HTTP server should listen. Port ``80`` is not used directly as it would
+  require root privileges, and it is strongly recommended against launching Libervia under
+  a privileged account. An HTTP Proxy or a port redirection should be set to redirect the
+  ``80`` port to the port specified here.
+  **default**: ``8123``
+  either ``http`` or ``https``. If you have a HTTP proxy such as Apache or NGINX which
+  already handles HTTPS, you may want to use ``http``.
+  **default**: ``https``
+  Note that the HTTP server should always use ``https`` with end-user, the ``http`` option
+  is only to be used with an HTTPS proxy.
+  A boolean value indicating if the gateway is allowed to convert pubsub node from
+  external XMPP service or not. A JID is considered external if its domain part doesn't
+  end with the gateway's server. For instance, if a gateway ```` is set on
+  the server ````, the JIDs ```` or
+  ```` will be considered local, but
+  ```` won't (note the different domain).
+  Most of time, ``local_only`` should be used.
+  **default**: ``true``
+  Path prefix to use for ActivityPub request. It's usually not necessary to change the
+  default value.
+  **default**: ``_ap``
+.. _ap-actor-from-xmpp:
+How to Address an AP Actor from XMPP
 When addressing an ActivityPub actor from XMPP, you must use a JID corresponding to the
@@ -210,33 +260,113 @@
 ```` 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
+.. _xmpp-node-from-ap:
+How to Address an XMPP Entity from AP
-To access an XMPP entity, just use its bare JID as AP actor.
+To access an XMPP entity, it is a little bit more complicated for 2 reasons:
+- XMPP use a wider range of allowed characters than most AP implementations [#AP_chars]_.
+- to get XMPP items, we need 2 data: the entity JID, and a pubsub node
+However, Libervia AP gateway tries to make it as user friendly as possible, thus it works
+like this:
+- in the most common case, one just wants to access the personal blog of a user, and basic
+  ASCII characters (with possibly ``-``, ``_`` or ``.``) are used. in this case, the XMPP
+  JID can be directly used as AP actor handle
+- when a pubsub node needs to be specified it is most of time with a pubsub JID which has
+  not user part (something like ````). In this case, the pubsub node can
+  be used as AP actor handle's user part, Libervia will use XMPP discovery to know that
+  it's a pubsub service. So if you want to access the blog named ``xmpp_news`` at
+  ````, you can use the handle ```` (be sure
+  that the domain ```` links to the Libervia AP gateway HTTP server)
+- if you want to use a specific node with an entity which already has a user part, then a
+  special encoding must be used, where ``---`` (three dashes) are used to separate node
+  from entity: ````
+- if you need to use special characters, then you'll have to use ``___`` followed by the
+  special encoding (see below).
+The encoding is explained in the documentation of the following method:
+.. automethod:: sat.plugins.plugin_comp_ap_gateway.APGateway.getJIDAndNode
+.. [#AP_chars] Most if not all AP implementations use webfinger `acct` URI as a de-facto
+   standard to manage user-friendly handles (something like ````). Those
+   handles, according to `RFC7565`_, should
+   manage a wide variety of characters thanks to the support of percent-encoding.
+   Unfortunately, at least one of the most-used AP implementation (Mastodon, which is used
+   a reference implementation for this gateway), only uses a limited subset of allowed
+   characters. In addition, Mastodon needs an associated handle [#m_wf]_ thus an alternate
+   way to encode characters had to be found.
+   An issue has been opened to improve this situation on Mastodon bug tracker:
+   .. _RFC7565:
+   .. [#m_wf]
-If Pierre wants to talk Louise, he can directly use the JID which is the same as the AP
+If Pierre wants to talk to Louise, he can directly use the JID which is the same as the AP
 actor identifier, i.e. ```` (note that on AP software, a ``@`` prefix is
 often required, thus Pierre will look for ````).
 .. 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 ````).
-using the component
+Getting AP Message from XMPP
+To retrieve ActivityPub messages of an actor from an XMPP client with blogging
+capabilities (like Libervia or Movim), just use the associated JID as explained in
+:ref:`ap-actor-from-xmpp`. The actor messages (from ``outbox`` collection) should appear
+as regular XMPP blog items.
+.. note::
+   Due to limitation of `ActivityStream Collection Paging`_, the conversion from XMPP
+   `RSM`_ requests is inneficient beyond first or last page. This problem is avoided if
+   anybody subscribe to the gateway node (i.e. follow the AP actor), as the collection
+   will then be cached, and efficiently delivered. Note that subscription/following is NOT
+   IMPLEMENTED YET, but will be in the close future.
+   .. _ActivityStream Collection Paging:
+   .. _RSM:
+.. note::
-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):
+   Only "root" items are currectly converted, i.e. items which are not replies to other
+   objects. Replies will be managed in the close future with AP collections caching.
+Getting XMPP Items from ActivityPub
+To get XMPP items from an ActivityPub implementation, just use the handle as explained at
+:ref:`xmpp-node-from-ap` (often handle searches are triggered with a ``@`` before the
+handle in AP implementations, e.g.: ````).
+.. note::
+   Some AP implementations such as Mastodon don't retrieve existing items, but only keep
+   new ones once an actor is followed. That means that you won't see any message published
+   before your entity is followed. Other implementations may work differently.
+Using the Component (for developers)
+Publication of AP items can be tested using 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