Introduce Transport:handshake/1,2

This commit deprecates Transport:accept_ack/1 in favor of
a new forward-compatible function. Transport:handshake/1,2
will use ssl:handshake/2,3 from Ranch 2.0 onward.

1 files changed, 31 insertions, 9 deletions

diff --git a/doc/src/manual/ranch.asciidoc b/doc/src/manual/ranch.asciidoc
index 7fd18d0..2380646 100644
--- a/doc/src/manual/ranch.asciidoc
+++ b/doc/src/manual/ranch.asciidoc
@@ -47,7 +47,7 @@ Unique name used to refer to a listener.
 None of the options are required.
 
 ack_timeout (5000)::
-	Maximum allowed time for the `ranch:accept_ack/1` call to finish.
+	Maximum allowed time for the `ranch:handshake/{1,2}` call to finish.
 connection_type (worker)::
 	Type of process that will handle the connection.
 max_connections (1024)::
@@ -63,13 +63,7 @@ socket::
 
 === accept_ack(Ref) -> ok
 
-Ref = ref():: Listener name.
-
-Acknowledge that the connection is accepted.
-
-This function MUST be used by a connection process to inform
-Ranch that it initialized properly and let it perform any
-additional operations before the socket can be safely used.
+This function is deprecated in favor of `ranch:handshake/1,2`.
 
 === child_spec(Ref, NumAcceptors, Transport, TransOpts, Protocol, ProtoOpts) -> supervisor:child_spec()
 
@@ -127,6 +121,34 @@ TransOpts = any():: Current transport options.
 
 Return the transport options set for the given listener.
 
+=== handshake(Ref) -> {ok, Socket}
+
+Ref = ref():: Listener name.
+Socket = any():: Initialized socket.
+
+Acknowledge that the connection is accepted.
+Returns a socket that is ready to use.
+
+One of the `ranch:handshake/{1,2}` functions MUST be used
+by a connection process to inform Ranch that it initialized
+properly and let it perform any additional operations before
+the socket can be safely used.
+
+=== handshake(Ref, Opts) -> {ok, Socket}
+
+Ref = ref():: Listener name.
+Opts = any():: Initialization options.
+Socket = any():: Initialized socket.
+
+Acknowledge that the connection is accepted.
+Additional options can be provided for socket initialization.
+Returns a socket that is ready to use.
+
+One of the `ranch:handshake/{1,2}` functions MUST be used
+by a connection process to inform Ranch that it initialized
+properly and let it perform any additional operations before
+the socket can be safely used.
+
 === info() -> [{Ref, [{Key, Value}]}]
 
 Ref = ref():: Listener name.
@@ -272,4 +294,4 @@ Operator = '>' | '>=' | '==' | '=<' | '<':: Comparison operator.
 NumConnections = non_neg_integer():: Number of connections to wait for.
 
 Wait until the number of connections on the given listener matches
-the given operator and number of connections.
\ No newline at end of file
+the given operator and number of connections.