From afca3147b03c730f07e98346239052519c934cf0 Mon Sep 17 00:00:00 2001 From: Kseniia Antonova Date: Fri, 4 Apr 2025 16:30:13 +0300 Subject: [PATCH] Clarify info in the `box.session` module - Update description in `box.session.su()`, `box.session.user()`, `box.session.uid()`, and `box.session.euid()` - Add `box.session.effective_user()` page Fixes #5062 --- doc/reference/reference_lua/box_session.rst | 9 ++- .../box_session/effective_user.rst | 18 +++++ .../reference_lua/box_session/euid.rst | 36 +++++----- .../reference_lua/box_session/su.rst | 72 +++++++++++++------ .../reference_lua/box_session/uid.rst | 6 +- .../reference_lua/box_session/user.rst | 17 +++-- .../reference/reference_lua/box_session/su.po | 16 ++--- 7 files changed, 116 insertions(+), 58 deletions(-) create mode 100644 doc/reference/reference_lua/box_session/effective_user.rst diff --git a/doc/reference/reference_lua/box_session.rst b/doc/reference/reference_lua/box_session.rst index 050356bf99..3ca865b1ee 100644 --- a/doc/reference/reference_lua/box_session.rst +++ b/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 diff --git a/doc/reference/reference_lua/box_session/effective_user.rst b/doc/reference/reference_lua/box_session/effective_user.rst new file mode 100644 index 0000000000..cf72fbc89d --- /dev/null +++ b/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 ` is changed temporarily using the :ref:`box.session.su() ` method, + `box.session.effective_user()` shows this change. + + See also: :ref:`box.session.euid() ` + + :return: the current effective user's name + + :rtype: string \ No newline at end of file diff --git a/doc/reference/reference_lua/box_session/euid.rst b/doc/reference/reference_lua/box_session/euid.rst index b76dfe626a..9817253f1b 100644 --- a/doc/reference/reference_lua/box_session/euid.rst +++ b/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 `. + :return: the :ref:`effective user ` ID of the :ref:`current user `. + 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) ` - -- 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() `. + 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}) ` - 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 diff --git a/doc/reference/reference_lua/box_session/su.rst b/doc/reference/reference_lua/box_session/su.rst index 975d8d835e..696e9beb1f 100644 --- a/doc/reference/reference_lua/box_session/su.rst +++ b/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 ` -- this is analogous to the Unix command ``su``. - Or, if function-to-execute is specified, - change Tarantool's :ref:`current user ` - 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() ` ignores this change. + - :ref:`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 ... diff --git a/doc/reference/reference_lua/box_session/uid.rst b/doc/reference/reference_lua/box_session/uid.rst index 2c96e31b01..5e3db9a5d9 100644 --- a/doc/reference/reference_lua/box_session/uid.rst +++ b/doc/reference/reference_lua/box_session/uid.rst @@ -1,9 +1,7 @@ +.. _box_session-uid: -.. _box_session-uid: - -================================================================================ box.session.uid() -================================================================================ +================= .. module:: box.session diff --git a/doc/reference/reference_lua/box_session/user.rst b/doc/reference/reference_lua/box_session/user.rst index 18fda311d6..840b25a8bc 100644 --- a/doc/reference/reference_lua/box_session/user.rst +++ b/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 `. + If the current user is changed temporarily using the :ref:`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() ` :return: the name of the :ref:`current user ` diff --git a/locale/ru/LC_MESSAGES/reference/reference_lua/box_session/su.po b/locale/ru/LC_MESSAGES/reference/reference_lua/box_session/su.po index 4d21e854f6..32e003da9e 100644 --- a/locale/ru/LC_MESSAGES/reference/reference_lua/box_session/su.po +++ b/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 ` temporarily while executing the function -- " "this is analogous to the Unix command ``sudo``." msgstr "" -"Или, если указана выполняемая функция (function-to-execute), временное " +"Или, если указана выполняемая функция (`function-to-execute`), временное " "изменение :ref:`текущего пользователя ` 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"