From ea2d16f4fc20dd23c057450d613457a046cc7d9c Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Fri, 13 Oct 2023 11:34:19 +0300 Subject: [PATCH 1/4] Add initial content * add functions to Lua and C API * add box.iproto module --- .../iproto/iproto_constants_export_test.lua | 192 +++++++++++++ doc/dev_guide/internals/iproto/format.rst | 14 +- doc/dev_guide/internals/iproto/keys.rst | 36 ++- .../internals/iproto/replication.rst | 4 +- doc/dev_guide/reference_capi/box.rst | 62 ++++- doc/reference/reference_lua/box.rst | 1 + .../reference_lua/box_info/schema_version.rst | 5 +- doc/reference/reference_lua/box_iproto.rst | 129 +++++++++ .../reference_lua/box_iproto/ballot.rst | 67 +++++ .../reference_lua/box_iproto/feature.rst | 65 +++++ .../reference_lua/box_iproto/flag.rst | 43 +++ .../reference_lua/box_iproto/key.rst | 252 ++++++++++++++++++ .../reference_lua/box_iproto/metadata.rst | 55 ++++ .../reference_lua/box_iproto/override.rst | 24 ++ .../box_iproto/protocol_features.rst | 24 ++ .../box_iproto/protocol_version.rst | 17 ++ .../reference_lua/box_iproto/raft.rst | 54 ++++ .../reference_lua/box_iproto/request_type.rst | 173 ++++++++++++ .../reference_lua/box_iproto/send.rst | 32 +++ .../reference_lua/box_session/id.rst | 17 +- styles/Vocab/Tarantool/accept.txt | 1 + 21 files changed, 1237 insertions(+), 30 deletions(-) create mode 100644 doc/code_snippets/test/iproto/iproto_constants_export_test.lua create mode 100644 doc/reference/reference_lua/box_iproto.rst create mode 100644 doc/reference/reference_lua/box_iproto/ballot.rst create mode 100644 doc/reference/reference_lua/box_iproto/feature.rst create mode 100644 doc/reference/reference_lua/box_iproto/flag.rst create mode 100644 doc/reference/reference_lua/box_iproto/key.rst create mode 100644 doc/reference/reference_lua/box_iproto/metadata.rst create mode 100644 doc/reference/reference_lua/box_iproto/override.rst create mode 100644 doc/reference/reference_lua/box_iproto/protocol_features.rst create mode 100644 doc/reference/reference_lua/box_iproto/protocol_version.rst create mode 100644 doc/reference/reference_lua/box_iproto/raft.rst create mode 100644 doc/reference/reference_lua/box_iproto/request_type.rst create mode 100644 doc/reference/reference_lua/box_iproto/send.rst diff --git a/doc/code_snippets/test/iproto/iproto_constants_export_test.lua b/doc/code_snippets/test/iproto/iproto_constants_export_test.lua new file mode 100644 index 0000000000..cfeed3d7c5 --- /dev/null +++ b/doc/code_snippets/test/iproto/iproto_constants_export_test.lua @@ -0,0 +1,192 @@ +local fio = require('fio') +local server = require('luatest.server') +local t = require('luatest') +local g = t.group() +g.before_each(function(cg) + cg.server = server:new { + box_cfg = {}, + workdir = fio.cwd() .. '/tmp' + } + cg.server:start() +end) + +g.after_each(function(cg) + cg.server:stop() + cg.server:drop() +end) + +local reference_table = { + -- `IPROTO_FLAGS` bitfield constants enumeration. + flag = { + COMMIT = 0x01, + WAIT_SYNC = 0x02, + WAIT_ACK = 0x04, + }, + + -- `iproto_key` enumeration. + key = { + REQUEST_TYPE = 0x00, + SYNC = 0x01, + REPLICA_ID = 0x02, + LSN = 0x03, + TIMESTAMP = 0x04, + SCHEMA_VERSION = 0x05, + SERVER_VERSION = 0x06, + GROUP_ID = 0x07, + TSN = 0x08, + FLAGS = 0x09, + STREAM_ID = 0x0a, + SPACE_ID = 0x10, + INDEX_ID = 0x11, + LIMIT = 0x12, + OFFSET = 0x13, + ITERATOR = 0x14, + INDEX_BASE = 0x15, + FETCH_POSITION = 0x1f, + KEY = 0x20, + TUPLE = 0x21, + FUNCTION_NAME = 0x22, + USER_NAME = 0x23, + INSTANCE_UUID = 0x24, + REPLICASET_UUID = 0x25, + VCLOCK = 0x26, + EXPR = 0x27, + OPS = 0x28, + BALLOT = 0x29, + TUPLE_META = 0x2a, + OPTIONS = 0x2b, + OLD_TUPLE = 0x2c, + NEW_TUPLE = 0x2d, + AFTER_POSITION = 0x2e, + AFTER_TUPLE = 0x2f, + DATA = 0x30, + ERROR_24 = 0x31, + METADATA = 0x32, + BIND_METADATA = 0x33, + BIND_COUNT = 0x34, + POSITION = 0x35, + SQL_TEXT = 0x40, + SQL_BIND = 0x41, + SQL_INFO = 0x42, + STMT_ID = 0x43, + REPLICA_ANON = 0x50, + ID_FILTER = 0x51, + ERROR = 0x52, + TERM = 0x53, + VERSION = 0x54, + FEATURES = 0x55, + TIMEOUT = 0x56, + EVENT_KEY = 0x57, + EVENT_DATA = 0x58, + TXN_ISOLATION = 0x59, + VCLOCK_SYNC = 0x5a, + AUTH_TYPE = 0x5b, + }, + + -- `iproto_metadata_key` enumeration. + metadata_key = { + NAME = 0, + TYPE = 1, + COLL = 2, + IS_NULLABLE = 3, + IS_AUTOINCREMENT = 4, + SPAN = 5, + }, + + -- `iproto_ballot_key` enumeration. + ballot_key = { + IS_RO_CFG = 0x01, + VCLOCK = 0x02, + GC_VCLOCK = 0x03, + IS_RO = 0x04, + IS_ANON = 0x05, + IS_BOOTED = 0x06, + CAN_LEAD = 0x07, + BOOTSTRAP_LEADER_UUID = 0x08, + REGISTERED_REPLICA_UUIDS = 0x09, + }, + + -- `iproto_type` enumeration. + type = { + OK = 0, + SELECT = 1, + INSERT = 2, + REPLACE = 3, + UPDATE = 4, + DELETE = 5, + CALL_16 = 6, + AUTH = 7, + EVAL = 8, + UPSERT = 9, + CALL = 10, + EXECUTE = 11, + NOP = 12, + PREPARE = 13, + BEGIN = 14, + COMMIT = 15, + ROLLBACK = 16, + RAFT = 30, + RAFT_PROMOTE = 31, + RAFT_DEMOTE = 32, + RAFT_CONFIRM = 40, + RAFT_ROLLBACK = 41, + PING = 64, + JOIN = 65, + SUBSCRIBE = 66, + VOTE_DEPRECATED = 67, + VOTE = 68, + FETCH_SNAPSHOT = 69, + REGISTER = 70, + JOIN_META = 71, + JOIN_SNAPSHOT = 72, + ID = 73, + WATCH = 74, + UNWATCH = 75, + EVENT = 76, + CHUNK = 128, + TYPE_ERROR = bit.lshift(1, 15), + UNKNOWN = -1, + }, + + -- `iproto_raft_keys` enumeration + raft_key = { + TERM = 0, + VOTE = 1, + STATE = 2, + VCLOCK = 3, + LEADER_ID = 4, + IS_LEADER_SEEN = 5, + }, + + -- `IPROTO_CURRENT_VERSION` constant + protocol_version = 4, + + -- `feature_id` enumeration + protocol_features = { + streams = true, + transactions = true, + error_extension = true, + watchers = true, + pagination = true, + }, + feature = { + streams = 0, + transactions = 1, + error_extension = 2, + watchers = 3, + pagination = 4, + }, +} + +-- Checks that IPROTO constants and features are exported correctly. +g.test_iproto_constants_export = function(cg) + cg.server:exec(function(reference_table) + for k, v in pairs(box.iproto) do + local v_type = type(v) + if v_type ~= 'function' and v_type ~= 'thread' and + v_type ~= 'userdata' then + t.assert_equals(v, reference_table[k]) + end + end + end, {reference_table}) +end diff --git a/doc/dev_guide/internals/iproto/format.rst b/doc/dev_guide/internals/iproto/format.rst index d258768565..4251793798 100644 --- a/doc/dev_guide/internals/iproto/format.rst +++ b/doc/dev_guide/internals/iproto/format.rst @@ -35,7 +35,7 @@ The header is an MP_MAP. It may contain, in any order: .. raw:: html :file: images/header.svg -* Both the request and response make use of the :ref:`IPROTO_REQUEST_TYPE ` key. +* Both the request and response use the :ref:`IPROTO_REQUEST_TYPE ` key. It denotes the type of the packet. * The request and the matching response have the same sync number (:ref:`IPROTO_SYNC `). @@ -61,22 +61,24 @@ To see how Tarantool decodes the header, have a look at file function ``netbox_decode_data``. For example, in a successful response to ``box.space:select()``, -the IPROTO_REQUEST_TYPE value will be 0 = ``IPROTO_OK`` and the -array will have all the tuples of the result. +the IPROTO_REQUEST_TYPE value is 0 = ``IPROTO_OK`` and the +array have all the tuples of the result. Read the source code file `net_box.c `__ where the function ``decode_metadata_optional`` is an example of how Tarantool itself decodes extra items. +.. _box_protocol-body: + Body ---- The body is an MP_MAP. Maximal iproto package body length is 2 GiB. The body has the details of the request or response. In a request, it can also -be absent or be an empty map. Both these states will be interpreted equally. -Responses will contain the body anyway even for an -:ref:`IPROTO_PING ` request, where it will be an empty MP_MAP. +be absent or be an empty map. Both these states are interpreted equally. +Responses contain the body anyway even for an +:ref:`IPROTO_PING ` request, where it is an empty MP_MAP. A lot of responses contain the IPROTO_DATA map: diff --git a/doc/dev_guide/internals/iproto/keys.rst b/doc/dev_guide/internals/iproto/keys.rst index 398512566d..8b6a312ee1 100644 --- a/doc/dev_guide/internals/iproto/keys.rst +++ b/doc/dev_guide/internals/iproto/keys.rst @@ -10,6 +10,8 @@ The keys are Tarantool constants that are either defined or mentioned in the While the keys themselves are unsigned 8-bit integers, their values can have different types. +.. _internals-iproto-keys-basic: + Basic description ----------------- @@ -50,6 +52,10 @@ General - 0x00 |br| MP_UINT - Request type or response type + * - :ref:`IPROTO_UNKNOWN ` + - -1 |br| MP_UINT + - Unknown request or response type + * - :ref:`IPROTO_ERROR ` - 0x52 |br| :ref:`MP_ERROR ` - Error response @@ -132,6 +138,8 @@ General - If ``IPROTO_FETCH_POSITION`` is **true**, returns a base64-encoded string representing the position of the last selected tuple +.. _internals-iproto-keys-streams: + Streams ~~~~~~~ @@ -192,8 +200,7 @@ General replication * - IPROTO_REPLICASET_UUID - 0x25 |br| MP_STR - - UUID of the replica set. - Prior to Tarantool version 2.11, IPROTO_REPLICASET_UUID was called IPROTO_CLUSTER_UUID. + - Before Tarantool version 2.11, IPROTO_REPLICASET_UUID was called IPROTO_CLUSTER_UUID. * - IPROTO_LSN - 0x03 |br| MP_UINT @@ -271,7 +278,7 @@ General replication followed by an array of ids of instances whose rows won't be relayed to the replica. Since v. :doc:`2.10.0 ` -.. _internals-iproto-keys-syncro-replication: +.. _internals-iproto-keys-synchro-replication: Synchronous replication ~~~~~~~~~~~~~~~~~~~~~~~ @@ -319,6 +326,8 @@ Synchronous replication All ``IPROTO_RAFT_*`` keys are used only in ``IPROTO_RAFT*`` requests. +.. _internals-iproto-keys-events: + Events and subscriptions ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -342,6 +351,8 @@ Events and subscriptions :ref:`Learn more about events and subscriptions in iproto `. +.. _internals-iproto-keys-sql-specific: + SQL-specific ~~~~~~~~~~~~ @@ -460,7 +471,7 @@ Available IPROTO_FEATURES are the following: in the request header). Learn more about :ref:`sending transaction commands `. - ``IPROTO_FEATURE_ERROR_EXTENSION = 2`` -- :ref:`MP_ERROR ` - MsgPack extension support. Clients that don't support this feature will receive + MsgPack extension support. Clients that don't support this feature receive error responses for :ref:`IPROTO_EVAL ` and :ref:`IPROTO_CALL ` encoded to string error messages. @@ -587,6 +598,13 @@ See requests and responses for :ref:`client-server communication `, :ref:`streams and interactive transactions `. +.. _internals-iproto-keys-unknown: + +IPROTO_UNKNOWN +~~~~~~~~~~~~~~ + +Code: -1. + .. _internals-iproto-keys-error: IPROTO_ERROR @@ -606,7 +624,7 @@ IPROTO_ERROR_24 Code: 0x31. -IPROTO_ERROR_24 is used in Tarantool versions prior to :doc:`2.4.1 `. +IPROTO_ERROR_24 is used in Tarantool versions before :doc:`2.4.1 `. The key contains the error in the string format. Since :doc:`Tarantool 2.4.1 `, @@ -654,10 +672,10 @@ Code: 0x09. When it comes to replicating synchronous transactions, the IPROTO_FLAGS key is included in the header. The key contains an MP_UINT value of one or more bits: -* IPROTO_FLAG_COMMIT (0x01) will be set if this is the last message for a transaction. -* IPROTO_FLAG_WAIT_SYNC (0x02) will be set if this is the last message +* IPROTO_FLAG_COMMIT (0x01) is set if this is the last message for a transaction. +* IPROTO_FLAG_WAIT_SYNC (0x02) is set if this is the last message for a transaction which cannot be completed immediately. -* IPROTO_FLAG_WAIT_ACK (0x04) will be set if this is the last message for a synchronous transaction. +* IPROTO_FLAG_WAIT_ACK (0x04) is set if this is the last message for a synchronous transaction. Example: @@ -739,7 +757,7 @@ at least IPROTO_FIELD_NAME (0x00) and MP_STR, and IPROTO_FIELD_TYPE (0x01) and M Additionally, if ``sql_full_metadata`` in the :ref:`_session_settings ` system space -is TRUE, then the array will have these additional column maps +is TRUE, then the array has these additional column maps which correspond to components described in the :ref:`box.execute() ` section. .. _internals-iproto-keys-sql_bind: diff --git a/doc/dev_guide/internals/iproto/replication.rst b/doc/dev_guide/internals/iproto/replication.rst index 9c7a0d7dc1..f22355c618 100644 --- a/doc/dev_guide/internals/iproto/replication.rst +++ b/doc/dev_guide/internals/iproto/replication.rst @@ -11,6 +11,8 @@ These values and the corresponding packet body structures are considered below. Connectors and clients do not need to send replication packets. +.. _box_protocol-general: + General ------- @@ -198,7 +200,7 @@ Synchronous - 0x28 - Confirm that the RAFT transactions have achieved quorum and can be committed - * - :ref:`IPROTO_RAFT_ROLLBACK ` + * - :ref:`IPROTO_RAFT_ROLLBACK ` - 0x29 - Roll back the RAFT transactions because they haven't achieved quorum diff --git a/doc/dev_guide/reference_capi/box.rst b/doc/dev_guide/reference_capi/box.rst index cbb0f016ae..c3348acab6 100644 --- a/doc/dev_guide/reference_capi/box.rst +++ b/doc/dev_guide/reference_capi/box.rst @@ -205,7 +205,7 @@ .. _box_box_sequence_current: -.. c:function:: int box_sequence_current(uint32_t seq_id, int64_t *result); +.. c:function:: int box_sequence_current(uint32_t seq_id, int64_t *result) Since version :doc:`2.4.1 `. Return the last retrieved value of the specified sequence. @@ -217,14 +217,68 @@ :return: 0 on success and -1 otherwise. In case of an error user could get it via ``box_error_last()``. -.. _box_box_session_id: +.. _box_box_schema_version: -.. c:function:: uint64_t box_session_id(void); +.. c:function:: uint32_t box_schema_version(void) + + Since version :doc:`2.11.0 `. + Return the database schema version. + A schema version is a number that indicates whether the :ref:`database schema ` is changed. + For example, the ``schema_version`` value grows if a :ref:`space ` or :ref:`index ` + is added or deleted, or a space, index, or field name is changed. + + :return: the database schema version + :rtype: number + + See also :ref:`box.info.schema_version ` and :ref:`IPROTO_SCHEMA_VERSION ` + +.. _box_box_session_id: + +.. c:function:: uint64_t box_session_id(void) Since version :doc:`2.11.0 `. Return the unique identifier (ID) for the current session. :return: the unique identifier (ID) for the current session :return: 0 or -1 if there is no session + :rtype: number + + See also :ref:`box.session.id() ` + +.. _box_box_iproto_send: + +.. 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 `. + Send an :ref:`IPROTO ` packet over the session's socket with the given MsgPack header + and body. NB: yields. + + :param uint32_t sid: IPROTO session identifier (see :ref:`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_end: end of a body encoded as MsgPack + + :return: 0 on success + :return: 1 if there is a failure + :rtype: number + + See also :ref:`box.iproto.send() ` + +.. _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 `. + Sets an IPROTO request handler with the provided context for the given request type. + + :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: context passed to handler + + :return: 0 on success + :return: -1 on error (check :ref:`box_error_last() `) + :rtype: number - See also :ref:`box.session.id()` + See also :ref:`box.session.id() ` \ No newline at end of file diff --git a/doc/reference/reference_lua/box.rst b/doc/reference/reference_lua/box.rst index 41cfcd49d9..13008e75be 100644 --- a/doc/reference/reference_lua/box.rst +++ b/doc/reference/reference_lua/box.rst @@ -27,6 +27,7 @@ with ``box``, with no arguments. The ``box`` module contains: box_error box_index box_info + box_iproto box_read_view box_schema box_schema_sequence diff --git a/doc/reference/reference_lua/box_info/schema_version.rst b/doc/reference/reference_lua/box_info/schema_version.rst index fed9dab577..dbd043297d 100644 --- a/doc/reference/reference_lua/box_info/schema_version.rst +++ b/doc/reference/reference_lua/box_info/schema_version.rst @@ -1,8 +1,7 @@ .. _box_info_schema_version: -================================================================================ box.info.schema_version -================================================================================ +======================= .. module:: box.info @@ -23,3 +22,5 @@ box.info.schema_version --- - 84 ... + + See also :ref:`IPROTO_SCHEMA_VERSION ` diff --git a/doc/reference/reference_lua/box_iproto.rst b/doc/reference/reference_lua/box_iproto.rst new file mode 100644 index 0000000000..9356ac0586 --- /dev/null +++ b/doc/reference/reference_lua/box_iproto.rst @@ -0,0 +1,129 @@ +.. _box_iproto: + +Submodule box.iproto +==================== + +Since :doc:`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 ` functionality from the Lua libraries. +With this submodule, you can: + +* parse the unknown IPROTO requests +* send arbitrary IPROTO packets +* override the behavior of the existing request types in binary protocol + +To make this possible, the submodule exports all IPROTO :ref:`constants ` and features to Lua. + +.. _box_iproto-constants: + +IPROTO constants +---------------- + +The IPROTO constants in the ``box.iproto`` namespace are written in the upper case without the ``IPROTO_`` prefix. +The constants are divided into several types: + +* :ref:`key ` (:ref:`IPROTO_SYNC `, :ref:`IPROTO_REQUEST_TYPE `) +* :ref:`request type ` (:ref:`IPROTO_OK `) +* :ref:`flag ` (:ref:`IPROTO_COMMIT `) +* :ref:`ballot key ` (:ref:`IPROTO_FLAG_COMMIT `) +* :ref:`metadata key ` (``IPROTO_FIELD_IS_NULLABLE``) +* :ref:`RAFT key ` (:ref:`IPROTO_TERM `) + +Each type is located in the corresponding subnamespace without prefix. +For example: + +.. code-block:: lua + + box.iproto.key.SYNC = 0x01 + -- ... + box.iproto.type.SELECT = 1 + -- ... + box.iproto.flag.COMMIT = 0x01 + -- ... + box.iproto.ballot_key.VCLOCK = 0x02 + -- ... + box.iproto.metadata_key.IS_NULLABLE = 3 + -- ... + box.iproto.raft_key.TERM = 0 + -- ... + +.. _box_iproto-features: + +IPROTO features +--------------- + +The submodule exports: + +* the current IPROTO protocol version (:ref:`box.iproto.protocol_version `) +* the set of IPROTO protocol features supported by the server (:ref:`box.iproto.protocol_features `) +* IPROTO protocol features with the corresponding code (:ref:`box.iproto.feature `) + +.. _box_iproto-reference: + +API reference +------------- + +The table lists all available members and functions of the submodule: + +.. container:: table + + .. rst-class:: left-align-column-1 + .. rst-class:: left-align-column-2 + + .. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Name + - Use + + * - :doc:`./box_iproto/keys` + - Request keys + + * - :doc:`./box_iproto/request_types` + - Request types + + * - :doc:`./box_iproto/flags` + - Flags from the :ref:`IPROTO_FLAGS `>` key + + * - :doc:`./box_iproto/ballot` + - Keys from the :ref:`IPROTO_BALLOT ` requests + + * - :doc:`./box_iproto/metadata` + - Keys nested in the :ref:`IPROTO_METADATA ` key + + * - :doc:`./box_iproto/raft` + - Keys from the ``IPROTO_RAFT*`` requests + + * - :doc:`./box_iproto/protocol_version` + - Current IPROTO protocol version + + * - :doc:`./box_iproto/protocol_features` + - The set of supported IPROTO protocol features + + * - :doc:`./box_iproto/feature` + - IPROTO protocol features + + * - :doc:`./box_iproto/override` + - Set the IPROTO request handler callbacks + + * - :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 + box_iproto/metadata + box_iproto/raft + box_iproto/protocol_version + box_iproto/protocol_features + box_iproto/feature + box_iproto/override + box_iproto/send diff --git a/doc/reference/reference_lua/box_iproto/ballot.rst b/doc/reference/reference_lua/box_iproto/ballot.rst new file mode 100644 index 0000000000..1d9ba557d6 --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/ballot.rst @@ -0,0 +1,67 @@ +.. _reference_lua-box_iproto_ballot: + +box.iproto.ballot_key +===================== + +.. module:: box.iproto + + .. data:: ballot_key + + The ``box.iproto.ballot_key`` namespace contains the keys from the :ref:`IPROTO_BALLOT ` requests. + Learn more: :ref:`IPROTO_BALLOT keys `. + + Available keys: + + .. list-table:: + :header-rows: 1 + :widths: 40 20 40 + + * - Exported constant + - IPROTO constant name + - Code + + * - IS_RO_CFG + - :ref:`IPROTO_BALLOT_IS_RO_CFG ` + - 0x01 + + * - VCLOCK + - :ref:`IPROTO_BALLOT_VCLOCK ` + - 0x02 + + * - GC_VCLOCK + - :ref:`IPROTO_BALLOT_GC_VCLOCK ` + - 0x03 + + * - IS_RO + - :ref:`IPROTO_BALLOT_IS_RO ` + - 0x04 + + * - IS_ANON + - 0x05 + - :ref:`IPROTO_BALLOT_IS_ANON ` + + * - IS_BOOTED + - :ref:`IPROTO_BALLOT_IS_BOOTED ` + - 0x06 + + * - CAN_LEAD + - :ref:`IPROTO_BALLOT_CAN_LEAD ` + - 0x07 + + * - BOOTSTRAP_LEADER_UUID + - :ref:`IPROTO_BALLOT_BOOTSTRAP_LEADER_UUID ` + - 0x08 + + * - REGISTERED_REPLICA_UUIDS + - :ref:`IPROTO_BALLOT_REGISTERED_REPLICA_UUIDS ` + - 0x09 + + +**Example** + +.. code-block:: lua + + box.iproto.ballot_key.IS_RO_CFG = 0x01 + -- ... + box.iproto.ballot_key.VCLOCK = 0x02 + -- ... diff --git a/doc/reference/reference_lua/box_iproto/feature.rst b/doc/reference/reference_lua/box_iproto/feature.rst new file mode 100644 index 0000000000..da2f6ff90f --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/feature.rst @@ -0,0 +1,65 @@ +.. _reference_lua-box_iproto_feature: + +box.iproto.feature +================== + +.. module:: box.iproto + + .. data:: feature + + The ``box.iproto.feature`` namespace contains the IPROTO protocol features supported by the server. + Each feature is mapped to its corresponding code. + Learn more: :ref:`IPROTO_FEATURES `. + + The features in the namespace are written + + * in the lower case + * without the ``IPROTO_FEATURE_`` prefix + + Available features: + + .. list-table:: + :header-rows: 1 + :widths: 40 20 40 + + * - Exported feature + - IPROTO protocol feature + - Code + - Description + + * - streams + - :ref:`IPROTO_FEATURE_STREAMS ` + - 0 + - :ref:`Stream ` support + + * - transactions + - :ref:`IPROTO_SYNC ` + - 1 + - Transaction support + + * - error_extension + - :ref:`IPROTO_FEATURE_ERROR_EXTENSION ` + - 2 + - :ref:`MP_ERROR ` MsgPack extension support + + * - watchers + - :ref:`IPROTO_FEATURE_WATCHERS ` + - 3 + - Remote watchers support ( see :ref:`IPROTO_WATCH `, + :ref:`IPROTO_UNWATCH `, and :ref:`IPROTO_EVENT `) + + * - pagination + - :ref:`IPROTO_FEATURE_PAGINATION ` + - 4 + - Pagination support + + +**Example** + +.. code-block:: lua + + box.iproto.feature.streams = 0 + box.iproto.feature.transactions = 1 + box.iproto.feature.error_extension = 2 + box.iproto.feature.watchers = 3 + box.iproto.feature.pagination = 4 diff --git a/doc/reference/reference_lua/box_iproto/flag.rst b/doc/reference/reference_lua/box_iproto/flag.rst new file mode 100644 index 0000000000..1aa3854a83 --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/flag.rst @@ -0,0 +1,43 @@ +.. _reference_lua-box_iproto_flag: + +box.iproto.flag +=============== + +.. module:: box.iproto + + .. data:: flag + + The ``box.iproto.flag`` namespace contains the flags from the ``IPROTO_FLAGS`` key. + Learn more: :ref:`IPROTO_FLAGS key `. + + Available flags: + + .. list-table:: + :header-rows: 1 + :widths: 40 20 40 + + * - Exported flag + - IPROTO flag name + - Code + + * - COMMIT + - :ref:`IPROTO_FLAG_COMMIT ` + - 0x01 + + * - WAIT_SYNC + - :ref:`IPROTO_FLAG_WAIT_SYNC ` + - 0x02 + + * - WAIT_ACK + - :ref:`IPROTO_FLAG_WAIT_ACK ` + - 0x03 + + +**Example** + +.. code-block:: lua + + box.iproto.flag.COMMIT = 0x01 + -- ... + box.iproto.flag.WAIT_SYNC = 0x02 + -- ... \ No newline at end of file diff --git a/doc/reference/reference_lua/box_iproto/key.rst b/doc/reference/reference_lua/box_iproto/key.rst new file mode 100644 index 0000000000..543f85a698 --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/key.rst @@ -0,0 +1,252 @@ +.. _reference_lua-box_iproto_key: + +box.iproto.key +============== + +.. module:: box.iproto + + .. data:: key + + The ``box.iproto.key`` namespace contains the request keys. + To + + Available keys: + + .. list-table:: + :header-rows: 1 + :widths: 40 20 40 + + * - Exported flag + - IPROTO flag name + - Code + + * - REQUEST_TYPE + - :ref:`IPROTO_REQUEST_TYPE ` + - 0x00 + + * - SYNC + - :ref:`IPROTO_SYNC ` + - 0x01 + + * - REPLICA_ID + - :ref:`IPROTO_REPLICA_ID ` + - 0x02 + + * - LSN + - :ref:`IPROTO_LSN ` + - 0x03 + + * - TIMESTAMP + - :ref:`IPROTO_TIMESTAMP ` + - 0x04 + + * - SCHEMA_VERSION + - :ref:`IPROTO_SCHEMA_VERSION ` + - 0x05 + + * - SERVER_VERSION + - :ref:`IPROTO_SERVER_VERSION ` + - 0x06 + + * - GROUP_ID + - IPROTO_GROUP_ID + - 0x07 + + * - TSN + - :ref:`IPROTO_TSN ` + - 0x08 + + * - FLAGS + - :ref:`IPROTO_FLAGS ` + - 0x09 + + * - STREAM_ID + - :ref:`IPROTO_STREAM_ID ` + - 0x0a + + * - SPACE_ID + - :ref:`IPROTO_SPACE_ID ` + - 0x10 + + * - INDEX_ID + - :ref:`IPROTO_INDEX_ID ` + - 0x11 + + * - LIMIT + - :ref:`IPROTO_LIMIT ` + - 0x12 + + * - OFFSET + - :ref:`IPROTO_OFFSET ` + - 0x13 + + * - ITERATOR + - :ref:`IPROTO_ITERATOR ` + - 0x14 + + * - INDEX_BASE + - :ref:`IPROTO_INDEX_BASE ` + - 0x15 + + * - FETCH_POSITION + - :ref:`IPROTO_FETCH_POSITION ` + - 0x1f + + * - KEY + - :ref:`IPROTO_KEY ` + - 0x20 + + * - TUPLE + - :ref:`IPROTO_TUPLE ` + - 0x21 + + * - FUNCTION_NAME + - :ref:`IPROTO_FUNCTION_NAME ` + - 0x22 + + * - USER_NAME + - :ref:`IPROTO_USER_NAME ` + - 0x23 + + * - INSTANCE_UUID + - :ref:`IPROTO_INSTANCE_UUID ` + - 0x24 + + * - REPLICASET_UUID + - :ref:`IPROTO_REPLICASET_UUID ` + - 0x25 + + * - VCLOCK + - :ref:`IPROTO_VCLOCK ` + - 0x26 + + * - EXPR + - :ref:`IPROTO_EXPR ` + - 0x27 + + * - OPS + - :ref:`IPROTO_OPS ` + - 0x28 + + * - BALLOT + - :ref:`IPROTO_BALLOT ` + - 0x29 + + * - TUPLE_META + - IPROTO_TUPLE_META + - 0x2a + + * - OPTIONS + - :ref:`IPROTO_OPTIONS ` + - 0x2b + + * - OLD_TUPLE + - IPROTO_OLD_TUPLE + - 0x2c + + * - NEW_TUPLE + - IPROTO_NEW_TUPLE + - 0x2d + + * - AFTER_POSITION + - :ref:`IPROTO_AFTER_POSITION ` + - 0x2e + + * - AFTER_TUPLE + - :ref:`IPROTO_AFTER_TUPLE ` + - 0x2f + + * - DATA + - :ref:`IPROTO_DATA ` + - 0x30 + + * - ERROR_24 + - :ref:`IPROTO_ERROR_24 ` + - 0x31 + + * - METADATA + - :ref:`IPROTO_METADATA ` + - 0x32 + + * - BIND_METADATA + - :ref:`IPROTO_BIND_METADATA ` + - 0x33 + + * - BIND_COUNT + - :ref:`IPROTO_BIND_COUNT ` + - 0x34 + + * - POSITION + - :ref:`IPROTO_POSITION ` + - 0x35 + + * - SQL_TEXT + - :ref:`IPROTO_SQL_TEXT ` + - 0x40 + + * - SQL_BIND + - :ref:`IPROTO_SQL_BIND ` + - 0x41 + + * - SQL_INFO + - :ref:`IPROTO_SQL_INFO ` + - 0x42 + + * - STMT_ID + - :ref:`IPROTO_STMT_ID ` + - 0x43 + + * - REPLICA_ANON + - :ref:`IPROTO_REPLICA_ANON ` + - 0x50 + + * - ID_FILTER + - :ref:`IPROTO_ID_FILTER ` + - 0x51 + + * - ERROR + - :ref:`IPROTO_ERROR ` + - 0x52 + + * - TERM + - :ref:`IPROTO_TERM ` + - 0x53 + + * - VERSION + - :ref:`IPROTO_VERSION ` + - 0x54 + + * - FEATURES + - :ref:`IPROTO_FEATURES ` + - 0x55 + + * - TIMEOUT + - :ref:`IPROTO_TIMEOUT ` + - 0x56 + + * - EVENT_KEY + - :ref:`IPROTO_EVENT_KEY ` + - 0x57 + + * - EVENT_DATA + - :ref:`IPROTO_EVENT_DATA ` + - 0x58 + + * - TXN_ISOLATION + - :ref:`IPROTO_TXN_ISOLATION ` + - 0x59 + + * - VCLOCK_SYNC + - :ref:`IPROTO_VCLOCK_SYNC ` + - 0x5a + + * - AUTH_TYPE + - :ref:`IPROTO_AUTH_TYPE ` + - 0x5b + +**Example** + +.. code-block:: lua + + box.iproto.key.SYNC = 0x01 + -- ... \ No newline at end of file diff --git a/doc/reference/reference_lua/box_iproto/metadata.rst b/doc/reference/reference_lua/box_iproto/metadata.rst new file mode 100644 index 0000000000..6d3fb801b3 --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/metadata.rst @@ -0,0 +1,55 @@ +.. _reference_lua-box_iproto_metadata: + +box.iproto.metadata_key +======================= + +.. module:: box.iproto + + .. data:: metadata_key + + The ``box.iproto.metadata_key`` namespace contains the ``IPROTO_FILED_*`` keys, which are nested in the + :ref:`IPROTO_METADATA ` key. + + Available keys: + + .. list-table:: + :header-rows: 1 + :widths: 40 20 40 + + * - Exported constant + - IPROTO constant name + - Code + + * - NAME + - :ref:`IPROTO_FIELD_NAME ` + - 0 + + * - TYPE + - :ref:`IPROTO_FIELD_TYPE ` + - 1 + + * - COLL + - :ref:`IPROTO_FIELD_COLL ` + - 2 + + * - IS_NULLABLE + - :ref:`IPROTO_FIELD_IS_NULLABLE ` + - 3 + + * - IS_AUTOINCREMENT + - :ref:`IPROTO_FIELD_IS_AUTOINCREMENT ` + - 4 + + * - SPAN + - :ref:`IPROTO_FIELD_SPAN ` + - 5 + + +**Example** + +.. code-block:: lua + + box.iproto.metadata_key.NAME = 1 + -- ... + box.iproto.metadata_key.TYPE = 2 + -- ... diff --git a/doc/reference/reference_lua/box_iproto/override.rst b/doc/reference/reference_lua/box_iproto/override.rst new file mode 100644 index 0000000000..5b55a4bdd2 --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/override.rst @@ -0,0 +1,24 @@ +.. _reference_lua-box_iproto_override: + +box.iproto.override() +===================== + +.. module:: box.iproto + +.. function:: override(request_type, handler) + + Since version :doc:`2.11.0 `. + Set the IPROTO request handler callbacks. + + :param uint32_t request_type: + :param iproto_handler_t handler: + + :return: 0 on success or -1 on error (check box_error_last()) + :rtype: number + + **Example:** + + .. code-block:: tarantoolsession + + tarantool> + diff --git a/doc/reference/reference_lua/box_iproto/protocol_features.rst b/doc/reference/reference_lua/box_iproto/protocol_features.rst new file mode 100644 index 0000000000..c2fc87291b --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/protocol_features.rst @@ -0,0 +1,24 @@ +.. _reference_lua-box_iproto_protocol-features: + +box.iproto.protocol_version +=========================== + +.. module:: box.iproto + + .. data:: protocol_version + + The set of IPROTO protocol features supported by the server. + Learn more: `src/box/iproto_features.h `__ + and `iproto_features_resolve() `__). + +**Example** + +.. code-block:: lua + + box.iproto.protocol_features = { + streams = true, + transactions = true, + error_extension = true, + watchers = true, + } + diff --git a/doc/reference/reference_lua/box_iproto/protocol_version.rst b/doc/reference/reference_lua/box_iproto/protocol_version.rst new file mode 100644 index 0000000000..76cbeaefa3 --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/protocol_version.rst @@ -0,0 +1,17 @@ +.. _reference_lua-box_iproto_version: + +box.iproto.protocol_version +=========================== + +.. module:: box.iproto + + .. data:: protocol_version + + Current IPROTO protocol version of the server. + Learn more: :ref:`IPROTO_ID `. + +**Example** + +.. code-block:: lua + + box.iproto.protocol_version = 4 \ No newline at end of file diff --git a/doc/reference/reference_lua/box_iproto/raft.rst b/doc/reference/reference_lua/box_iproto/raft.rst new file mode 100644 index 0000000000..ab1139356e --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/raft.rst @@ -0,0 +1,54 @@ +.. _reference_lua-box_iproto_raft: + +box.iproto.raft +=============== + +.. module:: box.iproto + + .. data:: raft_key + + The ``box.iproto.raft_key`` namespace contains the keys from the ``IPROTO_RAFT_*`` requests. + Learn more: :ref:`Synchronous replication keys `. + + Available keys: + + .. list-table:: + :header-rows: 1 + :widths: 40 20 40 + + * - Exported constant + - IPROTO constant name + - Code + + * - TERM + - :ref:`IPROTO_RAFT_TERM ` + - 0 + + * - VOTE + - :ref:`IPROTO_RAFT_VOTE ` + - 1 + + * - STATE + - :ref:`IPROTO_RAFT_STATE ` + - 2 + + * - VCLOCK + - :ref:`IPROTO_RAFT_VCLOCK ` + - 3 + + * - LEADER_ID + - :ref:`IPROTO_RAFT_LEADER_ID ` + - 4 + + * - IS_LEADER_SEEN + - :ref:`IPROTO_RAFT_IS_LEADER_SEEN ` + - 5 + +**Example** + +.. code-block:: lua + + box.iproto.raft_key.TERM = 0 + -- ... + box.iproto.raft_key.VOTE = 1 + -- ... diff --git a/doc/reference/reference_lua/box_iproto/request_type.rst b/doc/reference/reference_lua/box_iproto/request_type.rst new file mode 100644 index 0000000000..4563286321 --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/request_type.rst @@ -0,0 +1,173 @@ +.. _reference_lua-box_iproto_type: + +box.iproto.type +=============== + +.. module:: box.iproto + + .. data:: type + + The ``box.iproto.type`` namespace contains all available request types. + Learn more about the requests: :ref:`Client-server requests and responses `. + + Available types: + + .. list-table:: + :header-rows: 1 + :widths: 40 20 40 + + * - Exported constant + - IPROTO constant name + - Code + + * - OK + - :ref:`IPROTO_OK ` + - 0 + + * - SELECT + - :ref:`IPROTO_SELECT ` + - 1 + + * - INSERT + - :ref:`IPROTO_INSERT ` + - 2 + + * - REPLACE + - :ref:`IPROTO_REPLACE ` + - 3 + + * - UPDATE + - :ref:`IPROTO_REPLACE ` + - 4 + + * - DELETE + - :ref:`IPROTO_REPLACE ` + - 5 + + * - CALL_16 + - :ref:`IPROTO_CALL_16 ` + - 6 + + * - AUTH + - :ref:`IPROTO_AUTH ` + - 7 + + * - EVAL + - :ref:`IPROTO_EVAL ` + - 8 + + * - UPSERT + - :ref:`IPROTO_UPSERT ` + - 9 + + * - CALL + - :ref:`IPROTO_CALL ` + - 10 + + * - EXECUTE + - :ref:`IPROTO_EXECUTE ` + - 11 + + * - NOP + - :ref:`IPROTO_NOP ` + - 12 + + * - PREPARE + - :ref:`IPROTO_PREPARE ` + - 13 + + * - BEGIN + - :ref:`IPROTO_BEGIN ` + - 14 + + * - COMMIT + - :ref:`IPROTO_COMMIT ` + - 15 + + * - ROLLBACK + - :ref:`IPROTO_ROLLBACK ` + - 16 + + * - RAFT + - :ref:`IPROTO_RAFT ` + - 30 + + * - RAFT_PROMOTE + - :ref:`IPROTO_BALLOT_REGISTERED_REPLICA_UUIDS ` + - 31 + + * - RAFT_DEMOTE + - :ref:`IPROTO_RAFT_DEMOTE ` + - 32 + + * - RAFT_CONFIRM + - :ref:`IPROTO_RAFT_CONFIRM ` + - 40 + + * - RAFT_ROLLBACK + - :ref:`IPROTO_RAFT_ROLLBACK ` + - 41 + + * - PING + - :ref:`IPROTO_PING ` + - 64 + + * - JOIN + - :ref:`IPROTO_JOIN ` + - 65 + + * - SUBSCRIBE + - :ref:`IPROTO_SUBSCRIBE ` + - 66 + + * - VOTE_DEPRECATED + - IPROTO_VOTE_DEPRECATED + - 67 + + * - VOTE + - :ref:`IPROTO_VOTE ` + - 68 + + * - FETCH_SNAPSHOT + - :ref:`IPROTO_FETCH_SNAPSHOT ` + - 69 + + * - REGISTER + - :ref:`IPROTO_REGISTER ` + - 70 + + * - JOIN_META + - IPROTO_JOIN_META + - 71 + + * - JOIN_SNAPSHOT + - IPROTO_JOIN_SNAPSHOT + - 72 + + * - ID + - :ref:`IPROTO_ID ` + - 73 + + * - WATCH + - :ref:`IPROTO_WATCH ` + - 74 + + * - UNWATCH + - :ref:`IPROTO_UNWATCH ` + - 75 + + * - EVENT + - :ref:`IPROTO_WATCH ` + - 76 + + * - CHUNK + - :ref:`IPROTO_CHUNK ` + - 128 + + * - TYPE_ERROR + - :ref:`IPROTO_TYPE_ERROR ` + - bit.lshift(1, 15) + + * - UNKNOWN + - :ref:`IPROTO_UNKNOWN ` + - -1 diff --git a/doc/reference/reference_lua/box_iproto/send.rst b/doc/reference/reference_lua/box_iproto/send.rst new file mode 100644 index 0000000000..9fac68a264 --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/send.rst @@ -0,0 +1,32 @@ +.. _reference_lua-box_iproto_send: + +box.iproto.send() +================= + +.. module:: box.iproto + +.. function:: send(sid, header[, body]) + + Since version :doc:`2.11.0 `. + Send an :ref:`IPROTO ` packet over the session's socket with the given MsgPack header + and body. + + :param number sid: IPROTO session identifier (see :ref:`box.session.id() `) + :param table|string header: a request header encoded as MsgPack + :param table|string|nil body: a request body encoded as MsgPack + + :return: 0 on success + :return: 1 on error + :rtype: number + + **Possible errors:** + + * Index is not of type 'TREE'. + * :errcode:`ER_TRANSACTION_CONFLICT` if a transaction conflict is detected in the + :ref:`MVCC transaction mode `. + + **Complexity factors:** Index size, Index type. + + **Example:** + + diff --git a/doc/reference/reference_lua/box_session/id.rst b/doc/reference/reference_lua/box_session/id.rst index 9d383e4436..d48c1577aa 100644 --- a/doc/reference/reference_lua/box_session/id.rst +++ b/doc/reference/reference_lua/box_session/id.rst @@ -1,14 +1,15 @@ -.. _box_session-id: +.. _box_session-id: -================================================================================ box.session.id() -================================================================================ +================ -.. module:: box.session +.. module:: box.session -.. function:: id() +.. function:: id() - :return: the unique identifier (ID) for the current session. - The result can be 0 or -1 meaning there is no session. - :rtype: number \ No newline at end of file + Return the unique identifier (ID) for the current session. + + :return: the unique identifier (ID) for the current session + :return: 0 or -1 if there is no session + :rtype: number \ No newline at end of file diff --git a/styles/Vocab/Tarantool/accept.txt b/styles/Vocab/Tarantool/accept.txt index 79dc6dbd8d..ee96c83bfe 100644 --- a/styles/Vocab/Tarantool/accept.txt +++ b/styles/Vocab/Tarantool/accept.txt @@ -35,6 +35,7 @@ upsert tt SEQSCAN iproto +IPROTO autoincrement etcd canonicalization From f8b49a4a8c94fe78ec7e26bb9123a2bd4e0174ad Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Mon, 30 Oct 2023 12:01:55 +0300 Subject: [PATCH 2/4] Add minor fixes --- doc/dev_guide/internals/iproto/keys.rst | 2 + doc/reference/reference_lua/box_iproto.rst | 8 +- .../reference_lua/box_iproto/ballot.rst | 10 +- .../reference_lua/box_iproto/feature.rst | 72 ++-- .../reference_lua/box_iproto/flag.rst | 8 +- .../reference_lua/box_iproto/key.rst | 355 +++++++++--------- .../reference_lua/box_iproto/metadata.rst | 8 +- .../reference_lua/box_iproto/override.rst | 4 - .../box_iproto/protocol_features.rst | 8 +- .../box_iproto/protocol_version.rst | 7 +- .../reference_lua/box_iproto/raft.rst | 8 +- .../reference_lua/box_iproto/request_type.rst | 8 +- .../reference_lua/box_iproto/send.rst | 6 - 13 files changed, 248 insertions(+), 256 deletions(-) diff --git a/doc/dev_guide/internals/iproto/keys.rst b/doc/dev_guide/internals/iproto/keys.rst index 8b6a312ee1..656efe6f36 100644 --- a/doc/dev_guide/internals/iproto/keys.rst +++ b/doc/dev_guide/internals/iproto/keys.rst @@ -605,6 +605,8 @@ IPROTO_UNKNOWN Code: -1. +Unknown request or response type. + .. _internals-iproto-keys-error: IPROTO_ERROR diff --git a/doc/reference/reference_lua/box_iproto.rst b/doc/reference/reference_lua/box_iproto.rst index 9356ac0586..c716ddf989 100644 --- a/doc/reference/reference_lua/box_iproto.rst +++ b/doc/reference/reference_lua/box_iproto.rst @@ -27,7 +27,7 @@ The constants are divided into several types: * :ref:`request type ` (:ref:`IPROTO_OK `) * :ref:`flag ` (:ref:`IPROTO_COMMIT `) * :ref:`ballot key ` (:ref:`IPROTO_FLAG_COMMIT `) -* :ref:`metadata key ` (``IPROTO_FIELD_IS_NULLABLE``) +* :ref:`metadata key ` (:ref:`IPROTO_FIELD_IS_NULLABLE `) * :ref:`RAFT key ` (:ref:`IPROTO_TERM `) Each type is located in the corresponding subnamespace without prefix. @@ -64,7 +64,7 @@ The submodule exports: API reference ------------- -The table lists all available members and functions of the submodule: +The table lists all available functions and data of the submodule: .. container:: table @@ -85,7 +85,7 @@ The table lists all available members and functions of the submodule: - Request types * - :doc:`./box_iproto/flags` - - Flags from the :ref:`IPROTO_FLAGS `>` key + - Flags from the :ref:`IPROTO_FLAGS ` key * - :doc:`./box_iproto/ballot` - Keys from the :ref:`IPROTO_BALLOT ` requests @@ -103,7 +103,7 @@ The table lists all available members and functions of the submodule: - The set of supported IPROTO protocol features * - :doc:`./box_iproto/feature` - - IPROTO protocol features + - IPROTO protocol :ref:`features ` * - :doc:`./box_iproto/override` - Set the IPROTO request handler callbacks diff --git a/doc/reference/reference_lua/box_iproto/ballot.rst b/doc/reference/reference_lua/box_iproto/ballot.rst index 1d9ba557d6..35095b57aa 100644 --- a/doc/reference/reference_lua/box_iproto/ballot.rst +++ b/doc/reference/reference_lua/box_iproto/ballot.rst @@ -5,16 +5,16 @@ box.iproto.ballot_key .. module:: box.iproto - .. data:: ballot_key +.. data:: ballot_key - The ``box.iproto.ballot_key`` namespace contains the keys from the :ref:`IPROTO_BALLOT ` requests. - Learn more: :ref:`IPROTO_BALLOT keys `. + The ``box.iproto.ballot_key`` namespace contains the keys from the :ref:`IPROTO_BALLOT ` requests. + Learn more: :ref:`IPROTO_BALLOT keys `. Available keys: .. list-table:: :header-rows: 1 - :widths: 40 20 40 + :widths: 40 40 20 * - Exported constant - IPROTO constant name @@ -37,8 +37,8 @@ box.iproto.ballot_key - 0x04 * - IS_ANON - - 0x05 - :ref:`IPROTO_BALLOT_IS_ANON ` + - 0x05 * - IS_BOOTED - :ref:`IPROTO_BALLOT_IS_BOOTED ` diff --git a/doc/reference/reference_lua/box_iproto/feature.rst b/doc/reference/reference_lua/box_iproto/feature.rst index da2f6ff90f..d1e1ff3c6d 100644 --- a/doc/reference/reference_lua/box_iproto/feature.rst +++ b/doc/reference/reference_lua/box_iproto/feature.rst @@ -5,53 +5,53 @@ box.iproto.feature .. module:: box.iproto - .. data:: feature +.. data:: feature - The ``box.iproto.feature`` namespace contains the IPROTO protocol features supported by the server. - Each feature is mapped to its corresponding code. - Learn more: :ref:`IPROTO_FEATURES `. + The ``box.iproto.feature`` namespace contains the IPROTO protocol features supported by the server. + Each feature is mapped to its corresponding code. + Learn more: :ref:`IPROTO_FEATURES `. - The features in the namespace are written + The features in the namespace are written - * in the lower case - * without the ``IPROTO_FEATURE_`` prefix + * in the lower case + * without the ``IPROTO_FEATURE_`` prefix - Available features: + Available features: - .. list-table:: - :header-rows: 1 - :widths: 40 20 40 + .. list-table:: + :header-rows: 1 + :widths: 40 40 20 - * - Exported feature - - IPROTO protocol feature - - Code - - Description + * - Exported feature + - IPROTO protocol feature + - Code + - Description - * - streams - - :ref:`IPROTO_FEATURE_STREAMS ` - - 0 - - :ref:`Stream ` support + * - streams + - :ref:`IPROTO_FEATURE_STREAMS ` + - 0 + - :ref:`Stream ` support - * - transactions - - :ref:`IPROTO_SYNC ` - - 1 - - Transaction support + * - transactions + - :ref:`IPROTO_SYNC ` + - 1 + - Transaction support - * - error_extension - - :ref:`IPROTO_FEATURE_ERROR_EXTENSION ` - - 2 - - :ref:`MP_ERROR ` MsgPack extension support + * - error_extension + - :ref:`IPROTO_FEATURE_ERROR_EXTENSION ` + - 2 + - :ref:`MP_ERROR ` MsgPack extension support - * - watchers - - :ref:`IPROTO_FEATURE_WATCHERS ` - - 3 - - Remote watchers support ( see :ref:`IPROTO_WATCH `, - :ref:`IPROTO_UNWATCH `, and :ref:`IPROTO_EVENT `) + * - watchers + - :ref:`IPROTO_FEATURE_WATCHERS ` + - 3 + - Remote watchers support ( see :ref:`IPROTO_WATCH `, + :ref:`IPROTO_UNWATCH `, and :ref:`IPROTO_EVENT `) - * - pagination - - :ref:`IPROTO_FEATURE_PAGINATION ` - - 4 - - Pagination support + * - pagination + - :ref:`IPROTO_FEATURE_PAGINATION ` + - 4 + - Pagination support **Example** diff --git a/doc/reference/reference_lua/box_iproto/flag.rst b/doc/reference/reference_lua/box_iproto/flag.rst index 1aa3854a83..379fd2d5f1 100644 --- a/doc/reference/reference_lua/box_iproto/flag.rst +++ b/doc/reference/reference_lua/box_iproto/flag.rst @@ -5,16 +5,16 @@ box.iproto.flag .. module:: box.iproto - .. data:: flag +.. data:: flag - The ``box.iproto.flag`` namespace contains the flags from the ``IPROTO_FLAGS`` key. - Learn more: :ref:`IPROTO_FLAGS key `. + The ``box.iproto.flag`` namespace contains the flags from the ``IPROTO_FLAGS`` key. + Learn more: :ref:`IPROTO_FLAGS key `. Available flags: .. list-table:: :header-rows: 1 - :widths: 40 20 40 + :widths: 40 40 20 * - Exported flag - IPROTO flag name diff --git a/doc/reference/reference_lua/box_iproto/key.rst b/doc/reference/reference_lua/box_iproto/key.rst index 543f85a698..31209a2eb5 100644 --- a/doc/reference/reference_lua/box_iproto/key.rst +++ b/doc/reference/reference_lua/box_iproto/key.rst @@ -5,244 +5,243 @@ box.iproto.key .. module:: box.iproto - .. data:: key +.. data:: key - The ``box.iproto.key`` namespace contains the request keys. - To + The ``box.iproto.key`` namespace contains the request keys. - Available keys: + Available keys: - .. list-table:: - :header-rows: 1 - :widths: 40 20 40 + .. list-table:: + :header-rows: 1 + :widths: 40 40 20 - * - Exported flag - - IPROTO flag name - - Code + * - Exported flag + - IPROTO flag name + - Code - * - REQUEST_TYPE - - :ref:`IPROTO_REQUEST_TYPE ` - - 0x00 + * - REQUEST_TYPE + - :ref:`IPROTO_REQUEST_TYPE ` + - 0x00 - * - SYNC - - :ref:`IPROTO_SYNC ` - - 0x01 + * - SYNC + - :ref:`IPROTO_SYNC ` + - 0x01 - * - REPLICA_ID - - :ref:`IPROTO_REPLICA_ID ` - - 0x02 + * - REPLICA_ID + - :ref:`IPROTO_REPLICA_ID ` + - 0x02 - * - LSN - - :ref:`IPROTO_LSN ` - - 0x03 + * - LSN + - :ref:`IPROTO_LSN ` + - 0x03 - * - TIMESTAMP - - :ref:`IPROTO_TIMESTAMP ` - - 0x04 + * - TIMESTAMP + - :ref:`IPROTO_TIMESTAMP ` + - 0x04 - * - SCHEMA_VERSION - - :ref:`IPROTO_SCHEMA_VERSION ` - - 0x05 + * - SCHEMA_VERSION + - :ref:`IPROTO_SCHEMA_VERSION ` + - 0x05 - * - SERVER_VERSION - - :ref:`IPROTO_SERVER_VERSION ` - - 0x06 + * - SERVER_VERSION + - :ref:`IPROTO_SERVER_VERSION ` + - 0x06 - * - GROUP_ID - - IPROTO_GROUP_ID - - 0x07 + * - GROUP_ID + - IPROTO_GROUP_ID + - 0x07 - * - TSN - - :ref:`IPROTO_TSN ` - - 0x08 + * - TSN + - :ref:`IPROTO_TSN ` + - 0x08 - * - FLAGS - - :ref:`IPROTO_FLAGS ` - - 0x09 + * - FLAGS + - :ref:`IPROTO_FLAGS ` + - 0x09 - * - STREAM_ID - - :ref:`IPROTO_STREAM_ID ` - - 0x0a + * - STREAM_ID + - :ref:`IPROTO_STREAM_ID ` + - 0x0a - * - SPACE_ID - - :ref:`IPROTO_SPACE_ID ` - - 0x10 + * - SPACE_ID + - :ref:`IPROTO_SPACE_ID ` + - 0x10 - * - INDEX_ID - - :ref:`IPROTO_INDEX_ID ` - - 0x11 + * - INDEX_ID + - :ref:`IPROTO_INDEX_ID ` + - 0x11 - * - LIMIT - - :ref:`IPROTO_LIMIT ` - - 0x12 + * - LIMIT + - :ref:`IPROTO_LIMIT ` + - 0x12 - * - OFFSET - - :ref:`IPROTO_OFFSET ` - - 0x13 + * - OFFSET + - :ref:`IPROTO_OFFSET ` + - 0x13 - * - ITERATOR - - :ref:`IPROTO_ITERATOR ` - - 0x14 + * - ITERATOR + - :ref:`IPROTO_ITERATOR ` + - 0x14 - * - INDEX_BASE - - :ref:`IPROTO_INDEX_BASE ` - - 0x15 + * - INDEX_BASE + - :ref:`IPROTO_INDEX_BASE ` + - 0x15 - * - FETCH_POSITION - - :ref:`IPROTO_FETCH_POSITION ` - - 0x1f + * - FETCH_POSITION + - :ref:`IPROTO_FETCH_POSITION ` + - 0x1f - * - KEY - - :ref:`IPROTO_KEY ` - - 0x20 + * - KEY + - :ref:`IPROTO_KEY ` + - 0x20 - * - TUPLE - - :ref:`IPROTO_TUPLE ` - - 0x21 + * - TUPLE + - :ref:`IPROTO_TUPLE ` + - 0x21 - * - FUNCTION_NAME - - :ref:`IPROTO_FUNCTION_NAME ` - - 0x22 + * - FUNCTION_NAME + - :ref:`IPROTO_FUNCTION_NAME ` + - 0x22 - * - USER_NAME - - :ref:`IPROTO_USER_NAME ` - - 0x23 + * - USER_NAME + - :ref:`IPROTO_USER_NAME ` + - 0x23 - * - INSTANCE_UUID - - :ref:`IPROTO_INSTANCE_UUID ` - - 0x24 + * - INSTANCE_UUID + - :ref:`IPROTO_INSTANCE_UUID ` + - 0x24 - * - REPLICASET_UUID - - :ref:`IPROTO_REPLICASET_UUID ` - - 0x25 + * - REPLICASET_UUID + - :ref:`IPROTO_REPLICASET_UUID ` + - 0x25 - * - VCLOCK - - :ref:`IPROTO_VCLOCK ` - - 0x26 + * - VCLOCK + - :ref:`IPROTO_VCLOCK ` + - 0x26 - * - EXPR - - :ref:`IPROTO_EXPR ` - - 0x27 + * - EXPR + - :ref:`IPROTO_EXPR ` + - 0x27 - * - OPS - - :ref:`IPROTO_OPS ` - - 0x28 + * - OPS + - :ref:`IPROTO_OPS ` + - 0x28 - * - BALLOT - - :ref:`IPROTO_BALLOT ` - - 0x29 + * - BALLOT + - :ref:`IPROTO_BALLOT ` + - 0x29 - * - TUPLE_META - - IPROTO_TUPLE_META - - 0x2a + * - TUPLE_META + - IPROTO_TUPLE_META + - 0x2a - * - OPTIONS - - :ref:`IPROTO_OPTIONS ` - - 0x2b + * - OPTIONS + - :ref:`IPROTO_OPTIONS ` + - 0x2b - * - OLD_TUPLE - - IPROTO_OLD_TUPLE - - 0x2c + * - OLD_TUPLE + - IPROTO_OLD_TUPLE + - 0x2c - * - NEW_TUPLE - - IPROTO_NEW_TUPLE - - 0x2d + * - NEW_TUPLE + - IPROTO_NEW_TUPLE + - 0x2d - * - AFTER_POSITION - - :ref:`IPROTO_AFTER_POSITION ` - - 0x2e + * - AFTER_POSITION + - :ref:`IPROTO_AFTER_POSITION ` + - 0x2e - * - AFTER_TUPLE - - :ref:`IPROTO_AFTER_TUPLE ` - - 0x2f + * - AFTER_TUPLE + - :ref:`IPROTO_AFTER_TUPLE ` + - 0x2f - * - DATA - - :ref:`IPROTO_DATA ` - - 0x30 + * - DATA + - :ref:`IPROTO_DATA ` + - 0x30 - * - ERROR_24 - - :ref:`IPROTO_ERROR_24 ` - - 0x31 + * - ERROR_24 + - :ref:`IPROTO_ERROR_24 ` + - 0x31 - * - METADATA - - :ref:`IPROTO_METADATA ` - - 0x32 + * - METADATA + - :ref:`IPROTO_METADATA ` + - 0x32 - * - BIND_METADATA - - :ref:`IPROTO_BIND_METADATA ` - - 0x33 + * - BIND_METADATA + - :ref:`IPROTO_BIND_METADATA ` + - 0x33 - * - BIND_COUNT - - :ref:`IPROTO_BIND_COUNT ` - - 0x34 + * - BIND_COUNT + - :ref:`IPROTO_BIND_COUNT ` + - 0x34 - * - POSITION - - :ref:`IPROTO_POSITION ` - - 0x35 + * - POSITION + - :ref:`IPROTO_POSITION ` + - 0x35 - * - SQL_TEXT - - :ref:`IPROTO_SQL_TEXT ` - - 0x40 + * - SQL_TEXT + - :ref:`IPROTO_SQL_TEXT ` + - 0x40 - * - SQL_BIND - - :ref:`IPROTO_SQL_BIND ` - - 0x41 + * - SQL_BIND + - :ref:`IPROTO_SQL_BIND ` + - 0x41 - * - SQL_INFO - - :ref:`IPROTO_SQL_INFO ` - - 0x42 + * - SQL_INFO + - :ref:`IPROTO_SQL_INFO ` + - 0x42 - * - STMT_ID - - :ref:`IPROTO_STMT_ID ` - - 0x43 + * - STMT_ID + - :ref:`IPROTO_STMT_ID ` + - 0x43 - * - REPLICA_ANON - - :ref:`IPROTO_REPLICA_ANON ` - - 0x50 + * - REPLICA_ANON + - :ref:`IPROTO_REPLICA_ANON ` + - 0x50 - * - ID_FILTER - - :ref:`IPROTO_ID_FILTER ` - - 0x51 + * - ID_FILTER + - :ref:`IPROTO_ID_FILTER ` + - 0x51 - * - ERROR - - :ref:`IPROTO_ERROR ` - - 0x52 + * - ERROR + - :ref:`IPROTO_ERROR ` + - 0x52 - * - TERM - - :ref:`IPROTO_TERM ` - - 0x53 + * - TERM + - :ref:`IPROTO_TERM ` + - 0x53 - * - VERSION - - :ref:`IPROTO_VERSION ` - - 0x54 + * - VERSION + - :ref:`IPROTO_VERSION ` + - 0x54 - * - FEATURES - - :ref:`IPROTO_FEATURES ` - - 0x55 + * - FEATURES + - :ref:`IPROTO_FEATURES ` + - 0x55 - * - TIMEOUT - - :ref:`IPROTO_TIMEOUT ` - - 0x56 + * - TIMEOUT + - :ref:`IPROTO_TIMEOUT ` + - 0x56 - * - EVENT_KEY - - :ref:`IPROTO_EVENT_KEY ` - - 0x57 + * - EVENT_KEY + - :ref:`IPROTO_EVENT_KEY ` + - 0x57 - * - EVENT_DATA - - :ref:`IPROTO_EVENT_DATA ` - - 0x58 + * - EVENT_DATA + - :ref:`IPROTO_EVENT_DATA ` + - 0x58 - * - TXN_ISOLATION - - :ref:`IPROTO_TXN_ISOLATION ` - - 0x59 + * - TXN_ISOLATION + - :ref:`IPROTO_TXN_ISOLATION ` + - 0x59 - * - VCLOCK_SYNC - - :ref:`IPROTO_VCLOCK_SYNC ` - - 0x5a + * - VCLOCK_SYNC + - :ref:`IPROTO_VCLOCK_SYNC ` + - 0x5a - * - AUTH_TYPE - - :ref:`IPROTO_AUTH_TYPE ` - - 0x5b + * - AUTH_TYPE + - :ref:`IPROTO_AUTH_TYPE ` + - 0x5b **Example** diff --git a/doc/reference/reference_lua/box_iproto/metadata.rst b/doc/reference/reference_lua/box_iproto/metadata.rst index 6d3fb801b3..f515a0a6aa 100644 --- a/doc/reference/reference_lua/box_iproto/metadata.rst +++ b/doc/reference/reference_lua/box_iproto/metadata.rst @@ -5,16 +5,16 @@ box.iproto.metadata_key .. module:: box.iproto - .. data:: metadata_key +.. data:: metadata_key - The ``box.iproto.metadata_key`` namespace contains the ``IPROTO_FILED_*`` keys, which are nested in the - :ref:`IPROTO_METADATA ` key. + The ``box.iproto.metadata_key`` namespace contains the ``IPROTO_FILED_*`` keys, which are nested in the + :ref:`IPROTO_METADATA ` key. Available keys: .. list-table:: :header-rows: 1 - :widths: 40 20 40 + :widths: 40 40 20 * - Exported constant - IPROTO constant name diff --git a/doc/reference/reference_lua/box_iproto/override.rst b/doc/reference/reference_lua/box_iproto/override.rst index 5b55a4bdd2..a3519c8836 100644 --- a/doc/reference/reference_lua/box_iproto/override.rst +++ b/doc/reference/reference_lua/box_iproto/override.rst @@ -18,7 +18,3 @@ box.iproto.override() **Example:** - .. code-block:: tarantoolsession - - tarantool> - diff --git a/doc/reference/reference_lua/box_iproto/protocol_features.rst b/doc/reference/reference_lua/box_iproto/protocol_features.rst index c2fc87291b..d49e8e92bd 100644 --- a/doc/reference/reference_lua/box_iproto/protocol_features.rst +++ b/doc/reference/reference_lua/box_iproto/protocol_features.rst @@ -5,11 +5,11 @@ box.iproto.protocol_version .. module:: box.iproto - .. data:: protocol_version +.. data:: protocol_version - The set of IPROTO protocol features supported by the server. - Learn more: `src/box/iproto_features.h `__ - and `iproto_features_resolve() `__). + The set of IPROTO protocol features supported by the server. + Learn more: `src/box/iproto_features.h `__ + and `iproto_features_resolve() `__). **Example** diff --git a/doc/reference/reference_lua/box_iproto/protocol_version.rst b/doc/reference/reference_lua/box_iproto/protocol_version.rst index 76cbeaefa3..fa55869221 100644 --- a/doc/reference/reference_lua/box_iproto/protocol_version.rst +++ b/doc/reference/reference_lua/box_iproto/protocol_version.rst @@ -5,10 +5,11 @@ box.iproto.protocol_version .. module:: box.iproto - .. data:: protocol_version +.. data:: protocol_version + + Current IPROTO protocol version of the server. + Learn more: :ref:`IPROTO_ID `. - Current IPROTO protocol version of the server. - Learn more: :ref:`IPROTO_ID `. **Example** diff --git a/doc/reference/reference_lua/box_iproto/raft.rst b/doc/reference/reference_lua/box_iproto/raft.rst index ab1139356e..f55d72d319 100644 --- a/doc/reference/reference_lua/box_iproto/raft.rst +++ b/doc/reference/reference_lua/box_iproto/raft.rst @@ -5,16 +5,16 @@ box.iproto.raft .. module:: box.iproto - .. data:: raft_key +.. data:: raft_key - The ``box.iproto.raft_key`` namespace contains the keys from the ``IPROTO_RAFT_*`` requests. - Learn more: :ref:`Synchronous replication keys `. + The ``box.iproto.raft_key`` namespace contains the keys from the ``IPROTO_RAFT_*`` requests. + Learn more: :ref:`Synchronous replication keys `. Available keys: .. list-table:: :header-rows: 1 - :widths: 40 20 40 + :widths: 40 40 20 * - Exported constant - IPROTO constant name diff --git a/doc/reference/reference_lua/box_iproto/request_type.rst b/doc/reference/reference_lua/box_iproto/request_type.rst index 4563286321..8cc4334a8a 100644 --- a/doc/reference/reference_lua/box_iproto/request_type.rst +++ b/doc/reference/reference_lua/box_iproto/request_type.rst @@ -5,16 +5,16 @@ box.iproto.type .. module:: box.iproto - .. data:: type +.. data:: type - The ``box.iproto.type`` namespace contains all available request types. - Learn more about the requests: :ref:`Client-server requests and responses `. + The ``box.iproto.type`` namespace contains all available request types. + Learn more about the requests: :ref:`Client-server requests and responses `. Available types: .. list-table:: :header-rows: 1 - :widths: 40 20 40 + :widths: 40 40 20 * - Exported constant - IPROTO constant name diff --git a/doc/reference/reference_lua/box_iproto/send.rst b/doc/reference/reference_lua/box_iproto/send.rst index 9fac68a264..b518e5134e 100644 --- a/doc/reference/reference_lua/box_iproto/send.rst +++ b/doc/reference/reference_lua/box_iproto/send.rst @@ -21,12 +21,6 @@ box.iproto.send() **Possible errors:** - * Index is not of type 'TREE'. - * :errcode:`ER_TRANSACTION_CONFLICT` if a transaction conflict is detected in the - :ref:`MVCC transaction mode `. - - **Complexity factors:** Index size, Index type. - **Example:** From 089471aad048dd27e378091f21f8ac2ca1921772 Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Tue, 31 Oct 2023 15:56:25 +0300 Subject: [PATCH 3/4] Apply suggestions from code review --- .../iproto/iproto_constants_export_test.lua | 192 -------------- doc/dev_guide/internals/box_protocol.rst | 8 + doc/dev_guide/internals/iproto/format.rst | 2 +- doc/dev_guide/internals/iproto/keys.rst | 13 - doc/dev_guide/internals/iproto/requests.rst | 16 ++ doc/dev_guide/reference_capi/box.rst | 145 +++++++++- doc/dev_guide/reference_capi/error.rst | 4 + doc/reference/reference_lua/box_iproto.rst | 70 +++-- .../reference_lua/box_iproto/ballot.rst | 62 +---- .../reference_lua/box_iproto/feature.rst | 59 +---- .../reference_lua/box_iproto/flag.rst | 43 +-- .../reference_lua/box_iproto/key.rst | 250 +----------------- .../reference_lua/box_iproto/metadata.rst | 55 +--- .../reference_lua/box_iproto/override.rst | 71 ++++- .../box_iproto/protocol_features.rst | 29 +- .../box_iproto/protocol_version.rst | 10 +- .../reference_lua/box_iproto/raft.rst | 54 +--- .../reference_lua/box_iproto/request_type.rst | 173 +----------- .../reference_lua/box_iproto/send.rst | 46 +++- 19 files changed, 423 insertions(+), 879 deletions(-) delete mode 100644 doc/code_snippets/test/iproto/iproto_constants_export_test.lua diff --git a/doc/code_snippets/test/iproto/iproto_constants_export_test.lua b/doc/code_snippets/test/iproto/iproto_constants_export_test.lua deleted file mode 100644 index cfeed3d7c5..0000000000 --- a/doc/code_snippets/test/iproto/iproto_constants_export_test.lua +++ /dev/null @@ -1,192 +0,0 @@ -local fio = require('fio') -local server = require('luatest.server') -local t = require('luatest') -local g = t.group() -g.before_each(function(cg) - cg.server = server:new { - box_cfg = {}, - workdir = fio.cwd() .. '/tmp' - } - cg.server:start() -end) - -g.after_each(function(cg) - cg.server:stop() - cg.server:drop() -end) - -local reference_table = { - -- `IPROTO_FLAGS` bitfield constants enumeration. - flag = { - COMMIT = 0x01, - WAIT_SYNC = 0x02, - WAIT_ACK = 0x04, - }, - - -- `iproto_key` enumeration. - key = { - REQUEST_TYPE = 0x00, - SYNC = 0x01, - REPLICA_ID = 0x02, - LSN = 0x03, - TIMESTAMP = 0x04, - SCHEMA_VERSION = 0x05, - SERVER_VERSION = 0x06, - GROUP_ID = 0x07, - TSN = 0x08, - FLAGS = 0x09, - STREAM_ID = 0x0a, - SPACE_ID = 0x10, - INDEX_ID = 0x11, - LIMIT = 0x12, - OFFSET = 0x13, - ITERATOR = 0x14, - INDEX_BASE = 0x15, - FETCH_POSITION = 0x1f, - KEY = 0x20, - TUPLE = 0x21, - FUNCTION_NAME = 0x22, - USER_NAME = 0x23, - INSTANCE_UUID = 0x24, - REPLICASET_UUID = 0x25, - VCLOCK = 0x26, - EXPR = 0x27, - OPS = 0x28, - BALLOT = 0x29, - TUPLE_META = 0x2a, - OPTIONS = 0x2b, - OLD_TUPLE = 0x2c, - NEW_TUPLE = 0x2d, - AFTER_POSITION = 0x2e, - AFTER_TUPLE = 0x2f, - DATA = 0x30, - ERROR_24 = 0x31, - METADATA = 0x32, - BIND_METADATA = 0x33, - BIND_COUNT = 0x34, - POSITION = 0x35, - SQL_TEXT = 0x40, - SQL_BIND = 0x41, - SQL_INFO = 0x42, - STMT_ID = 0x43, - REPLICA_ANON = 0x50, - ID_FILTER = 0x51, - ERROR = 0x52, - TERM = 0x53, - VERSION = 0x54, - FEATURES = 0x55, - TIMEOUT = 0x56, - EVENT_KEY = 0x57, - EVENT_DATA = 0x58, - TXN_ISOLATION = 0x59, - VCLOCK_SYNC = 0x5a, - AUTH_TYPE = 0x5b, - }, - - -- `iproto_metadata_key` enumeration. - metadata_key = { - NAME = 0, - TYPE = 1, - COLL = 2, - IS_NULLABLE = 3, - IS_AUTOINCREMENT = 4, - SPAN = 5, - }, - - -- `iproto_ballot_key` enumeration. - ballot_key = { - IS_RO_CFG = 0x01, - VCLOCK = 0x02, - GC_VCLOCK = 0x03, - IS_RO = 0x04, - IS_ANON = 0x05, - IS_BOOTED = 0x06, - CAN_LEAD = 0x07, - BOOTSTRAP_LEADER_UUID = 0x08, - REGISTERED_REPLICA_UUIDS = 0x09, - }, - - -- `iproto_type` enumeration. - type = { - OK = 0, - SELECT = 1, - INSERT = 2, - REPLACE = 3, - UPDATE = 4, - DELETE = 5, - CALL_16 = 6, - AUTH = 7, - EVAL = 8, - UPSERT = 9, - CALL = 10, - EXECUTE = 11, - NOP = 12, - PREPARE = 13, - BEGIN = 14, - COMMIT = 15, - ROLLBACK = 16, - RAFT = 30, - RAFT_PROMOTE = 31, - RAFT_DEMOTE = 32, - RAFT_CONFIRM = 40, - RAFT_ROLLBACK = 41, - PING = 64, - JOIN = 65, - SUBSCRIBE = 66, - VOTE_DEPRECATED = 67, - VOTE = 68, - FETCH_SNAPSHOT = 69, - REGISTER = 70, - JOIN_META = 71, - JOIN_SNAPSHOT = 72, - ID = 73, - WATCH = 74, - UNWATCH = 75, - EVENT = 76, - CHUNK = 128, - TYPE_ERROR = bit.lshift(1, 15), - UNKNOWN = -1, - }, - - -- `iproto_raft_keys` enumeration - raft_key = { - TERM = 0, - VOTE = 1, - STATE = 2, - VCLOCK = 3, - LEADER_ID = 4, - IS_LEADER_SEEN = 5, - }, - - -- `IPROTO_CURRENT_VERSION` constant - protocol_version = 4, - - -- `feature_id` enumeration - protocol_features = { - streams = true, - transactions = true, - error_extension = true, - watchers = true, - pagination = true, - }, - feature = { - streams = 0, - transactions = 1, - error_extension = 2, - watchers = 3, - pagination = 4, - }, -} - --- Checks that IPROTO constants and features are exported correctly. -g.test_iproto_constants_export = function(cg) - cg.server:exec(function(reference_table) - for k, v in pairs(box.iproto) do - local v_type = type(v) - if v_type ~= 'function' and v_type ~= 'thread' and - v_type ~= 'userdata' then - t.assert_equals(v, reference_table[k]) - end - end - end, {reference_table}) -end diff --git a/doc/dev_guide/internals/box_protocol.rst b/doc/dev_guide/internals/box_protocol.rst index a159cc1d40..6df35f1208 100644 --- a/doc/dev_guide/internals/box_protocol.rst +++ b/doc/dev_guide/internals/box_protocol.rst @@ -20,6 +20,14 @@ 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 `, you can use the :ref:`box.iproto ` submodule to access + IPROTO constants and features from Lua. The submodule enables to :ref:`send arbitrary IPROTO packets ` + over the session's socket and :ref:`override the behavior ` for all IPROTO + request types. Also, :ref:`IPROTO_UNKNOWN ` constant is introduced. The constant is used for the + :ref:`box.iproto.override() ` API, which allows setting a handler for incoming requests with an unknown type. + .. toctree:: :maxdepth: 1 diff --git a/doc/dev_guide/internals/iproto/format.rst b/doc/dev_guide/internals/iproto/format.rst index 4251793798..e1882e513e 100644 --- a/doc/dev_guide/internals/iproto/format.rst +++ b/doc/dev_guide/internals/iproto/format.rst @@ -62,7 +62,7 @@ function ``netbox_decode_data``. For example, in a successful response to ``box.space:select()``, the IPROTO_REQUEST_TYPE value is 0 = ``IPROTO_OK`` and the -array have all the tuples of the result. +array has all the tuples of the result. Read the source code file `net_box.c `__ where the function ``decode_metadata_optional`` is an example of how Tarantool diff --git a/doc/dev_guide/internals/iproto/keys.rst b/doc/dev_guide/internals/iproto/keys.rst index 656efe6f36..27f9f88cd3 100644 --- a/doc/dev_guide/internals/iproto/keys.rst +++ b/doc/dev_guide/internals/iproto/keys.rst @@ -52,10 +52,6 @@ General - 0x00 |br| MP_UINT - Request type or response type - * - :ref:`IPROTO_UNKNOWN ` - - -1 |br| MP_UINT - - Unknown request or response type - * - :ref:`IPROTO_ERROR ` - 0x52 |br| :ref:`MP_ERROR ` - Error response @@ -598,15 +594,6 @@ See requests and responses for :ref:`client-server communication `, :ref:`streams and interactive transactions `. -.. _internals-iproto-keys-unknown: - -IPROTO_UNKNOWN -~~~~~~~~~~~~~~ - -Code: -1. - -Unknown request or response type. - .. _internals-iproto-keys-error: IPROTO_ERROR diff --git a/doc/dev_guide/internals/iproto/requests.rst b/doc/dev_guide/internals/iproto/requests.rst index c0d68bdcb7..b09cb93fa1 100644 --- a/doc/dev_guide/internals/iproto/requests.rst +++ b/doc/dev_guide/internals/iproto/requests.rst @@ -38,6 +38,10 @@ Overview - 0x8XXX |br| MP_INT - Error response + * - :ref:`IPROTO_UNKNOWN ` + - -1 |br| MP_UINT + - Unknown request type + * - :ref:`IPROTO_SELECT ` - 0x01 - :ref:`Select ` request @@ -126,6 +130,18 @@ constants for return codes. To learn more about error responses, check the section :ref:`Request and response format `. +.. _internals-iproto-unknown: + +IPROTO_UNKNOWN +~~~~~~~~~~~~~~ + +Since :doc:`2.11.0 `. + +Code: -1. + +Unknown request type. The constant is used to override the handler of unknown IPROTO request types. +Learn more: :ref:`box.iproto.override() ` and :ref:`box_box_iproto_override `. + .. _box_protocol-select: IPROTO_SELECT diff --git a/doc/dev_guide/reference_capi/box.rst b/doc/dev_guide/reference_capi/box.rst index c3348acab6..b25a9d18e1 100644 --- a/doc/dev_guide/reference_capi/box.rst +++ b/doc/dev_guide/reference_capi/box.rst @@ -247,38 +247,163 @@ .. _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 `. Send an :ref:`IPROTO ` packet over the session's socket with the given MsgPack header - and body. NB: yields. + and body. + The function yields. + The function works for binary sessions only. For details, see :ref:`box.session.type() `. :param uint32_t sid: IPROTO session identifier (see :ref:`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 - :return: 1 if there is a failure + :return: -1 on error (check :ref:`box_error_last() `) :rtype: number See also :ref:`box.iproto.send() ` + **Possible errors:** + + * :errcode:`ER_SESSION_CLOSED` -- the session is closed. + * :errcode:`ER_NO_SUCH_SESSION` -- the session does not exist. + * :errcode:`ER_MEMORY_ISSUE` -- out of memory limit has been reached. + * :errcode:`ER_WRONG_SESSION_TYPE` -- the session type is not binary. + + For details, see `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 `. - 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. + + :param uint32_t request_type: IPROTO request type code (for example, ``IPROTO_SELECT``). + For details, check :ref:`Client-server requests and responses `. + + To override the handler of unknown request types, use the :ref:`IPROTO_UNKNOWN ` type code. + + :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 ` section. + + :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 ` 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: context passed to handler + :param void* ctx: a context passed to the ``handler`` and ``destroy`` callbacks :return: 0 on success :return: -1 on error (check :ref:`box_error_last() `) :rtype: number - See also :ref:`box.session.id() ` \ No newline at end of file + See also :ref:`box.iproto.override() ` + + **Possible errors:** + + If a Lua handler throws an exception, the behavior is similar to that of a remote procedure call. + The following errors are returned to the client over IPROTO (see `src/lua/utils.h `__): + + * :errcode:`ER_PROC_LUA` -- an exception is thrown from a Lua handler, diagnostic is not set. + * diagnostics from ``src/box/errcode.h`` -- an exception is thrown, diagnostic is set. + + For details, see `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 + (see :ref:`box_error_set() ` and :ref:`box_error_raise() `) + + * ``IPROTO_REQUEST_HANDLER_FALLBACK`` -- fallback to the default handler + +.. _box_box_iproto_override-destroy: + + **Handler destructor function** + + The destructor is called when the handler is reset. + 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) diff --git a/doc/dev_guide/reference_capi/error.rst b/doc/dev_guide/reference_capi/error.rst index 7e73dbb830..003413c198 100644 --- a/doc/dev_guide/reference_capi/error.rst +++ b/doc/dev_guide/reference_capi/error.rst @@ -64,6 +64,8 @@ Clear the last error. +.. _c_api-error-box_error_set: + .. c:function:: int box_error_set(const char *file, unsigned line, uint32_t code, const char *format, ...) Set the last error. @@ -76,6 +78,8 @@ See also: IPROTO :ref:`error code` +.. _c_api-error-box_error_raise: + .. c:macro:: box_error_raise(code, format, ...) A backward-compatible API define. diff --git a/doc/reference/reference_lua/box_iproto.rst b/doc/reference/reference_lua/box_iproto.rst index c716ddf989..8195beae02 100644 --- a/doc/reference/reference_lua/box_iproto.rst +++ b/doc/reference/reference_lua/box_iproto.rst @@ -6,22 +6,22 @@ Submodule box.iproto Since :doc:`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 ` functionality from the Lua libraries. +It allows you to extend the :ref:`IPROTO ` functionality from Lua. With this submodule, you can: -* parse the unknown IPROTO requests -* send arbitrary IPROTO packets -* override the behavior of the existing request types in binary protocol +* :ref:`parse the unknown IPROTO requests types ` +* :ref:`send arbitrary IPROTO packets ` +* :ref:`override the behavior ` of the existing and unknown request types in the binary protocol -To make this possible, the submodule exports all IPROTO :ref:`constants ` and features to Lua. +The submodule exports all IPROTO :ref:`constants ` and :ref:`features ` to Lua. .. _box_iproto-constants: IPROTO constants ---------------- -The IPROTO constants in the ``box.iproto`` namespace are written in the upper case without the ``IPROTO_`` prefix. -The constants are divided into several types: +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 ` (:ref:`IPROTO_SYNC `, :ref:`IPROTO_REQUEST_TYPE `) * :ref:`request type ` (:ref:`IPROTO_OK `) @@ -30,7 +30,7 @@ The constants are divided into several types: * :ref:`metadata key ` (:ref:`IPROTO_FIELD_IS_NULLABLE `) * :ref:`RAFT key ` (:ref:`IPROTO_TERM `) -Each type 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 -- ... @@ -59,6 +59,39 @@ The submodule exports: * the set of IPROTO protocol features supported by the server (:ref:`box.iproto.protocol_features `) * IPROTO protocol features with the corresponding code (:ref:`box.iproto.feature `) +**Example** + +The example converts the feature names from ``box.iproto.protocol_features`` set into codes: + +.. code-block:: lua + + -- Features supported by the server + box.iproto.protocol_features = { + streams = true, + 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, 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 `, any unknown request raised an error. +Since :doc:`2.11.0 `, a new request type is introduced -- :ref:`IPROTO_UNKNOWN `. +This type is used to override the handlers of the unknown IPROTO request types. For details, see +:ref:`box.iproto.override() ` and :ref:`box_iproto_override ` functions. + .. _box_iproto-reference: API reference @@ -72,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 ` key * - :doc:`./box_iproto/ballot` @@ -94,7 +127,7 @@ The table lists all available functions and data of the submodule: - Keys nested in the :ref:`IPROTO_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 @@ -105,10 +138,10 @@ The table lists all available functions and data of the submodule: * - :doc:`./box_iproto/feature` - IPROTO protocol :ref:`features ` - * - :doc:`./box_iproto/override` - - Set the IPROTO request handler callbacks + * - :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 @@ -116,7 +149,6 @@ The table lists all available functions and data of the submodule: :hidden: box_iproto/key - box_iproto/request_key box_iproto/request_type box_iproto/flag box_iproto/ballot diff --git a/doc/reference/reference_lua/box_iproto/ballot.rst b/doc/reference/reference_lua/box_iproto/ballot.rst index 35095b57aa..a9a6bb7dfd 100644 --- a/doc/reference/reference_lua/box_iproto/ballot.rst +++ b/doc/reference/reference_lua/box_iproto/ballot.rst @@ -10,58 +10,16 @@ box.iproto.ballot_key The ``box.iproto.ballot_key`` namespace contains the keys from the :ref:`IPROTO_BALLOT ` requests. Learn more: :ref:`IPROTO_BALLOT keys `. - Available keys: + **Example** - .. list-table:: - :header-rows: 1 - :widths: 40 40 20 + .. code-block:: lua - * - Exported constant - - IPROTO constant name - - Code + tarantool> box.iproto.ballot_key.IS_RO_CFG + --- + - 1 + ... + tarantool> box.iproto.ballot_key.VCLOCK + --- + - 2 + ... - * - IS_RO_CFG - - :ref:`IPROTO_BALLOT_IS_RO_CFG ` - - 0x01 - - * - VCLOCK - - :ref:`IPROTO_BALLOT_VCLOCK ` - - 0x02 - - * - GC_VCLOCK - - :ref:`IPROTO_BALLOT_GC_VCLOCK ` - - 0x03 - - * - IS_RO - - :ref:`IPROTO_BALLOT_IS_RO ` - - 0x04 - - * - IS_ANON - - :ref:`IPROTO_BALLOT_IS_ANON ` - - 0x05 - - * - IS_BOOTED - - :ref:`IPROTO_BALLOT_IS_BOOTED ` - - 0x06 - - * - CAN_LEAD - - :ref:`IPROTO_BALLOT_CAN_LEAD ` - - 0x07 - - * - BOOTSTRAP_LEADER_UUID - - :ref:`IPROTO_BALLOT_BOOTSTRAP_LEADER_UUID ` - - 0x08 - - * - REGISTERED_REPLICA_UUIDS - - :ref:`IPROTO_BALLOT_REGISTERED_REPLICA_UUIDS ` - - 0x09 - - -**Example** - -.. code-block:: lua - - box.iproto.ballot_key.IS_RO_CFG = 0x01 - -- ... - box.iproto.ballot_key.VCLOCK = 0x02 - -- ... diff --git a/doc/reference/reference_lua/box_iproto/feature.rst b/doc/reference/reference_lua/box_iproto/feature.rst index d1e1ff3c6d..938f3ae891 100644 --- a/doc/reference/reference_lua/box_iproto/feature.rst +++ b/doc/reference/reference_lua/box_iproto/feature.rst @@ -7,59 +7,24 @@ box.iproto.feature .. data:: feature - The ``box.iproto.feature`` namespace contains the IPROTO protocol features supported by the server. + The ``box.iproto.feature`` namespace contains the IPROTO protocol features that are supported by the server. Each feature is mapped to its corresponding code. Learn more: :ref:`IPROTO_FEATURES `. The features in the namespace are written - * in the lower case + * in lowercase letters * without the ``IPROTO_FEATURE_`` prefix - Available features: + **Example** - .. list-table:: - :header-rows: 1 - :widths: 40 40 20 + .. code-block:: lua - * - Exported feature - - IPROTO protocol feature - - Code - - Description - - * - streams - - :ref:`IPROTO_FEATURE_STREAMS ` - - 0 - - :ref:`Stream ` support - - * - transactions - - :ref:`IPROTO_SYNC ` - - 1 - - Transaction support - - * - error_extension - - :ref:`IPROTO_FEATURE_ERROR_EXTENSION ` - - 2 - - :ref:`MP_ERROR ` MsgPack extension support - - * - watchers - - :ref:`IPROTO_FEATURE_WATCHERS ` - - 3 - - Remote watchers support ( see :ref:`IPROTO_WATCH `, - :ref:`IPROTO_UNWATCH `, and :ref:`IPROTO_EVENT `) - - * - pagination - - :ref:`IPROTO_FEATURE_PAGINATION ` - - 4 - - Pagination support - - -**Example** - -.. code-block:: lua - - box.iproto.feature.streams = 0 - box.iproto.feature.transactions = 1 - box.iproto.feature.error_extension = 2 - box.iproto.feature.watchers = 3 - box.iproto.feature.pagination = 4 + tarantool> box.iproto.feature.streams + --- + - 0 + ... + tarantool> box.iproto.feature.transactions + --- + - 1 + ... diff --git a/doc/reference/reference_lua/box_iproto/flag.rst b/doc/reference/reference_lua/box_iproto/flag.rst index 379fd2d5f1..13d393bcf1 100644 --- a/doc/reference/reference_lua/box_iproto/flag.rst +++ b/doc/reference/reference_lua/box_iproto/flag.rst @@ -10,34 +10,15 @@ box.iproto.flag The ``box.iproto.flag`` namespace contains the flags from the ``IPROTO_FLAGS`` key. Learn more: :ref:`IPROTO_FLAGS key `. - Available flags: - - .. list-table:: - :header-rows: 1 - :widths: 40 40 20 - - * - Exported flag - - IPROTO flag name - - Code - - * - COMMIT - - :ref:`IPROTO_FLAG_COMMIT ` - - 0x01 - - * - WAIT_SYNC - - :ref:`IPROTO_FLAG_WAIT_SYNC ` - - 0x02 - - * - WAIT_ACK - - :ref:`IPROTO_FLAG_WAIT_ACK ` - - 0x03 - - -**Example** - -.. code-block:: lua - - box.iproto.flag.COMMIT = 0x01 - -- ... - box.iproto.flag.WAIT_SYNC = 0x02 - -- ... \ No newline at end of file + **Example** + + .. code-block:: lua + + tarantool> box.iproto.flag.COMMIT + --- + - 1 + ... + tarantool> box.iproto.flag.WAIT_SYNC + --- + - 2 + ... diff --git a/doc/reference/reference_lua/box_iproto/key.rst b/doc/reference/reference_lua/box_iproto/key.rst index 31209a2eb5..2eb00233d2 100644 --- a/doc/reference/reference_lua/box_iproto/key.rst +++ b/doc/reference/reference_lua/box_iproto/key.rst @@ -1,4 +1,4 @@ -.. _reference_lua-box_iproto_key: +.. _reference_lua-box_iproto_key: box.iproto.key ============== @@ -7,245 +7,15 @@ box.iproto.key .. data:: key - The ``box.iproto.key`` namespace contains the request keys. + The ``box.iproto.key`` namespace contains all available request keys, except :ref:`raft `, + :ref:`metadata `, and :ref:`ballot ` keys. + Learn more: :ref:`Keys used in requests and responses `. - Available keys: + **Example** - .. list-table:: - :header-rows: 1 - :widths: 40 40 20 + .. code-block:: lua - * - Exported flag - - IPROTO flag name - - Code - - * - REQUEST_TYPE - - :ref:`IPROTO_REQUEST_TYPE ` - - 0x00 - - * - SYNC - - :ref:`IPROTO_SYNC ` - - 0x01 - - * - REPLICA_ID - - :ref:`IPROTO_REPLICA_ID ` - - 0x02 - - * - LSN - - :ref:`IPROTO_LSN ` - - 0x03 - - * - TIMESTAMP - - :ref:`IPROTO_TIMESTAMP ` - - 0x04 - - * - SCHEMA_VERSION - - :ref:`IPROTO_SCHEMA_VERSION ` - - 0x05 - - * - SERVER_VERSION - - :ref:`IPROTO_SERVER_VERSION ` - - 0x06 - - * - GROUP_ID - - IPROTO_GROUP_ID - - 0x07 - - * - TSN - - :ref:`IPROTO_TSN ` - - 0x08 - - * - FLAGS - - :ref:`IPROTO_FLAGS ` - - 0x09 - - * - STREAM_ID - - :ref:`IPROTO_STREAM_ID ` - - 0x0a - - * - SPACE_ID - - :ref:`IPROTO_SPACE_ID ` - - 0x10 - - * - INDEX_ID - - :ref:`IPROTO_INDEX_ID ` - - 0x11 - - * - LIMIT - - :ref:`IPROTO_LIMIT ` - - 0x12 - - * - OFFSET - - :ref:`IPROTO_OFFSET ` - - 0x13 - - * - ITERATOR - - :ref:`IPROTO_ITERATOR ` - - 0x14 - - * - INDEX_BASE - - :ref:`IPROTO_INDEX_BASE ` - - 0x15 - - * - FETCH_POSITION - - :ref:`IPROTO_FETCH_POSITION ` - - 0x1f - - * - KEY - - :ref:`IPROTO_KEY ` - - 0x20 - - * - TUPLE - - :ref:`IPROTO_TUPLE ` - - 0x21 - - * - FUNCTION_NAME - - :ref:`IPROTO_FUNCTION_NAME ` - - 0x22 - - * - USER_NAME - - :ref:`IPROTO_USER_NAME ` - - 0x23 - - * - INSTANCE_UUID - - :ref:`IPROTO_INSTANCE_UUID ` - - 0x24 - - * - REPLICASET_UUID - - :ref:`IPROTO_REPLICASET_UUID ` - - 0x25 - - * - VCLOCK - - :ref:`IPROTO_VCLOCK ` - - 0x26 - - * - EXPR - - :ref:`IPROTO_EXPR ` - - 0x27 - - * - OPS - - :ref:`IPROTO_OPS ` - - 0x28 - - * - BALLOT - - :ref:`IPROTO_BALLOT ` - - 0x29 - - * - TUPLE_META - - IPROTO_TUPLE_META - - 0x2a - - * - OPTIONS - - :ref:`IPROTO_OPTIONS ` - - 0x2b - - * - OLD_TUPLE - - IPROTO_OLD_TUPLE - - 0x2c - - * - NEW_TUPLE - - IPROTO_NEW_TUPLE - - 0x2d - - * - AFTER_POSITION - - :ref:`IPROTO_AFTER_POSITION ` - - 0x2e - - * - AFTER_TUPLE - - :ref:`IPROTO_AFTER_TUPLE ` - - 0x2f - - * - DATA - - :ref:`IPROTO_DATA ` - - 0x30 - - * - ERROR_24 - - :ref:`IPROTO_ERROR_24 ` - - 0x31 - - * - METADATA - - :ref:`IPROTO_METADATA ` - - 0x32 - - * - BIND_METADATA - - :ref:`IPROTO_BIND_METADATA ` - - 0x33 - - * - BIND_COUNT - - :ref:`IPROTO_BIND_COUNT ` - - 0x34 - - * - POSITION - - :ref:`IPROTO_POSITION ` - - 0x35 - - * - SQL_TEXT - - :ref:`IPROTO_SQL_TEXT ` - - 0x40 - - * - SQL_BIND - - :ref:`IPROTO_SQL_BIND ` - - 0x41 - - * - SQL_INFO - - :ref:`IPROTO_SQL_INFO ` - - 0x42 - - * - STMT_ID - - :ref:`IPROTO_STMT_ID ` - - 0x43 - - * - REPLICA_ANON - - :ref:`IPROTO_REPLICA_ANON ` - - 0x50 - - * - ID_FILTER - - :ref:`IPROTO_ID_FILTER ` - - 0x51 - - * - ERROR - - :ref:`IPROTO_ERROR ` - - 0x52 - - * - TERM - - :ref:`IPROTO_TERM ` - - 0x53 - - * - VERSION - - :ref:`IPROTO_VERSION ` - - 0x54 - - * - FEATURES - - :ref:`IPROTO_FEATURES ` - - 0x55 - - * - TIMEOUT - - :ref:`IPROTO_TIMEOUT ` - - 0x56 - - * - EVENT_KEY - - :ref:`IPROTO_EVENT_KEY ` - - 0x57 - - * - EVENT_DATA - - :ref:`IPROTO_EVENT_DATA ` - - 0x58 - - * - TXN_ISOLATION - - :ref:`IPROTO_TXN_ISOLATION ` - - 0x59 - - * - VCLOCK_SYNC - - :ref:`IPROTO_VCLOCK_SYNC ` - - 0x5a - - * - AUTH_TYPE - - :ref:`IPROTO_AUTH_TYPE ` - - 0x5b - -**Example** - -.. code-block:: lua - - box.iproto.key.SYNC = 0x01 - -- ... \ No newline at end of file + tarantool> box.iproto.key.SYNC + --- + - 1 + ... \ No newline at end of file diff --git a/doc/reference/reference_lua/box_iproto/metadata.rst b/doc/reference/reference_lua/box_iproto/metadata.rst index f515a0a6aa..d140b0c800 100644 --- a/doc/reference/reference_lua/box_iproto/metadata.rst +++ b/doc/reference/reference_lua/box_iproto/metadata.rst @@ -1,4 +1,4 @@ -.. _reference_lua-box_iproto_metadata: +.. _reference_lua-box_iproto_metadata: box.iproto.metadata_key ======================= @@ -7,49 +7,18 @@ box.iproto.metadata_key .. data:: metadata_key - The ``box.iproto.metadata_key`` namespace contains the ``IPROTO_FILED_*`` keys, which are nested in the + The ``box.iproto.metadata_key`` namespace contains the ``IPROTO_FIELD_*`` keys, which are nested in the :ref:`IPROTO_METADATA ` key. - Available keys: + **Example** - .. list-table:: - :header-rows: 1 - :widths: 40 40 20 + .. code-block:: lua - * - Exported constant - - IPROTO constant name - - Code - - * - NAME - - :ref:`IPROTO_FIELD_NAME ` - - 0 - - * - TYPE - - :ref:`IPROTO_FIELD_TYPE ` - - 1 - - * - COLL - - :ref:`IPROTO_FIELD_COLL ` - - 2 - - * - IS_NULLABLE - - :ref:`IPROTO_FIELD_IS_NULLABLE ` - - 3 - - * - IS_AUTOINCREMENT - - :ref:`IPROTO_FIELD_IS_AUTOINCREMENT ` - - 4 - - * - SPAN - - :ref:`IPROTO_FIELD_SPAN ` - - 5 - - -**Example** - -.. code-block:: lua - - box.iproto.metadata_key.NAME = 1 - -- ... - box.iproto.metadata_key.TYPE = 2 - -- ... + tarantool> box.iproto.metadata_key.NAME + --- + - 0 + ... + tarantool> box.iproto.metadata_key.TYPE + --- + - 1 + ... diff --git a/doc/reference/reference_lua/box_iproto/override.rst b/doc/reference/reference_lua/box_iproto/override.rst index a3519c8836..401509a3d6 100644 --- a/doc/reference/reference_lua/box_iproto/override.rst +++ b/doc/reference/reference_lua/box_iproto/override.rst @@ -1,4 +1,4 @@ -.. _reference_lua-box_iproto_override: +.. _reference_lua-box_iproto_override: box.iproto.override() ===================== @@ -8,13 +8,72 @@ box.iproto.override() .. function:: override(request_type, handler) Since version :doc:`2.11.0 `. - Set the IPROTO request handler callbacks. + Set a new IPROTO request handler callback for the given request type. - :param uint32_t request_type: - :param iproto_handler_t handler: + :param number request_type: a request type code. Possible values: - :return: 0 on success or -1 on error (check box_error_last()) - :rtype: number + * a type code from :ref:`box.iproto.type ` (except + ``box.iproto.type.UNKNOWN``) -- override the existing request type handler. + + * ``box.iproto.type.UNKNOWN`` -- override the handler of unknown request types. + + :param function handler: IPROTO request handler. + The signature of a handler function: ``function(sid, header, body)``, where + + * ``sid`` (number): current IPROTO session identifier (see :ref:`box.session.id() `) + * ``header`` (userdata): a request header encoded as a :ref:`msgpack_object ` + * ``body`` (userdata): a request body encoded as a :ref:`msgpack_object ` + + Returns ``true`` on success, otherwise ``false``. On ``false``, there is a fallback + to the default handler. Also, you can indicate an error by throwing an exception. + In this case, the return value is ``false``, but this does not always means a failure. + + To reset the request handler, set the ``handler`` parameter to ``nil``. + + :return: none + + **Possible errors:** + + If a Lua handler throws an exception, the behavior is similar to that of a remote procedure call. + The following errors are returned to the client over IPROTO (see `src/lua/utils.h `__): + + * :errcode:`ER_PROC_LUA` -- an exception is thrown from a Lua handler, diagnostic is not set. + * diagnostics from ``src/box/errcode.h`` -- an exception is thrown, diagnostic is set. + + For details, see `src/box/errcode.h `__. **Example:** + Define a handler function for the ``box.iproto.type.SELECT`` request type: + + .. code-block:: lua + + local function iproto_select_handler_lua(sid, header, body) + if body.space_id == 512 + box.iproto.send(box.session.id(), + {request_type = box.iproto.type.OK, + sync = header.SYNC, + schema_version = box.info.schema_version}), + {data = {1, 2, 3}}) + return true + end + return false + end + + Override ``box.iproto.type.SELECT`` handler: + + .. code-block:: lua + + box.iproto.override(box.iproto.type.SELECT, iproto_select_handler_lua) + + Reset ``box.iproto.type.SELECT`` handler: + + .. code-block:: lua + + box.iproto.override(box.iproto.type.SELECT, nil) + + Override a handler function for the unknown request type: + + .. code-block:: lua + + box.iproto.override(box.iproto.type.UNKNOWN, iproto_unknown_request_handler_lua) diff --git a/doc/reference/reference_lua/box_iproto/protocol_features.rst b/doc/reference/reference_lua/box_iproto/protocol_features.rst index d49e8e92bd..409fa43c7c 100644 --- a/doc/reference/reference_lua/box_iproto/protocol_features.rst +++ b/doc/reference/reference_lua/box_iproto/protocol_features.rst @@ -1,24 +1,25 @@ .. _reference_lua-box_iproto_protocol-features: -box.iproto.protocol_version -=========================== +box.iproto.protocol_features +============================ .. module:: box.iproto -.. data:: protocol_version +.. data:: protocol_features The set of IPROTO protocol features supported by the server. - Learn more: `src/box/iproto_features.h `__ - and `iproto_features_resolve() `__). + Learn more: :ref:`net.box features `, `src/box/iproto_features.h `__, + and `iproto_features_resolve() `__. -**Example** + **Example** -.. code-block:: lua - - box.iproto.protocol_features = { - streams = true, - transactions = true, - error_extension = true, - watchers = true, - } + .. code-block:: lua + tarantool> box.iproto.protocol_features + --- + - transactions: true + watchers: true + error_extension: true + streams: true + pagination: true + ... diff --git a/doc/reference/reference_lua/box_iproto/protocol_version.rst b/doc/reference/reference_lua/box_iproto/protocol_version.rst index fa55869221..8b4de21832 100644 --- a/doc/reference/reference_lua/box_iproto/protocol_version.rst +++ b/doc/reference/reference_lua/box_iproto/protocol_version.rst @@ -10,9 +10,11 @@ box.iproto.protocol_version Current IPROTO protocol version of the server. Learn more: :ref:`IPROTO_ID `. + **Example** -**Example** + .. code-block:: lua -.. code-block:: lua - - box.iproto.protocol_version = 4 \ No newline at end of file + tarantool> box.iproto.protocol_version + --- + - 4 + ... diff --git a/doc/reference/reference_lua/box_iproto/raft.rst b/doc/reference/reference_lua/box_iproto/raft.rst index f55d72d319..1dc99f2679 100644 --- a/doc/reference/reference_lua/box_iproto/raft.rst +++ b/doc/reference/reference_lua/box_iproto/raft.rst @@ -10,45 +10,15 @@ box.iproto.raft The ``box.iproto.raft_key`` namespace contains the keys from the ``IPROTO_RAFT_*`` requests. Learn more: :ref:`Synchronous replication keys `. - Available keys: - - .. list-table:: - :header-rows: 1 - :widths: 40 40 20 - - * - Exported constant - - IPROTO constant name - - Code - - * - TERM - - :ref:`IPROTO_RAFT_TERM ` - - 0 - - * - VOTE - - :ref:`IPROTO_RAFT_VOTE ` - - 1 - - * - STATE - - :ref:`IPROTO_RAFT_STATE ` - - 2 - - * - VCLOCK - - :ref:`IPROTO_RAFT_VCLOCK ` - - 3 - - * - LEADER_ID - - :ref:`IPROTO_RAFT_LEADER_ID ` - - 4 - - * - IS_LEADER_SEEN - - :ref:`IPROTO_RAFT_IS_LEADER_SEEN ` - - 5 - -**Example** - -.. code-block:: lua - - box.iproto.raft_key.TERM = 0 - -- ... - box.iproto.raft_key.VOTE = 1 - -- ... + **Example** + + .. code-block:: lua + + tarantool> box.iproto.raft_key.TERM + --- + - 0 + ... + tarantool> box.iproto.raft_key.VOTE + --- + - 1 + ... diff --git a/doc/reference/reference_lua/box_iproto/request_type.rst b/doc/reference/reference_lua/box_iproto/request_type.rst index 8cc4334a8a..dad73a1733 100644 --- a/doc/reference/reference_lua/box_iproto/request_type.rst +++ b/doc/reference/reference_lua/box_iproto/request_type.rst @@ -10,164 +10,15 @@ box.iproto.type The ``box.iproto.type`` namespace contains all available request types. Learn more about the requests: :ref:`Client-server requests and responses `. - Available types: - - .. list-table:: - :header-rows: 1 - :widths: 40 40 20 - - * - Exported constant - - IPROTO constant name - - Code - - * - OK - - :ref:`IPROTO_OK ` - - 0 - - * - SELECT - - :ref:`IPROTO_SELECT ` - - 1 - - * - INSERT - - :ref:`IPROTO_INSERT ` - - 2 - - * - REPLACE - - :ref:`IPROTO_REPLACE ` - - 3 - - * - UPDATE - - :ref:`IPROTO_REPLACE ` - - 4 - - * - DELETE - - :ref:`IPROTO_REPLACE ` - - 5 - - * - CALL_16 - - :ref:`IPROTO_CALL_16 ` - - 6 - - * - AUTH - - :ref:`IPROTO_AUTH ` - - 7 - - * - EVAL - - :ref:`IPROTO_EVAL ` - - 8 - - * - UPSERT - - :ref:`IPROTO_UPSERT ` - - 9 - - * - CALL - - :ref:`IPROTO_CALL ` - - 10 - - * - EXECUTE - - :ref:`IPROTO_EXECUTE ` - - 11 - - * - NOP - - :ref:`IPROTO_NOP ` - - 12 - - * - PREPARE - - :ref:`IPROTO_PREPARE ` - - 13 - - * - BEGIN - - :ref:`IPROTO_BEGIN ` - - 14 - - * - COMMIT - - :ref:`IPROTO_COMMIT ` - - 15 - - * - ROLLBACK - - :ref:`IPROTO_ROLLBACK ` - - 16 - - * - RAFT - - :ref:`IPROTO_RAFT ` - - 30 - - * - RAFT_PROMOTE - - :ref:`IPROTO_BALLOT_REGISTERED_REPLICA_UUIDS ` - - 31 - - * - RAFT_DEMOTE - - :ref:`IPROTO_RAFT_DEMOTE ` - - 32 - - * - RAFT_CONFIRM - - :ref:`IPROTO_RAFT_CONFIRM ` - - 40 - - * - RAFT_ROLLBACK - - :ref:`IPROTO_RAFT_ROLLBACK ` - - 41 - - * - PING - - :ref:`IPROTO_PING ` - - 64 - - * - JOIN - - :ref:`IPROTO_JOIN ` - - 65 - - * - SUBSCRIBE - - :ref:`IPROTO_SUBSCRIBE ` - - 66 - - * - VOTE_DEPRECATED - - IPROTO_VOTE_DEPRECATED - - 67 - - * - VOTE - - :ref:`IPROTO_VOTE ` - - 68 - - * - FETCH_SNAPSHOT - - :ref:`IPROTO_FETCH_SNAPSHOT ` - - 69 - - * - REGISTER - - :ref:`IPROTO_REGISTER ` - - 70 - - * - JOIN_META - - IPROTO_JOIN_META - - 71 - - * - JOIN_SNAPSHOT - - IPROTO_JOIN_SNAPSHOT - - 72 - - * - ID - - :ref:`IPROTO_ID ` - - 73 - - * - WATCH - - :ref:`IPROTO_WATCH ` - - 74 - - * - UNWATCH - - :ref:`IPROTO_UNWATCH ` - - 75 - - * - EVENT - - :ref:`IPROTO_WATCH ` - - 76 - - * - CHUNK - - :ref:`IPROTO_CHUNK ` - - 128 - - * - TYPE_ERROR - - :ref:`IPROTO_TYPE_ERROR ` - - bit.lshift(1, 15) - - * - UNKNOWN - - :ref:`IPROTO_UNKNOWN ` - - -1 + **Example** + + .. code-block:: lua + + tarantool> box.iproto.type.UNKNOWN + --- + - -1 + ... + tarantool> box.iproto.type.CHUNK + --- + - 128 + ... diff --git a/doc/reference/reference_lua/box_iproto/send.rst b/doc/reference/reference_lua/box_iproto/send.rst index b518e5134e..4ae4877c20 100644 --- a/doc/reference/reference_lua/box_iproto/send.rst +++ b/doc/reference/reference_lua/box_iproto/send.rst @@ -1,4 +1,4 @@ -.. _reference_lua-box_iproto_send: +.. _reference_lua-box_iproto_send: box.iproto.send() ================= @@ -10,17 +10,55 @@ box.iproto.send() Since version :doc:`2.11.0 `. Send an :ref:`IPROTO ` packet over the session's socket with the given MsgPack header and body. + The header and body contain exported IPROTO constants from the :ref:`box.iproto() ` submodule. + Possible IPROTO constant formats: + + * a lowercase constant without the ``IPROTO_`` prefix (``schema_version``, ``request_type``) + * a constant from the corresponding :ref:`box.iproto ` subnamespace (``box.iproto.SCHEMA_VERSION``, ``box.iproto.REQUEST_TYPE``) + + The function works for binary sessions only. For details, see :ref:`box.session.type() `. :param number sid: IPROTO session identifier (see :ref:`box.session.id() `) :param table|string header: a request header encoded as MsgPack :param table|string|nil body: a request body encoded as MsgPack - :return: 0 on success - :return: 1 on error + :return: 0 on success, otherwise an error is raised :rtype: number **Possible errors:** - **Example:** + * :errcode:`ER_SESSION_CLOSED` -- the session is closed. + * :errcode:`ER_NO_SUCH_SESSION` -- the session does not exist. + * :errcode:`ER_MEMORY_ISSUE` -- out of memory limit has been reached. + * :errcode:`ER_WRONG_SESSION_TYPE` -- the session type is not binary. + + For details, see `src/box/errcode.h `__. + + **Examples:** + + Send a packet using Lua tables and string IPROTO constants as keys: + + .. code-block:: lua + + box.iproto.send(box.session.id(), {request_type = box.iproto.type.OK, + sync = 10, + schema_version = box.info.schema_version}), + {data = 1})) + + Send a packet using Lua tables and numeric IPROTO constants: + + .. code-block:: lua + + box.iproto.send(box.session.id(), {[box.iproto.key.REQUEST_TYPE] = box.iproto.type.OK, + [box.iproto.key.SYNC] = 10, + [box.iproto.key.SCHEMA_VERSION] = box.info.schema_version}), + {[box.iproto.key.DATA] = 1})) + + Send a packet that contains only the header: + + .. code-block:: lua + box.iproto.send(box.session.id(), {request_type = box.iproto.type.OK, + sync = 10, + schema_version = box.info.schema_version})) From 7d9f4ef9a7cf194fd13c7d79fd629e8068ebd4c1 Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Thu, 16 Nov 2023 16:21:09 +0300 Subject: [PATCH 4/4] Apply suggestions from text review --- doc/dev_guide/internals/iproto/requests.rst | 6 +-- doc/dev_guide/reference_capi/box.rst | 39 +++++++++---------- .../reference_lua/box_info/schema_version.rst | 2 +- doc/reference/reference_lua/box_iproto.rst | 30 +++++++------- .../reference_lua/box_iproto/ballot.rst | 2 +- .../reference_lua/box_iproto/feature.rst | 2 +- .../reference_lua/box_iproto/flag.rst | 2 +- .../reference_lua/box_iproto/key.rst | 2 +- .../reference_lua/box_iproto/metadata.rst | 2 +- .../reference_lua/box_iproto/override.rst | 22 +++++------ .../box_iproto/protocol_features.rst | 2 +- .../box_iproto/protocol_version.rst | 4 +- .../reference_lua/box_iproto/raft.rst | 2 +- .../reference_lua/box_iproto/request_type.rst | 2 +- .../reference_lua/box_iproto/send.rst | 30 +++++++------- .../reference_lua/box_session/id.rst | 3 +- 16 files changed, 75 insertions(+), 77 deletions(-) diff --git a/doc/dev_guide/internals/iproto/requests.rst b/doc/dev_guide/internals/iproto/requests.rst index b09cb93fa1..df2026d976 100644 --- a/doc/dev_guide/internals/iproto/requests.rst +++ b/doc/dev_guide/internals/iproto/requests.rst @@ -40,7 +40,7 @@ Overview * - :ref:`IPROTO_UNKNOWN ` - -1 |br| MP_UINT - - Unknown request type + - An unknown request type * - :ref:`IPROTO_SELECT ` - 0x01 @@ -139,8 +139,8 @@ Since :doc:`2.11.0 `. Code: -1. -Unknown request type. The constant is used to override the handler of unknown IPROTO request types. -Learn more: :ref:`box.iproto.override() ` and :ref:`box_box_iproto_override `. +An unknown request type. The constant is used to override the handler of unknown IPROTO request types. +Learn more: :ref:`box.iproto.override() ` and :ref:`box_iproto_override `. .. _box_protocol-select: diff --git a/doc/dev_guide/reference_capi/box.rst b/doc/dev_guide/reference_capi/box.rst index b25a9d18e1..00cc8a84e8 100644 --- a/doc/dev_guide/reference_capi/box.rst +++ b/doc/dev_guide/reference_capi/box.rst @@ -105,7 +105,7 @@ :return: -1 on error (check :ref:`box_error_last()`) :return: 0 otherwise - See also :ref:`space_object.insert()` + See also: :ref:`space_object.insert()` .. _box-box_replace: @@ -122,7 +122,7 @@ :return: -1 on error (check :ref:`box_error_last()`) :return: 0 otherwise - See also :ref:`space_object.replace()` + See also: :ref:`space_object.replace()` .. c:function:: int box_delete(uint32_t space_id, uint32_t index_id, const char *key, const char *key_end, box_tuple_t **result) @@ -138,7 +138,7 @@ :return: -1 on error (check :ref:`box_error_last()`) :return: 0 otherwise - See also :ref:`space_object.delete()` + See also: :ref:`space_object.delete()` .. c:function:: int box_update(uint32_t space_id, uint32_t index_id, const char *key, const char *key_end, const char *ops, const char *ops_end, int index_base, box_tuple_t **result) @@ -159,7 +159,7 @@ :return: -1 on error (check :ref:`box_error_last()`) :return: 0 otherwise - See also :ref:`space_object.update()` + See also: :ref:`space_object.update()` .. c:function:: int box_upsert(uint32_t space_id, uint32_t index_id, const char *tuple, const char *tuple_end, const char *ops, const char *ops_end, int index_base, box_tuple_t **result) @@ -180,7 +180,7 @@ :return: -1 on error (check :ref:`box_error_last()`) :return: 0 otherwise - See also :ref:`space_object.upsert()` + See also: :ref:`space_object.upsert()` .. c:function:: int box_truncate(uint32_t space_id) @@ -230,7 +230,7 @@ :return: the database schema version :rtype: number - See also :ref:`box.info.schema_version ` and :ref:`IPROTO_SCHEMA_VERSION ` + See also: :ref:`box.info.schema_version ` and :ref:`IPROTO_SCHEMA_VERSION ` .. _box_box_session_id: @@ -239,11 +239,10 @@ Since version :doc:`2.11.0 `. Return the unique identifier (ID) for the current session. - :return: the unique identifier (ID) for the current session - :return: 0 or -1 if there is no session + :return: the session identifier; 0 or -1 if there is no session :rtype: number - See also :ref:`box.session.id() ` + See also: :ref:`box.session.id() ` .. _box_box_iproto_send: @@ -255,24 +254,23 @@ The function yields. The function works for binary sessions only. For details, see :ref:`box.session.type() `. - :param uint32_t sid: IPROTO session identifier (see :ref:`box_session_id() `) + :param uint32_t sid: the IPROTO session identifier (see :ref:`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. 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 - :return: -1 on error (check :ref:`box_error_last() `) + :return: 0 on success; -1 on error (check :ref:`box_error_last() `) :rtype: number - See also :ref:`box.iproto.send() ` + See also: :ref:`box.iproto.send() ` **Possible errors:** * :errcode:`ER_SESSION_CLOSED` -- the session is closed. * :errcode:`ER_NO_SUCH_SESSION` -- the session does not exist. - * :errcode:`ER_MEMORY_ISSUE` -- out of memory limit has been reached. + * :errcode:`ER_MEMORY_ISSUE` -- out-of-memory limit has been reached. * :errcode:`ER_WRONG_SESSION_TYPE` -- the session type is not binary. For details, see `src/box/errcode.h `__. @@ -335,11 +333,10 @@ :param void* ctx: a context passed to the ``handler`` and ``destroy`` callbacks - :return: 0 on success - :return: -1 on error (check :ref:`box_error_last() `) + :return: 0 on success; -1 on error (check :ref:`box_error_last() `) :rtype: number - See also :ref:`box.iproto.override() ` + See also: :ref:`box.iproto.override() ` **Possible errors:** @@ -371,10 +368,10 @@ 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 + * ``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: diff --git a/doc/reference/reference_lua/box_info/schema_version.rst b/doc/reference/reference_lua/box_info/schema_version.rst index dbd043297d..f39b93b3fc 100644 --- a/doc/reference/reference_lua/box_info/schema_version.rst +++ b/doc/reference/reference_lua/box_info/schema_version.rst @@ -23,4 +23,4 @@ box.info.schema_version - 84 ... - See also :ref:`IPROTO_SCHEMA_VERSION ` + See also: :ref:`IPROTO_SCHEMA_VERSION ` diff --git a/doc/reference/reference_lua/box_iproto.rst b/doc/reference/reference_lua/box_iproto.rst index 8195beae02..de894e43c7 100644 --- a/doc/reference/reference_lua/box_iproto.rst +++ b/doc/reference/reference_lua/box_iproto.rst @@ -9,7 +9,7 @@ The ``box.iproto`` submodule provides the ability to work with the network subsy It allows you to extend the :ref:`IPROTO ` functionality from Lua. With this submodule, you can: -* :ref:`parse the unknown IPROTO requests types ` +* :ref:`parse unknown IPROTO request types ` * :ref:`send arbitrary IPROTO packets ` * :ref:`override the behavior ` of the existing and unknown request types in the binary protocol @@ -23,12 +23,12 @@ IPROTO constants 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 ` (:ref:`IPROTO_SYNC `, :ref:`IPROTO_REQUEST_TYPE `) -* :ref:`request type ` (:ref:`IPROTO_OK `) -* :ref:`flag ` (:ref:`IPROTO_COMMIT `) -* :ref:`ballot key ` (:ref:`IPROTO_FLAG_COMMIT `) -* :ref:`metadata key ` (:ref:`IPROTO_FIELD_IS_NULLABLE `) -* :ref:`RAFT key ` (:ref:`IPROTO_TERM `) +* :ref:`key `. Example: :ref:`IPROTO_SYNC `. +* :ref:`request type `. Example: :ref:`IPROTO_OK `. +* :ref:`flag `. Example: :ref:`IPROTO_COMMIT `. +* :ref:`ballot key `. Example: :ref:`IPROTO_FLAG_COMMIT `. +* :ref:`metadata key `. Example: :ref:`IPROTO_FIELD_IS_NULLABLE `. +* :ref:`RAFT key `. Example: :ref:`IPROTO_TERM `. Each group is located in the corresponding subnamespace without the prefix. For example: @@ -67,11 +67,11 @@ The example converts the feature names from ``box.iproto.protocol_features`` set -- Features supported by the server box.iproto.protocol_features = { - streams = true, - transactions = true, - error_extension = true, - watchers = true, - pagination = true, + streams = true, + transactions = true, + error_extension = true, + watchers = true, + pagination = true, } -- Convert the feature names into codes @@ -79,7 +79,7 @@ The example converts the feature names from ``box.iproto.protocol_features`` set for name in pairs(box.iproto.protocol_features) do table.insert(features, box.iproto.feature[name]) end - features -- [0, 1, 2, 3, 4] + return features -- [0, 1, 2, 3, 4] .. _box_iproto-unknown: @@ -88,7 +88,7 @@ Handling the unknown IPROTO request types Every IPROTO request has a static handler. That is, before version :doc:`2.11.0 `, any unknown request raised an error. -Since :doc:`2.11.0 `, a new request type is introduced -- :ref:`IPROTO_UNKNOWN `. +Since :doc:`2.11.0 `, a new request type is introduced -- :ref:`IPROTO_UNKNOWN `. This type is used to override the handlers of the unknown IPROTO request types. For details, see :ref:`box.iproto.override() ` and :ref:`box_iproto_override ` functions. @@ -130,7 +130,7 @@ The table lists all available functions and data of the submodule: - Keys from the ``IPROTO_RAFT_`` requests * - :doc:`./box_iproto/protocol_version` - - Current IPROTO protocol version + - The current IPROTO protocol version * - :doc:`./box_iproto/protocol_features` - The set of supported IPROTO protocol features diff --git a/doc/reference/reference_lua/box_iproto/ballot.rst b/doc/reference/reference_lua/box_iproto/ballot.rst index a9a6bb7dfd..680c3db11b 100644 --- a/doc/reference/reference_lua/box_iproto/ballot.rst +++ b/doc/reference/reference_lua/box_iproto/ballot.rst @@ -7,7 +7,7 @@ box.iproto.ballot_key .. data:: ballot_key - The ``box.iproto.ballot_key`` namespace contains the keys from the :ref:`IPROTO_BALLOT ` requests. + Contains the keys from the :ref:`IPROTO_BALLOT ` requests. Learn more: :ref:`IPROTO_BALLOT keys `. **Example** diff --git a/doc/reference/reference_lua/box_iproto/feature.rst b/doc/reference/reference_lua/box_iproto/feature.rst index 938f3ae891..890a64b870 100644 --- a/doc/reference/reference_lua/box_iproto/feature.rst +++ b/doc/reference/reference_lua/box_iproto/feature.rst @@ -7,7 +7,7 @@ box.iproto.feature .. data:: feature - The ``box.iproto.feature`` namespace contains the IPROTO protocol features that are supported by the server. + Contains the IPROTO protocol features that are supported by the server. Each feature is mapped to its corresponding code. Learn more: :ref:`IPROTO_FEATURES `. diff --git a/doc/reference/reference_lua/box_iproto/flag.rst b/doc/reference/reference_lua/box_iproto/flag.rst index 13d393bcf1..a233085248 100644 --- a/doc/reference/reference_lua/box_iproto/flag.rst +++ b/doc/reference/reference_lua/box_iproto/flag.rst @@ -7,7 +7,7 @@ box.iproto.flag .. data:: flag - The ``box.iproto.flag`` namespace contains the flags from the ``IPROTO_FLAGS`` key. + Contains the flags from the ``IPROTO_FLAGS`` key. Learn more: :ref:`IPROTO_FLAGS key `. **Example** diff --git a/doc/reference/reference_lua/box_iproto/key.rst b/doc/reference/reference_lua/box_iproto/key.rst index 2eb00233d2..1bb49e4ca4 100644 --- a/doc/reference/reference_lua/box_iproto/key.rst +++ b/doc/reference/reference_lua/box_iproto/key.rst @@ -7,7 +7,7 @@ box.iproto.key .. data:: key - The ``box.iproto.key`` namespace contains all available request keys, except :ref:`raft `, + Contains all available request keys, except :ref:`raft `, :ref:`metadata `, and :ref:`ballot ` keys. Learn more: :ref:`Keys used in requests and responses `. diff --git a/doc/reference/reference_lua/box_iproto/metadata.rst b/doc/reference/reference_lua/box_iproto/metadata.rst index d140b0c800..c764838c32 100644 --- a/doc/reference/reference_lua/box_iproto/metadata.rst +++ b/doc/reference/reference_lua/box_iproto/metadata.rst @@ -7,7 +7,7 @@ box.iproto.metadata_key .. data:: metadata_key - The ``box.iproto.metadata_key`` namespace contains the ``IPROTO_FIELD_*`` keys, which are nested in the + Contains the ``IPROTO_FIELD_*`` keys, which are nested in the :ref:`IPROTO_METADATA ` key. **Example** diff --git a/doc/reference/reference_lua/box_iproto/override.rst b/doc/reference/reference_lua/box_iproto/override.rst index 401509a3d6..8c168b2762 100644 --- a/doc/reference/reference_lua/box_iproto/override.rst +++ b/doc/reference/reference_lua/box_iproto/override.rst @@ -20,13 +20,13 @@ box.iproto.override() :param function handler: IPROTO request handler. The signature of a handler function: ``function(sid, header, body)``, where - * ``sid`` (number): current IPROTO session identifier (see :ref:`box.session.id() `) + * ``sid`` (number): the current IPROTO session identifier (see :ref:`box.session.id() `) * ``header`` (userdata): a request header encoded as a :ref:`msgpack_object ` * ``body`` (userdata): a request body encoded as a :ref:`msgpack_object ` Returns ``true`` on success, otherwise ``false``. On ``false``, there is a fallback to the default handler. Also, you can indicate an error by throwing an exception. - In this case, the return value is ``false``, but this does not always means a failure. + In this case, the return value is ``false``, but this does not always mean a failure. To reset the request handler, set the ``handler`` parameter to ``nil``. @@ -49,15 +49,15 @@ box.iproto.override() .. code-block:: lua local function iproto_select_handler_lua(sid, header, body) - if body.space_id == 512 - box.iproto.send(box.session.id(), - {request_type = box.iproto.type.OK, - sync = header.SYNC, - schema_version = box.info.schema_version}), - {data = {1, 2, 3}}) - return true - end - return false + if body.space_id == 512 then + box.iproto.send(box.session.id(), + { request_type = box.iproto.type.OK, + sync = header.SYNC, + schema_version = box.info.schema_version }, + { data = { 1, 2, 3 } }) + return true + end + return false end Override ``box.iproto.type.SELECT`` handler: diff --git a/doc/reference/reference_lua/box_iproto/protocol_features.rst b/doc/reference/reference_lua/box_iproto/protocol_features.rst index 409fa43c7c..ad95a31fbc 100644 --- a/doc/reference/reference_lua/box_iproto/protocol_features.rst +++ b/doc/reference/reference_lua/box_iproto/protocol_features.rst @@ -1,4 +1,4 @@ -.. _reference_lua-box_iproto_protocol-features: +.. _reference_lua-box_iproto_protocol-features: box.iproto.protocol_features ============================ diff --git a/doc/reference/reference_lua/box_iproto/protocol_version.rst b/doc/reference/reference_lua/box_iproto/protocol_version.rst index 8b4de21832..947c23d433 100644 --- a/doc/reference/reference_lua/box_iproto/protocol_version.rst +++ b/doc/reference/reference_lua/box_iproto/protocol_version.rst @@ -1,4 +1,4 @@ -.. _reference_lua-box_iproto_version: +.. _reference_lua-box_iproto_version: box.iproto.protocol_version =========================== @@ -7,7 +7,7 @@ box.iproto.protocol_version .. data:: protocol_version - Current IPROTO protocol version of the server. + The current IPROTO protocol version of the server. Learn more: :ref:`IPROTO_ID `. **Example** diff --git a/doc/reference/reference_lua/box_iproto/raft.rst b/doc/reference/reference_lua/box_iproto/raft.rst index 1dc99f2679..ccfa8c7476 100644 --- a/doc/reference/reference_lua/box_iproto/raft.rst +++ b/doc/reference/reference_lua/box_iproto/raft.rst @@ -7,7 +7,7 @@ box.iproto.raft .. data:: raft_key - The ``box.iproto.raft_key`` namespace contains the keys from the ``IPROTO_RAFT_*`` requests. + Contains the keys from the ``IPROTO_RAFT_*`` requests. Learn more: :ref:`Synchronous replication keys `. **Example** diff --git a/doc/reference/reference_lua/box_iproto/request_type.rst b/doc/reference/reference_lua/box_iproto/request_type.rst index dad73a1733..4ca03be0e2 100644 --- a/doc/reference/reference_lua/box_iproto/request_type.rst +++ b/doc/reference/reference_lua/box_iproto/request_type.rst @@ -7,7 +7,7 @@ box.iproto.type .. data:: type - The ``box.iproto.type`` namespace contains all available request types. + Contains all available request types. Learn more about the requests: :ref:`Client-server requests and responses `. **Example** diff --git a/doc/reference/reference_lua/box_iproto/send.rst b/doc/reference/reference_lua/box_iproto/send.rst index 4ae4877c20..74226785e5 100644 --- a/doc/reference/reference_lua/box_iproto/send.rst +++ b/doc/reference/reference_lua/box_iproto/send.rst @@ -18,7 +18,7 @@ box.iproto.send() The function works for binary sessions only. For details, see :ref:`box.session.type() `. - :param number sid: IPROTO session identifier (see :ref:`box.session.id() `) + :param number sid: the IPROTO session identifier (see :ref:`box.session.id() `) :param table|string header: a request header encoded as MsgPack :param table|string|nil body: a request body encoded as MsgPack @@ -29,7 +29,7 @@ box.iproto.send() * :errcode:`ER_SESSION_CLOSED` -- the session is closed. * :errcode:`ER_NO_SUCH_SESSION` -- the session does not exist. - * :errcode:`ER_MEMORY_ISSUE` -- out of memory limit has been reached. + * :errcode:`ER_MEMORY_ISSUE` -- out-of-memory limit has been reached. * :errcode:`ER_WRONG_SESSION_TYPE` -- the session type is not binary. For details, see `src/box/errcode.h `__. @@ -40,25 +40,27 @@ box.iproto.send() .. code-block:: lua - box.iproto.send(box.session.id(), {request_type = box.iproto.type.OK, - sync = 10, - schema_version = box.info.schema_version}), - {data = 1})) + box.iproto.send(box.session.id(), + { request_type = box.iproto.type.OK, + sync = 10, + schema_version = box.info.schema_version }, + { data = 1 }) Send a packet using Lua tables and numeric IPROTO constants: .. code-block:: lua - box.iproto.send(box.session.id(), {[box.iproto.key.REQUEST_TYPE] = box.iproto.type.OK, - [box.iproto.key.SYNC] = 10, - [box.iproto.key.SCHEMA_VERSION] = box.info.schema_version}), - {[box.iproto.key.DATA] = 1})) + box.iproto.send(box.session.id(), + { [box.iproto.key.REQUEST_TYPE] = box.iproto.type.OK, + [box.iproto.key.SYNC] = 10, + [box.iproto.key.SCHEMA_VERSION] = box.info.schema_version }, + { [box.iproto.key.DATA] = 1 }) Send a packet that contains only the header: .. code-block:: lua - box.iproto.send(box.session.id(), {request_type = box.iproto.type.OK, - sync = 10, - schema_version = box.info.schema_version})) - + box.iproto.send(box.session.id(), + { request_type = box.iproto.type.OK, + sync = 10, + schema_version = box.info.schema_version }) diff --git a/doc/reference/reference_lua/box_session/id.rst b/doc/reference/reference_lua/box_session/id.rst index d48c1577aa..bc871e5118 100644 --- a/doc/reference/reference_lua/box_session/id.rst +++ b/doc/reference/reference_lua/box_session/id.rst @@ -10,6 +10,5 @@ box.session.id() Return the unique identifier (ID) for the current session. - :return: the unique identifier (ID) for the current session - :return: 0 or -1 if there is no session + :return: the session identifier; 0 or -1 if there is no session :rtype: number \ No newline at end of file