vcl_recv subroutine is executed when a client request is received by Fastly or as a result of a
Typically, the recv state is used for tasks such as:
- normalizing client input
- routing: dynamically allocating a backend to the request
- applying authentication or evaluating access rights (e.g., API keys, paywalls, session tokens, URL tokens)
- triggering synthetic responses for known paths (e.g., to implement redirects for old URLs)
- requiring TLS
- Denying requests based on geolocation or ACLs
- Enabling serve stale behavior
- Setting limits or defaults
- Enabling Image Optimization
- Validating initial request to remove 'trusted' headers that should only be added by edge logic
- Changing backend after a
restart, as part of the pre-flight pattern, A/B testing or origin failover.
The default return path from
GET requests is
lookup, which will trigger the
vcl_hash subroutine, perform a cache key calculation and look up the resulting address in the cache, ultimately triggering the
vcl_pass subroutines as appropriate. It's also possible to
return(pass), which will still perform a cache key calculation, but will always transition from
Changes made to the
req object in
vcl_recv will affect the calculation of the cache key, if the changed properties are included in
At the end of
vcl_recv, the default behavior is dependent on the method of the inbound request:
PURGErequests will trigger a
lookup, while all other methods will cause a
pass. This behavior is in the boilerplate VCL and is overridable by using custom VCL in your service.
- If the return state is
lookup, methods other than
POSTwill be converted to
GETon the backend request (
bereq) and any request body will be dropped. This behavior is part of the Fastly platfom and is not overridable.
HINT: With the default boilerplate VCL, the rules above will result in the conversion of a
HEAD request into a
GET to your origin server, allowing Fastly to populate the resource into our cache, but the response to the client will correctly exclude the content body, since the client requested only the HEAD.
To see this subroutine in the context of the full VCL flow, see using VCL.
The code example Use microservices to divide up a domain is a good example of the
vcl_recv subroutine in use:
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):