@platformatic/kafka 2.10.0 → 2.11.0

package/dist/clients/admin/admin.js

@@ -1,5 +1,5 @@
 import { createPromisifiedCallback, kCallbackPromise, runConcurrentCallbacks } from "../../apis/callbacks.js";
-import { ConfigResourceTypes, FetchIsolationLevels, FindCoordinatorKeyTypes } from "../../apis/enumerations.js";
+import { ConfigResourceTypes, FetchIsolationLevels, FindCoordinatorKeyTypes, legacyConsumerGroupStates } from "../../apis/enumerations.js";
 import { adminAclsChannel, adminClientQuotasChannel, adminConfigsChannel, adminConsumerGroupOffsetsChannel, adminGroupsChannel, adminLogDirsChannel, adminOffsetsChannel, adminTopicsChannel, createDiagnosticContext } from "../../diagnostic.js";
 import { findErrorBy, MultipleErrors, NetworkError, UserError } from "../../errors.js";
 import { Reader } from "../../protocol/reader.js";
@@ -477,9 +477,10 @@ export class Admin extends Base {
                     return;
                 }
                 const created = [];
-                for (const { name, topicId: id, numPartitions: partitions, replicationFactor: replicas, configs } of response.topics) {
+                const topics = response.topics;
+                for (const { name, topicId: id = '', numPartitions: partitions = -1, replicationFactor: replicas = -1, configs: topicConfigs } of topics) {
                     const configuration = {};
-                    for (const { name, value } of configs) {
+                    for (const { name, value } of topicConfigs ?? []) {
                         configuration[name] = value;
                     }
                     created.push({ id, name, partitions, replicas, configuration });
@@ -567,8 +568,11 @@ export class Admin extends Base {
                                 retryCallback(error);
                                 return;
                             }
+                            // Brokers filter on the values they put on the wire, so the legacy Java enum
+                            // constant names have to be translated or they would silently match nothing.
+                            const states = (options.states ?? []).map(state => legacyConsumerGroupStates[state] ?? state);
                             /* c8 ignore next 5 */
-                            api(connection, options.states ?? [], options.types, retryCallback);
+                            api(connection, states, options.types, retryCallback);
                         });
                     }, concurrentCallback, 0);
                 });
@@ -582,8 +586,10 @@ export class Admin extends Base {
                     for (const raw of result.groups) {
                         groups.set(raw.groupId, {
                             id: raw.groupId,
-                            state: raw.groupState.toUpperCase(),
-                            groupType: raw.groupType,
+                            // ListGroups only carries group_state from v4, so below that the codec has nothing
+                            // to report. 'Unknown' is the value Kafka itself uses for exactly this case.
+                            state: (raw.groupState || 'Unknown'),
+                            groupType: raw.groupType || undefined,
                             protocolType: raw.protocolType
                         });
                     }
@@ -636,7 +642,7 @@ export class Admin extends Base {
                         for (const raw of result.groups) {
                             const group = {
                                 id: raw.groupId,
-                                state: raw.groupState.toUpperCase(),
+                                state: raw.groupState,
                                 protocolType: raw.protocolType,
                                 protocol: raw.protocolData,
                                 members: new Map(),
@@ -769,7 +775,13 @@ export class Admin extends Base {
                             groupInstanceId: null,
                             reason: typeof member === 'string' ? 'Not specified' : member.reason
                         }));
-                        api(connection, options.groupId, members, retryCallback);
+                        if (api.version >= 3) {
+                            api(connection, options.groupId, members, retryCallback);
+                            return;
+                        }
+                        runConcurrentCallbacks('Removing members from consumer group failed.', members, (member, concurrentCallback) => {
+                            api(connection, options.groupId, [member], concurrentCallback);
+                        }, error => retryCallback(error));
                     });
                 });
             });
@@ -793,7 +805,28 @@ export class Admin extends Base {
                         retryCallback(error);
                         return;
                     }
-                    api(connection, options.keyType, options.keys, retryCallback);
+                    if (api.version >= 4) {
+                        api(connection, options.keyType, options.keys, retryCallback);
+                        return;
+                    }
+                    runConcurrentCallbacks('Finding coordinator failed.', options.keys, (key, concurrentCallback) => {
+                        api(connection, options.keyType, [key], (error, response) => {
+                            if (response) {
+                                response.coordinators[0].key = key;
+                            }
+                            concurrentCallback(error, response);
+                        });
+                    }, (error, responses) => {
+                        if (error) {
+                            retryCallback(error);
+                            return;
+                        }
+                        retryCallback(null, {
+                            // The caller controls how many keys are looked up, so reduce rather than spread.
+                            throttleTimeMs: responses.reduce((max, response) => Math.max(max, response.throttleTimeMs), 0),
+                            coordinators: responses.flatMap(response => response.coordinators)
+                        });
+                    });
                 });
             });
         }, (error, response) => {
@@ -829,7 +862,7 @@ export class Admin extends Base {
                 callback(new MultipleErrors('Describing client quotas failed.', [error]));
                 return;
             }
-            callback(null, response.entries);
+            callback(null, response.entries ?? []);
         }, 0);
     }
     #alterClientQuotas(options, callback) {
@@ -943,8 +976,38 @@ export class Admin extends Base {
                                     retryCallback(error);
                                     return;
                                 }
-                                /* c8 ignore next - Hard to test */
-                                api(connection, groupRequests, options.requireStable ?? false, retryCallback);
+                                if (api.version >= 8) {
+                                    api(connection, groupRequests, options.requireStable ?? false, retryCallback);
+                                    return;
+                                }
+                                runConcurrentCallbacks('Listing consumer group offsets failed.', groupRequests, (groupRequest, groupCallback) => {
+                                    api(connection, [groupRequest], options.requireStable ?? false, (error, response) => {
+                                        if (error) {
+                                            groupCallback(error);
+                                            return;
+                                        }
+                                        const legacyResponse = response;
+                                        groupCallback(null, {
+                                            throttleTimeMs: legacyResponse.throttleTimeMs,
+                                            groups: [
+                                                {
+                                                    groupId: groupRequest.groupId,
+                                                    topics: legacyResponse.topics,
+                                                    errorCode: legacyResponse.errorCode
+                                                }
+                                            ]
+                                        });
+                                    });
+                                }, (error, responses) => {
+                                    if (error) {
+                                        retryCallback(error);
+                                        return;
+                                    }
+                                    retryCallback(null, {
+                                        throttleTimeMs: responses.reduce((max, response) => Math.max(max, response.throttleTimeMs), 0),
+                                        groups: responses.flatMap(response => response.groups)
+                                    });
+                                });
                             });
                         });
                     }, concurrentCallback, 0);

package/dist/clients/admin/options.d.ts

@@ -185,7 +185,7 @@ export declare const listGroupsOptionsSchema: {
             items: {
                 type: string;
                 enumeration: {
-                    allowed: readonly ["PREPARING_REBALANCE", "COMPLETING_REBALANCE", "STABLE", "DEAD", "EMPTY"];
+                    allowed: ("Unknown" | "PreparingRebalance" | "CompletingRebalance" | "Stable" | "Dead" | "Empty" | "Assigning" | "Reconciling" | "NotReady" | "PREPARING_REBALANCE" | "COMPLETING_REBALANCE" | "STABLE" | "DEAD" | "EMPTY")[];
                     errorMessage: string;
                 };
             };
@@ -764,7 +764,7 @@ export declare const createAclsOptionsSchema: {
                     };
                     operation: {
                         type: string;
-                        enum: (0 | 1 | 2 | 4 | 8 | 7 | 10 | 3 | 5 | 6 | 9 | 11 | 12 | 13 | 14 | 15)[];
+                        enum: (0 | 1 | 2 | 4 | 8 | 7 | 10 | 12 | 3 | 5 | 6 | 9 | 11 | 13 | 14 | 15)[];
                     };
                     permissionType: {
                         type: string;
@@ -823,7 +823,7 @@ export declare const describeAclsOptionsSchema: {
                 };
                 operation: {
                     type: string;
-                    enum: (0 | 1 | 2 | 4 | 8 | 7 | 10 | 3 | 5 | 6 | 9 | 11 | 12 | 13 | 14 | 15)[];
+                    enum: (0 | 1 | 2 | 4 | 8 | 7 | 10 | 12 | 3 | 5 | 6 | 9 | 11 | 13 | 14 | 15)[];
                 };
                 permissionType: {
                     type: string;
@@ -882,7 +882,7 @@ export declare const deleteAclsOptionsSchema: {
                     };
                     operation: {
                         type: string;
-                        enum: (0 | 1 | 2 | 4 | 8 | 7 | 10 | 3 | 5 | 6 | 9 | 11 | 12 | 13 | 14 | 15)[];
+                        enum: (0 | 1 | 2 | 4 | 8 | 7 | 10 | 12 | 3 | 5 | 6 | 9 | 11 | 13 | 14 | 15)[];
                     };
                     permissionType: {
                         type: string;

package/dist/clients/admin/options.js

@@ -1,4 +1,4 @@
-import { allowedAclOperations, allowedAclPermissionTypes, allowedClientQuotaMatchTypes, allowedFetchIsolationLevels, allowedFindCoordinatorKeyTypes, allowedIncrementalAlterConfigOperationTypes, allowedResourcePatternTypes, allowedResourceTypes, ConsumerGroupStates, IncrementalAlterConfigOperationTypes } from "../../apis/enumerations.js";
+import { allowedAclOperations, allowedAclPermissionTypes, allowedClientQuotaMatchTypes, allowedFetchIsolationLevels, allowedFindCoordinatorKeyTypes, allowedIncrementalAlterConfigOperationTypes, allowedResourcePatternTypes, allowedResourceTypes, ConsumerGroupStates, KafkaConsumerGroupStates, IncrementalAlterConfigOperationTypes } from "../../apis/enumerations.js";
 import { ajv, listErrorMessage } from "../../utils.js";
 import { idProperty } from "../base/options.js";
 export const groupsProperties = {
@@ -117,8 +117,8 @@ export const listGroupsOptionsSchema = {
             items: {
                 type: 'string',
                 enumeration: {
-                    allowed: ConsumerGroupStates,
-                    errorMessage: listErrorMessage(ConsumerGroupStates)
+                    allowed: [...ConsumerGroupStates, ...KafkaConsumerGroupStates],
+                    errorMessage: listErrorMessage([...ConsumerGroupStates, ...KafkaConsumerGroupStates])
                 }
             },
             minItems: 0

package/dist/clients/admin/types.d.ts

@@ -33,7 +33,7 @@ export interface GroupMember {
 export interface GroupBase {
     id: string;
     state: ConsumerGroupStateValue;
-    groupType: string;
+    groupType?: string;
     protocolType: string;
 }
 export interface Group extends Omit<GroupBase, 'groupType'> {

package/dist/clients/base/base.d.ts

@@ -1,7 +1,7 @@
 import { type ValidateFunction } from 'ajv';
 import { type CallbackWithPromise } from '../../apis/callbacks.ts';
 import { type API, type Callback } from '../../apis/definitions.ts';
-import { type ApiVersionsResponseApi } from '../../apis/metadata/api-versions-v3.ts';
+import { type ApiVersionsResponseApi } from '../../apis/metadata/api-versions-v1.ts';
 import { type ClientType } from '../../diagnostic.ts';
 import { TypedEventEmitter, type TypedEvents } from '../../events.ts';
 import { ConnectionPool, type ConnectionPoolEventPayload } from '../../network/connection-pool.ts';

package/dist/clients/base/base.js

@@ -1,5 +1,6 @@
 import { createPromisifiedCallback, kCallbackPromise, runConcurrentCallbacks } from "../../apis/callbacks.js";
 import * as apis from "../../apis/index.js";
+import { api as apiVersionsV1 } from "../../apis/metadata/api-versions-v1.js";
 import { api as apiVersionsV3 } from "../../apis/metadata/api-versions-v3.js";
 import { baseApisChannel, baseMetadataChannel, createDiagnosticContext, notifyCreation } from "../../diagnostic.js";
 import { findErrorBy, MultipleErrors, NetworkError, UnsupportedApiError, UserError } from "../../errors.js";
@@ -47,6 +48,7 @@ export class Base extends TypedEventEmitter {
     [kPrometheus];
     #metadata;
     #inflightDeduplications;
+    #apiVersionsVersions;
     constructor(options) {
         super();
         this.setMaxListeners(0);
@@ -54,6 +56,7 @@ export class Base extends TypedEventEmitter {
         this[kInstance] = currentInstance++;
         this[kApis] = [];
         this[kContext] = options.context;
+        this.#apiVersionsVersions = new WeakMap();
         // Validate options
         this[kOptions] = Object.assign({}, defaultBaseOptions);
         for (const [key, value] of Object.entries(options)) {
@@ -212,8 +215,29 @@ export class Base extends TypedEventEmitter {
                         retryCallback(error);
                         return;
                     }
-                    // We use V3 to be able to get APIS from Kafka 2.4.0+
-                    apiVersionsV3(connection, clientSoftwareName, clientSoftwareVersion, retryCallback);
+                    const apiVersionsVersion = this.#apiVersionsVersions.get(connection);
+                    const listApisV1 = () => {
+                        apiVersionsV1(connection, clientSoftwareName, clientSoftwareVersion, (error, response) => {
+                            retryCallback(error, response);
+                        });
+                    };
+                    if (apiVersionsVersion === 1) {
+                        listApisV1();
+                        return;
+                    }
+                    apiVersionsV3(connection, clientSoftwareName, clientSoftwareVersion, (error, response) => {
+                        if (!error) {
+                            this.#apiVersionsVersions.set(connection, 3);
+                            retryCallback(null, response);
+                            return;
+                        }
+                        if (findErrorBy(error, 'apiId', 'UNSUPPORTED_VERSION')) {
+                            this.#apiVersionsVersions.set(connection, 1);
+                            listApisV1();
+                            return;
+                        }
+                        retryCallback(error);
+                    });
                 }, attempt);
             }, (error, metadata) => {
                 if (error) {
@@ -429,7 +453,16 @@ export class Base extends TypedEventEmitter {
                         // (e.g. MSK) authorize every topic operation and emit a CloudTrail
                         // AccessDenied per denied op (CreateTopic/DeleteTopic/...) — pure
                         // audit-log noise for permissions the client never exercises.
-                        api(connection, topicsToFetch, autocreateTopics, false, retryCallback);
+                        api(connection, topicsToFetch, autocreateTopics, false, (error, response) => {
+                            // Metadata v0-v8 do not carry topic UUIDs. Topic names are stable
+                            // surrogates for the consumer paths that use internal topic IDs.
+                            if (!error && api.version <= 8) {
+                                for (const topic of response.topics) {
+                                    topic.topicId = topic.name;
+                                }
+                            }
+                            retryCallback(error, response);
+                        });
                     });
                 }, attempt);
             }, (error, metadata) => {

package/dist/clients/consumer/consumer.js

@@ -362,6 +362,13 @@ export class Consumer extends Base {
             throw validationError;
         }
         this.#lagMonitoring = setTimeout(() => {
+            // Skip this tick while mid-(re)join: listOffsets adds load to a coordinator/cluster that
+            // may already be struggling, and any lag figure computed against stale/absent assignments
+            // would be meaningless anyway. Just reschedule and try again next tick.
+            if (!this.isActive()) {
+                this.#lagMonitoring.refresh();
+                return;
+            }
             this.getLag(options, () => this.#lagMonitoring.refresh());
         }, interval);
     }
@@ -592,7 +599,36 @@ export class Consumer extends Base {
                                 }
                             }
                         }
+                        // Fetch v12 identifies topics by name, while later versions use UUIDs.
+                        const useTopicNames = api.version <= 12;
+                        let topicIdsByName;
+                        if (useTopicNames) {
+                            // Built here rather than in the response callback so that the fetch loop allocates
+                            // it once per request instead of once per request and once per response.
+                            topicIdsByName = new Map();
+                            for (const [id, name] of topicIds) {
+                                topicIdsByName.set(name, id);
+                            }
+                            requestTopics = requestTopics.map(topic => ({
+                                ...topic,
+                                topicId: topicIds.get(topic.topicId) ?? topic.topicId
+                            }));
+                            for (const forgotten of forgottenTopicsData) {
+                                const topicId = forgotten.topicId ?? forgotten.topic;
+                                forgotten.topicId = topicIds.get(topicId) ?? topicId;
+                                delete forgotten.topic;
+                            }
+                        }
                         api(connection, options.maxWaitTime ?? this[kOptions].maxWaitTime, options.minBytes ?? this[kOptions].minBytes, options.maxBytes ?? this[kOptions].maxBytes, isolationLevel, sessionId, sessionEpoch, requestTopics, forgottenTopicsData, this.#clientRack, (error, result) => {
+                            const response = result ?? error?.response;
+                            if (response && !response.nodeEndpoints) {
+                                response.nodeEndpoints = [];
+                            }
+                            if (useTopicNames && response) {
+                                for (const topic of response.responses) {
+                                    topic.topicId = topicIdsByName.get(topic.topicId) ?? topic.topicId;
+                                }
+                            }
                             if (error) {
                                 refreshMetadata = NetworkError.isRetryable(error);
                                 this.#clearPreferredReadReplicas(options.topics, topicIds);
@@ -805,7 +841,17 @@ export class Consumer extends Base {
                         memberEpoch: this.#useConsumerGroupProtocol ? this.#memberEpoch : -1,
                         topics
                     }
-                ], false, groupCallback);
+                ], false, (error, response) => {
+                    if (error || api.version >= 8) {
+                        groupCallback(error, response);
+                        return;
+                    }
+                    const legacyResponse = response;
+                    groupCallback(null, {
+                        throttleTimeMs: legacyResponse.throttleTimeMs,
+                        groups: [{ groupId: this.groupId, topics: legacyResponse.topics, errorCode: legacyResponse.errorCode }]
+                    });
+                });
             });
         }, (error, response) => {
             if (error) {
@@ -1000,7 +1046,12 @@ export class Consumer extends Base {
                     this.assignments = [];
                     this.#syncPreferredReadReplicas();
                     this.#memberEpoch = 0;
-                    this.#consumerGroupHeartbeat(options, () => { });
+                    // Retry after a delay, not immediately: if many members get fenced around the same
+                    // rebalance, resending ConsumerGroupHeartbeat with no delay at all can flood the
+                    // coordinator faster than the group can converge.
+                    this.#heartbeatInterval = setTimeout(() => {
+                        this.#consumerGroupHeartbeat(options, () => { });
+                    }, this.#lastHeartbeatIntervalMs || 1000);
                     callback(error);
                     return;
                 }
@@ -1251,7 +1302,12 @@ export class Consumer extends Base {
                             retryCallback(error);
                             return;
                         }
-                        api(connection, FindCoordinatorKeyTypes.GROUP, [this.groupId], retryCallback);
+                        api(connection, FindCoordinatorKeyTypes.GROUP, [this.groupId], (error, response) => {
+                            if (response && api.version < 4) {
+                                response.coordinators[0].key = this.groupId;
+                            }
+                            retryCallback(error, response);
+                        });
                     });
                 });
             }, (error, response) => {
@@ -1632,12 +1688,13 @@ export class Consumer extends Base {
                 if (!partition.records) {
                     continue;
                 }
-                if (partition.abortedTransactions.length) {
+                const abortedTransactions = partition.abortedTransactions ?? [];
+                if (abortedTransactions.length) {
                     const abortedRanges = new Map();
                     // Find first offsets
                     // For last offsets we set -1n as special value. It allows us to detect open ranges, whichs means
                     // that Kafka has not sent the control marker. In that case we ignore the range for safety.
-                    for (const aborted of partition.abortedTransactions) {
+                    for (const aborted of abortedTransactions) {
                         abortedRanges.set(aborted.producerId, [aborted.firstOffset, -1n]);
                     }
                     // Now find last offsets

package/dist/clients/consumer/messages-stream.js

@@ -796,6 +796,16 @@ export class MessagesStream extends Readable {
         if (this.#offsetsToCommit.size === 0) {
             return;
         }
+        // Skip this tick while the consumer is mid-(re)join: a commit attempted here would fail
+        // with a rejoin-required error (ILLEGAL_GENERATION/UNKNOWN_MEMBER_ID/REBALANCE_IN_PROGRESS),
+        // and — since this runs on its own timer, independently of the group's own rejoin flow —
+        // each such failure calls joinGroup again. With a short autocommit interval and many
+        // consumers in the group, this can fire fresh JoinGroups fast enough that the group never
+        // completes a rebalance round. Leave the offsets queued; they are committed once the
+        // consumer becomes active again (next tick, or the final flush on close/destroy).
+        if (!this.#consumer.isActive()) {
+            return;
+        }
         this.#autocommitInflight = true;
         const offsets = Array.from(this.#offsetsToCommit.values());
         this.#offsetsToCommit.clear();

package/dist/clients/producer/producer.js

@@ -353,7 +353,12 @@ export class Producer extends Base {
                             retryCallback(error);
                             return;
                         }
-                        api(connection, FindCoordinatorKeyTypes.TRANSACTION, [transactionalId], retryCallback);
+                        api(connection, FindCoordinatorKeyTypes.TRANSACTION, [transactionalId], (error, response) => {
+                            if (response && api.version < 4) {
+                                response.coordinators[0].key = transactionalId;
+                            }
+                            retryCallback(error, response);
+                        });
                     });
                 }, attempt);
             }, (error, response) => {

package/dist/network/connection.js

@@ -4,7 +4,8 @@ import { createConnection } from 'node:net';
 import { connect as createTLSConnection } from 'node:tls';
 import { createPromisifiedCallback, kCallbackPromise } from "../apis/callbacks.js";
 import { allowedSASLMechanisms, SASLMechanisms } from "../apis/enumerations.js";
-import { saslAuthenticateV2, saslHandshakeV1 } from "../apis/index.js";
+import { clientSoftwareName, clientSoftwareVersion } from "../clients/base/options.js";
+import { apiVersionsV1, saslAuthenticateV0, saslAuthenticateV1, saslAuthenticateV2, saslHandshakeV1 } from "../apis/index.js";
 import { connectionsApiChannel, connectionsConnectsChannel, createDiagnosticContext, notifyCreation } from "../diagnostic.js";
 import { AuthenticationError, NetworkError, TimeoutError, UnexpectedCorrelationIdError, UserError } from "../errors.js";
 import { TypedEventEmitter } from "../events.js";
@@ -52,6 +53,8 @@ export class Connection extends TypedEventEmitter {
     #socketMustBeDrained;
     #detectMissingTLS;
     #reauthenticationTimeout;
+    // Negotiated once per connection: reauthentication runs the same path again.
+    #saslAuthenticateApi;
     constructor(clientId, options = {}) {
         super();
         this.setMaxListeners(0);
@@ -340,28 +343,71 @@ export class Connection extends TypedEventEmitter {
             this.#onConnectionError(host, port, diagnosticContext, new UserError(`SASL mechanism ${mechanism} not supported.`));
             return;
         }
-        saslHandshakeV1.api(this, mechanism, (error, response) => {
+        this.#negotiateSaslAuthenticate(saslAuthenticate => {
+            saslHandshakeV1.api(this, mechanism, (error, response) => {
+                if (error) {
+                    this.#onConnectionError(host, port, diagnosticContext, new AuthenticationError('Cannot find a suitable SASL mechanism.', { cause: error }));
+                    return;
+                }
+                this.emit('sasl:handshake', response.mechanisms);
+                const callback = this.#onSaslAuthenticate.bind(this, host, port, diagnosticContext);
+                if (authenticate) {
+                    authenticate(mechanism, this, saslAuthenticate, username, password, token, callback);
+                }
+                else if (mechanism === SASLMechanisms.PLAIN) {
+                    saslPlain.authenticate(saslAuthenticate, this, username, password, callback);
+                }
+                else if (mechanism === SASLMechanisms.OAUTHBEARER) {
+                    saslOAuthBearer.authenticate(saslAuthenticate, this, token, oauthBearerExtensions, callback);
+                }
+                else if (mechanism === SASLMechanisms.GSSAPI) {
+                    callback(new UserError('No custom SASL/GSSAPI authenticator provided.'));
+                }
+                else {
+                    saslScramSha.authenticate(saslAuthenticate, this, mechanism.substring(6), username, password, defaultCrypto, callback);
+                }
+            });
+        });
+    }
+    /**
+     * Chooses the SaslAuthenticate version to authenticate with.
+     *
+     * The version cannot be assumed: v1 arrived in Apache Kafka 2.0 and v2 in 2.4, so pinning the
+     * newest makes authentication fail outright on older brokers, which answer an unparseable request
+     * with InvalidRequestException and drop the connection.
+     *
+     * Brokers accept ApiVersions before authentication precisely so that clients can ask, and it has
+     * to happen before SaslHandshake: once the handshake is sent the connection only accepts
+     * SaslAuthenticate. The result is cached because reauthentication runs this path again.
+     *
+     * SaslHandshake itself stays at v1. v0 signals the pre-1.0 flow, where the SASL tokens are written
+     * raw on the wire rather than wrapped in SaslAuthenticate requests, which this package does not
+     * implement.
+     */
+    #negotiateSaslAuthenticate(callback) {
+        if (this.#saslAuthenticateApi) {
+            callback(this.#saslAuthenticateApi);
+            return;
+        }
+        const candidates = [
+            [2, saslAuthenticateV2.api],
+            [1, saslAuthenticateV1.api],
+            [0, saslAuthenticateV0.api]
+        ];
+        apiVersionsV1.api(this, clientSoftwareName, clientSoftwareVersion, (error, response) => {
+            let selected;
+            /* c8 ignore next 3 - Only reachable against a broker which refuses ApiVersions before authentication */
             if (error) {
-                this.#onConnectionError(host, port, diagnosticContext, new AuthenticationError('Cannot find a suitable SASL mechanism.', { cause: error }));
-                return;
-            }
-            this.emit('sasl:handshake', response.mechanisms);
-            const callback = this.#onSaslAuthenticate.bind(this, host, port, diagnosticContext);
-            if (authenticate) {
-                authenticate(mechanism, this, saslAuthenticateV2.api, username, password, token, callback);
-            }
-            else if (mechanism === SASLMechanisms.PLAIN) {
-                saslPlain.authenticate(saslAuthenticateV2.api, this, username, password, callback);
-            }
-            else if (mechanism === SASLMechanisms.OAUTHBEARER) {
-                saslOAuthBearer.authenticate(saslAuthenticateV2.api, this, token, oauthBearerExtensions, callback);
-            }
-            else if (mechanism === SASLMechanisms.GSSAPI) {
-                callback(new UserError('No custom SASL/GSSAPI authenticator provided.'));
+                selected = undefined;
             }
             else {
-                saslScramSha.authenticate(saslAuthenticateV2.api, this, mechanism.substring(6), username, password, defaultCrypto, callback);
+                const advertised = response.apiKeys.find(api => api.apiKey === saslAuthenticateV2.api.key);
+                selected = candidates.find(([version]) => advertised && version >= advertised.minVersion && version <= advertised.maxVersion)?.[1];
             }
+            // Falling back to the newest version keeps the previous behaviour for brokers which do not
+            // answer the probe, rather than failing a connection which would otherwise have worked.
+            this.#saslAuthenticateApi = selected ?? saslAuthenticateV2.api;
+            callback(this.#saslAuthenticateApi);
         });
     }
     /*

package/dist/protocol/definitions.js

@@ -7,5 +7,5 @@ export const EMPTY_BUFFER = Buffer.alloc(0);
 export const EMPTY_UUID = Buffer.alloc(UUID_SIZE);
 // Since it is serialized at either 0 (for nullable) or 1 (since length is stored as length + 1), it always uses a single byte
 export const EMPTY_OR_SINGLE_COMPACT_LENGTH_SIZE = INT8_SIZE;
-// TODO: Tagged fields are not supported yet
+// Flexible-version messages use this zero-length tagged-field section.
 export const EMPTY_TAGGED_FIELDS_BUFFER = Buffer.from([0]);

package/dist/protocol/reader.js

@@ -187,9 +187,13 @@ export class Reader {
         return this.readNullableString(compact, encoding) || '';
     }
     readUUID() {
-        const value = this.peekUUID();
+        const hex = this.peekUUID();
         this.position += UUID_SIZE;
-        return value.replace(/(.{8})(.{4})(.{4})(.{4})(.{12})/, '$1-$2-$3-$4-$5');
+        // Hyphenated by slicing rather than by a capture group regex. This runs once per topic per
+        // Fetch response from v13 up, and the regex form measured about fourteen times the cost, which
+        // made the newest Fetch versions measurably slower to decode than the ones identifying topics
+        // by name.
+        return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
     }
     readNullableBytes(compact = true) {
         let length;
@@ -300,7 +304,7 @@ export class Reader {
         }
         return reader();
     }
-    // TODO: Tagged fields are not supported yet
+    // Skip unknown tagged fields because codecs do not expose them to callers.
     readTaggedFields() {
         const length = this.readUnsignedVarInt();
         for (let i = 0; i < length; i++) {

package/dist/protocol/writer.js

@@ -1,6 +1,6 @@
 import { DynamicBuffer } from '@platformatic/dynamic-buffer';
 import { humanize } from "../utils.js";
-import { EMPTY_TAGGED_FIELDS_BUFFER, EMPTY_UUID } from "./definitions.js";
+import { EMPTY_TAGGED_FIELDS_BUFFER, EMPTY_UUID, UUID_SIZE } from "./definitions.js";
 const instanceIdentifier = Symbol('plt.kafka.writer.instanceIdentifier');
 export class Writer {
     context;
@@ -125,6 +125,12 @@ export class Writer {
             return this.append(EMPTY_UUID);
         }
         const buffer = Buffer.from(value.replaceAll('-', ''), 'hex');
+        // UUIDs are fixed width and carry no length prefix, so anything that is not exactly 16 bytes
+        // would silently desync the rest of the request. Buffer.from() stops at the first non hex
+        // character, so a topic name used as a topic id would append nothing at all here.
+        if (buffer.length !== UUID_SIZE) {
+            throw new RangeError(`Expected a UUID, got ${JSON.stringify(value)}.`);
+        }
         this.#buffer.append(buffer);
         return this;
     }
@@ -138,7 +144,9 @@ export class Writer {
         else {
             this.appendInt32(value.length);
         }
-        this.#buffer.append(value);
+        if (value.length > 0) {
+            this.#buffer.append(value);
+        }
         return this;
     }
     // Note that this does not follow the wire protocol specification and thus the length is not +1ed
@@ -147,7 +155,12 @@ export class Writer {
             return this.appendVarInt(-1);
         }
         this.appendVarInt(value.length);
-        this.#buffer.append(value);
+        // Appending an empty buffer corrupts DynamicBuffer's positional reads, so it must be skipped:
+        // see https://github.com/platformatic/dynamic-buffer/issues/12. Record keys and values are
+        // allowed to be empty without being null, so this is reachable.
+        if (value.length > 0) {
+            this.#buffer.append(value);
+        }
         return this;
     }
     appendArray(value, entryWriter, compact = true, appendTrailingTaggedFields = true) {
@@ -210,7 +223,7 @@ export class Writer {
         }
         return this;
     }
-    // TODO: Tagged fields are not supported yet
+    // This client emits only empty tagged-field sections; it does not expose tagged fields to callers.
     appendTaggedFields(_ = []) {
         return this.append(EMPTY_TAGGED_FIELDS_BUFFER);
     }