Document `IPROTO_WATCH_ONCE`

Product: Tarantool
Since: 3.0
Root document: https://www.tarantool.io/en/doc/latest/dev_guide/internals/iproto/requests/
SME: @ locker

Details

The new request type IPROTO_WATCH_ONCE has code 77 and can be used to
synchronously fetch the value currently associated with a specified
notification key. You can use it instead of IPROTO_WATCH if you just
need to get the current value without subscribing to future changes.

The new request is a standard synchronous request. Like any other
synchronous request (for example, IPROTO_SELECT), it takes a sync
number (IPROTO_SYNC) and optionally the desired schema version
(IPROTO_SCHEMA_VERSION) in the header. The same sync number and
the actual schema version are returned in the response header.

The request body is supposed to contain a single key IPROTO_EVENT_KEY
(which is also used by IPROTO_WATCH) with a string value that stores
the notification key of interest. The actual value is returned in the
response body, in the first entry of the IPROTO_DATA array. If there's
no value associated with a notification key (the key has never been
broadcast or was last set to nil), the IPROTO_DATA array will be
empty. (Note that IPROTO_DATA is also used by most other synchronous
requests. For example, IPROTO_SELECT returns the selected tuple array
in it.)

For example, suppose a key was broadcast with the following command on
the server:

box.broadcast('foo', {1, 2, 3})

Then IPROTO_WATCH_ONCE for IPROTO_EVENT_KEY equal to 'foo' will
return IPROTO_DATA' equal to [[1, 2, 3]]` (an array of one entry
containing the current value).

If the key didn't exist or was set to nil with

box.broadcast('foo', nil)

then IPROTO_WATCH_ONCE would return IPROTO_DATA equal to []
(an empty array).

The request shouldn't normally fail. It may fail only on some sort of
system error (out of memory; socket error), on schema version mismatch,
or on invalid input.

Like IPROTO_WATCH, the new request doesn't require authentication.

Like IPROTO_WATCH, the new request can't processed in a stream
(IPROTO_STREAM_ID must not be set in the request header).

If a server supports the IPROTO_WATCH_ONCE request, it'll set the
IPROTO_FEATURE_WATCH_ONCE = 6 bit in the protocol feature mask and
report the protocol version >= 6 in response to IPROTO_ID.
Requested by @locker in https://github.com/tarantool/tarantool/commit/6dc1433a58bbefad187f6d08531245e5a36415f1.

Start with the linked requests root document and review the existing IPROTO_WATCH documentation for structure and terminology. Add the IPROTO_WATCH_ONCE request details, request and response examples, feature-mask and protocol-version notes, authentication and stream restrictions, and failure conditions. Done means the root document fully explains the new request and its empty-value behavior.