New timeout nomenclature

[dridi]

This pull request is loosely based on work started a few years ago with @nigoroll. Loosely because it is not exactly where we left off our drafting effort last time we made progress together, and it adds things I had not previously discussed with him.

Thanks to the alias systems added to runtime parameters and VCL variables, renaming parameters does not break anything until we decide to remove the deprecated aliases.

Extract from the manual

Timeout Parameters
------------------

All timeout parameters follow a consistent naming scheme:

    <subject>_<event>_<type>

The subject may be one of the following:

- ``sess`` (client session)
- ``req`` (client request)
- ``resp`` (client response)
- ``pipe`` (client transaction turning into a pipe)
- ``bereq`` (backend request)
- ``beresp`` (backend response)
- ``backend`` (backend resource)
- ``cli`` (command line session)
- ``thread`` (worker thread)

Common events are:

- ``idle`` (waiting for data to be sent or received)
- ``send`` (complete delivery)
- ``start`` (first byte fetched)
- ``pool`` (time spent in a pool)

Finally, there are two types of timeouts:

- ``timeout`` (definitive failure condition)
- ``interrupt`` (triggered to verify another condition)

This does not really apply to "all" timeouts, only those with "timeout_" or "_timeout" in the name.

Parameter changes

• first_byte_timeout renamed to beresp_start_timeout
• between_bytes_timeout renamed to beresp_idle_timeout
• backend_idle_timeout renamed to backend_pool_timeout
• cli_timeout renamed to cli_resp_timeout
• connect_timeout renamed to bereq_connect_timeout
• idle_send_timeout renamed to resp_idle_interrupt
• pipe_timeout renamed to pipe_idle_timeout
• send_timeout renamed to resp_send_timeout
• timeout_idle renamed to sess_idle_timeout
• timeout_linger renamed to sess_linger_interrupt

VCL variables changes

• bereq.between_bytes_timeout renamed to beresp.idle_timeout
• bereq.first_byte_timeout renamed to beresp.start_timeout
• sess.idle_send_timeout renamed to resp.idle_interrupt
• sess.send_timeout renamed to resp.send_timeout
• sess.timeout_idle renamed to sess.idle_timeout
• sess.timeout_linger renamed to sess.linger_interrupt

Future timeout considerations

Thanks to this naming scheme we can more easily see what we may be missing. This pull request does not change anything except for parameter and VCL variable names, while offering compatibility aliases. There are known desirable timeouts that could be named like this following the proposed nomenclature:

• bereq_send_timeout (wanted by both UPLEX and Varnish Software)
• req_fetch_timeout (wanted by both UPLEX and Varnish Software)
• beresp_fetch_timeout (Varnish Software use case, would be the equivalent of last_byte_timeout from Varnish Enterprise)
• pipe_task_timeout (Varnish Software use case)
• req_task_timeout (UPLEX use case)
• bereq_task_timeout (UPLEX use case)

There are other aspects that our timeout draft covered, for example #3766, but I think we can start with this alone. The change is already large enough and promises interesting discussions since I don't expect consensus to arise immediately. Huge thanks to @nigoroll and sorry for not following up with you sooner.

[emacneille-at-varnish]

Note that some folks like to set timeouts on bereq in vcl_backend_fetch on a per-request basis, possibly allowing more time on specific objects that are known to require more computation in the backend. Some examples are here

If new timeouts are added and they aren't accessible via the bereq namespace, would you be able to set them instead in vcl_backend_response? Of course if you are already in vcl_backend_error, you have missed the opportunity to extend a timeout.

[dridi]

Taking the example you link to, we would from this:

import urlplus;

sub vcl_backend_fetch {
        if (urlplus.get_extension() == "zip") {
	        set bereq.last_byte_timeout = 4s;
        }
}

to this:

import urlplus;

sub vcl_backend_fetch {
        if (urlplus.get_extension() == "zip") {
	        set beresp.fetch_timeout = 4s;
        }
}

While you wouldn't have access to most of beresp, you could still set up beresp timeouts in vcl_backend_fetch if a) this pull request was merged and b) this specific timeout was not enterprise-only.

[emacneille-at-varnish]

Makes sense, thank you!

[dridi]

Rebased against current master to solve conflicts with #3812.

[nigoroll]

👍🏽 in general, but I would like to ask about some divergence from our previous collaboration:

* `between_bytes_timeout` renamed to `beresp_idle_timeout`

I think between bytes is a very good, descriptive name. Our last joint compromise seems to have been beresp_read_timeout, I would still suggest that or beresp_between_bytes_timeout

* `connect_timeout` renamed to `bereq_connect_timeout`

should be backend_connect_timeout, IMHO

* `idle_send_timeout` renamed to `resp_idle_interrupt`

We left the collaboration off with resp_write_timeout, which I still find clearer. Why the change? And, again "idle" is used in so many contexts that I really think we should avoid it except for "idle connections" (e.g. with HTTP/1.1 keepalive). That is sess_idle_timeout, which I like

* `pipe_timeout` renamed to `pipe_idle_timeout`

here I am happy with idle because a pipe not transferring data for some time is "idle"

[nigoroll]

see top-level comment