Map PyOpenSSL SysCallErrors to standard Python ConnectionErrors

Author: julianz-

.flake8

@@ -138,6 +138,7 @@ per-file-ignores =
   cheroot/test/test_core.py: C815, DAR101, DAR201, DAR401, I003, I004, N805, N806, S101, WPS110, WPS111, WPS114, WPS121, WPS202, WPS204, WPS226, WPS229, WPS324, WPS421, WPS422, WPS432, WPS602
   cheroot/test/test_dispatch.py: DAR101, DAR201, S101, WPS111, WPS121, WPS422, WPS430
   cheroot/test/test_ssl.py: C818, DAR101, DAR201, DAR301, DAR401, E800, I001, I003, I004, I005, S101, S309, S404, S603, WPS100, WPS110, WPS111, WPS114, WPS121, WPS130, WPS201, WPS202, WPS204, WPS210, WPS211, WPS218, WPS219, WPS222, WPS226, WPS231, WPS235, WPS301, WPS324, WPS335, WPS336, WPS408, WPS420, WPS421, WPS422, WPS432, WPS441, WPS509, WPS608
+  cheroot/test/test_ssl_pyopenssl.py: DAR101, DAR201, WPS226
   cheroot/test/test_server.py: DAR101, DAR201, DAR301, I001, I003, I004, I005, S101, WPS110, WPS111, WPS118, WPS121, WPS122, WPS130, WPS201, WPS202, WPS210, WPS218, WPS226, WPS229, WPS324, WPS421, WPS422, WPS430, WPS432, WPS473, WPS509, WPS608
   cheroot/test/test_conn.py: DAR101, DAR201, DAR301, DAR401, E800, I001, I003, I004, I005, N802, N805, RST304, S101, S310, WPS100, WPS110, WPS111, WPS114, WPS115, WPS120, WPS121, WPS122, WPS201, WPS202, WPS204, WPS210, WPS211, WPS213, WPS214, WPS218, WPS219, WPS226, WPS231, WPS301, WPS402, WPS420, WPS421, WPS422, WPS429, WPS430, WPS432, WPS435, WPS447, WPS504, WPS509, WPS602
   cheroot/test/webtest.py: DAR101, DAR201, DAR401, I001, I003, I004, N802, RST303, RST304, S101, S104, WPS100, WPS110, WPS111, WPS115, WPS120, WPS121, WPS122, WPS201, WPS202, WPS204, WPS210, WPS211, WPS213, WPS214, WPS220, WPS221, WPS223, WPS229, WPS230, WPS231, WPS236, WPS237, WPS301, WPS338, WPS414, WPS420, WPS421, WPS422, WPS430, WPS432, WPS501, WPS505, WPS601

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."""
 
@@ -229,7 +270,9 @@ def proxy_wrapper(self, *args):
                     new_args = (
                         args[:] if method not in proxy_methods_no_args else []
                     )
-                    return getattr(self._ssl_conn, method)(*new_args)
+                    # translate any SysCallError to ConnectionError
+                    with _morph_syscall_to_connection_error(method):
+                        return getattr(self._ssl_conn, method)(*new_args)
                 finally:
                     self._lock.release()
 

cheroot/test/test_ssl_pyopenssl.py

@@ -0,0 +1,78 @@
+"""Tests for :py:mod: `cheroot.ssl.pyopenssl` :py:class:`SSLConnection` wrapper."""
+
+import errno
+
+import pytest
+
+from OpenSSL import SSL
+
+from cheroot.ssl.pyopenssl import SSLConnection
+
+
+@pytest.fixture
+def mock_ssl_context(mocker):
+    """Fixture providing a mock instance of :py:class:`SSL.Context`."""
+    mock_context = mocker.Mock(spec=SSL.Context)
+
+    # Add a mock _context attribute to simulate SSL.Context behavior
+    mock_context._context = mocker.Mock()
+    return mock_context
+
+
+# (Method Name, SysCallError errno, Expected Exception Type)
+ERROR_MAPPINGS = (
+    ('close', errno.EBADF, ConnectionError),
+    ('close', errno.ECONNABORTED, ConnectionAbortedError),
+    ('shutdown', errno.EPIPE, BrokenPipeError),  # Test 'shutdown' here
+    (
+        'shutdown',
+        errno.ECONNRESET,
+        ConnectionResetError,
+    ),  # Test 'shutdown' here
+    ('close', errno.ENOTCONN, ConnectionError),
+    ('close', errno.EPIPE, BrokenPipeError),
+    ('close', errno.ESHUTDOWN, BrokenPipeError),
+)
+
+
+@pytest.mark.parametrize(
+    (
+        'tested_method_name',
+        'simulated_errno',
+        'expected_exception',
+    ),
+    ERROR_MAPPINGS,
+)
+def test_close_morphs_syscall_error_correctly(
+    mocker,
+    mock_ssl_context,
+    tested_method_name,
+    simulated_errno,
+    expected_exception,
+):
+    """Check ``SSLConnection.close()`` morphs ``SysCallError`` to ``ConnectionError``."""
+    # Prevents the real OpenSSL.SSL.Connection.__init__ from running
+    mocker.patch('OpenSSL.SSL.Connection')
+
+    # Create SSLConnection object. The patched SSL.Connection() call returns
+    # a mock that is stored internally as conn._ssl_conn.
+    conn = SSLConnection(mock_ssl_context)
+
+    # Define specific OpenSSL error based on the parameter
+    simulated_error = SSL.SysCallError(
+        simulated_errno,
+        'Simulated connection error',
+    )
+
+    # Dynamically retrieve the method on the underlying mock
+    underlying_method = getattr(conn._ssl_conn, tested_method_name)
+
+    # Patch the method to raise the simulated error
+    underlying_method.side_effect = simulated_error
+
+    # Assert the expected exception is raised based on the parameter
+    with pytest.raises(expected_exception) as excinfo:
+        getattr(conn, tested_method_name)()
+
+    # Assert the original SysCallError is included in the new exception's cause
+    assert excinfo.value.__cause__ is simulated_error

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-`