Clarify info in the box.session module (#5065)

- Update description in `box.session.su()`, `box.session.user()`, `box.session.uid()`, and `box.session.euid()`
- Add `box.session.effective_user()` page

Fixes #5062

Author: xuniq

doc/reference/reference_lua/box_session.rst

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

doc/reference/reference_lua/box_session/effective_user.rst

@@ -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* -- this user determines the process's permissions at any given moment.
+    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

doc/reference/reference_lua/box_session/euid.rst

@@ -1,34 +1,36 @@
+..  _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>`.
 
+    The system uses the effective user ID to determine the process's permissions at any given moment.
     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
 

doc/reference/reference_lua/box_session/su.rst

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

doc/reference/reference_lua/box_session/uid.rst

@@ -1,9 +1,7 @@
+..  _box_session-uid:
 
-.. _box_session-uid:
-
-================================================================================
 box.session.uid()
-================================================================================
+=================
 
 .. module:: box.session
 

doc/reference/reference_lua/box_session/user.rst

@@ -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>`
 

locale/ru/LC_MESSAGES/reference/reference_lua/box_session/su.po

@@ -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``."
 
@@ -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"