Merge lp:~leonardr/lazr.restful/disable-cache into lp:lazr.restful

[Leonard Richardson]

This branch adds a configuration option enable_server_side_representation_cache, which lets you disable the representation cache without un-registering it. I'll be using this to control the memcached representation cache in Launchpad with a Launchpad configuration setting. I have two goals.

1) Make it possible to test the cache in staging without having to deploy different code to staging and production.
2) Make it easy for the LOSAs to disable the cache if something goes wrong in production.

=== modified file 'src/lazr/restful/NEWS.txt'
--- src/lazr/restful/NEWS.txt	2010-06-02 17:04:40 +0000
+++ src/lazr/restful/NEWS.txt	2010-06-03 14:51:24 +0000
@@ -2,8 +2,13 @@
 NEWS for lazr.restful
 =====================
 
-0.9.28 (Development)
-====================
+0.9.28 (2010-06-03)
+===================
+
+Special note: This version adds a new configuration element,
+'enable_server_side_representation_cache'. This lets you turn the
+representation cache on and off at runtime without unregistering the
+cache utility.
 
 Fixed some test failures.
 

=== modified file 'src/lazr/restful/_resource.py'
--- src/lazr/restful/_resource.py	2010-06-03 14:26:13 +0000
+++ src/lazr/restful/_resource.py	2010-06-03 14:51:24 +0000
@@ -1527,22 +1527,21 @@
         if media_type in [self.WADL_TYPE, self.DEPRECATED_WADL_TYPE]:
             return self.toWADL().encode("utf-8")
         elif media_type == self.JSON_TYPE:
-            cache = None
-            try:
-                cache = getUtility(IRepresentationCache)
+            cache = self._representation_cache
+            if cache is None:
+                representation = None
+            else:
                 representation = cache.get(
                     self.context, self.JSON_TYPE, self.request.version)
-            except ComponentLookupError:
-                # There's no representation cache.
-                representation = None
 
             redacted_fields = self.redacted_fields
             if representation is None:
-                # Either there is no cache, or the representation
+                # Either there is no active cache, or the representation
                 # wasn't in the cache.
                 representation = simplejson.dumps(self, cls=ResourceJSONEncoder)
-                # If there's a cache, and this representation doesn't
-                # contain any redactions, store it in the cache.
+                # If there's an active cache, and this representation
+                # doesn't contain any redactions, store it in the
+                # cache.
                 if cache is not None and len(redacted_fields) == 0:
                     cache.set(self.context, self.JSON_TYPE,
                               self.request.version, representation)
@@ -1569,6 +1568,19 @@
                     "No representation implementation for media type %s"
                     % media_type)
 
+    @property
+    def _representation_cache(self):
+        """Return the representation cache, or None if missing/disabled."""
+        try:
+            cache = getUtility(IRepresentationCache)
+        except ComponentLookupError:
+            # There's no representation cache.
+            return None
+        config = getUtility(IWebServiceConfiguration)
+        if config.enable_server_side_representation_cache:
+            return cache
+        return None
+
 
 class CollectionResource(BatchingResourceMixin,
                          CustomOperationResourceMixin,

=== modified file 'src/lazr/restful/example/base/tests/representation-cache.txt'
--- src/lazr/restful/example/base/tests/representation-cache.txt	2010-05-24 13:52:30 +0000
+++ src/lazr/restful/example/base/tests/representation-cache.txt	2010-06-03 14:51:24 +0000
@@ -259,7 +259,65 @@
     This representation is from the cache.
     This representation is from the cache.
 
-Cleanup: de-register the cache.
+enable_server_side_representation_cache
+=======================================
+
+A configuration setting allows you to disable the cache without
+de-registering it. This is useful when you're debugging a cache
+implementation or a cache invalidation algorithm.
+
+    >>> from lazr.restful.interfaces import IWebServiceConfiguration
+    >>> config = getUtility(IWebServiceConfiguration)
+    >>> print config.enable_server_side_representation_cache
+    True
+
+Set this configuration value to False, and representations will not be
+served from the cache, even if present.
+
+    >>> config.enable_server_side_representation_cache = False
+    >>> recipes = webservice.get("/recipes").jsonBody()['entries']
+    >>> for instructions in (
+    ...     sorted(recipe['instructions'] for recipe in recipes)):
+    ...     print instructions
+    A perfectly roasted chicken is...
+    Draw, singe, stuff, and truss...
+    Preheat oven to...
+    You can always judge...
+
+New representations will not be added to the cache.
+
+    >>> before_keys = len(dictionary.keys())
+    >>> dishes = webservice.get("/dishes")
+    >>> len(dictionary.keys()) == before_keys
+    True
+
+The cache is still registered as a utility.
+
+    >>> print getUtility(IRepresentationCache)
+    <lazr.restful.simple.DictionaryBasedRepresentationCache object ...>
+
+And it's still populated, as we can see by re-enabling it.
+
+    >>> config.enable_server_side_representation_cache = True
+    >>> recipes = webservice.get("/recipes").jsonBody()['entries']
+    >>> for instructions in (
+    ...     sorted(recipe['instructions'] for recipe in recipes)):
+    ...     print instructions
+    This representation is from the cache.
+    This representation is from the cache.
+    This representation is from the cache.
+    This representation is from the cache.
+
+Once re-enabled, new representations are once again added to the cache.
+
+    >>> dishes = webservice.get("/dishes")
+    >>> len(dictionary.keys()) > before_keys
+    True
+
+Cleanup
+=======
+
+De-register the cache.
 
     >>> sm.registerUtility(None, IRepresentationCache)
 

=== modified file 'src/lazr/restful/interfaces/_rest.py'
--- src/lazr/restful/interfaces/_rest.py	2010-05-24 13:00:07 +0000
+++ src/lazr/restful/interfaces/_rest.py	2010-06-03 14:51:24 +0000
@@ -409,6 +409,13 @@
         service root for the latest version (which probably changes more
         often).""")
 
+    enable_server_side_representation_cache = Bool(
+        title=u"Enable the server-side representation cache.",
+        default=True,
+        description=u"""If this is false, the server-side representation
+        cache will not be used, even if one is registered."""
+        )
+
     service_description = TextLine(
         title=u"Service description",
         description=u"""A human-readable description of the web service.