Feat: support authentication

Signed-off-by: Evgeny Malygin <emalygin@bloomberg.net>

Author: 678098

bmq-sdk/src/main/java/com/bloomberg/bmq/AuthnCredential.java

@@ -0,0 +1,185 @@
+/*
+ * Copyright 2026 Bloomberg Finance L.P.
+ *
+ * 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
+ *
+ * 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 com.bloomberg.bmq;
+
+import com.bloomberg.bmq.impl.infr.util.Argument;
+import java.util.Arrays;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * A value-semantic type representing authentication credentials for a broker session.
+ *
+ * <p>An {@code AuthnCredential} consists of an authentication mechanism name and optional
+ * authentication data. It is used to configure credentials on a {@link SessionOptions} for
+ * authenticating with the broker during session initiation.
+ *
+ * <H2>Thread Safety</H2>
+ *
+ * Once created, an {@code AuthnCredential} object is immutable and thread safe. A {@code Builder}
+ * is provided for construction.
+ *
+ * <H2>Usage Example</H2>
+ *
+ * <pre>
+ *
+ * AuthnCredential credential = AuthnCredential.builder()
+ *                                             .setMechanism("OAUTH2")
+ *                                             .setData(tokenBytes)
+ *                                             .build();
+ * </pre>
+ */
+@Immutable
+public final class AuthnCredential {
+
+    private final String mechanism;
+    private final byte[] data;
+
+    private AuthnCredential() {
+        mechanism = "";
+        data = null;
+    }
+
+    private AuthnCredential(Builder builder) {
+        mechanism = builder.mechanism;
+        data = builder.data != null ? Arrays.copyOf(builder.data, builder.data.length) : null;
+    }
+
+    /**
+     * Creates an {@code AuthnCredential} with default values (empty mechanism, no data).
+     *
+     * @return AuthnCredential credential with default values
+     */
+    public static AuthnCredential createDefault() {
+        return new AuthnCredential();
+    }
+
+    /**
+     * Returns a helper class object to create an immutable {@code AuthnCredential} with custom
+     * settings.
+     *
+     * @return Builder a helper class object to create an immutable {@code AuthnCredential}
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    /**
+     * Returns a helper class object initialized with values from the specified {@code credential}.
+     *
+     * @param credential specifies credential which initializes the builder
+     * @return Builder a helper class object to create an immutable {@code AuthnCredential}
+     */
+    public static Builder builder(AuthnCredential credential) {
+        Argument.expectNonNull(credential, "credential");
+        return new Builder(credential);
+    }
+
+    /**
+     * Returns the authentication mechanism.
+     *
+     * @return String authentication mechanism
+     */
+    public String mechanism() {
+        return mechanism;
+    }
+
+    /**
+     * Returns the authentication data, or null if not set.
+     *
+     * @return byte array of authentication data, or null
+     */
+    public byte[] data() {
+        return data != null ? Arrays.copyOf(data, data.length) : null;
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (obj == this) return true;
+        if (!(obj instanceof AuthnCredential)) return false;
+        AuthnCredential other = (AuthnCredential) obj;
+        return mechanism.equals(other.mechanism) && Arrays.equals(data, other.data);
+    }
+
+    @Override
+    public int hashCode() {
+        int result = mechanism.hashCode();
+        result = 31 * result + Arrays.hashCode(data);
+        return result;
+    }
+
+    @Override
+    public String toString() {
+        StringBuilder sb = new StringBuilder();
+        sb.append("[ mechanism: ")
+                .append(mechanism)
+                .append(", data: ")
+                .append(data != null ? "<" + data.length + " bytes>" : "null")
+                .append(" ]");
+        return sb.toString();
+    }
+
+    /** A helper class to create an immutable {@code AuthnCredential} with custom settings. */
+    public static class Builder {
+
+        private String mechanism;
+        private byte[] data;
+
+        private Builder() {
+            mechanism = "";
+            data = null;
+        }
+
+        private Builder(AuthnCredential credential) {
+            mechanism = credential.mechanism;
+            data =
+                    credential.data != null
+                            ? Arrays.copyOf(credential.data, credential.data.length)
+                            : null;
+        }
+
+        /**
+         * Creates an {@code AuthnCredential} object based on this builder's properties.
+         *
+         * @return AuthnCredential immutable credential object
+         */
+        public AuthnCredential build() {
+            return new AuthnCredential(this);
+        }
+
+        /**
+         * Sets the authentication mechanism.
+         *
+         * @param value authentication mechanism
+         * @return Builder this object
+         * @throws NullPointerException if the specified value is null
+         */
+        public Builder setMechanism(String value) {
+            mechanism = Argument.expectNonNull(value, "mechanism");
+            return this;
+        }
+
+        /**
+         * Sets the authentication data.
+         *
+         * @param value authentication data, may be null
+         * @return Builder this object
+         */
+        public Builder setData(byte[] value) {
+            data = value != null ? Arrays.copyOf(value, value.length) : null;
+            return this;
+        }
+    }
+}

bmq-sdk/src/main/java/com/bloomberg/bmq/AuthnCredentialResult.java

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2026 Bloomberg Finance L.P.
+ *
+ * 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
+ *
+ * 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 com.bloomberg.bmq;
+
+import com.bloomberg.bmq.impl.infr.util.Argument;
+
+/**
+ * Represents the result of an authentication credential callback, containing either a credential on
+ * success or an error message on failure.
+ */
+public final class AuthnCredentialResult {
+
+    private final AuthnCredential credential;
+    private final String error;
+
+    private AuthnCredentialResult(AuthnCredential credential, String error) {
+        this.credential = credential;
+        this.error = error;
+    }
+
+    /**
+     * Creates a successful result with the specified mechanism and data.
+     *
+     * @param mechanism the authentication mechanism
+     * @param data the authentication data
+     * @return a successful result
+     * @throws NullPointerException if mechanism is null
+     */
+    public static AuthnCredentialResult success(String mechanism, byte[] data) {
+        return new AuthnCredentialResult(
+                AuthnCredential.builder().setMechanism(mechanism).setData(data).build(), null);
+    }
+
+    /**
+     * Creates a failed result containing the specified error message.
+     *
+     * @param message the error message describing why credentials could not be obtained
+     * @return a failed result
+     * @throws NullPointerException if message is null
+     */
+    public static AuthnCredentialResult error(String message) {
+        Argument.expectNonNull(message, "message");
+        return new AuthnCredentialResult(null, message);
+    }
+
+    /**
+     * Returns true if this result contains a credential.
+     *
+     * @return true on success, false on error
+     */
+    public boolean isSuccess() {
+        return credential != null;
+    }
+
+    /**
+     * Returns the credential, or null if this is an error result.
+     *
+     * @return the credential, or null
+     */
+    public AuthnCredential credential() {
+        return credential;
+    }
+
+    /**
+     * Returns the error message, or null if this is a success result.
+     *
+     * @return the error message, or null
+     */
+    public String error() {
+        return error;
+    }
+}

bmq-sdk/src/main/java/com/bloomberg/bmq/SessionOptions.java

@@ -196,6 +196,31 @@ public int highWaterMark() {
         }
     }
 
+    /**
+     * Function type used to obtain authentication credentials for authenticating with the broker.
+     *
+     * <p>The function should return an {@link AuthnCredentialResult} containing either an {@link
+     * AuthnCredential} on success, or an error message on failure.
+     *
+     * <p>If not set on {@code SessionOptions}, the session will not authenticate with the broker.
+     */
+    @FunctionalInterface
+    public interface AuthnCredentialCb {
+
+        /**
+         * Returns authentication credentials or an error.
+         *
+         * @return an {@link AuthnCredentialResult} containing credentials on success, or an error
+         *     message on failure
+         */
+        AuthnCredentialResult get();
+    }
+
+    // Default to anonymous authentication so that all clients authenticate with
+    // the broker seamlessly without requiring explicit configuration.
+    private static final AuthnCredentialCb DEFAULT_AUTHN_CREDENTIAL_CB =
+            () -> AuthnCredentialResult.success("ANONYMOUS", new byte[0]);
+
     private static final URI DEFAULT_URI = URI.create("tcp://localhost:30114");
     private static final Duration DEFAULT_START_TIMEOUT = Duration.ofSeconds(65);
     private static final Duration DEFAULT_STOP_TIMEOUT = Duration.ofSeconds(30);
@@ -215,6 +240,8 @@ public int highWaterMark() {
 
     private final HostHealthMonitor hostHealthMonitor;
 
+    private final AuthnCredentialCb authnCredentialCb;
+
     private SessionOptions() {
         brokerUri = DEFAULT_URI;
         startTimeout = DEFAULT_START_TIMEOUT;
@@ -226,6 +253,7 @@ private SessionOptions() {
         configureQueueTimeout = QUEUE_OPERATION_TIMEOUT;
         closeQueueTimeout = QUEUE_OPERATION_TIMEOUT;
         hostHealthMonitor = null;
+        authnCredentialCb = DEFAULT_AUTHN_CREDENTIAL_CB;
     }
 
     private SessionOptions(Builder builder) {
@@ -239,6 +267,7 @@ private SessionOptions(Builder builder) {
         configureQueueTimeout = builder.configureQueueTimeout;
         closeQueueTimeout = builder.closeQueueTimeout;
         hostHealthMonitor = builder.hostHealthMonitor;
+        authnCredentialCb = builder.authnCredentialCb;
     }
 
     /**
@@ -383,6 +412,16 @@ public HostHealthMonitor hostHealthMonitor() {
         return hostHealthMonitor;
     }
 
+    /**
+     * Returns the callback invoked to obtain authentication credentials for authenticating with the
+     * broker. Default value is null, meaning the session will not authenticate.
+     *
+     * @return authentication credential callback, or null if not set
+     */
+    public AuthnCredentialCb authnCredentialCb() {
+        return authnCredentialCb;
+    }
+
     /** Helper class to create a {@code SesssionOptions} object with custom settings. */
     public static class Builder {
         private URI brokerUri;
@@ -397,6 +436,8 @@ public static class Builder {
         private Duration closeQueueTimeout;
 
         private HostHealthMonitor hostHealthMonitor;
+        private AuthnCredentialCb authnCredentialCb;
+
         /**
          * Creates a {@code SesssionOptions} object based on this {@code Builder} properties.
          *
@@ -417,6 +458,7 @@ private Builder(SessionOptions options) {
             configureQueueTimeout = options.configureQueueTimeout;
             closeQueueTimeout = options.closeQueueTimeout;
             hostHealthMonitor = options.hostHealthMonitor;
+            authnCredentialCb = options.authnCredentialCb;
         }
 
         /**
@@ -558,5 +600,18 @@ public Builder setHostHealthMonitor(HostHealthMonitor value) {
             hostHealthMonitor = Argument.expectNonNull(value, "host health monitor");
             return this;
         }
+
+        /**
+         * Sets the callback invoked to obtain authentication credentials for authenticating with
+         * the broker. If not set, the session will not authenticate with the broker.
+         *
+         * @param value authentication credential callback
+         * @return Builder this object
+         * @throws NullPointerException if the specified value is null
+         */
+        public Builder setAuthnCredentialCb(AuthnCredentialCb value) {
+            authnCredentialCb = Argument.expectNonNull(value, "authnCredentialCb");
+            return this;
+        }
     }
 }