libervia-backend: doc/components.rst comparison

comparison doc/components.rst @ 3810:29380ef68dbe

doc (components): AP item retraction + blocking: fix 367

author	Goffi <goffi@goffi.org>
date	Fri, 17 Jun 2022 15:50:34 +0200
parents	24f70a29e382
children	23b53ac87e0f

comparison

equal deleted inserted replaced

-:04b57c0b2278
+:29380ef68dbe
 **example**
 If Louise wants to talk to Pierre which is on the ``example.net`` AP server, she can use
 her XMPP AP gateway which is at ``ap.example.org``. Pierre AP's actor identifier is
 ``pierre@example.net``, Louise can access it via the JID
-``pierre\40example.net@ap.example.org``.
+``pierre\40example.net@ap.example.org`` (we call it *virtual JID* of the AP actor).
 Of course, this is a bit cumbersome to do by hand, it is expected that XMPP clients will
 do the (un)escaping automatically for end-user, in a way that Louise could enter
 ``pierre@example.net`` directly, with an indicator to show that this is an ActivityPub
 actor identifier rather than an XMPP JID.
 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.
+.. _ap-message_delivery:
 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.
 .. _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
+Message/Item Retraction
+~~~~~~~~~~~~~~~~~~~~~~~
+If you retract a pubsub item (e.g. a blog post), that is followed by ActivityPub actors,
+a suitable `Delete` activity will be emitted. In other words, the ActivityPub servers will
+be notified of the retraction.
+Similarly if an AP actor is deleting an item, a suitable `XEP-0060 retraction event`_ will
+be sent to subscribers.
+In the case of direct messages (see :ref:`ap-message_delivery`), `XEP-0424 (Message
+Retraction)`_ is used in both reception (AP ``Delete`` activity is converted to XEP-0424
+and vice versa).
+All of this should be transparent to users as long as their clients support the mentioned
+XEPs.
+.. note::
+When retracting a message/item, a retraction request (or equivalent AP "Delete"
+activity) is sent, so the other end clients **may** delete the item.
+However, there is no way to be sure that the item will be actually deleted: once
+something is sent on the network, any recipient can see it, copy it, share it, etc.
+There is no way to forbid that, and this is true for software, decentralized or not
+(and not only ActivityPub or XMPP).
+Be sure to understand that before sending anything sensitive.
+.. note::
+When deleting an item on ActivityPub, the item is often replaced by a "tombstone", and
+it's not possible to send a new item with the same ID. Some software (it's at least the
+case with Mastodon), will silently reject the item, and thus people won't see it.
+This is a different behaviour from XMPP where you can publish a pubsub item, retract
+it, and publish a new item with the same ID.
+Thus if you retract an item, be sure to publish any new one with new and unique ID,
+otherwise the item may not appear to ActivityPub users (and as the item may be rejected
+silently, you may not be notified).
+However this should not be a problem in the vast majority of cases, as most XMPP client
+implementing pubsub or pubsub service will generate automatically unique IDs for new
+items.
+.. _XEP-0060 retraction event: https://xmpp.org/extensions/xep-0060.html#publisher-delete
+.. _XEP-0424 (Message Retraction): https://xmpp.org/extensions/xep-0424.html
+Blocking an User
+~~~~~~~~~~~~~~~~
+You can block AP actors using :ref:`its virtual JID <ap-actor-from-xmpp>` in the same way
+as for any XMPP entity, by using `XEP-0191 (Blocking Command)`_.
+This is done at the XMPP server level and your server must support it. From client side,
+many clients support it, and you can use Libervia CLI to do it from command-line (see
+:ref:`libervia-cli_blocking`).
+.. _XEP-0191 (Blocking Command): https://xmpp.org/extensions/xep-0191.html
 Using the Component (for developers)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Publication of AP items can be tested using the following method (with can be accessed
 through the ``APSend`` bridge method, client is then replaced by the ``profile`` name, as

Mercurial > libervia-backend

comparison doc/components.rst @ 3810:29380ef68dbe