[ESI] Explain requirements for Symfony to interopate with the gateway cache

[Bilge]

The ESI docs claim:

if Symfony detects that it’s talking to a gateway cache that supports ESI, it generates an ESI include tag.

Without going into any specifics, we're led to believe that Symfony magically knows whether ESI is supported by the "gateway cache", e.g. Varnish. Both @stof and @derrabus specifically cited Varnish with reference to ESI, (even though the docs don't mention or endorse any specific gateway cache implementation), so let's use Varnish. However, even the latest version of Varnish (6.5 at time of writing) does not work with Symfony's magic gateway cache detection out of the box.

It seems to me this specific function determines whether or not ESI is supported, but Varnish does not emit a Surrogate-Capability header whatsoever by default. Presumably, then, the onus is on the developer to program Varnish to emit this header in an appropriate format to satisfy Symfony. It is not simply enough for the header to be present, it also has to be in a specific format, e.g. it must contain ESI/1.0. Being as that's the case, the docs need to be expanded to be absolutely clear about what is required from the gateway cache in order to be interoperable with Symfony's ESI implementation and not just leave it to magic because that leaves the developer without a lead on what to do in case the magic fails.

[javiereguiluz]

Thanks for reporting this issue. In other similar cases we always close as "won't fix" because we don't want to share these internal code details in the docs. However, in this case we could make an exception because this is not trivial to discover and it's very important, so it's better to mention this in the docs instead of readers having to investigate in Symfony's code. See #14801.

[stof]

As this is about interacting with something outside Symfony, I don't think this can be considered an internal code detail.

[Bilge]

@stof Thanks for adding that. Although @javiereguiluz came to the correct conclusion, I don't think it needs to be justified as any kind of exception to any rule.

I'd also like to contribute my minimal working Varnish configuration for reference, if you think that'd be useful.

sub vcl_backend_fetch {
  # Inform app ESI is supported.
  set bereq.http.Surrogate-Capability = "ESI/1.0";
}

sub vcl_backend_response {
  # Perform ESI substitution in Varnish.
  set beresp.do_esi = true;
}