[master] 8802338e9 builtin.vcl: Explain backend refresh errros better

[Nils Goroll]

commit 8802338e950cc6b5edf26a979fc662c7e29af735
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Wed Sep 24 15:30:04 2025 +0200

    builtin.vcl: Explain backend refresh errros better
    
    We now use a specific reason for the cases of a late fail of a 304 response and
    also explain how the "wrong status" case can happen and, if intentional, what
    needs to be done to make it work.

diff --git a/bin/varnishd/builtin.vcl b/bin/varnishd/builtin.vcl
index c21b5374c..65fc37fa1 100644
--- a/bin/varnishd/builtin.vcl
+++ b/bin/varnishd/builtin.vcl
@@ -230,7 +230,10 @@ sub vcl_refresh_conditions {
 # We currently only revalidate 200 responses
 sub vcl_refresh_status {
 	if (obj_stale.status != 200) {
-		return (error(503, "Invalid object for refresh"));
+		# Can happen if VCL adds If-Modified-Since / If-None-Match
+		# for non-200 status objects. If deliberate, this sub can
+		# be overridden with sub vcl_refresh_status { return; }
+		return (error(503, "Invalid object for refresh (status)"));
 	}
 }
 
diff --git a/bin/varnishtest/tests/b00094.vtc b/bin/varnishtest/tests/b00094.vtc
index 65c54c53d..9058c19a6 100644
--- a/bin/varnishtest/tests/b00094.vtc
+++ b/bin/varnishtest/tests/b00094.vtc
@@ -24,7 +24,7 @@ server s1 {
 varnish v1 -vcl+backend {
 
 	sub vcl_backend_response {
-		set beresp.ttl = 0.01s;
+		set beresp.ttl = 1ms;
 		set beresp.grace = 0s;
 		set beresp.keep = 10m;
 		set beresp.http.was-304 = beresp.was_304;
@@ -216,5 +216,48 @@ client c8 {
 	txreq -url /2
 	rxresp
 	expect resp.status == 503
-	expect resp.reason == "Invalid object for refresh"
+	expect resp.reason == "Invalid object for refresh (status)"
+} -run
+
+###################################################################
+# overriding the status check, allowing 304 on non-200
+
+server s1 {
+	rxreq
+	txresp -status 404 -body "precious"
+	rxreq
+	txresp -status 304
+} -start
+
+varnish v1 -vcl+backend {
+
+	sub vcl_backend_response {
+		set beresp.ttl = 0.01s;
+		set beresp.grace = 0s;
+		set beresp.keep = 10m;
+		set beresp.http.was-304 = beresp.was_304;
+	}
+
+	sub vcl_backend_fetch {
+		set bereq.http.if-none-match = "abcd";
+	}
+
+	sub vcl_refresh_status {
+		return;
+	}
+}
+
+# Receiving 304 for non-200 objects, but accepting it
+# (violating http)
+client c8 {
+	txreq -url /3
+	rxresp
+	expect resp.status == 404
+	expect resp.body == "precious"
+	delay 0.01
+	txreq -url /3
+	rxresp
+	expect resp.status == 404
+	expect resp.http.was-304 == true
+	expect resp.body == "precious"
 } -run