Docs : Only handle actual PURGE HTTP methods, everything else is discarded

[Dridi Boukelmoune]

On Fri, Mar 30, 2018 at 5:11 PM, AWA SOLUTIONS <contact at awa.solutions> wrote:
>
> Hi there,
>
> While reading the docs, I found this in https://www.varnish-software.com/wiki/content/tutorials/varnish/sample_vclTemplate.html :
>
> HANDLING HTTP PURGE
>
>   sub vcl_purge {
>     # Only handle actual PURGE HTTP methods, everything else is discarded
>     if (req.method != "PURGE") {
>       # restart request
>       set req.http.X-Purge = "Yes";
>       return(restart);
>     }
>   }
>
> But in mattiasgeniar/varnish-4.0-configuration-templates https://github.com/mattiasgeniar/varnish-4.0-configuration-templates/blob/master/default.vcl
>
> This is just the opposite logic :
>
> sub vcl_purge {
>   # Only handle actual PURGE HTTP methods, everything else is discarded
>   if (req.method == "PURGE") {
>     # restart request
>     set req.http.X-Purge = "Yes";
>     return (restart);
>   }
> }
>
> So I assume the latter, wiki page, has a typo ?!

I think the wiki is meant to feed from the community and give a single
location to find all sorts of tips. If Mattias is not credited we have
a problem, but I'm personally not into community tutorials as I way
too often (as in almost always) see irrelevant or harmful examples or
habits from the Varnish 2 or 3 days that have become irrelevant today
but refuse to die (yes, I'm looking at you, deflate=).

Doing a git blame on the if statement shows that it was a typo in
Mattias' repo probably inherited as-is in the wiki, changed 3 weeks
ago:

https://github.com/mattiasgeniar/varnish-4.0-configuration-templates/commit/18efd041a9f5c27b31cd89396ef6ea649acc0b70

> Last, in https://book.varnish-software.com/4.0/chapters/Cache_Invalidation.html , after similar vcl_recv conditions than above to return purge, vcl_purge subroutine sets req.method instead of req.http.X-Purge :
>
> sub vcl_purge {
>     set req.method = "GET";
>     return (restart);
> }
>
> Sounds logical to change req.method to avoid infinite loops, so why isn’t it the same in above examples ?

Full disclosure as I reveal my trainer hat, yes that's the way to go,
assuming you only cache responses to GET requests.

My question is rather "why isn't it documented upstream?"

https://varnish-cache.org/docs/trunk/users-guide/purging.html

We know our docs lack in certain areas. They aren't bad, and they
actually cover a lot, but they don't offer the best experience (and we
plan to at least try to improve that). It's only my guess but I'm sure
we'd all be happy to review and vet pull requests around
documentation.

At least I'd be happy to review "now that learned this the hard way I
wish it was documented here" patches.

Cheers