Deprecated Makefile in favor of StreamReader and StreamWriter

We replace the `MakeFile` factory function with direct class instantiation.
The `MakeFile` function now emits a `DeprecationWarning` and will be
removed in a future release.

`makefile()` methods are also deprecated on the adapters and its
base class.

Author: julianz-

cheroot/connections.py

@@ -11,7 +11,6 @@
 
 from . import errors
 from ._compat import IS_WINDOWS
-from .makefile import MakeFile
 
 
 try:
@@ -304,7 +303,6 @@ def _from_server_socket(self, server_socket):  # noqa: C901  # FIXME
             if hasattr(s, 'settimeout'):
                 s.settimeout(self.server.timeout)
 
-            mf = MakeFile
             ssl_env = {}
             # if ssl cert and key are set, we try to be a secure HTTP server
             if self.server.ssl_adapter is not None:
@@ -327,12 +325,12 @@ def _from_server_socket(self, server_socket):  # noqa: C901  # FIXME
                     )
                     self._send_bad_request_plain_http_error(s)
                     return None
-                mf = self.server.ssl_adapter.makefile
+
                 # Re-apply our timeout since we may have a new socket object
                 if hasattr(s, 'settimeout'):
                     s.settimeout(self.server.timeout)
 
-            conn = self.server.ConnectionClass(self.server, s, mf)
+            conn = self.server.ConnectionClass(self.server, s)
 
             if not isinstance(self.server.bind_addr, (str, bytes)):
                 # optional values

cheroot/makefile.py

@@ -3,6 +3,7 @@
 # prefer slower Python-based io module
 import _pyio as io
 import socket
+from warnings import warn as _warn
 
 
 # Write only 16K at a time to sockets
@@ -70,6 +71,16 @@ def write(self, val, *args, **kwargs):
 
 
 def MakeFile(sock, mode='r', bufsize=io.DEFAULT_BUFFER_SIZE):
-    """File object attached to a socket object."""
+    """
+    File object attached to a socket object.
+
+    This function is now deprecated: Use
+    StreamReader or StreamWriter directly.
+    """
+    _warn(
+        'MakeFile is deprecated. Use StreamReader or StreamWriter directly.',
+        DeprecationWarning,
+        stacklevel=2,
+    )
     cls = StreamReader if 'r' in mode else StreamWriter
     return cls(sock, mode, bufsize)

cheroot/server.py

@@ -84,7 +84,7 @@
 
 from . import __version__, connections, errors
 from ._compat import IS_PPC, bton
-from .makefile import MakeFile, StreamWriter
+from .makefile import StreamReader, StreamWriter
 from .workers import threadpool
 
 
@@ -1276,19 +1276,31 @@ class HTTPConnection:
     # Fields set by ConnectionManager.
     last_used = None
 
-    def __init__(self, server, sock, makefile=MakeFile):
+    def __init__(self, server, sock, makefile=None):
         """Initialize HTTPConnection instance.
 
         Args:
             server (HTTPServer): web server object receiving this request
             sock (socket._socketobject): the raw socket object (usually
                 TCP) for this connection
-            makefile (file): a fileobject class for reading from the socket
+            makefile (file): Now deprecated
+                Use to be a fileobject class for reading from the socket
         """
         self.server = server
         self.socket = sock
-        self.rfile = makefile(sock, 'rb', self.rbufsize)
-        self.wfile = makefile(sock, 'wb', self.wbufsize)
+
+        if makefile is not None:
+            _warn(
+                'The `makefile` parameter in creating an `HTTPConnection` '
+                'is deprecated and will be removed in a future version. '
+                'The connection socket should now be fully wrapped by the '
+                'adapter before being passed to this constructor.',
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        self.rfile = StreamReader(sock, 'rb', self.rbufsize)
+        self.wfile = StreamWriter(sock, 'wb', self.wbufsize)
         self.requests_seen = 0
 
         self.peercreds_enabled = self.server.peercreds_enabled
@@ -1358,12 +1370,8 @@ def communicate(self):  # noqa: C901  # FIXME
     def _handle_no_ssl(self, req):
         if not req or req.sent_headers:
             return
-        # Unwrap wfile
-        try:
-            resp_sock = self.socket._sock
-        except AttributeError:
-            # self.socket is of OpenSSL.SSL.Connection type
-            resp_sock = self.socket._socket
+        # Unwrap to get raw TCP socket
+        resp_sock = self.socket._sock
         self.wfile = StreamWriter(resp_sock, 'wb', self.wbufsize)
         msg = (
             'The client sent a plain HTTP request, but '

cheroot/ssl/__init__.py

@@ -56,13 +56,24 @@ def _ensure_peer_speaks_https(raw_socket, /) -> None:
 
 
 class Adapter(ABC):
-    """Base class for SSL driver library adapters.
+    """
+    Base class for SSL driver library adapters.
 
     Required methods:
-
-        * ``wrap(sock) -> (wrapped socket, ssl environ dict)``
-        * ``makefile(sock, mode='r', bufsize=DEFAULT_BUFFER_SIZE) ->
-          socket file object``
+        ``wrap(sock)``: Wrap a socket with SSL. Also returns ssl environ dict.
+        ``get_environ()``: Get SSL environment variables as a dict.
+
+    Optional methods:
+        ``makefile(sock, mode, bufsize)``: Create custom file object.
+            This method is deprecated and will be removed in a future release.
+
+            Historically, the ``PyOpenSSL`` adapter used ``makefile()`` to
+            wrap the underlying socket in an ``OpenSSL``-aware file object
+            so that Cheroot's HTTP request parser (which expects file-like I/O
+            such as ``readline()``) could read from TLS connections. The
+            adapter now fully wraps the socket in a TLSSocket object that
+            implements the necessary socket and file-like
+            methods directly, so makefile() is no longer needed.
     """
 
     @abstractmethod
@@ -112,7 +123,11 @@ def get_environ(self):
 
     @abstractmethod
     def makefile(self, sock, mode='r', bufsize=-1):
-        """Return socket file object."""
+        """
+        Return socket file object.
+
+        This method is now deprecated. It will be removed in a future version.
+        """
         raise NotImplementedError  # pragma: no cover
 
     def _prompt_for_tls_password(self) -> str:

cheroot/ssl/builtin.py

@@ -7,31 +7,42 @@
 ``BuiltinSSLAdapter``.
 """
 
+import io
 import socket
 import sys
 import threading
 from contextlib import suppress
+from warnings import warn as _warn
 
 
 try:
     import ssl
 except ImportError:
     ssl = None
 
-try:
-    from _pyio import DEFAULT_BUFFER_SIZE
-except ImportError:
-    try:
-        from io import DEFAULT_BUFFER_SIZE
-    except ImportError:
-        DEFAULT_BUFFER_SIZE = -1
-
 from .. import errors
-from ..makefile import StreamReader, StreamWriter
 from ..server import HTTPServer
 from . import Adapter
 
 
+# WPS413 is to suppress linter error:
+# bad magic module function: __getattr__
+# DEFAULT_BUFFER_SIZE is deprecated so this module method will be removed
+# in a future release
+def __getattr__(name):  # noqa: WPS413
+    if name == 'DEFAULT_BUFFER_SIZE':
+        _warn(
+            (
+                '`DEFAULT_BUFFER_SIZE` is deprecated and '
+                'will be removed in a future release.'
+            ),
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return io.DEFAULT_BUFFER_SIZE
+    raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+
+
 def _assert_ssl_exc_contains(exc, *msgs):
     """Check whether SSL exception contains either of messages provided."""
     if len(msgs) < 1:
@@ -496,7 +507,19 @@ def _make_env_dn_dict(self, env_prefix, cert_value):
                 env['%s_%s_%i' % (env_prefix, attr_code, i)] = val
         return env
 
-    def makefile(self, sock, mode='r', bufsize=DEFAULT_BUFFER_SIZE):
-        """Return socket file object."""
-        cls = StreamReader if 'r' in mode else StreamWriter
-        return cls(sock, mode, bufsize)
+    def makefile(self, sock, mode='r', bufsize=-1):
+        """
+        Return socket file object.
+
+        ``makefile`` is now deprecated and will be removed in a future
+        version.
+        """
+        _warn(
+            'The `makefile` method is deprecated and will be removed in a future version. '
+            'The connection socket should be fully wrapped by the adapter '
+            'before being passed to the HTTPConnection constructor.',
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+        return sock.makefile(mode, bufsize)

cheroot/ssl/builtin.pyi

@@ -3,8 +3,6 @@ import typing as _t
 
 from . import Adapter
 
-DEFAULT_BUFFER_SIZE: int
-
 class BuiltinSSLAdapter(Adapter):
     CERT_KEY_TO_ENV: _t.Any
     CERT_KEY_TO_LDAP_CODE: _t.Any

cheroot/ssl/pyopenssl.py

@@ -54,6 +54,7 @@
 import sys
 import threading
 import time
+from contextlib import suppress as _suppress
 from warnings import warn as _warn
 
 
@@ -74,7 +75,6 @@
     errors,
     server as cheroot_server,
 )
-from ..makefile import StreamReader, StreamWriter
 from . import Adapter
 
 
@@ -168,14 +168,6 @@ def send(self, *args, **kwargs):
         )
 
 
-class SSLFileobjectStreamReader(SSLFileobjectMixin, StreamReader):
-    """SSL file object attached to a socket object."""
-
-
-class SSLFileobjectStreamWriter(SSLFileobjectMixin, StreamWriter):
-    """SSL file object attached to a socket object."""
-
-
 class SSLConnectionProxyMeta:
     """Metaclass for generating a bunch of proxy methods."""
 
@@ -345,9 +337,11 @@ def wrap(self, sock):
         )
 
         conn = SSLConnection(self.context, sock)
-
         conn.set_accept_state()  # Tell OpenSSL this is a server connection
-        return conn, self._environ.copy()
+
+        # Wrap the SSLConnection to provide standard socket interface
+        tls_socket = TLSSocket(conn)
+        return tls_socket, self._environ.copy()
 
     def _password_callback(
         self,
@@ -461,17 +455,91 @@ def get_environ(self):
         return ssl_environ
 
     def makefile(self, sock, mode='r', bufsize=-1):
-        """Return socket file object."""
-        cls = (
-            SSLFileobjectStreamReader
-            if 'r' in mode
-            else SSLFileobjectStreamWriter
+        """
+        Return socket file object.
+
+        ``makefile`` is now deprecated and will be removed in a future
+        version.
+        """
+        _warn(
+            'The `makefile` method is deprecated and will be removed in a future version. '
+            'The connection socket should be fully wrapped by the adapter '
+            'before being passed to the HTTPConnection constructor.',
+            DeprecationWarning,
+            stacklevel=2,
         )
-        # sock is an pyopenSSL.SSLConnection instance here
-        if SSL and isinstance(sock, SSLConnection):
-            wrapped_socket = cls(sock, mode, bufsize)
-            wrapped_socket.ssl_timeout = sock.gettimeout()
-            return wrapped_socket
-        # This is from past:
-        # TODO: figure out what it's meant for
-        return cheroot_server.CP_fileobject(sock, mode, bufsize)
+
+        return sock.makefile(mode, bufsize)
+
+
+class TLSSocket(SSLFileobjectMixin):
+    """
+    Wrap ``pyOpenSSL`` SSL.Connection to work with StreamReader/StreamWriter.
+
+    Handles OpenSSL-specific errors internally so that standard Python I/O
+    classes can use it transparently.
+    """
+
+    def __init__(self, ssl_conn, ssl_timeout=None, ssl_retry=0.01):
+        """Initialize with an SSL.Connection object."""
+        self._ssl_conn = ssl_conn
+        self._sock = ssl_conn._socket  # Store reference to raw TCP socket
+        self._lock = threading.RLock()
+        self.ssl_timeout = ssl_timeout or 3.0
+        self.ssl_retry = ssl_retry
+
+    # Socket I/O
+    # _safe_call is delegated to the SSLFileobjectMixin
+
+    def recv_into(self, buffer, nbytes=None):
+        """Receive data into a buffer (socket interface)."""
+        with self._lock:
+            result = self._safe_call(
+                True,
+                self._ssl_conn.recv_into,
+                buffer,
+                nbytes,
+            )
+            # Handle the case where _safe_call returns b'' for EOF
+            if result == b'':
+                return 0
+            return result
+
+    def send(self, data):
+        """Send data (socket interface)."""
+        with self._lock:
+            return self._safe_call(
+                False,  # is_reader=False
+                self._ssl_conn.send,
+                data,
+            )
+
+    def fileno(self):
+        """Return the file descriptor."""
+        return self._ssl_conn.fileno()
+
+    def _decref_socketios(self):
+        """Shutdown the connection."""
+        return self._ssl_conn._decref_socketios()
+
+    def shutdown(self, how):
+        """Shutdown the connection."""
+        # SSL shutdown can fail if the handshake didn't complete or during
+        # error conditions. Since shutdown is a cleanup operation, we suppress
+        # all errors - the connection will be closed anyway.
+        with _suppress(SSL.Error, socket.error, OSError):
+            return self._ssl_conn.shutdown(how)
+
+    def close(self):
+        """Close the TLS socket and underlying connection."""
+        # 1. Attempt an SSL-level shutdown
+        with _suppress(SSL.Error, OSError):
+            self._ssl_conn.shutdown()
+
+        # 2. Close the SSL connection object
+        with _suppress(SSL.Error, OSError):
+            self._ssl_conn.close()
+
+        # 3. Close the raw TCP socket
+        with _suppress(OSError):
+            self._sock.close()