[6.3] 8bf140bb0 Initial release notes for Varnish 6.3.0
Dridi Boukelmoune
dridi.boukelmoune at gmail.com
Thu Feb 20 16:01:07 UTC 2020
commit 8bf140bb04e6c1fda67b957db8091d2996e8f47a
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date: Thu Feb 20 12:04:31 2020 +0100
Initial release notes for Varnish 6.3.0
This is a result of a commit review between 6.2.0 and 6.3.0 and while
it should in theory be comprehensive, it is not. The upgrade notes in
particular are developer-centric, which may be a sign that none of the
changes require attention during an upgrade it could as well be an
oversight.
There is one item that I identified that should be mentioned in the
upgrade guide. I invite @nigoroll to give a shot at the VCL auto state.
In the absence of a fair warning, I extended WS_Reserve's grace period.
I omitted the -rcvbuf action on purpose, for the same reason why it is
not documented in vtc(7) on purpose: it's currently used in conjunction
with vmod_debug and we don't ship it.
While this is a milestone, I don't consider this work to be done so I
didn't remove the notes saying so.
We should also probably partially pick 53b4d2f58202 on the 6.3 branch.
diff --git a/bin/varnishd/cache/cache_ws.c b/bin/varnishd/cache/cache_ws.c
index 799bc0aa3..834158e13 100644
--- a/bin/varnishd/cache/cache_ws.c
+++ b/bin/varnishd/cache/cache_ws.c
@@ -273,7 +273,7 @@ WS_ReserveSize(struct ws *ws, unsigned bytes)
return (pdiff(ws->f, ws->r));
}
-/* REL_20200315 remove */
+/* REL_20200915 remove */
unsigned
WS_Reserve(struct ws *ws, unsigned bytes)
{
diff --git a/doc/sphinx/whats-new/changes-6.3.rst b/doc/sphinx/whats-new/changes-6.3.rst
index 377b73d8f..d73a8c930 100644
--- a/doc/sphinx/whats-new/changes-6.3.rst
+++ b/doc/sphinx/whats-new/changes-6.3.rst
@@ -23,28 +23,82 @@ varnishd
Parameters
~~~~~~~~~~
-**XXX changes in -p parameters**
+A new :ref:`ref_param_pipe_sess_max` parameter allows to limit the number of
+concurrent pipe transactions. The default value is zero and means unlimited,
+for backwards compatibility.
Other changes in varnishd
~~~~~~~~~~~~~~~~~~~~~~~~~
+The transferred bytes accounting for HTTP/2 sessions is more accurate:
+``ReqAcct`` log records no longer report a full delivery if a stream did
+not complete.
+
+The meaning of VCL temperature changed for the ``auto`` state: it used to
+automatically cool down a VCL transitioning from active to available, but
+that VCL would remain ``cold``. It now works in both directions, and such a
+cold VCL keeps the ``auto`` state and may be used or labelled immediately
+without an explicit change of state to ``warm``.
+
+As a result, a VCL with the ``cold`` state will no longer warm up
+automatically.
+
+The management of counters, and in particular dynamic counters (for example
+appearing or disappearing when a VCL is loaded or discarded), has seen
+significant performance improvements and setups involving a large amount of
+backends should be more responsive.
+
Changes to VCL
==============
VCL variables
~~~~~~~~~~~~~
-**XXX new, deprecated or removed variables, or changed semantics**
+The :ref:`ref_param_timeout_idle` parameter can be overriden in VCL using the
+``sess.timeout_idle`` variable.
Other changes to VCL
~~~~~~~~~~~~~~~~~~~~
-**TODO: return (error);**
+A new ``error`` transition to ``vcl_backend_error`` allows to purposely move
+to that subroutine. It is similar to the ``synth`` transition and can
+optionally take arguments. The three following statements are equivalent::
+
+ return (error);
+ return (error(503));
+ return (error(503, "Service Unavailable"));
+
+The ``error`` transition is available in :ref:`vcl_backend_fetch` and
+:ref:`vcl_backend_response`. Using an explicit ``error`` transition in
+``vcl_backend_fetch`` does not increment the ``MAIN.fetch_failed`` counter.
+
+It is possible to import the same VMOD twice, as long as the two imports are
+identical and wouldn't otherwise conflict. This allows for example included
+VCL files to import the VMODs they need without preventing the including VCL
+to also perform the same import.
+
+Similarly, it is now possible to include a VMOD under a different name::
+
+ import directors as dir;
+
+ sub vcl_init {
+ new rr = dir.round_robin();
+ }
+
+This can be useful for VMODs with a long name, or VMODs that could use a
+more expressive name in VCL code.
+
+The built-in VCL turns the ``Host`` header lowercase in ``vcl_recv`` to
+improve its hashing later in ``vcl_hash`` since domain names are case
+insensitive.
VMODs
=====
-**XXX changes in the bundled VMODs**
+``std.ip()`` now takes an optional ``STRING`` argument to specify a port
+number or service name.
+
+See: :ref:`std.ip()`
vsl-query(7)
============
@@ -122,25 +176,53 @@ will operate as if the ``or`` operator was used to join all the queries.
A new ``-Q`` option allows you to read the query from a file instead. It
can also be used multiple times and adds up to any ``-q`` option specified.
-varnishadm
-==========
+Similar to ``-c`` or ``-b`` for client or backend transactions,
+``varnishncsa(1)`` can take a ``-E`` option to include ESI transactions.
-**XXX changes concerning varnishadm(1) and/or varnish-cli(7)**
+``BackendStart`` log records are no longer used, but newer versions of log
+utilities should still recognize deprecated records. It remains possible
+to read logs written to a file with an older version of ``varnishlog(1)``,
+and that backward compatibility officially goes as far as Varnish 6.0.0
+even though it *may* be possible to read logs saved from older releases.
+
+``Debug`` records are no longer logged by default and can be removed from
+the :ref:`ref_param_vsl_mask` parameter to appear in the logs. Since such
+records are not meant for production they are only automatically enabled
+by ``varnishtest(1)``.
varnishstat
===========
-**XXX changes concerning varnishstat(1) and/or varnish-counters(7)**
+A new ``MAIN.n_pipe`` gauge keeps track of the number of ongoing pipe
+transactions.
+
+A new ``MAIN.pipe_limited`` counter keeps track of how many times a
+transaction failed to turn into a pipe because of the
+:ref:`ref_param_pipe_sess_max` parameter.
varnishtest
===========
-**XXX changes concerning varnishtest(1) and/or vtc(7)**
+A ``client`` can now use the ``-method`` action for ``txreq`` commands to
+specify the request method. This used to be done with ``-req`` which remains
+as an alias for compatibility.
+
+A ``client`` or ``server`` may use the ``-bodyfrom`` action for respectively
+``txreq`` or ``txresp`` commands to send a body from a file.
+
+An HTTP/2 ``client`` or ``server`` can work with gzip content encoding and has
+access to ``-gzipbody`` and ``-gziplen``.
Changes for developers and VMOD authors
=======================================
-**XXX changes concerning VRT, the public APIs, source code organization,
-builds etc.**
+The most notable change for VMOD developers is the deprecation of string lists
+in favor of strands.
+
+As usual, new functions were added to VRT, and others were changed or removed.
+See ``vrt.h`` for a list of changes since the 6.2.0 release.
+
+We continue to remove functions from VRT that weren't meant to be used by VMOD
+authors and were only part of the VMOD infrastructure code.
*eof*
diff --git a/doc/sphinx/whats-new/upgrading-6.3.rst b/doc/sphinx/whats-new/upgrading-6.3.rst
index dfd4f3510..df269e077 100644
--- a/doc/sphinx/whats-new/upgrading-6.3.rst
+++ b/doc/sphinx/whats-new/upgrading-6.3.rst
@@ -14,20 +14,42 @@ features are listed in "Changes". Explicitly mention what does *not*
have to be changed, especially in VCL. May include, but is not limited
to:**
-* Elements of VCL that have been removed or are deprecated, or whose
- semantics have changed.
+TODO: a word on VCL temperature and the ``auto`` change.
-* -p parameters that have been removed or are deprecated, or whose
- semantics have changed.
+For developers and authors of VMODs and API clients
+===================================================
-* Changes in the CLI.
+The Python 2 EOL is approaching and our build system now favors Python 3. In
+the 2020-03-15 release we plan to only support Python 3.
-* Changes in the output or interpretation of stats or the log, including
- changes affecting varnishncsa/-hist/-top.
+The "vararg" ``VCL_STRING_LIST`` type is superseded by the array-based
+``VCL_STRANDS`` type. The deprecated string list will eventually be removed
+entirely and VMOD authors are strongly encouraged to convert to strands.
+VRT functions working with string list arguments now take strands.
-* Changes that may be necessary in VTCs or in the use of varnishtest.
+More functions such as ``VRT_Vmod_Init()`` and ``VRT_Vmod_Unload()`` from
+the VRT namespace moved away to the Varnish Private Interface (VPI). Such
+functions were never intended for VMODs in the first place.
-* Changes in public APIs that may require changes in VMODs or VAPI/VUT
- clients.
+The functions ``VRT_ref_vcl()`` and ``VRT_rel_vcl()`` were renamed to
+respectively ``VRT_VCL_Prevent_Discard()`` and ``VRT_VCL_Allow_Discard()``.
+
+Some functions taking ``VCL_IP`` arguments now take a ``VRT_CTX`` in order
+to fail in the presence of an invalid IP address.
+
+See ``vrt.h`` for a list of changes since the 6.2.0 release.
+
+We sometimes use Coccinelle_ to automate C code refactoring throughout the
+code base. Our collection of semantic patches may be used by VMOD and API
+clients authors and are available in the Varnish source tree in the
+``tools/coccinelle/`` directory.
+
+.. _Coccinelle: http://coccinelle.lip6.fr/
+
+The ``WS_Reserve()`` function is deprecated and replaced by two functions
+``WS_ReserveAll()`` and ``WS_ReserveSize()`` to avoid ambiguous situations.
+Its removal is planned for the 2020-09-15 release.
+
+A ``ws_reserve.cocci`` semantic patch can help with the transition.
*eof*
More information about the varnish-commit
mailing list