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 d258768565..e1882e513e 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 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 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..27f9f88cd3 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 ----------------- @@ -132,6 +134,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 +196,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 +274,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 +322,8 @@ Synchronous replication All ``IPROTO_RAFT_*`` keys are used only in ``IPROTO_RAFT*`` requests. +.. _internals-iproto-keys-events: + Events and subscriptions ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -342,6 +347,8 @@ Events and subscriptions :ref:`Learn more about events and subscriptions in iproto `. +.. _internals-iproto-keys-sql-specific: + SQL-specific ~~~~~~~~~~~~ @@ -460,7 +467,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. @@ -606,7 +613,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 +661,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 +746,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/internals/iproto/requests.rst b/doc/dev_guide/internals/iproto/requests.rst index c0d68bdcb7..df2026d976 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 + - An 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. + +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: IPROTO_SELECT diff --git a/doc/dev_guide/reference_capi/box.rst b/doc/dev_guide/reference_capi/box.rst index cbb0f016ae..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) @@ -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,190 @@ :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 + :return: the session identifier; 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. + The function yields. + The function works for binary sessions only. For details, see :ref:`box.session.type() `. + + :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; -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 `. + 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 void* ctx: a context passed to the ``handler`` and ``destroy`` callbacks + + :return: 0 on success; -1 on error (check :ref:`box_error_last() `) + :rtype: number + + 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 - See also :ref:`box.session.id()` + 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.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..f39b93b3fc 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..de894e43c7 --- /dev/null +++ b/doc/reference/reference_lua/box_iproto.rst @@ -0,0 +1,161 @@ +.. _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 allows you to extend the :ref:`IPROTO ` functionality from Lua. +With this submodule, you can: + +* :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 + +The submodule exports all IPROTO :ref:`constants ` and :ref:`features ` to Lua. + +.. _box_iproto-constants: + +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 `. 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: + +.. code-block:: lua + + box.iproto.key.SYNC = 0x01 + -- ... + box.iproto.type.SELECT = 1 + -- ... + box.iproto.flag.COMMIT = 1 + -- ... + box.iproto.ballot_key.VCLOCK = 2 + -- ... + 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 `) + +**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 + return 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 +------------- + +The table lists all available functions and data of the submodule: + +.. container:: table + + .. rst-class:: left-align-column-1 + .. rst-class:: left-align-column-2 + + .. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Name + - Use + + * - :doc:`./box_iproto/key` + - Request keys + + * - :doc:`./box_iproto/request_type` + - Request types + + * - :doc:`./box_iproto/flag` + - 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` + - The current IPROTO protocol version + + * - :doc:`./box_iproto/protocol_features` + - The set of supported IPROTO protocol features + + * - :doc:`./box_iproto/feature` + - IPROTO protocol :ref:`features ` + + * - :doc:`./box_iproto/override` + - Set a new IPROTO request handler callback for the given request type + + * - :doc:`./box_iproto/send` + - Send an IPROTO packet over the session's socket + + +.. toctree:: + :hidden: + + box_iproto/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..680c3db11b --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/ballot.rst @@ -0,0 +1,25 @@ +.. _reference_lua-box_iproto_ballot: + +box.iproto.ballot_key +===================== + +.. module:: box.iproto + +.. data:: ballot_key + + Contains the keys from the :ref:`IPROTO_BALLOT ` requests. + Learn more: :ref:`IPROTO_BALLOT keys `. + + **Example** + + .. code-block:: lua + + tarantool> box.iproto.ballot_key.IS_RO_CFG + --- + - 1 + ... + tarantool> box.iproto.ballot_key.VCLOCK + --- + - 2 + ... + 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..890a64b870 --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/feature.rst @@ -0,0 +1,30 @@ +.. _reference_lua-box_iproto_feature: + +box.iproto.feature +================== + +.. module:: box.iproto + +.. data:: feature + + 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 lowercase letters + * without the ``IPROTO_FEATURE_`` prefix + + **Example** + + .. code-block:: lua + + 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 new file mode 100644 index 0000000000..a233085248 --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/flag.rst @@ -0,0 +1,24 @@ +.. _reference_lua-box_iproto_flag: + +box.iproto.flag +=============== + +.. module:: box.iproto + +.. data:: flag + + Contains the flags from the ``IPROTO_FLAGS`` key. + Learn more: :ref:`IPROTO_FLAGS key `. + + **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 new file mode 100644 index 0000000000..1bb49e4ca4 --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/key.rst @@ -0,0 +1,21 @@ +.. _reference_lua-box_iproto_key: + +box.iproto.key +============== + +.. module:: box.iproto + +.. data:: key + + Contains all available request keys, except :ref:`raft `, + :ref:`metadata `, and :ref:`ballot ` keys. + Learn more: :ref:`Keys used in requests and responses `. + + **Example** + + .. code-block:: lua + + 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 new file mode 100644 index 0000000000..c764838c32 --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/metadata.rst @@ -0,0 +1,24 @@ +.. _reference_lua-box_iproto_metadata: + +box.iproto.metadata_key +======================= + +.. module:: box.iproto + +.. data:: metadata_key + + Contains the ``IPROTO_FIELD_*`` keys, which are nested in the + :ref:`IPROTO_METADATA ` key. + + **Example** + + .. code-block:: lua + + 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 new file mode 100644 index 0000000000..8c168b2762 --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/override.rst @@ -0,0 +1,79 @@ +.. _reference_lua-box_iproto_override: + +box.iproto.override() +===================== + +.. module:: box.iproto + +.. function:: override(request_type, handler) + + Since version :doc:`2.11.0 `. + Set a new IPROTO request handler callback for the given request type. + + :param number request_type: a request type code. Possible values: + + * 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): 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 mean 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 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: + + .. 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 new file mode 100644 index 0000000000..ad95a31fbc --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/protocol_features.rst @@ -0,0 +1,25 @@ +.. _reference_lua-box_iproto_protocol-features: + +box.iproto.protocol_features +============================ + +.. module:: box.iproto + +.. data:: protocol_features + + The set of IPROTO protocol features supported by the server. + Learn more: :ref:`net.box features `, `src/box/iproto_features.h `__, + and `iproto_features_resolve() `__. + + **Example** + + .. 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 new file mode 100644 index 0000000000..947c23d433 --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/protocol_version.rst @@ -0,0 +1,20 @@ +.. _reference_lua-box_iproto_version: + +box.iproto.protocol_version +=========================== + +.. module:: box.iproto + +.. data:: protocol_version + + The current IPROTO protocol version of the server. + Learn more: :ref:`IPROTO_ID `. + + **Example** + + .. code-block:: lua + + 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 new file mode 100644 index 0000000000..ccfa8c7476 --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/raft.rst @@ -0,0 +1,24 @@ +.. _reference_lua-box_iproto_raft: + +box.iproto.raft +=============== + +.. module:: box.iproto + +.. data:: raft_key + + Contains the keys from the ``IPROTO_RAFT_*`` requests. + Learn more: :ref:`Synchronous replication keys `. + + **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 new file mode 100644 index 0000000000..4ca03be0e2 --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/request_type.rst @@ -0,0 +1,24 @@ +.. _reference_lua-box_iproto_type: + +box.iproto.type +=============== + +.. module:: box.iproto + +.. data:: type + + Contains all available request types. + Learn more about the requests: :ref:`Client-server requests and responses `. + + **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 new file mode 100644 index 0000000000..74226785e5 --- /dev/null +++ b/doc/reference/reference_lua/box_iproto/send.rst @@ -0,0 +1,66 @@ +.. _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. + 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: 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 + + :return: 0 on success, otherwise an error is raised + :rtype: number + + **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 `__. + + **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 }) diff --git a/doc/reference/reference_lua/box_session/id.rst b/doc/reference/reference_lua/box_session/id.rst index 9d383e4436..bc871e5118 100644 --- a/doc/reference/reference_lua/box_session/id.rst +++ b/doc/reference/reference_lua/box_session/id.rst @@ -1,14 +1,14 @@ -.. _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 session identifier; 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