Merge branch 'anders/diameter/transport_shutdown/OTP-10493' into maint

* anders/diameter/transport_shutdown/OTP-10493:
  Add simple DPR suite
  Correct diameter:remove_transport/2 doc
  Fix broken doc link
  Ensure watchdog dies with transport if DPR was sent
  Remove dead clause
  Implement transport_opt() disconnect_cb
  Document transport_opt() disconnect_cb

3 files changed, 132 insertions, 30 deletions

diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml
index a35fd5b3a8..15f398c5f8 100644
--- a/lib/diameter/doc/src/diameter.xml
+++ b/lib/diameter/doc/src/diameter.xml
@@ -833,6 +833,7 @@ request a connection with one peer over SCTP or another
 To listen on both SCTP and TCP, define one transport for each.</p>
 </item>
 
+<marker id="applications"/>
 <tag><c>{applications, [<seealso marker="#application_alias">application_alias()</seealso>]}</c></tag>
 <item>
 <p>
@@ -842,6 +843,7 @@ Defaults to all applications configured on the service in question.
 Applications not configured on the service in question are ignored.</p>
 </item>
 
+<marker id="capabilities"/>
 <tag><c>{capabilities, [<seealso marker="#capability">capability()</seealso>]}</c></tag>
 <item>
 <p>
@@ -856,33 +858,136 @@ TLS is desired over TCP as implemented by
 <seealso marker="diameter_tcp">diameter_tcp(3)</seealso>.</p>
 </item>
 
+<marker id="capabilities_cb"/>
 <tag><c>{capabilities_cb, <seealso marker="#evaluable">evaluable()</seealso>}</c></tag>
 <item>
 <p>
 A callback invoked upon reception of CER/CEA during capabilities
 exchange in order to ask whether or not the connection should
 be accepted.
-Applied to the relevant <c><seealso
-marker="#transport_ref">transport_ref()</seealso></c> and the
-<c>#diameter_caps{}</c> record of the connection.
-Returning <c>ok</c> accepts the connection.
-Returning <c>integer()</c> causes an incoming
-CER to be answered with the specified Result-Code.
-Returning <c>discard</c> causes an incoming CER to
-be discarded.
-Returning <c>unknown</c> is equivalent to returning <c>3010</c>,
-DIAMETER_UNKNOWN_PEER.
-Returning anything but <c>ok</c> or a 2xxx series result
-code causes the transport connection to be broken.</p>
+Applied to the <c><seealso
+marker="#transport_ref">transport_ref()</seealso></c> and
+<c>#diameter_caps{}</c> record of the connection.</p>
+
+<p>
+The return value can have one of the following types.</p>
+
+<taglist>
+<tag><c>ok</c></tag>
+<item>
+<p>
+Accept the connection.</p>
+</item>
+
+<tag><c>integer()</c></tag>
+<item>
+<p>
+Causes an incoming CER to be answered with the specified Result-Code.</p>
+</item>
+
+<tag><c>discard</c></tag>
+<item>
+<p>
+Causes an incoming CER to be discarded without CEA being sent.</p>
+</item>
+
+<tag><c>unknown</c></tag>
+<item>
+<p>
+Equivalent to returning <c>3010</c>, DIAMETER_UNKNOWN_PEER.</p>
+</item>
+</taglist>
 
 <p>
+Returning anything but <c>ok</c> or a 2xxx series result
+code causes the transport connection to be broken.
 Multiple <c>capabilities_cb</c> options can be specified, in which
 case the corresponding callbacks are applied until either all return
 <c>ok</c> or one does not.</p>
+</item>
 
-<marker id="watchdog_timer"/>
+<marker id="disconnect_cb"/>
+<tag><c>{disconnect_cb, <seealso marker="#evaluable">evaluable()</seealso>}</c></tag>
+
+<item>
+<p>
+A callback invoked prior to requesting shutdown of a transport process
+for a transport connection having watchdog state <c>OKAY</c>.
+Applied to <c>Reason=transport|service|application</c> and the
+<c><seealso marker="#transport_ref">transport_ref()</seealso></c> and
+<c><seealso marker="diameter_app#peer">diameter_app:peer()</seealso></c>
+in question, <c>Reason</c> indicating whether the the diameter
+application is being stopped, the service in question is being stopped
+at <seealso
+marker="diameter#stop_service">diameter:stop_service/1</seealso> or
+the transport in question is being removed at <seealso
+marker="diameter#remove_transport">diameter:remove_transport/2</seealso>,
+respectively.</p>
+
+<p>
+The return value can have one of the following types.</p>
+
+<taglist>
+<tag><c>{dpr, [option()]}</c></tag>
+<item>
+<p>
+Causes Disconnect-Peer-Request to be sent to the peer, transport
+process shutdown being requested after reception of
+Disconnect-Peer-Answer or timeout.
+An <c>option()</c> can be one of the following.</p>
+
+<taglist>
+<tag><c>{timeout, integer()}</c></tag>
+<item>
+<p>
+Transport process shutdown will be requested after this number of
+milliseconds if DPA is not received.
+Defaults to 1000.</p>
+</item>
+
+<tag><c>{cause, 0|rebooting|1|busy|2|goaway}</c></tag>
+<item>
+<p>
+The Disconnect-Cause to send, <c>REBOOTING</c>, <c>BUSY</c> and
+<c>DO_NOT_WANT_TO_TALK_TO_YOU</c> respectively.
+Defaults to <c>rebooting</c> for <c>Reason=service|application</c> and
+<c>goaway</c> for <c>Reason=transport</c>.</p>
+</item>
+</taglist>
+</item>
+
+<tag><c>dpr</c></tag>
+<item>
+<p>
+Equivalent to <c>{dpr, []}</c>.</p>
+</item>
+
+<tag><c>close</c></tag>
+<item>
+<p>
+Causes transport process shutdown to be requested without
+Disconnect-Peer-Request being sent to the peer.</p>
 </item>
 
+<tag><c>ignore</c></tag>
+<item>
+<p>
+Equivalent to not having configured the callback.</p>
+</item>
+</taglist>
+
+<p>
+Multiple <c>disconnect_cb</c> options can be specified, in which
+case the corresponding callbacks are applied until one of them returns
+a value other than <c>ignore</c>.
+All callbacks returning <c>ignore</c> is equivalent to not having
+configured them.</p>
+
+<p>
+Defaults to a single callback returning <c>dpr</c>.</p>
+</item>
+
+<marker id="watchdog_timer"/>
 <tag><c>{watchdog_timer, TwInit}</c></tag>
 <item>
 <code>
@@ -902,10 +1007,9 @@ the callback.</p>
 <p>
 An integer value must be at least 6000 as required by RFC 3539.
 Defaults to 30000 if unspecified.</p>
-
-<marker id="reconnect_timer"/>
 </item>
 
+<marker id="reconnect_timer"/>
 <tag><c>{reconnect_timer, Tc}</c></tag>
 <item>
 <code>
@@ -1161,7 +1265,7 @@ at the time the diameter application was started.</p>
 <!-- ===================================================================== -->
 
 <func>
-<name>remove_transport(SvcName, Pred) -> ok</name>
+<name>remove_transport(SvcName, Pred) -> ok | {error, Reason}</name>
 <fsummary>Remove previously added transports.</fsummary>
 <type>
 <v>SvcName = <seealso marker="#service_name">service_name()</seealso></v>
@@ -1171,6 +1275,7 @@ at the time the diameter application was started.</p>
 <v>&nbsp;&nbsp;&nbsp; | fun((<seealso marker="#transport_ref">transport_ref()</seealso>, list()) -> boolean())</v>
 <v>&nbsp;&nbsp;&nbsp; | fun((list()) -> boolean())</v>
 <v>MFA = {atom(), atom(), list()}</v>
+<v>Reason = term()</v>
 </type>
 <desc>
 <p>
@@ -1196,15 +1301,12 @@ Pred = {M,F,A}:  fun(Ref, Type, Opts) -> apply(M, F, [Ref, Type, Opts | A]) end
 </code>
 
 <p>
-Removing a transport causes all associated transport connections to
-be broken.
-A DPR message with
-Disconnect-Cause <c>DO_NOT_WANT_TO_TALK_TO_YOU</c> will be sent
-to each connected peer before disassociating the transport configuration
-from the service and terminating the transport upon reception of
-DPA or timeout.</p>
-
-<!-- TODO: document the timeout value, possibly make configurable. -->
+Removing a transport causes the corresponding transport processes to
+be asked to terminate.
+Whether or not a DPR message is sent to a peer is
+controlled by
+value of <seealso marker="disconnect_cb">disconnect_cb</seealso>
+configured on the transport.</p>
 
 <marker id="service_info"/>
 </desc>
diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml
index 9d8a6568eb..ac056c2d39 100644
--- a/lib/diameter/doc/src/diameter_app.xml
+++ b/lib/diameter/doc/src/diameter_app.xml
@@ -309,12 +309,12 @@ by either <seealso marker="#handle_answer">handle_answer/4</seealso>
 or <seealso marker="#handle_error">handle_error/4</seealso> depending
 on whether or not an answer message is received from the peer.
 If the transport becomes unavailable after <seealso
-marker="prepare_request">prepare_request/3</seealso> then a new <seealso
+marker="#prepare_request">prepare_request/3</seealso> then a new <seealso
 marker="#pick_peer">pick_peer/4</seealso> callback may take place to
 failover to an alternate peer, after which <seealso
 marker="#prepare_retransmit">prepare_retransmit/3</seealso> takes the
 place of <seealso
-marker="prepare_request">prepare_request/3</seealso> in resending the
+marker="#prepare_request">prepare_request/3</seealso> in resending the
 request.
 There is no guarantee that a <seealso
 marker="#pick_peer">pick_peer/4</seealso> callback to select
diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml
index d9b36a1e09..0c8b41397a 100644
--- a/lib/diameter/doc/src/diameter_transport.xml
+++ b/lib/diameter/doc/src/diameter_transport.xml
@@ -149,9 +149,9 @@ contains the binary to send.</p>
 <tag><c>{diameter, {close, Pid}}</c></tag>
 <item>
 <p>
-A request to close the transport connection.
-The transport process should terminate after closing the
-connection.
+A request to terminate the transport process after having received DPA
+in response to DPR.
+The transport process should exit.
 <c>Pid</c> is the pid() of the parent process.</p>
 </item>