Document `box.session.new` function

[TarantoolBot]

Product: Tarantool
Since: 3.0
Root document: https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_session/
SME: @ locker

Details

The new function creates a new session given a table of options:

• type: string, optional. Default: "binary". 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 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.

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'}.

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 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.

Requested by @locker in tarantool/tarantool@324872a.