Map PyOpenSSL SysCallErrors to standard Python ConnectionErrors

Author: julianz-

cheroot/ssl/pyopenssl.py

@@ -50,6 +50,8 @@
    pyopenssl
 """
 
+import errno
+import os
 import socket
 import sys
 import threading
@@ -77,6 +79,45 @@
 from . import Adapter
 
 
+@contextlib.contextmanager
+def _morph_syscall_to_connection_error(method_name, /):
+    """
+    Handle :exc:`OpenSSL.SSL.SysCallError` in a wrapped method.
+
+    This context manager catches and re-raises SSL system call errors
+    with appropriate exception types.
+
+    Yields:
+        None: Execution continues within the context block.
+    """  # noqa: DAR301
+    try:
+        yield
+    except SSL.SysCallError as ssl_syscall_err:
+        connection_error_map = {
+            errno.EBADF: ConnectionError,  # socket is gone?
+            errno.ECONNABORTED: ConnectionAbortedError,
+            errno.ECONNREFUSED: ConnectionRefusedError,
+            errno.ECONNRESET: ConnectionResetError,
+            errno.ENOTCONN: ConnectionError,
+            errno.EPIPE: BrokenPipeError,
+            errno.ESHUTDOWN: BrokenPipeError,
+        }
+        error_code = ssl_syscall_err.args[0] if ssl_syscall_err.args else None
+        error_msg = (
+            os.strerror(error_code)
+            if error_code is not None
+            else repr(ssl_syscall_err)
+        )
+        conn_err_cls = connection_error_map.get(
+            error_code,
+            ConnectionError,
+        )
+        raise conn_err_cls(
+            error_code,
+            f'Faied to {method_name!s} the PyOpenSSL connection: {error_msg!s}',
+        ) from ssl_syscall_err
+
+
 class SSLFileobjectMixin:
     """Base mixin for a TLS socket stream."""
 
@@ -269,6 +310,18 @@ def __init__(self, *args):
         self._ssl_conn = SSL.Connection(*args)
         self._lock = threading.RLock()
 
+    @_morph_syscall_to_connection_error('close')
+    def close(self):
+        """Close the connection, translating OpenSSL errors for shutdown."""
+        with self._lock:
+            return self._ssl_conn.close()
+
+    @_morph_syscall_to_connection_error('shutdown')
+    def shutdown(self):
+        """Shutdown the connection, translating OpenSSL errors."""
+        with self._lock:
+            return self._ssl_conn.shutdown()
+
 
 class pyOpenSSLAdapter(Adapter):
     """A wrapper for integrating :doc:`pyOpenSSL <pyopenssl:index>`."""

docs/changelog-fragments.d/786.bugfix.rst

@@ -0,0 +1,3 @@
+OpenSSL system call errors are now intercepted and reraised as standard Python ConnectionErrors.
+
+-- by :user:`julianz-`