PYTHON-5272 Implement TLS session resumption for connections (#2864)

Author: blink1073

doc/changelog.rst

@@ -1,6 +1,14 @@
 Changelog
 =========
 
+Changes in Version 4.18.0
+-------------------------
+
+- Improved TLS connection performance by reusing TLS sessions across connections
+  to the same server, avoiding a full handshake on each new connection.
+  Session resumption is supported on all Python versions for synchronous clients
+  and on Python 3.11+ for async clients.
+
 Changes in Version 4.17.0 (2026/04/20)
 --------------------------------------
 

pymongo/asynchronous/pool.py

@@ -754,6 +754,9 @@ def __init__(
         self._pending = 0
         self._max_connecting = self.opts.max_connecting
         self._client_id = client_id
+        self._ssl_session_cache: Optional[list[Any]] = (
+            [None] if self.opts._ssl_context is not None else None
+        )
         # Log before publishing event to prevent potential listener preemption in tests
         if self.enabled_for_logging and _CONNECTION_LOGGER.isEnabledFor(logging.DEBUG):
             _debug_log(
@@ -1041,7 +1044,9 @@ async def connect(self, handler: Optional[_MongoClientErrorHandler] = None) -> A
             listeners.publish_connection_created(self.address, conn_id)
 
         try:
-            networking_interface = await _configured_protocol_interface(self.address, self.opts)
+            networking_interface = await _configured_protocol_interface(
+                self.address, self.opts, self._ssl_session_cache
+            )
         # Catch KeyboardInterrupt, CancelledError, etc. and cleanup.
         except BaseException as error:
             async with self.lock:

pymongo/pool_shared.py

@@ -47,6 +47,14 @@
     from pymongo.pyopenssl_context import _sslConn
     from pymongo.typings import _Address
 
+
+def _get_ssl_session(ssl_sock: Any) -> Optional[Any]:
+    """Return the TLS session from an SSL socket, handling both PyOpenSSL and stdlib ssl."""
+    if hasattr(ssl_sock, "get_session"):
+        return ssl_sock.get_session()
+    return getattr(ssl_sock, "session", None)
+
+
 try:
     from fcntl import F_GETFD, F_SETFD, FD_CLOEXEC, fcntl
 
@@ -297,7 +305,9 @@ async def _async_configured_socket(
 
 
 async def _configured_protocol_interface(
-    address: _Address, options: PoolOptions
+    address: _Address,
+    options: PoolOptions,
+    ssl_session_cache: Optional[list[Any]] = None,
 ) -> AsyncNetworkingInterface:
     """Given (host, port) and PoolOptions, return a configured AsyncNetworkingInterface.
 
@@ -317,6 +327,22 @@ async def _configured_protocol_interface(
         )
 
     host = address[0]
+    # asyncio does not support TLS session resumption natively (cpython#79152,
+    # closed without a fix).  On Python 3.11+ SSLProtocol.__init__ calls
+    # wrap_bio() synchronously before the first event-loop yield, so setting
+    # sslobject_class is race-free.  Session injection is skipped on older
+    # Python versions.  (The async path always uses stdlib ssl, never PyOpenSSL.)
+    if ssl_session_cache is not None and sys.version_info >= (3, 11):
+        session = ssl_session_cache[0]
+        if session is not None:
+            _session = session
+
+            class _SessionSSLObject(ssl.SSLObject):
+                def __init__(self, *args: Any, **kwargs: Any) -> None:
+                    super().__init__(*args, **kwargs)
+                    self.session = _session
+
+            ssl_context.sslobject_class = _SessionSSLObject  # type: ignore[attr-defined]
     try:
         # We have to pass hostname / ip address to wrap_socket
         # to use SSLContext.check_hostname.
@@ -336,6 +362,7 @@ async def _configured_protocol_interface(
         # mismatch, will be turned into ServerSelectionTimeoutErrors later.
         details = _get_timeout_details(options)
         _raise_connection_failure(address, exc, "SSL handshake failed: ", timeout_details=details)
+
     if (
         ssl_context.verify_mode
         and not ssl_context.check_hostname
@@ -347,6 +374,13 @@ async def _configured_protocol_interface(
             transport.abort()
             raise
 
+    if ssl_session_cache is not None:
+        ssl_obj = transport.get_extra_info("ssl_object")
+        if ssl_obj is not None:
+            new_session = ssl_obj.session
+            if new_session is not None:
+                ssl_session_cache[0] = new_session
+
     return AsyncNetworkingInterface((transport, protocol))
 
 
@@ -469,7 +503,11 @@ def _configured_socket(address: _Address, options: PoolOptions) -> Union[socket.
     return ssl_sock
 
 
-def _configured_socket_interface(address: _Address, options: PoolOptions) -> NetworkingInterface:
+def _configured_socket_interface(
+    address: _Address,
+    options: PoolOptions,
+    ssl_session_cache: Optional[list[Any]] = None,
+) -> NetworkingInterface:
     """Given (host, port) and PoolOptions, return a NetworkingInterface wrapping a configured socket.
 
     Can raise socket.error, ConnectionFailure, or _CertificateError.
@@ -484,13 +522,14 @@ def _configured_socket_interface(address: _Address, options: PoolOptions) -> Net
         return NetworkingInterface(sock)
 
     host = address[0]
+    session = ssl_session_cache[0] if ssl_session_cache is not None else None
     try:
         # We have to pass hostname / ip address to wrap_socket
         # to use SSLContext.check_hostname.
         if _has_sni(True):
-            ssl_sock = ssl_context.wrap_socket(sock, server_hostname=host)
+            ssl_sock = ssl_context.wrap_socket(sock, server_hostname=host, session=session)
         else:
-            ssl_sock = ssl_context.wrap_socket(sock)
+            ssl_sock = ssl_context.wrap_socket(sock, session=session)
     except _CertificateError:
         sock.close()
         # Raise _CertificateError directly like we do after match_hostname
@@ -514,5 +553,10 @@ def _configured_socket_interface(address: _Address, options: PoolOptions) -> Net
             ssl_sock.close()
             raise
 
+    if ssl_session_cache is not None:
+        new_session = _get_ssl_session(ssl_sock)
+        if new_session is not None:
+            ssl_session_cache[0] = new_session
+
     ssl_sock.settimeout(options.socket_timeout)
     return NetworkingInterface(ssl_sock)

pymongo/synchronous/pool.py

@@ -752,6 +752,9 @@ def __init__(
         self._pending = 0
         self._max_connecting = self.opts.max_connecting
         self._client_id = client_id
+        self._ssl_session_cache: Optional[list[Any]] = (
+            [None] if self.opts._ssl_context is not None else None
+        )
         # Log before publishing event to prevent potential listener preemption in tests
         if self.enabled_for_logging and _CONNECTION_LOGGER.isEnabledFor(logging.DEBUG):
             _debug_log(
@@ -1037,7 +1040,9 @@ def connect(self, handler: Optional[_MongoClientErrorHandler] = None) -> Connect
             listeners.publish_connection_created(self.address, conn_id)
 
         try:
-            networking_interface = _configured_socket_interface(self.address, self.opts)
+            networking_interface = _configured_socket_interface(
+                self.address, self.opts, self._ssl_session_cache
+            )
         # Catch KeyboardInterrupt, CancelledError, etc. and cleanup.
         except BaseException as error:
             with self.lock: