.. _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.

.. note::

    Use this command with caution: even if cache will be re-constructed with time, that
    means that items will have to be retrieved again, that may be resource intensive both
    for your machine and for the pubsub services which will be used. That also means that
    searching items will return less results until all desired items are cached again.

    Also note that all items of cached nodes are retrieved, even if you have previously
    purged items, they will be retrieved again.

example
-------

Reset the whole pubsub cache::

    $ li pubsub cache reset