diff --git a/CHANGELOG.md b/CHANGELOG.md index 33aa193..80f27ed 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - A `tarantool.ttPath` configuration option can now be used to specify a path to TT utility if it's not available in the `$PATH`. +- Builtin `socket` module declarations. +- Builtin `xlog` module declarations. +- Builtin `box.iproto` submodule declarations. +- `box.tuple.format` submodule. +- Various `box.space.format` fields (e.g. `foreign_keys`, `constraint`). ### Changed diff --git a/tarantool-annotations/Library/box/iproto.lua b/tarantool-annotations/Library/box/iproto.lua new file mode 100644 index 0000000..bf8f259 --- /dev/null +++ b/tarantool-annotations/Library/box/iproto.lua @@ -0,0 +1,445 @@ +---@meta + +---# Builtin `box.iproto` submodule +--- +---*Since 2.11.0* +--- +---The `box.iproto` submodule provides the ability to work with the network subsystem of Tarantool. +---It allows you to extend the [`IPROTO`](doc://box_protocol) functionality from Lua. +--- +---With this submodule, you can: +--- +---* [Parse unknown IPROTO request types](doc://reference_lua-box_iproto_override) +---* [Send arbitrary IPROTO packets](doc://reference_lua-box_iproto_send) +---* [Override the behavior](doc://reference_lua-box_iproto_override) of the existing and unknown request types in the binary protocol +--- +---The submodule exports all IPROTO [constants](doc://internals-box_protocol) and [doc://features](internals-iproto-keys-features) to Lua. +box.iproto = {} + +---Send an IPROTO packet over the session's socket with the given MsgPack header and body. +--- +---*Since 2.11.0*. +--- +---The header and body contain exported IPROTO constants from the [box.iproto()](doc://box_iproto) submodule. +--- +---Possible IPROTO constant formats: +--- +---* A constant from the corresponding [box.iproto](doc://box_iproto) subnamespace (`box.iproto.SCHEMA_VERSION`, `box.iproto.REQUEST_TYPE`) +--- +---Send an [IPROTO](internals-iproto-format) packet over the session\'s socket with the given MsgPack header and body. The header and body contain exported IPROTO constants from the [box.iproto()](box_iproto) submodule. Possible IPROTO constant formats: +--- +---**Possible errors:** +--- +---* `ER_SESSION_CLOSED` -- the session is closed. +---* `ER_NO_SUCH_SESSION` -- the session does not exist. +---* `ER_MEMORY_ISSUE` -- out-of-memory limit has been reached. +---* `ER_WRONG_SESSION_TYPE` -- the session type is not binary. +--- +---The function works for binary sessions only. For details, see [box.session.type()](doc://box_session-type). +--- +---For details, see `src/box/errcode.h `__. +--- +---**Examples:** +--- +---Send a packet using Lua tables and string IPROTO constants as keys: +--- +--- ```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: +--- +--- ```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: +--- +--- ```lua +--- box.iproto.send(box.session.id(), +--- { request_type = box.iproto.type.OK, +--- sync = 10, +--- schema_version = box.info.schema_version }) +--- ``` +--- +---@param sid number the IPROTO session identifier (see [box.session.id()](doc://box_session-id)) +---@param header table | string ader: a request header encoded as MsgPack +---@param body? table | string a request body encoded as MsgPack +---@return integer 0 on success, otherwise an error is raised +function box.iproto.send(sid, header, body) end + +---Contains the keys from the IPROTO_BALLOT requests. +--- +---Learn more: [IPROTO_BALLOT keys](doc://internals-iproto-keys-ballot). +--- +---**Example:** +--- +--- ```lua +--- tarantool> box.iproto.ballot_key.IS_RO_CFG +--- --- +--- - 1 +--- ... +--- tarantool> box.iproto.ballot_key.VCLOCK +--- --- +--- - 2 +--- ... +--- ``` +--- +---@enum box.iproto.ballot_key +box.iproto.ballot_key = { + CAN_LEAD = 7, + INSTANCE_NAME = 10, + IS_ANON = 5, + IS_BOOTED = 6, + IS_RO = 4, + IS_RO_CFG = 1, + REGISTERED_REPLICA_UUIDS = 9, + BOOTSTRAP_LEADER_UUID = 8, + VCLOCK = 2, + GC_VCLOCK = 3, +} + +---@alias box.iproto.feature +---| 'transactions' +---| 'watchers' +---| 'error_extension' +---| 'call_arg_tuple_extension' +---| 'pagination' +---| 'is_sync' +---| 'space_and_index_names' +---| 'insert_arrow' +---| 'streams' +---| 'watch_once' +---| 'call_ret_tuple_extension' +---| 'fetch_snapshot_cursor' +---| 'dml_tuple_extension' +---| string + +---Contains the IPROTO protocol features that are supported by the server. +--- +---Each feature is mapped to its corresponding code. +--- +---Learn more: [IPROTO_FEATURES](doc://internals-iproto-keys-features). +--- +---The features in the namespace are written: +--- +---* In lowercase letters +---* Without the `IPROTO_FEATURE_` prefix +--- +---**Example:** +--- +--- ```lua +--- tarantool> box.iproto.feature.streams +--- --- +--- - 0 +--- ... +--- tarantool> box.iproto.feature.transactions +--- --- +--- - 1 +--- ... +--- ``` +--- +---@type table +box.iproto.feature = {} + +---Contains the flags from the `IPROTO_FLAGS` key. +--- +---Learn more: [IPROTO_FLAGS key](doc://box_protocol-flags). +--- +---**Example:** +--- +--- ```lua +--- tarantool> box.iproto.flag.COMMIT +--- --- +--- - 1 +--- ... +--- tarantool> box.iproto.flag.WAIT_SYNC +--- --- +--- - 2 +--- ... +--- ``` +--- +---@enum box.iproto.flag +box.iproto.flag = { + WAIT_SYNC = 2, + COMMIT = 1, + WAIT_ACK = 4, +} + +---Contains all available request keys, except raft, metadata, and ballot keys. +--- +---Learn more: [Keys used in requests and responses](doc://internals-iproto-keys). +--- +---**Example:** +--- +--- ```lua +--- tarantool> box.iproto.key.SYNC +--- --- +--- - 1 +--- ... +--- ``` +--- +---@enum box.iproto.key +box.iproto.key = { + SCHEMA_VERSION = 5, + ERROR_24 = 49, + STREAM_ID = 10, + STMT_ID = 67, + BALLOT = 41, + IS_SYNC = 97, + AUTH_TYPE = 91, + TUPLE_META = 42, + SYNC = 1, + VERSION = 84, + GROUP_ID = 7, + VCLOCK = 38, + FLAGS = 9, + SQL_BIND = 65, + EVENT_DATA = 88, + SPACE_ID = 16, + TERM = 83, + EXPR = 39, + ID_FILTER = 81, + METADATA = 50, + INDEX_NAME = 95, + KEY = 32, + OPTIONS = 43, + TIMESTAMP = 4, + DATA = 48, + VCLOCK_SYNC = 90, + INSTANCE_NAME = 93, + ARROW = 54, + USER_NAME = 35, + INSTANCE_UUID = 36, + SERVER_VERSION = 6, + NEW_TUPLE = 45, + BIND_METADATA = 51, + TUPLE_FORMATS = 96, + CHECKPOINT_LSN = 100, + INDEX_BASE = 21, + FEATURES = 85, + REPLICA_ID = 2, + EVENT_KEY = 87, + IS_CHECKPOINT_JOIN = 98, + REQUEST_TYPE = 0, + LIMIT = 18, + OPS = 40, + TXN_ISOLATION = 89, + INDEX_ID = 17, + SQL_INFO = 66, + AFTER_POSITION = 46, + AFTER_TUPLE = 47, + TUPLE = 33, + TIMEOUT = 86, + FUNCTION_NAME = 34, + REPLICA_ANON = 80, + CHECKPOINT_VCLOCK = 99, + OFFSET = 19, + OLD_TUPLE = 44, + LSN = 3, + TSN = 8, + ITERATOR = 20, + FETCH_POSITION = 31, + BIND_COUNT = 52, + POSITION = 53, + SQL_TEXT = 64, + ERROR = 82, + REPLICASET_NAME = 92, + SPACE_NAME = 94, + REPLICASET_UUID = 37, +} + +---Contains the `IPROTO_FIELD_*` keys, which are nested in the IPROTO_METADATA key. +--- +---**Example:** +--- +--- ```lua +--- tarantool> box.iproto.metadata_key.NAME +--- --- +--- - 0 +--- ... +--- tarantool> box.iproto.metadata_key.TYPE +--- --- +--- - 1 +--- ... +--- ``` +--- +---@enum box.iproto.metadata_key +box.iproto.metadata_key = { + COLL = 2, + SPAN = 5, + IS_AUTOINCREMENT = 4, + TYPE = 1, + NAME = 0, + IS_NULLABLE = 3, +} + +---Set a new IPROTO request handler callback for the given request type. +--- +---*Since 2.11.0*. +--- +---**Possible errors:** +--- +---If a Lua handler throws an exception: +---* `ER_PROC_LUA` -- an exception is thrown from a Lua handler, diagnostic is not set +---* Other diagnostics from `src/box/errcode.h` -- when diagnostic is set +--- +---**Warning:** +--- +---When using `box.iproto.override()`, it is important that you follow the wire protocol. The server response should match the return value types of the corresponding request type. Otherwise, it could lead to peer breakdown or undefined behavior. +--- +---**Example:** +--- +--- ```lua +--- local function iproto_select_handler_lua(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 +--- +--- box.iproto.override(box.iproto.type.SELECT, iproto_select_handler_lua) +--- box.iproto.override(box.iproto.type.SELECT, nil) -- Reset handler +--- box.iproto.override(box.iproto.type.UNKNOWN, iproto_unknown_request_handler_lua) +--- ``` +--- +---@param request_type box.iproto.type +---@param handler? fun(sid, header: userdata, body: userdata): bool request handler that returns `true` on success, otherwise `false`. On `false`, there is a fallback +function box.iproto.override(request_type, handler) end + +---The set of IPROTO protocol features supported by the server. +--- +---Learn more: [net.box features](doc://net_box-connect). +--- +---**Example:** +--- +--- ```lua +--- tarantool> box.iproto.protocol_features +--- --- +--- - transactions: true +--- watchers: true +--- error_extension: true +--- streams: true +--- pagination: true +--- ... +--- ``` +--- +---@type table +box.iproto.protocol_features = {} + +---The current IPROTO protocol version of the server. +--- +---Learn more: [IPROTO_ID](doc://box_protocol-id). +--- +--- **Example:** +--- +--- ```lua +--- tarantool> box.iproto.protocol_version +--- --- +--- - 4 +--- ... +--- ``` +--- +---@type integer +box.iproto.protocol_version = nil + +---Contains the keys from the `IPROTO_RAFT_*` requests. +--- +---Learn more: [Synchronous replication keys](doc://internals-iproto-keys-synchro-replication). +--- +---**Example:** +--- +--- ```lua +--- tarantool> box.iproto.raft_key.TERM +--- --- +--- - 0 +--- ... +--- tarantool> box.iproto.raft_key.VOTE +--- --- +--- - 1 +--- ... +--- ``` +--- +---@enum box.iproto.raft_key +box.iproto.raft_key = { + STATE = 2, + LEADER_ID = 4, + VOTE = 1, + TERM = 0, + VCLOCK = 3, + IS_LEADER_SEEN = 5, +} + +---Contains all available request types. +--- +---Learn more: [Client-server requests and responses](doc://internals-requests_responses). +--- +---**Example:** +--- +--- ```lua +--- tarantool> box.iproto.type.UNKNOWN +--- --- +--- - -1 +--- ... +--- tarantool> box.iproto.type.CHUNK +--- --- +--- - 128 +--- ... +--- ``` +--- +---@enum box.iproto.type +box.iproto.type = { + NOP = 12, + INSERT = 2, + EXECUTE = 11, + PREPARE = 13, + VOTE = 68, + RAFT_PROMOTE = 31, + UPDATE = 4, + RAFT_DEMOTE = 32, + SELECT = 1, + VOTE_DEPRECATED = 67, + EVENT = 76, + PING = 64, + FETCH_SNAPSHOT = 69, + RAFT_ROLLBACK = 41, + WATCH = 74, + INSERT_ARROW = 17, + BEGIN = 14, + ROLLBACK = 16, + REGISTER = 70, + JOIN_SNAPSHOT = 72, + UNKNOWN = -1, + JOIN_META = 71, + SUBSCRIBE = 66, + CHUNK = 128, + DELETE = 5, + COMMIT = 15, + WATCH_ONCE = 77, + ID = 73, + UNWATCH = 75, + EVAL = 8, + JOIN = 65, + OK = 0, + CALL = 10, + RAFT_CONFIRM = 40, + CALL_16 = 6, + REPLACE = 3, + RAFT = 30, + TYPE_ERROR = 32768, + AUTH = 7, + UPSERT = 9, +} diff --git a/tarantool-annotations/Library/box/space.lua b/tarantool-annotations/Library/box/space.lua index 4167949..9912f37 100644 --- a/tarantool-annotations/Library/box/space.lua +++ b/tarantool-annotations/Library/box/space.lua @@ -342,10 +342,20 @@ function space_methods:bsize() end function space_methods:count(key, iterator) end +---@alias box.space.foreign_key { space: string, field: string | { [string]: string } } +---@alias box.space.collation "unicode" | "unicode_ci" +---@alias box.space.nullable_action 'none'|'rollback'|'abort'|'fail'|'ignore'|'replace'|'default' + ---@alias box.space.field_format { --- name?: string, --- type?: tuple_type_name, ---- is_nullable?: boolean +--- is_nullable?: boolean, +--- nullable_action?: box.space.nullable_action, +--- collation?: box.space.collation, +--- constraint?: string | { [string]: string }, +--- foreign_key?: box.space.foreign_key | { [string]: box.space.foreign_key }, +--- default?: any, +--- default_func?: string, ---} | [string, tuple_type_name] ---@alias box.space.format box.space.field_format[] diff --git a/tarantool-annotations/Library/box/tuple.lua b/tarantool-annotations/Library/box/tuple.lua index f687dac..39f0122 100644 --- a/tarantool-annotations/Library/box/tuple.lua +++ b/tarantool-annotations/Library/box/tuple.lua @@ -357,8 +357,9 @@ box.tuple = {} --- ---@overload fun(...: tuple_type): box.tuple ---@param value tuple_type[] +---@param options? { format?: box.tuple.format|box.tuple.field_format[] } ---@return box.tuple tuple -function box.tuple.new(value) end +function box.tuple.new(value, options) end ---Check whether a given object is a tuple cdata object. --- @@ -369,3 +370,50 @@ function box.tuple.new(value) end ---@param object any ---@return boolean is_tuple returns true if given object is box.tuple function box.tuple.is(object) end + +---# Builtin `box.tuple.format` submodule +box.tuple.format = {} + +---Tuple format. +--- +---@class box.tuple.format: userdata +local tuple_format = {} + +---@alias box.tuple.field_format box.space.field_format + +---Returns tuple format as a lua table. +--- +---@return box.tuple.field_format[] +function tuple_format:totable() end + +---Get a tuple_format iterator. +--- +---In Lua, [`lua-table-value:pairs()`](https://www.lua.org/pil/7.3.html) is a method which returns: `function`, `lua-table-value`, `nil`. +--- +---Tarantool has extended this so that `tuple_format:pairs()` returns: `function`, `tuple_format_field`, `nil`. It is useful for Lua iterators, because Lua iterators traverse a value's components until an end marker is reached. +--- +---`tuple_format:ipairs()` is the same as `pairs()`, because tuple_format fields are always integers. +--- +---@see box.tuple.format.ipairs +---@return fun(tbl: any): (integer, box.tuple.field_format) +function tuple_format:pairs() end + +---@see box.tuple.format.pairs +tuple_format.ipairs = tuple_format.pairs + +---Get the format of a tuple. +--- +---The resulting table lists the fields of a tuple (their names and types) if the format option was specified during the tuple creation. Otherwise, empty table is returned. +--- +---@return box.tuple.field_format[] # the tuple format. +function tuple_object:format() end + +---Create a new tuple format. +---@param tuple_format box.tuple.field_format[] +---@return box.tuple.format +function box.tuple.format.new(tuple_format) end + +---Check whether a given object is a tuple_format userdata object. +---@param object any +---@return boolean is_tuple_format returns true if given object is box.tuple.format +function box.tuple.format.is(object) end diff --git a/tarantool-annotations/Library/socket.lua b/tarantool-annotations/Library/socket.lua new file mode 100644 index 0000000..d3d84c6 --- /dev/null +++ b/tarantool-annotations/Library/socket.lua @@ -0,0 +1,304 @@ +---@meta + +---# Builtin `socket` module. +--- +---The `socket` module allows exchanging data via BSD sockets with a local or remote host in connection-oriented (TCP) or datagram-oriented (UDP) mode. Semantics of the calls in the `socket` API closely follow semantics of the corresponding POSIX calls. +--- +---@class socket_module +---@overload fun(): socket_object +local socket = {} + +---@class socket: table +local socket_object = {} + +---Returns file descriptor of the socket. +--- +--- The `socket` module allows exchanging data via BSD sockets with a local or remote host in connection-oriented (TCP) or datagram-oriented (UDP) mode. Semantics of the calls in the `socket` API closely follow semantics of the corresponding POSIX calls. +--- +--- The functions for setting up and connecting are `socket`, `sysconnect`, `tcp_connect`. The functions for sending data are `send`, `sendto`, `write`, `syswrite`. The functions for receiving data are `recv`, `recvfrom`, `read`. The functions for waiting before sending/receiving data are `wait`, `readable`, `writable`. The functions for setting flags are `nonblock`, `setsockopt`. The functions for stopping and disconnecting are `shutdown`, `close`. The functions for error checking are `errno`, `error`. +--- +---@return number fd file descriptor +function socket_object:fd() end + +---Connect a socket to a remote host. +--- +---@async +---@param host string URL or IP address +---@param port number | string? port number string for unix socket +---@param timeout number? number of seconds to wait +---@return socket +---@return nil, string error_message +function socket.tcp_connect(host, port, timeout) end + +---The socket.getaddrinfo() function is useful for finding information about a remote site so that the correct arguments for sock:sysconnect() can be passed. This function may use the worker_pool_threads configuration parameter. +--- +---@async +---@overload fun(host: string, port: number|string, options?: { type: string, family: string, flags: any, protocol: string }) +---@param host string URL or IP address +---@param port number|string port number as a numeric or string +---@param timeout? number maximum number of seconds to wait +---@param options? { type: string, family: string, flags: any, protocol: string } +---@return {host: string, family: string, type: string, protocol: string, port: number}[]?, string error_message +function socket.getaddrinfo(host, port, timeout, options) end + + +---@class socket.tcp_server_handler +---@field handler fun(client: socket) client handler, executed once after accept() happens (once per connection) +---@field prepare fun(server: socket): number? it may have parameters = the socket object and a table with client information; it should return either a backlog value or nothing; +---@field name string + +---The socket.tcp_server() function makes Tarantool act as a server that can accept connections. +--- +---@async +---@param host string host name or IP +---@param port number host port, may be 0 +---@param handler fun(client: socket) | socket.tcp_server_handler what to execute when a connection occurs +---@param timeout? number host resolving timeout in seconds +---@return socket +---@return nil, string error_message +function socket.tcp_server(host, port, handler, timeout) end + +---Bind a socket to the given host/port. +--- +---@param host string URL or IP address +---@param port number port number +---@return socket +---@return nil, string error_message +function socket.bind(host, port) end + +---Connect an existing socket to a remote host. The argument values are the same as in tcp_connect(). The host must be an IP address. +--- +---@param host string|number representation of an IPv4 address or an IPv6 address; or “unix/”; or number, 0 (zero), meaning “all local interfaces”; +---@param port number|string port number; or path to a unix socket.; or If a port number is 0 (zero), the socket will be bound to a random local port. +---@return boolean success +function socket_object:sysconnect(host, port) end + +---Send data over a connected socket. +---@param data string what is to be sent +---@return number # number of bytes send +---@return nil # on error +function socket_object:send(data) end + +---Send data over a connected socket. +--- +---@param data string what is to be sent +---@return number # number of bytes send +---@return nil # on error +function socket_object:write(data) end + +---Write as much data as possible to the socket buffer if non-blocking. +--- +---Rarely used. +--- +---@param data string what is to be sent +---@return number # number of bytes send +---@return nil # on error +function socket_object:syswrite(data) end + + +---Read size bytes from a connected socket. An internal read-ahead buffer is used to reduce the cost of this call. +--- +---For recv and recvfrom: use the optional size parameter to limit the number of bytes to receive. A fixed size such as 512 is often reasonable; a pre-calculated size that depends on context – such as the message format or the state of the network – is often better. For recvfrom, be aware that a size greater than the Maximum Transmission Unit can cause inefficient transport. For Mac OS X, be aware that the size can be tuned by changing sysctl net.inet.udp.maxdgram. +--- +---If size is not stated: Tarantool will make an extra call to calculate how many bytes are necessary. This extra call takes time, therefore not stating size may be inefficient. +--- +---If size is stated: on a UDP socket, excess bytes are discarded. On a TCP socket, excess bytes are not discarded and can be received by the next call. +--- +---@param size integer maximum number of bytes to receive. +---@return string result string of the requested length on success. +---@return string empty_string, integer status, integer errno, string errstr on error +function socket_object:recv(size) end + + +---Read from a connected socket until some condition is true, and return the bytes that were read +--- +---Unlike socket_object:recv (which uses an internal read-ahead buffer), socket_object:read depends on the socket's buffer. +--- +---@async +---@param limit integer maximum number of bytes to read, for example 50 means “stop after 50 bytes” +---@param timeout? number maximum number of seconds to wait, for example 50 means “stop after 50 seconds” +---@return string data in case of success +---@return string empty_string if there is nothing more to read +---@return nil # if error +function socket_object:read(limit, timeout) end + +---Read from a connected socket until some condition is true, and return the bytes that were read +--- +---Unlike socket_object:recv (which uses an internal read-ahead buffer), socket_object:read depends on the socket's buffer. +--- +---@async +---@param delimiter string separator for example '?' means “stop after a question mark” +---@param timeout? number maximum number of seconds to wait, for example 50 means “stop after 50 seconds”. +---@return string data in case of success +---@return string empty_string if there is nothing more to read +---@return nil # if error +function socket_object:read(delimiter, timeout) end + +---Read from a connected socket until some condition is true, and return the bytes that were read. +--- +---Unlike socket_object:recv (which uses an internal read-ahead buffer), socket_object:read depends on the socket's buffer. +--- +---@async +---@param options { chunk: integer?, delimiter: string? } chunk=limit and/or delimiter=delimiter, for example {chunk=5,delimiter='x'} +---@param timeout? number maximum number of seconds to wait, for example 50 means “stop after 50 seconds”. +---@return string data in case of success +---@return string empty_string if there is nothing more to read +---@return nil # if error +function socket_object:read(options, timeout) end + +---Return data from the socket buffer if non-blocking. In case the socket is blocking, sysread() can block the calling process. Rarely used. +--- +---@param size integer +---@return string data in case of success +---@return string empty_string if there is nothing more to read +---@return nil # if error +function socket_object:sysread(size) end + +---Bind a socket to the given host/port. +--- +---A UDP socket after binding can be used to receive data (see socket_object.recvfrom). +--- +---A TCP socket can be used to accept new connections, after it has been put in listen mode. +--- +---@param host string URL or IP address +---@param port integer? port number +---@return boolean success true for success, false for error. If return is false, use socket_object:errno() or socket_object:error() to see details. +function socket_object:bind(host, port) end + +---Start listening for incoming connections. +--- +---@param backlog number on Linux the listen backlog backlog may be from /proc/sys/net/core/somaxconn, on BSD the backlog may be SOMAXCONN +---@return boolean success true for success, false for error. +function socket_object:listen(backlog) end + +---Accept a new client connection and create a new connected socket. +--- +---It is good practice to set the socket's blocking mode explicitly after accepting. +--- +---@return socket client new socket if success. +---@return nil # if error +function socket_object:accept() end + +---Send a message on a UDP socket to a specified host. +--- +---@param host string URL or IP address +---@param port number port number +---@param data string what is to be sent +---@return number bytes the number of bytes sent. +---@return nil, number? status, number? errno, string? errstr on error, returns nil and may return status, errno, errstr. +function socket_object:sendto(host, port, data) end + +---Receive a message on a UDP socket. +--- +---@param size? number maximum number of bytes to receive. +---@return string message, { host: string, family: string, port: number } source on success +---@return nil, number status, number errno, string errstr on error +function socket_object:recvfrom(size) end + +---Shutdown a reading end, a writing end, or both ends of a socket. +--- +---@param how number socket.SHUT_RD, socket.SHUT_WR, or socket.SHUT_RDWR. +---@return boolean success +function socket_object:shutdown(how) end + +---Close (destroy) a socket. +--- +---A closed socket should not be used any more. +--- +---A socket is closed automatically when the Lua garbage collector removes its user data. +--- +---@return boolean success true on success, false on error. For example, if sock is already closed, sock:close() returns false. +function socket_object:close() end + +---Retrieve information about the last error that occurred on a socket, if any. +--- +---Errors do not cause throwing of exceptions so these functions are usually necessary. +--- +---@return number errno if no error 0 is returned +function socket_object:errno() end + +---Retrieve information about the last error that occurred on a socket, if any. +--- +---Errors do not cause throwing of exceptions so these functions are usually necessary. +--- +---@return string errstr +function socket_object:error() end + +---Set socket flags. +--- +---@param level any +---@param name any +---@param value any +function socket_object:setsockopt(level, name, value) end + +---Get socket flags. +--- +---@param level any +---@param name any +function socket_object:getsockopt(level, name) end + +---Set or clear the SO_LINGER flag. +--- +---@param active boolean +function socket_object:linger(active) end + +---Returns the current O_NONBLOCK value. +--- +---@return boolean nonblock_flag +function socket_object:nonblock() end + +---Sets O_NONBLOCK flag. +--- +---@param flag boolean +---@return boolean new_flag_value +function socket_object:nonblock(flag) end + +---Wait until something is readable, or until a timeout value expires. +--- +---@async +---@param timeout? number timeout in seconds +---@return boolean is_readable true if the socket is now readable, false if timeout expired; +function socket_object:readable(timeout) end + +---Wait until something is writable, or until a timeout value expires. +--- +---@async +---@param timeout? number timeout in seconds +---@return boolean is_writable true if the socket is now writable, false if timeout expired; +function socket_object:writable(timeout) end + +---Wait until something is either readable or writable, or until a timeout value expires. +--- +---@async +---@param timeout? number timeout +---@return "R"|"W"|"RW"|"" # 'R' if the socket is now readable, 'W' if the socket is now writable, 'RW' if the socket is now both readable and writable, '' (empty string) if timeout expired; +function socket_object:wait(timeout) end + + +---Get information about the near side of the connection. +--- +---The equivalent POSIX function is `getsockname()`. +--- +---@return { host: string, family: string, type: string, protocol: string, port: number } +function socket_object:name() end + +---Get information about the far side of a connection. +--- +---The equivalent POSIX function is `getpeername()`. +--- +---@return { host: string, family: string, type: string, protocol: string, port: number } +function socket_object:peer() end + +---Wait until read-or-write activity occurs for a file descriptor. +--- +---If the fd parameter is nil, then there will be a sleep until the timeout. +--- +---If the timeout parameter is nil or unspecified, then timeout is infinite. +--- +---@async +---@param fd number file descriptor +---@param read_or_write_flags "R" | "W" | "RW" | 1 | 2 | 3 # 'R' or 1 = read, 'W' or 2 = write, 'RW' or 3 = read|write. +---@param timeout? number number of seconds to wait +function socket.iowait(fd, read_or_write_flags, timeout) end + +return socket diff --git a/tarantool-annotations/Library/xlog.lua b/tarantool-annotations/Library/xlog.lua new file mode 100644 index 0000000..e44760e --- /dev/null +++ b/tarantool-annotations/Library/xlog.lua @@ -0,0 +1,48 @@ +---@meta + +---# Builtin `xlog` module. +--- +---The xlog module contains one function: `pairs()`. +--- +---It can be used to read Tarantool's [snapshot files](doc://index-box_persistence) or [write-ahead-log (WAL)](doc://internals-wal) files. Ade scription of the file format is in section [Data persistence and the WAL file format](doc://internals-data_persistence). +local xlog = {} + +---Open a file, and allow iterating over one file entry at a time. +--- +---Possible errors: File does not contain properly formatted snapshot or write-ahead-log information. +--- +---**Example:** +--- +---This will read the first write-ahead-log (WAL) file that was created in the [wal_dir](doc://cfg_basic-wal_dir) directory in our ["Getting started" exercises](doc://getting_started). +--- +---Each result from `pairs()` is formatted with MsgPack so its structure can be specified with [__serialize](doc://msgpack-serialize). +--- +--- ```lua +--- xlog = require('xlog') +--- t = {} +--- for k, v in xlog.pairs('00000000000000000000.xlog') do +--- table.insert(t, setmetatable(v, { __serialize = "map"})) +--- end +--- return t +--- ``` +--- +---The first lines of the result will look like: +--- +--- ```tarantoolsession +--- (...) +--- --- +--- - - {'BODY': {'space_id': 272, 'index_base': 1, 'key': ['max_id'], +--- 'tuple': [['+', 2, 1]]}, +--- 'HEADER': {'type': 'UPDATE', 'timestamp': 1477846870.8541, +--- 'lsn': 1, 'server_id': 1}} +--- - {'BODY': {'space_id': 280, +--- 'tuple': [512, 1, 'tester', 'memtx', 0, {}, []]}, +--- 'HEADER': {'type': 'INSERT', 'timestamp': 1477846870.8597, +--- 'lsn': 2, 'server_id': 1}} +--- ``` +--- +---@param file string +---@return fun.iterator +function xlog.paris(file) end + +return xlog diff --git a/tarantool-annotations/README.md b/tarantool-annotations/README.md index 7f8aa08..90036ff 100644 --- a/tarantool-annotations/README.md +++ b/tarantool-annotations/README.md @@ -259,6 +259,7 @@ For more information on using LSP refer to the [project's documentation](https:/ + [x] `error` + [x] `index` (partial) + [x] `info` + + [x] `iproto` + [x] `schema` (partial, `func` is missing) + [x] `session` + [x] `slab` @@ -289,14 +290,14 @@ For more information on using LSP refer to the [project's documentation](https:/ - [x] `net.box` (partial) - [ ] `pickle` - [ ] `popen` - - [ ] `socket` + - [x] `socket` - [x] `strict` - [x] `string` - [ ] `tarantool` - [x] `uri` - [ ] `utf8` - [x] `uuid` - - [ ] `xlog` + - [x] `xlog` - [x] `yaml` * Popular Tarantool rocks