Skip to content

V
varnish-cache
Commit 0b0a8e8b authored by Nils Goroll's avatar Nils Goroll
Browse files
Options

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
parent 9f193da0
Hide whitespace changes
Inline Side-by-side
Showing with 120 additions and 45 deletions
doc/sphinx/users-guide/vcl-built-in-subs.rst
View file @ 0b0a8e8b
......@@ -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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment