# HG changeset patch # User Goffi # Date 1643650552 -3600 # Node ID 643622ff1492e988ef9b9e7644d895711aa8f539 # Parent 6cc39a3b8c14f6bc125cb0b6fe39f118f0ff6b60 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 diff -r 6cc39a3b8c14 -r 643622ff1492 doc/components.rst --- 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 + +Configuration +~~~~~~~~~~~~~ + +All options are to be set in ``[component ap-gateway]`` section. + +``public_url`` + 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. + +``http_port`` + 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`` + +``http_connection_type`` + 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. + +``local_only`` + 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 ``ap.example.org`` is set on + the server ``example.org``, the JIDs ``pierre@example.org`` or + ``some-node@pubsub.example.org`` will be considered local, but + ``buenaventura@example.net`` won't (note the different domain). + + Most of time, ``local_only`` should be used. + + **default**: ``true`` + +``ap_path`` + 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 @@ ``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 + +.. _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 ``pubsub.example.org``). 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 + ``pubsub.example.org``, you can use the handle ``xmpp_news@pubsub.example.org`` (be sure + that the domain ``pubsub.example.org`` 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: ``some_node--some_user@example.org`` +- 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 ``user@example.org``). 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: + https://github.com/mastodon/mastodon/issues/17222 + + .. _RFC7565: https://datatracker.ietf.org/doc/html/rfc7565 + .. [#m_wf] https://docs.joinmastodon.org/spec/webfinger/ **example** -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. ``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 -~~~~~~~~~~~~~~~~~~~ +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: https://www.w3.org/TR/activitystreams-core/#h-paging + .. _RSM: https://xmpp.org/extensions/xep-0059.html + +.. 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.: ``@louise@example.org``). + +.. 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