iproto: introduce box.session.new
Closes #8801 @TarantoolBot document Title: Document `box.session.new` The new function creates a new session given a table of options: - `type`: string, optional. Default: "binary". [Type][session-type] of the new session. Currently, only "binary" is supported, which creates a new IPROTO session. - `fd`: number, mandatory. File descriptor number (fd) to be used for the new connection input-output. The fd must refer to a [socket] and be switched to the [non-blocking mode][socket-nonblock] but this isn't enforced, i.e. the user may pass an invalid fd, in which case the connection won't work as expected. - `user`: string, optional. Default: "guest". Name of the user to authenticate the new session as. Note, this doesn't prevent the other end to perform explicit [authentication]. - `storage`: table, optional. Default: empty table. Initial value of the [session-local storage][session-storage]. On success, `box.session.new` takes ownership of the `fd` and returns nothing. On failure, an error is raised. Possible errors: - Invalid option value type. - `fd` isn't specified or has an invalid value. - `box.cfg` wasn't called. - `user` doesn't exist. Example: The code below creates a TCP server that accepts all incoming IPROTO connections on port 3301, authenticates them as 'admin' and sets the session-local storage to `{foo = 'bar'}`. ```lua box.cfg() require('socket').tcp_server('localhost', 3301, function(s) box.session.new({ type = 'binary', fd = s:fd(), user = 'admin', storage = {foo = 'bar'}, }) s:detach() end) ``` Notes: - `box.cfg` must be called before using `box.session.new` to start IPROTO threads. Setting [`box.cfg.listen`][box-cfg-listen] isn't required though. - The socket object must be detached after passing its fd to `box.session.new`, otherwise the fd would be closed on Lua garbage collection. [authentication]: https://www.tarantool.io/en/doc/latest/dev_guide/internals/iproto/authentication/ [box-cfg-listen]: https://www.tarantool.io/en/doc/latest/reference/configuration/#cfg-basic-listen [session-storage]: https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_session/storage/ [session-type]: https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_session/type/ [socket]: https://www.tarantool.io/en/doc/latest/reference/reference_lua/socket/ [socket-nonblock]: https://www.tarantool.io/en/doc/latest/reference/reference_lua/socket/#socket-nonblock
Showing
- changelogs/unreleased/gh-8801-iproto-session-from-fd.md 4 additions, 0 deletionschangelogs/unreleased/gh-8801-iproto-session-from-fd.md
- src/box/iproto.cc 99 additions, 7 deletionssrc/box/iproto.cc
- src/box/iproto.h 25 additions, 0 deletionssrc/box/iproto.h
- src/box/lua/iproto.c 52 additions, 10 deletionssrc/box/lua/iproto.c
- src/box/lua/session.lua 25 additions, 0 deletionssrc/box/lua/session.lua
- test/box-luatest/gh_7894_export_iproto_constants_and_features_test.lua 2 additions, 6 deletions...est/gh_7894_export_iproto_constants_and_features_test.lua
- test/box-luatest/gh_8801_iproto_session_from_fd_test.lua 220 additions, 0 deletionstest/box-luatest/gh_8801_iproto_session_from_fd_test.lua
Loading
Please register or sign in to comment