[Varnish] #1124: Document Cache-Control private/no-cache behaviour

[Varnish]

#1124: Document Cache-Control private/no-cache behaviour
----------------------+-----------------------------------------------------
 Reporter:  timbunce  |        Type:  documentation
   Status:  new       |    Priority:  normal       
Milestone:            |   Component:  documentation
  Version:  3.0.2     |    Severity:  normal       
 Keywords:            |  
----------------------+-----------------------------------------------------
 I couldn't find any documentation on how beresp.ttl is calculated. (I
 believe it the first of “s-maxage” in Cache-Control, “max-age” in Cache-
 Control or the Expire header.)

 I was wondering because I also couldn't find any documentation on if/how
 varnish interacts with private/no-cache clauses in the Cache-Control
 header.

 I found https://www.varnish-cache.org/trac/wiki/VCLExampleHitMissHeader
 which is described as "add extra diagnostic headers" but actually changes
 the behavior to implement support for Cache-Control private.

 That made me worry that Cache-Control private wasn't implemented by
 default. Then I found https://www.varnish-cache.org/trac/ticket/477 which
 confirmed it. I was very surprised.

 After some digging I see that in https://www.varnish-
 cache.org/lists/pipermail/varnish-misc/2007-November/001173.html PHK says
 "Varnish is not a cache in the RFC2616 sense." I'm pretty sure that
 statement would be a surprise to many.

 I can understand your choice here, and I respect that. However I think
 it's important to document this choice, and the implications, very
 clearly. Especially as it makes the default behavior _unsafe_ when used by
 someone not aware of this issue.

 Ideally I'd like to see:

 * A clear statement in the docs about what varnish is and isn't, and why.
 For example, statements like "Varnish is not a cache in the RFC2616 sense,
 so it's unlike most traditional reverse proxies. It's more like a web
 server that gets it's content via HTTP" and "For example, the private and
 no-cache clauses in the Cache-Control: header are ignored."

 * An official example VCL for correct implementation of Cache-Control
 private/no-cache etc clauses per RFC2616 (or as near as possible).

 * Add details to the varnish book. Currently it doesn't mention the
 behavior re Cache-Control private/no-cache anywhere that I could find.
 E.g., it's not mentioned in https://www.varnish-
 software.com/static/book/HTTP.html#cache-related-headers
 (Though it is implied in one of the exercises https://www.varnish-
 software.com/static/book/VCL_Basics.html?highlight=private#exercise-vcl-
 avoid-caching-a-page)

 Thanks!

-- 
Ticket URL: <https://www.varnish-cache.org/trac/ticket/1124>
Varnish <https://varnish-cache.org/>
The Varnish HTTP Accelerator