Skip to content
Snippets Groups Projects
Commit 324872ab authored by Vladimir Davydov's avatar Vladimir Davydov Committed by Vladimir Davydov
Browse files

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
parent bd64985a
No related branches found
No related tags found
No related merge requests found
Loading
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment