4.1.2 Further tweaking of validation behaviour

If cacheIsShared is false (it is true by default), Polipo will ignore the server-side ‘Cache-Control’ directives ‘private’, ‘s-maxage’ and ‘proxy-must-revalidate’. This is highly desirable behaviour when the proxy is used by just one user, but might break some sites if the proxy is shared.

When connectivity is very poor, the variable relaxTransparency can be used to cause Polipo to serve stale instances under some circumstances. If relaxTransparency is false (the default), all stale instances are validated (see Cache transparency), and failures to connect are reported to the client. This is the default mode of operation of most other proxies, and the least likely to surprise the user.

If relaxTransparency is maybe, all stale instances are still validated, but a failure to connect is only reported as an error if no data is available in the cache. If a connection fails and stale data is available, it is served to the client with a suitable HTTP/1.1 ‘Warning’ header. Current user-agents do not provide visible indication of such warnings, however, and this setting will typically cause the browser to display stale data with no indication that anything went wrong. It is useful when you are consulting a live web site but don’t want to be bothered with failed revalidations.

If relaxTransparency is true, missing data is fetched from remote servers, but stale data are unconditionally served with no validation. Client-side ‘Cache-Control’ directives are still honoured, which means that you can force an end-to-end revalidation from the browser’s interface (typically by shift-clicking on “reload”). This setting is only useful if you have very bad network connectivity or are consulting a very slow web site or one that provides incorrect cache control information¹² and are willing to manually revalidate pages that you suspect are stale.

If mindlesslyCacheVary is true, the presence of a ‘Vary’ header (which indicates that content-negotiation occurred, see Censor Accept-Language) is ignored, and cached negotiated instances are mindlessly returned to the client. If it is false (the default), negotiated instances are revalidated on every client request.

Unfortunately, a number of servers (most notably some versions of Apache’s mod_deflate module) send objects with a ‘ETag’ header that will confuse Polipo in the presence of a ‘Vary’ header. Polipo will make a reasonable check for consistency if ‘dontTrustVaryETag’ is set to ‘maybe’ (the default); it will systematically ignore ‘ETag’ headers on objects with ‘Vary’ headers if it is set to ‘true’.

A number of websites incorrectly mark variable resources as cachable; such issues can be worked around in polipo by manually marking given categories of objects as uncachable. If dontCacheCookies is true, all pages carrying HTTP cookies will be treated as uncachable. If dontCacheRedirects is true, all redirects (301 and 302) will be treated as uncachable. Finally, if everything else fails, a list of uncachable URLs can be given in the file specified by uncachableFile, which has the same format as the forbiddenFile (see Internal forbidden list). If not specified, its location defaults to ‘~/.polipo-uncachable’ or ‘/etc/polipo/uncachable’, whichever exists.