vcl_hit
The built-in vcl_hit subroutine is executed when an object has been found in the cache and is available to be delivered to the client.
A hit in cache usually, but not always, means that the object is fresh; that is, it is within the TTL set by the origin or within the vcl_fetch subroutine. In cases where the object is stale, but is configured with a positive beresp.stale_while_revalidate time that has yet to expire, this will still be considered a hit and will trigger a background fetch to repopulate the cache asynchronously. A stale object may also trigger a hit if the backend is considered sick; that is, it has a health check configured, the health check is consistently failing, and the object is configured with a beresp.stale_if_error time which has not expired.
The hit subroutine should return(deliver) to deliver the object. It is also possible to return(pass), ignoring the hit and instructing Fastly to fetch from the backend anyway. The exception statements restart and error may both be used in vcl_hit.
Typically hit is executed on a fetch node as a result of clustering.
State transitions
To see this subroutine in the context of the full VCL flow, see our guide about Fastly VCL.
Tokens available in this subroutine
The following limited-scope VCL functions and variables are available for use in this subroutine (those in bold are available only in this subroutine, those available in *all* subroutines are not listed):
