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

@@ -55,13 +55,16 @@ 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)``: Wrap a socket with SSL. Also returns ssl environ dict.
+        ``get_environ()``: Get SSL environment variables as a dict.
 
-        * ``wrap(sock) -> (wrapped socket, ssl environ dict)``
-        * ``makefile(sock, mode='r', bufsize=DEFAULT_BUFFER_SIZE) ->
-          socket file object``
+    Optional methods:
+        ``makefile(sock, mode, bufsize)``: Create custom file object.
+            The ``pyOpenSSL`` adapter uses this to handle SSL-specific errors.
     """
 
     @abstractmethod
@@ -111,5 +114,9 @@ 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

cheroot/ssl/builtin.py

@@ -11,23 +11,15 @@
 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
 
@@ -493,7 +485,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

@@ -2,8 +2,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

@@ -50,6 +50,7 @@
    pyopenssl
 """
 
+import io
 import socket
 import sys
 import threading
@@ -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,
@@ -450,17 +444,101 @@ 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 RawIOWrapperMixin:
+    """
+    Provide methods to satisfy the io.RawIOBase interface.
+
+    Delegates I/O to the core socket methods recv_into and send,
+    which are implemented by TLSSocket.
+    """
+
+    def readable(self):
+        """Return whether object supports reading."""
+        return True
+
+    def writable(self):
+        """Return whether object supports writing."""
+        return True
+
+    def readinto(self, b):
+        """Read bytes into a pre-allocated buffer (I/O interface)."""
+        # This relies on the concrete class implementing recv_into
+        return self.recv_into(b)
+
+    def write(self, b):
+        """Write bytes (I/O interface)."""
+        # This relies on the concrete class implementing send
+        return self.send(b)
+
+
+class TLSSocket(RawIOWrapperMixin, SSLFileobjectMixin, io.RawIOBase):
+    """
+    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:
+            return self._safe_call(
+                True,  # is_reader=True
+                self._ssl_conn.recv_into,
+                buffer,
+                nbytes,
+            )
+
+    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."""
+        return self._ssl_conn.shutdown(how)
+
+    def close(self):
+        """Close the connection."""
+        super().close()
+        self._ssl_conn.close()