tarantool / tarantool / 5878620662

88%

push

github

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]: ... (continued)

63801 of 115440 branches covered (55.27%)

64 of 64 new or added lines in 2 files covered. (100.0%)

95494 of 110712 relevant lines covered (86.25%)

3023988.77 hits per line