@drarzter/kafka-client 0.6.9 → 0.7.0

package/README.md

@@ -20,6 +20,7 @@ Type-safe Kafka client for Node.js. Framework-agnostic core with a first-class N
 - [Consuming messages](#consuming-messages)
   - [Declarative: @SubscribeTo()](#declarative-subscribeto)
   - [Imperative: startConsumer()](#imperative-startconsumer)
+  - [Iterator: consume()](#iterator-consume)
 - [Multiple consumer groups](#multiple-consumer-groups)
 - [Partition key](#partition-key)
 - [Message headers](#message-headers)
@@ -34,7 +35,10 @@ Type-safe Kafka client for Node.js. Framework-agnostic core with a first-class N
 - [Retry topic chain](#retry-topic-chain)
 - [stopConsumer](#stopconsumer)
 - [Pause and resume](#pause-and-resume)
+- [Circuit breaker](#circuit-breaker)
 - [Reset consumer offsets](#reset-consumer-offsets)
+- [Seek to offset](#seek-to-offset)
+- [Message TTL](#message-ttl)
 - [DLQ replay](#dlq-replay)
 - [Graceful shutdown](#graceful-shutdown)
 - [Consumer handles](#consumer-handles)
@@ -86,6 +90,10 @@ Safe by default. Configurable when you need it. Escape hatches for when you know
 - **Health check** — built-in health indicator for monitoring
 - **Multiple consumer groups** — named clients for different bounded contexts
 - **Declarative & imperative** — use `@SubscribeTo()` decorator or `startConsumer()` directly
+- **Async iterator** — `consume<K>()` returns an `AsyncIterableIterator<EventEnvelope<T[K]>>` for `for await` consumption; breaking out of the loop stops the consumer automatically
+- **Message TTL** — `messageTtlMs` drops or DLQs messages older than a configurable threshold, preventing stale events from poisoning downstream systems after a lag spike
+- **Circuit breaker** — `circuitBreaker` option applies a sliding-window breaker per topic-partition; pauses delivery on repeated DLQ failures and resumes after a configurable recovery window
+- **Seek to offset** — `seekToOffset(groupId, assignments)` seeks individual partitions to explicit offsets for fine-grained replay
 
 See the [Roadmap](./ROADMAP.md) for upcoming features and version history.
 
@@ -379,7 +387,7 @@ export class OrdersService {
 
 ## Consuming messages
 
-Two ways — choose what fits your style.
+Three ways — choose what fits your style.
 
 ### Declarative: @SubscribeTo()
 
@@ -428,6 +436,35 @@ export class OrdersService implements OnModuleInit {
 }
 ```
 
+### Iterator: consume()
+
+Stream messages from a single topic as an `AsyncIterableIterator` — useful for scripts, one-off tasks, or any context where you prefer `for await` over a callback:
+
+```typescript
+for await (const envelope of kafka.consume('order.created')) {
+  console.log('Order:', envelope.payload.orderId);
+}
+
+// Breaking out of the loop stops the consumer automatically
+for await (const envelope of kafka.consume('order.created')) {
+  if (envelope.payload.orderId === targetId) break;
+}
+```
+
+`consume()` accepts the same `ConsumerOptions` as `startConsumer()`:
+
+```typescript
+for await (const envelope of kafka.consume('orders', {
+  retry: { maxRetries: 3 },
+  dlq: true,
+  messageTtlMs: 60_000,
+})) {
+  await processOrder(envelope.payload);
+}
+```
+
+`break`, `return`, or any early exit from the loop calls the iterator's `return()` method, which closes the internal queue and calls `handle.stop()` on the background consumer.
+
 ## Multiple consumer groups
 
 ### Per-consumer groupId
@@ -828,6 +865,12 @@ Options for `sendMessage()` — the third argument:
 | `handlerTimeoutMs` | — | Log a warning if the handler hasn't resolved within this window (ms) — does not cancel the handler |
 | `deduplication.strategy` | `'drop'` | What to do with duplicate messages: `'drop'` silently discards, `'dlq'` forwards to `{topic}.dlq` (requires `dlq: true`), `'topic'` forwards to `{topic}.duplicates` |
 | `deduplication.duplicatesTopic` | `{topic}.duplicates` | Custom destination for `strategy: 'topic'` |
+| `messageTtlMs` | — | Drop (or DLQ) messages older than this many milliseconds at consumption time; evaluated against the `x-timestamp` header; see [Message TTL](#message-ttl) |
+| `circuitBreaker` | — | Enable circuit breaker with `{}` for zero-config defaults; requires `dlq: true`; see [Circuit breaker](#circuit-breaker) |
+| `circuitBreaker.threshold` | `5` | DLQ failures within `windowSize` that opens the circuit |
+| `circuitBreaker.recoveryMs` | `30_000` | Milliseconds to wait in OPEN state before entering HALF_OPEN |
+| `circuitBreaker.windowSize` | `threshold × 2, min 10` | Sliding window size in messages |
+| `circuitBreaker.halfOpenSuccesses` | `1` | Consecutive successes in HALF_OPEN required to close the circuit |
 | `batch` | `false` | (decorator only) Use `startBatchConsumer` instead of `startConsumer` |
 | `subscribeRetry.retries` | `5` | Max attempts for `consumer.subscribe()` when topic doesn't exist yet |
 | `subscribeRetry.backoffMs` | `5000` | Delay between subscribe retry attempts (ms) |
@@ -1109,6 +1152,54 @@ The first argument is the consumer group ID — pass `undefined` to target the d
 
 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.
 
+## Circuit breaker
+
+Automatically pause delivery from a topic-partition when its DLQ error rate exceeds a threshold. After a recovery window the partition is resumed automatically.
+
+**`dlq: true` is required** — the breaker counts DLQ events as failures. Without it no failures are recorded and the circuit never opens.
+
+Zero-config start — all options have sensible defaults:
+
+```typescript
+await kafka.startConsumer(['orders'], handler, {
+  dlq: true,
+  circuitBreaker: {},
+});
+```
+
+Full config for fine-tuning:
+
+```typescript
+await kafka.startConsumer(['orders'], handler, {
+  dlq: true,
+  circuitBreaker: {
+    threshold: 10,         // open after 10 failures (default: 5)
+    recoveryMs: 60_000,   // wait 60 s before probing (default: 30 s)
+    windowSize: 50,        // track last 50 messages (default: threshold × 2, min 10)
+    halfOpenSuccesses: 3,  // 3 successes to close (default: 1)
+  },
+});
+```
+
+State machine per `${groupId}:${topic}:${partition}`:
+
+| State | Behaviour |
+| ----- | --------- |
+| **CLOSED** (normal) | Messages delivered. Failures recorded in sliding window. Opens when `failures ≥ threshold`. |
+| **OPEN** | Partition paused via `pauseConsumer`. After `recoveryMs` ms transitions to HALF_OPEN. |
+| **HALF_OPEN** | Partition resumed. After `halfOpenSuccesses` consecutive successes the circuit closes. Any single failure immediately re-opens it. |
+
+Successful `onMessage` completions count as successes. The retry topic path is not subject to the breaker — it has its own backoff and EOS guarantees.
+
+Options:
+
+| Option | Default | Description |
+| ------ | ------- | ----------- |
+| `threshold` | `5` | DLQ failures within `windowSize` that opens the circuit |
+| `recoveryMs` | `30_000` | Milliseconds to wait in OPEN state before entering HALF_OPEN |
+| `windowSize` | `threshold × 2, min 10` | Sliding window size in messages |
+| `halfOpenSuccesses` | `1` | Consecutive successes in HALF_OPEN required to close the circuit |
+
 ## Reset consumer offsets
 
 Seek a consumer group's committed offsets to the beginning or end of a topic:
@@ -1126,6 +1217,46 @@ 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.
 
+## Seek to offset
+
+Seek individual topic-partitions to explicit offsets — useful when `resetOffsets` is too coarse and you need per-partition control:
+
+```typescript
+// Seek partition 0 of 'orders' to offset 100, partition 1 to offset 200
+await kafka.seekToOffset(undefined, [
+  { topic: 'orders', partition: 0, offset: '100' },
+  { topic: 'orders', partition: 1, offset: '200' },
+]);
+
+// Multiple topics in one call
+await kafka.seekToOffset('payments-group', [
+  { topic: 'payments', partition: 0, offset: '0' },
+  { topic: 'refunds',  partition: 0, offset: '500' },
+]);
+```
+
+The first argument is the consumer group ID — pass `undefined` to target the default group. Assignments are grouped by topic internally so each `admin.setOffsets` call covers all partitions of one topic.
+
+**Important:** the consumer for the specified group must be stopped before calling `seekToOffset`. An error is thrown if the group is currently running.
+
+## Message TTL
+
+Drop or route expired messages using `messageTtlMs` in `ConsumerOptions`:
+
+```typescript
+await kafka.startConsumer(['orders'], handler, {
+  messageTtlMs: 60_000, // drop messages older than 60 s
+  dlq: true,            // route expired messages to DLQ instead of dropping
+});
+```
+
+The TTL is evaluated against the `x-timestamp` header stamped on every outgoing message by the producer. Messages whose age at consumption time exceeds `messageTtlMs` are:
+
+- **Routed to DLQ** with `x-dlq-reason: ttl-expired` when `dlq: true`
+- **Dropped** (calling `onMessageLost`) otherwise
+
+Typical use: prevent stale events from poisoning downstream systems after a consumer lag spike — e.g. discard order events or push notifications that are no longer actionable.
+
 ## DLQ replay
 
 Re-publish messages from a dead letter queue back to the original topic:

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

@@ -336,9 +336,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),
@@ -711,6 +718,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.onMessageLost?.({
+          topic: topic2,
+          error: new Error(`TTL expired: ${ageMs}ms`),
+          attempt: 0,
+          headers: envelope.headers
+        });
+      }
+      await commitOffset?.();
+      return;
+    }
+  }
   await executeWithRetry(
     () => {
       const fn = () => runWithEnvelopeContext(
@@ -813,6 +845,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.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());
   }
@@ -1122,6 +1178,31 @@ async function startRetryTopicConsumers(originalTopics, originalGroupId, handleM
 // src/client/kafka.client/index.ts
 var { Kafka: KafkaClass, logLevel: KafkaLogLevel } = KafkaJS;
 var _activeTransactionalIds = /* @__PURE__ */ new Set();
+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;
@@ -1155,6 +1236,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 = [];
@@ -1296,7 +1381,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,
@@ -1322,6 +1409,7 @@ var KafkaClient = class _KafkaClient {
             timeoutMs,
             wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this),
             deduplication,
+            messageTtlMs: options.messageTtlMs,
             eosMainContext
           },
           deps
@@ -1362,7 +1450,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,
@@ -1388,6 +1478,7 @@ var KafkaClient = class _KafkaClient {
             timeoutMs,
             wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this),
             deduplication,
+            messageTtlMs: options.messageTtlMs,
             eosMainContext
           },
           deps
@@ -1424,6 +1515,37 @@ 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 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) {
@@ -1444,6 +1566,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);
@@ -1504,6 +1633,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");
     }
   }
@@ -1577,9 +1710,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;
@@ -1645,6 +1776,32 @@ 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)}`
+      );
+    }
+  }
   /**
    * Query consumer group lag per partition.
    * Lag = broker high-watermark − last committed offset.
@@ -1750,6 +1907,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 ────────────────────────────────────────────
@@ -1843,11 +2003,59 @@ 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";
+      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.metricsFor(envelope.topic).dedupCount++;
@@ -1855,11 +2063,38 @@ 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}`
+        );
+      }
+    } 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`.
@@ -2080,16 +2315,17 @@ 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,
       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() {
@@ -2143,4 +2379,4 @@ export {
   KafkaClient,
   topic
 };
-//# sourceMappingURL=chunk-4526Y4PV.mjs.map
+//# sourceMappingURL=chunk-MJ342P4R.mjs.map