Mercurial > libervia-backend
changeset 3786:cebfdfff3e99
doc (components): message delivery documentation:
fix 366
author | Goffi <goffi@goffi.org> |
---|---|
date | Tue, 24 May 2022 17:57:41 +0200 (2022-05-24) |
parents | 0b54be42d0aa |
children | f8a0f3b65371 |
files | doc/components.rst |
diffstat | 1 files changed, 51 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- 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) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~