added docs about cache invalidation

1 files changed, 48 insertions, 0 deletions

diff --git a/doc/development/plugins.txt b/doc/development/plugins.txt
index 5a1ceb885..59582e255 100644
--- a/doc/development/plugins.txt
+++ b/doc/development/plugins.txt
@@ -94,6 +94,54 @@ functions, you could run::
 
     bcfg2-admin xcmd Packages.Refresh
 
+Invalidating Caches
+-------------------
+
+.. versionadded:: 1.3.0
+
+In Bcfg2 1.3.0, some limited :ref:`server-caching` was introduced.  If
+you are writing a :class:`Bcfg2.Server.Plugin.interfaces.Connector`
+plugin that implements
+:func:`Bcfg2.Server.Plugin.interfaces.Connector.get_additional_groups`,
+then you need to be able to invalidate the server metadata cache in
+order to be compatible with the ``cautious`` or ``aggressive`` caching
+modes.
+
+The two attributes you need to know about are:
+
+* :attr:`Bcfg2.Server.Core.metadata_cache_mode`: A string description
+  of the caching mode.  See :ref:`server-caching` for a description of
+  each mode.
+* :attr:`Bcfg2.Server.Core.metadata_cache`: A dict-like
+  :class:`Bcfg2.Cache.Cache` object that stores the cached data.
+
+:class:`Bcfg2.Server.Plugin.base.Plugin` objects have access to the
+:class:`Bcfg2.Server.Core` object as ``self.core``.  In general,
+you'll be interested in the :func:`Bcfg2.Cache.Cache.expire` method;
+if called with no arguments, it expires all cached data; if called
+with one string argument, it expires cached data for the named client.
+
+It's important, therefore, that your Connector plugin can either track
+when changes are made to the group membership it reports, and expire
+cached data appropriately when in ``cautious`` or ``aggressive`` mode;
+or prudently flag an incompatibility with those two modes.
+
+For examples, see:
+
+* :func:`Bcfg2.Server.Plugins.Probes.ReceiveData` takes a copy of the
+  groups that have been assigned to a client by
+  :ref:`server-plugins-probes-index`, and if that data changes when
+  new probe data is received, it invalidates the cache for that
+  client.
+* :func:`Bcfg2.Server.Plugins.GroupPatterns.Index` expires the entire
+  cache whenever a FAM event is received for the
+  :ref:`server-plugins-grouping-grouppatterns` config file.
+* :func:`Bcfg2.Server.Plugins.PuppetENC.end_client_run` expires the
+  entire cache at the end of every client run and produces a message
+  at the warning level that the
+  :ref:`server-plugins-connectors-puppetenc` plugin is incompatible
+  with aggressive caching.
+
 Plugin Helper Classes
 ---------------------