We have put some thought to the interpretation of the ``+`` and ``-``
operators for various combinations of operands with differing data
types, many of which count as corner cases (what does it mean, for
example, to subtract a string from an IP address?). Recall that ``+``
denotes addition for numeric operands, and string concatenation for
string operands; operands may be converted to strings and
concatenated, if a string is expected and there is no sensible numeric
interpretation.

The semantics have not changed in nearly all cases, but the error
messages for illegal combinations of operands have improved. Most
importantly, we have taken the time to review these cases, so this
will be the way VCL works going forward.

To summarize:

* If both operands of ``+`` or ``-`` are one of BYTES, DURATION, INT
  or REAL, then the result has the same data type, with the obvious
  numeric interpretation. If such an expression is evaluated in a
  context that expects a STRING (for example for assignment to a
  header), then the arithmetic is done first, and the result it
  converted to a STRING.

* INTs and REALs can be added or subtracted to yield a REAL.

* A DURATION can be added to or subtracted from a TIME to yield a
  TIME.

* No other combinations of operand types are legal with ``-``.

* When a ``+`` expression is evaluated in a STRING context, then for
  all other combinations of operand data types, the operands are
  converted to STRINGs and concatenated.

* If a STRING is not expected for the ``+`` expression, then no other
  combination of data types is legal.

Other notes on data types:

* When ``bereq.backend`` is set to a director, then it returns an
  actual backend on subsequent reads if the director resolves to a
  backend immediately, or the director otherwise. If ``bereq.backend``
  was set to a director, then ``beresp.backend`` references the backend
  to which it was set for the fetch.  When either of these is used in
  string context, it returns the name of the director or of the
  resolved backend.

* Comparisons between symbols of type BACKEND now work properly::

      if (bereq.backend == foo.backend()) {
          # do something specific to the foo backends
      }

* DURATION types may be used in boolean contexts, and are evaluated as
  false when the duration is less than or equal to zero, true
  otherwise.

* INT, DURATION and REAL values can now be negative.

Response codes
~~~~~~~~~~~~~~

Response codes 1000 or greater may now be set in VCL internally.
``resp.status`` is delivered modulo 1000 in client responses.

IP address comparison

The data type STEVEDORE for storage backends is now available in VCL
and for VMODs. Storage objects with names of the form
``storage.SNAME`` will exist in a VCL instance, where ``SNAME`` is the
name of a storage backend provided with the ``varnishd`` command-line
option ``-s``. If no ``-s`` option is given, then ``storage.s0``
denotes the default storage.  The object ``storage.Transient`` always
exists, designating transient storage. See :ref:`guide-storage`, and
the notes about ``beresp.storage`` and ``req.storage`` below.

All VCL subroutines (except ``vcl_fini``)

* ``req.ttl`` is deprecated, see :ref:`vcl(7)`.

vcl_recv
~~~~~~~~

* Added ``req.storage``, which tells Varnish which storage backend to
  use if you choose to save the request body (see
  :ref:`std.cache_req_body()`).

* ``return(vcl(LABEL))`` may not be called after a restart. It can
  only be called from the active VCL instance.

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

* Added ``return(pass(DURATION))`` to set an object to hit-for-pass,
  see :ref:`whatsnew_changes_5.1_hitpass`.

* The object ``beresp.storage`` of type STEVEDORE should now be used
  to set a storage backend; ``beresp.storage_hint`` is deprecated and
  will be removed in a future release. Setting ``beresp.storage_hint``
  to a valid storage will set ``beresp.storage`` as well. If the
  storage is invalid, ``beresp.storage`` is left untouched.

For the case where multiple storage backends have been defined with
the ``-s`` command-line option for varnishd, but none is explicitly
set in ``vcl_backend_response``, storage selection and the use of the
nuke limit has been reworked (see
:ref:`ref_param_nuke_limit`). Previously, a storage backend was tried
first with a nuke limit of 0, and retried on failure with the limit
configured as the ``-p`` parameter ``nuke_limit``. When no storage was
specified, Varnish went through every one in round-robin order with a
nuke limit of 0 before retrying.

Now ``beresp.storage`` is initialized with a storage backend before
``vcl_backend_response`` executes, and the storage set in
``beresp.storage`` after its execution will be used. The configured
nuke limit is used in all cases.

vmod_std
~~~~~~~~

* Added :ref:`std.getenv()`.

* Added :ref:`std.late_100_continue()`.

Other changes
=============

* The storage backend type umem, long in disuse, has been retired.

* ``varnishstat(1)``:

  * Added the ``cache_hitmiss`` stat to count hits on hit-for-miss
    objects.

  * The ``cache_hitpass`` stat now only counts hits on hit-for-pass
    objects.

  * ``fetch_failed`` is incremented for any kind of fetch failure --
    when there is a failure after ``return(deliver)`` from
    ``vcl_backend_response``, or when control is diverted to
    ``vcl_backend_error``.

  * Added the ``n_test_gunzip`` stat, which is incremented when
    Varnish verifies a compressed response from a backend -- this
    operation was previously counted together with ``n_gunzip``.

  * Added the ``bans_lurker_obj_killed_cutoff`` stat to count the
    number of objects killed by the ban lurker to keep the number of
    bans below ``ban_cutoff``.

* ``varnishlog(1)``:

  * Hits on hit-for-miss and hit-for-pass objects are logged with
    the ``HitMiss`` and ``HitPass`` tags, respectively. In each case,
    the log payload is the VXID of the previous transaction in which
    the object was saved in the cache (as with ``Hit``).

  * An entry with the ``TTL`` tag and the prefix ``HFP`` is logged to
    record the duration set for hit-for-pass objects.

  * Added ``vxid`` as a lefthand side token for VSL queries, allowing
    for queries that search for transaction IDs in the log. See
    :ref:`vsl-query(7)`.

* ``varnishncsa(1)``:

  * Clarified the meaning of the ``%r`` formatter, see NOTES in
    :ref:`varnishncsa(1)`.

  * Clarified the meaning of the ``%{X}i`` and ``%{X}o`` formatters
    when the header X appears more than once (the last occurrence is
    is used).

* ``varnishtest(1)``:

  * Added the ``setenv`` and ``write_body`` commands, see :ref:`vtc(7)`.

  * ``-reason`` replaces ``-msg`` to set the reason string for a
    response (default "OK").

  * Added ``-cliexpect`` to match expected CLI responses to regular
    expressions.

  * Added the ``-match`` operator for the ``shell`` command.

  * Added the ``-hdrlen`` operator to generate a header with a
    given name and length.

  * The ``err_shell`` command is deprecated, use ``shell -err
    -expect`` instead.

  * The ``${bad_backend}`` macro can now be used for a backend that
    is always down, which does not require a port definition (as does
    ``${bad_ip}`` in a backend definition).

  * ``varnishtest`` can be stopped with the ``TERM``, ``INT`` of ``KILL``
    signals, but not with ``HUP``. These signals kill the process group,
    so that processes started by running tests are stopped.

* Added the ``vtest.sh`` tool to automate test builds, see
  :ref:`whatsnew_changes_5.1_vtest`.