Add TLS session resumption via SSLSessionCache

[sylwiaszunejko]

What and why

A shard-aware driver opens one TLS connection per shard to every node, and each one currently
pays for a full handshake — certificate exchange plus a signature, which is the expensive part,
especially with certificate authentication. TLS lets a client skip that by replaying a session
established earlier with the same peer (RFC 5077 tickets for TLS 1.2, RFC 8446 PSKs for
TLS 1.3), but OpenSSL never does this on its own: the client has to hold on to the session and
offer it explicitly on the next connection. Neither the stdlib ssl module nor pyOpenSSL
exposes SSL_CTX_sess_set_new_cb, so there is no way around doing it by hand.

This adds that: one SSLSessionCache per Cluster — a new cassandra.ssl_session_cache
module — offered to every connection before its handshake and refreshed after. On by default
whenever ssl_context is set and the reactor can restore a session before the handshake.

cluster = Cluster(ssl_context=ssl_context)                                  # resumption on
cluster = Cluster(ssl_context=ssl_context, ssl_session_cache=None)          # off
cluster = Cluster(ssl_context=ssl_context,
                  ssl_session_cache=SSLSessionCache(max_size=64))           # sized, or shared

The server has to issue tickets for any of this to happen. Scylla does so only when
enable_session_tickets is set in client_encryption_options, which defaults to true from
Scylla 2026.3 and to false in the releases before it. Without it nothing resumes and every
connection performs a full handshake, exactly as it does today.

Design notes

• A cached session is not consumed by being used. get() leaves the entry in place, and
  each successful handshake stores a fresh session over it. Measured: one session is accepted by
  four concurrent connections on TLS 1.2 and 1.3 against a loopback TLS server, and by every
  pool connection against real Scylla. Treating tickets as single-use (removing on get())
  would mean only the first connection of a per-shard burst resumes — precisely the case this
  ticket is about. RFC 8446's "SHOULD NOT reuse" concerns 0-RTT replay and tracking; the driver
  sends no early data.
• The session is stored from the ReadyMessage / AuthSuccessMessage handlers, not right after
  the handshake. A TLS 1.3 server sends its NewSessionTicket as a post-handshake message;
  confirmed against Scylla that has_ticket is False immediately after connect() and True
  after the first CQL exchange. Storing is idempotent, so nothing needs to track whether it
  already happened, and every failure in this path is logged and dropped — both call sites are
  wrapped in @defunct_on_error, where a raised exception would kill a healthy connection over
  an optimisation.
• An entry is never offered past the lifetime the peer announced. A ticket carries one, and
  what remains of it after the handshake and CQL startup is what the entry gets, measured from a
  monotonic mark rather than the wall-clock SSLSession.time. A zero lifetime means opposite
  things in the two RFCs, so the negotiated version decides: discard on TLS 1.3, "unspecified"
  on TLS 1.2. RFC 8446 caps a client at seven days regardless. Re-storing a session the peer
  handed back unchanged keeps the deadline it had, so one ticket cannot be kept alive by being
  reused.
• The SSLContext is part of the cache key, together with the endpoint and the name the
  peer certificate is verified against. A session cannot be replayed onto a different context —
  the stdlib rejects it with ValueError: Session refers to a different SSLContext — which is
  also why the deprecated ssl_options-only path does not participate: each of those
  connections builds its own context. The verified name is in the key because a resumed
  handshake sends no Certificate, so that name is never checked again. The shard-aware port is
  the exception: that endpoint carries the node's key, so the per-shard burst resumes the
  session the control connection established rather than handshaking in full.
• A session offered on a connection whose TLS handshake then failed is retracted, whether
  the failure surfaces at connect time or, where ssl_options defer the handshake, in the
  reactor. Only a TLS error counts, and only the session that connection offered — a sibling may
  have stored a newer one meanwhile, and that one failed nothing.
• A cache you supply is yours. shutdown() leaves its entries alone, so clusters can share
  sessions, at the same time or one after another. One the driver created for a cluster is
  reachable only through it and goes when it does.
• Policy is separated from accessors (_set_tls_session, _get_resumable_tls_session,
  _tls_negotiated_version) so a reactor not using the stdlib ssl module overrides only those
  three; nothing else in the policy touches a socket, and a test holds that by driving it with
  no socket at all.

Not covered

• asyncio — the handshake happens inside loop.create_connection(..., ssl=...), which offers
  no point at which a session could be restored. AsyncioConnection declares
  supports_tls_session_resumption = False and no cache is created for it. Worth knowing that
  this is the default reactor on Python 3.12 and newer when the libev extension is not
  installed, since asyncore left the standard library there.

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]

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.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds SSLSessionCache, a thread-safe bounded LRU cache for TLS sessions. Cluster creates, disables, or accepts a cache and passes it to connections. Connections derive endpoint-specific keys, restore sessions before handshakes, and store sessions after startup or authentication. Reactor implementations declare unsupported resumption. Tests cover cache behavior, TLS 1.2 and TLS 1.3, concurrency, cache isolation, and shard-aware connections.

Possibly related PRs

• scylladb/python-driver#936: Both changes modify shard-aware connection handling.
• scylladb/python-driver#938: Both changes modify TLS configuration and connection initialization.

Suggested reviewers: mykaul, dkropachev, lorak-mmk

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 19.83% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The description includes a valid Fixes annotation for DRIVER-165.
Out of Scope Changes check	✅ Passed	The changes support the stated TLS session resumption objective and add related implementation, reactor declarations, documentation, and tests. No unrelated changes are evident.
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding TLS session resumption through SSLSessionCache.
Description check	✅ Passed	The description explains the motivation, design, scope, configuration, limitations, tests, issue reference, and completed checklist items. It satisfies the repository template.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[dkropachev]

One inline correctness issue. Branch also needs a rebase onto current master; PR is currently conflicting.

[nikagra]

The design is right where it matters — one cache per Cluster, restore before the handshake, store from Ready/AuthSuccess, context and hostname in the key. None of that is what I want to revisit.

What I would like to settle before the next push is the shape of the bookkeeping around it, because each round so far has been answered with a parameter or a method rather than a change of mechanism:

round	what was added
ticket lifetime ignored	set(lifetime=)
deadline slides on reuse	set(extend=) + _tls_session_was_renewed()
context retention	weakref → discard_context() → acquire_context/release_context + _context_owners + two Cluster attributes + a shutdown hook
bad entry re-offered	discard(key, session) + _tls_session_offered cleared in three places
shard-aware keying	_tls_session_cache_key_override set from pool.py

Two changes would collapse most of that.

1. The cache has an owner, and the driver knows which it is. An auto-created cache is a Cluster attribute, so its lifetime is already the cluster's and it needs no refcount. A user-supplied one is the user's object, and the driver deleting rows in it is the part I would question. Recording which of the two it is at construction removes acquire_context, release_context, _context_owners, both Cluster attributes, the shutdown hook and the k[0] is ssl_context scan — along with the cases each of those had to handle: cluster that never connected, shutdown that raised, cache assigned after construction, keys that are not tuples.

2. The accessor boundary should hold. _tls_session_lifetime and _tls_session_was_renewed read self._socket directly, against the note at :1352. @dkropachev's open twisted and eventlet threads are the same boundary from the reactor side.

Order I would suggest: 1, then 2 (which also removes the version-guessing in _get_resumable_tls_session), then move the extend decision inside set(), where the lock is.

Separately: five threads are resolved while the code at each is unchanged — cluster.py, connection.py, pool.py, cluster.py, test_tls_resumption.py. If any of those was a decision rather than an oversight, say so and I will drop it.

Deliberately not raising this round, to keep it to the shape above: docs for an on-by-default change, SSLSessionCache.set/discard edge behaviour, the asyncio hostname duplication, the SniEndPoint key override, unit-suite cost.

[nikagra]

Detail under the comment above — the two changes there would remove most of what these three sit on.

[nikagra]

Both findings below are from the 2026-09-08 rework of the cache core, not the earlier rounds -- the rest of the backlog reads as closed to me. One follow-up on the TLS 1.3 discard thread separately.

[nikagra]

[Major] 🟠 The description still contradicts the code on the point @dkropachev asked to have updated in #789 (comment):

• "No TTL. OpenSSL enforces session lifetime itself" — it doesn't, and the driver now does. _tls_session_lifetime() takes the lifetime the server announced, capped at _MAX_TLS_SESSION_LIFETIME, and SSLSessionCache drops an entry past its deadline both on lookup and on eviction. That bullet needs to describe the rule that shipped, including the TLS 1.2 / 1.3 split on a zero lifetime.
• "Policy is separated from accessors (_get_resumable_tls_session / _set_tls_session)" — three now; _tls_negotiated_version is the one the retention rules read.
• "Measured: … stdlib and pyOpenSSL" — no pyOpenSSL reactor is left in the tree. Worth saying the measurement predates their removal, or dropping that half.
• The deferrals are agreed but unlinked: #984 (test capability detection), #985 (multi-ticket caching — #789 (comment) asked for this link explicitly), #986 (tickets after CQL startup). A "Deferred" section naming the three closes two bot threads with it.

The checklist's docstring and docs boxes are also unticked on a PR that adds docs/api/cassandra/ssl_session_cache.rst.

---

Notes on the process

Separately, and about process rather than code. I have closed six of my seven open threads with this pass; the one left is #789 (comment), which is now on its third restatement. Worth noting why that happens, because the code here is converging and the threads are not: git diff 637f384c 8c74beec -- cassandra/connection.py is five hunks — one import, one docstring cross-reference, the 190-line SSLSessionCache move into its own module, one docstring reword, and one line from the rebase. No functional change at all, yet 15 threads are open and only three of them anchor to current code.

Three things would end this:

• @coderabbitai pause. 33 of the 100 review threads on this PR are bot-opened (copilot 25, coderabbit 8), several were stale when posted, and they bury the human blockers.
• Settle the retention policy in DRIVER-165, not here. Lifetime source, cache ownership and failed-handshake behaviour have each been designed twice in review — two complete mechanisms were built and then deleted (SSLContext retention went strong key → weakref key → discard_context → none of it; _decide_tls_session_cache plus three bookkeeping flags → a property). Get an explicit ack from @dkropachev on the policy, then review conformance only.
• Cut the prose to contract level. cassandra/ssl_session_cache.py is 70 lines of code to 141 of docstring and comment; _is_same_session is 23 lines of docstring over 4 of code. Rationale that is not a caller's contract belongs in DRIVER-165 or a commit message. As it stands every behaviour change forces a paragraph rewrite, which manufactures new review surface — two of my findings this round, and a good share of every round before it, are prose contradicting code rather than defects.

If the next round is not green, the way out is three stacked PRs — (a) ssl_session_cache.py + EndPoint.tls_session_cache_key + tests, no behaviour change; (b) connection wiring; (c) the Cluster surface — one reviewer concern each.

[nikagra]

First pass over the head commits — the TLS mechanics hold up end to end (session restored pre-handshake, offered-identity retraction, monotonic lifetimes, the TLS 1.2/1.3 split). Nothing below blocks merge.

[nikagra]

Approving. My open thread on the TLS 1.3 discard path is closed -- option 1 landed as written. Two non-blocking notes inline.

[sylwiaszunejko]

CI failures due to flaky tests