Translate OpenSSL SysCallError to ConnectionError

PyOpenSSL raises SysCallError which cheroot does not translate, leading to
unhandled exceptions when the underlying connection is closed or shut down
abruptly. This commit ensures all relevant errno codes are translated into
standard Python ConnectionError types for reliable handling by consumers.

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'Error in calling {method_name!s} on PyOpenSSL connection: {error_msg!s}',
+        ) from ssl_syscall_err
+
+
 class SSLFileobjectMixin:
     """Base mixin for a TLS socket stream."""
 
@@ -224,14 +265,12 @@ def lock_decorator(method):
             """Create a proxy method for a new class."""
 
             def proxy_wrapper(self, *args):
-                self._lock.acquire()
-                try:
-                    new_args = (
-                        args[:] if method not in proxy_methods_no_args else []
-                    )
+                new_args = (
+                    args[:] if method not in proxy_methods_no_args else []
+                )
+                # translate any SysCallError to ConnectionError
+                with _morph_syscall_to_connection_error(method), self._lock:
                     return getattr(self._ssl_conn, method)(*new_args)
-                finally:
-                    self._lock.release()
 
             return proxy_wrapper
 

cheroot/test/ssl/test_ssl_pyopenssl.py

@@ -0,0 +1,106 @@
+"""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
+
+
+@pytest.mark.filterwarnings('ignore:Non-callable called')
+@pytest.mark.parametrize(
+    (
+        'tested_method_name',
+        'simulated_errno',
+        'expected_exception',
+    ),
+    (
+        pytest.param('close', errno.EBADF, ConnectionError, id='close-EBADF'),
+        pytest.param(
+            'close',
+            errno.ECONNABORTED,
+            ConnectionAbortedError,
+            id='close-ECONNABORTED',
+        ),
+        pytest.param(
+            'send',
+            errno.EPIPE,
+            BrokenPipeError,
+            id='send-EPIPE',
+        ),  # Expanded coverage
+        pytest.param(
+            'shutdown',
+            errno.EPIPE,
+            BrokenPipeError,
+            id='shutdown-EPIPE',
+        ),
+        pytest.param(
+            'shutdown',
+            errno.ECONNRESET,
+            ConnectionResetError,
+            id='shutdown-ECONNRESET',
+        ),
+        pytest.param(
+            'close',
+            errno.ENOTCONN,
+            ConnectionError,
+            id='close-ENOTCONN',
+        ),
+        pytest.param('close', errno.EPIPE, BrokenPipeError, id='close-EPIPE'),
+        pytest.param(
+            'close',
+            errno.ESHUTDOWN,
+            BrokenPipeError,
+            id='close-ESHUTDOWN',
+        ),
+    ),
+)
+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
+
+    expected_match = (
+        f'.*Error in calling {tested_method_name} on PyOpenSSL connection.*'
+    )
+
+    # Assert the expected exception is raised based on the parameter
+    with pytest.raises(expected_exception, match=expected_match) 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 re-raised as standard Python :exc:`ConnectionErrors`.
+
+-- by :user:`julianz-`