Why can header.copy not be used in vcl_deliver? - varnish

Question

I was wondering about an unexpected behaviour of varnish and the header vmod.
The following vcl will not compile, because of the use of header.copy in vcl_deliver.
Why is the use of header.copy not allowed here? Is there any documentation for this behaviour? Neither the documentation of varnish nor header say anything ybout it.
I don't need a workaround. I already have that.
vcl 4.1;
import header;
backend default {
.host = "127.0.0.1";
.port = "8888";
}
sub vcl_backend_response {
header.copy(beresp.http.Set-Cookie, beresp.http.X-Set-Cookie);
unset beresp.http.Set-Cookie;
}
sub vcl_deliver {
header.copy(beresp.http.X-Set-Cookie, beresp.http.Set-Cookie);
unset beresp.http.X-Set-Cookie;
}
will result in the following error, when compiled
Feb 09 06:40:11 epcentos7.dev varnishd[12938]: Error: Feb 09 06:40:11
epcentos7.dev varnishd[12938]: Message from VCC-compiler: Feb 09
06:40:11 epcentos7.dev varnishd[12938]: ('/etc/varnish/default.vcl'
Line 15 Pos 15) -- (Pos 20) Feb 09 06:40:11 epcentos7.dev
varnishd[12938]: header.copy(beresp.http.X-Set-Cookie,
beresp.http.Set-Cookie); Feb 09 06:40:11 epcentos7.dev
varnishd[12938]:
--------------######--------------------------------------------
Feb 09 06:40:11 epcentos7.dev varnishd[12938]: Not available in subroutine
'vcl_deliver'. Feb 09 06:40:11 epcentos7.dev varnishd[12938]: Running
VCC-compiler failed, exited with 2 Feb 09 06:40:11 epcentos7.dev
varnishd[12938]: VCL compilation failed Feb 09 06:40:11 epcentos7.dev
systemd[1]: varnish.service: control process exited, code=exited
status=255 Feb 09 06:40:11 epcentos7.dev systemd[1]: Failed to start
Varnish Cache, a high-performance HTTP accelerator.

Answer 1

The beresp object is not available in vcl_deliver as it is part of a different flow. The equivalent would be resp, which would result in the following header.copy() line:
sub vcl_deliver {
header.copy(resp.http.X-Set-Cookie, resp.http.Set-Cookie);
unset resp.http.X-Set-Cookie;
}
Transaction scope
Varnish has 2 kinds of transactions:
Client transactions: requests being received from the client, and responses being served to the client
Backend transactions: backend requests being sent to the backend, and backend responses being received from the backend
When a request results in a cache hit, Varnish only needs a client transaction to process it. No connection to the backend is made, so no backend transaction is used.
When a request results in a cache miss, Varnish will use both a client transaction to interact with the client, and a backend transaction to get the non-cached data from the backend
Subroutine scope
With the transaction scope in mind, we can now map VCL subroutines to it.
Here's an overview of client-side subroutines:
vcl_recv
vcl_hash
vcl_miss
vcl_hit
vcl_pass
vcl_deliver
vcl_synth
vcl_purge
These transactions have access to the req object and the resp object for requests and responses.
There are also backend subroutines such as:
vcl_backend_fetch
vcl_backend_response
vcl_backend_error
These subroutines have access to the bereq and beresp objects.
Object flow
When a request is received, the request information is stored in the req object. When it the request results in a cache miss, the req object information is copied into the bereq object.
When the backend responds the beresp object contains the (potentially) cacheable information. The beresp object data is copied into the obj object which represents what is stored in cache, but also to the resp object that is used to serve the response to the client that requested it.