commit f4068c8f285f69475a11a231332730aeac7742f7
Author: Dridi Boukelmoune <dridi.boukelmoune@gmail.com>
Date: Thu Mar 14 23:33:50 2024 +0100
whats-new: Clarify changes to bits parameters
Quick attempt to address 3f69805f91ff70d55d2585214445abf267e4e26b.
The remaining TODO in the changes needs to be addressed, and upgrade
notes are empty.
diff --git a/doc/sphinx/whats-new/changes-trunk.rst b/doc/sphinx/whats-new/changes-trunk.rst
index f592518f7..714f44cee 100644
--- a/doc/sphinx/whats-new/changes-trunk.rst
+++ b/doc/sphinx/whats-new/changes-trunk.rst
@@ -19,41 +19,10 @@ varnishd
Parameters
~~~~~~~~~~
-**XXX changes in -p parameters**
-
The default value of ``cli_limit`` has been increased from 48KB to
64KB to avoid truncating the ``param.show -j`` output for common use
cases.
-The ``vsl_mask`` parameter accepts a new special value "all" that enables
-logging of all VSL tags, the counterpart of "none".
-
-.. I am not sure if "absolute value" is the best name here. It is
- "relative to all", but I do not have a better idea
-
-This allows all bits parameters to be set atomically to an absolute
-value, as in::
-
- param.set vsl_mask all,-Debug,-ExpKill
-
-The ``param.show`` output prints the absolute value. This enables
-operations to atomically set a bits parameter, relative or absolute,
-and collect the absolute value::
-
- param.show vsl_mask
- 200
- vsl_mask
- Value is: all,-Debug,-ExpKill
- [...]
-
-The ``param.set`` command in JSON mode (``-j argument``) prints the
-``param.show`` JSON output after successfully updating a
-parameter. The ``param.reset`` command now shares the same behavior.
-
-The special value ``default`` for bits parameters was deprecated in
-favor of the generic ``param.reset`` command. It will be removed in a
-future release.
-
A new ``pipe_task_deadline`` specifies the maximum duration of a pipe
transaction. The default value is the special value "never" to align with the
former lack of such timeout::
@@ -77,6 +46,65 @@ All the timeout parameters that can be disabled accept the "never" value:
The :ref:`varnishd(1)` manual advertises the ``timeout`` flag for these
parameters.
+Bits parameters
+~~~~~~~~~~~~~~~
+
+In Varnish 7.1.0 the ``param.set`` command grew a new ``-j`` option that
+displays the same output as ``param.show -j`` for the parameter that is
+successfully updated.
+
+The goal was to atomically change a value and communicate how a subsequent
+``param.show`` would render it. This could be used for consistency checks,
+to ensure that a parameter was not changed by a different party. Collecting
+how the parameter is displayed can be important for example for floating-point
+numbers parameters that could be displayed with different resolutions, or
+parameters that can take units and have multiple representations.
+
+Here is a concrete example::
+
+ $ varnishadm param.set -j workspace_client 16384 | jq '.[3].value'
+ 16384
+ $ varnishadm param.set -j workspace_client 128k | jq '.[3].value'
+ 131072
+
+However, this could not work with bits parameters::
+
+ $ varnishadm param.set -j feature +http2 | jq -r '.[3].value'
+ +http2,+validate_headers
+
+If the ``feature`` parameter is changed, reusing the output of ``param.set``
+cannot guarantee the restoration that exact value::
+
+ $ varnishadm param.set -j feature +http2,+validate_headers | jq -r '.[3].value'
+ +http2,+no_coredump,+validate_headers
+
+To fill this gap, bits parameters are now displayed as absolute values,
+relative to none of the bits being set. A list of bits can start with the
+special value ``none`` to clear all the bits, followed by specific bits to
+raise::
+
+ $ varnishadm param.set -j feature +http2 | jq -r '.[3].value'
+ none,+http2,+validate_headers
+ $ varnishadm param.set -j feature none,+http2,+validate_headers | jq -r '.[3].value'
+ none,+http2,+validate_headers
+
+The output of ``param.show`` and ``param.set`` is now idempotent for bits
+parameters, and can be used by a consistency check system to restore a
+parameter to its desired value.
+
+Almost all bits parameters are displayed as bits set relative to a ``none``
+value. The notable exception is ``vsl_mask`` that is expressed with bits
+cleared. For this purpose the ``vsl_mask`` parameter is now displayed as
+bits cleared relative to an ``all`` value::
+
+
+ $ varnishadm param.set -j vsl_mask all,-Debug | jq -r '.[3].value'
+ all,-Debug
+
+The special value ``default`` for bits parameters was deprecated in
+favor of the generic ``param.reset`` command. It might be removed in a
+future release.
+
Other changes in varnishd
~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -109,8 +137,6 @@ Changes to VCL
VCL variables
~~~~~~~~~~~~~
-**XXX new, deprecated or removed variables, or changed semantics**
-
A new ``bereq.task_deadline`` variable is available in ``vcl_pipe`` to
override the ``pipe_task_deadline`` parameter.
@@ -158,16 +184,9 @@ Other changes to VCL
The new ``+fold`` flag for ACLs merges adjacent subnets together and optimize
out subnets for which there exist another all-encompassing subnet.
-VMODs
-=====
-
-**XXX changes in the bundled VMODs**
-
varnishlog
==========
-**XXX changes concerning varnishlog(1) and/or vsl(7)**
-
When a ``BackendClose`` record includes a reason field, it now shows the
reason tag (for example ``RX_TIMEOUT``) instead of its description (Receive
timeout) to align with ``SessClose`` records. See :ref:`vsl(7)`.
@@ -192,16 +211,9 @@ without having to repeat it::
varnishncsa -F ``%{Varnish:default_format}x %{Varnish:handling}x``
-varnishadm
-==========
-
-**XXX changes concerning varnishadm(1) and/or varnish-cli(7)**
-
varnishstat
===========
-**XXX changes concerning varnishstat(1) and/or varnish-counters(7)**
-
A new counter ``MAIN.n_superseded`` adds visibility on how many objects are
inserted as the replacement of another object in the cache. This can give
insights regarding the nature of churn in a cache.
@@ -209,8 +221,6 @@ insights regarding the nature of churn in a cache.
varnishtest
===========
-**XXX changes concerning varnishtest(1) and/or vtc(7)**
-
When an HTTP/2 stream number does not matter and the stream is handled in a
single block, the automatic ``next`` identifier can be used::
@@ -231,9 +241,6 @@ include command itself. There are no guards against recursive includes.
Changes for developers and VMOD authors
=======================================
-**XXX changes concerning VRT, the public APIs, source code organization,
-builds etc.**
-
The ``VSB_tofile()`` function can work with VSBs larger than ``INT_MAX`` and
tolerate partial writes.
_______________________________________________
varnish-commit mailing list
varnish-commit@varnish-cache.org
https://www.varnish-cache.org/lists/mailman/listinfo/varnish-commit
Author: Dridi Boukelmoune <dridi.boukelmoune@gmail.com>
Date: Thu Mar 14 23:33:50 2024 +0100
whats-new: Clarify changes to bits parameters
Quick attempt to address 3f69805f91ff70d55d2585214445abf267e4e26b.
The remaining TODO in the changes needs to be addressed, and upgrade
notes are empty.
diff --git a/doc/sphinx/whats-new/changes-trunk.rst b/doc/sphinx/whats-new/changes-trunk.rst
index f592518f7..714f44cee 100644
--- a/doc/sphinx/whats-new/changes-trunk.rst
+++ b/doc/sphinx/whats-new/changes-trunk.rst
@@ -19,41 +19,10 @@ varnishd
Parameters
~~~~~~~~~~
-**XXX changes in -p parameters**
-
The default value of ``cli_limit`` has been increased from 48KB to
64KB to avoid truncating the ``param.show -j`` output for common use
cases.
-The ``vsl_mask`` parameter accepts a new special value "all" that enables
-logging of all VSL tags, the counterpart of "none".
-
-.. I am not sure if "absolute value" is the best name here. It is
- "relative to all", but I do not have a better idea
-
-This allows all bits parameters to be set atomically to an absolute
-value, as in::
-
- param.set vsl_mask all,-Debug,-ExpKill
-
-The ``param.show`` output prints the absolute value. This enables
-operations to atomically set a bits parameter, relative or absolute,
-and collect the absolute value::
-
- param.show vsl_mask
- 200
- vsl_mask
- Value is: all,-Debug,-ExpKill
- [...]
-
-The ``param.set`` command in JSON mode (``-j argument``) prints the
-``param.show`` JSON output after successfully updating a
-parameter. The ``param.reset`` command now shares the same behavior.
-
-The special value ``default`` for bits parameters was deprecated in
-favor of the generic ``param.reset`` command. It will be removed in a
-future release.
-
A new ``pipe_task_deadline`` specifies the maximum duration of a pipe
transaction. The default value is the special value "never" to align with the
former lack of such timeout::
@@ -77,6 +46,65 @@ All the timeout parameters that can be disabled accept the "never" value:
The :ref:`varnishd(1)` manual advertises the ``timeout`` flag for these
parameters.
+Bits parameters
+~~~~~~~~~~~~~~~
+
+In Varnish 7.1.0 the ``param.set`` command grew a new ``-j`` option that
+displays the same output as ``param.show -j`` for the parameter that is
+successfully updated.
+
+The goal was to atomically change a value and communicate how a subsequent
+``param.show`` would render it. This could be used for consistency checks,
+to ensure that a parameter was not changed by a different party. Collecting
+how the parameter is displayed can be important for example for floating-point
+numbers parameters that could be displayed with different resolutions, or
+parameters that can take units and have multiple representations.
+
+Here is a concrete example::
+
+ $ varnishadm param.set -j workspace_client 16384 | jq '.[3].value'
+ 16384
+ $ varnishadm param.set -j workspace_client 128k | jq '.[3].value'
+ 131072
+
+However, this could not work with bits parameters::
+
+ $ varnishadm param.set -j feature +http2 | jq -r '.[3].value'
+ +http2,+validate_headers
+
+If the ``feature`` parameter is changed, reusing the output of ``param.set``
+cannot guarantee the restoration that exact value::
+
+ $ varnishadm param.set -j feature +http2,+validate_headers | jq -r '.[3].value'
+ +http2,+no_coredump,+validate_headers
+
+To fill this gap, bits parameters are now displayed as absolute values,
+relative to none of the bits being set. A list of bits can start with the
+special value ``none`` to clear all the bits, followed by specific bits to
+raise::
+
+ $ varnishadm param.set -j feature +http2 | jq -r '.[3].value'
+ none,+http2,+validate_headers
+ $ varnishadm param.set -j feature none,+http2,+validate_headers | jq -r '.[3].value'
+ none,+http2,+validate_headers
+
+The output of ``param.show`` and ``param.set`` is now idempotent for bits
+parameters, and can be used by a consistency check system to restore a
+parameter to its desired value.
+
+Almost all bits parameters are displayed as bits set relative to a ``none``
+value. The notable exception is ``vsl_mask`` that is expressed with bits
+cleared. For this purpose the ``vsl_mask`` parameter is now displayed as
+bits cleared relative to an ``all`` value::
+
+
+ $ varnishadm param.set -j vsl_mask all,-Debug | jq -r '.[3].value'
+ all,-Debug
+
+The special value ``default`` for bits parameters was deprecated in
+favor of the generic ``param.reset`` command. It might be removed in a
+future release.
+
Other changes in varnishd
~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -109,8 +137,6 @@ Changes to VCL
VCL variables
~~~~~~~~~~~~~
-**XXX new, deprecated or removed variables, or changed semantics**
-
A new ``bereq.task_deadline`` variable is available in ``vcl_pipe`` to
override the ``pipe_task_deadline`` parameter.
@@ -158,16 +184,9 @@ Other changes to VCL
The new ``+fold`` flag for ACLs merges adjacent subnets together and optimize
out subnets for which there exist another all-encompassing subnet.
-VMODs
-=====
-
-**XXX changes in the bundled VMODs**
-
varnishlog
==========
-**XXX changes concerning varnishlog(1) and/or vsl(7)**
-
When a ``BackendClose`` record includes a reason field, it now shows the
reason tag (for example ``RX_TIMEOUT``) instead of its description (Receive
timeout) to align with ``SessClose`` records. See :ref:`vsl(7)`.
@@ -192,16 +211,9 @@ without having to repeat it::
varnishncsa -F ``%{Varnish:default_format}x %{Varnish:handling}x``
-varnishadm
-==========
-
-**XXX changes concerning varnishadm(1) and/or varnish-cli(7)**
-
varnishstat
===========
-**XXX changes concerning varnishstat(1) and/or varnish-counters(7)**
-
A new counter ``MAIN.n_superseded`` adds visibility on how many objects are
inserted as the replacement of another object in the cache. This can give
insights regarding the nature of churn in a cache.
@@ -209,8 +221,6 @@ insights regarding the nature of churn in a cache.
varnishtest
===========
-**XXX changes concerning varnishtest(1) and/or vtc(7)**
-
When an HTTP/2 stream number does not matter and the stream is handled in a
single block, the automatic ``next`` identifier can be used::
@@ -231,9 +241,6 @@ include command itself. There are no guards against recursive includes.
Changes for developers and VMOD authors
=======================================
-**XXX changes concerning VRT, the public APIs, source code organization,
-builds etc.**
-
The ``VSB_tofile()`` function can work with VSBs larger than ``INT_MAX`` and
tolerate partial writes.
_______________________________________________
varnish-commit mailing list
varnish-commit@varnish-cache.org
https://www.varnish-cache.org/lists/mailman/listinfo/varnish-commit