@platformatic/kafka 2.10.0-alpha.1 → 2.11.0

package/dist/apis/metadata/api-versions-v3.js

@@ -32,8 +32,15 @@ export function createRequest(clientSoftwareName, clientSoftwareVersion) {
       zk_migration_ready (3) => BOOLEAN
 */
 export function parseResponse(_correlationId, apiKey, apiVersion, reader) {
+    const errorCode = reader.readInt16();
+    // Kafka returns an ApiVersions v0-framed response when v3 is unsupported.
+    // Stop before reading the compact array, which would interpret the legacy
+    // array length as flexible protocol data and desynchronize the response.
+    if (errorCode !== 0) {
+        throw new ResponseError(apiKey, apiVersion, { '/': [errorCode, null] }, { errorCode, apiKeys: [], throttleTimeMs: 0 });
+    }
     const response = {
-        errorCode: reader.readInt16(),
+        errorCode,
         apiKeys: reader.readArray(r => {
             const apiKey = r.readInt16();
             const api = {

package/dist/clients/admin/admin.js

@@ -1,7 +1,7 @@
 import { createPromisifiedCallback, kCallbackPromise, runConcurrentCallbacks } from "../../apis/callbacks.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, UserError } from "../../errors.js";
+import { findErrorBy, MultipleErrors, NetworkError, UserError } from "../../errors.js";
 import { Reader } from "../../protocol/reader.js";
 import { Base, kAfterCreate, kCheckNotClosed, kConnections, kGetApi, kGetBootstrapConnection, kGetConnection, kMetadata, kOptions, kPerformDeduplicated, kPerformWithRetry, kValidateOptions } from "../base/base.js";
 import { adminListOffsetsOptionsValidator, alterClientQuotasOptionsValidator, alterConfigsOptionsValidator, alterConsumerGroupOffsetsOptionsValidator, createAclsOptionsValidator, createPartitionsOptionsValidator, createTopicsOptionsValidator, deleteAclsOptionsValidator, deleteConsumerGroupOffsetsOptionsValidator, deleteGroupsOptionsValidator, deleteRecordsOptionsValidator, deleteTopicsOptionsValidator, describeAclsOptionsValidator, describeClientQuotasOptionsValidator, describeConfigsOptionsValidator, describeGroupsOptionsValidator, describeLogDirsOptionsValidator, findCoordinatorOptionsValidator, incrementalAlterConfigsOptionsValidator, listConsumerGroupOffsetsOptionsValidator, listGroupsOptionsValidator, listTopicsOptionsValidator, removeMembersFromConsumerGroupOptionsValidator } from "./options.js";
@@ -366,7 +366,12 @@ export class Admin extends Base {
     }
     #getControllerConnection(callback) {
         if (this.#controller) {
-            this[kConnections].get(this.#controller, callback);
+            this[kConnections].get(this.#controller, (error, connection) => {
+                if (NetworkError.isRetryable(error)) {
+                    this.#controller = null;
+                }
+                callback(error, connection);
+            });
         }
         else {
             this[kGetBootstrapConnection](callback);
@@ -422,26 +427,34 @@ export class Admin extends Base {
             }, 0);
         }, callback);
     }
+    #mapTopicAssignments(assignments) {
+        const mapped = [];
+        for (const { partition, brokers } of assignments ?? []) {
+            mapped.push({ partitionIndex: partition, brokerIds: brokers });
+        }
+        return mapped;
+    }
     #createTopics(options, callback) {
         // -1 is required if manual assignments are used. If no manual assignments are used, -1 will default to broker settings.
         const numPartitions = options.partitions ?? -1;
         const replicationFactor = options.replicas ?? -1;
-        const assignments = [];
+        const assignments = this.#mapTopicAssignments(options.assignments);
         const configs = options.configs ?? [];
-        for (const { partition, brokers } of options.assignments ?? []) {
-            assignments.push({ partitionIndex: partition, brokerIds: brokers });
-        }
         const requests = [];
         for (const topic of options.topics) {
+            if (typeof topic === 'string') {
+                requests.push({ name: topic, numPartitions, replicationFactor, assignments, configs });
+                continue;
+            }
             requests.push({
-                name: topic,
-                numPartitions,
-                replicationFactor,
-                assignments,
+                name: topic.topic,
+                numPartitions: topic.partitions ?? numPartitions,
+                replicationFactor: topic.replicas ?? replicationFactor,
+                assignments: topic.assignments ? this.#mapTopicAssignments(topic.assignments) : assignments,
                 configs
             });
         }
-        this[kPerformDeduplicated](`createTopics-${options.topics.join(',')}`, deduplicateCallback => {
+        this[kPerformDeduplicated](`createTopics-${options.topics.map(topic => (typeof topic === 'string' ? topic : topic.topic)).join(',')}`, deduplicateCallback => {
             this[kPerformWithRetry]('createTopics', retryCallback => {
                 this.#getControllerConnection((error, connection) => {
                     if (error) {

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

@@ -14,8 +14,48 @@ export declare const createTopicOptionsSchema: {
         topics: {
             type: string;
             items: {
-                type: string;
-                pattern: string;
+                oneOf: ({
+                    type: string;
+                    pattern: string;
+                } | {
+                    type: string;
+                    properties: {
+                        topic: {
+                            type: string;
+                            pattern: string;
+                        };
+                        partitions: {
+                            type: string;
+                        };
+                        replicas: {
+                            type: string;
+                        };
+                        assignments: {
+                            type: string;
+                            items: {
+                                type: string;
+                                properties: {
+                                    partition: {
+                                        type: string;
+                                        minimum: number;
+                                    };
+                                    brokers: {
+                                        type: string;
+                                        items: {
+                                            type: string;
+                                        };
+                                        minItems: number;
+                                    };
+                                };
+                                required: string[];
+                                additionalProperties: boolean;
+                            };
+                            minItems: number;
+                        };
+                    };
+                    required: string[];
+                    additionalProperties: boolean;
+                })[];
             };
         };
         partitions: {
@@ -46,6 +86,22 @@ export declare const createTopicOptionsSchema: {
             };
             minItems: number;
         };
+        configs: {
+            type: string;
+            items: {
+                type: string;
+                properties: {
+                    name: {
+                        type: string;
+                    };
+                    value: {
+                        type: string[];
+                    };
+                };
+                required: string[];
+                additionalProperties: boolean;
+            };
+        };
     };
     required: string[];
     additionalProperties: boolean;

package/dist/clients/admin/options.js

@@ -8,24 +8,55 @@ export const groupsProperties = {
         minItems: 1
     }
 };
+const createTopicAssignmentsSchema = {
+    type: 'array',
+    items: {
+        type: 'object',
+        properties: {
+            partition: { type: 'number', minimum: 0 },
+            brokers: { type: 'array', items: { type: 'number' }, minItems: 1 }
+        },
+        required: ['partition', 'brokers'],
+        additionalProperties: false
+    },
+    minItems: 1
+};
 export const createTopicOptionsSchema = {
     type: 'object',
     properties: {
-        topics: { type: 'array', items: idProperty },
+        topics: {
+            type: 'array',
+            items: {
+                oneOf: [
+                    idProperty,
+                    {
+                        type: 'object',
+                        properties: {
+                            topic: idProperty,
+                            partitions: { type: 'number' },
+                            replicas: { type: 'number' },
+                            assignments: createTopicAssignmentsSchema
+                        },
+                        required: ['topic'],
+                        additionalProperties: false
+                    }
+                ]
+            }
+        },
         partitions: { type: 'number' },
         replicas: { type: 'number' },
-        assignments: {
+        assignments: createTopicAssignmentsSchema,
+        configs: {
             type: 'array',
             items: {
                 type: 'object',
                 properties: {
-                    partition: { type: 'number', minimum: 0 },
-                    brokers: { type: 'array', items: { type: 'number' }, minItems: 1 }
+                    name: { type: 'string' },
+                    value: { type: ['string', 'null'] }
                 },
-                required: ['partition', 'brokers'],
+                required: ['name'],
                 additionalProperties: false
-            },
-            minItems: 1
+            }
         }
     },
     required: ['topics'],

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

@@ -43,8 +43,14 @@ export interface Group extends Omit<GroupBase, 'groupType'> {
 }
 export interface AdminOptions extends BaseOptions {
 }
+export interface CreateTopicsTopicOptions {
+    topic: string;
+    partitions?: number;
+    replicas?: number;
+    assignments?: BrokerAssignment[];
+}
 export interface CreateTopicsOptions {
-    topics: string[];
+    topics: (string | CreateTopicsTopicOptions)[];
     partitions?: number;
     replicas?: number;
     assignments?: BrokerAssignment[];

package/dist/clients/base/base.js

@@ -1,6 +1,7 @@
 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";
 import { TypedEventEmitter } from "../../events.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,14 +215,29 @@ export class Base extends TypedEventEmitter {
                         retryCallback(error);
                         return;
                     }
-                    // We use V1 because it is supported by Kafka 1.1.0+.
-                    //
-                    // The tradeoff is that clientSoftwareName and clientSoftwareVersion only exist from
-                    // V3, so brokers cannot attribute client metrics to this package (KIP-511) and the
-                    // two arguments below are accepted and discarded by the V1 codec. Removing the
-                    // tradeoff requires negotiating down from V3 on UNSUPPORTED_VERSION rather than
-                    // pinning a version: see https://github.com/platformatic/kafka/issues/343.
-                    apiVersionsV1(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) {

package/dist/clients/consumer/consumer.d.ts

@@ -6,7 +6,7 @@ import { Base, type BaseEvents, kCreateConnectionPool } from '../base/base.ts';
 import { type ClusterMetadata } from '../base/types.ts';
 import { MessagesStream } from './messages-stream.ts';
 import { TopicsMap } from './topics-map.ts';
-import { type CommitOptions, type ConsumeOptions, type ConsumerGroupJoinPayload, type ConsumerGroupLeavePayload, type ConsumerGroupRebalancePayload, type ConsumerHeartbeatErrorPayload, type ConsumerHeartbeatPayload, type ConsumerOptions, type FetchOptions, type GetLagOptions, type GroupAssignment, type GroupOptions, type ListCommitsOptions, type ListOffsetsOptions, type Offsets, type OffsetsWithTimestamps } from './types.ts';
+import { type CommitOptions, type ConsumeOptions, type ConsumerGroupJoinPayload, type ConsumerGroupLeavePayload, type ConsumerGroupRebalancePayload, type ConsumerHeartbeatErrorPayload, type ConsumerHeartbeatPayload, type ConsumerHeartbeatStalledPayload, type ConsumerOptions, type FetchOptions, type GetLagOptions, type GroupAssignment, type GroupOptions, type ListCommitsOptions, type ListOffsetsOptions, type Offsets, type OffsetsWithTimestamps } from './types.ts';
 export interface ConsumerEvents extends BaseEvents {
     'consumer:group:join': (payload: ConsumerGroupJoinPayload) => void;
     'consumer:group:leave': (payload: ConsumerGroupLeavePayload) => void;
@@ -16,6 +16,7 @@ export interface ConsumerEvents extends BaseEvents {
     'consumer:heartbeat:cancel': (payload: ConsumerHeartbeatPayload) => void;
     'consumer:heartbeat:end': (payload?: ConsumerHeartbeatPayload) => void;
     'consumer:heartbeat:error': (payload: ConsumerHeartbeatErrorPayload) => void;
+    'consumer:heartbeat:stalled': (payload: ConsumerHeartbeatStalledPayload) => void;
     'consumer:lag': (lag: Offsets) => void;
     'consumer:lag:error': (error: Error) => void;
 }

package/dist/clients/consumer/consumer.js

@@ -32,6 +32,10 @@ export class Consumer extends Base {
     #heartbeatInterval;
     #lastHeartbeatIntervalMs;
     #lastHeartbeat;
+    #heartbeatStallTimer;
+    #heartbeatStallStart;
+    #heartbeatStalled;
+    #heartbeatStallError;
     #useConsumerGroupProtocol;
     #memberEpoch;
     #groupRemoteAssignor;
@@ -77,6 +81,10 @@ export class Consumer extends Base {
         this.#heartbeatInterval = null;
         this.#lastHeartbeatIntervalMs = 0;
         this.#lastHeartbeat = null;
+        this.#heartbeatStallTimer = null;
+        this.#heartbeatStallStart = null;
+        this.#heartbeatStalled = false;
+        this.#heartbeatStallError = undefined;
         this.#streams = new Set();
         this.#lagMonitoring = null;
         this.#memberEpoch = 0;
@@ -121,6 +129,7 @@ export class Consumer extends Base {
         }
         this[kClosed] = true;
         clearTimeout(this.#lagMonitoring);
+        this.#resetHeartbeatStall();
         let closer;
         if (this.#useConsumerGroupProtocol) {
             closer = this.#leaveGroupConsumerProtocol.bind(this);
@@ -353,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);
     }
@@ -424,6 +440,7 @@ export class Consumer extends Base {
             return callback[kCallbackPromise];
         }
         this.#membershipActive = false;
+        this.#resetHeartbeatStall();
         this.#leaveGroupClassicProtocol(force, error => {
             if (error) {
                 this.#membershipActive = true;
@@ -486,12 +503,15 @@ export class Consumer extends Base {
     }
     #fetch(options, callback) {
         const isolationLevel = options.isolationLevel ?? this[kOptions].isolationLevel;
+        let refreshMetadata = false;
         this[kPerformWithRetry]('fetch', retryCallback => {
-            this[kMetadata]({ topics: this.topics.current }, (error, metadata) => {
+            this[kMetadata]({ topics: this.topics.current, forceUpdate: refreshMetadata }, (error, metadata) => {
                 if (error) {
+                    refreshMetadata = NetworkError.isRetryable(error);
                     retryCallback(error);
                     return;
                 }
+                refreshMetadata = false;
                 const topicIds = this.#topicIdsById(metadata);
                 const node = this.#fetchNodeForRequest(metadata, options.node, options.topics, topicIds, Date.now());
                 const broker = metadata.brokers.get(node);
@@ -502,6 +522,7 @@ export class Consumer extends Base {
                 const pool = options.connectionPool ?? this[kConnections];
                 pool.get(broker, (error, connection) => {
                     if (error) {
+                        refreshMetadata = NetworkError.isRetryable(error);
                         this.#clearPreferredReadReplicas(options.topics, topicIds);
                         this.#fetchSessions.delete(node);
                         // When a connection was not available (either interrupted or not available) we
@@ -517,6 +538,7 @@ export class Consumer extends Base {
                     }
                     this[kGetApi]('Fetch', (error, api) => {
                         if (error) {
+                            refreshMetadata = NetworkError.isRetryable(error);
                             retryCallback(error);
                             return;
                         }
@@ -608,6 +630,7 @@ export class Consumer extends Base {
                                 }
                             }
                             if (error) {
+                                refreshMetadata = NetworkError.isRetryable(error);
                                 this.#clearPreferredReadReplicas(options.topics, topicIds);
                                 if (findErrorBy(error, 'apiId', 'FETCH_SESSION_ID_NOT_FOUND') ||
                                     findErrorBy(error, 'apiId', 'INVALID_FETCH_SESSION_EPOCH') ||
@@ -697,12 +720,12 @@ export class Consumer extends Base {
             callback(error);
         });
     }
-    #listOffsets(withTimestamps, options, callback) {
+    #listOffsets(withTimestamps, options, callback, forceUpdateMetadata = false) {
         let topics = options.topics;
         if (!topics || topics.length === 0) {
             topics = this.topics.current;
         }
-        this[kMetadata]({ topics }, (error, metadata) => {
+        this[kMetadata]({ topics, forceUpdate: forceUpdateMetadata }, (error, metadata) => {
             if (error) {
                 callback(error);
                 return;
@@ -757,6 +780,11 @@ export class Consumer extends Base {
                 }, concurrentCallback, 0);
             }, (error, responses) => {
                 if (error) {
+                    if (!forceUpdateMetadata && NetworkError.isRetryable(error)) {
+                        this.clearMetadata();
+                        this.#listOffsets(withTimestamps, options, callback, true);
+                        return;
+                    }
                     callback(this.#handleError(error));
                     return;
                 }
@@ -881,6 +909,7 @@ export class Consumer extends Base {
                 return;
             }
             this.emitWithDebug('consumer:heartbeat', 'start', eventPayload);
+            this.#trackHeartbeatStall(options);
             this[kGetApi]('Heartbeat', (error, api) => {
                 if (error) {
                     groupCallback(error);
@@ -897,21 +926,43 @@ export class Consumer extends Base {
             if (error) {
                 this.#cancelHeartbeat();
                 if (this.#getRejoinError(error)) {
+                    // A rejoin can legitimately block up to rebalanceTimeout:
+                    // - extend the stall window by that bound rather than pausing it
+                    // - a rejoin that never completes still surfaces as a stall
+                    this.#resetHeartbeatStall();
+                    this.#trackHeartbeatStall(options, error, options.rebalanceTimeout + this.#heartbeatStallTimeoutFor(options));
                     this[kPerformWithRetry]('rejoinGroup', retryCallback => {
                         this.#joinGroup(options, retryCallback);
                     }, error => {
                         if (error) {
                             this.emitWithDebug(null, 'error', error);
+                            if (!this.#heartbeatStalled) {
+                                // No more heartbeats will be scheduled: restart the stall window without
+                                // the rejoin grace, keeping the triggering heartbeat error as lastError.
+                                const heartbeatError = this.#heartbeatStallError;
+                                this.#resetHeartbeatStall();
+                                this.#trackHeartbeatStall(options, heartbeatError);
+                            }
+                        }
+                        else {
+                            // Rejoin succeeded: drop the extended window; the next heartbeat opens the normal one.
+                            this.#resetHeartbeatStall();
                         }
                         this.emitWithDebug('consumer', 'rejoin');
                     }, 0);
                     return;
                 }
+                // The error was not group related, so we schedule another heartbeat.
+                // Do this before notifying listeners so they can still cancel it.
+                this.#heartbeatInterval = setTimeout(() => {
+                    this.#heartbeat(options);
+                }, options.heartbeatInterval);
                 this.emitWithDebug('consumer:heartbeat', 'error', { ...eventPayload, error });
-                // Note that here we purposely do not return, since it was not a group related problem we schedule another heartbeat
+                this.#trackHeartbeatStall(options, error);
             }
             else {
                 this.#lastHeartbeat = new Date();
+                this.#resetHeartbeatStall();
                 this.emitWithDebug('consumer:heartbeat', 'end', eventPayload);
             }
             this.#heartbeatInterval?.refresh();
@@ -921,6 +972,47 @@ export class Consumer extends Base {
         clearTimeout(this.#heartbeatInterval);
         this.#heartbeatInterval = null;
     }
+    #heartbeatStallTimeoutFor(options) {
+        return (options.heartbeatStallTimeout ??
+            this[kOptions].heartbeatStallTimeout ??
+            options.rebalanceTimeout ??
+            this[kOptions].rebalanceTimeout ??
+            defaultConsumerOptions.rebalanceTimeout);
+    }
+    // Opens the stall window on the first heartbeat attempt after the last success.
+    // The window survives retries and only #resetHeartbeatStall closes it.
+    #trackHeartbeatStall(options, error, timeout) {
+        if (error) {
+            this.#heartbeatStallError = error;
+        }
+        if (this.#heartbeatStalled || this.#heartbeatStallTimer) {
+            return;
+        }
+        timeout ??= this.#heartbeatStallTimeoutFor(options);
+        this.#heartbeatStallStart = Date.now();
+        this.#heartbeatStallTimer = setTimeout(() => {
+            this.#heartbeatStallTimer = null;
+            // Emit once per stall episode. The next successful heartbeat re-arms the tracking.
+            this.#heartbeatStalled = true;
+            if (this[kClosed] || !this.#membershipActive) {
+                return;
+            }
+            this.emitWithDebug('consumer:heartbeat', 'stalled', {
+                lastError: this.#heartbeatStallError,
+                lastHeartbeat: this.#lastHeartbeat,
+                stalledFor: Date.now() - this.#heartbeatStallStart
+            });
+        }, timeout);
+    }
+    #resetHeartbeatStall() {
+        if (this.#heartbeatStallTimer) {
+            clearTimeout(this.#heartbeatStallTimer);
+            this.#heartbeatStallTimer = null;
+        }
+        this.#heartbeatStallStart = null;
+        this.#heartbeatStalled = false;
+        this.#heartbeatStallError = undefined;
+    }
     #consumerGroupHeartbeat(options, callback) {
         options.rebalanceTimeout ??= this[kOptions].rebalanceTimeout;
         consumerHeartbeatChannel.traceCallback(this.#performConsumerGroupHeartbeat, 1, createDiagnosticContext({ client: this, operation: 'consumerGroupHeartbeat' }), this, options, callback);
@@ -928,6 +1020,7 @@ export class Consumer extends Base {
     #performConsumerGroupHeartbeat(options, callback) {
         this.#performGroupOperation('consumerGroupHeartbeat', (connection, groupCallback) => {
             this.emitWithDebug('consumer:heartbeat', 'start');
+            this.#trackHeartbeatStall(options);
             this[kGetApi]('ConsumerGroupHeartbeat', (error, api) => {
                 if (error) {
                     groupCallback(error);
@@ -938,6 +1031,7 @@ export class Consumer extends Base {
             });
         }, (error, response) => {
             if (this[kClosed]) {
+                this.#resetHeartbeatStall();
                 this.emitWithDebug('consumer:heartbeat', 'end');
                 callback(null);
                 return;
@@ -945,13 +1039,19 @@ export class Consumer extends Base {
             if (error) {
                 this.#cancelHeartbeat();
                 this.emitWithDebug('consumer:heartbeat', 'error', { error });
+                this.#trackHeartbeatStall(options, error);
                 const fenced = error.response?.errorCode === protocolErrors.FENCED_MEMBER_EPOCH.code;
                 if (fenced) {
                     this.#assignments = [];
                     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;
                 }
@@ -962,6 +1062,7 @@ export class Consumer extends Base {
                 return;
             }
             this.#lastHeartbeat = new Date();
+            this.#resetHeartbeatStall();
             this.#memberEpoch = response.memberEpoch;
             if (response.memberId) {
                 const changed = this.memberId !== response.memberId;
@@ -1011,6 +1112,7 @@ export class Consumer extends Base {
         if (toRevoke.length === 0) {
             return;
         }
+        this.emitWithDebug('consumer', 'group:rebalance', { groupId: this.groupId });
         for (const stream of this.#streams) {
             stream.pause();
             stream[kAutocommit]();