libervia-backend: doc/components.rst comparison

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

-:e597dbfbc4c6
+:98ba02637436
 .. 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
+will then be cached, and efficiently delivered.
-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
 This way, admins can configure the model which suits best the clients which is expected to
 be mainly used on the instance.
 .. _XEP-0277 comments: https://xmpp.org/extensions/xep-0277.html#comments
+Publishing an Item
+~~~~~~~~~~~~~~~~~~
+To publish a new item (e.g. a blog post), you just need to publish normally on your own
+PEP/pubsub node, AP actors following you will be notified. To reply to an AP item, just
+publish to the corresponding pubsub node managed by the gateway. This is transparent for
+AP and XMPP end users.
+For instance, if Pierre has posted an interesting message on his AP server, and Louise
+wants to reply to it, she just use a client to reply on the comments node of this message,
+this will be delivered as an AP object to Pierre's AP server.
+On the other hand, if Louise is publishing a new blog post on her XMPP server, Pierre will
+receive corresponding AP object because he's following her. If Pierre answer using his AP
+client, the corresponding message will be published on the comments node of the message
+that Louise has initially published.
+Following, Subscribing and Cache
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When you try to access an uncached AP collection from XMPP (e.g. blog posts), a best
+effort is done to translate XMPP pagination (which uses `XEP-0059 (Result Set
+Management)`_) to the less powerful `AP Collection Paging`_. This is inefficient due to
+technical limitations (page size can't be specified in AP, there is not standard way to
+request item after or before a specific ID, implementations may not implement reverse
+pagination).
+That's one of the reason why whenever possible, collections are cached locally. Once
+cached, it's easier to return items according to complex requests.
+However, to cache correctly an AP collection, you need to keep it in sync, and thus to
+receive update when something change (e.g. a new blog item is published).
+In AP, this is done by following an actor, in XMPP this correspond to a node subscription.
+When you subscribe to a blog node managed by this gateway, this will be translated to a
+*follow* activity on AP side, and vice versa.
+When an AP actor is followed, its *outbox* collection (i.e. message published), are
+automatically cached, and will be updated when events will be received. That means that
+you can use pubsub cache search on followed actors, e.g. to retrieve all items about a
+specific topic or published at specific time range.
+Reciprocally, unsubscribing from a node will *unfollow* the corresponding AP actor.
+If an AP actor is following or unfollowing an actor mapping an XMPP entity, they nodes
+will be subscribed to or unsubscribed from.
+All subscriptions are made public as specified by `XEP-0465 (Pubsub Public Subscriptions)`_.
+.. _XEP-0059 (Result Set Management): https://xmpp.org/extensions/xep-0059.html
+.. _AP Collection Paging: https://www.w3.org/TR/activitystreams-core/#h-paging
+.. _XEP-0465 (Pubsub Public Subscriptions): https://xmpp.org/extensions/inbox/pubsub-public-subscriptions.html
+Following/Followers Collections and Public Pubsub Subscription
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The AP *following* collection is mapped to `XEP-0465 (Pubsub Public Subscriptions)`_.
+In the same spirit, the AP *followers* collection correspond to public subscribers to the
+microblog node.
+Because AP doesn't send any event when *following* or *followers* collections are
+modified, those collections can't be cached, and thus the translation to public pubsub
+subscriptions is done as best as possible given the constraints.
 Using the Component (for developers)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Publication of AP items can be tested using the following method (with can be accessed

Mercurial > libervia-backend

comparison doc/components.rst @ 3772:98ba02637436