commit f247a97918f38d1e38e675709edcb672d64518dd
Author: Nils Goroll <nils.goroll@uplex.de>
Date: Tue Mar 14 14:14:01 2023 +0100
Polish release docs
- I think the excellent ESI processing changes documentation should
be promoted from changes.rst. I think it is more helpful to
users planning their upgrade, because it gives better advice.
- I thought we could be a little more verbose on abstract UDSes
and the weak Last-Modified changes.
- The director .release callback was not yet mentioned
All other changes are not worth mentioning I guess.
diff --git a/doc/sphinx/whats-new/changes-trunk.rst b/doc/sphinx/whats-new/changes-trunk.rst
index fc1e56cdb..8b1887150 100644
--- a/doc/sphinx/whats-new/changes-trunk.rst
+++ b/doc/sphinx/whats-new/changes-trunk.rst
@@ -32,26 +32,48 @@ from filling up storage too fast at the expense of cacheable resources. When
transit buffer is enabled, a client request will effectively hold its backend
connection open until the client response delivery completes.
+ESI processing changes
+----------------------
+
+Response status codes other than 200 and 204 are now considered errors for ESI
+fragments.
+
+Previously, any ``ESI:include`` object would be included, no matter what
+the status of it were, 200, 503, didn't matter.
+
+From now on, by default, only objects with 200 and 204 status will be
+included and any other status code will fail the parent ESI request.
+
+If objects with other status should be delivered, they should have
+their status changed to 200 in VCL, for instance in ``sub
+vcl_backend_error{}``, ``vcl_synth{}`` or ``vcl_deliver{}``.
+
+If ``param.set feature +esi_include_onerror`` is used, and the
+``<esi:include …>`` tag has a ``onerror="continue"`` attribute, any
+and all ESI:include objects will be delivered, no matter what their
+status might be, and not even a partial delivery of them will fail the
+parent ESI request. To be used with great caution.
+
+
Other changes in varnishd
~~~~~~~~~~~~~~~~~~~~~~~~~
-In addition to classic Unix-domain sockets, abstract sockets can now be used
-on Linux. Instead of an absolute path, the syntax ``-a @name`` can be used to
-bind the abstract socket called ``name``.
+In addition to classic Unix-domain sockets, Varnish now supports
+abstract sockets. If the operating system supports them, as does any
+fairly recent Linux kernel, abstract sockets can be specified using
+the commonplace ``@`` notation for accept sockets, e.g.::
+
+ varnishd -a @kandinsky
-Weak ``Last-Modified`` headers are no longer candidates for revalidation. This
-means that a subsequent fetch will not, when such a stale object is available,
-include an ``If-Modified-Since`` header. A weak ``Last-Modified`` header does
-not prevent ``Etag`` revalidation.
+Weak ``Last-Modified`` headers whose timestamp lies within one second
+of the corresponding ``Date`` header are no longer candidates for
+revalidation. This means that a subsequent fetch will not, when a
+stale object is available, include an ``If-Modified-Since`` header. A
+weak ``Last-Modified`` header does not prevent ``Etag`` revalidation.
A cache hit on an object being streamed no longer prevents delivery of partial
responses (status code 206) to range requests.
-Response status codes other than 200 and 204 are now considered errors for ESI
-fragments. The default behavior was changed, errors are no longer delivered by
-default. The feature flag ``esi_include_onerror`` can be raised to allow a
-backend to specify whether to continue.
-
Changes to VCL
==============
@@ -70,7 +92,7 @@ variable.
Other changes to VCL
~~~~~~~~~~~~~~~~~~~~
-Backends have a new ``.via`` attribute referencing another backend::
+Backends have a new ``.via`` attribute optionally referencing another backend::
backend detour {
.host = "...";
@@ -88,8 +110,8 @@ define an authority TLV in the PROXYv2 header.
Backends can connect to abstract sockets on linux::
- backend abstract {
- .path = "@name";
+ backend miro {
+ .path = "@miro";
}
This is the same syntax as the ``varnishd -a`` command line option.
@@ -108,10 +130,11 @@ varnishlog
**XXX changes concerning varnishlog(1) and/or vsl(7)**
-The in-memory and on-disk format of VSL records changed to allow 64bit VXID
-numbers. The new binary format is not compatible with previous versions, and
-log dumps performed with a previous Varnish release are no longer readable
-from now on. Consequently, unused log tags have been removed.
+The in-memory and on-disk format of VSL records changed to allow 64bit
+VXID numbers. The new binary format is **not compatible** with
+previous versions, and log dumps performed with a previous Varnish
+release are no longer readable from now on. Consequently, unused log
+tags have been removed.
The VXID range is limited to ``VRT_INTEGER`` to fit in VCL the variables
``req.xid``, ``bereq.xid`` and ``sess.xid``.
@@ -124,10 +147,8 @@ varnishadm
**XXX changes concerning varnishadm(1) and/or varnish-cli(7)**
-The ``debug.xid`` command generally used by ``varnishtest`` used to set up the
-current VXID. As the intent usually is to set up the next VXID, this forced to
-set an off-by-one value. To simplify its usage it now sets up the next VXID
-directly.
+The ``debug.xid`` command generally used by ``varnishtest`` now sets
+up the next VXID directly.
varnishstat
===========
diff --git a/doc/sphinx/whats-new/upgrading-trunk.rst b/doc/sphinx/whats-new/upgrading-trunk.rst
index 6a2f56cff..98b5b92d2 100644
--- a/doc/sphinx/whats-new/upgrading-trunk.rst
+++ b/doc/sphinx/whats-new/upgrading-trunk.rst
@@ -43,24 +43,45 @@ binary logs need to remain usable, the only solution is to use a compatible
Varnish version and at the time of this release, the 6.0 branch is the only
one without an EOL date.
+For developers and VMOD authors: C interface changes requiring adjustments
+==========================================================================
+
Via backends
-============
+------------
The new backend argument to the ``VRT_new_backend*()`` functions is optional
and ``NULL`` can be passed to match the previous behavior.
suckaddr
-========
+--------
The following functions return or accept ``const`` pointers from now on:
- ``VSA_Clone()``
- ``VSA_getsockname()``
- ``VSA_getpeername()``
-- ``VSA_free()``
- ``VSA_Malloc()``
- ``VSA_Build*()``
- ``VSS_ResolveOne()``
- ``VSS_ResolveFirst()``
+``VSA_free()`` has been added to free heap memory allocated by
+``VSA_Malloc()`` or one of the ``VSA_Build*()`` functions with a
+``NULL`` first argument.
+
+directors
+---------
+
+Directors which take and hold references to other directors via
+``VRT_Assign_Backend()`` (typically any director which has other
+directors as backends) are now expected to implement the new
+``.release`` callback of type ``void
+vdi_release_f(VCL_BACKEND)``. This function is called by
+``VRT_DelDirector()``. The implementation is expected drop any backend
+references which the director holds (again using
+``VRT_Assign_Backend()`` with ``NULL`` as the second argument).
+
+Failure to implement this callback can result in deadlocks, in
+particular during VCL discard.
+
*eof*
_______________________________________________
varnish-commit mailing list
varnish-commit@varnish-cache.org
https://www.varnish-cache.org/lists/mailman/listinfo/varnish-commit
Author: Nils Goroll <nils.goroll@uplex.de>
Date: Tue Mar 14 14:14:01 2023 +0100
Polish release docs
- I think the excellent ESI processing changes documentation should
be promoted from changes.rst. I think it is more helpful to
users planning their upgrade, because it gives better advice.
- I thought we could be a little more verbose on abstract UDSes
and the weak Last-Modified changes.
- The director .release callback was not yet mentioned
All other changes are not worth mentioning I guess.
diff --git a/doc/sphinx/whats-new/changes-trunk.rst b/doc/sphinx/whats-new/changes-trunk.rst
index fc1e56cdb..8b1887150 100644
--- a/doc/sphinx/whats-new/changes-trunk.rst
+++ b/doc/sphinx/whats-new/changes-trunk.rst
@@ -32,26 +32,48 @@ from filling up storage too fast at the expense of cacheable resources. When
transit buffer is enabled, a client request will effectively hold its backend
connection open until the client response delivery completes.
+ESI processing changes
+----------------------
+
+Response status codes other than 200 and 204 are now considered errors for ESI
+fragments.
+
+Previously, any ``ESI:include`` object would be included, no matter what
+the status of it were, 200, 503, didn't matter.
+
+From now on, by default, only objects with 200 and 204 status will be
+included and any other status code will fail the parent ESI request.
+
+If objects with other status should be delivered, they should have
+their status changed to 200 in VCL, for instance in ``sub
+vcl_backend_error{}``, ``vcl_synth{}`` or ``vcl_deliver{}``.
+
+If ``param.set feature +esi_include_onerror`` is used, and the
+``<esi:include …>`` tag has a ``onerror="continue"`` attribute, any
+and all ESI:include objects will be delivered, no matter what their
+status might be, and not even a partial delivery of them will fail the
+parent ESI request. To be used with great caution.
+
+
Other changes in varnishd
~~~~~~~~~~~~~~~~~~~~~~~~~
-In addition to classic Unix-domain sockets, abstract sockets can now be used
-on Linux. Instead of an absolute path, the syntax ``-a @name`` can be used to
-bind the abstract socket called ``name``.
+In addition to classic Unix-domain sockets, Varnish now supports
+abstract sockets. If the operating system supports them, as does any
+fairly recent Linux kernel, abstract sockets can be specified using
+the commonplace ``@`` notation for accept sockets, e.g.::
+
+ varnishd -a @kandinsky
-Weak ``Last-Modified`` headers are no longer candidates for revalidation. This
-means that a subsequent fetch will not, when such a stale object is available,
-include an ``If-Modified-Since`` header. A weak ``Last-Modified`` header does
-not prevent ``Etag`` revalidation.
+Weak ``Last-Modified`` headers whose timestamp lies within one second
+of the corresponding ``Date`` header are no longer candidates for
+revalidation. This means that a subsequent fetch will not, when a
+stale object is available, include an ``If-Modified-Since`` header. A
+weak ``Last-Modified`` header does not prevent ``Etag`` revalidation.
A cache hit on an object being streamed no longer prevents delivery of partial
responses (status code 206) to range requests.
-Response status codes other than 200 and 204 are now considered errors for ESI
-fragments. The default behavior was changed, errors are no longer delivered by
-default. The feature flag ``esi_include_onerror`` can be raised to allow a
-backend to specify whether to continue.
-
Changes to VCL
==============
@@ -70,7 +92,7 @@ variable.
Other changes to VCL
~~~~~~~~~~~~~~~~~~~~
-Backends have a new ``.via`` attribute referencing another backend::
+Backends have a new ``.via`` attribute optionally referencing another backend::
backend detour {
.host = "...";
@@ -88,8 +110,8 @@ define an authority TLV in the PROXYv2 header.
Backends can connect to abstract sockets on linux::
- backend abstract {
- .path = "@name";
+ backend miro {
+ .path = "@miro";
}
This is the same syntax as the ``varnishd -a`` command line option.
@@ -108,10 +130,11 @@ varnishlog
**XXX changes concerning varnishlog(1) and/or vsl(7)**
-The in-memory and on-disk format of VSL records changed to allow 64bit VXID
-numbers. The new binary format is not compatible with previous versions, and
-log dumps performed with a previous Varnish release are no longer readable
-from now on. Consequently, unused log tags have been removed.
+The in-memory and on-disk format of VSL records changed to allow 64bit
+VXID numbers. The new binary format is **not compatible** with
+previous versions, and log dumps performed with a previous Varnish
+release are no longer readable from now on. Consequently, unused log
+tags have been removed.
The VXID range is limited to ``VRT_INTEGER`` to fit in VCL the variables
``req.xid``, ``bereq.xid`` and ``sess.xid``.
@@ -124,10 +147,8 @@ varnishadm
**XXX changes concerning varnishadm(1) and/or varnish-cli(7)**
-The ``debug.xid`` command generally used by ``varnishtest`` used to set up the
-current VXID. As the intent usually is to set up the next VXID, this forced to
-set an off-by-one value. To simplify its usage it now sets up the next VXID
-directly.
+The ``debug.xid`` command generally used by ``varnishtest`` now sets
+up the next VXID directly.
varnishstat
===========
diff --git a/doc/sphinx/whats-new/upgrading-trunk.rst b/doc/sphinx/whats-new/upgrading-trunk.rst
index 6a2f56cff..98b5b92d2 100644
--- a/doc/sphinx/whats-new/upgrading-trunk.rst
+++ b/doc/sphinx/whats-new/upgrading-trunk.rst
@@ -43,24 +43,45 @@ binary logs need to remain usable, the only solution is to use a compatible
Varnish version and at the time of this release, the 6.0 branch is the only
one without an EOL date.
+For developers and VMOD authors: C interface changes requiring adjustments
+==========================================================================
+
Via backends
-============
+------------
The new backend argument to the ``VRT_new_backend*()`` functions is optional
and ``NULL`` can be passed to match the previous behavior.
suckaddr
-========
+--------
The following functions return or accept ``const`` pointers from now on:
- ``VSA_Clone()``
- ``VSA_getsockname()``
- ``VSA_getpeername()``
-- ``VSA_free()``
- ``VSA_Malloc()``
- ``VSA_Build*()``
- ``VSS_ResolveOne()``
- ``VSS_ResolveFirst()``
+``VSA_free()`` has been added to free heap memory allocated by
+``VSA_Malloc()`` or one of the ``VSA_Build*()`` functions with a
+``NULL`` first argument.
+
+directors
+---------
+
+Directors which take and hold references to other directors via
+``VRT_Assign_Backend()`` (typically any director which has other
+directors as backends) are now expected to implement the new
+``.release`` callback of type ``void
+vdi_release_f(VCL_BACKEND)``. This function is called by
+``VRT_DelDirector()``. The implementation is expected drop any backend
+references which the director holds (again using
+``VRT_Assign_Backend()`` with ``NULL`` as the second argument).
+
+Failure to implement this callback can result in deadlocks, in
+particular during VCL discard.
+
*eof*
_______________________________________________
varnish-commit mailing list
varnish-commit@varnish-cache.org
https://www.varnish-cache.org/lists/mailman/listinfo/varnish-commit