[master] 0fc0475c6 VCL: introduce sub vcl_backend_refresh
Walid Boudebouda
walid.boudebouda at gmail.com
Mon Sep 1 08:46:05 UTC 2025
commit 0fc0475c6a2a75eb18dfc5fafddbc4c8446b03e1
Author: Walid Boudebouda <walid.boudebouda at gmail.com>
Date: Mon Oct 2 14:56:47 2023 +0200
VCL: introduce sub vcl_backend_refresh
This commit introduces a new sub vcl_backend_refresh method intended
to allow allow a more flexible approach on object revalidation.
diff --git a/bin/varnishd/builtin.vcl b/bin/varnishd/builtin.vcl
index 271a0217e..a6f8c79c9 100644
--- a/bin/varnishd/builtin.vcl
+++ b/bin/varnishd/builtin.vcl
@@ -209,6 +209,10 @@ sub vcl_backend_response {
return (deliver);
}
+sub vcl_backend_refresh {
+ return (merge);
+}
+
sub vcl_builtin_backend_response {
call vcl_beresp_range;
if (bereq.uncacheable) {
diff --git a/doc/sphinx/reference/vcl_step.rst b/doc/sphinx/reference/vcl_step.rst
index 81bb7b4e0..794f4fb76 100644
--- a/doc/sphinx/reference/vcl_step.rst
+++ b/doc/sphinx/reference/vcl_step.rst
@@ -331,6 +331,51 @@ hashing the request method and/or request body.
HEAD request can be satisfied from cached GET responses.
+.. _vcl_backend_refresh:
+
+vcl_backend_refresh
+~~~~~~~~~~~~~~~~~~~
+
+This subroutine is called after a legitimate 304 response is received from
+the backend so that you can chose how to handle the object revalidation.
+
+The default is to apply the RFC logic which is to merge the new headers with
+the stale ones.
+
+The returned value only affects response headers, the body that is delivered
+is always the one from the stale object.
+
+ |
+ | ``merge``
+ | Merge the headers we got from the backend response with
+ | the ones we had in the cached object.
+ |
+ | ``obj_stale``
+ | Return the stale object's headers without performing the RFC merge logic.
+ |
+ | ``beresp``
+ | Return the beresp headers as they were at the end of this subroutine
+ | without executing the RFC merge logic. Any content-length and
+ | content-encoding headers present in the 304 beresp will be removed and
+ | replaced by the stale object ones if available. Etag and Last-Modified
+ | headers are also copied from the stale object to allow futur revalidations.
+ |
+ | ``fail``
+ | see :ref:`fail` section above
+ |
+ | ``abandon``
+ | see :ref:`abandon` section above
+ |
+ | ``retry``
+ | Retry the backend transaction. Increases the `retries` counter.
+ | If the number of retries is higher than *max_retries*,
+ | control will be passed to :ref:`vcl_backend_error`.
+ |
+ | ``error(status code, reason)``
+ | Transition to :ref:`vcl_backend_error` with ``beresp.status`` and
+ | ``beresp.reason`` being preset to the arguments of ``error()`` if
+ | arguments are provided.
+
.. _vcl_backend_response:
vcl_backend_response
diff --git a/doc/sphinx/reference/vcl_var.rst b/doc/sphinx/reference/vcl_var.rst
index 6b724ebb8..633a2eeb6 100644
--- a/doc/sphinx/reference/vcl_var.rst
+++ b/doc/sphinx/reference/vcl_var.rst
@@ -984,7 +984,7 @@ beresp
Type: HTTP
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
The entire backend response HTTP data structure, useful as
argument to VMOD functions.
@@ -995,7 +995,7 @@ beresp.age
Type: DURATION
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
Default: Age header, or zero.
@@ -1008,7 +1008,7 @@ beresp.backend
Type: BACKEND
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
This is the backend we fetched from. If bereq.backend
was set to a director, this will be the backend selected
@@ -1031,7 +1031,7 @@ beresp.backend.name
Type: STRING
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
Name of the backend this response was fetched from.
Same as beresp.backend.
@@ -1054,9 +1054,9 @@ beresp.do_esi
Type: BOOL
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
- Writable from: vcl_backend_response, vcl_backend_error
+ Writable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
Default: ``false``.
@@ -1075,9 +1075,9 @@ beresp.do_gunzip
Type: BOOL
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
- Writable from: vcl_backend_response, vcl_backend_error
+ Writable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
Default: ``false``.
@@ -1096,9 +1096,9 @@ beresp.do_gzip
Type: BOOL
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
- Writable from: vcl_backend_response, vcl_backend_error
+ Writable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
Default: ``false``.
@@ -1116,9 +1116,9 @@ beresp.do_stream
Type: BOOL
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
- Writable from: vcl_backend_response, vcl_backend_error
+ Writable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
Default: ``true``.
@@ -1201,9 +1201,9 @@ beresp.grace
Type: DURATION
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
- Writable from: vcl_backend_response, vcl_backend_error
+ Writable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
Default: Cache-Control ``stale-while-revalidate`` directive,
or ``default_grace`` parameter.
@@ -1217,11 +1217,11 @@ beresp.http.*
Type: HEADER
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
- Writable from: vcl_backend_response, vcl_backend_error
+ Writable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
- Unsettable from: vcl_backend_response, vcl_backend_error
+ Unsettable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
The HTTP headers returned from the server.
@@ -1232,7 +1232,7 @@ beresp.http.content-length
Type: HEADER
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
The content-length header field is protected, see protected_headers_.
@@ -1241,7 +1241,7 @@ beresp.http.transfer-encoding
Type: HEADER
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
The transfer-encoding header field is protected, see protected_headers_.
@@ -1252,9 +1252,9 @@ beresp.keep
Type: DURATION
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
- Writable from: vcl_backend_response, vcl_backend_error
+ Writable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
Default: ``default_keep`` parameter.
@@ -1271,9 +1271,9 @@ beresp.proto ``VCL <= 4.0``
Type: STRING
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
- Writable from: vcl_backend_response, vcl_backend_error
+ Writable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
The HTTP protocol version the backend replied with.
@@ -1284,7 +1284,7 @@ beresp.proto ``VCL >= 4.1``
Type: STRING
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
The HTTP protocol version the backend replied with.
@@ -1295,9 +1295,9 @@ beresp.reason
Type: STRING
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
- Writable from: vcl_backend_response, vcl_backend_error
+ Writable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
The HTTP status message returned by the server.
@@ -1308,9 +1308,9 @@ beresp.status
Type: INT
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
- Writable from: vcl_backend_response, vcl_backend_error
+ Writable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
The HTTP status code returned by the server.
@@ -1323,9 +1323,9 @@ beresp.storage
Type: STEVEDORE
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
- Writable from: vcl_backend_response, vcl_backend_error
+ Writable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
The storage backend to use to save this object. If
@@ -1337,9 +1337,9 @@ beresp.storage_hint ``VCL <= 4.0``
Type: STRING
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
- Writable from: vcl_backend_response, vcl_backend_error
+ Writable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
Deprecated since varnish 5.1 and discontinued since VCL
@@ -1355,7 +1355,7 @@ beresp.time
Type: TIME
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
When the backend headers were fully received just before
``vcl_backend_response {}`` was entered, or when
@@ -1385,9 +1385,9 @@ beresp.ttl
Type: DURATION
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
- Writable from: vcl_backend_response, vcl_backend_error
+ Writable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
Default: Cache-Control ``s-maxage`` or ``max-age`` directives,
or a value computed from the Expires header's deadline, or the
@@ -1402,9 +1402,9 @@ beresp.uncacheable
Type: BOOL
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
- Writable from: vcl_backend_response, vcl_backend_error
+ Writable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
Inherited from bereq.uncacheable, see there.
@@ -1422,7 +1422,7 @@ beresp.was_304
Type: BOOL
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_backend_response, vcl_backend_error, vcl_backend_refresh
When ``true`` this indicates that we got a 304 response
More information about the varnish-commit
mailing list