[master] 0b0a8e8 consolidate return keyword documentation and add missing keywords
Nils Goroll
nils.goroll at uplex.de
Mon Oct 2 19:16:06 UTC 2017
commit 0b0a8e8bc75f8db85670e3a653a2ef725fbdff1a
Author: Nils Goroll <nils.goroll at uplex.de>
Date: Mon Oct 2 19:03:45 2017 +0200
consolidate return keyword documentation and add missing keywords
Remove duplication to some extent by moving common return keywords
to a separate paragraph.
Add fail and vcl(label) keywords
Fix some typos
diff --git a/doc/sphinx/users-guide/vcl-built-in-subs.rst b/doc/sphinx/users-guide/vcl-built-in-subs.rst
index 941f0b8..14a740d 100644
--- a/doc/sphinx/users-guide/vcl-built-in-subs.rst
+++ b/doc/sphinx/users-guide/vcl-built-in-subs.rst
@@ -7,9 +7,58 @@ Built in subroutines
Various built-in subroutines are called during processing of client-
and backend requests as well as upon ``vcl.load`` and ``vcl.discard``.
-See :ref:`reference-states` for a defailed graphical overview of the
+See :ref:`reference-states` for a detailed graphical overview of the
states and how they relate to core code functions and VCL subroutines.
+Subroutines always terminate with a ``return()`` on a keyword, which
+determines how processing continues in the request processing state
+machine.
+
+The behaviour for ``return()`` keywords is identical or at least
+similar across subroutines, so differences are only documented where
+relevant.
+
+common return keywords
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. _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.
+
+.. _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. 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"))``
+
-----------
client side
-----------
@@ -30,15 +79,17 @@ be set as a default for the backend processing side.
The `vcl_recv` subroutine may terminate with calling ``return()`` on one
of the following keywords:
+ ``fail``
+ see `fail`_
+
``synth(status code, reason)``
- Transition to :ref:`vcl_synth` with ``resp.status`` and
- ``resp.reason`` being preset to the arguments of ``synth()``.
+ see `synth`_
``pass``
- Switch to pass mode. Control will eventually pass to :ref:`vcl_pass`.
+ see `pass`_
``pipe``
- Switch to pipe mode. Control will eventually pass to :ref:`vcl_pipe`.
+ see `pipe`_
``hash``
Continue processing the object as a potential candidate for
@@ -46,7 +97,13 @@ of the following keywords:
``purge``
Purge the object and it's variants. Control passes through
- vcl_hash to vcl_purge.
+ :ref:`vcl_hash` to :ref:`vcl_purge`.
+
+ ``vcl(label)``
+ Switch to vcl labelled *label*. This will continue vcl processing
+ in this vcl's :ref:`vcl_recv` as if it was the active vcl.
+
+ See the :ref:`varnishadm(1)` ``vcl.label`` command.
.. _vcl_pipe:
@@ -63,9 +120,11 @@ other VCL subroutine will ever get called after `vcl_pipe`.
The `vcl_pipe` subroutine may terminate with calling ``return()`` with one
of the following keywords:
+ ``fail``
+ see `fail`_
+
``synth(status code, reason)``
- Transition to :ref:`vcl_synth` with ``resp.status`` and
- ``resp.reason`` being preset to the arguments of ``synth()``.
+ see `synth`_
``pipe``
Proceed with pipe mode.
@@ -83,14 +142,14 @@ submitted over the same client connection are handled normally.
The `vcl_pass` subroutine may terminate with calling ``return()`` with one
of the following keywords:
+ ``fail``
+ see `fail`_
+
``synth(status code, reason)``
- Transition to :ref:`vcl_synth` with ``resp.status`` and
- ``resp.reason`` being preset to the arguments of ``synth()``.
+ see `synth`_
``restart``
- Restart the transaction. Increases the restart counter. If the number
- of restarts is higher than *max_restarts* Varnish emits a guru meditation
- error.
+ see `restart`_
``fetch``
Proceed with pass mode - initiate a backend request.
@@ -103,14 +162,20 @@ vcl_hash
Called after `vcl_recv` to create a hash value for the request. This is
used as a key to look up the object in Varnish.
-The `vcl_hash` subroutine may only terminate with calling ``return(lookup)``:
+The `vcl_hash` subroutine may terminate with calling ``return()`` with one
+of the following keywords:
+
+ ``fail``
+ see `fail`_
``lookup``
Look up the object in cache.
+
Control passes to :ref:`vcl_purge` when coming from a ``purge``
return in `vcl_recv`.
- Otherwise control passes to the next subroutine depending on the result of
- the cache lookup:
+
+ Otherwise control passes to the next subroutine depending on the
+ result of the cache lookup:
* a hit: pass to :ref:`vcl_hit`
@@ -126,19 +191,19 @@ The `vcl_hash` subroutine may only terminate with calling ``return(lookup)``:
vcl_purge
~~~~~~~~~
-Called after the purge has been executed and all its variants have been evited.
+Called after the purge has been executed and all its variants have been evicted.
The `vcl_purge` subroutine may terminate with calling ``return()`` with one
of the following keywords:
+ ``fail``
+ see `fail`_
+
``synth(status code, reason)``
- Transition to :ref:`vcl_synth` with ``resp.status`` and
- ``resp.reason`` being preset to the arguments of ``synth()``.
+ see `synth`_
``restart``
- Restart the transaction. Increases the restart counter. If the number
- of restarts is higher than *max_restarts* Varnish emits a guru meditation
- error.
+ see `restart`_
.. _vcl_miss:
@@ -155,17 +220,17 @@ the backend processing side.
The `vcl_miss` subroutine may terminate with calling ``return()`` with one
of the following keywords:
+ ``fail``
+ see `fail`_
+
``synth(status code, reason)``
- Transition to :ref:`vcl_synth` with ``resp.status`` and
- ``resp.reason`` being preset to the arguments of ``synth()``.
+ see `synth`_
``restart``
- Restart the transaction. Increases the restart counter. If the number
- of restarts is higher than *max_restarts* Varnish emits a guru meditation
- error.
+ see `restart`_
``pass``
- Switch to pass mode. Control will eventually pass to :ref:`vcl_pass`.
+ see `pass`_
``fetch``
Retrieve the requested object from the backend. Control will
@@ -183,17 +248,17 @@ stale: It can have a zero or negative `ttl` with only `grace` or
The `vcl_hit` subroutine may terminate with calling ``return()``
with one of the following keywords:
+ ``fail``
+ see `fail`_
+
``synth(status code, reason)``
- Transition to :ref:`vcl_synth` with ``resp.status`` and
- ``resp.reason`` being preset to the arguments of ``synth()``.
+ see `synth`_
``restart``
- Restart the transaction. Increases the restart counter. If the number
- of restarts is higher than *max_restarts* Varnish emits a guru meditation
- error.
+ see `restart`_
``pass``
- Switch to pass mode. Control will eventually pass to :ref:`vcl_pass`.
+ see `pass`_
``miss``
Synchronously refresh the object from the backend despite the
@@ -213,14 +278,14 @@ Called before any object except a `vcl_synth` result is delivered to the client.
The `vcl_deliver` subroutine may terminate with calling ``return()`` with one
of the following keywords:
+ ``fail``
+ see `fail`_
+
``synth(status code, reason)``
- Transition to :ref:`vcl_synth` with ``resp.status`` and
- ``resp.reason`` being preset to the arguments of ``synth()``.
+ see `synth`_
``restart``
- Restart the transaction. Increases the restart counter. If the number
- of restarts is higher than *max_restarts* Varnish emits a guru meditation
- error.
+ see `restart`_
``deliver``
Deliver the object to the client.
@@ -240,14 +305,15 @@ A `vcl_synth` defined object never enters the cache, contrary to a
The subroutine may terminate with calling ``return()`` with one of the
following keywords:
+ ``fail``
+ see `fail`_
+
``restart``
- Restart the transaction. Increases the restart counter. If the number
- of restarts is higher than *max_restarts* Varnish emits a guru meditation
- error.
+ see `restart`_
``deliver``
- Directly deliver the object defined by `vcl_synth` to the
- client without calling `vcl_deliver`.
+ Directly deliver the object defined by `vcl_synth` to the client
+ without calling `vcl_deliver`.
------------
Backend Side
@@ -264,6 +330,9 @@ typically alter the request before it gets to the backend.
The `vcl_backend_fetch` subroutine may terminate with calling
``return()`` with one of the following keywords:
+ ``fail``
+ see `fail`_
+
``fetch``
Fetch the object from the backend.
@@ -323,13 +392,16 @@ For a 304 response, varnish core code amends ``beresp`` before calling
`beresp.was_304` marks that this conditional response processing has
happened.
-Note: Backend conditional requests are independend of client
+Note: Backend conditional requests are independent of client
conditional requests, so clients may receive 304 responses no matter
if a backend request was conditional.
The `vcl_backend_response` subroutine may terminate with calling
``return()`` with one of the following keywords:
+ ``fail``
+ see `fail`_
+
``deliver``
For a 304 response, create an updated cache object.
Otherwise, fetch the object body from the backend and initiate
@@ -365,6 +437,9 @@ using the ``synthetic()`` function.
The `vcl_backend_error` subroutine may terminate with calling ``return()``
with one of the following keywords:
+ ``fail``
+ see `fail`_
+
``deliver``
Deliver and possibly cache the object defined in
`vcl_backend_error` **as if it was fetched from the backend**, also
More information about the varnish-commit
mailing list