@drarzter/kafka-client 0.5.5 → 0.5.7

package/dist/chunk-TD2AE774.mjs

@@ -0,0 +1,1231 @@
+// src/client/kafka.client/index.ts
+import { KafkaJS } from "@confluentinc/kafka-javascript";
+
+// src/client/message/envelope.ts
+import { AsyncLocalStorage } from "async_hooks";
+import { randomUUID } from "crypto";
+var HEADER_EVENT_ID = "x-event-id";
+var HEADER_CORRELATION_ID = "x-correlation-id";
+var HEADER_TIMESTAMP = "x-timestamp";
+var HEADER_SCHEMA_VERSION = "x-schema-version";
+var HEADER_TRACEPARENT = "traceparent";
+var envelopeStorage = new AsyncLocalStorage();
+function getEnvelopeContext() {
+  return envelopeStorage.getStore();
+}
+function runWithEnvelopeContext(ctx, fn) {
+  return envelopeStorage.run(ctx, fn);
+}
+function buildEnvelopeHeaders(options = {}) {
+  const ctx = getEnvelopeContext();
+  const correlationId = options.correlationId ?? ctx?.correlationId ?? randomUUID();
+  const eventId = options.eventId ?? randomUUID();
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const schemaVersion = String(options.schemaVersion ?? 1);
+  const envelope = {
+    [HEADER_EVENT_ID]: eventId,
+    [HEADER_CORRELATION_ID]: correlationId,
+    [HEADER_TIMESTAMP]: timestamp,
+    [HEADER_SCHEMA_VERSION]: schemaVersion
+  };
+  if (ctx?.traceparent) {
+    envelope[HEADER_TRACEPARENT] = ctx.traceparent;
+  }
+  return { ...envelope, ...options.headers };
+}
+function decodeHeaders(raw) {
+  if (!raw) return {};
+  const result = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (value === void 0) continue;
+    if (Array.isArray(value)) {
+      result[key] = value.map((v) => Buffer.isBuffer(v) ? v.toString() : v).join(",");
+    } else {
+      result[key] = Buffer.isBuffer(value) ? value.toString() : value;
+    }
+  }
+  return result;
+}
+function extractEnvelope(payload, headers, topic2, partition, offset) {
+  return {
+    payload,
+    topic: topic2,
+    partition,
+    offset,
+    eventId: headers[HEADER_EVENT_ID] ?? randomUUID(),
+    correlationId: headers[HEADER_CORRELATION_ID] ?? randomUUID(),
+    timestamp: headers[HEADER_TIMESTAMP] ?? (/* @__PURE__ */ new Date()).toISOString(),
+    schemaVersion: Number(headers[HEADER_SCHEMA_VERSION] ?? 1),
+    traceparent: headers[HEADER_TRACEPARENT],
+    headers
+  };
+}
+
+// src/client/errors.ts
+var KafkaProcessingError = class extends Error {
+  constructor(message, topic2, originalMessage, options) {
+    super(message, options);
+    this.topic = topic2;
+    this.originalMessage = originalMessage;
+    this.name = "KafkaProcessingError";
+    if (options?.cause) this.cause = options.cause;
+  }
+};
+var KafkaValidationError = class extends Error {
+  constructor(topic2, originalMessage, options) {
+    super(`Schema validation failed for topic "${topic2}"`, options);
+    this.topic = topic2;
+    this.originalMessage = originalMessage;
+    this.name = "KafkaValidationError";
+    if (options?.cause) this.cause = options.cause;
+  }
+};
+var KafkaRetryExhaustedError = class extends KafkaProcessingError {
+  constructor(topic2, originalMessage, attempts, options) {
+    super(
+      `Message processing failed after ${attempts} attempts on topic "${topic2}"`,
+      topic2,
+      originalMessage,
+      options
+    );
+    this.attempts = attempts;
+    this.name = "KafkaRetryExhaustedError";
+  }
+};
+
+// src/client/kafka.client/producer-ops.ts
+function resolveTopicName(topicOrDescriptor) {
+  if (typeof topicOrDescriptor === "string") return topicOrDescriptor;
+  if (topicOrDescriptor && typeof topicOrDescriptor === "object" && "__topic" in topicOrDescriptor) {
+    return topicOrDescriptor.__topic;
+  }
+  return String(topicOrDescriptor);
+}
+function registerSchema(topicOrDesc, schemaRegistry) {
+  if (topicOrDesc?.__schema) {
+    const topic2 = resolveTopicName(topicOrDesc);
+    schemaRegistry.set(topic2, topicOrDesc.__schema);
+  }
+}
+async function validateMessage(topicOrDesc, message, deps) {
+  const topicName = resolveTopicName(topicOrDesc);
+  if (topicOrDesc?.__schema) {
+    try {
+      return await topicOrDesc.__schema.parse(message);
+    } catch (error) {
+      throw new KafkaValidationError(topicName, message, {
+        cause: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+  }
+  if (deps.strictSchemasEnabled && typeof topicOrDesc === "string") {
+    const schema = deps.schemaRegistry.get(topicOrDesc);
+    if (schema) {
+      try {
+        return await schema.parse(message);
+      } catch (error) {
+        throw new KafkaValidationError(topicName, message, {
+          cause: error instanceof Error ? error : new Error(String(error))
+        });
+      }
+    }
+  }
+  return message;
+}
+async function buildSendPayload(topicOrDesc, messages, deps) {
+  const topic2 = resolveTopicName(topicOrDesc);
+  const builtMessages = await Promise.all(
+    messages.map(async (m) => {
+      const envelopeHeaders = buildEnvelopeHeaders({
+        correlationId: m.correlationId,
+        schemaVersion: m.schemaVersion,
+        eventId: m.eventId,
+        headers: m.headers
+      });
+      for (const inst of deps.instrumentation) {
+        inst.beforeSend?.(topic2, envelopeHeaders);
+      }
+      return {
+        value: JSON.stringify(
+          await validateMessage(topicOrDesc, m.value, deps)
+        ),
+        key: m.key ?? null,
+        headers: envelopeHeaders
+      };
+    })
+  );
+  return { topic: topic2, messages: builtMessages };
+}
+
+// src/client/kafka.client/consumer-ops.ts
+function getOrCreateConsumer(groupId, fromBeginning, autoCommit, deps) {
+  const { consumers, consumerCreationOptions, kafka, onRebalance, logger } = deps;
+  if (consumers.has(groupId)) {
+    const prev = consumerCreationOptions.get(groupId);
+    if (prev.fromBeginning !== fromBeginning || prev.autoCommit !== autoCommit) {
+      logger.warn(
+        `Consumer group "${groupId}" already exists with options (fromBeginning: ${prev.fromBeginning}, autoCommit: ${prev.autoCommit}) \u2014 new options (fromBeginning: ${fromBeginning}, autoCommit: ${autoCommit}) ignored. Use a different groupId to apply different options.`
+      );
+    }
+    return consumers.get(groupId);
+  }
+  consumerCreationOptions.set(groupId, { fromBeginning, autoCommit });
+  const config = {
+    kafkaJS: { groupId, fromBeginning, autoCommit }
+  };
+  if (onRebalance) {
+    const cb = onRebalance;
+    config["rebalance_cb"] = (err, assignment) => {
+      const type = err.code === -175 ? "assign" : "revoke";
+      try {
+        cb(
+          type,
+          assignment.map((p) => ({ topic: p.topic, partition: p.partition }))
+        );
+      } catch (e) {
+        logger.warn(`onRebalance callback threw: ${e.message}`);
+      }
+    };
+  }
+  const consumer = kafka.consumer(config);
+  consumers.set(groupId, consumer);
+  return consumer;
+}
+function buildSchemaMap(topics, schemaRegistry, optionSchemas) {
+  const schemaMap = /* @__PURE__ */ new Map();
+  for (const t of topics) {
+    if (t?.__schema) {
+      const name = resolveTopicName(t);
+      schemaMap.set(name, t.__schema);
+      schemaRegistry.set(name, t.__schema);
+    }
+  }
+  if (optionSchemas) {
+    for (const [k, v] of optionSchemas) {
+      schemaMap.set(k, v);
+      schemaRegistry.set(k, v);
+    }
+  }
+  return schemaMap;
+}
+
+// src/client/consumer/pipeline.ts
+function toError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function parseJsonMessage(raw, topic2, logger) {
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    logger.error(
+      `Failed to parse message from topic ${topic2}:`,
+      toError(error).stack
+    );
+    return null;
+  }
+}
+async function validateWithSchema(message, raw, topic2, schemaMap, interceptors, dlq, deps) {
+  const schema = schemaMap.get(topic2);
+  if (!schema) return message;
+  try {
+    return await schema.parse(message);
+  } catch (error) {
+    const err = toError(error);
+    const validationError = new KafkaValidationError(topic2, message, {
+      cause: err
+    });
+    deps.logger.error(
+      `Schema validation failed for topic ${topic2}:`,
+      err.message
+    );
+    if (dlq) {
+      await sendToDlq(topic2, raw, deps, {
+        error: validationError,
+        attempt: 0,
+        originalHeaders: deps.originalHeaders
+      });
+    } else {
+      await deps.onMessageLost?.({
+        topic: topic2,
+        error: validationError,
+        attempt: 0,
+        headers: deps.originalHeaders ?? {}
+      });
+    }
+    const errorEnvelope = extractEnvelope(
+      message,
+      deps.originalHeaders ?? {},
+      topic2,
+      -1,
+      ""
+    );
+    for (const interceptor of interceptors) {
+      await interceptor.onError?.(errorEnvelope, validationError);
+    }
+    return null;
+  }
+}
+async function sendToDlq(topic2, rawMessage, deps, meta) {
+  const dlqTopic = `${topic2}.dlq`;
+  const headers = {
+    ...meta?.originalHeaders ?? {},
+    "x-dlq-original-topic": topic2,
+    "x-dlq-failed-at": (/* @__PURE__ */ new Date()).toISOString(),
+    "x-dlq-error-message": meta?.error.message ?? "unknown",
+    "x-dlq-error-stack": meta?.error.stack?.slice(0, 2e3) ?? "",
+    "x-dlq-attempt-count": String(meta?.attempt ?? 0)
+  };
+  try {
+    await deps.producer.send({
+      topic: dlqTopic,
+      messages: [{ value: rawMessage, headers }]
+    });
+    deps.logger.warn(`Message sent to DLQ: ${dlqTopic}`);
+  } catch (error) {
+    deps.logger.error(
+      `Failed to send message to DLQ ${dlqTopic}:`,
+      toError(error).stack
+    );
+  }
+}
+var RETRY_HEADER_ATTEMPT = "x-retry-attempt";
+var RETRY_HEADER_AFTER = "x-retry-after";
+var RETRY_HEADER_MAX_RETRIES = "x-retry-max-retries";
+var RETRY_HEADER_ORIGINAL_TOPIC = "x-retry-original-topic";
+async function sendToRetryTopic(originalTopic, rawMessages, attempt, maxRetries, delayMs, originalHeaders, deps) {
+  const retryTopic = `${originalTopic}.retry.${attempt}`;
+  const {
+    [RETRY_HEADER_ATTEMPT]: _a,
+    [RETRY_HEADER_AFTER]: _b,
+    [RETRY_HEADER_MAX_RETRIES]: _c,
+    [RETRY_HEADER_ORIGINAL_TOPIC]: _d,
+    ...userHeaders
+  } = originalHeaders;
+  const headers = {
+    ...userHeaders,
+    [RETRY_HEADER_ATTEMPT]: String(attempt),
+    [RETRY_HEADER_AFTER]: String(Date.now() + delayMs),
+    [RETRY_HEADER_MAX_RETRIES]: String(maxRetries),
+    [RETRY_HEADER_ORIGINAL_TOPIC]: originalTopic
+  };
+  try {
+    for (const raw of rawMessages) {
+      await deps.producer.send({
+        topic: retryTopic,
+        messages: [{ value: raw, headers }]
+      });
+    }
+    deps.logger.warn(
+      `Message queued in retry topic ${retryTopic} (attempt ${attempt}/${maxRetries})`
+    );
+  } catch (error) {
+    deps.logger.error(
+      `Failed to send message to retry topic ${retryTopic}:`,
+      toError(error).stack
+    );
+  }
+}
+async function broadcastToInterceptors(envelopes, interceptors, cb) {
+  for (const env of envelopes) {
+    for (const interceptor of interceptors) {
+      await cb(interceptor, env);
+    }
+  }
+}
+async function runHandlerWithPipeline(fn, envelopes, interceptors, instrumentation) {
+  const cleanups = [];
+  try {
+    for (const env of envelopes) {
+      for (const inst of instrumentation) {
+        const cleanup = inst.beforeConsume?.(env);
+        if (typeof cleanup === "function") cleanups.push(cleanup);
+      }
+    }
+    for (const env of envelopes) {
+      for (const interceptor of interceptors) {
+        await interceptor.before?.(env);
+      }
+    }
+    await fn();
+    for (const env of envelopes) {
+      for (const interceptor of interceptors) {
+        await interceptor.after?.(env);
+      }
+    }
+    for (const cleanup of cleanups) cleanup();
+    return null;
+  } catch (error) {
+    const err = toError(error);
+    for (const env of envelopes) {
+      for (const inst of instrumentation) {
+        inst.onConsumeError?.(env, err);
+      }
+    }
+    for (const cleanup of cleanups) cleanup();
+    return err;
+  }
+}
+async function notifyInterceptorsOnError(envelopes, interceptors, error) {
+  await broadcastToInterceptors(
+    envelopes,
+    interceptors,
+    (i, env) => i.onError?.(env, error)
+  );
+}
+async function executeWithRetry(fn, ctx, deps) {
+  const {
+    envelope,
+    rawMessages,
+    interceptors,
+    dlq,
+    retry,
+    isBatch,
+    retryTopics
+  } = ctx;
+  const maxAttempts = retryTopics ? 1 : retry ? retry.maxRetries + 1 : 1;
+  const backoffMs = retry?.backoffMs ?? 1e3;
+  const maxBackoffMs = retry?.maxBackoffMs ?? 3e4;
+  const envelopes = Array.isArray(envelope) ? envelope : [envelope];
+  const topic2 = envelopes[0]?.topic ?? "unknown";
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const error = await runHandlerWithPipeline(
+      fn,
+      envelopes,
+      interceptors,
+      deps.instrumentation
+    );
+    if (!error) return;
+    const isLastAttempt = attempt === maxAttempts;
+    const reportedError = isLastAttempt && maxAttempts > 1 ? new KafkaRetryExhaustedError(
+      topic2,
+      envelopes.map((e) => e.payload),
+      maxAttempts,
+      { cause: error }
+    ) : error;
+    await notifyInterceptorsOnError(envelopes, interceptors, reportedError);
+    deps.logger.error(
+      `Error processing ${isBatch ? "batch" : "message"} from topic ${topic2} (attempt ${attempt}/${maxAttempts}):`,
+      error.stack
+    );
+    if (retryTopics && retry) {
+      const cap = Math.min(backoffMs, maxBackoffMs);
+      const delay = Math.floor(Math.random() * cap);
+      await sendToRetryTopic(
+        topic2,
+        rawMessages,
+        1,
+        retry.maxRetries,
+        delay,
+        envelopes[0]?.headers ?? {},
+        deps
+      );
+    } else if (isLastAttempt) {
+      if (dlq) {
+        const dlqMeta = {
+          error,
+          attempt,
+          originalHeaders: envelopes[0]?.headers
+        };
+        for (const raw of rawMessages) {
+          await sendToDlq(topic2, raw, deps, dlqMeta);
+        }
+      } else {
+        await deps.onMessageLost?.({
+          topic: topic2,
+          error,
+          attempt,
+          headers: envelopes[0]?.headers ?? {}
+        });
+      }
+    } else {
+      const cap = Math.min(backoffMs * 2 ** (attempt - 1), maxBackoffMs);
+      await sleep(Math.random() * cap);
+    }
+  }
+}
+
+// src/client/kafka.client/message-handler.ts
+async function parseSingleMessage(message, topic2, partition, schemaMap, interceptors, dlq, deps) {
+  if (!message.value) {
+    deps.logger.warn(`Received empty message from topic ${topic2}`);
+    return null;
+  }
+  const raw = message.value.toString();
+  const parsed = parseJsonMessage(raw, topic2, deps.logger);
+  if (parsed === null) return null;
+  const headers = decodeHeaders(message.headers);
+  const validated = await validateWithSchema(
+    parsed,
+    raw,
+    topic2,
+    schemaMap,
+    interceptors,
+    dlq,
+    { ...deps, originalHeaders: headers }
+  );
+  if (validated === null) return null;
+  return extractEnvelope(validated, headers, topic2, partition, message.offset);
+}
+async function handleEachMessage(payload, opts, deps) {
+  const { topic: topic2, partition, message } = payload;
+  const {
+    schemaMap,
+    handleMessage,
+    interceptors,
+    dlq,
+    retry,
+    retryTopics,
+    timeoutMs,
+    wrapWithTimeout
+  } = opts;
+  const envelope = await parseSingleMessage(
+    message,
+    topic2,
+    partition,
+    schemaMap,
+    interceptors,
+    dlq,
+    deps
+  );
+  if (envelope === null) return;
+  await executeWithRetry(
+    () => {
+      const fn = () => runWithEnvelopeContext(
+        {
+          correlationId: envelope.correlationId,
+          traceparent: envelope.traceparent
+        },
+        () => handleMessage(envelope)
+      );
+      return timeoutMs ? wrapWithTimeout(fn, timeoutMs, topic2) : fn();
+    },
+    {
+      envelope,
+      rawMessages: [message.value.toString()],
+      interceptors,
+      dlq,
+      retry,
+      retryTopics
+    },
+    deps
+  );
+}
+async function handleEachBatch(payload, opts, deps) {
+  const { batch, heartbeat, resolveOffset, commitOffsetsIfNecessary } = payload;
+  const {
+    schemaMap,
+    handleBatch,
+    interceptors,
+    dlq,
+    retry,
+    timeoutMs,
+    wrapWithTimeout
+  } = opts;
+  const envelopes = [];
+  const rawMessages = [];
+  for (const message of batch.messages) {
+    const envelope = await parseSingleMessage(
+      message,
+      batch.topic,
+      batch.partition,
+      schemaMap,
+      interceptors,
+      dlq,
+      deps
+    );
+    if (envelope === null) continue;
+    envelopes.push(envelope);
+    rawMessages.push(message.value.toString());
+  }
+  if (envelopes.length === 0) return;
+  const meta = {
+    partition: batch.partition,
+    highWatermark: batch.highWatermark,
+    heartbeat,
+    resolveOffset,
+    commitOffsetsIfNecessary
+  };
+  await executeWithRetry(
+    () => {
+      const fn = () => handleBatch(envelopes, meta);
+      return timeoutMs ? wrapWithTimeout(fn, timeoutMs, batch.topic) : fn();
+    },
+    {
+      envelope: envelopes,
+      rawMessages: batch.messages.filter((m) => m.value).map((m) => m.value.toString()),
+      interceptors,
+      dlq,
+      retry,
+      isBatch: true
+    },
+    deps
+  );
+}
+
+// src/client/consumer/subscribe-retry.ts
+async function subscribeWithRetry(consumer, topics, logger, retryOpts) {
+  const maxAttempts = retryOpts?.retries ?? 5;
+  const backoffMs = retryOpts?.backoffMs ?? 5e3;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      await consumer.subscribe({ topics });
+      return;
+    } catch (error) {
+      if (attempt === maxAttempts) throw error;
+      const msg = toError(error).message;
+      logger.warn(
+        `Failed to subscribe to [${topics.join(", ")}] (attempt ${attempt}/${maxAttempts}): ${msg}. Retrying in ${backoffMs}ms...`
+      );
+      await sleep(backoffMs);
+    }
+  }
+}
+
+// src/client/kafka.client/retry-topic.ts
+async function waitForPartitionAssignment(consumer, topics, logger, timeoutMs = 1e4) {
+  const topicSet = new Set(topics);
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const assigned = consumer.assignment();
+      if (assigned.some((a) => topicSet.has(a.topic))) return;
+    } catch {
+    }
+    await sleep(200);
+  }
+  logger.warn(
+    `Retry consumer did not receive partition assignments for [${topics.join(", ")}] within ${timeoutMs}ms`
+  );
+}
+async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopics, handleMessage, retry, dlq, interceptors, schemaMap, deps, assignmentTimeoutMs) {
+  const {
+    logger,
+    producer,
+    instrumentation,
+    onMessageLost,
+    ensureTopic,
+    getOrCreateConsumer: getOrCreateConsumer2,
+    runningConsumers
+  } = deps;
+  const backoffMs = retry.backoffMs ?? 1e3;
+  const maxBackoffMs = retry.maxBackoffMs ?? 3e4;
+  const pipelineDeps = { logger, producer, instrumentation, onMessageLost };
+  for (const lt of levelTopics) {
+    await ensureTopic(lt);
+  }
+  const consumer = getOrCreateConsumer2(levelGroupId, false, false);
+  await consumer.connect();
+  await subscribeWithRetry(consumer, levelTopics, logger);
+  await consumer.run({
+    eachMessage: async ({ topic: levelTopic, partition, message }) => {
+      const nextOffset = {
+        topic: levelTopic,
+        partition,
+        offset: (parseInt(message.offset, 10) + 1).toString()
+      };
+      if (!message.value) {
+        await consumer.commitOffsets([nextOffset]);
+        return;
+      }
+      const headers = decodeHeaders(message.headers);
+      const retryAfter = parseInt(
+        headers[RETRY_HEADER_AFTER] ?? "0",
+        10
+      );
+      const remaining = retryAfter - Date.now();
+      if (remaining > 0) {
+        consumer.pause([{ topic: levelTopic, partitions: [partition] }]);
+        await sleep(remaining);
+        consumer.resume([{ topic: levelTopic, partitions: [partition] }]);
+      }
+      const raw = message.value.toString();
+      const parsed = parseJsonMessage(raw, levelTopic, logger);
+      if (parsed === null) {
+        await consumer.commitOffsets([nextOffset]);
+        return;
+      }
+      const currentMaxRetries = parseInt(
+        headers[RETRY_HEADER_MAX_RETRIES] ?? String(retry.maxRetries),
+        10
+      );
+      const originalTopic = headers[RETRY_HEADER_ORIGINAL_TOPIC] ?? levelTopic.replace(/\.retry\.\d+$/, "");
+      const validated = await validateWithSchema(
+        parsed,
+        raw,
+        originalTopic,
+        schemaMap,
+        interceptors,
+        dlq,
+        { ...pipelineDeps, originalHeaders: headers }
+      );
+      if (validated === null) {
+        await consumer.commitOffsets([nextOffset]);
+        return;
+      }
+      const envelope = extractEnvelope(
+        validated,
+        headers,
+        originalTopic,
+        partition,
+        message.offset
+      );
+      const error = await runHandlerWithPipeline(
+        () => runWithEnvelopeContext(
+          {
+            correlationId: envelope.correlationId,
+            traceparent: envelope.traceparent
+          },
+          () => handleMessage(envelope)
+        ),
+        [envelope],
+        interceptors,
+        instrumentation
+      );
+      if (!error) {
+        await consumer.commitOffsets([nextOffset]);
+        return;
+      }
+      const exhausted = level >= currentMaxRetries;
+      const reportedError = exhausted && currentMaxRetries > 1 ? new KafkaRetryExhaustedError(
+        originalTopic,
+        [envelope.payload],
+        currentMaxRetries,
+        { cause: error }
+      ) : error;
+      await notifyInterceptorsOnError([envelope], interceptors, reportedError);
+      logger.error(
+        `Retry consumer error for ${originalTopic} (level ${level}/${currentMaxRetries}):`,
+        error.stack
+      );
+      if (!exhausted) {
+        const nextLevel = level + 1;
+        const cap = Math.min(backoffMs * 2 ** level, maxBackoffMs);
+        const delay = Math.floor(Math.random() * cap);
+        await sendToRetryTopic(
+          originalTopic,
+          [raw],
+          nextLevel,
+          currentMaxRetries,
+          delay,
+          headers,
+          pipelineDeps
+        );
+      } else if (dlq) {
+        await sendToDlq(originalTopic, raw, pipelineDeps, {
+          error,
+          // +1 to account for the main consumer's initial attempt before routing.
+          attempt: level + 1,
+          originalHeaders: headers
+        });
+      } else {
+        await onMessageLost?.({
+          topic: originalTopic,
+          error,
+          attempt: level,
+          headers
+        });
+      }
+      await consumer.commitOffsets([nextOffset]);
+    }
+  });
+  runningConsumers.set(levelGroupId, "eachMessage");
+  await waitForPartitionAssignment(consumer, levelTopics, logger, assignmentTimeoutMs);
+  logger.log(
+    `Retry level ${level}/${retry.maxRetries} consumer started for: ${originalTopics.join(", ")} (group: ${levelGroupId})`
+  );
+}
+async function startRetryTopicConsumers(originalTopics, originalGroupId, handleMessage, retry, dlq, interceptors, schemaMap, deps, assignmentTimeoutMs) {
+  const levelGroupIds = [];
+  for (let level = 1; level <= retry.maxRetries; level++) {
+    const levelTopics = originalTopics.map((t) => `${t}.retry.${level}`);
+    const levelGroupId = `${originalGroupId}-retry.${level}`;
+    await startLevelConsumer(
+      level,
+      levelTopics,
+      levelGroupId,
+      originalTopics,
+      handleMessage,
+      retry,
+      dlq,
+      interceptors,
+      schemaMap,
+      deps,
+      assignmentTimeoutMs
+    );
+    levelGroupIds.push(levelGroupId);
+  }
+  return levelGroupIds;
+}
+
+// src/client/kafka.client/index.ts
+var { Kafka: KafkaClass, logLevel: KafkaLogLevel } = KafkaJS;
+var KafkaClient = class {
+  kafka;
+  producer;
+  txProducer;
+  consumers = /* @__PURE__ */ new Map();
+  admin;
+  logger;
+  autoCreateTopicsEnabled;
+  strictSchemasEnabled;
+  numPartitions;
+  ensuredTopics = /* @__PURE__ */ new Set();
+  defaultGroupId;
+  schemaRegistry = /* @__PURE__ */ new Map();
+  runningConsumers = /* @__PURE__ */ new Map();
+  consumerCreationOptions = /* @__PURE__ */ new Map();
+  /** Maps each main consumer groupId to its companion retry level groupIds. */
+  companionGroupIds = /* @__PURE__ */ new Map();
+  instrumentation;
+  onMessageLost;
+  onRebalance;
+  isAdminConnected = false;
+  clientId;
+  constructor(clientId, groupId, brokers, options) {
+    this.clientId = clientId;
+    this.defaultGroupId = groupId;
+    this.logger = options?.logger ?? {
+      log: (msg) => console.log(`[KafkaClient:${clientId}] ${msg}`),
+      warn: (msg, ...args) => console.warn(`[KafkaClient:${clientId}] ${msg}`, ...args),
+      error: (msg, ...args) => console.error(`[KafkaClient:${clientId}] ${msg}`, ...args)
+    };
+    this.autoCreateTopicsEnabled = options?.autoCreateTopics ?? false;
+    this.strictSchemasEnabled = options?.strictSchemas ?? true;
+    this.numPartitions = options?.numPartitions ?? 1;
+    this.instrumentation = options?.instrumentation ?? [];
+    this.onMessageLost = options?.onMessageLost;
+    this.onRebalance = options?.onRebalance;
+    this.kafka = new KafkaClass({
+      kafkaJS: {
+        clientId: this.clientId,
+        brokers,
+        logLevel: KafkaLogLevel.ERROR
+      }
+    });
+    this.producer = this.kafka.producer({
+      kafkaJS: {
+        acks: -1
+      }
+    });
+    this.admin = this.kafka.admin();
+  }
+  async sendMessage(topicOrDesc, message, options = {}) {
+    const payload = await this.preparePayload(topicOrDesc, [
+      {
+        value: message,
+        key: options.key,
+        headers: options.headers,
+        correlationId: options.correlationId,
+        schemaVersion: options.schemaVersion,
+        eventId: options.eventId
+      }
+    ]);
+    await this.producer.send(payload);
+    this.notifyAfterSend(payload.topic, payload.messages.length);
+  }
+  async sendBatch(topicOrDesc, messages) {
+    const payload = await this.preparePayload(topicOrDesc, messages);
+    await this.producer.send(payload);
+    this.notifyAfterSend(payload.topic, payload.messages.length);
+  }
+  /** Execute multiple sends atomically. Commits on success, aborts on error. */
+  async transaction(fn) {
+    if (!this.txProducer) {
+      this.txProducer = this.kafka.producer({
+        kafkaJS: {
+          acks: -1,
+          idempotent: true,
+          transactionalId: `${this.clientId}-tx`,
+          maxInFlightRequests: 1
+        }
+      });
+      await this.txProducer.connect();
+    }
+    const tx = await this.txProducer.transaction();
+    try {
+      const ctx = {
+        send: async (topicOrDesc, message, options = {}) => {
+          const payload = await this.preparePayload(topicOrDesc, [
+            {
+              value: message,
+              key: options.key,
+              headers: options.headers,
+              correlationId: options.correlationId,
+              schemaVersion: options.schemaVersion,
+              eventId: options.eventId
+            }
+          ]);
+          await tx.send(payload);
+        },
+        sendBatch: async (topicOrDesc, messages) => {
+          await tx.send(await this.preparePayload(topicOrDesc, messages));
+        }
+      };
+      await fn(ctx);
+      await tx.commit();
+    } catch (error) {
+      try {
+        await tx.abort();
+      } catch (abortError) {
+        this.logger.error(
+          "Failed to abort transaction:",
+          toError(abortError).message
+        );
+      }
+      throw error;
+    }
+  }
+  // ── Producer lifecycle ───────────────────────────────────────────
+  /** Connect the idempotent producer. Called automatically by `KafkaModule.register()`. */
+  async connectProducer() {
+    await this.producer.connect();
+    this.logger.log("Producer connected");
+  }
+  async disconnectProducer() {
+    await this.producer.disconnect();
+    this.logger.log("Producer disconnected");
+  }
+  async startConsumer(topics, handleMessage, options = {}) {
+    if (options.retryTopics && !options.retry) {
+      throw new Error(
+        "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 timeoutMs = options.handlerTimeoutMs;
+    await consumer.run({
+      eachMessage: (payload) => handleEachMessage(
+        payload,
+        {
+          schemaMap,
+          handleMessage,
+          interceptors,
+          dlq,
+          retry,
+          retryTopics: options.retryTopics,
+          timeoutMs,
+          wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this)
+        },
+        deps
+      )
+    });
+    this.runningConsumers.set(gid, "eachMessage");
+    if (options.retryTopics && retry) {
+      const companions = await startRetryTopicConsumers(
+        topicNames,
+        gid,
+        handleMessage,
+        retry,
+        dlq,
+        interceptors,
+        schemaMap,
+        this.retryTopicDeps,
+        options.retryTopicAssignmentTimeoutMs
+      );
+      this.companionGroupIds.set(gid, companions);
+    }
+    return { groupId: gid, stop: () => this.stopConsumer(gid) };
+  }
+  async startBatchConsumer(topics, handleBatch, options = {}) {
+    const { consumer, schemaMap, gid, dlq, interceptors, retry } = await this.setupConsumer(topics, "eachBatch", options);
+    const deps = this.messageDeps;
+    const timeoutMs = options.handlerTimeoutMs;
+    await consumer.run({
+      eachBatch: (payload) => handleEachBatch(
+        payload,
+        {
+          schemaMap,
+          handleBatch,
+          interceptors,
+          dlq,
+          retry,
+          timeoutMs,
+          wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this)
+        },
+        deps
+      )
+    });
+    this.runningConsumers.set(gid, "eachBatch");
+    return { groupId: gid, stop: () => this.stopConsumer(gid) };
+  }
+  // ── Consumer lifecycle ───────────────────────────────────────────
+  async stopConsumer(groupId) {
+    if (groupId !== void 0) {
+      const consumer = this.consumers.get(groupId);
+      if (!consumer) {
+        this.logger.warn(
+          `stopConsumer: no active consumer for group "${groupId}"`
+        );
+        return;
+      }
+      await consumer.disconnect().catch(() => {
+      });
+      this.consumers.delete(groupId);
+      this.runningConsumers.delete(groupId);
+      this.consumerCreationOptions.delete(groupId);
+      this.logger.log(`Consumer disconnected: group "${groupId}"`);
+      const companions = this.companionGroupIds.get(groupId) ?? [];
+      for (const cGroupId of companions) {
+        const cConsumer = this.consumers.get(cGroupId);
+        if (cConsumer) {
+          await cConsumer.disconnect().catch(() => {
+          });
+          this.consumers.delete(cGroupId);
+          this.runningConsumers.delete(cGroupId);
+          this.consumerCreationOptions.delete(cGroupId);
+          this.logger.log(`Retry consumer disconnected: group "${cGroupId}"`);
+        }
+      }
+      this.companionGroupIds.delete(groupId);
+    } else {
+      const tasks = Array.from(this.consumers.values()).map(
+        (c) => c.disconnect().catch(() => {
+        })
+      );
+      await Promise.allSettled(tasks);
+      this.consumers.clear();
+      this.runningConsumers.clear();
+      this.consumerCreationOptions.clear();
+      this.companionGroupIds.clear();
+      this.logger.log("All consumers disconnected");
+    }
+  }
+  /**
+   * Query consumer group lag per partition.
+   * Lag = broker high-watermark − last committed offset.
+   * A committed offset of -1 (nothing committed yet) counts as full lag.
+   */
+  async getConsumerLag(groupId) {
+    const gid = groupId ?? this.defaultGroupId;
+    if (!this.isAdminConnected) {
+      await this.admin.connect();
+      this.isAdminConnected = true;
+    }
+    const committedByTopic = await this.admin.fetchOffsets({ groupId: gid });
+    const result = [];
+    for (const { topic: topic2, partitions } of committedByTopic) {
+      const brokerOffsets = await this.admin.fetchTopicOffsets(topic2);
+      for (const { partition, offset } of partitions) {
+        const broker = brokerOffsets.find((o) => o.partition === partition);
+        if (!broker) continue;
+        const committed = parseInt(offset, 10);
+        const high = parseInt(broker.high, 10);
+        const lag = committed === -1 ? high : Math.max(0, high - committed);
+        result.push({ topic: topic2, partition, lag });
+      }
+    }
+    return result;
+  }
+  /** Check broker connectivity. Never throws — returns a discriminated union. */
+  async checkStatus() {
+    try {
+      if (!this.isAdminConnected) {
+        await this.admin.connect();
+        this.isAdminConnected = true;
+      }
+      const topics = await this.admin.listTopics();
+      return { status: "up", clientId: this.clientId, topics };
+    } catch (error) {
+      return {
+        status: "down",
+        clientId: this.clientId,
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+  getClientId() {
+    return this.clientId;
+  }
+  /** Gracefully disconnect producer, all consumers, and admin. */
+  async disconnect() {
+    const tasks = [this.producer.disconnect()];
+    if (this.txProducer) {
+      tasks.push(this.txProducer.disconnect());
+      this.txProducer = void 0;
+    }
+    for (const consumer of this.consumers.values()) {
+      tasks.push(consumer.disconnect());
+    }
+    if (this.isAdminConnected) {
+      tasks.push(this.admin.disconnect());
+      this.isAdminConnected = false;
+    }
+    await Promise.allSettled(tasks);
+    this.consumers.clear();
+    this.runningConsumers.clear();
+    this.consumerCreationOptions.clear();
+    this.companionGroupIds.clear();
+    this.logger.log("All connections closed");
+  }
+  // ── Private helpers ──────────────────────────────────────────────
+  async preparePayload(topicOrDesc, messages) {
+    registerSchema(topicOrDesc, this.schemaRegistry);
+    const payload = await buildSendPayload(
+      topicOrDesc,
+      messages,
+      this.producerOpsDeps
+    );
+    await this.ensureTopic(payload.topic);
+    return payload;
+  }
+  // afterSend is called once per message — symmetric with beforeSend in buildSendPayload.
+  notifyAfterSend(topic2, count) {
+    for (let i = 0; i < count; i++) {
+      for (const inst of this.instrumentation) {
+        inst.afterSend?.(topic2);
+      }
+    }
+  }
+  /**
+   * Start a timer that logs a warning if `fn` hasn't resolved within `timeoutMs`.
+   * The handler itself is not cancelled — the warning is diagnostic only.
+   */
+  wrapWithTimeoutWarning(fn, timeoutMs, topic2) {
+    let timer;
+    const promise = fn().finally(() => {
+      if (timer !== void 0) clearTimeout(timer);
+    });
+    timer = setTimeout(() => {
+      this.logger.warn(
+        `Handler for topic "${topic2}" has not resolved after ${timeoutMs}ms \u2014 possible stuck handler`
+      );
+    }, timeoutMs);
+    return promise;
+  }
+  async ensureTopic(topic2) {
+    if (!this.autoCreateTopicsEnabled || this.ensuredTopics.has(topic2)) return;
+    if (!this.isAdminConnected) {
+      await this.admin.connect();
+      this.isAdminConnected = true;
+    }
+    await this.admin.createTopics({
+      topics: [{ topic: topic2, numPartitions: this.numPartitions }]
+    });
+    this.ensuredTopics.add(topic2);
+  }
+  /** Shared consumer setup: groupId check, schema map, connect, subscribe. */
+  async setupConsumer(topics, mode, options) {
+    const {
+      groupId: optGroupId,
+      fromBeginning = false,
+      retry,
+      dlq = false,
+      interceptors = [],
+      schemas: optionSchemas
+    } = options;
+    const gid = optGroupId || this.defaultGroupId;
+    const existingMode = this.runningConsumers.get(gid);
+    const oppositeMode = mode === "eachMessage" ? "eachBatch" : "eachMessage";
+    if (existingMode === oppositeMode) {
+      throw new Error(
+        `Cannot use ${mode} on consumer group "${gid}" \u2014 it is already running with ${oppositeMode}. Use a different groupId for this consumer.`
+      );
+    }
+    const consumer = getOrCreateConsumer(
+      gid,
+      fromBeginning,
+      options.autoCommit ?? true,
+      this.consumerOpsDeps
+    );
+    const schemaMap = buildSchemaMap(
+      topics,
+      this.schemaRegistry,
+      optionSchemas
+    );
+    const topicNames = topics.map((t) => resolveTopicName(t));
+    for (const t of topicNames) {
+      await this.ensureTopic(t);
+    }
+    if (dlq) {
+      for (const t of topicNames) {
+        await this.ensureTopic(`${t}.dlq`);
+      }
+    }
+    await consumer.connect();
+    await subscribeWithRetry(
+      consumer,
+      topicNames,
+      this.logger,
+      options.subscribeRetry
+    );
+    this.logger.log(
+      `${mode === "eachBatch" ? "Batch consumer" : "Consumer"} subscribed to topics: ${topicNames.join(", ")}`
+    );
+    return { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry };
+  }
+  // ── Deps object getters ──────────────────────────────────────────
+  get producerOpsDeps() {
+    return {
+      schemaRegistry: this.schemaRegistry,
+      strictSchemasEnabled: this.strictSchemasEnabled,
+      instrumentation: this.instrumentation
+    };
+  }
+  get consumerOpsDeps() {
+    return {
+      consumers: this.consumers,
+      consumerCreationOptions: this.consumerCreationOptions,
+      kafka: this.kafka,
+      onRebalance: this.onRebalance,
+      logger: this.logger
+    };
+  }
+  get messageDeps() {
+    return {
+      logger: this.logger,
+      producer: this.producer,
+      instrumentation: this.instrumentation,
+      onMessageLost: this.onMessageLost
+    };
+  }
+  get retryTopicDeps() {
+    return {
+      logger: this.logger,
+      producer: this.producer,
+      instrumentation: this.instrumentation,
+      onMessageLost: this.onMessageLost,
+      ensureTopic: (t) => this.ensureTopic(t),
+      getOrCreateConsumer: (gid, fb, ac) => getOrCreateConsumer(gid, fb, ac, this.consumerOpsDeps),
+      runningConsumers: this.runningConsumers
+    };
+  }
+};
+
+// src/client/message/topic.ts
+function topic(name) {
+  return {
+    /** Provide an explicit message type without a runtime schema. */
+    type: () => ({
+      __topic: name,
+      __type: void 0
+    }),
+    schema: (schema) => ({
+      __topic: name,
+      __type: void 0,
+      __schema: schema
+    })
+  };
+}
+
+export {
+  HEADER_EVENT_ID,
+  HEADER_CORRELATION_ID,
+  HEADER_TIMESTAMP,
+  HEADER_SCHEMA_VERSION,
+  HEADER_TRACEPARENT,
+  getEnvelopeContext,
+  runWithEnvelopeContext,
+  buildEnvelopeHeaders,
+  decodeHeaders,
+  extractEnvelope,
+  KafkaProcessingError,
+  KafkaValidationError,
+  KafkaRetryExhaustedError,
+  KafkaClient,
+  topic
+};
+//# sourceMappingURL=chunk-TD2AE774.mjs.map