Mercurial > libervia-backend
comparison doc/components.rst @ 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 <goffi@goffi.org> |
---|---|
date | Mon, 31 Jan 2022 18:35:52 +0100 |
parents | a1eff4e32848 |
children | fa3dc4ed7906 |
comparison
equal
deleted
inserted
replaced
3733:6cc39a3b8c14 | 3734:643622ff1492 |
---|---|
158 | 158 |
159 **entry_point:** ``ap-gateway`` | 159 **entry_point:** ``ap-gateway`` |
160 | 160 |
161 .. note:: | 161 .. note:: |
162 | 162 |
163 this component is currently in active development, and not yet usable for end-user. This | 163 this component is currently in active development, and not yet fully functional. This |
164 documentation will be updated during evolution of component. | 164 documentation will be updated during evolution of component. |
165 | 165 |
166 You can follow the development by reading `Libervia Progress Notes`_. | 166 You can follow the development by reading `Libervia Progress Notes`_. |
167 | 167 |
168 .. _Libervia Progress Notes: https://www.goffi.org/tag/Libervia%20progress | 168 .. _Libervia Progress Notes: https://www.goffi.org/tag/Libervia%20progress |
184 facing internet (e.g. integrated in an existing website though a proxy), you'll have to | 184 facing internet (e.g. integrated in an existing website though a proxy), you'll have to |
185 redirect the requests made to those path to the HTTP server (i.e. to component host at the | 185 redirect the requests made to those path to the HTTP server (i.e. to component host at the |
186 port set at ``http_port``, see configuration below). Please check your HTTP server | 186 port set at ``http_port``, see configuration below). Please check your HTTP server |
187 documentation to find how this must be done. | 187 documentation to find how this must be done. |
188 | 188 |
189 how to address an AP actor from XMPP | 189 |
190 Configuration | |
191 ~~~~~~~~~~~~~ | |
192 | |
193 All options are to be set in ``[component ap-gateway]`` section. | |
194 | |
195 ``public_url`` | |
196 Main user-facing domain of the HTTP server, this will be used to construct all AP URLs | |
197 | |
198 **default**: if not set, ``xmpp_domain`` is used. If ``xmpp_domain`` is not set either, | |
199 an error is raised. | |
200 | |
201 ``http_port`` | |
202 port where the HTTP server should listen. Port ``80`` is not used directly as it would | |
203 require root privileges, and it is strongly recommended against launching Libervia under | |
204 a privileged account. An HTTP Proxy or a port redirection should be set to redirect the | |
205 ``80`` port to the port specified here. | |
206 | |
207 **default**: ``8123`` | |
208 | |
209 ``http_connection_type`` | |
210 either ``http`` or ``https``. If you have a HTTP proxy such as Apache or NGINX which | |
211 already handles HTTPS, you may want to use ``http``. | |
212 | |
213 **default**: ``https`` | |
214 | |
215 Note that the HTTP server should always use ``https`` with end-user, the ``http`` option | |
216 is only to be used with an HTTPS proxy. | |
217 | |
218 ``local_only`` | |
219 A boolean value indicating if the gateway is allowed to convert pubsub node from | |
220 external XMPP service or not. A JID is considered external if its domain part doesn't | |
221 end with the gateway's server. For instance, if a gateway ``ap.example.org`` is set on | |
222 the server ``example.org``, the JIDs ``pierre@example.org`` or | |
223 ``some-node@pubsub.example.org`` will be considered local, but | |
224 ``buenaventura@example.net`` won't (note the different domain). | |
225 | |
226 Most of time, ``local_only`` should be used. | |
227 | |
228 **default**: ``true`` | |
229 | |
230 ``ap_path`` | |
231 Path prefix to use for ActivityPub request. It's usually not necessary to change the | |
232 default value. | |
233 | |
234 **default**: ``_ap`` | |
235 | |
236 | |
237 .. _ap-actor-from-xmpp: | |
238 | |
239 How to Address an AP Actor from XMPP | |
190 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 240 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
191 | 241 |
192 When addressing an ActivityPub actor from XMPP, you must use a JID corresponding to the | 242 When addressing an ActivityPub actor from XMPP, you must use a JID corresponding to the |
193 actor. The domain part of the JID correspond to the gateway JID (the one set in gateway | 243 actor. The domain part of the JID correspond to the gateway JID (the one set in gateway |
194 profile), while the local part (before the ``@``) is used to specify the AP actor. | 244 profile), while the local part (before the ``@``) is used to specify the AP actor. |
208 Of course, this is a bit cumbersome to do by hand, it is expected that XMPP clients will | 258 Of course, this is a bit cumbersome to do by hand, it is expected that XMPP clients will |
209 do the (un)escaping automatically for end-user, in a way that Louise could enter | 259 do the (un)escaping automatically for end-user, in a way that Louise could enter |
210 ``pierre@example.net`` directly, with an indicator to show that this is an ActivityPub | 260 ``pierre@example.net`` directly, with an indicator to show that this is an ActivityPub |
211 actor identifier rather than an XMPP JID. | 261 actor identifier rather than an XMPP JID. |
212 | 262 |
213 how to address an XMPP entity from AP | 263 |
264 .. _xmpp-node-from-ap: | |
265 | |
266 How to Address an XMPP Entity from AP | |
214 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 267 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
215 | 268 |
216 To access an XMPP entity, just use its bare JID as AP actor. | 269 To access an XMPP entity, it is a little bit more complicated for 2 reasons: |
270 | |
271 - XMPP use a wider range of allowed characters than most AP implementations [#AP_chars]_. | |
272 - to get XMPP items, we need 2 data: the entity JID, and a pubsub node | |
273 | |
274 | |
275 However, Libervia AP gateway tries to make it as user friendly as possible, thus it works | |
276 like this: | |
277 | |
278 - in the most common case, one just wants to access the personal blog of a user, and basic | |
279 ASCII characters (with possibly ``-``, ``_`` or ``.``) are used. in this case, the XMPP | |
280 JID can be directly used as AP actor handle | |
281 - when a pubsub node needs to be specified it is most of time with a pubsub JID which has | |
282 not user part (something like ``pubsub.example.org``). In this case, the pubsub node can | |
283 be used as AP actor handle's user part, Libervia will use XMPP discovery to know that | |
284 it's a pubsub service. So if you want to access the blog named ``xmpp_news`` at | |
285 ``pubsub.example.org``, you can use the handle ``xmpp_news@pubsub.example.org`` (be sure | |
286 that the domain ``pubsub.example.org`` links to the Libervia AP gateway HTTP server) | |
287 - if you want to use a specific node with an entity which already has a user part, then a | |
288 special encoding must be used, where ``---`` (three dashes) are used to separate node | |
289 from entity: ``some_node--some_user@example.org`` | |
290 - if you need to use special characters, then you'll have to use ``___`` followed by the | |
291 special encoding (see below). | |
292 | |
293 The encoding is explained in the documentation of the following method: | |
294 | |
295 .. automethod:: sat.plugins.plugin_comp_ap_gateway.APGateway.getJIDAndNode | |
296 | |
297 | |
298 .. [#AP_chars] Most if not all AP implementations use webfinger `acct` URI as a de-facto | |
299 standard to manage user-friendly handles (something like ``user@example.org``). Those | |
300 handles, according to `RFC7565`_, should | |
301 manage a wide variety of characters thanks to the support of percent-encoding. | |
302 | |
303 Unfortunately, at least one of the most-used AP implementation (Mastodon, which is used | |
304 a reference implementation for this gateway), only uses a limited subset of allowed | |
305 characters. In addition, Mastodon needs an associated handle [#m_wf]_ thus an alternate | |
306 way to encode characters had to be found. | |
307 | |
308 An issue has been opened to improve this situation on Mastodon bug tracker: | |
309 https://github.com/mastodon/mastodon/issues/17222 | |
310 | |
311 .. _RFC7565: https://datatracker.ietf.org/doc/html/rfc7565 | |
312 .. [#m_wf] https://docs.joinmastodon.org/spec/webfinger/ | |
217 | 313 |
218 **example** | 314 **example** |
219 | 315 |
220 If Pierre wants to talk Louise, he can directly use the JID which is the same as the AP | 316 If Pierre wants to talk to Louise, he can directly use the JID which is the same as the AP |
221 actor identifier, i.e. ``louise@example.org`` (note that on AP software, a ``@`` prefix is | 317 actor identifier, i.e. ``louise@example.org`` (note that on AP software, a ``@`` prefix is |
222 often required, thus Pierre will look for ``@louise@example.org``). | 318 often required, thus Pierre will look for ``@louise@example.org``). |
223 | 319 |
224 .. note:: | 320 .. note:: |
225 | 321 |
226 Currently the gateway only uses bare JID, and character set must be recognised by the | |
227 AP software to be used. This will evolve in the close future to have a way to access | |
228 various XMPP Pubsub nodes. | |
229 | |
230 The actor endpoint can also be used directly in AP software (in the example above, it | 322 The actor endpoint can also be used directly in AP software (in the example above, it |
231 would be by default ``https://example.org/_ap/actor/louise%40example.org``). | 323 would be by default ``https://example.org/_ap/actor/louise%40example.org``). |
232 | 324 |
233 | 325 |
234 using the component | 326 Getting AP Message from XMPP |
235 ~~~~~~~~~~~~~~~~~~~ | 327 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
236 | 328 |
237 The component is currently only usable for development purpose, and it can be used with | 329 To retrieve ActivityPub messages of an actor from an XMPP client with blogging |
238 the following method (with can be accessed through the ``APSend`` bridge method, client is | 330 capabilities (like Libervia or Movim), just use the associated JID as explained in |
239 then replaced by the ``profile`` name, as last argument): | 331 :ref:`ap-actor-from-xmpp`. The actor messages (from ``outbox`` collection) should appear |
332 as regular XMPP blog items. | |
333 | |
334 .. note:: | |
335 | |
336 Due to limitation of `ActivityStream Collection Paging`_, the conversion from XMPP | |
337 `RSM`_ requests is inneficient beyond first or last page. This problem is avoided if | |
338 anybody subscribe to the gateway node (i.e. follow the AP actor), as the collection | |
339 will then be cached, and efficiently delivered. Note that subscription/following is NOT | |
340 IMPLEMENTED YET, but will be in the close future. | |
341 | |
342 .. _ActivityStream Collection Paging: https://www.w3.org/TR/activitystreams-core/#h-paging | |
343 .. _RSM: https://xmpp.org/extensions/xep-0059.html | |
344 | |
345 .. note:: | |
346 | |
347 Only "root" items are currectly converted, i.e. items which are not replies to other | |
348 objects. Replies will be managed in the close future with AP collections caching. | |
349 | |
350 Getting XMPP Items from ActivityPub | |
351 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
352 | |
353 To get XMPP items from an ActivityPub implementation, just use the handle as explained at | |
354 :ref:`xmpp-node-from-ap` (often handle searches are triggered with a ``@`` before the | |
355 handle in AP implementations, e.g.: ``@louise@example.org``). | |
356 | |
357 .. note:: | |
358 | |
359 Some AP implementations such as Mastodon don't retrieve existing items, but only keep | |
360 new ones once an actor is followed. That means that you won't see any message published | |
361 before your entity is followed. Other implementations may work differently. | |
362 | |
363 | |
364 Using the Component (for developers) | |
365 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
366 | |
367 Publication of AP items can be tested using the following method (with can be accessed | |
368 through the ``APSend`` bridge method, client is then replaced by the ``profile`` name, as | |
369 last argument): | |
240 | 370 |
241 .. automethod:: sat.plugins.plugin_comp_ap_gateway.APGateway.publishMessage | 371 .. automethod:: sat.plugins.plugin_comp_ap_gateway.APGateway.publishMessage |
242 | 372 |
243 The method can be used either with CLI's :ref:`debug bridge method | 373 The method can be used either with CLI's :ref:`debug bridge method |
244 <li_debug_bridge_method>` or with any D-Bus tool like ``qdbus`` or ``d-feet`` (only if you | 374 <li_debug_bridge_method>` or with any D-Bus tool like ``qdbus`` or ``d-feet`` (only if you |