doc (cli/pubsub): document pubsub cache management commands

doc/libervia-cli/pubsub.rst

@@ -33,6 +33,8 @@ Create an item with a custom note XML::
 
   $ echo '<note xmlns="http://example.net/mynotes">this is a note</note>' | li pubsub set -n "notes"
 
+.. _li_pubsub_get:
+
 get
 ===
 
@@ -331,7 +333,7 @@ returned.
 example
 -------
 
-Imagine that you want to replace all occurrences of "sàt" by "Libervia" in your personal blog. You first create a Python script like this:
+Imagine that you want to replace all occurrences of "SàT" by "Libervia" in your personal blog. You first create a Python script like this:
 
 .. sourcecode:: python
 
@@ -339,10 +341,10 @@ Imagine that you want to replace all occurrences of "sàt" by "Libervia" in your
 
    import sys
    item_raw = sys.stdin.read()
-   if not "sàt" in item_raw:
+   if not "SàT" in item_raw:
        print("SKIP")
    else:
-       print(item_raw.replace("sàt", "Libervia"))
+       print(item_raw.replace("SàT", "Libervia"))
 
 And save it a some location, e.g. ``~/expand_sat.py`` (don't forget to make is executable
 with ``chmod +x ~/expand_sat.py``).
@@ -381,3 +383,8 @@ hook
 ====
 
 Subcommands for hooks management. Please check :ref:`libervia-cli_pubsub_hook`.
+
+cache
+=====
+
+Subcommands for cache management. Please check :ref:`libervia-cli_pubsub_cache`.

doc/libervia-cli/pubsub_cache.rst

@@ -0,0 +1,98 @@
+.. _libervia-cli_pubsub_cache:
+
+=====================================
+pubsub/cache: PubSub Cache Management
+=====================================
+
+Libervia runs transparently a cache for pubsub. That means that according to internal
+criteria, some pubsub items are stored locally.
+
+The ``cache`` subcommands let user inspect and manipulate the internal cache.
+
+get
+===
+
+Retrieve items from internal cache only. Most end-users won't need to use this command, as
+the usual ``pubsub get`` command will use cache transparently. However, it may be useful
+to inspect local cache, notably for debugging.
+
+The parameters are basically the same as for :ref:`li_pubsub_get`.
+
+example
+-------
+
+Retrieve the last 2 cached items for personal blog::
+
+    $ li pubsub cache get -n urn:xmpp:microblog:0 -M 2
+
+.. _li_pubsub_cache_sync:
+
+sync
+====
+
+Synchronise or resynchronise a pubsub node. If the node is already in cache, it will be
+deleted then re-cached. Node will be put in cache even if internal policy doesn't request
+a synchronisation for this kind of nodes. Node will be (re-)subscribed to keep cache
+synchronised.
+
+All items of the node (up to the internal limit which is high), will be retrieved and put
+in cache, even if a previous version of those items have been deleted by the
+:ref:`li_pubsub_cache_purge` command.
+
+
+example
+-------
+
+Resynchronise personal blog::
+
+    $ li pubusb cache sync -n urn:xmpp:microblog:0
+
+.. _li_pubsub_cache_purge:
+
+purge
+=====
+
+Remove items from cache. This may be desirable to save resource, notably disk space.
+
+Note that once a pubsub node is cached, the cache is the source of trust. That means that
+if cache is not explicitly bypassed when retrieving items of a pubsub node (notably with
+the ``-C, --no-cache`` option of :ref:`li_pubsub_get`), only items found in cache will be
+returned, thus purged items won't be used or returned anymore even if they still exists on
+the original pubsub service.
+
+If you have purged items by mistake, it is possible to retrieve them either node by node
+using :ref:`li_pubsub_cache_sync`, or by resetting the whole pubsub cache with
+:ref:`li_pubsub_cache_reset`.
+
+If you have a node or a profile (e.g. a component) caching a lot of items frequently, you
+may use this command using a scheduler like cron_.
+
+.. _cron: https://en.wikipedia.org/wiki/Cron
+
+examples
+--------
+
+Remove all blog and event items from cache if they haven't been updated since 6 months::
+
+    $ li pubsub cache purge -t blog -t event -b "6 months ago"
+
+Remove items from profile ``ap_gateway`` if they have been created more that 2 months
+ago::
+
+    $ li pubsub cache purge -p ap_gateway --created-before "2 months ago"
+
+.. _li_pubsub_cache_reset:
+
+reset
+=====
+
+Reset the whole pubsub cache. This means that all nodes and all them items will be removed
+from cache. After this command, cache will be re-filled progressively as if it where a new
+one.
+
+example
+-------
+
+Reset the whole pubsub cache::
+
+    $ li pubsub cache reset

doc/libervia-cli/pubsub_hook.rst

@@ -4,7 +4,7 @@
 pubsub/hook: PubSub hooks management
 ====================================
 
-``hook`` is a subcommands grouping all PubSub commands related to hooks management. Hooks
+``hook`` is a subcommand grouping all PubSub commands related to hooks management. Hooks
 are user actions launched on specific events.
 
 3 types of hooks can be used: