From a86df41f36c9808967384258362718bd6e7e2e3f Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Fri, 27 May 2022 18:04:02 +0700 Subject: [PATCH 1/8] Add IPROTO_ID request --- doc/dev_guide/internals/box_protocol.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/dev_guide/internals/box_protocol.rst b/doc/dev_guide/internals/box_protocol.rst index 37ef583e6a..9647980c15 100644 --- a/doc/dev_guide/internals/box_protocol.rst +++ b/doc/dev_guide/internals/box_protocol.rst @@ -80,6 +80,7 @@ The IPROTO constants that identify requests that we will mention in this section IPROTO_VOTE=0x44 IPROTO_FETCH_SNAPSHOT=0x45 IPROTO_REGISTER=0x46 + IPROTO_ID=0x49 The IPROTO constants that appear within requests or responses that we will describe in this section are: @@ -140,6 +141,8 @@ The IPROTO constants that appear within requests or responses that we will descr IPROTO_RAFT_VOTE=0x01 IPROTO_RAFT_STATE=0x02 IPROTO_RAFT_VCLOCK=0x03 + IPROTO_VERSION=0x54 + IPROTO_FEATURES=0x55 To denote message descriptions we will say ``msgpack(...)`` and within it we will use modified From ce99633df80a731761d74d72179dabfc8c9cc081 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Mon, 30 May 2022 15:24:58 +0700 Subject: [PATCH 2/8] Add IPROTO_ID details --- doc/dev_guide/internals/box_protocol.rst | 54 +++++++++++++++++++++--- 1 file changed, 48 insertions(+), 6 deletions(-) diff --git a/doc/dev_guide/internals/box_protocol.rst b/doc/dev_guide/internals/box_protocol.rst index 9647980c15..b03d4f220a 100644 --- a/doc/dev_guide/internals/box_protocol.rst +++ b/doc/dev_guide/internals/box_protocol.rst @@ -803,6 +803,40 @@ The body is a 2-item map: IPROTO_LSN: :samp:`{{MP_INT integer}}` }) +.. _box_protocol-id: + +IPROTO_ID = 0x49 +~~~~~~~~~~~~~~~~~~~~~~ + +Clients send this message to inform the server about the protocol version and +features they support. Based on this information, the server can limit its +functionality when interacting with these clients. + +The body is a 2-item map: + +.. cssclass:: highlight +.. parsed-literal:: + + # + msgpack(:samp:`{{MP_UINT unsigned integer = size(
) + size()}}`) + #
+ msgpack({ + IPROTO_REQUEST_TYPE: IPROTO_ID, + IPROTO_SYNC: :samp:`{{MP_UINT unsigned integer}}` + }) + # + msgpack({ + IPROTO_VERSION: :samp:`{{MP_UINT unsigned integer}}}`, + IPROTO_FEATURES: :samp:`{{MP_ARRAY array of unsigned integers}}}` + }) + +Currently supported IPROTO_VERSION is 1. + +The IPROTO_FEATURES array can contain constants defined in the +`iproto_features.h file `_. + +This request can be processed without authentication. + .. _box_protocol-responses: @@ -835,12 +869,20 @@ For IPROTO_OK, the header Response-Code-Indicator will be 0 and the body is a 1- IPROTO_DATA: :samp:`{{any type}}` }) -For :ref:`IPROTO_PING ` the body will be an empty map. -For most data-access requests (IPROTO_SELECT IPROTO_INSERT IPROTO_DELETE etc.) -the body is an IPROTO_DATA map with an array of tuples that contain an array of fields. -For :ref:`IPROTO_EVAL ` and :ref:`IPROTO_CALL ` -it will usually be an array but, since Lua requests can result in a wide variety -of structures, bodies can have a wide variety of structures. +- For :ref:`IPROTO_PING ` the body will be an empty map. + +- For most data-access requests (:ref:`IPROTO_SELECT `, + :ref:`IPROTO_INSERT `, :ref:`IPROTO_DELETE ` + , etc.) the body is an IPROTO_DATA map with an array of tuples that contain + an array of fields. + +- For :ref:`IPROTO_EVAL ` and :ref:`IPROTO_CALL ` + it will usually be an array but, since Lua requests can result in a wide variety + of structures, bodies can have a wide variety of structures. + +- For :ref:`IPROTO_ID `, the body has the same structure as + the request. It informs the client about the protocol version and features + that the server supports. Example: if this is the fifth message and the request is :codenormal:`box.space.`:codeitalic:`space-name`:codenormal:`:insert{6}`, From 6b1037eb8aa5bcb60c9abd0ec29555af3b16a229 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Mon, 30 May 2022 15:26:17 +0700 Subject: [PATCH 3/8] Improve wording --- doc/dev_guide/internals/box_protocol.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/dev_guide/internals/box_protocol.rst b/doc/dev_guide/internals/box_protocol.rst index b03d4f220a..65e56f6546 100644 --- a/doc/dev_guide/internals/box_protocol.rst +++ b/doc/dev_guide/internals/box_protocol.rst @@ -880,8 +880,8 @@ For IPROTO_OK, the header Response-Code-Indicator will be 0 and the body is a 1- it will usually be an array but, since Lua requests can result in a wide variety of structures, bodies can have a wide variety of structures. -- For :ref:`IPROTO_ID `, the body has the same structure as - the request. It informs the client about the protocol version and features +- For :ref:`IPROTO_ID `, the response body has the same structure as + the request body. It informs the client about the protocol version and features that the server supports. Example: if this is the fifth message and the request is From 6bef360ca5d1599d74e97bd74137154565ed4cd2 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Mon, 30 May 2022 16:27:24 +0700 Subject: [PATCH 4/8] Update protocol version and features --- doc/dev_guide/internals/box_protocol.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/dev_guide/internals/box_protocol.rst b/doc/dev_guide/internals/box_protocol.rst index 65e56f6546..fc6b4f48d1 100644 --- a/doc/dev_guide/internals/box_protocol.rst +++ b/doc/dev_guide/internals/box_protocol.rst @@ -830,9 +830,7 @@ The body is a 2-item map: IPROTO_FEATURES: :samp:`{{MP_ARRAY array of unsigned integers}}}` }) -Currently supported IPROTO_VERSION is 1. - -The IPROTO_FEATURES array can contain constants defined in the +The latest IPROTO_VERSION and the constants that define IPROTO_FEATURES are listed in the `iproto_features.h file `_. This request can be processed without authentication. From 576318581fed2f5971061c8fed8191c977985ba6 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Mon, 30 May 2022 17:40:05 +0700 Subject: [PATCH 5/8] Add substitution for IPROTO_VERSION --- doc/dev_guide/internals/box_protocol.rst | 5 ++++- prolog.rst | 2 ++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/doc/dev_guide/internals/box_protocol.rst b/doc/dev_guide/internals/box_protocol.rst index fc6b4f48d1..a91f2bbeaf 100644 --- a/doc/dev_guide/internals/box_protocol.rst +++ b/doc/dev_guide/internals/box_protocol.rst @@ -830,7 +830,10 @@ The body is a 2-item map: IPROTO_FEATURES: :samp:`{{MP_ARRAY array of unsigned integers}}}` }) -The latest IPROTO_VERSION and the constants that define IPROTO_FEATURES are listed in the +IPROTO_VERSION is the integer number that increases by one with each change in +the IPROTO_FEATURES set. The latest version is |iproto_version|. + +Supported IPROTO_FEATURES are listed in the `iproto_features.h file `_. This request can be processed without authentication. diff --git a/prolog.rst b/prolog.rst index 4fa0432980..967293b9af 100644 --- a/prolog.rst +++ b/prolog.rst @@ -34,3 +34,5 @@
+.. |iproto_version| replace:: 3 + From 8d4758ef18fac8a1f95b4cb026e557e607ce61f6 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Mon, 30 May 2022 18:25:51 +0700 Subject: [PATCH 6/8] Add IPROTO_FEATURES --- doc/dev_guide/internals/box_protocol.rst | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/doc/dev_guide/internals/box_protocol.rst b/doc/dev_guide/internals/box_protocol.rst index a91f2bbeaf..4b1115c596 100644 --- a/doc/dev_guide/internals/box_protocol.rst +++ b/doc/dev_guide/internals/box_protocol.rst @@ -833,10 +833,19 @@ The body is a 2-item map: IPROTO_VERSION is the integer number that increases by one with each change in the IPROTO_FEATURES set. The latest version is |iproto_version|. -Supported IPROTO_FEATURES are listed in the -`iproto_features.h file `_. - -This request can be processed without authentication. +Available IPROTO_FEATURES are the following: + +- ``IPROTO_FEATURE_STREAMS = 0`` -- streams support: :ref:`IPROTO_STREAM_ID ` + in the request header +- ``IPROTO_FEATURE_TRANSACTIONS = 1`` -- transaction support: IPROTO_BEGIN, IPROTO_COMMIT, + and IPROTO_ROLLBACK commands +- ``IPROTO_FEATURE_ERROR_EXTENSION = 2`` -- :ref:`MP_ERROR ` + MsgPack extension support +- ``IPROTO_FEATURE_WATCHERS = 3`` -- remote watchers support: IPROTO_WATCH, IPROTO_UNWATCH, + and IPROTO_EVENT commands +.. // TODO: document remote watchers commands + +IPROTO_ID requests can be processed without authentication. .. _box_protocol-responses: From 944aadbc7ff48232b474745319c7ed913b09cacc Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Mon, 30 May 2022 18:49:00 +0700 Subject: [PATCH 7/8] Improve wording --- doc/dev_guide/internals/box_protocol.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/dev_guide/internals/box_protocol.rst b/doc/dev_guide/internals/box_protocol.rst index 4b1115c596..064efb957c 100644 --- a/doc/dev_guide/internals/box_protocol.rst +++ b/doc/dev_guide/internals/box_protocol.rst @@ -809,8 +809,8 @@ IPROTO_ID = 0x49 ~~~~~~~~~~~~~~~~~~~~~~ Clients send this message to inform the server about the protocol version and -features they support. Based on this information, the server can limit its -functionality when interacting with these clients. +features they support. Based on this information, the server can enable or +disable certain features in interacting with these clients. The body is a 2-item map: @@ -830,8 +830,8 @@ The body is a 2-item map: IPROTO_FEATURES: :samp:`{{MP_ARRAY array of unsigned integers}}}` }) -IPROTO_VERSION is the integer number that increases by one with each change in -the IPROTO_FEATURES set. The latest version is |iproto_version|. +IPROTO_VERSION is an integer number reflecting the version of protocol that the +client supports. The latest IPROTO_VERSION is |iproto_version|. Available IPROTO_FEATURES are the following: From a8d78418f5b3f2f004d5f922e0bfde23d7002258 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Tue, 31 May 2022 13:27:14 +0700 Subject: [PATCH 8/8] Add feature details --- doc/dev_guide/internals/box_protocol.rst | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/doc/dev_guide/internals/box_protocol.rst b/doc/dev_guide/internals/box_protocol.rst index 064efb957c..db26a72d3b 100644 --- a/doc/dev_guide/internals/box_protocol.rst +++ b/doc/dev_guide/internals/box_protocol.rst @@ -836,13 +836,16 @@ client supports. The latest IPROTO_VERSION is |iproto_version|. Available IPROTO_FEATURES are the following: - ``IPROTO_FEATURE_STREAMS = 0`` -- streams support: :ref:`IPROTO_STREAM_ID ` - in the request header -- ``IPROTO_FEATURE_TRANSACTIONS = 1`` -- transaction support: IPROTO_BEGIN, IPROTO_COMMIT, - and IPROTO_ROLLBACK commands + in the request header. +- ``IPROTO_FEATURE_TRANSACTIONS = 1`` -- transaction support: IPROTO_BEGIN, + IPROTO_COMMIT, and IPROTO_ROLLBACK commands (with :ref:`IPROTO_STREAM_ID ` + in the request header). Learn more about :ref:`sending transaction commands `. - ``IPROTO_FEATURE_ERROR_EXTENSION = 2`` -- :ref:`MP_ERROR ` - MsgPack extension support -- ``IPROTO_FEATURE_WATCHERS = 3`` -- remote watchers support: IPROTO_WATCH, IPROTO_UNWATCH, - and IPROTO_EVENT commands + MsgPack extension support. Clients that don't support this feature will receive + error responses for :ref:`IPROTO_EVAL ` and + :ref:`IPROTO_CALL ` encoded to string error messages. +- ``IPROTO_FEATURE_WATCHERS = 3`` -- remote watchers support: IPROTO_WATCH, + IPROTO_UNWATCH, and IPROTO_EVENT commands. .. // TODO: document remote watchers commands IPROTO_ID requests can be processed without authentication. @@ -1226,9 +1229,8 @@ function ``netbox_encode_auth``. .. _box_protocol-streams: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Binary protocol -- streams -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------- The :ref:`Streams and interactive transactions ` feature, which was added in Tarantool version @@ -1276,6 +1278,8 @@ that the header will contain an additional item: IPROTO_STREAM_ID=0x0a with MP_UINT=0x01. It happens to equal 1 for this example because each call to conn:new_stream() assigns a new number, starting with 1. +.. _box_protocol-stream_transactions: + The client makes stream transactions by sending, in order: IPROTO_BEGIN, the transaction data-change and query requests, IPROTO_COMMIT or IPROTO_ROLLBACK.