[master] 8f48758fc man: Move beresp initialization to vcl-var(7)

Nils Goroll nils.goroll at uplex.de
Mon May 15 13:27:06 UTC 2023


commit 8f48758fc68c7f3183922be82d06624209734636
Author: Walid Boudebouda <walid.boudebouda at gmail.com>
Date:   Mon Mar 27 17:59:30 2023 +0200

    man: Move beresp initialization to vcl-var(7)
    
    The 304 handling and initial values for beresp.ttl, beresp.grace and
    beresp.keep belong in a reference manual.

diff --git a/doc/sphinx/reference/vcl-var.rst b/doc/sphinx/reference/vcl-var.rst
index b8278b57a..f2d832306 100644
--- a/doc/sphinx/reference/vcl-var.rst
+++ b/doc/sphinx/reference/vcl-var.rst
@@ -74,6 +74,79 @@ Assigning an HTTP standardized code to ``resp.status`` or ``beresp.status``
 will also set ``resp.reason`` or ``beresp.reason``  to the corresponding
 status message.
 
+
+304 handling
+~~~~~~~~~~~~
+
+For a 304 response, Varnish core code amends ``beresp`` before calling
+`vcl_backend_response`:
+
+* If the gzip status changed, ``Content-Encoding`` is unset and any
+  ``Etag`` is weakened
+
+* Any headers not present in the 304 response are copied from the
+  existing cache object. ``Content-Length`` is copied if present in
+  the existing cache object and discarded otherwise.
+
+* The status gets set to 200.
+
+`beresp.was_304` marks that this conditional response processing has
+happened.
+
+Note: Backend conditional requests are independent of client
+conditional requests, so clients may receive 304 responses no matter
+if a backend request was conditional.
+
+beresp.ttl / beresp.grace / beresp.keep
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before calling `vcl_backend_response`, core code sets ``beresp.ttl``
+based on the response status and the response headers ``Age``,
+``Cache-Control`` or ``Expires`` and ``Date`` as follows:
+
+* If present and valid, the value of the ``Age`` header is effectively
+  deduced from all ttl calculations.
+
+* For status codes 200, 203, 204, 300, 301, 304, 404, 410 and 414:
+
+  * If ``Cache-Control`` contains an ``s-maxage`` or ``max-age`` field
+    (in that order of preference), the ttl is set to the respective
+    non-negative value or 0 if negative.
+
+  * Otherwise, if no ``Expires`` header exists, the default ttl is
+    used.
+
+  * Otherwise, if ``Expires`` contains a time stamp before ``Date``,
+    the ttl is set to 0.
+
+  * Otherwise, if no ``Date`` header is present or the ``Date`` header
+    timestamp differs from the local clock by no more than the
+    `clock_skew` parameter, the ttl is set to
+
+    * 0 if ``Expires`` denotes a past timestamp or
+
+    * the difference between the local clock and the ``Expires``
+      header otherwise.
+
+  * Otherwise, the ttl is set to the difference between ``Expires``
+    and ``Date``
+
+* For status codes 302 and 307, the calculation is identical except
+  that the default ttl is not used and -1 is returned if neither
+  ``Cache-Control`` nor ``Expires`` exists.
+
+* For all other status codes, ttl -1 is returned.
+
+``beresp.grace`` defaults to the `default_grace` parameter.
+
+For a non-negative ttl, if ``Cache-Control`` contains a
+``stale-while-revalidate`` field value, ``beresp.grace`` is
+set to that value if non-negative or 0 otherwise.
+
+``beresp.keep`` defaults to the `default_keep` parameter.
+
+
+
 SEE ALSO
 ========
 
diff --git a/doc/sphinx/users-guide/vcl-built-in-subs.rst b/doc/sphinx/users-guide/vcl-built-in-subs.rst
index b614a8428..3d6b67f04 100644
--- a/doc/sphinx/users-guide/vcl-built-in-subs.rst
+++ b/doc/sphinx/users-guide/vcl-built-in-subs.rst
@@ -28,6 +28,7 @@ subroutines are documented herein.
 A default behavior is provided for all :ref:`reference-states` in the
 :ref:`vcl-built-in-code` code.
 
+
 client side
 -----------
 
@@ -382,76 +383,6 @@ The `vcl_backend_response` subroutine may terminate with calling
     ``beresp.reason`` being preset to the arguments of ``error()`` if
     arguments are provided.
 
-304 handling
-~~~~~~~~~~~~
-
-For a 304 response, Varnish core code amends ``beresp`` before calling
-`vcl_backend_response`:
-
-* If the gzip status changed, ``Content-Encoding`` is unset and any
-  ``Etag`` is weakened
-
-* Any headers not present in the 304 response are copied from the
-  existing cache object. ``Content-Length`` is copied if present in
-  the existing cache object and discarded otherwise.
-
-* The status gets set to 200.
-
-`beresp.was_304` marks that this conditional response processing has
-happened.
-
-Note: Backend conditional requests are independent of client
-conditional requests, so clients may receive 304 responses no matter
-if a backend request was conditional.
-
-beresp.ttl / beresp.grace / beresp.keep
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Before calling `vcl_backend_response`, core code sets ``beresp.ttl``
-based on the response status and the response headers ``Age``,
-``Cache-Control`` or ``Expires`` and ``Date`` as follows:
-
-* If present and valid, the value of the ``Age`` header is effectively
-  deduced from all ttl calculations.
-
-* For status codes 200, 203, 204, 300, 301, 304, 404, 410 and 414:
-
-  * If ``Cache-Control`` contains an ``s-maxage`` or ``max-age`` field
-    (in that order of preference), the ttl is set to the respective
-    non-negative value or 0 if negative.
-
-  * Otherwise, if no ``Expires`` header exists, the default ttl is
-    used.
-
-  * Otherwise, if ``Expires`` contains a time stamp before ``Date``,
-    the ttl is set to 0.
-
-  * Otherwise, if no ``Date`` header is present or the ``Date`` header
-    timestamp differs from the local clock by no more than the
-    `clock_skew` parameter, the ttl is set to
-
-    * 0 if ``Expires`` denotes a past timestamp or
-
-    * the difference between the local clock and the ``Expires``
-      header otherwise.
-
-  * Otherwise, the ttl is set to the difference between ``Expires``
-    and ``Date``
-
-* For status codes 302 and 307, the calculation is identical except
-  that the default ttl is not used and -1 is returned if neither
-  ``Cache-Control`` nor ``Expires`` exists.
-
-* For all other status codes, ttl -1 is returned.
-
-``beresp.grace`` defaults to the `default_grace` parameter.
-
-For a non-negative ttl, if ``Cache-Control`` contains a
-``stale-while-revalidate`` field value, ``beresp.grace`` is
-set to that value if non-negative or 0 otherwise.
-
-``beresp.keep`` defaults to the `default_keep` parameter.
-
 .. _vcl_backend_error:
 
 vcl_backend_error


More information about the varnish-commit mailing list