Update after the review

Author: xuniq

doc/dev_guide/internals/box_protocol.rst

@@ -20,6 +20,13 @@ The binary protocol provides complete access to Tarantool functionality, includi
     asynchronously via the same connection
 *   response format that supports zero-copy writes
 
+..  note::
+
+    Since version :doc:`2.11.0 </release/2.11.0>`, you can use the :ref:`box.iproto <box_iproto>` submodule to access
+    IPROTO constants and features from Lua. The submodule enables to :ref:`send arbitrary IPROTO packets <reference_lua-box_iproto_send>`
+    over the session's socket and :ref:`override the behavior <reference_lua-box_iproto_override>` for all IPROTO
+    request types (including the :ref:`unknown <box_iproto-unknown>` types).
+
 ..  toctree::
     :maxdepth: 1
 

doc/dev_guide/internals/iproto/keys.rst

@@ -52,10 +52,6 @@ General
             -   0x00 |br| MP_UINT
             -   Request type or response type
 
-        *   -   :ref:`IPROTO_UNKNOWN <internals-iproto-keys-unknown>`
-            -   -1 |br| MP_UINT
-            -   Unknown request type. The key is used only for IPROTO handler overriding.
-
         *   -   :ref:`IPROTO_ERROR <internals-iproto-keys-error>`
             -   0x52 |br| :ref:`MP_ERROR <msgpack_ext-error>`
             -   Error response
@@ -598,16 +594,6 @@ See requests and responses for :ref:`client-server communication <internals-requ
 :ref:`events and subscriptions <box-protocol-watchers>`,
 :ref:`streams and interactive transactions <internals-iproto-streams>`.
 
-..  _internals-iproto-keys-unknown:
-
-IPROTO_UNKNOWN
-~~~~~~~~~~~~~~
-
-Code: -1.
-
-Unknown request type. The constant is used for overriding the unknown request handler.
-Learn more: :ref:`box.iproto.override() <reference_lua-box_iproto_override>`.
-
 ..  _internals-iproto-keys-error:
 
 IPROTO_ERROR

doc/dev_guide/internals/iproto/requests.rst

@@ -38,6 +38,10 @@ Overview
             -   0x8XXX |br| MP_INT
             -   Error response
 
+        *   -   :ref:`IPROTO_UNKNOWN <internals-iproto-keys-unknown>`
+            -   -1 |br| MP_UINT
+            -   Unknown request type. The constant is used only for IPROTO handler :ref:`overriding <reference_lua-box_iproto_override>`.
+
         *   -   :ref:`IPROTO_SELECT <box_protocol-select>`
             -   0x01
             -   :ref:`Select <box_space-select>` request
@@ -126,6 +130,18 @@ constants for return codes.
 To learn more about error responses,
 check the section :ref:`Request and response format <box_protocol-responses_error>`.
 
+..  _internals-iproto-unknown:
+
+IPROTO_UNKNOWN
+~~~~~~~~~~~~~~
+
+Since :doc:`2.11.0 </release/2.11.0>`.
+
+Code: -1.
+
+Unknown request type. The constant is used for overriding an unknown IPROTO request handler.
+Learn more: :ref:`box.iproto.override() <reference_lua-box_iproto_override>` and :ref:`box_box_iproto_override <box_iproto_override>`.
+
 ..  _box_protocol-select:
 
 IPROTO_SELECT

doc/dev_guide/reference_capi/box.rst

@@ -247,7 +247,7 @@
 
 ..  _box_box_iproto_send:
 
-..  c:function:: int box_iproto_send(uint64_t sid, char *header, char *header_end, char *body, char *body_end)
+..  c:function:: int box_iproto_send(uint64_t sid, char *header, char *header_end[, char *body, char *body_end])
 
     Since version :doc:`2.11.0 </release/2.11.0>`.
     Send an :ref:`IPROTO <internals-iproto-format>` packet over the session's socket with the given MsgPack header
@@ -258,7 +258,8 @@
     :param uint32_t     sid: IPROTO session identifier (see :ref:`box_session_id() <box_box_session_id>`)
     :param char*     header: a MsgPack-encoded header
     :param char*     header_end: end of a header encoded as MsgPack
-    :param char*     body: a MsgPack-encoded body
+    :param char*     body: a MsgPack-encoded body. If the ``body`` and ``body_end`` parameters are omitted, the packet
+                           consists of the header only.
     :param char*     body_end: end of a body encoded as MsgPack
 
     :return: 0 on success
@@ -276,24 +277,62 @@
 
     For details, see `src/box/errcode.h <https://github.com/tarantool/tarantool/blob/master/src/box/errcode.h>`__.
 
+    **Example**
+
+    ..  code-block:: c
+
+        /* IPROTO constants are not exported to C.
+        * That is, the user encodes them by himself.
+        */
+        #define IPROTO_REQUEST_TYPE 0x00
+        #define IPROTO_OK 0x00
+        #define IPROTO_SYNC 0x01
+        #define IPROTO_SCHEMA_VERSION 0x05
+        #define IPROTO_DATA 0x30
+
+        char buf[256] = {};
+        char *header = buf;
+        char *header_end = header;
+        header_end = mp_encode_map(header_end, 3);
+        header_end = mp_encode_uint(header_end, IPROTO_REQUEST_TYPE);
+        header_end = mp_encode_uint(header_end, IPROTO_OK);
+        header_end = mp_encode_uint(header_end, IPROTO_SYNC);
+        header_end = mp_encode_uint(header_end, 10);
+        header_end = mp_encode_uint(header_end, IPROTO_SCHEMA_VERSION);
+        header_end = mp_encode_uint(header_end, box_schema_version());
+
+        char *body = header_end;
+        char *body_end = body;
+        body_end = mp_encode_map(body_end, 1);
+        body_end = mp_encode_uint(body_end, IPROTO_DATA);
+        body_end = mp_encode_uint(body_end, 1);
+
+        /* The packet contains both the header and body. */
+        box_iproto_send(box_session_id(), header, header_end, body, body_end);
+
+        /* The packet contains the header only. */
+        box_iproto_send(box_session_id(), header, header_end, NULL, NULL);
+
 ..  _box_box_iproto_override:
 
 ..  c:function:: void box_iproto_override(uint32_t request_type, iproto_handler_t handler, iproto_handler_destroy_t destroy, void *ctx)
 
     Since version :doc:`2.11.0 </release/2.11.0>`.
-    Sets an IPROTO request handler with the provided context for the given request type.
+    Set a new IPROTO request handler with the provided context for the given request type.
     The function yields.
 
-Possible values:
+    :param uint32_t request_type: IPROTO request type code (for example, ``IPROTO_SELECT``).
+                                  For details, check :ref:`Client-server requests and responses <internals-requests_responses>`.
+
+                                  To override the handler of an unknown request type, use the :ref:`IPROTO_UNKNOWN <internals-iproto-keys-unknown>` type code.
 
-                                *   a type code from the :ref:`box.iproto.type <reference_lua-box_iproto_type>` (except
-                                    ``box.iproto.type.UNKNOWN``) -- override the existing request type.
+    :param iproto_handler_t handler: IPROTO request handler. To reset the request handler, set the ``handler`` parameter to ``NULL``.
+                                     See the full parameter description in the :ref:`Handler function <box_box_iproto_override-handler>` section.
 
-                                *   ``box.iproto.type.UNKNOWN`` -- override an unknown request type.
+    :param iproto_handler_destroy_t destroy: IPROTO request handler destructor. The destructor is called when the
+                                             corresponding handler is removed. See the full parameter description
+                                             in the :ref:`Handler destructor function <box_box_iproto_override-destroy>` section.
 
-    :param uint32_t request_type: request type code from the ``iproto_type`` enumeration
-    :param iproto_handler_t handler: IPROTO request handler
-    :param iproto_handler_destroy_t destroy: IPROTO request handler destructor
     :param void* ctx: a context passed to the ``handler`` and ``destroy`` callbacks
 
     :return: 0 on success
@@ -304,7 +343,64 @@ Possible values:
 
     **Possible errors:**
 
+    If the Lua handler throws an exception, the behavior is similar to a remote procedure call.
+    The following errors are returned to the client over IPROTO (see `src/lua/utils.h <https://github.com/tarantool/tarantool/blob/dec0e0221e183fa972efa65bb0fb658112f2196f/src/lua/utils.h#L366-L371>`__):
+
     *   :errcode:`ER_PROC_LUA` -- the exception is thrown, diagnostic is not set.
     *   diagnostics from ``src/box/errcode.h`` -- the exception is thrown, diagnostic is set.
 
-    For details, see `src/box/errcode.h <https://github.com/tarantool/tarantool/blob/master/src/box/errcode.h>`__.
+    For details, see `src/box/errcode.h <https://github.com/tarantool/tarantool/blob/master/src/box/errcode.h>`__.
+
+..  _box_box_iproto_override-handler:
+
+    **Handler function**
+
+    The signature of a handler function (the ``handler`` parameter):
+
+    ..  code-block:: c
+
+        enum iproto_handler_status {
+                IPROTO_HANDLER_OK,
+                IPROTO_HANDLER_ERROR,
+                IPROTO_HANDLER_FALLBACK,
+        }
+
+        typedef enum iproto_handler_status
+        (*iproto_handler_t)(const char *header, const char *header_end,
+                            const char *body, const char *body_end, void *ctx);
+
+    where:
+
+    *   ``header``(const char*) -- a MsgPack-encoded header
+    *   ``header_end``(const char*) -- end of a header encoded as MsgPack
+    *   ``body``(const char*) -- a MsgPack-encoded body
+    *   ``header_end``(const char*) -- end of a body encoded as MsgPack
+
+    The handler returns a status code. Possible statuses:
+
+    *  ``IPROTO_REQUEST_HANDLER_OK`` -- success
+    *  ``IPROTO_REQUEST_HANDLER_ERROR`` -- error, diagnostic must be set by handler
+    *  ``IPROTO_REQUEST_HANDLER_FALLBACK`` -- fallback to the system handler
+
+..  _box_box_iproto_override-destroy:
+
+    **Handler destructor function**
+
+    The signature of a destructor function (the ``destroy`` parameter):
+
+    ..  code-block:: c
+
+        typedef void (*iproto_handler_destroy_t)(void *ctx);
+
+    where:
+
+    *   ``ctx`` (void*): the context provided by ``box_iproto_override()`` function.
+
+    **Examples**
+
+    ..  code-block:: c
+
+        box_iproto_override(1000, iproto_request_handler_с, NULL)
+        box_iproto_override(IPROTO_SELECT, iproto_request_handler_с, (uintptr_t)23)
+        box_iproto_override(IPROTO_SELECT, NULL, NULL)
+        box_iproto_override(IPROTO_UNKNOWN, iproto_unknown_request_handler_с, &ctx)

doc/reference/reference_lua/box_iproto.rst

@@ -6,12 +6,12 @@ Submodule box.iproto
 Since :doc:`2.11.0 </release/2.11.0>`.
 
 The ``box.iproto`` submodule provides the ability to work with the network subsystem of Tarantool.
-It enables to extend the :ref:`binary protocol <box_protocol>` functionality from the Lua libraries.
+It enables to extend :ref:`IPROTO <box_protocol>` functionality from the Lua libraries.
 With this submodule, you can:
 
 *   :ref:`parse the unknown IPROTO requests types <reference_lua-box_iproto_override>`
 *   :ref:`send arbitrary IPROTO packets <reference_lua-box_iproto_send>`
-*   :ref:`override the behavior <reference_lua-box_iproto_override>` of the existing request types in binary protocol
+*   :ref:`override the behavior <reference_lua-box_iproto_override>` of the existing request types in the binary protocol
 
 The submodule exports all IPROTO :ref:`constants <internals-box_protocol>` and :ref:`features <internals-iproto-keys-features>` to Lua.
 
@@ -20,7 +20,7 @@ The submodule exports all IPROTO :ref:`constants <internals-box_protocol>` and :
 IPROTO constants
 ----------------
 
-The IPROTO constants in the ``box.iproto`` namespace are written in the upper case without the ``IPROTO_`` prefix.
+IPROTO constants in the ``box.iproto`` namespace are written in uppercase letters without the ``IPROTO_`` prefix.
 The constants are divided into several groups:
 
 *   :ref:`key <reference_lua-box_iproto_key>` (:ref:`IPROTO_SYNC <internals-iproto-keys-sync>`, :ref:`IPROTO_REQUEST_TYPE <internals-iproto-keys-request_type>`)
@@ -30,7 +30,7 @@ The constants are divided into several groups:
 *   :ref:`metadata key <reference_lua-box_iproto_metadata>` (:ref:`IPROTO_FIELD_IS_NULLABLE <internals-iproto-keys-sql-specific>`)
 *   :ref:`RAFT key <reference_lua-box_iproto_raft>` (:ref:`IPROTO_TERM <internals-iproto-keys-term>`)
 
-Each group is located in the corresponding subnamespace without prefix.
+Each group is located in the corresponding subnamespace without the prefix.
 For example:
 
 ..  code-block:: lua
@@ -39,9 +39,9 @@ For example:
     -- ...
     box.iproto.type.SELECT = 1
     -- ...
-    box.iproto.flag.COMMIT = 0x01
+    box.iproto.flag.COMMIT = 1
     -- ...
-    box.iproto.ballot_key.VCLOCK = 0x02
+    box.iproto.ballot_key.VCLOCK = 2
     -- ...
     box.iproto.metadata_key.IS_NULLABLE = 3
     -- ...
@@ -61,7 +61,7 @@ The submodule exports:
 
 **Example**
 
-The example converts the feature names from the ``box.iproto.protocol_features`` set into the code numbers:
+The example converts the feature names from the ``box.iproto.protocol_features`` set into codes:
 
 ..  code-block:: lua
 
@@ -71,15 +71,26 @@ The example converts the feature names from the ``box.iproto.protocol_features``
     transactions = true,
     error_extension = true,
     watchers = true,
+    pagination = true,
     }
 
     -- Convert the feature names into codes
     features = {}
     for name in pairs(box.iproto.protocol_features) do
         table.insert(features, box.iproto.feature[name])
     end
-    features -- [0, 1, 2, 3]
+    features -- [0, 1, 2, 3, 4]
 
+..  _box_iproto-unknown:
+
+Handling the unknown IPROTO request types
+-----------------------------------------
+
+Every IPROTO request has a static handler.
+That is, before version :doc:`2.11.0 </release/2.11.0>`, any unknown request raised an error.
+Since :doc:`2.11.0 </release/2.11.0>`, a new request type is introduced -- :ref:`IPROTO_UNKNOWN <internals-iproto-keys-unknown>`.
+This type is used to override the handlers of the unknown IPROTO requests types. For details, see
+:ref:`box.iproto.override() <reference_lua-box_iproto_override>` and :ref:`box_iproto_override <box_box_iproto_override>` functions.
 
 ..  _box_iproto-reference:
 
@@ -94,19 +105,19 @@ The table lists all available functions and data of the submodule:
     ..  rst-class:: left-align-column-2
 
     ..  list-table::
-        :widths: 25 75
+        :widths: 30 70
         :header-rows: 1
 
         *   - Name
             - Use
 
-        *   - :doc:`./box_iproto/keys`
+        *   - :doc:`./box_iproto/key`
             - Request keys
 
-        *   - :doc:`./box_iproto/request_types`
+        *   - :doc:`./box_iproto/request_type`
             - Request types
 
-        *   - :doc:`./box_iproto/flags`
+        *   - :doc:`./box_iproto/flag`
             - Flags from the :ref:`IPROTO_FLAGS <box_protocol-flags>` key
 
         *   - :doc:`./box_iproto/ballot`
@@ -116,7 +127,7 @@ The table lists all available functions and data of the submodule:
             - Keys nested in the :ref:`IPROTO_METADATA <internals-iproto-keys-metadata>` key
 
         *   - :doc:`./box_iproto/raft`
-            - Keys from the ``IPROTO_RAFT*`` requests
+            - Keys from the ``IPROTO_RAFT_`` requests
 
         *   - :doc:`./box_iproto/protocol_version`
             - Current IPROTO protocol version
@@ -127,18 +138,17 @@ The table lists all available functions and data of the submodule:
         *   - :doc:`./box_iproto/feature`
             - IPROTO protocol :ref:`features <internals-iproto-keys-features>`
 
-         *  - :doc:`./box_iproto/override`
-            - Set an IPROTO request handler callbacks for the given request type
+        *   - :doc:`./box_iproto/override`
+            - Set a new IPROTO request handler callback for the given request type
 
-         *  - :doc:`./box_iproto/send`
+        *   - :doc:`./box_iproto/send`
             - Send an IPROTO packet over the session's socket
 
 
 ..  toctree::
     :hidden:
 
     box_iproto/key
-    box_iproto/request_key
     box_iproto/request_type
     box_iproto/flag
     box_iproto/ballot

doc/reference/reference_lua/box_iproto/ballot.rst

@@ -10,11 +10,16 @@ box.iproto.ballot_key
     The ``box.iproto.ballot_key`` namespace contains the keys from the :ref:`IPROTO_BALLOT <box_protocol-ballots>` requests.
     Learn more: :ref:`IPROTO_BALLOT keys <internals-iproto-keys-ballot>`.
 
-**Example**
+    **Example**
 
-..  code-block:: lua
+    ..  code-block:: lua
+
+        tarantool> box.iproto.ballot_key.IS_RO_CFG
+        ---
+        - 1
+        ...
+        tarantool> box.iproto.ballot_key.VCLOCK
+        ---
+        - 2
+        ...
 
-    box.iproto.ballot_key.IS_RO_CFG = 0x01
-    -- ...
-    box.iproto.ballot_key.VCLOCK = 0x02
-    -- ...