Skip to content

Clarify info in the box.session module #5065

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: latest
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions doc/reference/reference_lua/box_session.rst
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,9 @@ Below is a list of all ``box.session`` functions and members.
* - :doc:`./box_session/user`
- Get the current user's name

* - :doc:`./box_session/effective_user`
- Get the current effective user's name

* - :doc:`./box_session/type`
- Get the connection type or cause of action

Expand All @@ -49,7 +52,7 @@ Below is a list of all ``box.session`` functions and members.
- Get the current user's ID

* - :doc:`./box_session/euid`
- Get the current effective user's ID
- Get the current effective user's ID

* - :doc:`./box_session/storage`
- Table with session-specific names and values
Expand All @@ -61,10 +64,10 @@ Below is a list of all ``box.session`` functions and members.
- Define a disconnect trigger

* - :doc:`./box_session/on_auth`
- Define an authentication trigger
- Define an authentication trigger

* - :doc:`./box_session/on_access_denied`
- Define a trigger to report restricted actions
- Define a trigger to report restricted actions

* - :doc:`./box_session/push`
- (Deprecated) Send an out-of-band message
Expand Down
18 changes: 18 additions & 0 deletions doc/reference/reference_lua/box_session/effective_user.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
.. _box_session-effective_user:

box.session.effective_user()
============================

.. module:: box.session

.. function:: effective_user()

Return the name of the effective user - the .
If the :ref:`current user <authentication-users>` is changed temporarily using the :ref:`box.session.su() <box_session-su>` method,
`box.session.effective_user()` shows this change.

See also: :ref:`box.session.euid() <box_session-euid>`

:return: the current effective user's name

:rtype: string
35 changes: 18 additions & 17 deletions doc/reference/reference_lua/box_session/euid.rst
Original file line number Diff line number Diff line change
@@ -1,34 +1,35 @@
.. _box_session-euid:

.. _box_session-euid:

================================================================================
box.session.euid()
================================================================================
==================

.. module:: box.session

.. function:: euid()

:return: the effective user ID of the :ref:`current user <authentication-users>`.
:return: the :ref:`effective user <box_session-effective_user>` ID of the :ref:`current user <authentication-users>`.

This is the same as :doc:`/reference/reference_lua/box_session/uid`, except
in two cases:
two cases:

* The first case: if the call to ``box.session.euid()`` is within
* ``box.session.euid()`` is called within
a function invoked by
:doc:`box.session.su(user-name, function-to-execute) </reference/reference_lua/box_session/su>`
-- in that case, ``box.session.euid()`` returns the ID of the changed user
(the user who is specified by the ``user-name`` parameter of the ``su``
function) but ``box.session.uid()`` returns the ID of the original user
(the user who is calling the ``su`` function).
:doc:`box.session.su() </reference/reference_lua/box_session/su>`.
In this case:

- ``box.session.euid()`` returns the ID of the changed user
(the user who is specified by the ``user-name`` parameter of the ``box.session.su()`` function).
- ``box.session.uid()`` returns the ID of the original user
(the user who calls the ``box.session.su()`` function).

* The second case: if the call to ``box.session.euid()`` is within
* ``box.session.euid()`` is called within
a function specified with
:doc:`box.schema.func.create(function-name, {setuid= true}) </reference/reference_lua/box_schema/func_create>`
and the binary protocol is in use
-- in that case, ``box.session.euid()`` returns the ID of the user who
created "function-name" but ``box.session.uid()`` returns the ID of the
the user who is calling "function-name".
and the binary protocol is in use.
In this case:

- ``box.session.euid()`` returns the ID of the user who created ``function-name``.
- ``box.session.uid()`` returns the ID of the user who calls ``function-name``.

:rtype: number

Expand Down
72 changes: 52 additions & 20 deletions doc/reference/reference_lua/box_session/su.rst
Original file line number Diff line number Diff line change
@@ -1,43 +1,75 @@
.. _box_session-su:

.. _box_session-su:

================================================================================
box.session.su()
================================================================================
================

.. module:: box.session
.. module:: box.session

.. function:: su(user-name [, function-to-execute])
.. function:: su(user-name [, function-to-execute])

Change Tarantool's :ref:`current user <authentication-users>` --
this is analogous to the Unix command ``su``.

Or, if function-to-execute is specified,
change Tarantool's :ref:`current user <authentication-users>`
temporarily while executing the function --
Or, if the ``function-to-execute`` option is specified,
change Tarantool's current user temporarily while executing the function --
this is analogous to the Unix command ``sudo``.
If the user is changed temporarily:

- :ref:`box.session.user() <box_session-user>` ignores this change.
- :ref:`box.session.effective_user() <box_session-effective_user>` shows this change.


:param string user-name: name of a target user
:param function-to-execute: name of a function, or definition of a function.
:param function-to-execute: a function object.
Additional parameters may be passed to
``box.session.su``, they will be interpreted
as parameters of function-to-execute.
``box.session.su()``, they will be interpreted
as parameters of ``function-to-execute``.

**Example 1**

Change Tarantool's current user to ``guest``:

.. code-block:: tarantoolsession

app:instance001> box.session.su('guest')
---
...

**Example 2**

Change Tarantool's current user to ``temporary_user`` temporarily:

**Example:**
.. code-block:: tarantoolsession

.. code-block:: tarantoolsession
app:instance001> function get_current_user() return box.session.user() end
---
...

app:instance001> function get_effective_user() return box.session.effective_user() end
---
...

app:instance001> get_current_user()
---
- admin
...

app:instance001> box.session.su('temporary_user', get_current_user)
---
- admin
...

tarantool> function f(a) return box.session.user() .. a end
app:instance001> box.session.su('temporary_user', get_effective_user)
---
- temporary_user
...

tarantool> box.session.su('guest', f, '-xxx')
app:instance001> box.session.su('temporary_user', get_effective_user, '-xxx')
---
- guest-xxx
- temporary_user-xxx
...

tarantool> box.session.su('guest',function(...) return ... end,1,2)
app:instance001> box.session.su('temporary_user', function(...) return box.session.user() end)
---
- 1
- 2
- admin
...
6 changes: 2 additions & 4 deletions doc/reference/reference_lua/box_session/uid.rst
Original file line number Diff line number Diff line change
@@ -1,9 +1,7 @@
.. _box_session-uid:

.. _box_session-uid:

================================================================================
box.session.uid()
================================================================================
=================

.. module:: box.session

Expand Down
17 changes: 11 additions & 6 deletions doc/reference/reference_lua/box_session/user.rst
Original file line number Diff line number Diff line change
@@ -1,13 +1,18 @@
.. _box_session-user:

.. _box_session-user:

================================================================================
box.session.user()
================================================================================
==================

.. module:: box.session

.. function:: user()

.. module:: box.session
Return the name of the :ref:`current Tarantool user <authentication-users>`.
If the current user is changed temporarily using the :ref:`box.session.su() <box_session-su>` method,
`box.session.user()` ignores this change.
In this case, ``box.session.user()`` returns the initial current user (the user who calls the ``box.session.su()`` function).

.. function:: user()
See also: :ref:`box.session.uid() <box_session-uid>`

:return: the name of the :ref:`current user <authentication-users>`

Expand Down
16 changes: 8 additions & 8 deletions locale/ru/LC_MESSAGES/reference/reference_lua/box_session/su.po
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,11 @@ msgstr ""
" аналогично Unix-команде ``su``."

msgid ""
"Or, if function-to-execute is specified, change Tarantool's :ref:`current "
"Or, if the `function-to-execute` option is specified, change Tarantool's :ref:`current "
"user <authentication-users>` temporarily while executing the function -- "
"this is analogous to the Unix command ``sudo``."
msgstr ""
"Или, если указана выполняемая функция (function-to-execute), временное "
"Или, если указана выполняемая функция (`function-to-execute`), временное "
"изменение :ref:`текущего пользователя <authentication-users>` Tarantool во"
" время выполнения функции – аналогично Unix-команде ``sudo``."

Expand All @@ -26,15 +26,15 @@ msgstr "целевое имя пользователя"

msgid ""
"name of a function, or definition of a function. Additional parameters may "
"be passed to ``box.session.su``, they will be interpreted as parameters of "
"function-to-execute."
"be passed to ``box.session.su()``, they will be interpreted as parameters of "
"`function-to-execute`."
msgstr ""
"имя функции или определение функции. Дополнительные параметры могут "
"передаваться в ``box.session.su``, они будут интерпретироваться как "
"имя функции или определение функции. Дополнительные параметры, переданные "
"в ``box.session.su``, интерпретируются как "
"параметры выполняемой функции."

msgid "**Example:**"
msgstr "**Пример:**"
msgid "**Examples:**"
msgstr "**Примеры:**"

msgid ""
"tarantool> function f(a) return box.session.user() .. a end\n"
Expand Down