# HG changeset patch
# User Goffi <goffi@goffi.org>
# Date 1655473834 -7200
# Node ID 29380ef68dbe611ee8bc9b603566fa616c39172e
# Parent  04b57c0b2278a78f330339483acee37f449e23f7
doc (components): AP item retraction + blocking:

fix 367

diff -r 04b57c0b2278 -r 29380ef68dbe doc/components.rst
--- a/doc/components.rst	Fri Jun 17 15:50:34 2022 +0200
+++ b/doc/components.rst	Fri Jun 17 15:50:34 2022 +0200
@@ -257,7 +257,7 @@
 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
@@ -470,6 +470,8 @@
 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
 ~~~~~~~~~~~~~~~~~
 
@@ -521,6 +523,67 @@
 .. _*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)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff -r 04b57c0b2278 -r 29380ef68dbe doc/libervia-cli/blocking.rst
--- a/doc/libervia-cli/blocking.rst	Fri Jun 17 15:50:34 2022 +0200
+++ b/doc/libervia-cli/blocking.rst	Fri Jun 17 15:50:34 2022 +0200
@@ -1,3 +1,5 @@
+.. _libervia-cli_blocking:
+
 ===========================
 blocking: entities blocking
 ===========================