document and test bereq.backend vs. beresp.backend vs. beresp.backend.name

bin/varnishtest/tests/v00025.vtc

@@ -8,9 +8,16 @@ server s1 {
 varnish v1 -arg "-i J.F.Nobody" -vcl+backend {
 
 	import std;
+	import directors;
+
+	sub vcl_init {
+		new rr = directors.round_robin();
+		rr.add_backend(s1);
+	}
 
 	sub vcl_recv {
 		set client.identity = "Samuel B. Nobody";
+		set req.backend_hint = rr.backend();
 	}
 
 	sub vcl_deliver {
@@ -32,7 +39,8 @@ varnish v1 -arg "-i J.F.Nobody" -vcl+backend {
 	}
 
 	sub vcl_backend_response {
-		set beresp.http.backend = bereq.backend;
+		set beresp.http.bereq_backend = bereq.backend;
+		set beresp.http.beresp_backend = beresp.backend;
 		set beresp.http.keep = beresp.keep;
 		set beresp.http.hint = beresp.storage_hint;
 		set beresp.http.be_ip = beresp.backend.ip;
@@ -73,6 +81,13 @@ varnish v1 -arg "-i J.F.Nobody" -vcl+backend {
 client c1 {
 	txreq
 	rxresp
+	expect resp.status == 200
+	expect resp.http.bereq_backend == "rr"
+	expect resp.http.beresp_backend == "s1"
+	expect resp.http.be_ip == "127.0.0.1"
+	expect resp.http.be_nm == "s1"
+	expect resp.http.be == "rr"
+
 	txreq
 	rxresp
 } -run

lib/libvcc/generate.py

@@ -299,6 +299,11 @@ sp_variables = [
 		('client', ),
 		('client',), """
 		Set bereq.backend to this if we attempt to fetch.
+		When set to a director, reading this variable returns
+		an actual backend if the director has resolved immediately,
+		or the director otherwise.
+		When used in string context, returns the name of the director
+		or backend, respectively.
 		"""
 	),
 	('req.hash_ignore_busy',
@@ -380,6 +385,11 @@ sp_variables = [
 		('pipe', 'backend', ),
 		('pipe', 'backend', ), """
 		This is the backend or director we attempt to fetch from.
+		When set to a director, reading this variable returns
+		an actual backend if the director has resolved immediately,
+		or the director otherwise.
+		When used in string context, returns the name of the director
+		or backend, respectively.
 		"""
 	),
 	('bereq.body',
@@ -592,6 +602,7 @@ sp_variables = [
 		This is the backend we fetched from.  If bereq.backend
 		was set to a director, this will be the backend selected
 		by the director.
+		When used in string context, returns its name.
 		"""
 	),
 	('beresp.backend.name',
@@ -599,6 +610,7 @@ sp_variables = [
 		('backend_response', 'backend_error'),
 		(), """
 		Name of the backend this response was fetched from.
+		Same as beresp.backend.
 		"""
 	),
 	('beresp.backend.ip',