Document `box.session.new` function

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 https://github.com/tarantool/tarantool/commit/324872ab22b36e743eecc0a73cb8a7f0c162b848.

Start with the box_session root document linked in the issue and review its existing function entries and cross-references. Document box.session.new with its options, return behavior, errors, example, and socket lifecycle notes. Done means the new function is included consistently in that reference section with working links and formatted Lua documentation.