@platformatic/kafka 2.0.1 → 2.2.0

package/dist/clients/consumer/options.js

@@ -8,6 +8,7 @@ export const groupOptionsProperties = {
     sessionTimeout: { type: 'number', minimum: 0 },
     rebalanceTimeout: { type: 'number', minimum: 0 },
     heartbeatInterval: { type: 'number', minimum: 0 },
+    heartbeatStallTimeout: { type: 'number', minimum: 0 },
     groupProtocol: { type: 'string', enum: allowedGroupProtocols },
     groupRemoteAssignor: { type: 'string' },
     protocols: {
@@ -25,6 +26,7 @@ export const groupOptionsProperties = {
             }
         }
     },
+    protocolsMetadata: { function: true },
     partitionAssigner: { function: true }
 };
 export const groupOptionsAdditionalValidations = {
@@ -89,6 +91,7 @@ export const consumeOptionsSchema = {
             }
         },
         onCorruptedMessage: { function: true },
+        onDeserializationError: { function: true },
         ...groupOptionsProperties,
         ...consumeOptionsProperties
     },

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

@@ -1,10 +1,11 @@
+import { type Callback } from '../../apis/definitions.ts';
 import { type FetchRequestTopic } from '../../apis/consumer/fetch-v17.ts';
 import { type GroupProtocols } from '../../apis/enumerations.ts';
 import { type ConnectionPool } from '../../network/connection-pool.ts';
 import { type KafkaRecord, type Message } from '../../protocol/records.ts';
 import { type SchemaRegistry } from '../../registries/abstract.ts';
 import { type BaseOptions, type ClusterMetadata, type TopicWithPartitionAndOffset } from '../base/types.ts';
-import { type BeforeDeserializationHook, type Deserializers } from '../serde.ts';
+import { type BeforeDeserializationHook, type BeforeHookPayloadType, type Deserializers } from '../serde.ts';
 export interface GroupProtocolSubscription {
     name: string;
     version: number;
@@ -27,8 +28,37 @@ export type OffsetsWithTimestamps = Map<string, Map<number, {
     offset: bigint;
     timestamp: bigint;
 }>>;
-export type CorruptedMessageHandler = (record: KafkaRecord, topic: string, partition: number, firstTimestamp: bigint, firstOffset: bigint, commit: Message['commit']) => boolean;
+export interface PreferredReadReplica {
+    node: number;
+    expiresAt: number;
+}
+export declare const DeserializationErrorActions: {
+    readonly FAIL: "fail";
+    readonly SKIP: "skip";
+    readonly CONTINUE: "continue";
+};
+export type DeserializationErrorAction = (typeof DeserializationErrorActions)[keyof typeof DeserializationErrorActions];
+export interface DeserializationErrorContext {
+    error: unknown;
+    payloadType: BeforeHookPayloadType;
+    record: KafkaRecord;
+    topic: string;
+    partition: number;
+    offset: bigint;
+    timestamp: bigint;
+    commit: Message['commit'];
+}
+export interface MessageDeserializationError {
+    error: unknown;
+    payloadType: BeforeHookPayloadType;
+}
+export type DeserializationErrorHandler = (context: DeserializationErrorContext) => DeserializationErrorAction;
+/**
+ * @deprecated Use `DeserializationErrorHandler` instead.
+ */
+export type CorruptedMessageHandler = (record: KafkaRecord, topic: string, partition: number, firstTimestamp: bigint, firstOffset: bigint, commit: Message['commit'], error: unknown) => boolean;
 export type GroupPartitionsAssigner = (current: string, members: Map<string, ExtendedGroupProtocolSubscription>, topics: Set<string>, metadata: ClusterMetadata) => GroupPartitionsAssignments[];
+export type GroupProtocolsMetadataCallback = (protocols: GroupProtocolSubscription[], topics: string[], metadata: ClusterMetadata, callback: Callback<Buffer>) => Buffer | Promise<Buffer> | undefined;
 export declare const MessagesStreamModes: {
     readonly LATEST: "latest";
     readonly EARLIEST: "earliest";
@@ -52,7 +82,9 @@ export interface GroupOptions {
     sessionTimeout?: number;
     rebalanceTimeout?: number;
     heartbeatInterval?: number;
+    heartbeatStallTimeout?: number;
     protocols?: GroupProtocolSubscription[];
+    protocolsMetadata?: GroupProtocolsMetadataCallback;
     partitionAssigner?: GroupPartitionsAssigner;
     assignmentUserData?: Buffer;
 }
@@ -61,6 +93,7 @@ export interface ConsumerGroupOptions {
     groupInstanceId?: string;
     groupRemoteAssignor?: string;
     rebalanceTimeout?: number;
+    heartbeatStallTimeout?: number;
     assignmentUserData?: Buffer;
 }
 export interface ConsumeBaseOptions<Key, Value, HeaderKey, HeaderValue> {
@@ -82,6 +115,10 @@ export interface StreamOptions {
     fallbackMode?: MessagesStreamFallbackModeValue;
     maxFetches?: number;
     offsets?: TopicWithPartitionAndOffset[];
+    onDeserializationError?: DeserializationErrorHandler;
+    /**
+     * @deprecated Use `onDeserializationError` instead.
+     */
     onCorruptedMessage?: CorruptedMessageHandler;
 }
 export type ConsumeOptions<Key, Value, HeaderKey, HeaderValue> = StreamOptions & ConsumeBaseOptions<Key, Value, HeaderKey, HeaderValue> & GroupOptions;
@@ -134,3 +171,8 @@ export interface ConsumerHeartbeatPayload {
 export interface ConsumerHeartbeatErrorPayload extends ConsumerHeartbeatPayload {
     error: Error;
 }
+export interface ConsumerHeartbeatStalledPayload {
+    lastError?: Error;
+    lastHeartbeat: Date | null;
+    stalledFor: number;
+}

package/dist/clients/consumer/types.js

@@ -1,3 +1,8 @@
+export const DeserializationErrorActions = {
+    FAIL: 'fail',
+    SKIP: 'skip',
+    CONTINUE: 'continue'
+};
 export const MessagesStreamModes = {
     LATEST: 'latest',
     EARLIEST: 'earliest',

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

@@ -0,0 +1,2 @@
+export declare function partitionKey(topic: string, partition: number): string;
+export declare function nextFetchEpoch(epoch: number): number;

package/dist/clients/consumer/utils.js

@@ -0,0 +1,9 @@
+export function partitionKey(topic, partition) {
+    return `${topic}:${partition}`;
+}
+export function nextFetchEpoch(epoch) {
+    if (epoch < 0) {
+        return 0;
+    }
+    return epoch >= 0x7fffffff ? 1 : epoch + 1;
+}

package/dist/clients/producer/producer.d.ts

@@ -13,7 +13,7 @@ export declare class Producer<Key = Buffer, Value = Buffer, HeaderKey = Buffer,
     get producerId(): bigint | undefined;
     get producerEpoch(): number | undefined;
     get transaction(): Transaction<Key, Value, HeaderKey, HeaderValue> | undefined;
-    get coordinatorId(): number;
+    get coordinatorId(): number | undefined;
     get streamsCount(): number;
     close(force: boolean | CallbackWithPromise<void>, callback?: CallbackWithPromise<void>): void;
     close(force?: boolean): Promise<void>;

package/dist/clients/producer/producer.js

@@ -2,7 +2,7 @@ import { randomUUID } from 'crypto';
 import { createPromisifiedCallback, kCallbackPromise, runConcurrentCallbacks } from "../../apis/callbacks.js";
 import { FindCoordinatorKeyTypes, ProduceAcks } from "../../apis/enumerations.js";
 import { createDiagnosticContext, producerInitIdempotentChannel, producerSendsChannel, producerTransactionsChannel } from "../../diagnostic.js";
-import { GenericError, UserError } from "../../errors.js";
+import { findErrorBy, NetworkError, UserError } from "../../errors.js";
 import { runAsyncSeries } from "../../registries/abstract.js";
 import { kInstance, kTransaction, kTransactionAddOffsets, kTransactionAddPartitions, kTransactionCancel, kTransactionCommitOffset, kTransactionEnd, kTransactionFindCoordinator, kTransactionPrepare } from "../../symbols.js";
 import { emitExperimentalApiWarning, NumericMap } from "../../utils.js";
@@ -342,7 +342,7 @@ export class Producer extends Base {
         }
         const transactionalId = this.#transaction.id;
         this[kPerformDeduplicated]('findCoordinator', deduplicateCallback => {
-            this[kPerformWithRetry]('findCoordinator', retryCallback => {
+            this[kPerformWithRetry]('findCoordinator', (retryCallback, attempt) => {
                 this[kGetBootstrapConnection]((error, connection) => {
                     if (error) {
                         retryCallback(error);
@@ -353,9 +353,14 @@ 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) => {
                 if (error) {
                     deduplicateCallback(error);
@@ -383,12 +388,12 @@ export class Producer extends Base {
             this[kPerformWithRetry]('addPartitionsToTransaction', retryCallback => {
                 this.#getCoordinatorConnection((error, connection) => {
                     if (error) {
-                        retryCallback(error);
+                        retryCallback(this.#handleError(error));
                         return;
                     }
                     this[kGetApi]('AddPartitionsToTxn', (error, api) => {
                         if (error) {
-                            retryCallback(error);
+                            retryCallback(this.#handleError(error));
                             return;
                         }
                         api(connection, [
@@ -401,7 +406,7 @@ export class Producer extends Base {
                             }
                         ], error => {
                             if (error) {
-                                retryCallback(error);
+                                retryCallback(this.#handleError(error));
                                 return;
                             }
                             retryCallback(null);
@@ -420,17 +425,17 @@ export class Producer extends Base {
             this[kPerformWithRetry]('addOffsetsToTransaction', retryCallback => {
                 this.#getCoordinatorConnection((error, connection) => {
                     if (error) {
-                        retryCallback(error);
+                        retryCallback(this.#handleError(error));
                         return;
                     }
                     this[kGetApi]('AddOffsetsToTxn', (error, api) => {
                         if (error) {
-                            retryCallback(error);
+                            retryCallback(this.#handleError(error));
                             return;
                         }
                         api(connection, this.#transaction.id, this.#producerInfo.producerId, this.#producerInfo.producerEpoch, groupId, error => {
                             if (error) {
-                                retryCallback(error);
+                                retryCallback(this.#handleError(error));
                                 return;
                             }
                             retryCallback(null);
@@ -498,18 +503,18 @@ export class Producer extends Base {
             this[kPerformWithRetry]('endTransaction', retryCallback => {
                 this.#getCoordinatorConnection((error, connection) => {
                     if (error) {
-                        retryCallback(error);
+                        retryCallback(this.#handleError(error));
                         return;
                     }
                     this[kGetApi]('EndTxn', (error, api) => {
                         if (error) {
-                            retryCallback(error);
+                            retryCallback(this.#handleError(error));
                             return;
                         }
                         api(connection, this.#transaction.id, this.#producerInfo.producerId, this.#producerInfo.producerEpoch, commit, error => {
                             if (error) {
                                 this.#handleFencingError(error);
-                                retryCallback(error);
+                                retryCallback(this.#handleError(error));
                                 return;
                             }
                             this.#transaction = undefined;
@@ -531,11 +536,8 @@ export class Producer extends Base {
     #initIdempotentProducer(options, callback) {
         const transactionalId = this.#transaction?.id;
         this[kPerformDeduplicated]('initProducerId', deduplicateCallback => {
-            this[kPerformWithRetry]('initProducerId', retryCallback => {
-                const connector = transactionalId
-                    ? this.#getCoordinatorConnection.bind(this)
-                    : this[kGetBootstrapConnection].bind(this);
-                connector((error, connection) => {
+            this[kPerformWithRetry]('initProducerId', (retryCallback, attempt) => {
+                const onConnection = (error, connection) => {
                     if (error) {
                         retryCallback(error);
                         return;
@@ -545,13 +547,24 @@ export class Producer extends Base {
                             retryCallback(error);
                             return;
                         }
-                        api(connection, transactionalId, this[kOptions].timeout, options.producerId ?? this[kOptions].producerId ?? 0n, options.producerEpoch ?? this[kOptions].producerEpoch ?? 0, retryCallback);
+                        api(connection, transactionalId, this[kOptions].timeout, options.producerId ?? this[kOptions].producerId ?? 0n, options.producerEpoch ?? this[kOptions].producerEpoch ?? 0, (error, response) => {
+                            retryCallback(this.#handleError(error), response);
+                        });
                     });
-                });
+                };
+                // The transactional path fails over inside #getCoordinatorConnection (via
+                // #findCoordinator -> kGetBootstrapConnection). The idempotent path must thread
+                // `attempt` so kGetBootstrapConnection rotates past a reachable-but-hung broker.
+                if (transactionalId) {
+                    this.#getCoordinatorConnection(onConnection);
+                }
+                else {
+                    this[kGetBootstrapConnection](onConnection, attempt);
+                }
             }, (error, response) => {
                 if (error) {
                     this.#handleFencingError(error);
-                    deduplicateCallback(error);
+                    deduplicateCallback(this.#handleError(error));
                     return;
                 }
                 this.#producerInfo = {
@@ -683,9 +696,16 @@ export class Producer extends Base {
             }
             // Track nodes so that we can get their ID for delayed write reporting
             const nodes = [];
+            const sequenceSnapshot = produceOptions.sequences ? new NumericMap() : undefined;
+            if (sequenceSnapshot) {
+                for (const [partitionKey, messagesCount] of messagesPerPartition) {
+                    sequenceSnapshot.set(partitionKey, this.#sequences.postIncrement(partitionKey, messagesCount, 0));
+                }
+                produceOptions = { ...produceOptions, sequences: sequenceSnapshot };
+            }
             runConcurrentCallbacks('Producing messages failed.', messagesByDestination, ([destination, destinationMessages], concurrentCallback) => {
                 nodes.push(destination);
-                this.#performSingleDestinationSend(topics, destinationMessages, this[kOptions].timeout, sendOptions.acks, sendOptions.autocreateTopics, sendOptions.repeatOnStaleMetadata, produceOptions, concurrentCallback);
+                this.#performSingleDestinationSend(topics, destinationMessages, this[kOptions].timeout, sendOptions.acks, sendOptions.autocreateTopics, sendOptions.repeatOnStaleMetadata, produceOptions, true, concurrentCallback);
             }, (error, apiResults) => {
                 this.#metricsProducedMessages?.inc(messages.length);
                 const results = {};
@@ -708,14 +728,16 @@ export class Producer extends Base {
                                     partition: partitionResponse.index,
                                     offset: partitionResponse.baseOffset
                                 });
-                                const partitionKey = `${name}:${partitionResponse.index}`;
-                                this.#sequences.postIncrement(partitionKey, messagesPerPartition.get(partitionKey), 0);
                             }
                         }
                         results.offsets = topics;
                     }
                 }
                 if (error) {
+                    if (sendOptions.idempotent && !this.#transaction) {
+                        this.#producerInfo = undefined;
+                        this.#sequences.clear();
+                    }
                     ;
                     error.produced = results;
                     callback(error);
@@ -726,80 +748,138 @@ export class Producer extends Base {
             });
         });
     }
-    #performSingleDestinationSend(topics, messages, timeout, acks, autocreateTopics, repeatOnStaleMetadata, produceOptions, callback) {
-        // Get the metadata with the topic/partitions informations
-        this[kMetadata]({ topics, autocreateTopics }, (error, metadata) => {
-            if (error) {
-                callback(error);
-                return;
-            }
-            const { topic, partition } = messages[0];
-            const leader = metadata.topics.get(topic).partitions[partition].leader;
-            this[kPerformWithRetry]('produce', retryCallback => {
+    #performSingleDestinationSend(topics, messages, timeout, acks, autocreateTopics, repeatOnStaleMetadata, produceOptions, recoverOnProducerStateLoss, callback) {
+        const { topic, partition } = messages[0];
+        let refreshMetadata = false;
+        this[kPerformWithRetry]('produce', retryCallback => {
+            this[kMetadata]({ topics, autocreateTopics, forceUpdate: refreshMetadata }, (error, metadata) => {
+                if (error) {
+                    refreshMetadata = NetworkError.isRetryable(error);
+                    retryCallback(error);
+                    return;
+                }
+                refreshMetadata = false;
+                const leader = metadata.topics.get(topic).partitions[partition].leader;
                 this[kGetConnection](metadata.brokers.get(leader), (error, connection) => {
                     if (error) {
+                        refreshMetadata = NetworkError.isRetryable(error);
                         retryCallback(error);
                         return;
                     }
                     this[kGetApi]('Produce', (error, api) => {
                         if (error) {
+                            refreshMetadata = NetworkError.isRetryable(error);
                             retryCallback(error);
                             return;
                         }
-                        api(connection, acks, timeout, messages, produceOptions, retryCallback);
+                        api(connection, acks, timeout, messages, produceOptions, (error, response) => {
+                            refreshMetadata = NetworkError.isRetryable(error);
+                            retryCallback(error, response);
+                        });
                     });
                 });
-            }, (error, results) => {
-                if (error) {
-                    // If the last error was due to stale metadata, we retry the operation with this set of messages
-                    // since the partition is already set, it should attempt on the new destination
-                    /* c8 ignore next 3 - Hard to test */
-                    const kafkaError = GenericError.isGenericError(error)
-                        ? error
-                        : null;
-                    const hasStaleMetadata = kafkaError?.findBy('hasStaleMetadata', true);
-                    if (hasStaleMetadata && repeatOnStaleMetadata) {
-                        this.clearMetadata();
-                        this.#performSingleDestinationSend(topics, messages, timeout, acks, autocreateTopics, false, produceOptions, callback);
-                        return;
-                    }
-                    callback(error, results);
+            });
+        }, (error, results) => {
+            if (error) {
+                // If the last error was due to stale metadata, we retry the operation with this set of messages
+                // since the partition is already set, it should attempt on the new destination
+                /* c8 ignore next - Hard to test */
+                const hasStaleMetadata = findErrorBy(error, 'hasStaleMetadata', true);
+                if (hasStaleMetadata && repeatOnStaleMetadata) {
+                    this.clearMetadata();
+                    this.#performSingleDestinationSend(topics, messages, timeout, acks, autocreateTopics, false, produceOptions, recoverOnProducerStateLoss, callback);
                     return;
                 }
-                callback(error, results);
-            }, 0, [], error => {
-                /* c8 ignore next 3 - Hard to test */
-                if (!repeatOnStaleMetadata || !GenericError.isGenericError(error)) {
-                    return false;
+                if (recoverOnProducerStateLoss && !this.#transaction && this.#isProducerStateLost(error)) {
+                    this.#recoverIdempotentProducer(messages, produceOptions, (error, recoveredProduceOptions) => {
+                        if (error) {
+                            callback(error);
+                            return;
+                        }
+                        this.#performSingleDestinationSend(topics, messages, timeout, acks, autocreateTopics, repeatOnStaleMetadata, recoveredProduceOptions, false, callback);
+                    });
+                    return;
                 }
-                return !!error.findBy('hasStaleMetadata', true);
+                callback(error, results);
+                return;
+            }
+            callback(error, results);
+        }, 0, [], error => {
+            /* c8 ignore next 3 - Hard to test */
+            if (!repeatOnStaleMetadata) {
+                return false;
+            }
+            return !!findErrorBy(error, 'hasStaleMetadata', true);
+        });
+    }
+    #isProducerStateLost(error) {
+        return !!(findErrorBy(error, 'apiId', 'UNKNOWN_PRODUCER_ID') || findErrorBy(error, 'apiId', 'OUT_OF_ORDER_SEQUENCE_NUMBER'));
+    }
+    #recoverIdempotentProducer(messages, produceOptions, callback) {
+        this.#producerInfo = undefined;
+        this.#sequences.clear();
+        this.initIdempotentProducer({}, (error, producerInfo) => {
+            if (error) {
+                callback(error);
+                return;
+            }
+            const sequences = new NumericMap();
+            const messagesPerPartition = new NumericMap();
+            for (const { topic, partition } of messages) {
+                messagesPerPartition.postIncrement(`${topic}:${partition}`, 1, 0);
+            }
+            for (const [partitionKey, messagesCount] of messagesPerPartition) {
+                sequences.set(partitionKey, this.#sequences.postIncrement(partitionKey, messagesCount, 0));
+            }
+            callback(null, {
+                ...produceOptions,
+                producerId: producerInfo.producerId,
+                producerEpoch: producerInfo.producerEpoch,
+                sequences
             });
         });
     }
     #getCoordinatorConnection(callback) {
+        if (this.#coordinatorId === undefined) {
+            this[kTransactionFindCoordinator](error => {
+                if (error) {
+                    callback(error);
+                    return;
+                }
+                this.#getCoordinatorConnection(callback);
+            });
+            return;
+        }
         // Get a connection to the coordinator
         this[kMetadata]({}, (error, metadata) => {
             if (error) {
                 callback(error);
                 return;
             }
-            this[kPerformWithRetry]('getCoordinatorConnection', retryCallback => {
-                this[kGetConnection](metadata.brokers.get(this.#coordinatorId), (error, connection) => {
-                    if (error) {
-                        retryCallback(error);
-                        return;
-                    }
-                    retryCallback(null, connection);
-                });
-            }, callback);
+            this[kGetConnection](metadata.brokers.get(this.#coordinatorId), (error, connection) => {
+                if (error) {
+                    callback(this.#handleError(error));
+                    return;
+                }
+                callback(null, connection);
+            });
         });
     }
     #handleFencingError(error) {
-        if (error.findBy?.('producerFenced', true)) {
+        if (findErrorBy(error, 'producerFenced', true)) {
             this.#producerInfo = undefined;
             this.#transaction = undefined;
         }
     }
+    #handleError(error) {
+        if (findErrorBy(error, 'code', 'PLT_KFK_NETWORK') ||
+            findErrorBy(error, 'apiId', 'COORDINATOR_LOAD_IN_PROGRESS') ||
+            findErrorBy(error, 'apiId', 'COORDINATOR_NOT_AVAILABLE') ||
+            findErrorBy(error, 'apiId', 'NOT_COORDINATOR')) {
+            this.#coordinatorId = undefined;
+        }
+        return error;
+    }
     #beforeSerialization(hook, options, callback) {
         // Create the pre-serialization requests
         const requests = [];

package/dist/clients/serde.d.ts

@@ -17,7 +17,7 @@ export interface Deserializers<Key, Value, HeaderKey, HeaderValue> {
     headerValue: Deserializer<HeaderValue>;
 }
 export type BeforeHookPayloadType = 'key' | 'value' | 'headerKey' | 'headerValue';
-export type BeforeDeserializationHook = (payload: Buffer, type: BeforeHookPayloadType, message: MessageToConsume, callback: Callback<void>) => void | Promise<void>;
+export type BeforeDeserializationHook = (payload: Buffer | null, type: BeforeHookPayloadType, message: MessageToConsume, callback: Callback<void>) => void | Promise<void>;
 export type BeforeSerializationHook<Key, Value, HeaderKey, HeaderValue> = (payload: unknown, type: BeforeHookPayloadType, message: MessageToProduce<Key, Value, HeaderKey, HeaderValue>, callback: Callback<void>) => void | Promise<void>;
 export declare function stringSerializer(data?: string): Buffer | undefined;
 export declare function stringDeserializer(data?: string | Buffer): string | undefined;

package/dist/errors.d.ts

@@ -14,6 +14,7 @@ export declare class GenericError extends Error {
     static isGenericError(error: Error): error is GenericError | MultipleErrors;
     constructor(code: ErrorCode, message: string, { cause, ...rest }?: ErrorProperties);
     findBy<ErrorType extends GenericError = GenericError>(property: string, value: unknown): ErrorType | null;
+    toString(): string;
 }
 export declare class MultipleErrors extends AggregateError {
     code: string;
@@ -25,7 +26,9 @@ export declare class MultipleErrors extends AggregateError {
     static isMultipleErrors(error: Error): error is MultipleErrors;
     constructor(message: string, errors: Error[], { cause, ...rest }?: ErrorProperties);
     findBy<ErrorType extends GenericError | MultipleErrors = MultipleErrors>(property: string, value: unknown): ErrorType | null;
+    toString(): string;
 }
+export declare function findErrorBy<ErrorType extends GenericError = GenericError>(error: Error | null | undefined, property: string, value: unknown): ErrorType | null;
 export * from './protocol/errors.ts';
 export declare class AuthenticationError extends GenericError {
     static code: ErrorCode;
@@ -33,6 +36,7 @@ export declare class AuthenticationError extends GenericError {
 }
 export declare class NetworkError extends GenericError {
     static code: ErrorCode;
+    static isRetryable(error: Error | null | undefined): boolean;
     constructor(message: string, properties?: ErrorProperties);
 }
 export declare class ProtocolError extends GenericError {

package/dist/errors.js

@@ -45,6 +45,9 @@ export class GenericError extends Error {
         }
         return null;
     }
+    toString() {
+        return `Error ${this.code}: ${this.message}`;
+    }
 }
 export class MultipleErrors extends AggregateError {
     code;
@@ -91,6 +94,21 @@ export class MultipleErrors extends AggregateError {
         }
         return null;
     }
+    toString() {
+        return `Error ${this.code}: ${this.message} (caused by: ${this.errors.map(error => error.toString()).join(', ')})`;
+    }
+}
+// findBy only exists on the library's own error classes, but errors also come from user code, Node
+// internals and third parties. This brand checks first, so classification is total: an error that
+// cannot be classified reports no match instead of throwing. Use it for any error whose origin is
+// not statically known.
+export function findErrorBy(error, property, value) {
+    if (!error || !GenericError.isGenericError(error)) {
+        return null;
+    }
+    // GenericError and MultipleErrors declare findBy with different generic defaults, so the union is
+    // not callable. The brand check above guarantees the call is safe either way.
+    return error.findBy(property, value);
 }
 export * from "./protocol/errors.js";
 export class AuthenticationError extends GenericError {
@@ -101,6 +119,10 @@ export class AuthenticationError extends GenericError {
 }
 export class NetworkError extends GenericError {
     static code = 'PLT_KFK_NETWORK';
+    static isRetryable(error) {
+        const networkError = findErrorBy(error, 'code', NetworkError.code);
+        return networkError?.canRetry === true;
+    }
     constructor(message, properties = {}) {
         super(NetworkError.code, message, { canRetry: true, ...properties });
     }

package/dist/network/connection-pool.js

@@ -1,6 +1,6 @@
 import { createPromisifiedCallback, kCallbackPromise, runConcurrentCallbacks } from "../apis/callbacks.js";
 import { connectionsPoolGetsChannel, createDiagnosticContext, notifyCreation } from "../diagnostic.js";
-import { MultipleErrors } from "../errors.js";
+import { MultipleErrors, NetworkError } from "../errors.js";
 import { TypedEventEmitter } from "../events.js";
 import { Connection, ConnectionStatuses } from "./connection.js";
 let currentInstance = 0;
@@ -92,7 +92,17 @@ export class ConnectionPool extends TypedEventEmitter {
     }
     #get(broker, callback) {
         if (this.#closed) {
-            callback(new Error('Connection pool is closed.'));
+            // A closed pool never reopens, so this must not be retried. It also has to be a library error:
+            // clients classify errors via findBy, which only exists on GenericError subclasses.
+            callback(new NetworkError('Connection pool is closed.', { canRetry: false, closed: true, broker }));
+            return;
+        }
+        if (broker == null || broker.host == null || broker.port == null) {
+            callback(new NetworkError('Cannot get a connection: the broker is not available in the current cluster metadata.', {
+                canRetry: true,
+                hasStaleMetadata: true,
+                broker
+            }));
             return;
         }
         const key = `${broker.host}:${broker.port}`;