JVMCBC-1679 Support short lived mTLS certs refresh without application restart

Motivation
----------
Support credential rotation.

Keep the code that load new credentials
off the hot path; discourage blocking
low-level async I/O threads.

Modifications
-------------
Add DelegatingAuthenticator which delegates
to another authenticator the user can swap
at runtime.

Change-Id: I53bbcfde090b8d50cf2e57e76601fc1b39459c6d
Reviewed-on: https://review.couchbase.org/c/couchbase-jvm-clients/+/233162
Tested-by: Build Bot <[email protected]>
Reviewed-by: Michael Reiche <[email protected]>

Author: dnault

core-io/src/main/java/com/couchbase/client/core/env/Authenticator.java

@@ -26,10 +26,14 @@
 import reactor.util.annotation.Nullable;
 
 /**
- * The {@link Authenticator} encapsulates authentication strategies.
+ * An authentication strategy.
+ * <p>
+ * <b>Note:</b> The methods of this interface are part of the SDK's internal API, and may change at any time.
+ * Implementing this interface yourself is not recommended. Please use one of the provided implementations.
  *
- * <p>Please only use the implementations of this class, since the actual interfaces are unstable, internal
- * and may change at any time!</p>
+ * @see PasswordAuthenticator
+ * @see CertificateAuthenticator
+ * @see DelegatingAuthenticator
  *
  * @since 2.0.0
  */

core-io/src/main/java/com/couchbase/client/core/env/AuthenticatorWrapper.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2025 Couchbase, Inc.
+ *
+ * Licensed 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
+ *
+ * https://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 com.couchbase.client.core.env;
+
+import com.couchbase.client.core.annotation.Stability;
+import com.couchbase.client.core.deps.io.grpc.CallCredentials;
+import com.couchbase.client.core.deps.io.netty.channel.ChannelPipeline;
+import com.couchbase.client.core.deps.io.netty.handler.codec.http.HttpRequest;
+import com.couchbase.client.core.deps.io.netty.handler.ssl.SslContextBuilder;
+import com.couchbase.client.core.endpoint.EndpointContext;
+import com.couchbase.client.core.service.ServiceType;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+@NullMarked
+@Stability.Internal
+abstract class AuthenticatorWrapper implements Authenticator {
+
+  abstract Authenticator wrapped();
+
+  @Override
+  public void authKeyValueConnection(final EndpointContext endpointContext, final ChannelPipeline pipeline) {
+    wrapped().authKeyValueConnection(endpointContext, pipeline);
+  }
+
+  @Override
+  public void authHttpRequest(final ServiceType serviceType, final HttpRequest request) {
+    wrapped().authHttpRequest(serviceType, request);
+  }
+
+  @Override
+  public @Nullable CallCredentials protostellarCallCredentials() {
+    return wrapped().protostellarCallCredentials();
+  }
+
+  @Override
+  public void applyTlsProperties(final SslContextBuilder sslContextBuilder) {
+    wrapped().applyTlsProperties(sslContextBuilder);
+  }
+
+  @Override
+  public boolean supportsTls() {
+    return wrapped().supportsTls();
+  }
+
+  @Override
+  public boolean supportsNonTls() {
+    return wrapped().supportsNonTls();
+  }
+}

core-io/src/main/java/com/couchbase/client/core/env/DelegatingAuthenticator.java

@@ -0,0 +1,62 @@
+/*
+ * Copyright 2025 Couchbase, Inc.
+ *
+ * Licensed 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
+ *
+ * https://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 com.couchbase.client.core.env;
+
+import org.jspecify.annotations.NullMarked;
+
+import static java.util.Objects.requireNonNull;
+
+/**
+ * Delegates authentication to another authenticator.
+ * <p>
+ * The other authenticator can be swapped at runtime
+ * to support credential rotation.
+ *
+ * @see #create(Authenticator)
+ */
+@NullMarked
+public class DelegatingAuthenticator extends AuthenticatorWrapper {
+  private volatile Authenticator delegate;
+
+  /**
+   * Returns a new authenticator that delegates to the given authenticator.
+   * <p>
+   * The delegate may be updated later by calling {@link #setDelegate(Authenticator)}.
+   */
+  public static DelegatingAuthenticator create(Authenticator delegate) {
+    return new DelegatingAuthenticator(delegate);
+  }
+
+  public void setDelegate(Authenticator delegate) {
+    this.delegate = requireNonNull(delegate);
+  }
+
+  DelegatingAuthenticator(Authenticator delegate) {
+    setDelegate(delegate);
+  }
+
+  Authenticator wrapped() {
+    return delegate;
+  }
+
+  @Override
+  public String toString() {
+    return "DelegatingAuthenticator{" +
+      "delegate=" + delegate +
+      '}';
+  }
+}

core-io/src/main/java/com/couchbase/client/core/env/PasswordAuthenticator.java

@@ -92,7 +92,11 @@ public static PasswordAuthenticator.Builder builder(String username, String pass
    * One way to keep the supplier's value up to date is to schedule a recurring task
    * that reads new credentials from an external source and stores them
    * in the volatile field.
+   *
+   * @deprecated This method is difficult to use safely, because it's easy to accidentally
+   * do blocking IO inside the supplier. Please use {@link DelegatingAuthenticator} instead.
    */
+  @Deprecated
   public static PasswordAuthenticator.Builder builder(Supplier<UsernameAndPassword> supplier) {
     return new Builder(supplier);
   }
@@ -262,7 +266,7 @@ public Builder username(final String username) {
      * @param username A supplier that returns the username to use.
      * @return this builder for chaining purposes.
      * @deprecated This method does not support returning username and password as an atomic unit.
-     * Please use {@link PasswordAuthenticator#builder(Supplier)} instead.
+     * Please use {@link DelegatingAuthenticator} instead.
      */
     @Deprecated
     public Builder username(final Supplier<String> username) {
@@ -304,7 +308,7 @@ public Builder password(final String password) {
      * @param password the password to alongside for the username provided.
      * @return this builder for chaining purposes.
      * @deprecated This method does not support returning username and password as an atomic unit.
-     * Please use {@link PasswordAuthenticator#builder(Supplier)} instead.
+     * Please use {@link DelegatingAuthenticator} instead.
      */
     @Deprecated
     public Builder password(final Supplier<String> password) {