Cache the pool key identity digest per realm - #2389

Motivation

PrincipalScopedPartitionKey.scope(...) runs on every pool poll and offer of a connection-authenticated exchange: an NTLM, Kerberos or SPNEGO origin, or a proxy login on a per-connection proxy hop (HTTPS or WebSocket through an HTTP proxy, or SOCKS). Each call ran SHA-256 over all identity fields of the realm, hex-encoded the result, joined the origin and proxy digests into a new string, and the pool then hashed that string again. That is about 0.4 us and 560 bytes per call for one realm, twice per exchange.

The key was introduced for GHSA-v2j5-22fr-j62r (83e552e, d3bb4d6) so that two identities never share an authenticated socket, and it holds a digest so that it never holds the password. Both stay true.

Modification

• identityOf(realm) caches the digest per thread in a small table (8 sets of 2 ways), keyed by the realm instance: a hit needs WeakReference.get() == realm. Every digest input except the custom login config is a final field of Realm. The login config is the caller's own map, which they can still change after build() and which SpnegoEngine reads when it logs in, so a realm that has one is digested on every call, as before.
• The cache holds both the realm and its digest through weak references. It keeps neither the realm (and with it the password) nor the digest alive. A digest that no pool key holds is computed again after the next collection.
• The thread-local values are JDK types only (MessageDigest, Object[] of WeakReference), so the cache does not pin this library's class loader on container threads.
• The key stores the origin and proxy digests as two fields instead of joining them as origin + '/' + proxy. Equality is unchanged, because a hex digest never contains /. A cache hit reuses the same String, so its hash code is computed once.
• The digest inputs and their encoding are unchanged, including the Digest scheme not keying on the challenge realm name. No public API change: identityOf, digest and CACHED_IDENTITIES are package-private, for the test.

Only PrincipalScopedPartitionKey, its test and a new benchmark change.

Tests

New in PrincipalScopedPartitionKeyTest:

• aCachedIdentityIsTheDigestItself: identityOf equals digest, a second call returns the same instance, and a realm with a login config is digested on every call.
• aCachedIdentityMatchesAnUncachedOne: same key from the cached path, the uncached path and another thread, for NTLM, Kerberos and SPNEGO on both hops.
• aWarmCacheStillSeparatesEveryKeyedField: with the base realm cached, a change to any one keyed field still changes the key, on both hops: scheme, principal, password, realm name, NTLM domain and host, login context, SPN, useCanonicalHostname, login config.
• equalRealmsBuiltSeparatelyShareAKey, also across threads.
• aLoginConfigChangedAfterBuildMovesTheKey.
• manyRealmsKeepTheirOwnKeys: 200 realms over 16 slots, with rebuilt equal instances.
• twoRealmsInOneSetBothStayCached: two realms in the same slot, called alternately. Checked by mutation: a one-way cache fails it.
• theCacheKeepsNeitherTheRealmNorItsIdentityAlive. Checked by mutation: holding the identity strongly fails it.
• anOriginLoginAndTheSameProxyLoginDoNotShareAKey.

./mvnw clean verify on JDK 17.0.2 (Windows) passed on ba8a92112: 2043 tests, 0 failures, 35 skipped, Revapi clean. JDK 11 is not installed on this machine, so CI covers it.

Benchmark

PrincipalScopedPartitionKeyBenchmark, JMH 1.37, JDK 17.0.2, Windows, 1 fork, 5 x 1 s warmup, 5 x 1 s measurement, -prof gc. main and this branch run the same benchmark class: for main, its PrincipalScopedPartitionKey.class comes first on the classpath. scopeOnly calls scope(...). lookup also does a HashMap.get with the key, as the pool does. realms = 1 reuses one realm per hop. realms = 1024 cycles through equal, separately built instances, so every call misses the cache. The host runs other builds, so the times are noisy. B/op is exact.

On a miss the times overlap with main within the error, and allocation is 40 bytes lower: no join, but two weak references. An earlier, quieter run of the same miss path gave scopeOnly ntlm 434 ns on main against 449 ns on the branch, and proxyTunnel 450 ns against 411 ns.

Notes

• A realm rebuilt for every request (for example through RequestBuilder.setRealm(Realm.Builder)), the realm the NTLM 401 handshake rebuilds, and the first poll after each collection on a caller thread all take the miss path, which costs what main costs today.
• Pool polls from virtual threads (one per request) never hit the cache, and each such thread allocates one 32-element array. The cost is bounded and the thread-local MessageDigest was already there.

Second-agent review

Both reviewers ran read-only in fresh CLI sessions, with the intent and the security constraints (identity mixing, password exposure) in the prompt.

Findings and what was done:

• Thread-local value of a library class pins the class loader (round 1, guided, bug). Fixed: the thread-locals hold JDK types only.
• both benchmark measures permanent misses when the two realms share a slot (round 1, guided, risk). Fixed with two ways per set. twoRealmsInOneSetBothStayCached covers it.
• The cached digest, an unsalted function of the password, outlived the realm and the client on caller threads (round 1, independent, low risk). Fixed: the digest is also held through a weak reference. theCacheKeepsNeitherTheRealmNorItsIdentityAlive covers it.
• Class loader pinning (round 1, independent, nit). Same fix as above.
• The benchmark measured hits only (round 1, independent, nit). Added realms = 1024.
• The test reference for "uncached" relied on the login-config bypass, and nothing checked retention (round 1, independent, nit). Added a direct comparison with digest, an assertion that the bypass digests every call, and the retention test.
• A hit in the second way did not become most recent, and a realm whose digest was collected could take both ways (round 2, independent, nit). Fixed: a hit there swaps the ways without allocating, and the realm's own stale entry is replaced in place.
• The retention test relied on System.gc() alone (round 2, independent, nit). It now also allocates while it waits.
• Virtual threads never hit the cache (round 2, independent, nit). Not changed: the cost is bounded and there is no regression. See Notes.

Claude Code on behalf of Pavel Ptashyts

🤖 Generated with Claude Code