ssl: deprecate OpenSSL::SSL::SSLServer

ext/openssl/ossl.c

@@ -944,16 +944,20 @@ ossl_crypto_fixed_length_secure_compare(VALUE dummy, VALUE str1, VALUE str2)
  *   context.cert = cert
  *   context.key = key
  *
- * Then create an OpenSSL::SSL::SSLServer with a TCP server socket and the
- * context.  Use the SSLServer like an ordinary TCP server.
+ * After establishing a TCP connection, the socket is wrapped in an
+ * OpenSSL::SSL::SSLSocket with the context. OpenSSL::SSL::SSLSocket#accept
+ * is called to perform the TLS handshake.
  *
  *   require 'socket'
  *
  *   tcp_server = TCPServer.new 5000
- *   ssl_server = OpenSSL::SSL::SSLServer.new tcp_server, context
  *
  *   loop do
- *     ssl_connection = ssl_server.accept
+ *     tcp_connection = tcp_server.accept
+ *     ssl_connection = OpenSSL::SSL::SSLSocket.new tcp_connection, context
+ *     # Or you can close tcp_connection manually after ssl_connection.close
+ *     ssl_connection.sync_close = true
+ *     ssl_connection.accept
  *
  *     data = ssl_connection.gets
  *

lib/openssl/ssl.rb

@@ -475,9 +475,19 @@ def open(remote_host, remote_port, local_host=nil, local_port=nil, context: nil)
 
     ##
     # SSLServer represents a TCP/IP server socket with Secure Sockets Layer.
+    #
+    # *Deprecated.* Use TCPServer or Socket to accept a TCP connection, and
+    # then wrap it with OpenSSL::SSL::SSLSocket.
+    # See also OpenSSL::SSL::SSLSocket#accept.
     class SSLServer
       include SocketForwarder
-      # When true then #accept works exactly the same as TCPServer#accept
+
+      # When set to +true+, #accept will immediately perform the SSL/TLS
+      # handshake after accepting a TCP connection. Defaults to +true+.
+      #
+      # *NOTE*: #accept performs the SSL/TLS handshake synchronously. A slow
+      # client can therefore prevent the server from accepting new connections
+      # indefinitely. For this reason, SSLServer is deprecated.
       attr_accessor :start_immediately
 
       # Creates a new instance of SSLServer.
@@ -511,6 +521,8 @@ def shutdown(how=Socket::SHUT_RDWR)
       end
 
       # Works similar to TCPServer#accept.
+      #
+      # *NOTE*: SSLServer is deprecated. See #start_immediately for details.
       def accept
         # Socket#accept returns [socket, addrinfo].
         # TCPServer#accept returns a socket.