# HG changeset patch
# User Goffi <goffi@goffi.org>
# Date 1653407861 -7200
# Node ID cebfdfff3e99c722a7c3ac706a187d0fee9bc350
# Parent  0b54be42d0aaee684a35281dd887a79ad3f4d3b9
doc (components): message delivery documentation:

fix 366

diff -r 0b54be42d0aa -r cebfdfff3e99 doc/components.rst
--- a/doc/components.rst	Tue May 24 17:57:39 2022 +0200
+++ b/doc/components.rst	Tue May 24 17:57:41 2022 +0200
@@ -470,6 +470,57 @@
 modified, those collections can't be cached, and thus the translation to public pubsub
 subscriptions is done as best as possible given the constraints.
 
+Messages Delivery
+~~~~~~~~~~~~~~~~~
+
+The gateway can convert AP publications to either XMPP pubsub items (using `XEP-0277
+(Microblogging over XMPP)`_ when suitable) or to XMPP messages (`<message>` stanzas, i.e.
+the ones used for instant messaging). Of course it also convert in a similar way in the
+other direction (XMPP → ActivityPub).
+
+A received AP items will be converted to an XMPP pubsub item if any of the following
+condition is fulfilled:
+
+  - it is addressed to the special `*public* collection`_
+  - it is addressed to a local *followers* collection
+
+A received AP item will be convert to an XMPP message if all the following condition are
+fulfilled:
+
+  - it is **not** addressed to the special *public* collection
+  - it is **not** addressed to a any local *followers* collection.
+
+In other words, if an AP items is addressed directly to one or more local users, is not
+public and is not addressed to a *followers* collection, it will be converted to an XMPP
+message, otherwise it will be converted to an XMPP pubsub item.
+
+The behaviour is symmetric, thus if you send an XMPP message it will be converted to an AP
+item which will be only addressed to your recipient. If you write using XMPP pubsub, the
+suitable followers collections of the target AP actor will be automatically added, and the
+item will have the special *public* collection added.
+
+.. note::
+
+   ActivyPub doesn't do any kind of `end-to-end encryption`_, it is **not** the same level of
+   privacy as XMPP.
+
+   Messages will be at minimum readable by the administrators of the AP gateway and of the
+   ActivyPub server of the destinee. Be sure to understand that before sending messages.
+
+   If you need more privacy, you need to use either XMPP only (without the ActivityPub
+   gateway) with clients implementing correctly end-to-end encryption, or an other
+   software. Depending of the level of pricacy required, you may want to use
+   authentication by a separated channel, a client which has been audited, encryption by
+   default, etc. This is beyond the scope of this AP gateway documentation.
+
+   In short, don't use ActivityPub if you need a high level of privacy. This is a current
+   protocol limitation, and there is nothing that this gateway can do about this until
+   ActivityPub and its implementations evolve.
+
+.. _XEP-0277 (Microblogging over XMPP): https://xmpp.org/extensions/xep-0277.html
+.. _*public* collection: https://www.w3.org/TR/activitypub/#public-addressing
+.. _end-to-end encryption: https://en.wikipedia.org/wiki/End-to-end_encryption
+
 Using the Component (for developers)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~