From f7eb0a8a8ca8d442f9869ac79b0086a2e17b6939 Mon Sep 17 00:00:00 2001
From: Sam Whited <sam@samwhited.com>
Date: Tue, 1 Sep 2015 19:54:32 -0500
Subject: [PATCH] Add cache invalidation to entity versioning

---
 inbox/entityversioning.xml | 55 +++++++++++++++++++++++++++++++++++---
 1 file changed, 52 insertions(+), 3 deletions(-)

diff --git a/inbox/entityversioning.xml b/inbox/entityversioning.xml
index 45451591..8546d25a 100644
--- a/inbox/entityversioning.xml
+++ b/inbox/entityversioning.xml
@@ -52,9 +52,13 @@
     which was later merged into &rfc6121; §2.6. While this solved the problem
     for the roster, it didn't account for other entities (eg. disco items).
     Furthermore, roster versioning requires that the server maintain a great
-    deal of state (multiple versions of the roster) which can be difficult to
-    implement in a large, distributed system. This XEP defines a method by
-    which entities other than the roster can be versioned and cached.
+    deal of state (roster items which should be pushed for each entity on
+    reconnect, or monotonically increasing counters, etc.) which can be
+    difficult to store or synchronize in a large, distributed system. This XEP
+    defines a method by which the roster and entities other than the roster can
+    be versioned and cached, and which is optimized for distributed systems
+    with large enity lists (but works equally well on small, single server
+    deployments).
   </p>
 </section1>
 
@@ -268,6 +272,51 @@
     question when a version token is received.
   </p>
 </section2>
+<section2 topic='Cache Invalidation' anchor='deletes'>
+  <p>
+    When a client syncs with the server and indicates that it has a version
+    token in its cache that does not match any entity on the server (or when
+    the server wants to remove an entity from the clients cache for any other
+    reason), the server MUST reply with an empty &lt;version/&gt; node. When
+    the client receives such an empty version node it SHOULD purge the entity
+    from its cache. For example, the following exchange would trigger the
+    removal of 'inverness@chat.shakespeare.lit' from the cached MUC list:
+
+    <example caption="MUC deletion"><![CDATA[
+<!-- Client -->
+<iq from='hag66@shakespeare.lit/phone'
+    id='zb8q41fas6yn4'
+    to='chat.shakespeare.lit'
+    type='get'>
+  <query xmlns='http://jabber.org/protocol/disco#items>
+    <item jid='coven@chat.shakespeare.lit'>
+      <version xmlns='urn:xmpp:entityver:0'>25P2A7H8</version>
+    </item>
+    <item jid='inverness@chat.shakespeare.lit'>
+      <version xmlns='urn:xmpp:entityver:0'>4OLGSVNY</version>
+    </item>
+  </query>
+</iq>
+
+<!-- Server -->
+<iq from='chat.shakespeare.lit'
+  id='zb8q41fas6yn4'
+  to='hag66@shakespeare.lit/phone'
+  type='result'>
+  <query xmlns='http://jabber.org/protocol/disco#items'>
+    <item jid='inverness@chat.shakespeare.lit'>
+      <version xmlns='urn:xmpp:entityver:0'/>
+    </item>
+  </query>
+</iq>
+    ]]></example>
+  </p>
+  <p>
+    If the client receives an indication that it should delete an item from a
+    list by any other means (eg. via a roster push), it SHOULD remove the
+    version token associated with that entity from its cache.
+  </p>
+</section2>
 <section2 topic='Aggregate Tokens' anchor='agg_tokens'>
   <p>
     While the version token approach to caching does not require a great deal