Deprecate box.session.push() (#4695)

Resolves #3615

Author: p7nov

Diff for: doc/reference/configuration/configuration_reference.rst

@@ -529,6 +529,7 @@ The ``compat`` section defines values of the :ref:`compat <compat-module>` modul
     -   ``new``: raise an error
     -   ``old``: do not raise an error
 
+    See also: :ref:`compat-option-session-push-deprecation`
 
     |
     | Type: string

Diff for: doc/reference/reference_capi/box.rst

@@ -192,6 +192,8 @@
 
 .. c:function:: int box_session_push(const char *data, const char *data_end)
 
+    **Deprecated since** :doc:`3.0.0 </release/3.0.0>`.
+
     Since version :doc:`2.4.1 </release/2.4.1>`. Push MessagePack data into
     a session data channel -- socket, console or
     whatever is behind the session. Behaves just like Lua

Diff for: doc/reference/reference_lua/box_session.rst

@@ -67,7 +67,7 @@ Below is a list of all ``box.session`` functions and members.
            - 	Define a trigger to report restricted actions
 
         *  - :doc:`./box_session/push`
-           - Send an out-of-band message
+           - (Deprecated) Send an out-of-band message
 
 .. toctree::
     :hidden:

Diff for: doc/reference/reference_lua/box_session/push.rst

@@ -10,6 +10,8 @@ box.session.push()
 
 .. function:: box.session.push(message [, sync])
 
+    **Deprecated since** :doc:`3.0.0 </release/3.0.0>`.
+
     Generate an out-of-band message. By "out-of-band" we mean an extra
     message which supplements what is passed in a network via the usual
     channels. Although ``box.session.push()`` can be called at any time, in

Diff for: doc/reference/reference_lua/compat.rst

@@ -74,6 +74,7 @@ Below are the available ``compat`` options:
 * :doc:`fiber_slice_default <./compat/fiber_slice_default>`
 * :doc:`binary_data_decoding <./compat/binary_data_decoding>`
 * :doc:`box_info_cluster_meaning <./compat/box_info_cluster_meaning>`
+* :doc:`box_session_push_deprecation <./compat/box_session_push_deprecation>`
 
 ..  toctree::
     :hidden:
@@ -85,4 +86,5 @@ Below are the available ``compat`` options:
     compat/sql_seq_scan_default
     compat/fiber_slice_default
     compat/binary_data_decoding
+    compat/box_session_push_deprecation
     compat/compat_tutorial

Diff for: doc/reference/reference_lua/compat/box_session_push_deprecation.rst

@@ -0,0 +1,47 @@
+.. _compat-option-session-push-deprecation:
+
+box.session.push() deprecation
+==============================
+
+Option: ``box_session_push_deprecation``
+
+Starting from version 3.0, Lua API function :ref:`box.session.push() <box_session-push>`
+and C API function :ref:`box_session_push() <box_box_session_push>` are deprecated.
+
+Old and new behavior
+--------------------
+
+New behavior: calling `box.session.push()` raises an error.
+
+..  code-block:: tarantoolsession
+
+    tarantool> box.session.push({1})
+    ---
+    - error: box.session.push is deprecated
+    ...
+
+Old behavior: `box.session.push()` is available to use. When it's called for the
+first time, a deprecation warning is printed to the log.
+
+..  code-block:: tarantoolsession
+
+    tarantool> box.session.push({1})
+    2024-12-18 15:42:51.537 [50750] main/104/interactive session.c:569 W> box.session.push is deprecated. Consider using box.broadcast instead.
+    %TAG !push! tag:tarantool.io/push,2018
+    ---
+    - 1
+    ...
+    ---
+    - true
+    ...
+
+Known compatibility issues
+--------------------------
+
+At this point, no incompatible modules are known.
+
+Detecting issues in your codebase
+---------------------------------
+
+If your application uses `box.session.push()`, consider rewriting it using
+:ref:`box.broadcast() <box-broadcast>`.