@drarzter/kafka-client 0.6.7 → 0.7.0

package/dist/index.js

@@ -394,9 +394,16 @@ var RETRY_HEADER_MAX_RETRIES = "x-retry-max-retries";
 var RETRY_HEADER_ORIGINAL_TOPIC = "x-retry-original-topic";
 function buildRetryTopicPayload(originalTopic, rawMessages, attempt, maxRetries, delayMs, originalHeaders) {
   const retryTopic = `${originalTopic}.retry.${attempt}`;
-  const STRIP = /* @__PURE__ */ new Set([RETRY_HEADER_ATTEMPT, RETRY_HEADER_AFTER, RETRY_HEADER_MAX_RETRIES, RETRY_HEADER_ORIGINAL_TOPIC]);
+  const STRIP = /* @__PURE__ */ new Set([
+    RETRY_HEADER_ATTEMPT,
+    RETRY_HEADER_AFTER,
+    RETRY_HEADER_MAX_RETRIES,
+    RETRY_HEADER_ORIGINAL_TOPIC
+  ]);
   function buildHeaders(hdr) {
-    const userHeaders = Object.fromEntries(Object.entries(hdr).filter(([k]) => !STRIP.has(k)));
+    const userHeaders = Object.fromEntries(
+      Object.entries(hdr).filter(([k]) => !STRIP.has(k))
+    );
     return {
       ...userHeaders,
       [RETRY_HEADER_ATTEMPT]: String(attempt),
@@ -556,6 +563,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;
     }
@@ -574,16 +592,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++) {
@@ -683,6 +713,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,
@@ -692,7 +759,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,
@@ -701,7 +771,35 @@ async function handleEachMessage(payload, opts, deps) {
       dlq,
       deps
     );
-    if (isDuplicate) return;
+    if (isDuplicate) {
+      await commitOffset?.();
+      return;
+    }
+  }
+  if (opts.messageTtlMs !== void 0) {
+    const ageMs = Date.now() - new Date(envelope.timestamp).getTime();
+    if (ageMs > opts.messageTtlMs) {
+      deps.logger.warn(
+        `[KafkaClient] TTL expired on ${topic2}: age ${ageMs}ms > ${opts.messageTtlMs}ms`
+      );
+      if (dlq) {
+        await sendToDlq(topic2, message.value.toString(), deps, {
+          error: new Error(`Message TTL expired: age ${ageMs}ms`),
+          attempt: 0,
+          originalHeaders: envelope.headers
+        });
+        deps.onDlq?.(envelope, "ttl-expired");
+      } else {
+        await deps.onMessageLost?.({
+          topic: topic2,
+          error: new Error(`TTL expired: ${ageMs}ms`),
+          attempt: 0,
+          headers: envelope.headers
+        });
+      }
+      await commitOffset?.();
+      return;
+    }
   }
   await executeWithRetry(
     () => {
@@ -722,7 +820,7 @@ async function handleEachMessage(payload, opts, deps) {
       retry,
       retryTopics
     },
-    deps
+    { ...deps, eosRouteToRetry, eosCommitOnSuccess: commitOffset }
   );
 }
 async function handleEachBatch(payload, opts, deps) {
@@ -737,6 +835,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) {
@@ -761,10 +903,37 @@ async function handleEachBatch(payload, opts, deps) {
       );
       if (isDuplicate) continue;
     }
+    if (opts.messageTtlMs !== void 0) {
+      const ageMs = Date.now() - new Date(envelope.timestamp).getTime();
+      if (ageMs > opts.messageTtlMs) {
+        deps.logger.warn(
+          `[KafkaClient] TTL expired on ${batch.topic}: age ${ageMs}ms > ${opts.messageTtlMs}ms`
+        );
+        if (dlq) {
+          await sendToDlq(batch.topic, message.value.toString(), deps, {
+            error: new Error(`Message TTL expired: age ${ageMs}ms`),
+            attempt: 0,
+            originalHeaders: envelope.headers
+          });
+          deps.onDlq?.(envelope, "ttl-expired");
+        } else {
+          await deps.onMessageLost?.({
+            topic: batch.topic,
+            error: new Error(`TTL expired: ${ageMs}ms`),
+            attempt: 0,
+            headers: envelope.headers
+          });
+        }
+        continue;
+      }
+    }
     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,
@@ -786,7 +955,7 @@ async function handleEachBatch(payload, opts, deps) {
       isBatch: true,
       retryTopics
     },
-    deps
+    { ...deps, eosRouteToRetry, eosCommitOnSuccess: commitBatchOffset }
   );
 }
 
@@ -1067,7 +1236,32 @@ async function startRetryTopicConsumers(originalTopics, originalGroupId, handleM
 // src/client/kafka.client/index.ts
 var { Kafka: KafkaClass, logLevel: KafkaLogLevel } = import_kafka_javascript.KafkaJS;
 var _activeTransactionalIds = /* @__PURE__ */ new Set();
-var KafkaClient = class {
+var AsyncQueue = class {
+  items = [];
+  waiting = [];
+  closed = false;
+  push(item) {
+    if (this.waiting.length > 0) {
+      this.waiting.shift()({ value: item, done: false });
+    } else {
+      this.items.push(item);
+    }
+  }
+  close() {
+    this.closed = true;
+    for (const r of this.waiting.splice(0)) {
+      r({ value: void 0, done: true });
+    }
+  }
+  next() {
+    if (this.items.length > 0)
+      return Promise.resolve({ value: this.items.shift(), done: false });
+    if (this.closed)
+      return Promise.resolve({ value: void 0, done: true });
+    return new Promise((r) => this.waiting.push(r));
+  }
+};
+var KafkaClient = class _KafkaClient {
   kafka;
   producer;
   txProducer;
@@ -1094,17 +1288,16 @@ 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. */
   dedupStates = /* @__PURE__ */ new Map();
+  /** Circuit breaker state per `"${gid}:${topic}:${partition}"` key. */
+  circuitStates = /* @__PURE__ */ new Map();
+  /** Circuit breaker config per groupId, set at startConsumer/startBatchConsumer time. */
+  circuitConfigs = /* @__PURE__ */ new Map();
   isAdminConnected = false;
   inFlightTotal = 0;
   drainResolvers = [];
@@ -1244,13 +1437,22 @@ 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 deps = this.messageDeps;
+    const setupOptions = options.retryTopics ? { ...options, autoCommit: false } : options;
+    const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry } = await this.setupConsumer(topics, "eachMessage", setupOptions);
+    if (options.circuitBreaker)
+      this.circuitConfigs.set(gid, options.circuitBreaker);
+    const deps = this.messageDepsFor(gid);
     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(
@@ -1264,7 +1466,9 @@ var KafkaClient = class {
             retryTopics: options.retryTopics,
             timeoutMs,
             wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this),
-            deduplication
+            deduplication,
+            messageTtlMs: options.messageTtlMs,
+            eosMainContext
           },
           deps
         )
@@ -1296,18 +1500,28 @@ 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 deps = this.messageDeps;
+    const setupOptions = options.retryTopics ? { ...options, autoCommit: false } : options;
+    const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry } = await this.setupConsumer(topics, "eachBatch", setupOptions);
+    if (options.circuitBreaker)
+      this.circuitConfigs.set(gid, options.circuitBreaker);
+    const deps = this.messageDepsFor(gid);
     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(
@@ -1321,7 +1535,9 @@ var KafkaClient = class {
             retryTopics: options.retryTopics,
             timeoutMs,
             wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this),
-            deduplication
+            deduplication,
+            messageTtlMs: options.messageTtlMs,
+            eosMainContext
           },
           deps
         )
@@ -1357,6 +1573,37 @@ var KafkaClient = class {
     }
     return { groupId: gid, stop: () => this.stopConsumer(gid) };
   }
+  /**
+   * Consume messages from a topic as an AsyncIterableIterator.
+   * Use with `for await` — breaking out of the loop automatically stops the consumer.
+   *
+   * @example
+   * for await (const envelope of kafka.consume('my.topic')) {
+   *   console.log(envelope.data);
+   * }
+   */
+  consume(topic2, options) {
+    const queue = new AsyncQueue();
+    const handlePromise = this.startConsumer(
+      [topic2],
+      async (envelope) => {
+        queue.push(envelope);
+      },
+      options
+    );
+    return {
+      [Symbol.asyncIterator]() {
+        return this;
+      },
+      next: () => queue.next(),
+      return: async () => {
+        queue.close();
+        const handle = await handlePromise;
+        await handle.stop();
+        return { value: void 0, done: true };
+      }
+    };
+  }
   // ── Consumer lifecycle ───────────────────────────────────────────
   async stopConsumer(groupId) {
     if (groupId !== void 0) {
@@ -1377,7 +1624,26 @@ var KafkaClient = class {
       this.runningConsumers.delete(groupId);
       this.consumerCreationOptions.delete(groupId);
       this.dedupStates.delete(groupId);
+      for (const key of [...this.circuitStates.keys()]) {
+        if (key.startsWith(`${groupId}:`)) {
+          clearTimeout(this.circuitStates.get(key).timer);
+          this.circuitStates.delete(key);
+        }
+      }
+      this.circuitConfigs.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);
@@ -1425,9 +1691,175 @@ var KafkaClient = class {
       this.companionGroupIds.clear();
       this.retryTxProducers.clear();
       this.dedupStates.clear();
+      for (const state of this.circuitStates.values())
+        clearTimeout(state.timer);
+      this.circuitStates.clear();
+      this.circuitConfigs.clear();
       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}"`
+    );
+  }
+  /**
+   * Seek specific topic-partition pairs to explicit offsets for a stopped consumer group.
+   * Throws if the group is still running — call `stopConsumer(groupId)` first.
+   * Assignments are grouped by topic and committed via `admin.setOffsets`.
+   */
+  async seekToOffset(groupId, assignments) {
+    const gid = groupId ?? this.defaultGroupId;
+    if (this.runningConsumers.has(gid)) {
+      throw new Error(
+        `seekToOffset: consumer group "${gid}" is still running. Call stopConsumer("${gid}") before seeking offsets.`
+      );
+    }
+    await this.ensureAdminConnected();
+    const byTopic = /* @__PURE__ */ new Map();
+    for (const { topic: topic2, partition, offset } of assignments) {
+      const list = byTopic.get(topic2) ?? [];
+      list.push({ partition, offset });
+      byTopic.set(topic2, list);
+    }
+    for (const [topic2, partitions] of byTopic) {
+      await this.admin.setOffsets({ groupId: gid, topic: topic2, partitions });
+      this.logger.log(
+        `Offsets set for group "${gid}" on "${topic2}": ${JSON.stringify(partitions)}`
+      );
+    }
+  }
   /**
    * Query consumer group lag per partition.
    * Lag = broker high-watermark − last committed offset.
@@ -1478,14 +1910,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) {
@@ -1516,6 +1965,9 @@ var KafkaClient = class {
     this.runningConsumers.clear();
     this.consumerCreationOptions.clear();
     this.companionGroupIds.clear();
+    for (const state of this.circuitStates.values()) clearTimeout(state.timer);
+    this.circuitStates.clear();
+    this.circuitConfigs.clear();
     this.logger.log("All connections closed");
   }
   // ── Graceful shutdown ────────────────────────────────────────────
@@ -1595,29 +2047,112 @@ 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++;
+  notifyDlq(envelope, reason, gid) {
+    this.metricsFor(envelope.topic).dlqCount++;
     for (const inst of this.instrumentation) {
       inst.onDlq?.(envelope, reason);
     }
+    if (!gid) return;
+    const cfg = this.circuitConfigs.get(gid);
+    if (!cfg) return;
+    const threshold = cfg.threshold ?? 5;
+    const recoveryMs = cfg.recoveryMs ?? 3e4;
+    const stateKey = `${gid}:${envelope.topic}:${envelope.partition}`;
+    let state = this.circuitStates.get(stateKey);
+    if (!state) {
+      state = { status: "closed", window: [], successes: 0 };
+      this.circuitStates.set(stateKey, state);
+    }
+    if (state.status === "open") return;
+    const openCircuit = () => {
+      state.status = "open";
+      this.pauseConsumer(gid, [
+        { topic: envelope.topic, partitions: [envelope.partition] }
+      ]);
+      state.timer = setTimeout(() => {
+        state.status = "half-open";
+        state.successes = 0;
+        this.logger.log(
+          `[CircuitBreaker] HALF-OPEN \u2014 group="${gid}" topic="${envelope.topic}" partition=${envelope.partition}`
+        );
+        this.resumeConsumer(gid, [
+          { topic: envelope.topic, partitions: [envelope.partition] }
+        ]);
+      }, recoveryMs);
+    };
+    if (state.status === "half-open") {
+      clearTimeout(state.timer);
+      this.logger.warn(
+        `[CircuitBreaker] OPEN (half-open failure) \u2014 group="${gid}" topic="${envelope.topic}" partition=${envelope.partition}`
+      );
+      openCircuit();
+      return;
+    }
+    const windowSize = cfg.windowSize ?? Math.max(threshold * 2, 10);
+    state.window = [...state.window, false];
+    if (state.window.length > windowSize) {
+      state.window = state.window.slice(state.window.length - windowSize);
+    }
+    const failures = state.window.filter((v) => !v).length;
+    if (failures >= threshold) {
+      this.logger.warn(
+        `[CircuitBreaker] OPEN \u2014 group="${gid}" topic="${envelope.topic}" partition=${envelope.partition} (${failures}/${state.window.length} failures, threshold=${threshold})`
+      );
+      openCircuit();
+    }
   }
   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++;
+  notifyMessage(envelope, gid) {
+    this.metricsFor(envelope.topic).processedCount++;
     for (const inst of this.instrumentation) {
       inst.onMessage?.(envelope);
     }
+    if (!gid) return;
+    const cfg = this.circuitConfigs.get(gid);
+    if (!cfg) return;
+    const stateKey = `${gid}:${envelope.topic}:${envelope.partition}`;
+    const state = this.circuitStates.get(stateKey);
+    if (!state) return;
+    const halfOpenSuccesses = cfg.halfOpenSuccesses ?? 1;
+    if (state.status === "half-open") {
+      state.successes++;
+      if (state.successes >= halfOpenSuccesses) {
+        clearTimeout(state.timer);
+        state.timer = void 0;
+        state.status = "closed";
+        state.window = [];
+        state.successes = 0;
+        this.logger.log(
+          `[CircuitBreaker] CLOSED \u2014 group="${gid}" topic="${envelope.topic}" partition=${envelope.partition}`
+        );
+      }
+    } else if (state.status === "closed") {
+      const threshold = cfg.threshold ?? 5;
+      const windowSize = cfg.windowSize ?? Math.max(threshold * 2, 10);
+      state.window = [...state.window, true];
+      if (state.window.length > windowSize) {
+        state.window = state.window.slice(state.window.length - windowSize);
+      }
+    }
   }
   /**
    * Start a timer that logs a warning if `fn` hasn't resolved within `timeoutMs`.
@@ -1838,16 +2373,17 @@ var KafkaClient = class {
       logger: this.logger
     };
   }
-  get messageDeps() {
+  /** Build MessageHandlerDeps with circuit breaker callbacks bound to the given groupId. */
+  messageDepsFor(gid) {
     return {
       logger: this.logger,
       producer: this.producer,
       instrumentation: this.instrumentation,
       onMessageLost: this.onMessageLost,
       onRetry: this.notifyRetry.bind(this),
-      onDlq: this.notifyDlq.bind(this),
+      onDlq: (envelope, reason) => this.notifyDlq(envelope, reason, gid),
       onDuplicate: this.notifyDuplicate.bind(this),
-      onMessage: this.notifyMessage.bind(this)
+      onMessage: (envelope) => this.notifyMessage(envelope, gid)
     };
   }
   get retryTopicDeps() {