@drarzter/kafka-client 0.6.7 → 0.6.9

package/README.md

@@ -33,6 +33,9 @@ Type-safe Kafka client for Node.js. Framework-agnostic core with a first-class N
 - [Deduplication (Lamport Clock)](#deduplication-lamport-clock)
 - [Retry topic chain](#retry-topic-chain)
 - [stopConsumer](#stopconsumer)
+- [Pause and resume](#pause-and-resume)
+- [Reset consumer offsets](#reset-consumer-offsets)
+- [DLQ replay](#dlq-replay)
 - [Graceful shutdown](#graceful-shutdown)
 - [Consumer handles](#consumer-handles)
 - [onMessageLost](#onmessagelost)
@@ -776,12 +779,20 @@ const myInstrumentation: KafkaInstrumentation = {
 `KafkaClient` maintains lightweight in-process event counters independently of any instrumentation:
 
 ```typescript
+// Global snapshot — aggregate across all topics
 const snapshot = kafka.getMetrics();
 // { processedCount: number; retryCount: number; dlqCount: number; dedupCount: number }
 
-kafka.resetMetrics(); // reset all counters to zero
+// Per-topic snapshot
+const orderMetrics = kafka.getMetrics('order.created');
+// { processedCount: 5, retryCount: 1, dlqCount: 0, dedupCount: 0 }
+
+kafka.resetMetrics();                // reset all counters
+kafka.resetMetrics('order.created'); // reset only one topic's counters
 ```
 
+Passing a topic name that has not seen any events returns a zero-valued snapshot — it never throws.
+
 Counters are incremented in the same code paths that fire the corresponding hooks — they are always active regardless of whether any instrumentation is configured.
 
 ## Options reference
@@ -1025,7 +1036,7 @@ By default, retry is handled in-process: the consumer sleeps between attempts wh
 
 Benefits over in-process retry:
 
-- **Durable** — retry messages survive a consumer restart; routing between levels and to DLQ is exactly-once via Kafka transactions
+- **Durable** — retry messages survive a consumer restart; all routing (main → retry.1, level N → N+1, retry → DLQ) is exactly-once via Kafka transactions
 - **Non-blocking** — the original consumer is free immediately; each level consumer only pauses its specific partition during the delay window, so other partitions continue processing
 - **Isolated** — each retry level has its own consumer group, so a slow level 3 consumer never blocks a level 1 consumer
 
@@ -1057,9 +1068,9 @@ Each level consumer uses `consumer.pause → sleep(remaining) → consumer.resum
 
 The retry topic messages carry scheduling headers (`x-retry-attempt`, `x-retry-after`, `x-retry-original-topic`, `x-retry-max-retries`) that each level consumer reads automatically — no manual configuration needed.
 
-> **Delivery guarantee:** routing within the retry chain (retry.N → retry.N+1 and retry.N → DLQ) is **exactly-once** — each routing step is wrapped in a Kafka transaction via `sendOffsetsToTransaction`, so the produce and the consumer offset commit happen atomically. A crash at any point rolls back the transaction: the message is redelivered and the routing is retried, with no duplicate in the next level. If the EOS transaction itself fails (broker unavailable), the offset is not committed and the message stays safely in the retry topic until the broker recovers.
+> **Delivery guarantee:** the entire retry chain — including the **main consumer → retry.1** boundary — is **exactly-once**. Every routing step (main → retry.1, retry.N → retry.N+1, retry.N → DLQ) is wrapped in a Kafka transaction via `sendOffsetsToTransaction`: the produce and the consumer offset commit happen atomically. A crash at any point rolls back the transaction: the message is redelivered and the routing is retried, with no duplicate in the next level. If the EOS transaction fails (broker unavailable), the offset stays uncommitted and the message is safely redelivered — it is never lost.
 >
-> The remaining at-least-once window is at the **main consumer → retry.1** boundary: the main consumer uses `autoCommit: true` by default, so if it crashes after routing to `retry.1` but before autoCommit fires, the message may appear twice in `retry.1`. This is the standard Kafka at-least-once trade-off for any consumer using autoCommit. Design handlers to be idempotent if this edge case is unacceptable.
+> The standard Kafka at-least-once guarantee still applies at the handler level: if your handler succeeds but the process crashes before the manual offset commit completes, the message is redelivered to the handler. Design handlers to be idempotent.
 >
 > **Startup validation:** `retryTopics` requires `retry` to be set — an error is thrown at startup if `retry` is missing. When `autoCreateTopics: false`, all `{topic}.retry.N` topics are validated to exist at startup and a clear error lists any missing ones. With `autoCreateTopics: true` the check is skipped — topics are created automatically by the `ensureTopic` path. Supported by both `startConsumer` and `startBatchConsumer`.
 
@@ -1079,6 +1090,75 @@ await kafka.stopConsumer();
 
 `stopConsumer(groupId)` disconnects and removes only that group's consumer, leaving other groups running. Useful when you want to pause processing for a specific topic without restarting the whole client.
 
+## Pause and resume
+
+Temporarily stop delivering messages from specific partitions without disconnecting the consumer:
+
+```typescript
+// Pause partition 0 of 'orders' (default group)
+kafka.pauseConsumer(undefined, [{ topic: 'orders', partitions: [0] }]);
+
+// Resume it later
+kafka.resumeConsumer(undefined, [{ topic: 'orders', partitions: [0] }]);
+
+// Target a specific consumer group, multiple partitions
+kafka.pauseConsumer('payments-group', [{ topic: 'payments', partitions: [0, 1] }]);
+```
+
+The first argument is the consumer group ID — pass `undefined` to target the default group. A warning is logged if the group is not found.
+
+Pausing is non-destructive: the consumer stays connected and Kafka preserves the partition assignment for as long as the group session is alive. Messages accumulate in the topic and are delivered once the consumer resumes. Typical use: apply backpressure when a downstream dependency (e.g. a database) is temporarily overloaded.
+
+## Reset consumer offsets
+
+Seek a consumer group's committed offsets to the beginning or end of a topic:
+
+```typescript
+// Seek to the beginning — re-process all existing messages
+await kafka.resetOffsets(undefined, 'orders', 'earliest');
+
+// Seek to the end — skip existing messages, process only new ones
+await kafka.resetOffsets(undefined, 'orders', 'latest');
+
+// Target a specific consumer group
+await kafka.resetOffsets('payments-group', 'orders', 'earliest');
+```
+
+**Important:** the consumer for the specified group must be stopped before calling `resetOffsets`. An error is thrown if the group is currently running — this prevents the reset from racing with an active offset commit.
+
+## DLQ replay
+
+Re-publish messages from a dead letter queue back to the original topic:
+
+```typescript
+// Re-publish all messages from 'orders.dlq' → 'orders'
+const result = await kafka.replayDlq('orders');
+// { replayed: 42, skipped: 0 }
+```
+
+Options:
+
+| Option | Default | Description |
+| ------ | ------- | ----------- |
+| `targetTopic` | `x-dlq-original-topic` header | Override the destination topic |
+| `dryRun` | `false` | Count messages without sending |
+| `filter` | — | `(headers) => boolean` — skip messages where the callback returns `false` |
+
+```typescript
+// Dry run — see how many messages would be replayed
+const dry = await kafka.replayDlq('orders', { dryRun: true });
+
+// Route to a different topic
+const result = await kafka.replayDlq('orders', { targetTopic: 'orders.v2' });
+
+// Only replay messages with a specific correlation ID
+const filtered = await kafka.replayDlq('orders', {
+  filter: (headers) => headers['x-correlation-id'] === 'corr-123',
+});
+```
+
+`replayDlq` creates a temporary consumer group that reads the DLQ topic up to the high-watermark at the time of the call — messages published after replay starts are not included. DLQ metadata headers (`x-dlq-original-topic`, `x-dlq-error-message`, `x-dlq-error-stack`, `x-dlq-failed-at`, `x-dlq-attempt-count`) are stripped from the replayed messages; all other headers (e.g. `x-correlation-id`) are preserved.
+
 ## Graceful shutdown
 
 `disconnect()` now drains in-flight handlers before tearing down connections — no messages are silently cut off mid-processing.

package/dist/{chunk-ISYOEX4W.mjs → chunk-4526Y4PV.mjs}

@@ -498,6 +498,17 @@ async function executeWithRetry(fn, ctx, deps) {
       deps.instrumentation
     );
     if (!error) {
+      if (deps.eosCommitOnSuccess) {
+        try {
+          await deps.eosCommitOnSuccess();
+        } catch (commitErr) {
+          deps.logger.error(
+            `EOS offset commit failed after successful handler \u2014 message will be redelivered:`,
+            toError(commitErr).stack
+          );
+          return;
+        }
+      }
       for (const env of envelopes) deps.onMessage?.(env);
       return;
     }
@@ -516,16 +527,28 @@ async function executeWithRetry(fn, ctx, deps) {
     if (retryTopics && retry) {
       const cap = Math.min(backoffMs, maxBackoffMs);
       const delay = Math.floor(Math.random() * cap);
-      await sendToRetryTopic(
-        topic2,
-        rawMessages,
-        1,
-        retry.maxRetries,
-        delay,
-        isBatch ? envelopes.map((e) => e.headers) : envelopes[0]?.headers ?? {},
-        deps
-      );
-      deps.onRetry?.(envelopes[0], 1, retry.maxRetries);
+      if (deps.eosRouteToRetry) {
+        try {
+          await deps.eosRouteToRetry(rawMessages, envelopes, delay);
+          deps.onRetry?.(envelopes[0], 1, retry.maxRetries);
+        } catch (txErr) {
+          deps.logger.error(
+            `EOS routing to retry topic failed \u2014 message will be redelivered:`,
+            toError(txErr).stack
+          );
+        }
+      } else {
+        await sendToRetryTopic(
+          topic2,
+          rawMessages,
+          1,
+          retry.maxRetries,
+          delay,
+          isBatch ? envelopes.map((e) => e.headers) : envelopes[0]?.headers ?? {},
+          deps
+        );
+        deps.onRetry?.(envelopes[0], 1, retry.maxRetries);
+      }
     } else if (isLastAttempt) {
       if (dlq) {
         for (let i = 0; i < rawMessages.length; i++) {
@@ -625,6 +648,43 @@ async function handleEachMessage(payload, opts, deps) {
     timeoutMs,
     wrapWithTimeout
   } = opts;
+  const eos = opts.eosMainContext;
+  const nextOffsetStr = (parseInt(message.offset, 10) + 1).toString();
+  const commitOffset = eos ? async () => {
+    await eos.consumer.commitOffsets([
+      { topic: topic2, partition, offset: nextOffsetStr }
+    ]);
+  } : void 0;
+  const eosRouteToRetry = eos && retry ? async (rawMsgs, envelopes, delay) => {
+    const { topic: rtTopic, messages: rtMsgs } = buildRetryTopicPayload(
+      topic2,
+      rawMsgs,
+      1,
+      retry.maxRetries,
+      delay,
+      envelopes[0]?.headers ?? {}
+    );
+    const tx = await eos.txProducer.transaction();
+    try {
+      await tx.send({ topic: rtTopic, messages: rtMsgs });
+      await tx.sendOffsets({
+        consumer: eos.consumer,
+        topics: [
+          {
+            topic: topic2,
+            partitions: [{ partition, offset: nextOffsetStr }]
+          }
+        ]
+      });
+      await tx.commit();
+    } catch (txErr) {
+      try {
+        await tx.abort();
+      } catch {
+      }
+      throw txErr;
+    }
+  } : void 0;
   const envelope = await parseSingleMessage(
     message,
     topic2,
@@ -634,7 +694,10 @@ async function handleEachMessage(payload, opts, deps) {
     dlq,
     deps
   );
-  if (envelope === null) return;
+  if (envelope === null) {
+    await commitOffset?.();
+    return;
+  }
   if (opts.deduplication) {
     const isDuplicate = await applyDeduplication(
       envelope,
@@ -643,7 +706,10 @@ async function handleEachMessage(payload, opts, deps) {
       dlq,
       deps
     );
-    if (isDuplicate) return;
+    if (isDuplicate) {
+      await commitOffset?.();
+      return;
+    }
   }
   await executeWithRetry(
     () => {
@@ -664,7 +730,7 @@ async function handleEachMessage(payload, opts, deps) {
       retry,
       retryTopics
     },
-    deps
+    { ...deps, eosRouteToRetry, eosCommitOnSuccess: commitOffset }
   );
 }
 async function handleEachBatch(payload, opts, deps) {
@@ -679,6 +745,50 @@ async function handleEachBatch(payload, opts, deps) {
     timeoutMs,
     wrapWithTimeout
   } = opts;
+  const eos = opts.eosMainContext;
+  const lastRawOffset = batch.messages.length > 0 ? batch.messages[batch.messages.length - 1].offset : void 0;
+  const batchNextOffsetStr = lastRawOffset ? (parseInt(lastRawOffset, 10) + 1).toString() : void 0;
+  const commitBatchOffset = eos && batchNextOffsetStr ? async () => {
+    await eos.consumer.commitOffsets([
+      {
+        topic: batch.topic,
+        partition: batch.partition,
+        offset: batchNextOffsetStr
+      }
+    ]);
+  } : void 0;
+  const eosRouteToRetry = eos && retry && batchNextOffsetStr ? async (rawMsgs, envelopes2, delay) => {
+    const { topic: rtTopic, messages: rtMsgs } = buildRetryTopicPayload(
+      batch.topic,
+      rawMsgs,
+      1,
+      retry.maxRetries,
+      delay,
+      envelopes2.map((e) => e.headers)
+    );
+    const tx = await eos.txProducer.transaction();
+    try {
+      await tx.send({ topic: rtTopic, messages: rtMsgs });
+      await tx.sendOffsets({
+        consumer: eos.consumer,
+        topics: [
+          {
+            topic: batch.topic,
+            partitions: [
+              { partition: batch.partition, offset: batchNextOffsetStr }
+            ]
+          }
+        ]
+      });
+      await tx.commit();
+    } catch (txErr) {
+      try {
+        await tx.abort();
+      } catch {
+      }
+      throw txErr;
+    }
+  } : void 0;
   const envelopes = [];
   const rawMessages = [];
   for (const message of batch.messages) {
@@ -706,7 +816,10 @@ async function handleEachBatch(payload, opts, deps) {
     envelopes.push(envelope);
     rawMessages.push(message.value.toString());
   }
-  if (envelopes.length === 0) return;
+  if (envelopes.length === 0) {
+    await commitBatchOffset?.();
+    return;
+  }
   const meta = {
     partition: batch.partition,
     highWatermark: batch.highWatermark,
@@ -728,7 +841,7 @@ async function handleEachBatch(payload, opts, deps) {
       isBatch: true,
       retryTopics
     },
-    deps
+    { ...deps, eosRouteToRetry, eosCommitOnSuccess: commitBatchOffset }
   );
 }
 
@@ -1009,7 +1122,7 @@ async function startRetryTopicConsumers(originalTopics, originalGroupId, handleM
 // src/client/kafka.client/index.ts
 var { Kafka: KafkaClass, logLevel: KafkaLogLevel } = KafkaJS;
 var _activeTransactionalIds = /* @__PURE__ */ new Set();
-var KafkaClient = class {
+var KafkaClient = class _KafkaClient {
   kafka;
   producer;
   txProducer;
@@ -1036,13 +1149,8 @@ var KafkaClient = class {
   onRebalance;
   /** Transactional producer ID — configurable via `KafkaClientOptions.transactionalId`. */
   txId;
-  /** Internal event counters exposed via `getMetrics()`. */
-  _metrics = {
-    processedCount: 0,
-    retryCount: 0,
-    dlqCount: 0,
-    dedupCount: 0
-  };
+  /** Per-topic event counters, lazily created on first event. Aggregated by `getMetrics()`. */
+  _topicMetrics = /* @__PURE__ */ new Map();
   /** Monotonically increasing Lamport clock stamped on every outgoing message. */
   _lamportClock = 0;
   /** Per-groupId deduplication state: `"topic:partition"` → last processed clock. */
@@ -1186,13 +1294,20 @@ var KafkaClient = class {
         "retryTopics requires retry to be configured \u2014 set retry.maxRetries to enable the retry topic chain"
       );
     }
-    const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry } = await this.setupConsumer(topics, "eachMessage", options);
+    const setupOptions = options.retryTopics ? { ...options, autoCommit: false } : options;
+    const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry } = await this.setupConsumer(topics, "eachMessage", setupOptions);
     const deps = this.messageDeps;
     const timeoutMs = options.handlerTimeoutMs;
     const deduplication = this.resolveDeduplicationContext(
       gid,
       options.deduplication
     );
+    let eosMainContext;
+    if (options.retryTopics && retry) {
+      const mainTxId = `${gid}-main-tx`;
+      const txProducer = await this.createRetryTxProducer(mainTxId);
+      eosMainContext = { txProducer, consumer };
+    }
     await consumer.run({
       eachMessage: (payload) => this.trackInFlight(
         () => handleEachMessage(
@@ -1206,7 +1321,8 @@ var KafkaClient = class {
             retryTopics: options.retryTopics,
             timeoutMs,
             wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this),
-            deduplication
+            deduplication,
+            eosMainContext
           },
           deps
         )
@@ -1238,18 +1354,26 @@ var KafkaClient = class {
         "retryTopics requires retry to be configured \u2014 set retry.maxRetries to enable the retry topic chain"
       );
     }
-    if (options.autoCommit !== false) {
+    if (options.retryTopics) {
+    } else if (options.autoCommit !== false) {
       this.logger.debug?.(
         `startBatchConsumer: autoCommit is enabled (default true). If your handler calls resolveOffset() or commitOffsetsIfNecessary(), set autoCommit: false to avoid offset conflicts.`
       );
     }
-    const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry } = await this.setupConsumer(topics, "eachBatch", options);
+    const setupOptions = options.retryTopics ? { ...options, autoCommit: false } : options;
+    const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry } = await this.setupConsumer(topics, "eachBatch", setupOptions);
     const deps = this.messageDeps;
     const timeoutMs = options.handlerTimeoutMs;
     const deduplication = this.resolveDeduplicationContext(
       gid,
       options.deduplication
     );
+    let eosMainContext;
+    if (options.retryTopics && retry) {
+      const mainTxId = `${gid}-main-tx`;
+      const txProducer = await this.createRetryTxProducer(mainTxId);
+      eosMainContext = { txProducer, consumer };
+    }
     await consumer.run({
       eachBatch: (payload) => this.trackInFlight(
         () => handleEachBatch(
@@ -1263,7 +1387,8 @@ var KafkaClient = class {
             retryTopics: options.retryTopics,
             timeoutMs,
             wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this),
-            deduplication
+            deduplication,
+            eosMainContext
           },
           deps
         )
@@ -1320,6 +1445,18 @@ var KafkaClient = class {
       this.consumerCreationOptions.delete(groupId);
       this.dedupStates.delete(groupId);
       this.logger.log(`Consumer disconnected: group "${groupId}"`);
+      const mainTxId = `${groupId}-main-tx`;
+      const mainTxProducer = this.retryTxProducers.get(mainTxId);
+      if (mainTxProducer) {
+        await mainTxProducer.disconnect().catch(
+          (e) => this.logger.warn(
+            `Error disconnecting main tx producer "${mainTxId}":`,
+            toError(e).message
+          )
+        );
+        _activeTransactionalIds.delete(mainTxId);
+        this.retryTxProducers.delete(mainTxId);
+      }
       const companions = this.companionGroupIds.get(groupId) ?? [];
       for (const cGroupId of companions) {
         const cConsumer = this.consumers.get(cGroupId);
@@ -1370,6 +1507,144 @@ var KafkaClient = class {
       this.logger.log("All consumers disconnected");
     }
   }
+  pauseConsumer(groupId, assignments) {
+    const gid = groupId ?? this.defaultGroupId;
+    const consumer = this.consumers.get(gid);
+    if (!consumer) {
+      this.logger.warn(`pauseConsumer: no active consumer for group "${gid}"`);
+      return;
+    }
+    consumer.pause(
+      assignments.flatMap(
+        ({ topic: topic2, partitions }) => partitions.map((p) => ({ topic: topic2, partitions: [p] }))
+      )
+    );
+  }
+  resumeConsumer(groupId, assignments) {
+    const gid = groupId ?? this.defaultGroupId;
+    const consumer = this.consumers.get(gid);
+    if (!consumer) {
+      this.logger.warn(`resumeConsumer: no active consumer for group "${gid}"`);
+      return;
+    }
+    consumer.resume(
+      assignments.flatMap(
+        ({ topic: topic2, partitions }) => partitions.map((p) => ({ topic: topic2, partitions: [p] }))
+      )
+    );
+  }
+  /** DLQ header keys added by `sendToDlq` — stripped before re-publishing. */
+  static DLQ_HEADER_KEYS = /* @__PURE__ */ new Set([
+    "x-dlq-original-topic",
+    "x-dlq-failed-at",
+    "x-dlq-error-message",
+    "x-dlq-error-stack",
+    "x-dlq-attempt-count"
+  ]);
+  async replayDlq(topic2, options = {}) {
+    const dlqTopic = `${topic2}.dlq`;
+    await this.ensureAdminConnected();
+    const partitionOffsets = await this.admin.fetchTopicOffsets(dlqTopic);
+    const activePartitions = partitionOffsets.filter(
+      (p) => parseInt(p.high, 10) > 0
+    );
+    if (activePartitions.length === 0) {
+      this.logger.log(`replayDlq: "${dlqTopic}" is empty \u2014 nothing to replay`);
+      return { replayed: 0, skipped: 0 };
+    }
+    const highWatermarks = new Map(
+      activePartitions.map(({ partition, high }) => [
+        partition,
+        parseInt(high, 10)
+      ])
+    );
+    const processedOffsets = /* @__PURE__ */ new Map();
+    let replayed = 0;
+    let skipped = 0;
+    const tempGroupId = `${dlqTopic}-replay-${Date.now()}`;
+    await new Promise((resolve, reject) => {
+      const consumer = getOrCreateConsumer(
+        tempGroupId,
+        true,
+        true,
+        this.consumerOpsDeps
+      );
+      const cleanup = () => {
+        consumer.disconnect().catch(() => {
+        }).finally(() => {
+          this.consumers.delete(tempGroupId);
+          this.runningConsumers.delete(tempGroupId);
+          this.consumerCreationOptions.delete(tempGroupId);
+        });
+      };
+      consumer.connect().then(
+        () => subscribeWithRetry(consumer, [dlqTopic], this.logger)
+      ).then(
+        () => consumer.run({
+          eachMessage: async ({ partition, message }) => {
+            if (!message.value) return;
+            const offset = parseInt(message.offset, 10);
+            processedOffsets.set(partition, offset);
+            const headers = decodeHeaders(message.headers);
+            const targetTopic = options.targetTopic ?? headers["x-dlq-original-topic"];
+            const originalHeaders = Object.fromEntries(
+              Object.entries(headers).filter(
+                ([k]) => !_KafkaClient.DLQ_HEADER_KEYS.has(k)
+              )
+            );
+            const value = message.value.toString();
+            const shouldProcess = !options.filter || options.filter(headers, value);
+            if (!targetTopic || !shouldProcess) {
+              skipped++;
+            } else if (options.dryRun) {
+              this.logger.log(
+                `[DLQ replay dry-run] Would replay to "${targetTopic}"`
+              );
+              replayed++;
+            } else {
+              await this.producer.send({
+                topic: targetTopic,
+                messages: [{ value, headers: originalHeaders }]
+              });
+              replayed++;
+            }
+            const allDone = Array.from(highWatermarks.entries()).every(
+              ([p, hwm]) => (processedOffsets.get(p) ?? -1) >= hwm - 1
+            );
+            if (allDone) {
+              cleanup();
+              resolve();
+            }
+          }
+        })
+      ).catch((err) => {
+        cleanup();
+        reject(err);
+      });
+    });
+    this.logger.log(
+      `replayDlq: replayed ${replayed}, skipped ${skipped} from "${dlqTopic}"`
+    );
+    return { replayed, skipped };
+  }
+  async resetOffsets(groupId, topic2, position) {
+    const gid = groupId ?? this.defaultGroupId;
+    if (this.runningConsumers.has(gid)) {
+      throw new Error(
+        `resetOffsets: consumer group "${gid}" is still running. Call stopConsumer("${gid}") before resetting offsets.`
+      );
+    }
+    await this.ensureAdminConnected();
+    const partitionOffsets = await this.admin.fetchTopicOffsets(topic2);
+    const partitions = partitionOffsets.map(({ partition, low, high }) => ({
+      partition,
+      offset: position === "earliest" ? low : high
+    }));
+    await this.admin.setOffsets({ groupId: gid, topic: topic2, partitions });
+    this.logger.log(
+      `Offsets reset to ${position} for group "${gid}" on topic "${topic2}"`
+    );
+  }
   /**
    * Query consumer group lag per partition.
    * Lag = broker high-watermark − last committed offset.
@@ -1420,14 +1695,31 @@ var KafkaClient = class {
   getClientId() {
     return this.clientId;
   }
-  getMetrics() {
-    return { ...this._metrics };
+  getMetrics(topic2) {
+    if (topic2 !== void 0) {
+      const m = this._topicMetrics.get(topic2);
+      return m ? { ...m } : { processedCount: 0, retryCount: 0, dlqCount: 0, dedupCount: 0 };
+    }
+    const agg = {
+      processedCount: 0,
+      retryCount: 0,
+      dlqCount: 0,
+      dedupCount: 0
+    };
+    for (const m of this._topicMetrics.values()) {
+      agg.processedCount += m.processedCount;
+      agg.retryCount += m.retryCount;
+      agg.dlqCount += m.dlqCount;
+      agg.dedupCount += m.dedupCount;
+    }
+    return agg;
   }
-  resetMetrics() {
-    this._metrics.processedCount = 0;
-    this._metrics.retryCount = 0;
-    this._metrics.dlqCount = 0;
-    this._metrics.dedupCount = 0;
+  resetMetrics(topic2) {
+    if (topic2 !== void 0) {
+      this._topicMetrics.delete(topic2);
+      return;
+    }
+    this._topicMetrics.clear();
   }
   /** Gracefully disconnect producer, all consumers, and admin. */
   async disconnect(drainTimeoutMs = 3e4) {
@@ -1537,26 +1829,34 @@ var KafkaClient = class {
       }
     }
   }
+  metricsFor(topic2) {
+    let m = this._topicMetrics.get(topic2);
+    if (!m) {
+      m = { processedCount: 0, retryCount: 0, dlqCount: 0, dedupCount: 0 };
+      this._topicMetrics.set(topic2, m);
+    }
+    return m;
+  }
   notifyRetry(envelope, attempt, maxRetries) {
-    this._metrics.retryCount++;
+    this.metricsFor(envelope.topic).retryCount++;
     for (const inst of this.instrumentation) {
       inst.onRetry?.(envelope, attempt, maxRetries);
     }
   }
   notifyDlq(envelope, reason) {
-    this._metrics.dlqCount++;
+    this.metricsFor(envelope.topic).dlqCount++;
     for (const inst of this.instrumentation) {
       inst.onDlq?.(envelope, reason);
     }
   }
   notifyDuplicate(envelope, strategy) {
-    this._metrics.dedupCount++;
+    this.metricsFor(envelope.topic).dedupCount++;
     for (const inst of this.instrumentation) {
       inst.onDuplicate?.(envelope, strategy);
     }
   }
   notifyMessage(envelope) {
-    this._metrics.processedCount++;
+    this.metricsFor(envelope.topic).processedCount++;
     for (const inst of this.instrumentation) {
       inst.onMessage?.(envelope);
     }
@@ -1843,4 +2143,4 @@ export {
   KafkaClient,
   topic
 };
-//# sourceMappingURL=chunk-ISYOEX4W.mjs.map
+//# sourceMappingURL=chunk-4526Y4PV.mjs.map