Skip to content

Commit 93cd850

Browse files
xuniqxuniq
committed
Update iproto watchers
1 parent c88db01 commit 93cd850

File tree

1 file changed

+120
-40
lines changed

1 file changed

+120
-40
lines changed

‎doc/dev_guide/internals/box_protocol.rst

Lines changed: 120 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,10 @@ The IPROTO constants that identify requests that we will mention in this section
8181
IPROTO_FETCH_SNAPSHOT=0x45
8282
IPROTO_REGISTER=0x46
8383
IPROTO_ID=0x49
84+
IPROTO_WATCH=0x4a
85+
IPROTO_UNWATCH=0x4b
86+
IPROTO_EVENT=0x4c
87+
8488
8589
The IPROTO constants that appear within requests or responses that we will describe in this section are:
8690

@@ -146,7 +150,9 @@ The IPROTO constants that appear within requests or responses that we will descr
146150
IPROTO_VERSION=0x54
147151
IPROTO_FEATURES=0x55
148152
IPROTO_TIMEOUT=0x56
149-
IPROTO_TXN_ISOLATION = 0x59
153+
IPROTO_EVENT_KEY=0x57
154+
IPROTO_EVENT_DATA=0x58
155+
IPROTO_TXN_ISOLATION=0x59
150156
151157
152158
To denote message descriptions we will say ``msgpack(...)`` and within it we will use modified
@@ -935,13 +941,122 @@ Available IPROTO_FEATURES are the following:
935941
MsgPack extension support. Clients that don't support this feature will receive
936942
error responses for :ref:`IPROTO_EVAL <box_protocol-eval>` and
937943
:ref:`IPROTO_CALL <box_protocol-call>` encoded to string error messages.
938-
- ``IPROTO_FEATURE_WATCHERS = 3`` -- remote watchers support: IPROTO_WATCH,
939-
IPROTO_UNWATCH, and IPROTO_EVENT commands.
940-
941-
.. // TODO: document remote watchers commands
944+
- ``IPROTO_FEATURE_WATCHERS = 3`` -- remote watchers support: :ref:`IPROTO_WATCH <box_protocol-watch>`,
945+
:ref:`IPROTO_UNWATCH <box_protocol-unwatch>`, and :ref:`IPROTO_EVENT <box_protocol-event>` commands.
942946

943947
IPROTO_ID requests can be processed without authentication.
944948

949+
.. _box-protocol-watchers:
950+
951+
Watchers
952+
--------
953+
954+
The commands below support asynchronous server-client notifications signaled
955+
with :ref:`box.broadcast() <box-broadcast>`.
956+
Servers that support the new feature set the ``IPROTO_FEATURE_WATCHERS`` feature in reply to the ``IPROTO_ID`` command.
957+
When a connection is closed, all watchers registered for it are unregistered.
958+
959+
The remote :ref:`watcher <box-watchers>` protocol works in the following way:
960+
961+
#. The client sends an ``IPROTO_WATCH`` packet to subscribe to the updates of a specified key defined on the server.
962+
963+
#. The server sends an ``IPROTO_EVENT`` packet to the subscribed client with the key name and
964+
its current value unconditionally after registration.
965+
After that, the packet is sent every time the key value is updated provided the last notification
966+
was acknowledged (see below).
967+
968+
#. After receiving a notification, the client sends an ``IPROTO_WATCH`` packet to acknowledge the notification.
969+
970+
#. If the client doesn't want to receive any more notifications, it unsubscribes by sending
971+
an ``IPROTO_UNWATCH`` packet.
972+
973+
All the three request types are fully asynchronous -- a receiving end doesn't send a packet in reply to any of them.
974+
Therefore, neither of them has a sync number.
975+
976+
.. _box_protocol-watch:
977+
978+
IPROTO_WATCH = 0x4a
979+
~~~~~~~~~~~~~~~~~~~
980+
981+
Registers a new watcher for the given notification key or confirms a notification if a watcher is
982+
already subscribed.
983+
The watcher is notified unconditionally after registration.
984+
After that, the notification is sent every time the key is updated with
985+
``box.broadcast()`` provided the last notification was acknowledged.
986+
The server doesn't reply to the request unless it fails to parse the packet.
987+
988+
The body is a 2-item map:
989+
990+
.. cssclass:: highlight
991+
.. parsed-literal::
992+
993+
# <size>
994+
msgpack(:samp:`{{MP_UINT unsigned integer = size(<header>) + size(<body>)}}`)
995+
# <header>
996+
msgpack({
997+
IPROTO_REQUEST_TYPE: IPROTO_WATCH
998+
})
999+
# <body>
1000+
msgpack({
1001+
IPROTO_EVENT_KEY: :samp:`{{MP_STR string}}}`
1002+
})
1003+
1004+
``IPROTO_EVENT_KEY`` (code 0x56) contains a key name.
1005+
1006+
.. _box_protocol-unwatch:
1007+
1008+
IPROTO_UNWATCH = 0x4b
1009+
~~~~~~~~~~~~~~~~~~~~~
1010+
1011+
Unregisters a watcher subscribed to the given notification key.
1012+
A server doesn't reply to the request unless it fails to parse the packet.
1013+
1014+
The body is a 2-item map:
1015+
1016+
.. cssclass:: highlight
1017+
.. parsed-literal::
1018+
1019+
# <size>
1020+
msgpack(:samp:`{{MP_UINT unsigned integer = size(<header>) + size(<body>)}}`)
1021+
# <header>
1022+
msgpack({
1023+
IPROTO_REQUEST_TYPE: IPROTO_UNWATCH
1024+
})
1025+
# <body>
1026+
msgpack({
1027+
IPROTO_EVENT_KEY: :samp:`{{MP_STR string}}}`
1028+
})
1029+
1030+
``IPROTO_EVENT_KEY`` (code 0x56) contains a key name.
1031+
1032+
.. _box_protocol-event:
1033+
1034+
IPROTO_EVENT = 0x4c
1035+
~~~~~~~~~~~~~~~~~~~~
1036+
1037+
Sent by the server to notify a client about a key update.
1038+
1039+
The body is a 2-item map:
1040+
1041+
.. cssclass:: highlight
1042+
.. parsed-literal::
1043+
1044+
# <size>
1045+
msgpack(:samp:`{{MP_UINT unsigned integer = size(<header>) + size(<body>)}}`)
1046+
# <header>
1047+
msgpack({
1048+
IPROTO_REQUEST_TYPE: IPROTO_EVENT
1049+
})
1050+
# <body>
1051+
msgpack({
1052+
IPROTO_EVENT_KEY: :samp:`{{MP_STR string}}}`,
1053+
IPROTO_EVENT_DATA: :samp:`{{MP_NIL nil}}}`
1054+
})
1055+
1056+
``IPROTO_EVENT_KEY`` (code 0x56) contains a key name.
1057+
1058+
``IPROTO_EVENT_DATA`` (code 0x57) contains data sent to a remote watcher.
1059+
The parameter is optional, the default value is ```nil``.
9451060

9461061
.. _box_protocol-responses:
9471062

@@ -1610,41 +1725,6 @@ In other words, there should be a full-mesh connection between the nodes.
16101725
16111726
})
16121727
1613-
.. _box-protocol-watchers:
1614-
1615-
Watchers
1616-
--------
1617-
1618-
The commands below support asynchronous server-client
1619-
notifications signaled with ``box.broadcast()``.
1620-
Servers that support the new feature set the ``IPROTO_FEATURE_WATCHERS``
1621-
feature bit (bit 3) in reply to the ``IPROTO_ID`` command.
1622-
When a connection is closed, all watchers registered for it are unregistered.
1623-
1624-
IPROTO_WATCH (code 74)
1625-
~~~~~~~~~~~~~~~~~~~~~~
1626-
1627-
Registers a new watcher for the given notification key or acknowledges a notification if a watcher is
1628-
already subscribed.
1629-
The key name is passed in ``IPROTO_EVENT_KEY`` (code 0x56).
1630-
The watcher will be notified unconditionally after registration and then every time the key is updated with
1631-
``box.broadcast()`` provided the last notification was acknowledged.
1632-
The server doesn't reply to the request unless it fails to parse the packet.
1633-
1634-
IPROTO_UNWATCH (code 75)
1635-
~~~~~~~~~~~~~~~~~~~~~~~~
1636-
1637-
Unregisters a watcher subscribed for the given notification key.
1638-
The key name is passed in ``IPROTO_EVENT_KEY`` (code 0x56).
1639-
A server doesn't reply to the request unless it fails to parse the packet.
1640-
1641-
IPROTO_EVENT (code 76)
1642-
~~~~~~~~~~~~~~~~~~~~~~
1643-
1644-
Sent by the server to notify a client about a key update.
1645-
The key name is passed in ``IPROTO_EVENT_KEY`` (code 0x56).
1646-
The key data (optional) is passed in ``IPROTO_EVENT_DATA`` (code 0x57).
1647-
16481728
.. _box_protocol-illustration:
16491729

16501730
Examples

0 commit comments

Comments
 (0)