Mercurial > libervia-backend
comparison doc/components.rst @ 3772:98ba02637436
doc (components): update AP gateway documentation:
add documentation for:
- Publishing an Item
- Following, Subscribing and Cache
- Following/Followers Collections and Public Pubsub Subscription
fix 365
author | Goffi <goffi@goffi.org> |
---|---|
date | Fri, 13 May 2022 19:34:12 +0200 |
parents | fa3dc4ed7906 |
children | cebfdfff3e99 |
comparison
equal
deleted
inserted
replaced
3771:e597dbfbc4c6 | 3772:98ba02637436 |
---|---|
338 .. note:: | 338 .. note:: |
339 | 339 |
340 Due to limitation of `ActivityStream Collection Paging`_, the conversion from XMPP | 340 Due to limitation of `ActivityStream Collection Paging`_, the conversion from XMPP |
341 `RSM`_ requests is inneficient beyond first or last page. This problem is avoided if | 341 `RSM`_ requests is inneficient beyond first or last page. This problem is avoided if |
342 anybody subscribe to the gateway node (i.e. follow the AP actor), as the collection | 342 anybody subscribe to the gateway node (i.e. follow the AP actor), as the collection |
343 will then be cached, and efficiently delivered. Note that subscription/following is NOT | 343 will then be cached, and efficiently delivered. |
344 IMPLEMENTED YET, but will be in the close future. | |
345 | 344 |
346 .. _ActivityStream Collection Paging: https://www.w3.org/TR/activitystreams-core/#h-paging | 345 .. _ActivityStream Collection Paging: https://www.w3.org/TR/activitystreams-core/#h-paging |
347 .. _RSM: https://xmpp.org/extensions/xep-0059.html | 346 .. _RSM: https://xmpp.org/extensions/xep-0059.html |
348 | |
349 .. note:: | |
350 | |
351 Only "root" items are currectly converted, i.e. items which are not replies to other | |
352 objects. Replies will be managed in the close future with AP collections caching. | |
353 | 347 |
354 Getting XMPP Items from ActivityPub | 348 Getting XMPP Items from ActivityPub |
355 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 349 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
356 | 350 |
357 To get XMPP items from an ActivityPub implementation, just use the handle as explained at | 351 To get XMPP items from an ActivityPub implementation, just use the handle as explained at |
408 This way, admins can configure the model which suits best the clients which is expected to | 402 This way, admins can configure the model which suits best the clients which is expected to |
409 be mainly used on the instance. | 403 be mainly used on the instance. |
410 | 404 |
411 .. _XEP-0277 comments: https://xmpp.org/extensions/xep-0277.html#comments | 405 .. _XEP-0277 comments: https://xmpp.org/extensions/xep-0277.html#comments |
412 | 406 |
407 Publishing an Item | |
408 ~~~~~~~~~~~~~~~~~~ | |
409 | |
410 To publish a new item (e.g. a blog post), you just need to publish normally on your own | |
411 PEP/pubsub node, AP actors following you will be notified. To reply to an AP item, just | |
412 publish to the corresponding pubsub node managed by the gateway. This is transparent for | |
413 AP and XMPP end users. | |
414 | |
415 For instance, if Pierre has posted an interesting message on his AP server, and Louise | |
416 wants to reply to it, she just use a client to reply on the comments node of this message, | |
417 this will be delivered as an AP object to Pierre's AP server. | |
418 | |
419 On the other hand, if Louise is publishing a new blog post on her XMPP server, Pierre will | |
420 receive corresponding AP object because he's following her. If Pierre answer using his AP | |
421 client, the corresponding message will be published on the comments node of the message | |
422 that Louise has initially published. | |
423 | |
424 Following, Subscribing and Cache | |
425 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
426 | |
427 When you try to access an uncached AP collection from XMPP (e.g. blog posts), a best | |
428 effort is done to translate XMPP pagination (which uses `XEP-0059 (Result Set | |
429 Management)`_) to the less powerful `AP Collection Paging`_. This is inefficient due to | |
430 technical limitations (page size can't be specified in AP, there is not standard way to | |
431 request item after or before a specific ID, implementations may not implement reverse | |
432 pagination). | |
433 | |
434 That's one of the reason why whenever possible, collections are cached locally. Once | |
435 cached, it's easier to return items according to complex requests. | |
436 | |
437 However, to cache correctly an AP collection, you need to keep it in sync, and thus to | |
438 receive update when something change (e.g. a new blog item is published). | |
439 | |
440 In AP, this is done by following an actor, in XMPP this correspond to a node subscription. | |
441 | |
442 When you subscribe to a blog node managed by this gateway, this will be translated to a | |
443 *follow* activity on AP side, and vice versa. | |
444 | |
445 When an AP actor is followed, its *outbox* collection (i.e. message published), are | |
446 automatically cached, and will be updated when events will be received. That means that | |
447 you can use pubsub cache search on followed actors, e.g. to retrieve all items about a | |
448 specific topic or published at specific time range. | |
449 | |
450 Reciprocally, unsubscribing from a node will *unfollow* the corresponding AP actor. | |
451 | |
452 If an AP actor is following or unfollowing an actor mapping an XMPP entity, they nodes | |
453 will be subscribed to or unsubscribed from. | |
454 | |
455 All subscriptions are made public as specified by `XEP-0465 (Pubsub Public Subscriptions)`_. | |
456 | |
457 .. _XEP-0059 (Result Set Management): https://xmpp.org/extensions/xep-0059.html | |
458 .. _AP Collection Paging: https://www.w3.org/TR/activitystreams-core/#h-paging | |
459 .. _XEP-0465 (Pubsub Public Subscriptions): https://xmpp.org/extensions/inbox/pubsub-public-subscriptions.html | |
460 | |
461 Following/Followers Collections and Public Pubsub Subscription | |
462 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
463 | |
464 The AP *following* collection is mapped to `XEP-0465 (Pubsub Public Subscriptions)`_. | |
465 | |
466 In the same spirit, the AP *followers* collection correspond to public subscribers to the | |
467 microblog node. | |
468 | |
469 Because AP doesn't send any event when *following* or *followers* collections are | |
470 modified, those collections can't be cached, and thus the translation to public pubsub | |
471 subscriptions is done as best as possible given the constraints. | |
413 | 472 |
414 Using the Component (for developers) | 473 Using the Component (for developers) |
415 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 474 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
416 | 475 |
417 Publication of AP items can be tested using the following method (with can be accessed | 476 Publication of AP items can be tested using the following method (with can be accessed |