Move plone.app.caching documentation to deployment/caching

Author: ericof

docs/_static/caching/ControlPanel-01.png

@@ -0,0 +1,19 @@
+# Composite views
+
+A `composite view` is just a general term for most page views you see when you visit a Plone site.
+
+It includes all content item views, content folder views, and many template views.
+
+For our purposes, the distinguishing characteristic of composite views is the difficulty inherent in keeping track of all changes that might affect the final composited view.
+
+Because of the difficulty of dependency tracking, composite views are often notoriously difficult to purge reliably from caching proxies so the default caching profiles set headers which expire the cache immediately (i.e. *weak caching*).
+
+However, most of the inline resources linked to from the composite view (css, javascript, images, etc.) can be cached very well in proxy so the overall speed of most composite views will always be better with a caching proxy in front despite the page itself not being cached.
+
+For relatively stable composite views or for those views for which you can tolerate some potential staleness, you might be tempted to try switching from *weak caching* to *moderate caching* with the `s-maxage` expiration value set to some tolerable value but first make sure you understand the issues regarding "split view" caching (see below).
+
+A way to speedup a site with lots of composite view is to use "Terse" caching.
+
+It caches a page for just a small time (be default 10s in browser and 60s in the caching proxy).
+
+Thus the content is almost up to date, but on high load visitors are getting pages served from the cache.

docs/_static/caching/ControlPanel-02.png

@@ -0,0 +1,63 @@
+---
+myst:
+  html_meta:
+    "description": "Control panel for Plone caching"
+    "property=og:description": "Control panel for Plone caching"
+    "property=og:title": "Caching Control Panel"
+    "keywords": "Plone, deployment, automation, caching"
+---
+
+(caching-control-panel-label)=
+
+# Control panel
+
+The Caching control panel in Plone's `Site Setup` supports a granular control of caching operations for a Plone site.
+
+```{image} /_static/caching/ControlPanel-02.png
+:alt: Plone Control Panel (Classic UI)
+```
+
+This control panel consists of four main tabs:
+
+## `Change settings`
+
+Where you can control caching behaviour, it contains four fieldsets:
+
+### `Global settings`
+
+For global options such as turning caching on or off.
+
+### `Caching proxies`
+
+Where you can control Plone's use of a caching proxy such or Varnish or a CDN.
+
+### `In-memory caache`
+
+Where you can control Plone's use of in-memory cache.
+
+### `Caching operation`
+
+Where caching rulesets (hints about views and resources used for caching purposes) can be associated with caching operations.
+
+Those either intercept a request to return a cached response, or modifies a response to add cache control headers.
+
+This is also where rulesets for legacy page templates (created through the web or the  portal_skins tool) are configured.
+
+### `Detailed settings`
+
+Where you can configure parameters for individual caching operations.
+
+
+## `Import settings`
+
+Where you can import pre-defined profiles of cache settings
+
+## `Purge caching proxy`
+
+Where you can manually purge content from a caching proxy.
+
+This tab only appears if you have purging enabled under *Change settings*.
+
+## `RAM cache`
+
+Where you can view statistics about and purge the RAM cache.

docs/_static/caching/ControlPanel-03.png

@@ -0,0 +1,51 @@
+---
+myst:
+  html_meta:
+    "description": "Caching Plone: Enable cache support"
+    "property=og:description": "Enabling caching support for Plone"
+    "property=og:title": "Caching Plone: Enabling support"
+    "keywords": "Plone, deployment, automation, caching"
+---
+
+(caching-installation-label)=
+
+# Installation
+
+Caching support is implemented by the package `plone.app.caching`, which is already shipped as a dependency of the *Plone* package, and it should be available on all Plone installations.
+
+Even though Caching support is available in Plone, it is **not enabled by default**, although it is highly recommended to configure caching for every new Plone site in production.
+
+## Enable Caching
+
+Under the Advanced header, look for the `Caching` control panel -- currently only supported on the Classic UI -- and select it.
+
+```{image} /_static/caching/ControlPanel-01.png
+:alt: Plone Control Panel (Classic UI)
+```
+
+In the Caching control panel, the tab `Change settings` is selected and inside of it the tab `Global settings` have the option to **Enable caching** (disable by default)
+
+```{image} /_static/caching/ControlPanel-02.png
+:alt: Caching Control Panel with caching disabled
+```
+
+To enable caching, just click the checkbox:
+
+```{image} /_static/caching/ControlPanel-03.png
+:alt: Caching Control Panel with caching enabled
+```
+
+## Troubleshooting
+
+When the Caching control panel is not there, there can be various reasons for this:
+
+- If your installation does not load the `Plone` package, but only `Products.CMFPlone`, then `plone.app.caching` is not included.
+- If the package *is* included, but you add a Plone Site using the advanced form and disable caching, then the control panel is not there.
+
+If you want to install it in an existing Plone Site:
+
+1. Make sure the package is available in the Plone instance, by adding `plone.app.caching` or `Plone` to your installation.
+2. From the Plone Site Setup go to the ZMI (Zope Management Interface).
+3. Go to ``portal_setup``, and then to the Import tab.
+4. Select the HTTP caching support profile, perhaps easiest by id: `profile-plone.app.caching:default`.
+5. Click 'Import all steps'.

docs/deployment/caching/composite-views.md

@@ -0,0 +1,75 @@
+---
+myst:
+  html_meta:
+    "description": "ETags support for Plone caching"
+    "property=og:description": "ETags support for Plone caching"
+    "property=og:title": "ETags support for Plone"
+    "keywords": "Plone, deployment, automation, caching"
+---
+
+(caching-etags-label)=
+
+# ETags
+
+ETags are used in to check whether pages need to be re-calculated or can be served from cache.
+An ETag is simply a string. Under `plone.app.caching`, it is a string of tokens separated by pipe characters.
+The tokens hold values such as a user id, the current skin name, or a counter indicating how many objects have been added to the site.
+The idea is that the browser sends a request with the ETag included in an `If-None-Match` header.
+Plone can then quickly calculate the current ETag for the requested resource.
+If the ETag is the same, Plone can reply with `304 NOT MODIFIED` response, telling the browser to use its cached copy.
+Otherwise, Plone renders the page and returns it as normal.
+
+Many caching operations use ETags. The tokens to include are typically listed in an `etags` tuple in the operation's options.
+
+## Default tokens
+
+The ETag names tokens supported by default are:
+
+| etag | description |
+| --- | --- |
+| userid | The current user's id .|
+| roles | A list of the current user's roles in the given context. |
+| language | The language(s) accepted by the browser, in the `ACCEPT_LANGUAGE` header. |
+| userLanguage | The current user's preferred language. |
+| lastModified | A timestamp indicating the last-modified date of the given context. |
+| catalogCounter | A counter that is incremented each time the catalog is updated. I.e. each time content in the site is changed. |
+| locked | Whether or not the given context is locked for editing. |
+| skin | The name of the current skin (theme). |
+| resourceRegistries | A timestamp indicating the last-modified timestamp for the Resource Registries. This is useful for avoiding requests for expired resources from cached pages. |
+
+## Additional tokens
+
+It is possible to provide additional tokens by registering an `IETagValue` adapter.
+
+This should be a named adapter on the published object (typically a view, file resource or Zope page template object) and request, with a unique name.
+
+The name is used to look up the component. Thus, you can also override one of the tokens above for a particular type of context or request (e.g. via a browser layer), by registering a more specific adapter with the same name.
+
+As an example, here is the `language` adapter:
+
+```python
+from plone.app.caching.interfaces import IETagValue
+from zope.component import adapter
+from zope.interface import implementer
+from zope.interface import Interface
+
+@implementer(IETagValue)
+@adapter(Interface, Interface)
+class Language:
+    """The `language` etag component, returning the value of the
+    HTTP_ACCEPT_LANGUAGE request key.
+    """
+
+    def __init__(self, published, request):
+        self.published = published
+        self.request = request
+
+    def __call__(self):
+        return self.request.get('HTTP_ACCEPT_LANGUAGE', '')
+```
+
+This is registered in `ZCML` like so:
+
+```xml
+<adapter factory=".etags.Language" name="language" />
+```

docs/deployment/caching/control-panel.md

@@ -0,0 +1,41 @@
+---
+myst:
+  html_meta:
+    "description": "Caching Plone"
+    "property=og:description": "Caching Plone"
+    "property=og:title": "Caching Plone"
+    "keywords": "Plone, deployment, automation, caching"
+---
+
+(caching-label)=
+
+# Caching
+
+## Overview
+
+HTTP caching is a technique used to speed up the delivery of web content by storing previously requested resources (such as images, scripts, and stylesheets) in a cache. When a user requests a resource, the cache can serve the resource directly from its storage, rather than having to fetch it from the original source.
+
+It is possible to use a web accelerator, like {term}`Varnish` or {term}`Squid`, to implement HTTP caching in your own premises. The usual setup will have the web accelerator installed between Plone and the Internet, and when a request is made to the site the web accelerator will intercept the request and check to see if it has a cached copy of the requested resource. If a cached copy is found, the accelerator will serve the cached copy directly to the client, otherwise it will make a request to the backend Plone server and then store a copy on the content in its local cache.
+
+A Content Delivery Network (CDN) can also be used to implement the HTTP caching and speed up the delivery of web content. A CDN is a network of servers located in multiple geographic regions that work together to deliver web content to users more quickly and efficiently. When a user requests a resource from a website that is using a CDN, the request is routed to the nearest server in the CDN, rather than having to travel all the way to the website's origin server.
+
+## Plone support
+
+Plone, since version 4.1, ships with a powerful and extensible `HTTP` and `In-Memory` cache support, implemented by the package `plone.app.caching`.
+
+
+```{toctree}
+:maxdepth: 2
+:hidden: true
+
+enable
+control-panel
+profiles
+rulesets-and-caching-operations
+proxies
+ram-cache
+etags
+composite-views
+split-views
+restapi
+```

docs/deployment/caching/enable.md

@@ -0,0 +1,116 @@
+---
+myst:
+  html_meta:
+    "description": "Caching profiles for Plone"
+    "property=og:description": "Caching profiles for Plone"
+    "property=og:title": "Caching profiles for Plone"
+    "keywords": "Plone, deployment, automation, caching"
+---
+
+(caching-profiles-label)=
+
+# Caching profiles
+
+All persistent configuration for the caching machinery is stored in the configuration registry, as managed by `plone.app.registry`.
+
+This can be modified using the `registry.xml` GenericSetup import step.
+
+The *Import settings* tab of the control panel allows you to import these caching profiles.
+
+
+## Default caching profiles
+
+`plone.app.caching` includes three default caching profiles.
+
+Two of these  profiles encapsulate the cache settings that are known to work well with a typical default Plone installation:
+
+### Without caching proxy
+
+Settings useful for setups without a caching proxy.
+
+### With caching proxy
+
+Settings useful for setups with a caching proxy such as Squid or Varnish.
+The only difference from the "without caching proxy" profile are some settings to enable proxy caching of files/images in content space and content feeds.
+
+## Custom caching profiles
+
+Caching policies are often a compromise between speed and freshness.
+More aggressive caching often comes at the cost of increased risk of stale responses.
+The default profiles provided tend to err on the side of freshness over speed so there is some room for tweaking if greater speed is desired.
+
+Customization may also be needed if third-party products are installed which require special treatment.
+Examine the HTTP response headers to determine whether the third-party product requires special treatment.
+Most simple cases probably can be solved by adding the content type or template to the appropriate mapping.
+More complicated cases, may require custom caching operations.
+
+A GenericSetup profile used for caching should be registered for the `ICacheProfiles` marker interface to distinguish it from more general profiles used to install a product.
+This also hides the profile from Plone's Add-ons control panel.
+
+Here is an example from this package:
+
+```xml
+    <genericsetup:registerProfile
+        name="with-caching-proxy"
+        title="With caching proxy"
+        description="Settings useful for setups with a caching proxy such as Squid or Varnish"
+        directory="profiles/with-caching-proxy"
+        provides="Products.GenericSetup.interfaces.EXTENSION"
+        for="plone.app.caching.interfaces.ICacheProfiles"
+        />
+```
+
+The directory `profiles/with-caching-proxy` contains a single import step, `registry.xml`,
+containing settings to configure the ruleset to operation mapping,
+and setting options for various operations.
+
+At the time of writing, this includes:
+
+```xml
+    <record name="plone.caching.interfaces.ICacheSettings.operationMapping">
+        <value purge="False">
+            <element key="plone.resource">plone.app.caching.strongCaching</element>
+            <element key="plone.stableResource">plone.app.caching.strongCaching</element>
+            <element key="plone.content.itemView">plone.app.caching.weakCaching</element>
+            <element key="plone.content.feed">plone.app.caching.moderateCaching</element>
+            <element key="plone.content.folderView">plone.app.caching.weakCaching</element>
+            <element key="plone.content.file">plone.app.caching.moderateCaching</element>
+            <element key="plone.content.dynamic">plone.app.caching.terseCaching</element>
+        </value>
+    </record>
+```
+
+Default options for the various standard operations are found in the `registry.xml` file that is part of the standard installation profile for this product, in the directory `profiles/default`.
+
+The custom profile overrides a number of operation settings for specific rulesets (see below).
+
+For example:
+
+```xml
+    <record name="plone.app.caching.weakCaching.plone.content.itemView.ramCache">
+        <field ref="plone.app.caching.weakCaching.ramCache" />
+        <value>True</value>
+    </record>
+```
+
+This enables RAM caching for the "weak caching" operation for resources using the ruleset `plone.content.itemView`.
+The default is defined in the main `registry.xml` as::
+
+```xml
+    <record name="plone.app.caching.weakCaching.ramCache">
+        <field type="plone.registry.field.Bool">
+            <title>RAM cache</title>
+            <description>Turn on caching in Zope memory</description>
+            <required>False</required>
+        </field>
+        <value>False</value>
+    </record>
+```
+
+Notice how we use a *field reference* to avoid having to re-define the field.
+
+It may be useful looking at these bundled `registry.xml` for inspiration if you are building your own caching profile.
+Alternatively, you can export the registry from the `portal_setup` tool and pull out the records under the prefixes `plone.caching` and `plone.app.caching`.
+
+Typically, `registry.xml` is all that is required, but you are free to add additional import steps if required.
+You can also add a `metadata.xml` and use the GenericSetup dependency mechanism to install other profiles on the fly.