[master] 9f02342b4 vcl: rename req.ttl to req.max_age, keep req.ttl as an alias
Nils Goroll
nils.goroll at uplex.de
Tue Oct 7 10:41:06 UTC 2025
commit 9f02342b455469349e24a88e49550f23c262baaf
Author: Nils Goroll <nils.goroll at uplex.de>
Date: Tue Oct 7 12:27:24 2025 +0200
vcl: rename req.ttl to req.max_age, keep req.ttl as an alias
... and document as deprecated, but do not emit a warning (yet).
Closes #4389
diff --git a/bin/varnishd/cache/cache_expire.c b/bin/varnishd/cache/cache_expire.c
index 75a45bc5a..cd604f1d0 100644
--- a/bin/varnishd/cache/cache_expire.c
+++ b/bin/varnishd/cache/cache_expire.c
@@ -60,9 +60,9 @@ struct exp_priv {
static struct exp_priv *exphdl;
static int exp_shutdown = 0;
-/*--------------------------------------------------------------------
- * Calculate an object's effective ttl time, taking req.ttl into account
- * if it is available.
+/*---------------------------------------------------------------------
+ * Calculate the point in time when an object will become stale, taking
+ * req.max_age into account, if available
*/
vtim_real
diff --git a/bin/varnishd/cache/cache_hash.c b/bin/varnishd/cache/cache_hash.c
index a72abd8cc..06afcd78a 100644
--- a/bin/varnishd/cache/cache_hash.c
+++ b/bin/varnishd/cache/cache_hash.c
@@ -577,7 +577,7 @@ HSH_Lookup(struct req *req, struct objcore **ocp, struct objcore **bocp)
break;
}
- if (EXP_Ttl(NULL, oc) <= req->t_req && /* ignore req.ttl */
+ if (EXP_Ttl(NULL, oc) <= req->t_req && /* ignore req.max_age */
oc->t_origin > exp_t_origin) {
/* record the newest object */
exp_oc = oc;
diff --git a/bin/varnishd/cache/cache_vrt_var.c b/bin/varnishd/cache/cache_vrt_var.c
index fc3861a33..4cdff3685 100644
--- a/bin/varnishd/cache/cache_vrt_var.c
+++ b/bin/varnishd/cache/cache_vrt_var.c
@@ -598,13 +598,18 @@ VRT_u_req_##nm(VRT_CTX) \
REQ_VAR_R(backend_hint, director_hint, VCL_BACKEND)
-REQ_VAR_L(ttl, d_ttl, VCL_DURATION, if (!(arg>0.0)) arg = 0;)
-REQ_VAR_R(ttl, d_ttl, VCL_DURATION)
-REQ_VAR_U(ttl, d_ttl, -1)
+REQ_VAR_L(max_age, d_ttl, VCL_DURATION, if (!(arg>0.0)) arg = 0;)
+REQ_VAR_R(max_age, d_ttl, VCL_DURATION)
+REQ_VAR_U(max_age, d_ttl, -1)
REQ_VAR_L(grace, d_grace, VCL_DURATION, if (!(arg>0.0)) arg = 0;)
REQ_VAR_R(grace, d_grace, VCL_DURATION)
REQ_VAR_U(grace, d_grace, -1)
+// deprecated, to be removed
+VCL_VOID VRT_l_req_ttl(VRT_CTX, VCL_DURATION arg) { VRT_l_req_max_age(ctx, arg); }
+VCL_DURATION VRT_r_req_ttl(VRT_CTX) { return (VRT_r_req_max_age(ctx)); }
+VCL_VOID VRT_u_req_ttl(VRT_CTX) { return (VRT_u_req_max_age(ctx)); }
+
VCL_VOID
VRT_l_req_backend_hint(VRT_CTX, VCL_BACKEND be)
{
diff --git a/bin/varnishtest/tests/c00009.vtc b/bin/varnishtest/tests/c00009.vtc
index b71ce59fc..601b9403a 100644
--- a/bin/varnishtest/tests/c00009.vtc
+++ b/bin/varnishtest/tests/c00009.vtc
@@ -20,7 +20,7 @@ varnish v1 -syntax 4.0 -arg "-smysteve=malloc,1m" -vcl+backend {
set req.proto = "HTTP/1.2";
set req.http.preserveme = "1";
set req.storage = storage.mysteve;
- set req.ttl = 42m;
+ set req.max_age = 42m;
set req.esi = false;
set req.backend_hint = s2;
set req.hash_ignore_busy = true;
@@ -53,7 +53,7 @@ varnish v1 -syntax 4.0 -arg "-smysteve=malloc,1m" -vcl+backend {
set resp.http.preserveme = req.http.preserveme;
set resp.http.restarts = req.restarts;
set resp.http.storage = req.storage;
- set resp.http.ttl = req.ttl;
+ set resp.http.ttl = req.max_age;
set resp.http.esi = req.esi;
set resp.http.backend_hint = req.backend_hint;
set resp.http.hash-ignore-busy = req.hash_ignore_busy;
diff --git a/bin/varnishtest/tests/r02422.vtc b/bin/varnishtest/tests/r02422.vtc
index 7a51689d2..1dfcfaf3c 100644
--- a/bin/varnishtest/tests/r02422.vtc
+++ b/bin/varnishtest/tests/r02422.vtc
@@ -1,4 +1,4 @@
-varnishtest "long polling and low latency using req.ttl"
+varnishtest "long polling and low latency using req.max_age"
# synchronizes the setup of all clients
barrier b1 cond 2
@@ -25,7 +25,7 @@ varnish v1 -cliok "param.set default_grace 0"
varnish v1 -vcl+backend {
sub vcl_recv {
if (req.restarts > 0) {
- set req.ttl = 1ms;
+ set req.max_age = 1ms;
}
}
diff --git a/bin/varnishtest/tests/v00000.vtc b/bin/varnishtest/tests/v00000.vtc
index 10f3892ff..54a971613 100644
--- a/bin/varnishtest/tests/v00000.vtc
+++ b/bin/varnishtest/tests/v00000.vtc
@@ -1,4 +1,4 @@
-varnishtest "VCL/VRT: req.ttl / beresp.ttl / beresp.grace"
+varnishtest "VCL/VRT: req.max_age / beresp.ttl / beresp.grace"
server s1 {
@@ -10,7 +10,7 @@ server s1 -start
varnish v1 -vcl+backend {
sub vcl_recv {
- set req.ttl += 1 s;
+ set req.max_age += 1 s;
}
sub vcl_backend_response {
set beresp.ttl += 1 m;
diff --git a/bin/varnishtest/tests/v00020.vtc b/bin/varnishtest/tests/v00020.vtc
index 86268bd80..239ecc991 100644
--- a/bin/varnishtest/tests/v00020.vtc
+++ b/bin/varnishtest/tests/v00020.vtc
@@ -77,7 +77,7 @@ varnish v1 -errvcl {Operator * not possible on type STRING.} {
varnish v1 -errvcl {DURATION + INT not possible.} {
sub vcl_backend_response {
- set req.ttl = req.ttl + beresp.status;
+ set req.max_age = req.max_age + beresp.status;
}
}
@@ -90,7 +90,7 @@ varnish v1 -errvcl {BOOL + BOOL not possible.} {
varnish v1 -errvcl {Operator % only possible on INT} {
sub vcl_recv {
- if (req.ttl % 1000) {
+ if (req.max_age % 1000) {
}
}
}
@@ -143,22 +143,22 @@ varnish v1 -vcl {
set req.http.foo = req.http.foo + "bar" ~ "bar";
set req.http.foo = req.http.foo + "bar" !~ "bar";
- set req.http.foo = "foo" + req.ttl;
+ set req.http.foo = "foo" + req.max_age;
set req.http.foo = client.ip + ", " + server.ip;
- set req.ttl = -1s;
- set req.ttl = 1s;
- set req.ttl *= 1.5;
- set req.ttl = 1.5 s * 2.5;
- set req.ttl = 1.5 s / 2.5;
- set req.ttl = 1.5h + 1.5s;
- set req.ttl = 1.5h - 1.5s;
+ set req.max_age = -1s;
+ set req.max_age = 1s;
+ set req.max_age *= 1.5;
+ set req.max_age = 1.5 s * 2.5;
+ set req.max_age = 1.5 s / 2.5;
+ set req.max_age = 1.5h + 1.5s;
+ set req.max_age = 1.5h - 1.5s;
- if (req.ttl) { }
- if (!req.ttl) { }
- if (req.ttl > 1d) { }
- if (req.ttl < 1d) { }
+ if (req.max_age) { }
+ if (!req.max_age) { }
+ if (req.max_age > 1d) { }
+ if (req.max_age < 1d) { }
if (1) { }
if (2 == 3) { }
@@ -197,13 +197,13 @@ varnish v1 -errvcl {STRING - STRING not possible.} {
varnish v1 -errvcl {TIME + STRING not possible.} {
sub vcl_recv {
- set req.ttl = now + "foo";
+ set req.max_age = now + "foo";
}
}
varnish v1 -errvcl {TIME + TIME not possible.} {
sub vcl_recv {
- set req.ttl = now + now;
+ set req.max_age = now + now;
}
}
@@ -221,25 +221,25 @@ varnish v1 -errvcl {INT + TIME not possible.} {
varnish v1 -errvcl {DURATION + INT not possible.} {
sub vcl_recv {
- set req.ttl = 1s + 1;
+ set req.max_age = 1s + 1;
}
}
varnish v1 -errvcl {DURATION + TIME not possible.} {
sub vcl_recv {
- set req.ttl = 1s + now;
+ set req.max_age = 1s + now;
}
}
varnish v1 -errvcl {DURATION + STRING not possible.} {
sub vcl_recv {
- set req.ttl = 1s + "foo";
+ set req.max_age = 1s + "foo";
}
}
varnish v1 -errvcl {IP + IP not possible.} {
sub vcl_recv {
- set req.ttl = client.ip + server.ip;
+ set req.max_age = client.ip + server.ip;
}
}
diff --git a/bin/varnishtest/tests/v00025.vtc b/bin/varnishtest/tests/v00025.vtc
index c6cdadd8f..5d40ff683 100644
--- a/bin/varnishtest/tests/v00025.vtc
+++ b/bin/varnishtest/tests/v00025.vtc
@@ -43,8 +43,8 @@ varnish v1 -syntax 4.0 -vcl+backend {
sub vcl_deliver {
set resp.http.server_port = std.port(server.ip);
set resp.http.server_port_foo = std.port(server.ip) + "_foo";
- set resp.http.ttl1 = (req.ttl + 10s);
- set resp.http.ttl2 = req.ttl + 10s;
+ set resp.http.ttl1 = (req.max_age + 10s);
+ set resp.http.ttl2 = req.max_age + 10s;
set resp.http.id = server.identity;
set resp.http.esi = req.esi;
set resp.http.be = req.backend_hint;
diff --git a/doc/changes.rst b/doc/changes.rst
index 6f8eb2529..0ced70596 100644
--- a/doc/changes.rst
+++ b/doc/changes.rst
@@ -41,6 +41,12 @@ Vinyl-Cache NEXT (2026-03-15)
.. PLEASE keep this roughly in commit order as shown by git-log / tig
(new to old)
+.. _4389: https://github.com/varnishcache/varnish-cache/issues/4389
+
+* ``req.ttl`` has been renamed to ``req.max_age`` for clarity, with ``req.ttl``
+ being retained as an alias. ``req.ttl`` is now deprecated, but no warning is
+ emitted yet. It will be removed in a future version of Vinyl-Cache. (`4389`_)
+
================================
Varnish-Cache 8.0.0 (2025-09-15)
================================
diff --git a/doc/sphinx/reference/vcl_var.rst b/doc/sphinx/reference/vcl_var.rst
index 627caa15f..52cff63da 100644
--- a/doc/sphinx/reference/vcl_var.rst
+++ b/doc/sphinx/reference/vcl_var.rst
@@ -529,6 +529,24 @@ req.transport
The transport protocol which brought this request.
+.. _req.max_age:
+
+req.max_age
+
+ Type: DURATION
+
+ Readable from: client
+
+ Writable from: client
+
+ Unsettable from: client
+
+
+ Upper limit on the object age for cache lookups to return hit. Matches
+ ``Cache-Control: max-age`` request header semantics.
+
+ When reading the unset value, it is returned as -1.
+
.. _req.ttl:
req.ttl
@@ -539,12 +557,11 @@ req.ttl
Writable from: client
- Unsettable from: client
-
+ Unsettable from: client
- Upper limit on the object age for cache lookups to return hit.
- When reading the unset value, it is returned as -1.
+ Deprecated alias of ``req.max-age``, which will be removed in a future
+ version of Vinyl-Cache.
.. _req.url:
More information about the varnish-commit
mailing list