You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by lh...@apache.org on 2026/08/27 17:57:50 UTC
(pulsar) branch master updated: [fix][proxy] PIP-478: resolve the proxy's broker-client credential off the event loop (#26328)
This is an automated email from the ASF dual-hosted git repository.
lhotari pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new 7e9edb8b043c [fix][proxy] PIP-478: resolve the proxy's broker-client credential off the event loop (#26328)
7e9edb8b043c is described below
commit 7e9edb8b043c1d43197c811e6c9cbfcde33aa86b
Author: Lari Hotari <lh...@users.noreply.github.com>
AuthorDate: Thu Aug 27 20:57:41 2026 +0300
[fix][proxy] PIP-478: resolve the proxy's broker-client credential off the event loop (#26328)
---
pip/pip-478.md | 2 +-
.../pulsar/proxy/server/DirectProxyHandler.java | 180 ++++++++++---
.../apache/pulsar/proxy/server/ProxyService.java | 40 +++
.../proxy/server/DirectProxyHandlerAuthTest.java | 300 +++++++++++++++++++++
4 files changed, 486 insertions(+), 36 deletions(-)
diff --git a/pip/pip-478.md b/pip/pip-478.md
index 113fb1682b75..57396d8d7277 100644
--- a/pip/pip-478.md
+++ b/pip/pip-478.md
@@ -142,7 +142,7 @@ This PIP introduces new API and implementation across the existing `pulsar-clien
- **Non-Java client SDKs.** Each non-Java SDK (Python, Go, C++, Node.js) follows its own auth model and will be addressed by per-SDK PIPs.
-- **Off-loading the proxy's own broker-client credential I/O (known gap).** Motivation #1's event-loop-safety guarantee is delivered for `PulsarClient` / `PulsarAdmin` (and the broker's outbound clients, which are genuine clients that bind the framework's `ClientAuthenticationServices`). The **proxy's** connection to the broker is not a `PulsarClientImpl`: its lookup path uses a bare `ConnectionPool` and its data path a hand-rolled Netty `DirectProxyHandler`, and neither binds the client [...]
+- **Binding the proxy's broker-client legs to client-owned services (known gap).** Motivation #1's event-loop-safety guarantee is delivered for `PulsarClient` / `PulsarAdmin` (and the broker's outbound clients, which are genuine clients that bind the framework's `ClientAuthenticationServices`). The **proxy's** connection to the broker is not a `PulsarClientImpl`: its lookup path uses a bare `ConnectionPool` and its data path a hand-rolled Netty `DirectProxyHandler`, and neither binds the [...]
- **The broader FIPS-compliance mode.** This PIP covers the **TLS-transport** requirements for FIPS: a configurable TLS engine (JDK, not native BoringSSL) wired through every component plus the two configurable provider axes (Motivation #4, Goal #5). It does **not** define a full FIPS-mode profile: FIPS-approved algorithms in message encryption (key-wrap) and authentication (password hashing, token signing), a FIPS distribution/packaging variant (shipping `bc-fips` and excluding non-vali [...]
diff --git a/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/DirectProxyHandler.java b/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/DirectProxyHandler.java
index 19e37cba3a74..ce5d50c7e1e9 100644
--- a/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/DirectProxyHandler.java
+++ b/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/DirectProxyHandler.java
@@ -42,14 +42,15 @@ import io.netty.handler.timeout.ReadTimeoutHandler;
import io.netty.util.CharsetUtil;
import java.net.InetSocketAddress;
import java.util.Arrays;
+import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;
+import java.util.function.Function;
import lombok.CustomLog;
import lombok.Getter;
import lombok.SneakyThrows;
import org.apache.pulsar.PulsarVersion;
import org.apache.pulsar.client.api.Authentication;
-import org.apache.pulsar.client.api.AuthenticationDataProvider;
-import org.apache.pulsar.client.api.PulsarClientException;
+import org.apache.pulsar.client.impl.auth.v5.BinaryAuthenticationDriver.AuthenticationExchange;
import org.apache.pulsar.common.allocator.PulsarByteBufAllocator;
import org.apache.pulsar.common.api.AuthData;
import org.apache.pulsar.common.api.proto.BaseCommand;
@@ -61,6 +62,7 @@ import org.apache.pulsar.common.protocol.FrameDecoderUtil;
import org.apache.pulsar.common.protocol.PulsarDecoder;
import org.apache.pulsar.common.stats.Rate;
import org.apache.pulsar.common.tls.impl.TlsContextAcquisition;
+import org.apache.pulsar.common.util.FutureUtil;
import org.apache.pulsar.common.util.netty.NettyChannelUtil;
@CustomLog
@@ -79,8 +81,13 @@ public class DirectProxyHandler {
private final String clientAuthMethod;
public static final String TLS_HANDLER = "tls";
+ // PIP-478: hard cap on broker challenge rounds within a single binary authentication exchange, mirroring
+ // ClientCnx.MAX_AUTH_CHALLENGE_ROUNDS (both in turn mirror HttpAuthenticationDriver.MAX_CHALLENGE_ROUNDS).
+ // A broker that answers every CommandAuthResponse with another challenge would otherwise loop against the
+ // proxy forever, and each round now also schedules credential work onto a blocking pool.
+ static final int MAX_AUTH_CHALLENGE_ROUNDS = 10;
+
private final Authentication authentication;
- private AuthenticationDataProvider authenticationDataProvider;
private final ProxyService service;
private final Runnable onHandshakeCompleteAction;
final boolean tlsEnabledWithBroker;
@@ -259,6 +266,18 @@ public class DirectProxyHandler {
private final ProxyConfiguration config;
private final int protocolVersion;
private final FeatureFlags featureFlags;
+ // PIP-478: the v5 exchange this backend connection authenticates through. Replaced on a broker-pushed
+ // REFRESH, which starts a fresh exchange. Only ever touched on this channel's event loop.
+ private AuthenticationExchange authExchange;
+ // PIP-478: round state. AuthenticationExchange is single-round and non-thread-safe, and serializing
+ // its rounds is the caller's obligation; this class is its second caller after ClientCnx. While the
+ // frame decoder is still running (state Init) two challenge frames arriving in one read reach
+ // handleAuthChallenge in the same event-loop turn, before either resolution has completed, and would
+ // otherwise drive the same exchange concurrently. Both fields are touched only on this channel's
+ // event loop (channelActive, handleAuthChallenge, and the continuations dispatched there), so they
+ // need no synchronization.
+ private boolean authRoundInProgress;
+ private int authChallengeRounds;
public ProxyBackendHandler(ProxyConfiguration config, int protocolVersion, String remoteHostName,
FeatureFlags featureFlags) {
@@ -275,16 +294,76 @@ public class DirectProxyHandler {
if (config.isHaProxyProtocolEnabled()) {
writeHAProxyMessage();
}
-
- // Send the Connect command to broker
- authenticationDataProvider = authentication.getAuthData(remoteHostName);
- AuthData authData = authenticationDataProvider.authenticate(AuthData.INIT_AUTH_DATA);
- ByteBuf command = Commands.newConnect(
- authentication.getAuthMethodName(), authData, protocolVersion,
- proxyConnection.clientVersion, null /* target broker */,
- originalPrincipal, clientAuthData, clientAuthMethod, PulsarVersion.getVersion(), featureFlags);
- writeAndFlush(command);
isTlsOutboundChannel = ProxyConnection.isTlsChannel(inboundChannel);
+
+ // Send the Connect command to broker. PIP-478: the credential is resolved through a v5 exchange
+ // rather than by calling the v4 plugin here. This method runs on the Netty event loop, and the v4
+ // call it used to make is arbitrary plugin code — an OAuth2 token endpoint round trip, an Athenz
+ // ZTS fetch, a GSSAPI exchange with the KDC — which stalled every connection multiplexed onto
+ // that loop for its duration. The exchange's calls always off-load.
+ //
+ // The auth method name is read from the v4 plugin here and in handleAuthChallenge below, where
+ // ClientCnx instead takes it from the exchange that produced the credential. Both are correct for
+ // the proxy — it owns one started plugin, and the bridge's authMethodName() delegates straight to
+ // it — and reading it from the plugin does not depend on a round having completed. Deliberate.
+ authExchange = service.getProxyClientAuthenticationDriver().newAuthenticationExchange(remoteHostName);
+ sendWhenResolved(authExchange.getAuthDataAsync(),
+ authData -> Commands.newConnect(
+ authentication.getAuthMethodName(), authData, protocolVersion,
+ proxyConnection.clientVersion, null /* target broker */,
+ originalPrincipal, clientAuthData, clientAuthMethod, PulsarVersion.getVersion(),
+ featureFlags),
+ "connect");
+ }
+
+ /**
+ * Send a command built from an asynchronously-resolved credential (PIP-478).
+ *
+ * <p>The continuation is dispatched onto this channel's event loop, so the command is built and
+ * written there whether the credential was already in memory or needed I/O — command ordering on the
+ * channel is therefore unchanged from the synchronous version. A failure closes the backend channel:
+ * the proxy has no credential to send, and leaving the connection open would wait out the broker's
+ * timeout instead of letting the client retry. That covers a failure to build the command too, not
+ * just a failure to resolve the credential.
+ *
+ * <p>This is where an authentication round begins: the round is marked in progress so that a
+ * challenge arriving before it completes is dropped rather than re-entering the exchange
+ * concurrently.
+ *
+ * @param resolution the credential being resolved
+ * @param commandBuilder builds the command to send from the resolved credential
+ * @param what what is being authenticated, for logging
+ */
+ private void sendWhenResolved(CompletableFuture<AuthData> resolution,
+ Function<AuthData, ByteBuf> commandBuilder, String what) {
+ authRoundInProgress = true;
+ // The future returned by whenCompleteAsync is intentionally discarded: the continuation handles
+ // every outcome itself, and the only way that future fails is ctx.executor() rejecting during
+ // event-loop shutdown — at which point the channel is already going away.
+ resolution.whenCompleteAsync((authData, throwable) -> {
+ authRoundInProgress = false;
+ if (throwable != null) {
+ Throwable cause = FutureUtil.unwrapCompletionException(throwable);
+ log.error().attr("channel", ctx.channel()).attr("stage", what).exception(cause)
+ .log("Failed to resolve the proxy's broker-client credential");
+ ctx.close();
+ return;
+ }
+ if (!ctx.channel().isActive()) {
+ // The backend connection went away while the credential was resolving. Logged so that
+ // "backend connected but never sent CommandConnect" is diagnosable rather than silent.
+ log.debug().attr("channel", ctx.channel()).attr("stage", what)
+ .log("Backend channel closed while the proxy's broker-client credential resolved");
+ return;
+ }
+ try {
+ writeAndFlush(commandBuilder.apply(authData));
+ } catch (Throwable t) {
+ log.error().attr("channel", ctx.channel()).attr("stage", what).exception(t)
+ .log("Failed to send the proxy's broker-client authentication command");
+ ctx.close();
+ }
+ }, ctx.executor());
}
@Override
@@ -345,37 +424,68 @@ public class DirectProxyHandler {
checkArgument(authChallenge.hasChallenge());
checkArgument(authChallenge.getChallenge().hasAuthData() && authChallenge.getChallenge().hasAuthData());
- if (Arrays.equals(AuthData.REFRESH_AUTH_DATA_BYTES, authChallenge.getChallenge().getAuthData())) {
- try {
- authenticationDataProvider = authentication.getAuthData(remoteHostName);
- } catch (PulsarClientException e) {
- log.error().attr("channel", ctx.channel())
- .exception(e)
- .log("Error refreshing authentication data provider");
- return;
+ // PIP-478 binary routing rule 2: the broker's REFRESH sentinel restarts authentication with a
+ // fresh exchange whose getAuthDataAsync() re-produces the current credential, rather than being
+ // routed into the conversation it just terminated. Any other challenge is a round of the current
+ // exchange, whose state slot carries conversation state across rounds. This mirrors ClientCnx.
+ // The REFRESH branch is conformance with that rule rather than a path the broker can reach here:
+ // this handler stops decoding once state == HandshakeCompleted, and the broker arms its refresh
+ // task with an initial delay of authenticationRefreshCheckSeconds after connect completes, so by
+ // the time a REFRESH is pushed it is proxied straight through to the client, which answers it.
+ // The proxy's own credential refresh lives in ProxyConnection, not here.
+ boolean refresh =
+ Arrays.equals(AuthData.REFRESH_AUTH_DATA_BYTES, authChallenge.getChallenge().getAuthData());
+ // PIP-478 (serialize-or-drop): a broker never pipelines challenges — it waits for each
+ // CommandAuthResponse — so a challenge arriving while a round is still in flight is anomalous,
+ // and servicing it would re-enter the same single-round, non-thread-safe exchange concurrently.
+ // Dropping it makes rounds strictly serialized, which is why this class needs none of the
+ // generation guarding ClientCnx carries: nothing here can supersede an in-flight round. ClientCnx
+ // does need it, because it lets a REFRESH supersede one; the proxy can drop a REFRESH instead,
+ // both because it cannot reach this handler and because the broker's refresh check is a
+ // scheduleAtFixedRate task that would re-send it on the next tick.
+ if (authRoundInProgress) {
+ log.debug().attr("channel", ctx.channel())
+ .log("Dropping a broker auth challenge received while an auth round is in progress");
+ return;
+ }
+ // Bound the exchange. A REFRESH opens a fresh exchange, so it resets the counter; any other
+ // challenge counts towards the cap.
+ if (refresh) {
+ authChallengeRounds = 0;
+ } else if (++authChallengeRounds > MAX_AUTH_CHALLENGE_ROUNDS) {
+ log.error().attr("channel", ctx.channel()).attr("maxChallengeRounds", MAX_AUTH_CHALLENGE_ROUNDS)
+ .log("Binary authentication exceeded the maximum challenge rounds; closing the "
+ + "broker connection");
+ ctx.close();
+ return;
+ }
+ CompletableFuture<AuthData> resolution;
+ try {
+ if (refresh) {
+ authExchange =
+ service.getProxyClientAuthenticationDriver().newAuthenticationExchange(remoteHostName);
+ resolution = authExchange.getAuthDataAsync();
+ } else {
+ resolution = authExchange
+ .authenticateAsync(AuthData.of(authChallenge.getChallenge().getAuthData()));
}
+ } catch (Throwable t) {
+ // One try/catch so a plugin that throws synchronously fails the connection rather than
+ // propagating up the event loop.
+ resolution = CompletableFuture.failedFuture(t);
}
// mutual authn. If auth not complete, continue auth; if auth complete, complete connectionFuture.
- try {
- AuthData authData = authenticationDataProvider
- .authenticate(AuthData.of(authChallenge.getChallenge().getAuthData()));
-
+ sendWhenResolved(resolution, authData -> {
checkState(!authData.isComplete());
-
- ByteBuf request = Commands.newAuthResponse(authentication.getAuthMethodName(),
- authData,
- this.protocolVersion,
- PulsarVersion.getVersion());
-
log.debug().attr("channel", ctx.channel())
.attr("authMethod", authentication.getAuthMethodName())
.log("Mutual auth");
-
- writeAndFlush(request);
- } catch (Exception e) {
- log.error().exception(e).log("Error mutual verify");
- }
+ return Commands.newAuthResponse(authentication.getAuthMethodName(),
+ authData,
+ this.protocolVersion,
+ PulsarVersion.getVersion());
+ }, "challenge");
}
@Override
diff --git a/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/ProxyService.java b/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/ProxyService.java
index 5662d59a303e..fb781c35df60 100644
--- a/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/ProxyService.java
+++ b/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/ProxyService.java
@@ -69,6 +69,9 @@ import org.apache.pulsar.broker.topiclistlimit.TopicListMemoryLimiter;
import org.apache.pulsar.broker.topiclistlimit.TopicListSizeResultCache;
import org.apache.pulsar.broker.web.plugin.servlet.AdditionalServlets;
import org.apache.pulsar.client.api.Authentication;
+import org.apache.pulsar.client.impl.auth.v5.BinaryAuthenticationDriver;
+import org.apache.pulsar.client.impl.auth.v5.V5AuthenticationLoader;
+import org.apache.pulsar.client.impl.auth.v5.V5BinaryAuthenticationDriver;
import org.apache.pulsar.client.impl.conf.ClientConfigurationData;
import org.apache.pulsar.client.impl.tls.ClientTlsFactorySupport;
import org.apache.pulsar.common.allocator.PulsarByteBufAllocator;
@@ -96,6 +99,9 @@ public class ProxyService implements Closeable {
private final ProxyConfiguration proxyConfig;
private final Authentication proxyClientAuthentication;
+ // PIP-478: lazily built from proxyClientAuthentication; see getProxyClientAuthenticationDriver().
+ // Volatile because that getter reads it without holding the monitor.
+ private volatile BinaryAuthenticationDriver proxyClientAuthenticationDriver;
@Getter
private final DnsAddressResolverGroup dnsAddressResolverGroup;
@Getter
@@ -679,6 +685,40 @@ public class ProxyService implements Closeable {
return this.proxyClientAuthentication;
}
+ /**
+ * The v5 driver the proxy's broker connections authenticate through (PIP-478).
+ *
+ * <p>The proxy owns one started v4 plugin for all of its broker connections, so it owns one driver:
+ * every {@code DirectProxyHandler} opens its own exchange against it, and the exchange is what carries
+ * per-connection conversation state. Built from the <em>started</em> plugin, because {@link ProxyService}
+ * starts and closes that instance itself — the bridge must not run that lifecycle a second time.
+ *
+ * <p>No {@code ClientAuthenticationServices} are bound: the proxy is not a {@code PulsarClient} and has
+ * no client-owned executor to lend. Credential work therefore lands on the framework's shared blocking
+ * pool, which is the case {@code V5AuthContexts} documents for exactly this caller — the alternative,
+ * running it inline, is the Netty event loop.
+ *
+ * <p>Read on every backend connection's {@code channelActive}, so the hit path is lock-free and only a
+ * miss takes the monitor — as {@code ClientCnx.resolveAuthDriver} does, and for the same reason: this
+ * monitor is the {@link ProxyService} one, shared with the metrics-servlet accessors, and a connection
+ * being set up should not have to queue behind unrelated machinery.
+ *
+ * @return the shared binary authentication driver
+ */
+ public BinaryAuthenticationDriver getProxyClientAuthenticationDriver() {
+ BinaryAuthenticationDriver resolved = proxyClientAuthenticationDriver;
+ if (resolved != null) {
+ return resolved;
+ }
+ synchronized (this) {
+ if (proxyClientAuthenticationDriver == null) {
+ proxyClientAuthenticationDriver = new V5BinaryAuthenticationDriver(
+ V5AuthenticationLoader.forStartedV4Plugin(proxyClientAuthentication));
+ }
+ return proxyClientAuthenticationDriver;
+ }
+ }
+
public synchronized PrometheusMetricsServlet getMetricsServlet() {
return metricsServlet;
}
diff --git a/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/DirectProxyHandlerAuthTest.java b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/DirectProxyHandlerAuthTest.java
new file mode 100644
index 000000000000..e1d9b9f39fb3
--- /dev/null
+++ b/pulsar-proxy/src/test/java/org/apache/pulsar/proxy/server/DirectProxyHandlerAuthTest.java
@@ -0,0 +1,300 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.pulsar.proxy.server;
+
+import static java.nio.charset.StandardCharsets.UTF_8;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+import io.netty.channel.ChannelHandlerContext;
+import io.netty.channel.embedded.EmbeddedChannel;
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.function.Supplier;
+import org.apache.pulsar.client.api.Authentication;
+import org.apache.pulsar.client.api.AuthenticationDataProvider;
+import org.apache.pulsar.client.impl.auth.v5.BinaryAuthenticationDriver;
+import org.apache.pulsar.client.impl.auth.v5.V5AuthenticationLoader;
+import org.apache.pulsar.client.impl.auth.v5.V5BinaryAuthenticationDriver;
+import org.apache.pulsar.common.api.AuthData;
+import org.apache.pulsar.common.api.proto.CommandAuthChallenge;
+import org.apache.pulsar.common.api.proto.FeatureFlags;
+import org.apache.pulsar.common.protocol.Commands;
+import org.awaitility.Awaitility;
+import org.testng.annotations.AfterMethod;
+import org.testng.annotations.BeforeMethod;
+import org.testng.annotations.Test;
+
+/**
+ * PIP-478: the proxy's broker-client credential must not be resolved on the Netty event loop, and the
+ * exchange it is resolved through must have its rounds serialized and bounded.
+ *
+ * <p>Both properties live entirely inside {@code DirectProxyHandler.ProxyBackendHandler}, so they are pinned
+ * here against an {@link EmbeddedChannel} rather than through a running proxy: an embedded event loop only
+ * runs the tasks submitted to it when {@code runPendingTasks()} is called, which makes "did this run on the
+ * event loop or off it" an assertion rather than a race. An end-to-end proxy fixture can observe neither —
+ * the handshake completes the same way whichever thread the plugin was called on.
+ */
+public class DirectProxyHandlerAuthTest {
+
+ private static final String AUTH_METHOD = "thread-recording";
+ private static final String BROKER_HOST = "broker.example:6650";
+
+ private ProxyConfiguration proxyConfig;
+ private ProxyService service;
+ private ProxyConnection proxyConnection;
+ private EmbeddedChannel inboundChannel;
+ private EmbeddedChannel backendChannel;
+ private ThreadRecordingAuthentication plugin;
+
+ /**
+ * A v4 plugin that records the thread each of its credential calls runs on, standing in for one that
+ * blocks there — an OAuth2 token endpoint round trip, an Athenz ZTS fetch, a GSSAPI exchange with the KDC.
+ * It answers challenges too, so a challenge round reaches {@code authenticate} a second time.
+ */
+ private static final class ThreadRecordingAuthentication implements Authentication {
+
+ private final List<String> credentialThreads = new CopyOnWriteArrayList<>();
+
+ @Override
+ public String getAuthMethodName() {
+ return AUTH_METHOD;
+ }
+
+ @Override
+ public AuthenticationDataProvider getAuthData(String brokerHostName) {
+ return new AuthenticationDataProvider() {
+ @Override
+ public boolean hasDataFromCommand() {
+ return true;
+ }
+
+ @Override
+ public AuthData authenticate(AuthData data) {
+ credentialThreads.add(Thread.currentThread().getName());
+ return AuthData.of("credential".getBytes(UTF_8));
+ }
+ };
+ }
+
+ @SuppressWarnings("deprecation")
+ @Override
+ public void configure(Map<String, String> authParams) {
+ }
+
+ @Override
+ public void start() {
+ }
+
+ @Override
+ public void close() {
+ }
+ }
+
+ /**
+ * A driver whose rounds the test completes by hand, for the guards that are about <em>when</em> a round is
+ * serviced rather than about which thread services it.
+ */
+ private static final class ScriptedDriver implements BinaryAuthenticationDriver {
+
+ private final Supplier<CompletableFuture<AuthData>> connectCredential;
+ private final Supplier<CompletableFuture<AuthData>> challengeResponse;
+ private final AtomicInteger challengeRounds = new AtomicInteger();
+
+ private ScriptedDriver(Supplier<CompletableFuture<AuthData>> connectCredential,
+ Supplier<CompletableFuture<AuthData>> challengeResponse) {
+ this.connectCredential = connectCredential;
+ this.challengeResponse = challengeResponse;
+ }
+
+ @Override
+ public AuthenticationExchange newAuthenticationExchange(String brokerHostName) {
+ return new AuthenticationExchange() {
+ @Override
+ public CompletableFuture<AuthData> getAuthDataAsync() {
+ return connectCredential.get();
+ }
+
+ @Override
+ public String authMethodName() {
+ return AUTH_METHOD;
+ }
+
+ @Override
+ public CompletableFuture<AuthData> authenticateAsync(AuthData challenge) {
+ challengeRounds.incrementAndGet();
+ return challengeResponse.get();
+ }
+ };
+ }
+ }
+
+ @BeforeMethod
+ public void setUp() {
+ proxyConfig = new ProxyConfiguration();
+ plugin = new ThreadRecordingAuthentication();
+ inboundChannel = new EmbeddedChannel();
+
+ ChannelHandlerContext inboundCtx = mock(ChannelHandlerContext.class);
+ when(inboundCtx.channel()).thenReturn(inboundChannel);
+
+ service = mock(ProxyService.class);
+ when(service.getConfiguration()).thenReturn(proxyConfig);
+
+ proxyConnection = mock(ProxyConnection.class);
+ when(proxyConnection.ctx()).thenReturn(inboundCtx);
+ when(proxyConnection.getClientAuthentication()).thenReturn(plugin);
+ proxyConnection.clientVersion = "test-client";
+ }
+
+ @AfterMethod(alwaysRun = true)
+ public void tearDown() {
+ if (backendChannel != null) {
+ backendChannel.finishAndReleaseAll();
+ }
+ inboundChannel.finishAndReleaseAll();
+ }
+
+ /**
+ * Build the backend handler on an embedded channel and activate it, which is what starts the connect
+ * round. The outbound channel is published before registration so the handler has somewhere to write.
+ *
+ * @param driver the authentication driver the handler resolves its credential through
+ * @return the backend handler under test
+ * @throws Exception if activating the channel fails
+ */
+ private DirectProxyHandler.ProxyBackendHandler activateBackend(BinaryAuthenticationDriver driver)
+ throws Exception {
+ when(service.getProxyClientAuthenticationDriver()).thenReturn(driver);
+ DirectProxyHandler directProxyHandler = new DirectProxyHandler(service, proxyConnection);
+ DirectProxyHandler.ProxyBackendHandler backend = directProxyHandler.new ProxyBackendHandler(
+ proxyConfig, Commands.getCurrentProtocolVersion(), BROKER_HOST, new FeatureFlags());
+ backendChannel = new EmbeddedChannel(false, false, backend);
+ directProxyHandler.outboundChannel = backendChannel;
+ backendChannel.register();
+ return backend;
+ }
+
+ private BinaryAuthenticationDriver realDriver() {
+ return new V5BinaryAuthenticationDriver(V5AuthenticationLoader.forStartedV4Plugin(plugin));
+ }
+
+ private static CommandAuthChallenge challenge(String payload) {
+ CommandAuthChallenge command = new CommandAuthChallenge();
+ command.setProtocolVersion(Commands.getCurrentProtocolVersion())
+ .setChallenge()
+ .setAuthData(payload.getBytes(UTF_8))
+ .setAuthMethodName(AUTH_METHOD);
+ return command;
+ }
+
+ /** Drain the embedded loop until the handler has written the command it owes, or fail. */
+ private void awaitCommandWritten(int expectedCommands) {
+ Awaitility.await().atMost(Duration.ofSeconds(30)).untilAsserted(() -> {
+ backendChannel.runPendingTasks();
+ assertThat(backendChannel.outboundMessages()).hasSize(expectedCommands);
+ });
+ }
+
+ @Test
+ public void theConnectCredentialIsResolvedOffTheEventLoop() throws Exception {
+ activateBackend(realDriver());
+ awaitCommandWritten(1);
+
+ assertThat(plugin.credentialThreads)
+ .as("the v4 credential for CommandConnect must not be resolved on the channel's event loop")
+ .singleElement().asString().startsWith("pulsar-auth-blocking-shared");
+ }
+
+ /**
+ * The second half of the composition. Off-loading only the connect credential would leave every challenge
+ * round — a SASL exchange with the KDC, say — running on the loop that carries all of this proxy's
+ * multiplexed connections.
+ */
+ @Test
+ public void theChallengeRoundIsResolvedOffTheEventLoop() throws Exception {
+ DirectProxyHandler.ProxyBackendHandler backend = activateBackend(realDriver());
+ awaitCommandWritten(1);
+
+ backend.handleAuthChallenge(challenge("server-round-1"));
+ awaitCommandWritten(2);
+
+ assertThat(plugin.credentialThreads)
+ .as("both v4 credential calls must be resolved off the channel's event loop")
+ .hasSize(2)
+ .allSatisfy(thread -> assertThat(thread).startsWith("pulsar-auth-blocking-shared"));
+ }
+
+ /**
+ * {@code AuthenticationExchange} is single-round and non-thread-safe, and serializing its rounds is the
+ * caller's obligation. While the frame decoder is still running, two challenge frames arriving in one read
+ * reach {@code handleAuthChallenge} in the same event-loop turn — the sequence reproduced here — and
+ * without the guard both would drive the same exchange before either resolution completed.
+ */
+ @Test
+ public void aChallengeArrivingWhileARoundIsInFlightIsDropped() throws Exception {
+ CompletableFuture<AuthData> connectCredential = new CompletableFuture<>();
+ ScriptedDriver driver = new ScriptedDriver(() -> connectCredential,
+ () -> CompletableFuture.completedFuture(AuthData.of("response".getBytes(UTF_8))));
+ DirectProxyHandler.ProxyBackendHandler backend = activateBackend(driver);
+
+ // The connect round is still resolving: nothing has completed it yet.
+ backend.handleAuthChallenge(challenge("early-challenge"));
+ backendChannel.runPendingTasks();
+ assertThat(driver.challengeRounds).as("a challenge received mid-round must not re-enter the exchange")
+ .hasValue(0);
+
+ // Once the round in flight lands, the next challenge is serviced normally.
+ connectCredential.complete(AuthData.of("credential".getBytes(UTF_8)));
+ awaitCommandWritten(1);
+ backend.handleAuthChallenge(challenge("later-challenge"));
+ awaitCommandWritten(2);
+ assertThat(driver.challengeRounds).as("a challenge received between rounds must be serviced")
+ .hasValue(1);
+ }
+
+ /**
+ * A broker that answers every {@code CommandAuthResponse} with another challenge would otherwise loop
+ * against the proxy forever, and each round now also schedules credential work onto a blocking pool.
+ */
+ @Test
+ public void anEndlesslyChallengingBrokerIsCutOffAtTheRoundCap() throws Exception {
+ ScriptedDriver driver = new ScriptedDriver(
+ () -> CompletableFuture.completedFuture(AuthData.of("credential".getBytes(UTF_8))),
+ () -> CompletableFuture.completedFuture(AuthData.of("response".getBytes(UTF_8))));
+ DirectProxyHandler.ProxyBackendHandler backend = activateBackend(driver);
+ awaitCommandWritten(1);
+
+ for (int round = 1; round <= DirectProxyHandler.MAX_AUTH_CHALLENGE_ROUNDS + 1; round++) {
+ backend.handleAuthChallenge(challenge("server-round-" + round));
+ backendChannel.runPendingTasks();
+ }
+
+ assertThat(driver.challengeRounds)
+ .as("the exchange must stop at the round cap rather than answering challenges forever")
+ .hasValue(DirectProxyHandler.MAX_AUTH_CHALLENGE_ROUNDS);
+ assertThat(backendChannel.isOpen())
+ .as("exceeding the round cap must close the backend connection")
+ .isFalse();
+ }
+}