@drarzter/kafka-client 0.6.9 → 0.7.1

package/dist/core.mjs

@@ -15,7 +15,7 @@ import {
   getEnvelopeContext,
   runWithEnvelopeContext,
   topic
-} from "./chunk-4526Y4PV.mjs";
+} from "./chunk-AMEGMOZH.mjs";
 import "./chunk-EQQGB2QZ.mjs";
 export {
   HEADER_CORRELATION_ID,

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 export { KafkaClient, KafkaProcessingError, KafkaRetryExhaustedError, KafkaValidationError } from './core.mjs';
-import { T as TopicMapConstraint, C as ClientId, G as GroupId, K as KafkaInstrumentation, a as KafkaClientOptions, S as SchemaLike, b as ConsumerOptions, c as TopicDescriptor, I as IKafkaClient, d as KafkaHealthResult } from './types-736Gj0J3.mjs';
-export { B as BatchMessageItem, e as BatchMeta, f as BeforeConsumeResult, g as ConsumerHandle, h as ConsumerInterceptor, D as DeduplicationOptions, i as DlqReason, j as DlqReplayOptions, E as EnvelopeHeaderOptions, k as EventEnvelope, H as HEADER_CORRELATION_ID, l as HEADER_EVENT_ID, m as HEADER_LAMPORT_CLOCK, n as HEADER_SCHEMA_VERSION, o as HEADER_TIMESTAMP, p as HEADER_TRACEPARENT, q as InferSchema, r as KafkaLogger, s as KafkaMetrics, M as MessageHeaders, t as MessageLostContext, R as RetryOptions, u as SchemaParseContext, v as SendOptions, w as SubscribeRetryOptions, x as TTopicMessageMap, y as TopicsFrom, z as TransactionContext, A as buildEnvelopeHeaders, F as decodeHeaders, J as extractEnvelope, L as getEnvelopeContext, N as runWithEnvelopeContext, O as topic } from './types-736Gj0J3.mjs';
+import { T as TopicMapConstraint, C as ClientId, G as GroupId, K as KafkaInstrumentation, a as KafkaClientOptions, S as SchemaLike, b as ConsumerOptions, c as TopicDescriptor, I as IKafkaClient, d as KafkaHealthResult } from './types-BEIGjmV6.mjs';
+export { B as BatchMessageItem, e as BatchMeta, f as BeforeConsumeResult, g as CircuitBreakerOptions, h as ConsumerHandle, i as ConsumerInterceptor, D as DeduplicationOptions, j as DlqReason, k as DlqReplayOptions, E as EnvelopeHeaderOptions, l as EventEnvelope, H as HEADER_CORRELATION_ID, m as HEADER_EVENT_ID, n as HEADER_LAMPORT_CLOCK, o as HEADER_SCHEMA_VERSION, p as HEADER_TIMESTAMP, q as HEADER_TRACEPARENT, r as InferSchema, s as KafkaLogger, t as KafkaMetrics, M as MessageHeaders, u as MessageLostContext, R as RetryOptions, v as SchemaParseContext, w as SendOptions, x as SubscribeRetryOptions, y as TTopicMessageMap, z as TopicsFrom, A as TransactionContext, F as TtlExpiredContext, J as buildEnvelopeHeaders, L as decodeHeaders, N as extractEnvelope, O as getEnvelopeContext, P as runWithEnvelopeContext, Q as topic } from './types-BEIGjmV6.mjs';
 import { DynamicModule, OnModuleInit } from '@nestjs/common';
 import { DiscoveryService, ModuleRef } from '@nestjs/core';
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { KafkaClient, KafkaProcessingError, KafkaRetryExhaustedError, KafkaValidationError } from './core.js';
-import { T as TopicMapConstraint, C as ClientId, G as GroupId, K as KafkaInstrumentation, a as KafkaClientOptions, S as SchemaLike, b as ConsumerOptions, c as TopicDescriptor, I as IKafkaClient, d as KafkaHealthResult } from './types-736Gj0J3.js';
-export { B as BatchMessageItem, e as BatchMeta, f as BeforeConsumeResult, g as ConsumerHandle, h as ConsumerInterceptor, D as DeduplicationOptions, i as DlqReason, j as DlqReplayOptions, E as EnvelopeHeaderOptions, k as EventEnvelope, H as HEADER_CORRELATION_ID, l as HEADER_EVENT_ID, m as HEADER_LAMPORT_CLOCK, n as HEADER_SCHEMA_VERSION, o as HEADER_TIMESTAMP, p as HEADER_TRACEPARENT, q as InferSchema, r as KafkaLogger, s as KafkaMetrics, M as MessageHeaders, t as MessageLostContext, R as RetryOptions, u as SchemaParseContext, v as SendOptions, w as SubscribeRetryOptions, x as TTopicMessageMap, y as TopicsFrom, z as TransactionContext, A as buildEnvelopeHeaders, F as decodeHeaders, J as extractEnvelope, L as getEnvelopeContext, N as runWithEnvelopeContext, O as topic } from './types-736Gj0J3.js';
+import { T as TopicMapConstraint, C as ClientId, G as GroupId, K as KafkaInstrumentation, a as KafkaClientOptions, S as SchemaLike, b as ConsumerOptions, c as TopicDescriptor, I as IKafkaClient, d as KafkaHealthResult } from './types-BEIGjmV6.js';
+export { B as BatchMessageItem, e as BatchMeta, f as BeforeConsumeResult, g as CircuitBreakerOptions, h as ConsumerHandle, i as ConsumerInterceptor, D as DeduplicationOptions, j as DlqReason, k as DlqReplayOptions, E as EnvelopeHeaderOptions, l as EventEnvelope, H as HEADER_CORRELATION_ID, m as HEADER_EVENT_ID, n as HEADER_LAMPORT_CLOCK, o as HEADER_SCHEMA_VERSION, p as HEADER_TIMESTAMP, q as HEADER_TRACEPARENT, r as InferSchema, s as KafkaLogger, t as KafkaMetrics, M as MessageHeaders, u as MessageLostContext, R as RetryOptions, v as SchemaParseContext, w as SendOptions, x as SubscribeRetryOptions, y as TTopicMessageMap, z as TopicsFrom, A as TransactionContext, F as TtlExpiredContext, J as buildEnvelopeHeaders, L as decodeHeaders, N as extractEnvelope, O as getEnvelopeContext, P as runWithEnvelopeContext, Q as topic } from './types-BEIGjmV6.js';
 import { DynamicModule, OnModuleInit } from '@nestjs/common';
 import { DiscoveryService, ModuleRef } from '@nestjs/core';
 

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),
@@ -769,6 +776,31 @@ async function handleEachMessage(payload, opts, deps) {
       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.onTtlExpired?.({
+          topic: topic2,
+          ageMs,
+          messageTtlMs: opts.messageTtlMs,
+          headers: envelope.headers
+        });
+      }
+      await commitOffset?.();
+      return;
+    }
+  }
   await executeWithRetry(
     () => {
       const fn = () => runWithEnvelopeContext(
@@ -871,6 +903,30 @@ 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.onTtlExpired?.({
+            topic: batch.topic,
+            ageMs,
+            messageTtlMs: opts.messageTtlMs,
+            headers: envelope.headers
+          });
+        }
+        continue;
+      }
+    }
     envelopes.push(envelope);
     rawMessages.push(message.value.toString());
   }
@@ -1180,6 +1236,54 @@ 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 AsyncQueue = class {
+  constructor(highWaterMark = Infinity, onFull = () => {
+  }, onDrained = () => {
+  }) {
+    this.highWaterMark = highWaterMark;
+    this.onFull = onFull;
+    this.onDrained = onDrained;
+  }
+  items = [];
+  waiting = [];
+  closed = false;
+  error;
+  paused = false;
+  push(item) {
+    if (this.waiting.length > 0) {
+      this.waiting.shift().resolve({ value: item, done: false });
+    } else {
+      this.items.push(item);
+      if (!this.paused && this.items.length >= this.highWaterMark) {
+        this.paused = true;
+        this.onFull();
+      }
+    }
+  }
+  fail(err) {
+    this.closed = true;
+    this.error = err;
+    for (const { reject } of this.waiting.splice(0)) reject(err);
+  }
+  close() {
+    this.closed = true;
+    for (const { resolve } of this.waiting.splice(0))
+      resolve({ value: void 0, done: true });
+  }
+  next() {
+    if (this.error) return Promise.reject(this.error);
+    if (this.items.length > 0) {
+      const value = this.items.shift();
+      if (this.paused && this.items.length <= Math.floor(this.highWaterMark / 2)) {
+        this.paused = false;
+        this.onDrained();
+      }
+      return Promise.resolve({ value, done: false });
+    }
+    if (this.closed) return Promise.resolve({ value: void 0, done: true });
+    return new Promise((resolve, reject) => this.waiting.push({ resolve, reject }));
+  }
+};
 var KafkaClient = class _KafkaClient {
   kafka;
   producer;
@@ -1204,6 +1308,7 @@ var KafkaClient = class _KafkaClient {
   companionGroupIds = /* @__PURE__ */ new Map();
   instrumentation;
   onMessageLost;
+  onTtlExpired;
   onRebalance;
   /** Transactional producer ID — configurable via `KafkaClientOptions.transactionalId`. */
   txId;
@@ -1213,6 +1318,10 @@ var KafkaClient = class _KafkaClient {
   _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 = [];
@@ -1231,6 +1340,7 @@ var KafkaClient = class _KafkaClient {
     this.numPartitions = options?.numPartitions ?? 1;
     this.instrumentation = options?.instrumentation ?? [];
     this.onMessageLost = options?.onMessageLost;
+    this.onTtlExpired = options?.onTtlExpired;
     this.onRebalance = options?.onRebalance;
     this.txId = options?.transactionalId ?? `${clientId}-tx`;
     this.kafka = new KafkaClass({
@@ -1354,7 +1464,9 @@ var KafkaClient = class _KafkaClient {
     }
     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;
+    if (options.circuitBreaker)
+      this.circuitConfigs.set(gid, options.circuitBreaker);
+    const deps = this.messageDepsFor(gid);
     const timeoutMs = options.handlerTimeoutMs;
     const deduplication = this.resolveDeduplicationContext(
       gid,
@@ -1380,6 +1492,7 @@ var KafkaClient = class _KafkaClient {
             timeoutMs,
             wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this),
             deduplication,
+            messageTtlMs: options.messageTtlMs,
             eosMainContext
           },
           deps
@@ -1420,7 +1533,9 @@ var KafkaClient = class _KafkaClient {
     }
     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;
+    if (options.circuitBreaker)
+      this.circuitConfigs.set(gid, options.circuitBreaker);
+    const deps = this.messageDepsFor(gid);
     const timeoutMs = options.handlerTimeoutMs;
     const deduplication = this.resolveDeduplicationContext(
       gid,
@@ -1446,6 +1561,7 @@ var KafkaClient = class _KafkaClient {
             timeoutMs,
             wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this),
             deduplication,
+            messageTtlMs: options.messageTtlMs,
             eosMainContext
           },
           deps
@@ -1482,6 +1598,43 @@ var KafkaClient = class _KafkaClient {
     }
     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 gid = options?.groupId ?? this.defaultGroupId;
+    const queue = new AsyncQueue(
+      options?.queueHighWaterMark,
+      () => this.pauseTopicAllPartitions(gid, topic2),
+      () => this.resumeTopicAllPartitions(gid, topic2)
+    );
+    const handlePromise = this.startConsumer(
+      [topic2],
+      async (envelope) => {
+        queue.push(envelope);
+      },
+      options
+    );
+    handlePromise.catch((err) => queue.fail(err));
+    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) {
@@ -1502,6 +1655,13 @@ var KafkaClient = class _KafkaClient {
       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);
@@ -1562,6 +1722,10 @@ var KafkaClient = class _KafkaClient {
       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");
     }
   }
@@ -1591,6 +1755,24 @@ var KafkaClient = class _KafkaClient {
       )
     );
   }
+  /** Pause all assigned partitions of a topic for a consumer group (used for queue backpressure). */
+  pauseTopicAllPartitions(gid, topic2) {
+    const consumer = this.consumers.get(gid);
+    if (!consumer) return;
+    const assignment = consumer.assignment?.() ?? [];
+    const partitions = assignment.filter((a) => a.topic === topic2).map((a) => a.partition);
+    if (partitions.length > 0)
+      consumer.pause(partitions.map((p) => ({ topic: topic2, partitions: [p] })));
+  }
+  /** Resume all assigned partitions of a topic for a consumer group (used for queue backpressure). */
+  resumeTopicAllPartitions(gid, topic2) {
+    const consumer = this.consumers.get(gid);
+    if (!consumer) return;
+    const assignment = consumer.assignment?.() ?? [];
+    const partitions = assignment.filter((a) => a.topic === topic2).map((a) => a.partition);
+    if (partitions.length > 0)
+      consumer.resume(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",
@@ -1635,9 +1817,7 @@ var KafkaClient = class _KafkaClient {
           this.consumerCreationOptions.delete(tempGroupId);
         });
       };
-      consumer.connect().then(
-        () => subscribeWithRetry(consumer, [dlqTopic], this.logger)
-      ).then(
+      consumer.connect().then(() => subscribeWithRetry(consumer, [dlqTopic], this.logger)).then(
         () => consumer.run({
           eachMessage: async ({ partition, message }) => {
             if (!message.value) return;
@@ -1703,6 +1883,75 @@ var KafkaClient = class _KafkaClient {
       `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)}`
+      );
+    }
+  }
+  async seekToTimestamp(groupId, assignments) {
+    const gid = groupId ?? this.defaultGroupId;
+    if (this.runningConsumers.has(gid)) {
+      throw new Error(
+        `seekToTimestamp: 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, timestamp } of assignments) {
+      const list = byTopic.get(topic2) ?? [];
+      list.push({ partition, timestamp });
+      byTopic.set(topic2, list);
+    }
+    for (const [topic2, parts] of byTopic) {
+      const offsets = await Promise.all(
+        parts.map(async ({ partition, timestamp }) => {
+          const results = await this.admin.fetchTopicOffsetsByTime(
+            topic2,
+            timestamp
+          );
+          const found = results.find(
+            (r) => r.partition === partition
+          );
+          return { partition, offset: found?.offset ?? "-1" };
+        })
+      );
+      await this.admin.setOffsets({ groupId: gid, topic: topic2, partitions: offsets });
+      this.logger.log(
+        `Offsets set by timestamp for group "${gid}" on "${topic2}": ${JSON.stringify(offsets)}`
+      );
+    }
+  }
+  getCircuitState(topic2, partition, groupId) {
+    const gid = groupId ?? this.defaultGroupId;
+    const state = this.circuitStates.get(`${gid}:${topic2}:${partition}`);
+    if (!state) return void 0;
+    return {
+      status: state.status,
+      failures: state.window.filter((v) => !v).length,
+      windowSize: state.window.length
+    };
+  }
   /**
    * Query consumer group lag per partition.
    * Lag = broker high-watermark − last committed offset.
@@ -1808,6 +2057,9 @@ var KafkaClient = class _KafkaClient {
     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 ────────────────────────────────────────────
@@ -1901,11 +2153,66 @@ var KafkaClient = class _KafkaClient {
       inst.onRetry?.(envelope, attempt, maxRetries);
     }
   }
-  notifyDlq(envelope, reason) {
+  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";
+      state.window = [];
+      state.successes = 0;
+      clearTimeout(state.timer);
+      for (const inst of this.instrumentation)
+        inst.onCircuitOpen?.(envelope.topic, envelope.partition);
+      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}`
+        );
+        for (const inst of this.instrumentation)
+          inst.onCircuitHalfOpen?.(envelope.topic, 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.metricsFor(envelope.topic).dedupCount++;
@@ -1913,11 +2220,40 @@ var KafkaClient = class _KafkaClient {
       inst.onDuplicate?.(envelope, strategy);
     }
   }
-  notifyMessage(envelope) {
+  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}`
+        );
+        for (const inst of this.instrumentation)
+          inst.onCircuitClose?.(envelope.topic, 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`.
@@ -2138,16 +2474,18 @@ var KafkaClient = class _KafkaClient {
       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,
+      onTtlExpired: this.onTtlExpired,
       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() {