File 1432-ssh-improve-docs-of-ssh-keep-alive.patch of Package erlang

From 51e2907d2610d947586ef0a6e9e1c18ebb8d706f Mon Sep 17 00:00:00 2001
From: Alexandre Rodrigues <alexandrejbr@live.com>
Date: Wed, 13 Aug 2025 15:55:12 +0200
Subject: [PATCH 02/20] ssh: improve docs of ssh keep alive

---
 lib/ssh/src/ssh.hrl                    | 21 +++++++++++++++++++++
 lib/ssh/src/ssh_connection_handler.erl | 14 ++++++++------
 2 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/lib/ssh/src/ssh.hrl b/lib/ssh/src/ssh.hrl
index 7b9c292d63..be99ba3d2a 100644
--- a/lib/ssh/src/ssh.hrl
+++ b/lib/ssh/src/ssh.hrl
@@ -378,6 +378,7 @@ further explained below.
       | auth_methods_common_option()
       | inet_common_option()
       | fd_common_option()
+      | alive_common_option()
         .
 
 -doc """
@@ -538,6 +539,26 @@ protocol).
 -doc(#{group => <<"Common Options">>}).
 -type fd_common_option() :: {fd, gen_tcp:socket()} .
 
+-doc """
+This option is used to configure the alive messages. Alive messages are sent through the encrypted
+channel and are typically used to detect that a connection became unresponsive.
+
+The first value of the tuple sets the maximum number
+of alive messages which may be sent without the client/server receiving any messages back
+from the peer. If this threshold is reached the connection will be terminated.
+The second value of the tuple sets the timeout interval, in seconds, after which, if no data
+has been received from the peer, the client/server will send a message to request a response
+from the peer.
+
+The default is {3, infinity}, which means that alive messages will not be sent to the peer,
+since the `AliveInterval` is set to `infinity`.
+
+No alive messages are sent during renegotiation, however, a timeout derived from the alive parameters
+is set to ensure that if the connection becomes unresponsive during renegotiation, the client/server
+disconnect.
+""".
+-doc(#{group => <<"Common Options">>}).
+-type alive_common_option() :: {AliveCountMax::pos_integer(), AliveInterval::timeout()}.
 
 -doc """
 Experimental options that should not to be used in products.
diff --git a/lib/ssh/src/ssh_connection_handler.erl b/lib/ssh/src/ssh_connection_handler.erl
index 855783b7c7..614adfad68 100644
--- a/lib/ssh/src/ssh_connection_handler.erl
+++ b/lib/ssh/src/ssh_connection_handler.erl
@@ -2187,13 +2187,11 @@ update_inet_buffers(Socket) ->
 %%%----------------------------------------------------------------
 %%% Keep-alive
 
-%% @doc Reset the last_alive timer on #data{ssh_params=#ssh{}} record
-%% @private
+%% Reset the last_alive timer on #data{ssh_params=#ssh{}} record
 reset_alive(D = #data{ssh_params = Ssh}) ->
     D#data{ssh_params = reset_alive_ssh_params(Ssh)}.
 
-%% @doc Update #data.ssh_params last_alive on an incoming SSH message
-%% @private
+%% Update #data.ssh_params last_alive on an incoming SSH message
 reset_alive_ssh_params(SSH = #ssh{alive_interval = AliveInterval})
   when is_integer(AliveInterval) ->
     Now = erlang:monotonic_time(milli_seconds),
@@ -2202,7 +2200,7 @@ reset_alive_ssh_params(SSH = #ssh{alive_interval = AliveInterval})
 reset_alive_ssh_params(SSH) ->
     SSH.
 
-%% @doc Returns a pair of {TriggerFlag, Actions} where trigger flag indicates that
+%% Returns a pair of {TriggerFlag, Actions} where trigger flag indicates that
 %% the timeout has been triggered already and it is time to disconnect, and
 %% Actions may contain a new timeout action to check for the timeout again.
 get_next_alive_timeout(#ssh{alive_interval = AliveInterval,
@@ -2227,7 +2225,6 @@ triggered_alive(StateName, D0 = #data{},
     Details = "Alive timeout triggered",
     {Shutdown, D} = ?send_disconnect(?SSH_DISCONNECT_CONNECTION_LOST, Details, StateName, D0),
     {stop, Shutdown, D};
-
 triggered_alive(_StateName, Data, _Ssh = #ssh{alive_sent_probes = SentProbes}, Actions) ->
     Data1 = send_msg(?KEEP_ALIVE_REQUEST, Data),
     Ssh = Data1#data.ssh_params,
@@ -2237,6 +2234,11 @@ triggered_alive(_StateName, Data, _Ssh = #ssh{alive_sent_probes = SentProbes}, A
                    last_alive_at = Now},
     {keep_state, Data1#data{ssh_params = Ssh1}, Actions}.
 
+%% Keep-alive messages can't be sent during renegotiation, but since this
+%% feature acts as a keep-alive and a timeout, an equivalent timeout is
+%% established for the renegotiation procedure if alive is enabled.
+%% For simplicity the timeout value is derived from alive_interval and
+%% alive_count.
 renegotiation_alive_timeout(#ssh{alive_interval = infinity}) ->
     infinity;
 renegotiation_alive_timeout(#ssh{alive_interval = Interval, alive_count = Count}) ->
-- 
2.51.0