[master] 88025e951 man: Fold vcl-actions.rst into vcl-step.rst
Nils Goroll
nils.goroll at uplex.de
Mon May 15 13:27:06 UTC 2023
commit 88025e9515d239a0770be736a9280f2deafe0c83
Author: Walid Boudebouda <walid.boudebouda at gmail.com>
Date: Thu Mar 30 14:32:51 2023 +0200
man: Fold vcl-actions.rst into vcl-step.rst
This also belongs in a reference manual and should not be disjoint. It
also avoids broken references with rst2man that only sphinx can resolve
across multiple pages.
diff --git a/doc/sphinx/reference/vcl-step.rst b/doc/sphinx/reference/vcl-step.rst
index 011e84e00..6deff971b 100644
--- a/doc/sphinx/reference/vcl-step.rst
+++ b/doc/sphinx/reference/vcl-step.rst
@@ -36,12 +36,97 @@ The behaviour of actions is identical or at least similar across
subroutines, so differences are only documented where relevant.
Common actions are documented in
-:ref:`user-guide-vcl_actions`. Actions specific to only one or some
-subroutines are documented herein.
+:ref:`vcl_actions` in the next section. Actions specific
+to only one or some subroutines are documented in :ref:`vcl_steps`.
A default behavior is provided for all :ref:`reference-states` in the
:ref:`vcl-built-in-code` code.
+.. _vcl_actions:
+
+VCL Actions
+===========
+
+Actions are used with the ``return(<action>)`` keyword, which returns
+control from subroutines back to varnish. The action determines how
+processing in varnish continues as shown in :ref:`reference-states`.
+
+Common actions are documented here, while additional actions specific
+to only one or some subroutines are documented in the next section
+:ref:`vcl_steps` as well as which action can be used from which built
+in subroutine.
+
+Common actions for the client and backend side
+##############################################
+
+.. _fail:
+
+``fail``
+~~~~~~~~
+
+ Transition to :ref:`vcl_synth` on the client side as for
+ ``return(synth(503, "VCL Failed"))``, but with any request state
+ changes undone as if ``std.rollback()`` was called and forcing a
+ connection close.
+
+ Intended for fatal errors, for which only minimal error handling is
+ possible.
+
+Common actions for the client side
+##################################
+
+.. _synth:
+
+``synth(status code, reason)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ Transition to :ref:`vcl_synth` with ``resp.status`` and
+ ``resp.reason`` being preset to the arguments of ``synth()``.
+
+.. _pass:
+
+``pass``
+~~~~~~~~
+
+ Switch to pass mode, making the current request not use the cache
+ and not putting its response into it. Control will eventually pass to
+ :ref:`vcl_pass`.
+
+.. _pipe:
+
+``pipe``
+~~~~~~~~
+
+ Switch to pipe mode. Control will eventually pass to
+ :ref:`vcl_pipe`.
+
+.. _restart:
+
+``restart``
+~~~~~~~~~~~
+
+ Restart the transaction. Increases the ``req.restarts`` counter.
+
+ If the number of restarts is higher than the *max_restarts*
+ parameter, control is passed to :ref:`vcl_synth` as for
+ ``return(synth(503, "Too many restarts"))``
+
+ For a restart, all modifications to ``req`` attributes are
+ preserved except for ``req.restarts`` and ``req.xid``, which need
+ to change by design.
+
+Common actions for the backend side
+###################################
+
+.. _abandon:
+
+``abandon``
+~~~~~~~~~~~
+
+ Abandon the backend request. Unless the backend request was a
+ background fetch, control is passed to :ref:`vcl_synth` on the
+ client side with ``resp.status`` preset to 503.
+
.. include:: vcl_step.rst
diff --git a/doc/sphinx/reference/vcl_step.rst b/doc/sphinx/reference/vcl_step.rst
index 30d946a9a..ee07f6169 100644
--- a/doc/sphinx/reference/vcl_step.rst
+++ b/doc/sphinx/reference/vcl_step.rst
@@ -25,19 +25,19 @@ of the following keywords:
|
| ``fail``
- | see :ref:`fail`
+ | see :ref:`fail` section above
|
| ``synth(status code, reason)``
- | see :ref:`synth`
+ | see :ref:`synth` section above
|
| ``restart``
- | see :ref:`restart`
+ | see :ref:`restart` section above
|
| ``pass``
- | see :ref:`pass`
+ | see :ref:`pass` section above
|
| ``pipe``
- | see :ref:`pipe`
+ | see :ref:`pipe` section above
|
| ``hash``
| Continue processing the object as a potential candidate for
@@ -57,7 +57,7 @@ of the following keywords:
| The ``vcl(label)`` return is only valid while the ``req.restarts``
| count is zero and if used from the active vcl.
|
- | See the :ref:`ref_cli_vcl_label` command.
+ | See the :ref:`ref_cli_vcl_label` command in :ref:`varnish-cli(7)`.
.. _vcl_pipe:
@@ -76,10 +76,10 @@ of the following keywords:
|
| ``fail``
- | see :ref:`fail`
+ | see :ref:`fail` section above
|
| ``synth(status code, reason)``
- | see :ref:`synth`
+ | see :ref:`synth` section above
|
| ``pipe``
| Proceed with pipe mode.
@@ -99,13 +99,13 @@ of the following keywords:
|
| ``fail``
- | see :ref:`fail`
+ | see :ref:`fail` section above
|
| ``synth(status code, reason)``
- | see :ref:`synth`
+ | see :ref:`synth` section above
|
| ``restart``
- | see :ref:`restart`
+ | see :ref:`restart` section above
|
| ``fetch``
| Proceed with pass mode - initiate a backend request.
@@ -123,7 +123,7 @@ of the following keywords:
|
| ``fail``
- | see :ref:`fail`
+ | see :ref:`fail` section above
|
| ``lookup``
| Look up the object in cache.
@@ -155,13 +155,13 @@ of the following keywords:
|
| ``fail``
- | see :ref:`fail`
+ | see :ref:`fail` section above
|
| ``synth(status code, reason)``
- | see :ref:`synth`
+ | see :ref:`synth` section above
|
| ``restart``
- | see :ref:`restart`
+ | see :ref:`restart` section above
.. _vcl_miss:
@@ -180,16 +180,16 @@ of the following keywords:
|
| ``fail``
- | see :ref:`fail`
+ | see :ref:`fail` section above
|
| ``synth(status code, reason)``
- | see :ref:`synth`
+ | see :ref:`synth` section above
|
| ``restart``
- | see :ref:`restart`
+ | see :ref:`restart` section above
|
| ``pass``
- | see :ref:`pass`
+ | see :ref:`pass` section above
|
| ``fetch``
| Retrieve the requested object from the backend. Control will
@@ -208,16 +208,16 @@ The `vcl_hit` subroutine may terminate with calling ``return()``
with one of the following keywords:
| ``fail``
- | see :ref:`fail`
+ | see :ref:`fail` section above
|
| ``synth(status code, reason)``
- | see :ref:`synth`
+ | see :ref:`synth` section above
|
| ``restart``
- | see :ref:`restart`
+ | see :ref:`restart` section above
|
| ``pass``
- | see :ref:`pass`
+ | see :ref:`pass` section above
|
| ``deliver``
| Deliver the object. If it is stale, a background fetch to refresh
@@ -235,13 +235,13 @@ of the following keywords:
|
| ``fail``
- | see :ref:`fail`
+ | see :ref:`fail` section above
|
| ``synth(status code, reason)``
- | see :ref:`synth`
+ | see :ref:`synth` section above
|
| ``restart``
- | see :ref:`restart`
+ | see :ref:`restart` section above
|
| ``deliver``
| Deliver the object to the client.
@@ -263,10 +263,10 @@ following keywords:
|
| ``fail``
- | see :ref:`fail`
+ | see :ref:`fail` section above
|
| ``restart``
- | see :ref:`restart`
+ | see :ref:`restart` section above
|
| ``deliver``
| Directly deliver the object defined by `vcl_synth` to the client
@@ -288,10 +288,10 @@ The `vcl_backend_fetch` subroutine may terminate with calling
|
| ``fail``
- | see :ref:`fail`
+ | see :ref:`fail` section above
|
| ``abandon``
- | see :ref:`abandon`
+ | see :ref:`abandon` section above
|
| ``fetch``
| Fetch the object from the backend.
@@ -342,10 +342,10 @@ The `vcl_backend_response` subroutine may terminate with calling
|
| ``fail``
- | see :ref:`fail`
+ | see :ref:`fail` section above
|
| ``abandon``
- | see :ref:`abandon`
+ | see :ref:`abandon` section above
|
| ``deliver``
| For a 304 response, create an updated cache object.
@@ -397,10 +397,10 @@ with one of the following keywords:
|
| ``fail``
- | see :ref:`fail`
+ | see :ref:`fail` section above
|
| ``abandon``
- | see :ref:`abandon`
+ | see :ref:`abandon` section above
|
| ``deliver``
| Deliver and possibly cache the object defined in
diff --git a/doc/sphinx/users-guide/increasing-your-hitrate.rst b/doc/sphinx/users-guide/increasing-your-hitrate.rst
index 8c49e5a8b..88f166204 100644
--- a/doc/sphinx/users-guide/increasing-your-hitrate.rst
+++ b/doc/sphinx/users-guide/increasing-your-hitrate.rst
@@ -222,7 +222,7 @@ Cookies coming from the backend
If your backend server sets a cookie using the 'Set-Cookie' header
Varnish will not cache the page when using the default configuration.
-A `hit-for-miss` object (see :ref:`user-guide-vcl_actions`) is
+A `hit-for-miss` object (see :ref:`vcl_actions`) is
created. So, if the backend server acts silly and sets unwanted
cookies just unset the 'Set-Cookie' header and all should be fine.
diff --git a/doc/sphinx/users-guide/vcl-actions.rst b/doc/sphinx/users-guide/vcl-actions.rst
deleted file mode 100644
index b51b1bf92..000000000
--- a/doc/sphinx/users-guide/vcl-actions.rst
+++ /dev/null
@@ -1,89 +0,0 @@
-..
- Copyright (c) 2012-2019 Varnish Software AS
- SPDX-License-Identifier: BSD-2-Clause
- See LICENSE file for full text of license
-
-.. _user-guide-vcl_actions:
-
-Actions
-=======
-
-Actions are used with the ``return(<action>)`` keyword, which returns
-control from subroutines back to varnish. The action determines how
-processing in varnish continues as shown in :ref:`reference-states`.
-
-Common actions are documented here, while additional actions specific
-to only one or some subroutines are documented in
-:ref:`vcl-steps(7)` as well as which action can be used from
-which built in subroutine.
-
-common actions for the client and backend side
-----------------------------------------------
-
-.. _fail:
-
-``fail``
-~~~~~~~~
-
- Transition to :ref:`vcl_synth` on the client side as for
- ``return(synth(503, "VCL Failed"))``, but with any request state
- changes undone as if ``std.rollback()`` was called and forcing a
- connection close.
-
- Intended for fatal errors, for which only minimal error handling is
- possible.
-
-common actions for the client side
-----------------------------------
-
-.. _synth:
-
-``synth(status code, reason)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- Transition to :ref:`vcl_synth` with ``resp.status`` and
- ``resp.reason`` being preset to the arguments of ``synth()``.
-
-.. _pass:
-
-``pass``
-~~~~~~~~
-
- Switch to pass mode, making the current request not use the cache
- and not putting its response into it. Control will eventually pass to
- :ref:`vcl_pass`.
-
-.. _pipe:
-
-``pipe``
-~~~~~~~~
-
- Switch to pipe mode. Control will eventually pass to
- :ref:`vcl_pipe`.
-
-.. _restart:
-
-``restart``
-~~~~~~~~~~~
-
- Restart the transaction. Increases the ``req.restarts`` counter.
-
- If the number of restarts is higher than the *max_restarts*
- parameter, control is passed to :ref:`vcl_synth` as for
- ``return(synth(503, "Too many restarts"))``
-
- For a restart, all modifications to ``req`` attributes are
- preserved except for ``req.restarts`` and ``req.xid``, which need
- to change by design.
-
-common actions for the backend side
------------------------------------
-
-.. _abandon:
-
-``abandon``
-~~~~~~~~~~~
-
- Abandon the backend request. Unless the backend request was a
- background fetch, control is passed to :ref:`vcl_synth` on the
- client side with ``resp.status`` preset to 503.
diff --git a/doc/sphinx/users-guide/vcl-example-manipulating-responses.rst b/doc/sphinx/users-guide/vcl-example-manipulating-responses.rst
index 8edf0d193..59bc12bcf 100644
--- a/doc/sphinx/users-guide/vcl-example-manipulating-responses.rst
+++ b/doc/sphinx/users-guide/vcl-example-manipulating-responses.rst
@@ -21,4 +21,4 @@ matches certain criteria::
We also remove any Set-Cookie headers in order to avoid creation of a
-`hit-for-miss` object. See :ref:`user-guide-vcl_actions`.
+`hit-for-miss` object. See :ref:`vcl_actions`.
diff --git a/doc/sphinx/users-guide/vcl-syntax.rst b/doc/sphinx/users-guide/vcl-syntax.rst
index 10748596a..3d9d819ec 100644
--- a/doc/sphinx/users-guide/vcl-syntax.rst
+++ b/doc/sphinx/users-guide/vcl-syntax.rst
@@ -102,7 +102,7 @@ transaction as it flows through Varnish. These built-in subroutines are
all named ``vcl_*`` and are explained in :ref:`vcl_steps`.
Processing in built-in subroutines ends with ``return (<action>)``
-(see :ref:`user-guide-vcl_actions`).
+(see :ref:`vcl_actions`).
The :ref:`vcl-built-in-code` also contains custom assistant subroutines
called by the built-in subroutines, also prefixed with ``vcl_``.
@@ -128,7 +128,7 @@ subroutine's name::
Custom subroutines in VCL do not take arguments, nor do they return
values.
-``return (<action>)`` (see :ref:`user-guide-vcl_actions`) as shown in
+``return (<action>)`` (see :ref:`vcl_actions`) as shown in
the example above returns all the way from the top level built in
subroutine (see :ref:`vcl_steps`) which, possibly through
multiple steps, lead to the call of the custom subroutine.
diff --git a/doc/sphinx/users-guide/vcl.rst b/doc/sphinx/users-guide/vcl.rst
index 2647a6491..d74898358 100644
--- a/doc/sphinx/users-guide/vcl.rst
+++ b/doc/sphinx/users-guide/vcl.rst
@@ -42,7 +42,6 @@ code commented out in the file `builtin.vcl` that ships with Varnish Cache.
vcl-syntax
vcl-built-in-code
vcl-variables
- vcl-actions
vcl-backends
vcl-hashing
vcl-grace
More information about the varnish-commit
mailing list