# HG changeset patch
# User Goffi <goffi@goffi.org>
# Date 1652463252 -7200
# Node ID 98ba02637436c1bfa18d507e45977266846acd96
# Parent  e597dbfbc4c6714a3322c6e6a4768e4faaf5d8e3
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

diff -r e597dbfbc4c6 -r 98ba02637436 doc/components.rst
--- a/doc/components.rst	Fri May 13 19:32:06 2022 +0200
+++ b/doc/components.rst	Fri May 13 19:34:12 2022 +0200
@@ -340,17 +340,11 @@
    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.
+   will then be cached, and efficiently delivered.
 
    .. _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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -410,6 +404,71 @@
 
 .. _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)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~