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
This commit is contained in:
Goffi
parent
d1a623d12b
commit
a8ec84f3ec
1 changed files with 144 additions and 14 deletions
|
|
@ -160,7 +160,7 @@ ActivityPub Gateway
|
|||
|
||||
.. 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 @@ redirect the requests made to those path to the HTTP server (i.e. to component h
|
|||
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 @@ 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
|
||||
|
||||
.. _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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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):
|
||||
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::
|
||||
|
||||
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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue