Introduce TLSSocket abstraction for uniform handling

Introduces a new `TLSSocket` class to act as a unified wrapper for
SSL/TLS connections, regardless of the underlying adapter
(`builtin`, `pyOpenSSL`).

This refactoring aims to:
1. Simplify adapter logic by centralizing common TLS socket
properties and methods (e.g., cipher details, certificate paths).
2. Improve consistency when populating WSGI environment variables.
3. Centralize error handling in the adapters.

Author: julianz-

.flake8

@@ -124,13 +124,14 @@ per-file-ignores =
   cheroot/__main__.py: WPS130
   cheroot/_compat.py: DAR101, DAR201, DAR301, DAR401, I003, RST304, WPS100, WPS111, WPS123, WPS226, WPS229, WPS420, WPS422, WPS432, WPS504, WPS505
   cheroot/cli.py: DAR101, DAR201, DAR401, I001, I004, I005, WPS100, WPS110, WPS120, WPS130, WPS202, WPS226, WPS229, WPS338, WPS420, WPS421
-  cheroot/connections.py: DAR101, DAR201, DAR301, DAR401, I001, I003, I004, I005, RST304, S104, WPS100, WPS110, WPS111, WPS121, WPS122, WPS130, WPS201, WPS204, WPS210, WPS212, WPS214, WPS220, WPS229, WPS231, WPS301, WPS324, WPS338, WPS420, WPS421, WPS422, WPS432, WPS501, WPS504, WPS505
+  cheroot/connections.py: DAR101, DAR201, DAR301, DAR401, I001, I003, I004, I005, RST304, S104, WPS100, WPS110, WPS111, WPS121, WPS122, WPS130, WPS201, WPS204, WPS210, WPS212, WPS214, WPS220, WPS229, WPS231, WPS237, WPS301, WPS324, WPS338, WPS420, WPS421, WPS422, WPS432, WPS501, WPS504, WPS505
   cheroot/errors.py: DAR101, DAR201, I003, RST304, WPS111, WPS121, WPS422
   cheroot/makefile.py: DAR101, DAR201, DAR401, E800, I003, I004, N801, N802, S101, WPS100, WPS110, WPS111, WPS117, WPS120, WPS121, WPS122, WPS123, WPS130, WPS204, WPS210, WPS212, WPS213, WPS220, WPS229, WPS231, WPS232, WPS338, WPS420, WPS422, WPS429, WPS431, WPS504, WPS604, WPS606
   cheroot/server.py: DAR003, DAR101, DAR201, DAR202, DAR301, DAR401, E800, I001, I003, I004, I005, N806, RST201, RST301, RST303, RST304, WPS100, WPS110, WPS111, WPS115, WPS120, WPS121, WPS122, WPS130, WPS132, WPS201, WPS202, WPS204, WPS210, WPS211, WPS212, WPS213, WPS214, WPS220, WPS221, WPS225, WPS226, WPS229, WPS230, WPS231, WPS236, WPS237, WPS238, WPS301, WPS338, WPS342, WPS410, WPS420, WPS421, WPS422, WPS429, WPS432, WPS504, WPS505, WPS601, WPS602, WPS608, WPS617
-  cheroot/ssl/builtin.py: DAR101, DAR201, DAR401, I001, I003, N806, RST304, WPS110, WPS111, WPS115, WPS117, WPS120, WPS121, WPS122, WPS130, WPS201, WPS210, WPS214, WPS229, WPS231, WPS338, WPS422, WPS501, WPS505, WPS529, WPS608, WPS612
+  cheroot/ssl/builtin.py: DAR101, DAR201, DAR401, I001, I003, N806, RST304, WPS110, WPS111, WPS115, WPS117, WPS120, WPS121, WPS122, WPS130, WPS201, WPS204, WPS210, WPS220, WPS214, WPS226, WPS229, WPS231, WPS338, WPS421, WPS422, WPS501, WPS505, WPS529, WPS608, WPS612
   cheroot/ssl/pyopenssl.py: C815, DAR101, DAR201, DAR401, I001, I003, I005, N801, N804, RST304, WPS100, WPS110, WPS111, WPS117, WPS120, WPS121, WPS130, WPS210, WPS220, WPS221, WPS225, WPS229, WPS231, WPS238, WPS301, WPS335, WPS338, WPS420, WPS422, WPS430, WPS432, WPS501, WPS504, WPS505, WPS601, WPS608, WPS615
-  cheroot/test/conftest.py: DAR101, DAR201, DAR301, I001, I003, I005, WPS100, WPS130, WPS325, WPS354, WPS420, WPS422, WPS430, WPS457
+  cheroot/ssl/tls_socket.py: DAR101, DAR201, DAR401, WPS110, WPS122, WPS210, WPS212, WPS214, WPS220, WPS225, WPS226, WPS229, WPS231, WPS238, WPS338, WPS362, WPS407
+  cheroot/test/conftest.py: DAR101, DAR201, DAR301, I001, I003, I005, WPS100, WPS130, WPS202, WPS325, WPS354, WPS420, WPS422, WPS430, WPS457
   cheroot/test/helper.py: DAR101, DAR201, DAR401, I001, I003, I004, N802, WPS110, WPS111, WPS121, WPS201, WPS220, WPS231, WPS301, WPS414, WPS421, WPS422, WPS505
   cheroot/test/test_cli.py: DAR101, DAR201, I001, I005, N802, S101, S108, WPS110, WPS421, WPS431, WPS473
   cheroot/test/test_makefile.py: DAR101, DAR201, I004, RST304, S101, WPS110, WPS122
@@ -144,7 +145,9 @@ per-file-ignores =
   cheroot/testing.py: C815, DAR101, DAR201, DAR301, I001, I003, S104, WPS100, WPS202, WPS211, WPS229, WPS301, WPS414, WPS420, WPS422, WPS430
   cheroot/workers/threadpool.py: DAR101, DAR201, E800, I001, I003, I004, RST201, RST203, RST301, WPS100, WPS110, WPS111, WPS121, WPS122, WPS210, WPS211, WPS214, WPS220, WPS229, WPS230, WPS231, WPS335, WPS338, WPS362, WPS363, WPS410, WPS414, WPS420, WPS422, WPS432, WPS501, WPS505, WPS601, WPS602, WPS617
   cheroot/wsgi.py: DAR101, DAR201, DAR401, I001, I003, I005, N801, RST201, RST301, WPS100, WPS110, WPS111, WPS114, WPS121, WPS122, WPS130, WPS210, WPS211, WPS226, WPS229, WPS231, WPS338, WPS420, WPS421, WPS422, WPS430, WPS501, WPS504, WPS602, WPS608
-  cheroot/ssl/__init__.py: DAR101, DAR201, I003, WPS412, WPS422
+  cheroot/ssl/__init__.py: DAR101, DAR201, I003, WPS210, WPS412, WPS422
+  cheroot/test/ssl/test_ssl_builtin.py: DAR101, DAR201, I003, WPS118, WPS201, WPS202, WPS210, WPS213, WPS218, WPS211, WPS226, WPS229, WPS231, WPS243, WPS412, WPS420, WPS422, WPS430, WPS505
+  cheroot/test/ssl/test_ssl_pyopenssl.py: DAR101, DAR201, I003, WPS118, WPS201, WPS202, WPS204, WPS210, WPS220, WPS213, WPS218, WPS211, WPS226, WPS229, WPS231, WPS243, WPS412, WPS420, WPS422, WPS430, WPS432, WPS435, WPS505
   cheroot/test/_pytest_plugin.py: DAR101, I003, I004, WPS422
   cheroot/test/test__compat.py: DAR101, I001, I003, I005, WPS116, WPS226, WPS422, S101
   cheroot/test/test_errors.py: DAR101, WPS509, S101

.mypy.ini

@@ -1,5 +1,5 @@
 [mypy]
-python_version = 3.8
+python_version = 3.9
 color_output = true
 error_summary = true
 files =

cheroot/connections.py

@@ -1,6 +1,5 @@
 """Utilities to manage open connections."""
 
-import io
 import os
 import selectors
 import socket
@@ -295,8 +294,17 @@ def _from_server_socket(self, server_socket):  # noqa: C901  # FIXME
 
             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:
+                # 1. Preemptive check for BuiltinSSLAdapter
+                if hasattr(
+                    self.server.ssl_adapter,
+                    '_check_for_plain_http',
+                ) and self.server.ssl_adapter._check_for_plain_http(s):
+                    return self._send_bad_request_plain_http_error(s, addr)
+
+                # 2. Secure HTTP server attempt
                 try:
                     s, ssl_env = self.server.ssl_adapter.wrap(s)
                 except errors.FatalSSLAlert as tls_connection_drop_error:
@@ -306,35 +314,11 @@ def _from_server_socket(self, server_socket):  # noqa: C901  # FIXME
                         f'{tls_connection_drop_error!s}',
                     )
                     return None
-                except errors.NoSSLError as http_over_https_err:
-                    self.server.error_log(
-                        f'Client {addr!s} attempted to speak plain HTTP into '
-                        'a TCP connection configured for TLS-only traffic — '
-                        'trying to send back a plain HTTP error response: '
-                        f'{http_over_https_err!s}',
-                    )
-                    msg = (
-                        'The client sent a plain HTTP request, but '
-                        'this server only speaks HTTPS on this port.'
-                    )
-                    buf = [
-                        '%s 400 Bad Request\r\n' % self.server.protocol,
-                        'Content-Length: %s\r\n' % len(msg),
-                        'Content-Type: text/plain\r\n\r\n',
-                        msg,
-                    ]
-
-                    wfile = mf(s, 'wb', io.DEFAULT_BUFFER_SIZE)
-                    try:
-                        wfile.write(''.join(buf).encode('ISO-8859-1'))
-                    except OSError as ex:
-                        if ex.args[0] not in errors.socket_errors_to_ignore:
-                            raise
-                    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)
+                except errors.NoSSLError:
+                    # this only arises for PyOpenSSL as
+                    # we handle http over https pre-emptivley
+                    # for the Builtin adapter
+                    return self._send_bad_request_plain_http_error(s, addr)
 
             conn = self.server.ConnectionClass(self.server, s, mf)
 
@@ -381,6 +365,38 @@ def _from_server_socket(self, server_socket):  # noqa: C901  # FIXME
                 return None
             raise
 
+    def _send_bad_request_plain_http_error(self, sock, addr):
+        """Send Bad Request 400 response, and close the socket."""
+        self.server.error_log(
+            f'Client {addr!s} attempted to speak plain HTTP into '
+            'a TCP connection configured for TLS-only traffic — '
+            'Sending 400 Bad Request.',
+        )
+
+        msg = (
+            'The client sent a plain HTTP request, but this server '
+            'only speaks HTTPS on this port.'
+        )
+
+        response_parts = [
+            f'{self.server.protocol} 400 Bad Request\r\n',
+            'Content-Type: text/plain\r\n',
+            f'Content-Length: {len(msg)}\r\n',
+            'Connection: close\r\n',
+            '\r\n',
+            msg,
+        ]
+        response_bytes = ''.join(response_parts).encode('ISO-8859-1')
+
+        try:
+            sock.sendall(response_bytes)
+            sock.shutdown(socket.SHUT_WR)
+        except OSError as ex:
+            if ex.args[0] not in errors.socket_errors_to_ignore:
+                raise
+
+        sock.close()
+
     def close(self):
         """Close all monitored connections."""
         for _, conn in self._selector.connections:

cheroot/makefile.py

@@ -4,6 +4,8 @@
 import _pyio as io
 import socket
 
+from .ssl.tls_socket import TLSSocket
+
 
 # Write only 16K at a time to sockets
 SOCK_WRITE_BLOCKSIZE = 16384
@@ -40,7 +42,14 @@ class StreamReader(io.BufferedReader):
 
     def __init__(self, sock, mode='r', bufsize=io.DEFAULT_BUFFER_SIZE):
         """Initialize socket stream reader."""
-        super().__init__(socket.SocketIO(sock, mode), bufsize)
+        # If sock is TLSSocket, it's already wrapped.
+        if isinstance(sock, TLSSocket):
+            raw_io = sock
+        else:
+            # Standard socket - wrap with SocketIO
+            raw_io = socket.SocketIO(sock, mode)
+
+        super().__init__(raw_io, bufsize)
         self.bytes_read = 0
 
     def read(self, *args, **kwargs):
@@ -59,7 +68,14 @@ class StreamWriter(BufferedWriter):
 
     def __init__(self, sock, mode='w', bufsize=io.DEFAULT_BUFFER_SIZE):
         """Initialize socket stream writer."""
-        super().__init__(socket.SocketIO(sock, mode), bufsize)
+        # If sock is TLSSocket, use it directly as raw I/O
+        if isinstance(sock, TLSSocket):
+            raw_io = sock
+        else:
+            # Standard socket - wrap with SocketIO
+            raw_io = socket.SocketIO(sock, mode)
+
+        super().__init__(raw_io, bufsize)
         self.bytes_written = 0
 
     def write(self, val, *args, **kwargs):

cheroot/server.py

@@ -1522,7 +1522,7 @@ def _close_kernel_socket(self):
                 raise
 
 
-class HTTPServer:
+class HTTPServer:  # noqa: PLR0904
     """An HTTP server."""
 
     _bind_addr = '127.0.0.1'
@@ -1590,14 +1590,26 @@ class HTTPServer:
     ConnectionClass = HTTPConnection
     """The class to use for handling HTTP connections."""
 
-    ssl_adapter = None
+    _ssl_adapter = None
     """An instance of ``ssl.Adapter`` (or a subclass).
 
     Ref: :py:class:`ssl.Adapter <cheroot.ssl.Adapter>`.
 
     You must have the corresponding TLS driver library installed.
     """
 
+    @property
+    def ssl_adapter(self):
+        """An instance of ssl.Adapter (or a subclass)."""
+        return self._ssl_adapter
+
+    @ssl_adapter.setter
+    def ssl_adapter(self, value):
+        """Set the SSL adapter and establish bidirectional reference."""
+        self._ssl_adapter = value
+        if value is not None:
+            value.server = self
+
     peercreds_enabled = False
     """
     Whether :py:data:`True`, peer credentials will be looked up via UNIX