[PR #11148/86a9a38 backport][3.12] Abort ssl connections on close when ssl_shutdown_timeout is 0 (#11155)

Author: bdraco

CHANGES/11148.deprecation.rst

@@ -0,0 +1 @@
+11148.feature.rst

CHANGES/11148.feature.rst

@@ -0,0 +1,10 @@
+Improved SSL connection handling by changing the default ``ssl_shutdown_timeout``
+from ``0.1`` to ``0`` seconds. SSL connections now use Python's default graceful
+shutdown during normal operation but are aborted immediately when the connector
+is closed, providing optimal behavior for both cases. Also added support for
+``ssl_shutdown_timeout=0`` on all Python versions. Previously, this value was
+rejected on Python 3.11+ and ignored on earlier versions. Non-zero values on
+Python < 3.11 now trigger a ``RuntimeWarning`` -- by :user:`bdraco`.
+
+The ``ssl_shutdown_timeout`` parameter is now deprecated and will be removed in
+aiohttp 4.0 as there is no clear use case for changing the default.

aiohttp/client.py

@@ -303,7 +303,7 @@ def __init__(
         max_field_size: int = 8190,
         fallback_charset_resolver: _CharsetResolver = lambda r, b: "utf-8",
         middlewares: Sequence[ClientMiddlewareType] = (),
-        ssl_shutdown_timeout: Optional[float] = 0.1,
+        ssl_shutdown_timeout: Union[_SENTINEL, None, float] = sentinel,
     ) -> None:
         # We initialise _connector to None immediately, as it's referenced in __del__()
         # and could cause issues if an exception occurs during initialisation.
@@ -361,6 +361,13 @@ def __init__(
                     "timeout.connect"
                 )
 
+        if ssl_shutdown_timeout is not sentinel:
+            warnings.warn(
+                "The ssl_shutdown_timeout parameter is deprecated and will be removed in aiohttp 4.0",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
         if connector is None:
             connector = TCPConnector(ssl_shutdown_timeout=ssl_shutdown_timeout)
 

aiohttp/client_proto.py

@@ -95,6 +95,15 @@ def close(self) -> None:
             self._payload = None
             self._drop_timeout()
 
+    def abort(self) -> None:
+        self._exception = None  # Break cyclic references
+        transport = self.transport
+        if transport is not None:
+            transport.abort()
+            self.transport = None
+            self._payload = None
+            self._drop_timeout()
+
     def is_connected(self) -> bool:
         return self.transport is not None and not self.transport.is_closing()
 

aiohttp/connector.py

@@ -52,6 +52,7 @@
 from .client_proto import ResponseHandler
 from .client_reqrep import ClientRequest, Fingerprint, _merge_ssl_params
 from .helpers import (
+    _SENTINEL,
     ceil_timeout,
     is_ip_address,
     noop,
@@ -231,15 +232,19 @@ def closed(self) -> bool:
 class _TransportPlaceholder:
     """placeholder for BaseConnector.connect function"""
 
-    __slots__ = ("closed",)
+    __slots__ = ("closed", "transport")
 
     def __init__(self, closed_future: asyncio.Future[Optional[Exception]]) -> None:
         """Initialize a placeholder for a transport."""
         self.closed = closed_future
+        self.transport = None
 
     def close(self) -> None:
         """Close the placeholder."""
 
+    def abort(self) -> None:
+        """Abort the placeholder (does nothing)."""
+
 
 class BaseConnector:
     """Base connector class.
@@ -469,9 +474,14 @@ def _cleanup_closed(self) -> None:
                 timeout_ceil_threshold=self._timeout_ceil_threshold,
             )
 
-    def close(self) -> Awaitable[None]:
-        """Close all opened transports."""
-        if not (waiters := self._close()):
+    def close(self, *, abort_ssl: bool = False) -> Awaitable[None]:
+        """Close all opened transports.
+
+        :param abort_ssl: If True, SSL connections will be aborted immediately
+                         without performing the shutdown handshake. This provides
+                         faster cleanup at the cost of less graceful disconnection.
+        """
+        if not (waiters := self._close(abort_ssl=abort_ssl)):
             # If there are no connections to close, we can return a noop
             # awaitable to avoid scheduling a task on the event loop.
             return _DeprecationWaiter(noop())
@@ -484,7 +494,7 @@ def close(self) -> Awaitable[None]:
             task = self._loop.create_task(coro)
         return _DeprecationWaiter(task)
 
-    def _close(self) -> List[Awaitable[object]]:
+    def _close(self, *, abort_ssl: bool = False) -> List[Awaitable[object]]:
         waiters: List[Awaitable[object]] = []
 
         if self._closed:
@@ -506,12 +516,26 @@ def _close(self) -> List[Awaitable[object]]:
 
             for data in self._conns.values():
                 for proto, _ in data:
-                    proto.close()
+                    if (
+                        abort_ssl
+                        and proto.transport
+                        and proto.transport.get_extra_info("sslcontext") is not None
+                    ):
+                        proto.abort()
+                    else:
+                        proto.close()
                     if closed := proto.closed:
                         waiters.append(closed)
 
             for proto in self._acquired:
-                proto.close()
+                if (
+                    abort_ssl
+                    and proto.transport
+                    and proto.transport.get_extra_info("sslcontext") is not None
+                ):
+                    proto.abort()
+                else:
+                    proto.close()
                 if closed := proto.closed:
                     waiters.append(closed)
 
@@ -881,11 +905,12 @@ class TCPConnector(BaseConnector):
     socket_factory - A SocketFactoryType function that, if supplied,
                      will be used to create sockets given an
                      AddrInfoType.
-    ssl_shutdown_timeout - Grace period for SSL shutdown handshake on TLS
-                           connections. Default is 0.1 seconds. This usually
-                           allows for a clean SSL shutdown by notifying the
-                           remote peer of connection closure, while avoiding
-                           excessive delays during connector cleanup.
+    ssl_shutdown_timeout - DEPRECATED. Will be removed in aiohttp 4.0.
+                           Grace period for SSL shutdown handshake on TLS
+                           connections. Default is 0 seconds (immediate abort).
+                           This parameter allowed for a clean SSL shutdown by
+                           notifying the remote peer of connection closure,
+                           while avoiding excessive delays during connector cleanup.
                            Note: Only takes effect on Python 3.11+.
     """
 
@@ -913,7 +938,7 @@ def __init__(
         happy_eyeballs_delay: Optional[float] = 0.25,
         interleave: Optional[int] = None,
         socket_factory: Optional[SocketFactoryType] = None,
-        ssl_shutdown_timeout: Optional[float] = 0.1,
+        ssl_shutdown_timeout: Union[_SENTINEL, None, float] = sentinel,
     ):
         super().__init__(
             keepalive_timeout=keepalive_timeout,
@@ -946,26 +971,57 @@ def __init__(
         self._interleave = interleave
         self._resolve_host_tasks: Set["asyncio.Task[List[ResolveResult]]"] = set()
         self._socket_factory = socket_factory
-        self._ssl_shutdown_timeout = ssl_shutdown_timeout
+        self._ssl_shutdown_timeout: Optional[float]
+        # Handle ssl_shutdown_timeout with warning for Python < 3.11
+        if ssl_shutdown_timeout is sentinel:
+            self._ssl_shutdown_timeout = 0
+        else:
+            # Deprecation warning for ssl_shutdown_timeout parameter
+            warnings.warn(
+                "The ssl_shutdown_timeout parameter is deprecated and will be removed in aiohttp 4.0",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            if (
+                sys.version_info < (3, 11)
+                and ssl_shutdown_timeout is not None
+                and ssl_shutdown_timeout != 0
+            ):
+                warnings.warn(
+                    f"ssl_shutdown_timeout={ssl_shutdown_timeout} is ignored on Python < 3.11; "
+                    "only ssl_shutdown_timeout=0 is supported. The timeout will be ignored.",
+                    RuntimeWarning,
+                    stacklevel=2,
+                )
+            self._ssl_shutdown_timeout = ssl_shutdown_timeout
 
-    def _close(self) -> List[Awaitable[object]]:
+    def _close(self, *, abort_ssl: bool = False) -> List[Awaitable[object]]:
         """Close all ongoing DNS calls."""
         for fut in chain.from_iterable(self._throttle_dns_futures.values()):
             fut.cancel()
 
-        waiters = super()._close()
+        waiters = super()._close(abort_ssl=abort_ssl)
 
         for t in self._resolve_host_tasks:
             t.cancel()
             waiters.append(t)
 
         return waiters
 
-    async def close(self) -> None:
-        """Close all opened transports."""
+    async def close(self, *, abort_ssl: bool = False) -> None:
+        """
+        Close all opened transports.
+
+        :param abort_ssl: If True, SSL connections will be aborted immediately
+                         without performing the shutdown handshake. If False (default),
+                         the behavior is determined by ssl_shutdown_timeout:
+                         - If ssl_shutdown_timeout=0: connections are aborted
+                         - If ssl_shutdown_timeout>0: graceful shutdown is performed
+        """
         if self._resolver_owner:
             await self._resolver.close()
-        await super().close()
+        # Use abort_ssl param if explicitly set, otherwise use ssl_shutdown_timeout default
+        await super().close(abort_ssl=abort_ssl or self._ssl_shutdown_timeout == 0)
 
     @property
     def family(self) -> int:
@@ -1200,7 +1256,7 @@ async def _wrap_create_connection(
                 # Add ssl_shutdown_timeout for Python 3.11+ when SSL is used
                 if (
                     kwargs.get("ssl")
-                    and self._ssl_shutdown_timeout is not None
+                    and self._ssl_shutdown_timeout
                     and sys.version_info >= (3, 11)
                 ):
                     kwargs["ssl_shutdown_timeout"] = self._ssl_shutdown_timeout
@@ -1343,10 +1399,7 @@ async def _start_tls_connection(
             ):
                 try:
                     # ssl_shutdown_timeout is only available in Python 3.11+
-                    if (
-                        sys.version_info >= (3, 11)
-                        and self._ssl_shutdown_timeout is not None
-                    ):
+                    if sys.version_info >= (3, 11) and self._ssl_shutdown_timeout:
                         tls_transport = await self._loop.start_tls(
                             underlying_transport,
                             tls_proto,
@@ -1367,7 +1420,10 @@ async def _start_tls_connection(
                     # We need to close the underlying transport since
                     # `start_tls()` probably failed before it had a
                     # chance to do this:
-                    underlying_transport.close()
+                    if self._ssl_shutdown_timeout == 0:
+                        underlying_transport.abort()
+                    else:
+                        underlying_transport.close()
                     raise
                 if isinstance(tls_transport, asyncio.Transport):
                     fingerprint = self._get_fingerprint(req)

docs/client_reference.rst

@@ -58,7 +58,7 @@ The client session supports the context manager protocol for self closing.
                          max_line_size=8190, \
                          max_field_size=8190, \
                          fallback_charset_resolver=lambda r, b: "utf-8", \
-                         ssl_shutdown_timeout=0.1)
+                         ssl_shutdown_timeout=0)
 
    The class for creating client sessions and making requests.
 
@@ -257,16 +257,31 @@ The client session supports the context manager protocol for self closing.
 
       .. versionadded:: 3.8.6
 
-   :param float ssl_shutdown_timeout: Grace period for SSL shutdown handshake on TLS
-      connections (``0.1`` seconds by default). This usually provides sufficient time
-      to notify the remote peer of connection closure, helping prevent broken
-      connections on the server side, while minimizing delays during connector
-      cleanup. This timeout is passed to the underlying :class:`TCPConnector`
-      when one is created automatically. Note: This parameter only takes effect
-      on Python 3.11+.
+   :param float ssl_shutdown_timeout: **(DEPRECATED)** This parameter is deprecated
+      and will be removed in aiohttp 4.0. Grace period for SSL shutdown handshake on
+      TLS connections when the connector is closed (``0`` seconds by default).
+      By default (``0``), SSL connections are aborted immediately when the
+      connector is closed, without performing the shutdown handshake. During
+      normal operation, SSL connections use Python's default SSL shutdown
+      behavior. Setting this to a positive value (e.g., ``0.1``) will perform
+      a graceful shutdown when closing the connector, notifying the remote
+      peer which can help prevent "connection reset" errors at the cost of
+      additional cleanup time. This timeout is passed to the underlying
+      :class:`TCPConnector` when one is created automatically.
+      Note: On Python versions prior to 3.11, only a value of ``0`` is supported;
+      other values will trigger a warning.
 
       .. versionadded:: 3.12.5
 
+      .. versionchanged:: 3.12.11
+         Changed default from ``0.1`` to ``0`` to abort SSL connections
+         immediately when the connector is closed. Added support for
+         ``ssl_shutdown_timeout=0`` on all Python versions. A :exc:`RuntimeWarning`
+         is issued when non-zero values are passed on Python < 3.11.
+
+      .. deprecated:: 3.12.11
+         This parameter is deprecated and will be removed in aiohttp 4.0.
+
    .. attribute:: closed
 
       ``True`` if the session has been closed, ``False`` otherwise.
@@ -1196,7 +1211,7 @@ is controlled by *force_close* constructor's parameter).
                  force_close=False, limit=100, limit_per_host=0, \
                  enable_cleanup_closed=False, timeout_ceil_threshold=5, \
                  happy_eyeballs_delay=0.25, interleave=None, loop=None, \
-                 socket_factory=None, ssl_shutdown_timeout=0.1)
+                 socket_factory=None, ssl_shutdown_timeout=0)
 
    Connector for working with *HTTP* and *HTTPS* via *TCP* sockets.
 
@@ -1323,16 +1338,29 @@ is controlled by *force_close* constructor's parameter).
 
         .. versionadded:: 3.12
 
-   :param float ssl_shutdown_timeout: Grace period for SSL shutdown on TLS
-      connections (``0.1`` seconds by default). This parameter balances two
-      important considerations: usually providing sufficient time to notify
-      the remote server (which helps prevent "connection reset" errors),
-      while avoiding unnecessary delays during connector cleanup.
-      The default value provides a reasonable compromise for most use cases.
-      Note: This parameter only takes effect on Python 3.11+.
+   :param float ssl_shutdown_timeout: **(DEPRECATED)** This parameter is deprecated
+      and will be removed in aiohttp 4.0. Grace period for SSL shutdown on TLS
+      connections when the connector is closed (``0`` seconds by default).
+      By default (``0``), SSL connections are aborted immediately when the
+      connector is closed, without performing the shutdown handshake. During
+      normal operation, SSL connections use Python's default SSL shutdown
+      behavior. Setting this to a positive value (e.g., ``0.1``) will perform
+      a graceful shutdown when closing the connector, notifying the remote
+      server which can help prevent "connection reset" errors at the cost of
+      additional cleanup time. Note: On Python versions prior to 3.11, only
+      a value of ``0`` is supported; other values will trigger a warning.
 
         .. versionadded:: 3.12.5
 
+        .. versionchanged:: 3.12.11
+           Changed default from ``0.1`` to ``0`` to abort SSL connections
+           immediately when the connector is closed. Added support for
+           ``ssl_shutdown_timeout=0`` on all Python versions. A :exc:`RuntimeWarning`
+           is issued when non-zero values are passed on Python < 3.11.
+
+        .. deprecated:: 3.12.11
+           This parameter is deprecated and will be removed in aiohttp 4.0.
+
    .. attribute:: family
 
       *TCP* socket family e.g. :data:`socket.AF_INET` or

tests/test_client_functional.py

@@ -698,7 +698,10 @@ async def test_ssl_client_shutdown_timeout(
 ) -> None:
     # Test that ssl_shutdown_timeout is properly used during connection closure
 
-    connector = aiohttp.TCPConnector(ssl=client_ssl_ctx, ssl_shutdown_timeout=0.1)
+    with pytest.warns(
+        DeprecationWarning, match="ssl_shutdown_timeout parameter is deprecated"
+    ):
+        connector = aiohttp.TCPConnector(ssl=client_ssl_ctx, ssl_shutdown_timeout=0.1)
 
     async def streaming_handler(request: web.Request) -> NoReturn:
         # Create a streaming response that continuously sends data