Skip to content
This repository has been archived by the owner on Apr 21, 2023. It is now read-only.

Design Doc: Cache Purge API

Jump to bottom
Jeff Kaufman edited this page Jan 9, 2017 · 1 revision

Cache Purge API

Ilya Grigorik, March 2013

The Cache Purge API should allow the user to programmatically flush a resource from the PageSpeed cache

Use case

User modifies a static asset, such as a CSS stylesheet, on their origin server, navigates to their production site and hits refresh. Expected behavior: instant update and new resource is updated immediately. Likely workflow today: if origin resource has a cache lifetime, than a stale resource may be served until the time has expired.

Above workflow is very common for hosted environments, such as WordPress blog hosting, where the site owner modifies their CSS / JS and HTML templates directly on the live site through the WP admin dashboard - saving a file overwrites the production copy directly, and the user must be able to see the changes immediately on the production site. Otherwise, the changes may actually result in broken markup and borken rendering of the page.

Based on feedback from hosting providers and CDNs, the above workflow is very common for their customers, and something that we should address.

Current behavior

Currently, PageSpeed provides some support to address above problem: use "load from file" to avoid this problem

However, this does not work when mod/ngx_pagespeed are not running on the same server where the files reside (aka, as reverse proxy to some other server).

An interim solution is to set a "short cache lifetime" on the origin server for each asset, but while this makes the problem slightly less painful, it nonetheless does not address the underlying problem. The user should not see any stale resources, and further, should not have to worry about manually invalidating stale assets.

Solution

Above scenario is a standard problem for any CDN / cache layer, which is solved by providing an integration endpoint between the application and the cache: whenever the user modifies an asset, a request is sent to the cache server by the application to immediately invalidate the resource. Such plugins exist for all popular platforms + caches. For example:

We do not need to build the individual plugins, but we do need to provide an API which will allow the user to create such an integration between mod_pagespeed / ngx_pagespeed instance. For example:

PURGE /path/to/resource/to_purge.css HTTP/1.0
Host: mysite.com

Popular caches such as Varnish / nginx (ngx_cache_purge) invalidate a single resource per request, which appears to be sufficient - no need for bulk API’s. Similarly, authorization can be handled by existing mechanisms:

  • mod_pagespeed / ngx_pagespeed authentication can be provided by built in mechanisms (such as only allowing purge requests from internal IPs)

Reference

Clone this wiki locally