Surrogate-Capability
A surrogate announces what it is able to do through the unofficial Surrogate-Capability request header. The CDN or reverse proxy adds the header on requests toward the origin, naming itself and the capability set it supports, so the origin knows whether a Surrogate-Control response or Edge Side Includes markup will be honored on the way back.
Usage
The header comes from the same 2001 Edge Architecture note as Surrogate-Control, forming the request half of the pair: capabilities travel toward the origin, directives travel back. Each entry names a device token, an equals sign, and a quoted capability list, with multiple surrogates appending their own entries the way Via grows hop by hop.
The practical capability is ESI. An origin seeing
ESI/1.0 in the value emits Edge Side Includes
markup and a matching
Surrogate-Control: content="ESI/1.0" directive,
letting the edge assemble pages from cached
fragments. Without the announcement, the origin
serves fully assembled pages, since ESI markup
reaching a browser renders as nothing.
Varnish deployments set the header in VCL before fetching from the backend, and origin frameworks with ESI support (Symfony among them) switch output modes on the value.
Values
Surrogate-Capability: <device>="<capability tokens>"
Capability tokens from the Edge Architecture note
cover Surrogate/1.0 for the base caching model and
ESI/1.0 for Edge Side Includes processing.
Example
A Varnish node announces ESI support to the origin, and the origin answers with ESI markup plus the matching directive.
Request
GET /page HTTP/1.1
Host: www.example.re
Surrogate-Capability: varnish="ESI/1.0"
Response
HTTP/1.1 200 OK
Content-Type: text/html
Surrogate-Control: content="ESI/1.0"