.. _vcl-built-in-subs:

====================
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
states and how they relate to core code functions and VCL subroutines.

-----------
client side
-----------

.. _vcl_recv:

vcl_recv
~~~~~~~~

Called at the beginning of a request, after the complete request has
been received and parsed, after a `restart` or as the result of an ESI
include.

Its purpose is to decide whether or not to serve the request, possibly
modify it and decide on how to process it further. A backend hint may
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:

  ``hash``
    Continue processing the object as a potential candidate for
    caching. Passes the control over to :ref:`vcl_hash`.

  ``pass``
    Switch to pass mode. Control will eventually pass to :ref:`vcl_pass`.

  ``pipe``
    Switch to pipe mode. Control will eventually pass to :ref:`vcl_pipe`.

  ``synth(status code, reason)``
    Transition to :ref:`vcl_synth` with ``resp.status`` and
    ``resp.reason`` being preset to the arguments of ``synth()``.

  ``purge``
    Purge the object and it's variants. Control passes through
    vcl_hash to vcl_purge.

.. _vcl_pipe:

vcl_pipe
~~~~~~~~

Called upon entering pipe mode. In this mode, the request is passed on
to the backend, and any further data from both the client and backend
is passed on unaltered until either end closes the
connection. Basically, Varnish will degrade into a simple TCP proxy,
shuffling bytes back and forth. For a connection in pipe mode, no
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:

  ``pipe``
    Proceed with pipe mode.

  ``synth(status code, reason)``
    Transition to :ref:`vcl_synth` with ``resp.status`` and
    ``resp.reason`` being preset to the arguments of ``synth()``.

.. _vcl_pass:

vcl_pass
~~~~~~~~

Called upon entering pass mode. In this mode, the request is passed
on to the backend, and the backend's response is passed on to the
client, but is not entered into the cache. Subsequent requests
submitted over the same client connection are handled normally.

The `vcl_pass` subroutine may terminate with calling ``return()`` with one
of the following keywords:

  ``fetch``
    Proceed with pass mode - initiate a backend request.

  ``restart``
    Restart the transaction. Increases the restart counter. If the number
    of restarts is higher than *max_restarts* Varnish emits a guru meditation
    error.

  ``synth(status code, reason)``
    Transition to :ref:`vcl_synth` with ``resp.status`` and
    ``resp.reason`` being preset to the arguments of ``synth()``.

.. _vcl_hit:

vcl_hit
~~~~~~~

Called when a cache lookup is successful. The object being hit may be
stale: It can have a zero or negative `ttl` with only `grace` or
`keep` time left.

The `vcl_hit` subroutine may terminate with calling ``return()``
with one of the following keywords:

  ``deliver``
    Deliver the object. If it is stale, a background fetch to refresh
    it is triggered.

  ``miss``
    Synchronously refresh the object from the backend despite the
    cache hit. Control will eventually pass to :ref:`vcl_miss`.

  ``pass``
    Switch to pass mode. Control will eventually pass to :ref:`vcl_pass`.

  ``restart``
    Restart the transaction. Increases the restart counter. If the number
    of restarts is higher than *max_restarts* Varnish emits a guru meditation
    error.

  ``synth(status code, reason)``
    Transition to :ref:`vcl_synth` with ``resp.status`` and
    ``resp.reason`` being preset to the arguments of ``synth()``.

  ``fetch`` (deprecated)
    same as ``miss``. Will get removed in a future version, triggers a
    VCL_Error log message.

.. _vcl_miss:

vcl_miss
~~~~~~~~

Called after a cache lookup if the requested document was not found in
the cache or if :ref:`vcl_hit` returned ``fetch``.

Its purpose is to decide whether or not to attempt to retrieve the
document from the backend. A backend hint may be set as a default for
the backend processing side.

The `vcl_miss` subroutine may terminate with calling ``return()`` with one
of the following keywords:

  ``fetch``
    Retrieve the requested object from the backend. Control will
    eventually pass to `vcl_backend_fetch`.

  ``pass``
    Switch to pass mode. Control will eventually pass to :ref:`vcl_pass`.

  ``restart``
    Restart the transaction. Increases the restart counter. If the number
    of restarts is higher than *max_restarts* Varnish emits a guru meditation
    error.

  ``synth(status code, reason)``
    Transition to :ref:`vcl_synth` with ``resp.status`` and
    ``resp.reason`` being preset to the arguments of ``synth()``.

.. XXX: #1603 hit should not go to miss

.. _vcl_hash:

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)``:

  ``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 :ref:`vcl_hit`, :ref:`vcl_miss` or
    :ref:`vcl_pass` if the cache lookup result was a hit, a miss or hit
    on a hit-for-pass object (object with ``obj.uncacheable ==
    true``), respectively.

.. _vcl_purge:

vcl_purge
~~~~~~~~~

Called after the purge has been executed and all its variants have been evited.

The `vcl_purge` subroutine may terminate with calling ``return()`` with one
of the following keywords:

  ``restart``
    Restart the transaction. Increases the restart counter. If the number
    of restarts is higher than *max_restarts* Varnish emits a guru meditation
    error.

  ``synth(status code, reason)``
    Transition to :ref:`vcl_synth` with ``resp.status`` and
    ``resp.reason`` being preset to the arguments of ``synth()``.

.. _vcl_deliver:

vcl_deliver
~~~~~~~~~~~

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:

  ``deliver``
    Deliver the object to the client.

  ``restart``
    Restart the transaction. Increases the restart counter. If the number
    of restarts is higher than *max_restarts* Varnish emits a guru meditation
    error.

  ``synth(status code, reason)``
    Transition to :ref:`vcl_synth` with ``resp.status`` and
    ``resp.reason`` being preset to the arguments of ``synth()``.

.. _vcl_synth:

vcl_synth
~~~~~~~~~

Called to deliver a synthetic object. A synthetic object is generated
in VCL, not fetched from the backend. Its body may be constructed using
the ``synthetic()`` function.

A `vcl_synth` defined object never enters the cache, contrary to a
:ref:`vcl_backend_error` defined object, which may end up in cache.

The subroutine may terminate with calling ``return()`` with one of the
following keywords:

  ``deliver``
    Directly deliver the object defined by `vcl_synth` to the
    client without calling `vcl_deliver`.

  ``restart``
    Restart the transaction. Increases the restart counter. If the number
    of restarts is higher than *max_restarts* Varnish emits a guru meditation
    error.

------------
Backend Side
------------

.. _vcl_backend_fetch:

vcl_backend_fetch
~~~~~~~~~~~~~~~~~

Called before sending the backend request. In this subroutine you
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:

  ``fetch``
    Fetch the object from the backend.

  ``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.

.. _vcl_backend_response:

vcl_backend_response
~~~~~~~~~~~~~~~~~~~~

Called after the response headers have been successfully retrieved from
the backend.

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 independend 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:

  ``deliver``
    For a 304 response, create an updated cache object.
    Otherwise, fetch the object body from the backend and initiate
    delivery to any waiting client requests, possibly in parallel
    (streaming).

  ``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.

  ``retry``
    Retry the backend transaction. Increases the `retries` counter.
    If the number of retries is higher than *max_retries*,
    control will be passed to :ref:`vcl_backend_error`.

.. _vcl_backend_error:

vcl_backend_error
~~~~~~~~~~~~~~~~~

This subroutine is called if we fail the backend fetch or if
*max_retries* has been exceeded.

A synthetic object is generated in VCL, whose body may be constructed
using the ``synthetic()`` function.

The `vcl_backend_error` subroutine may terminate with calling ``return()``
with one of the following keywords:

  ``deliver``
    Deliver and possibly cache the object defined in
    `vcl_backend_error` **as if it was fetched from the backend**, also
    referred to as a "backend synth".

  ``retry``
    Retry the backend transaction. Increases the `retries` counter.
    If the number of retries is higher than *max_retries*,
    :ref:`vcl_synth` on the client side is called with ``resp.status``
    preset to 503.

----------------------
vcl.load / vcl.discard
----------------------

.. _vcl_init:

vcl_init
~~~~~~~~

Called when VCL is loaded, before any requests pass through it.
Typically used to initialize VMODs.

The `vcl_init` subroutine may terminate with calling ``return()``
with one of the following keywords:

  ``ok``
    Normal return, VCL continues loading.

  ``fail``
    Abort loading of this VCL.

.. _vcl_fini:

vcl_fini
~~~~~~~~

Called when VCL is discarded only after all requests have exited the VCL.
Typically used to clean up VMODs.

The `vcl_fini` subroutine may terminate with calling ``return()``
with one of the following keywords:

  ``ok``
    Normal return, VCL will be discarded.
