Add TLS session resumption via SSLSessionCache

[sylwiaszunejko]

Summary

This PR implements TLS session resumption for the Python driver. After the first
successful TLS handshake with a node, the negotiated session is stored in a
thread-safe cache and reused on subsequent connections, skipping the full
handshake.

Both TLS 1.2 (session IDs) and TLS 1.3 (session tickets / PSK) are supported.

Changes

cassandra/connection.py — SSLSessionCache class & endpoint keys

• _SessionCacheEntry namedtuple stores (session, timestamp) for TTL tracking.
• SSLSessionCache: a thread-safe OrderedDict-based cache with LRU eviction,
  TTL expiration, and periodic cleanup (every 100 set() calls), keyed by
  endpoint tls_session_cache_key.
• Configurable max_size (default 100) and ttl (default 3600 s).
• Base EndPoint class provides a default tls_session_cache_key property
  returning (address, port). Subclasses override for context-specific keys:
  • DefaultEndPoint: (address, port) — inherits default
  • SniEndPoint: (address, port, server_name) — prevents proxy collisions
  • UnixSocketEndPoint: (unix_socket_path,)
  • ClientRoutesEndPoint: (host_id, address, port)

cassandra/connection.py — Connection wiring

• Connection gains _ssl_session_cache attribute, set via ssl_session_cache
  kwarg in __init__.
• _wrap_socket_from_context() restores a cached session via
  ssl_sock.session = ... after wrap_socket(); gracefully handles
  ssl.SSLError / AttributeError if the server rejects the session.
• _ssl_session_cache_key() helper delegates to
  endpoint.tls_session_cache_key.
• _cache_tls_session_if_needed() stores socket.session in the cache when
  ssl_context is set and the session is non-None.
• Sessions are cached at three points to cover both TLS 1.2 and 1.3:
  1. After _initiate_connection() in _connect_socket() — TLS 1.2 sessions
     are available immediately after connect.
  2. After ReadyMessage in _handle_startup_response() — TLS 1.3 tickets
     arrive asynchronously after the first application-data exchange.
  3. After AuthSuccessMessage in _handle_auth_response() — same TLS 1.3
     coverage for authenticated connections.

cassandra/cluster.py — Cluster integration

• Imports SSLSessionCache.
• Adds ssl_session_cache class attribute with docstring.
• __init__ accepts ssl_session_cache=_NOT_SET parameter.
• Auto-creates an SSLSessionCache() when ssl_context or ssl_options are
  set; no configuration required for the common case.
• Pass ssl_session_cache=None explicitly to opt out.
• A custom SSLSessionCache(max_size=…, ttl=…) can be supplied.
• _make_connection_kwargs() passes the cache to every Connection via
  kwargs_dict.setdefault('ssl_session_cache', self.ssl_session_cache).

cassandra/io/eventletreactor.py — Eventlet (PyOpenSSL) support

• _wrap_socket_from_context() restores cached PyOpenSSL sessions via
  set_session() before the handshake.
• _initiate_connection() calls _cache_pyopenssl_session() after
  do_handshake().
• New _cache_pyopenssl_session() helper stores the session via
  get_session(), logs whether the session was reused
  (session_reused()), and catches all exceptions silently.

cassandra/io/twistedreactor.py — Twisted (PyOpenSSL) support

• _SSLCreator.__init__ accepts an optional ssl_session_cache parameter.
• clientConnectionForTLS() restores cached sessions via set_session().
• info_callback() stores sessions after SSL_CB_HANDSHAKE_DONE via
  get_session(), logs reuse status.
• TwistedConnection.add_connection() passes ssl_session_cache=self._ssl_session_cache
  to _SSLCreator.

Tests

tests/unit/test_connection.py

• TestSSLSessionCache — empty lookup, set/get, key isolation by
  address/port/SNI, overwrite, thread safety, TTL expiration, LRU eviction,
  max_size enforcement, clear(), clear_expired(), automatic periodic
  cleanup, None session handling.
• TestEndPointTLSSessionCacheKey — cache key correctness for
  DefaultEndPoint, SniEndPoint, UnixSocketEndPoint,
  ClientRoutesEndPoint, plus isolation between different paths/addresses.
• TestConnectionSSLSessionRestore — session restore from cache,
  tolerance when cache is None, ssl.SSLError on session setter,
  SNI-specific cached session lookup.
• TestConnectionCacheTLSSession — session stored after connect,
  no-op when session=None, no-op when cache=None, no-op when
  ssl_context=None, SNI-specific key used for storage.

tests/unit/test_cluster.py

• TestSSLSessionCacheAutoCreation — auto-create with ssl_context,
  auto-create with ssl_options, no cache without TLS, explicit None
  opt-out, custom cache injection, cache passed to connection_factory.

Fixes: https://scylladb.atlassian.net/browse/DRIVER-165

Pre-review checklist

• I have split my patch into logically separate commits.
• All commit messages clearly explain what they change and why.
• I added relevant tests for new features and bug fixes.
• All commits compile, pass static checks and pass test.
• PR description sums up the changes and reasons why they should be introduced.
• I have provided docstrings for the public items that I want to introduce.
• I have adjusted the documentation in ./docs/source/.
• I added appropriate Fixes: annotations to PR description.

[Lorak-mmk]

This reduces reconnection latency and CPU overhead, especially in
deployments with short-lived connections or frequent reconnects.

Such claims would ideally be supported by benchmarks. Could you try to create some?
I very vaguely remember this feature being postponed because the performance gains were underwhelming (but perhaps memory is failing me).

[sylwiaszunejko]

This reduces reconnection latency and CPU overhead, especially in
deployments with short-lived connections or frequent reconnects.

Such claims would ideally be supported by benchmarks. Could you try to create some? I very vaguely remember this feature being postponed because the performance gains were underwhelming (but perhaps memory is failing me).

That's the goal, but you're right, I don't have any tests to prove that, removed this claim from the PR description. If I manage to create proper benchmarks I will update on that

[mykaul]

We could, if it helps, only support this for TLS 1.3.

[sylwiaszunejko]

@dkropachev @Lorak-mmk I pushed changes with improvement from older Dmitry's PR, will update PR description soon

[dkropachev]

I rechecked the TLS session-resumption path against the current branch. The ssl_options configuration still builds a fresh SSLContext per Connection, and a cached stdlib session from the previous connection is incompatible with that new context. I reproduced the failure locally on Python 3.10.12; the session restore path raises ValueError: Session refers to a different SSLContext. Since the new code only catches AttributeError and ssl.SSLError, reconnects fail instead of falling back to a full handshake, and the regression is enabled by default because Cluster auto-creates SSLSessionCache for ssl_options.

[dkropachev]

Two blocking issues from local validation:

1. Twisted caches a TLS session even after hostname verification has already failed, which lets an untrusted peer populate the resumption cache.
2. SSLSessionCache accepts max_size <= 0 and then crashes on the first insert (KeyError from popitem() on an empty OrderedDict).

[dkropachev]

failVerification() should short-circuit this callback. As written, a hostname mismatch still falls through and caches the just-negotiated session, so an untrusted peer can seed the resumption cache. I reproduced this locally with a mocked _SSLCreator: failVerification was called and the session still landed in SSLSessionCache.

[dkropachev]

SSLSessionCache(max_size=0) currently crashes on the first insert: len(self._sessions) >= self._max_size is already true for an empty cache, so popitem(last=False) raises KeyError. Since this is now a public tuning knob, please validate max_size > 0 (and probably ttl > 0) or define zero as a disabled cache, and cover it with a unit test.

[dkropachev]

Two correctness issues need attention before this lands: the PyOpenSSL TLS 1.3 cache point is too early to capture the resumable session, and the cache can evict a live entry while expired ones remain resident.

[dkropachev]

For the PyOpenSSL reactors this is still too early for TLS 1.3. At SSL_CB_HANDSHAKE_DONE, connection.get_session() is the pre-ticket session; OpenSSL swaps in the resumable one only after the first application read. A safer fix is to keep info_callback() for hostname verification only, then cache from the live OpenSSL.SSL.Connection after the first CQL response (ReadyMessage / AuthSuccessMessage), mirroring the late cache point already used in Connection._handle_startup_response() and _handle_auth_response(). The same timing change is needed in EventletConnection, where _cache_pyopenssl_session() currently runs immediately after do_handshake().

[dkropachev]

This evicts the current LRU entry before giving expired entries a chance to fall out. If the cache fills up between periodic cleanups, an expired session can stay resident while a still-valid session gets dropped, which wastes capacity and reduces the resumption hit rate under small max_size / short ttl settings.