@eventferry/kafka 3.3.1 → 3.4.0

package/dist/consume.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/consume.ts"],"sourcesContent":["/**\n * Consumer-side helpers — paired with the publisher's outbound surface.\n *\n * eventferry is a publisher-only library, but the messages it produces are\n * consumed somewhere downstream. This module normalizes the message shape\n * that both `kafkajs` and `@confluentinc/kafka-javascript` deliver to\n * consumer callbacks, decodes the payload, and extracts the W3C trace\n * context the publisher injected (see {@link KafkaTracer.inject}).\n *\n * Imported via subpath so consumer code paths don't pull in the producer:\n *\n *   import { decode, extractTraceContext } from \"@eventferry/kafka/consume\";\n *\n * There is intentionally NO Kafka client here — bring your own consumer\n * (kafkajs's `Consumer`, librdkafka's, whatever) and call `decode()` /\n * `extractTraceContext()` on the message you receive.\n */\n\n/**\n * Raw incoming Kafka message — structural subset both kafkajs and confluent\n * (via the kafkaJS-compat layer) deliver. Fields are optional because\n * different consumer APIs surface different subsets.\n */\nexport interface IncomingKafkaMessage {\n  key?: Buffer | string | null;\n  value?: Buffer | string | null;\n  headers?: IncomingHeaders;\n  /** ISO ms string or numeric epoch ms — depends on the client. */\n  timestamp?: string | number;\n  /** Numeric or string per client. */\n  offset?: string | number;\n  partition?: number;\n}\n\n/** Headers as the underlying clients deliver them: bytes, strings, or undefined. */\nexport type IncomingHeaders = Record<string, Buffer | string | undefined>;\n\n/** Headers normalized to UTF-8 strings (the form most application code wants). */\nexport type DecodedHeaders = Record<string, string>;\n\n/** Payload decoder. Buffer in, decoded value out. */\nexport type Decoder<T> = (bytes: Buffer) => T;\n\n/** Decoded message wrapper — value plus normalized headers, key, metadata. */\nexport interface DecodedMessage<V = unknown> {\n  key: string | null;\n  value: V | null;\n  headers: DecodedHeaders;\n  /** Epoch ms when the broker stamped the record. */\n  timestamp?: number;\n  /** Stringified offset (Kafka offsets exceed 2^53 — strings stay safe). */\n  offset?: string;\n  partition?: number;\n}\n\nexport interface DecodeOptions<V> {\n  /**\n   * Decoder for the payload bytes. Built-ins:\n   *\n   * - `\"json\"` (default) — `JSON.parse(value.toString(\"utf8\"))`. Empty\n   *   value returns `null` (matches Kafka tombstones on compacted topics).\n   * - `\"utf8\"` — raw text. Returns the string as-is.\n   * - `\"none\"` — returns the raw `Buffer` unchanged.\n   *\n   * Or pass your own `(bytes: Buffer) => V` for Avro / Protobuf / MessagePack.\n   */\n  decoder?: \"json\" | \"utf8\" | \"none\" | Decoder<V>;\n}\n\n/**\n * Normalize headers to a plain string→string map. Buffers are read as UTF-8;\n * `undefined` entries are dropped (consumers occasionally surface absent\n * headers as `undefined` values).\n */\nexport function decodeHeaders(raw?: IncomingHeaders): DecodedHeaders {\n  if (!raw) return {};\n  const out: DecodedHeaders = {};\n  for (const [k, v] of Object.entries(raw)) {\n    if (v === undefined || v === null) continue;\n    out[k] = Buffer.isBuffer(v) ? v.toString(\"utf8\") : v;\n  }\n  return out;\n}\n\n/**\n * Decode a Kafka message: normalize the key + headers, decode the value\n * with the chosen decoder, and surface the broker metadata.\n *\n * Tombstones (null/empty value) come back with `value: null` regardless of\n * the decoder — compaction-friendly.\n *\n * @throws when `decoder: \"json\"` (the default) and the payload is non-empty\n *   but not valid JSON. Catch the error and decide whether to DLQ the\n *   record or skip it — eventferry does not assume.\n */\nexport function decode<V = unknown>(\n  msg: IncomingKafkaMessage,\n  opts: DecodeOptions<V> = {},\n): DecodedMessage<V> {\n  const headers = decodeHeaders(msg.headers);\n  const key = normalizeKey(msg.key);\n  const value = decodeValue<V>(msg.value, opts.decoder ?? \"json\");\n  const timestamp =\n    msg.timestamp !== undefined ? Number(msg.timestamp) : undefined;\n  const offset = msg.offset !== undefined ? String(msg.offset) : undefined;\n  return {\n    key,\n    value,\n    headers,\n    timestamp,\n    offset,\n    partition: msg.partition,\n  };\n}\n\nfunction normalizeKey(key?: Buffer | string | null): string | null {\n  if (key === null || key === undefined) return null;\n  return Buffer.isBuffer(key) ? key.toString(\"utf8\") : key;\n}\n\nfunction decodeValue<V>(\n  value: Buffer | string | null | undefined,\n  decoder: DecodeOptions<V>[\"decoder\"],\n): V | null {\n  if (value === null || value === undefined) return null;\n  const buf = Buffer.isBuffer(value) ? value : Buffer.from(value);\n  // Tombstones: an empty buffer is a kafka \"delete me\" on compacted\n  // topics. Surface as null for every decoder — applications usually\n  // want the same null-handling for both.\n  if (buf.length === 0) return null;\n  if (typeof decoder === \"function\") return decoder(buf);\n  switch (decoder) {\n    case \"utf8\":\n      return buf.toString(\"utf8\") as unknown as V;\n    case \"none\":\n      return buf as unknown as V;\n    case \"json\":\n    case undefined:\n    default: {\n      const text = buf.toString(\"utf8\");\n      try {\n        return JSON.parse(text) as V;\n      } catch (err) {\n        throw new Error(\n          `decode: JSON.parse failed on message value: ${(err as Error).message}`,\n        );\n      }\n    }\n  }\n}\n\n/**\n * W3C Trace Context extracted from message headers.\n *\n * - `traceparent`: full header value, format `version-traceId-spanId-flags`.\n * - `tracestate`: optional vendor-specific state (W3C `tracestate` header).\n * - `traceId`: 32 hex chars, parsed from `traceparent`.\n * - `spanId`: 16 hex chars (the PARENT span id from the producer).\n * - `sampled`: parsed from the `traceparent` flags (bit 0 = sampled).\n *\n * Returns `null` when no `traceparent` header is present or the value\n * fails W3C validation.\n *\n * Spec: https://www.w3.org/TR/trace-context/\n */\nexport interface TraceContext {\n  traceparent: string;\n  tracestate?: string;\n  traceId: string;\n  spanId: string;\n  sampled: boolean;\n}\n\nconst TRACEPARENT_RE =\n  /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;\nconst INVALID_TRACE_ID = \"0\".repeat(32);\nconst INVALID_SPAN_ID = \"0\".repeat(16);\n\n/**\n * Extract the W3C trace context the publisher injected into headers.\n * Headers may be raw (Buffer values) or already-decoded (string values) —\n * both shapes work, so you can call this before OR after `decode()`.\n *\n * Validation follows the W3C spec strictly: invalid all-zero trace/span\n * IDs are rejected, version `ff` is rejected, malformed hex is rejected.\n * On any of these, the function returns `null` rather than throwing —\n * consumer code should fall back to starting a fresh trace.\n */\nexport function extractTraceContext(\n  headers: IncomingHeaders | DecodedHeaders | undefined,\n): TraceContext | null {\n  if (!headers) return null;\n  const tp = readHeader(headers, \"traceparent\");\n  if (!tp) return null;\n  const match = TRACEPARENT_RE.exec(tp);\n  if (!match) return null;\n  const [, version, traceId, spanId, flags] = match as unknown as [\n    string,\n    string,\n    string,\n    string,\n    string,\n  ];\n  // Spec §3.2.2.5: version \"ff\" is forbidden (reserved sentinel).\n  if (version === \"ff\") return null;\n  if (traceId === INVALID_TRACE_ID || spanId === INVALID_SPAN_ID) return null;\n  const sampled = (parseInt(flags, 16) & 0x01) === 1;\n  const ts = readHeader(headers, \"tracestate\");\n  return {\n    traceparent: tp,\n    tracestate: ts && ts.length > 0 ? ts : undefined,\n    traceId,\n    spanId,\n    sampled,\n  };\n}\n\nfunction readHeader(\n  headers: IncomingHeaders | DecodedHeaders,\n  name: string,\n): string | undefined {\n  const v = (headers as Record<string, Buffer | string | undefined>)[name];\n  if (v === undefined || v === null) return undefined;\n  if (typeof v === \"string\") return v;\n  if (Buffer.isBuffer(v)) return v.toString(\"utf8\");\n  return undefined;\n}\n"],"mappings":";AA0EO,SAAS,cAAc,KAAuC;AACnE,MAAI,CAAC,IAAK,QAAO,CAAC;AAClB,QAAM,MAAsB,CAAC;AAC7B,aAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,GAAG,GAAG;AACxC,QAAI,MAAM,UAAa,MAAM,KAAM;AACnC,QAAI,CAAC,IAAI,OAAO,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,IAAI;AAAA,EACrD;AACA,SAAO;AACT;AAaO,SAAS,OACd,KACA,OAAyB,CAAC,GACP;AACnB,QAAM,UAAU,cAAc,IAAI,OAAO;AACzC,QAAM,MAAM,aAAa,IAAI,GAAG;AAChC,QAAM,QAAQ,YAAe,IAAI,OAAO,KAAK,WAAW,MAAM;AAC9D,QAAM,YACJ,IAAI,cAAc,SAAY,OAAO,IAAI,SAAS,IAAI;AACxD,QAAM,SAAS,IAAI,WAAW,SAAY,OAAO,IAAI,MAAM,IAAI;AAC/D,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,WAAW,IAAI;AAAA,EACjB;AACF;AAEA,SAAS,aAAa,KAA6C;AACjE,MAAI,QAAQ,QAAQ,QAAQ,OAAW,QAAO;AAC9C,SAAO,OAAO,SAAS,GAAG,IAAI,IAAI,SAAS,MAAM,IAAI;AACvD;AAEA,SAAS,YACP,OACA,SACU;AACV,MAAI,UAAU,QAAQ,UAAU,OAAW,QAAO;AAClD,QAAM,MAAM,OAAO,SAAS,KAAK,IAAI,QAAQ,OAAO,KAAK,KAAK;AAI9D,MAAI,IAAI,WAAW,EAAG,QAAO;AAC7B,MAAI,OAAO,YAAY,WAAY,QAAO,QAAQ,GAAG;AACrD,UAAQ,SAAS;AAAA,IACf,KAAK;AACH,aAAO,IAAI,SAAS,MAAM;AAAA,IAC5B,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AAAA,IACL,KAAK;AAAA,IACL,SAAS;AACP,YAAM,OAAO,IAAI,SAAS,MAAM;AAChC,UAAI;AACF,eAAO,KAAK,MAAM,IAAI;AAAA,MACxB,SAAS,KAAK;AACZ,cAAM,IAAI;AAAA,UACR,+CAAgD,IAAc,OAAO;AAAA,QACvE;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;AAwBA,IAAM,iBACJ;AACF,IAAM,mBAAmB,IAAI,OAAO,EAAE;AACtC,IAAM,kBAAkB,IAAI,OAAO,EAAE;AAY9B,SAAS,oBACd,SACqB;AACrB,MAAI,CAAC,QAAS,QAAO;AACrB,QAAM,KAAK,WAAW,SAAS,aAAa;AAC5C,MAAI,CAAC,GAAI,QAAO;AAChB,QAAM,QAAQ,eAAe,KAAK,EAAE;AACpC,MAAI,CAAC,MAAO,QAAO;AACnB,QAAM,CAAC,EAAE,SAAS,SAAS,QAAQ,KAAK,IAAI;AAQ5C,MAAI,YAAY,KAAM,QAAO;AAC7B,MAAI,YAAY,oBAAoB,WAAW,gBAAiB,QAAO;AACvE,QAAM,WAAW,SAAS,OAAO,EAAE,IAAI,OAAU;AACjD,QAAM,KAAK,WAAW,SAAS,YAAY;AAC3C,SAAO;AAAA,IACL,aAAa;AAAA,IACb,YAAY,MAAM,GAAG,SAAS,IAAI,KAAK;AAAA,IACvC;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAEA,SAAS,WACP,SACA,MACoB;AACpB,QAAM,IAAK,QAAwD,IAAI;AACvE,MAAI,MAAM,UAAa,MAAM,KAAM,QAAO;AAC1C,MAAI,OAAO,MAAM,SAAU,QAAO;AAClC,MAAI,OAAO,SAAS,CAAC,EAAG,QAAO,EAAE,SAAS,MAAM;AAChD,SAAO;AACT;","names":[]}

package/dist/index.cjs

@@ -148,7 +148,10 @@ var UNSUPPORTED_BY_KAFKAJS = [
   "lingerMs",
   "batchSize",
   "deliveryTimeoutMs",
-  "maxRequestSize"
+  "maxRequestSize",
+  // Confluent-only escape hatches; ignored on kafkajs.
+  "compressionLevel",
+  "rawProducerConfig"
 ];
 var KafkaJsDriver = class {
   transactional;
@@ -187,13 +190,21 @@ var KafkaJsDriver = class {
       // the provider's returned token (other fields are ignored).
       sasl: this.opts.sasl
     });
-    const createPartitioner = resolveCreatePartitioner(
-      mod.Partitioners,
+    return kafka.producer(await this.buildProducerOptions(mod.Partitioners));
+  }
+  /**
+   * Compute the options object passed to `kafka.producer({...})`. Exposed
+   * as a test seam so power-user escape hatches (customPartitioner,
+   * rawKafkaJsProducerConfig) can be asserted without a live broker.
+   */
+  async buildProducerOptions(partitioners) {
+    const createPartitioner = this.opts.customPartitioner ?? resolveCreatePartitioner(
+      partitioners,
       this.opts.partitioner,
       this.transactional
     );
     const resolvedTxId = this.transactional ? await resolveTransactionalId(this.opts.transactionalId) : void 0;
-    return kafka.producer({
+    return {
       idempotent: this.opts.idempotent ?? true,
       // Idempotent / transactional producers cap maxInFlight at 5. When the
       // user picks transactional we force 1 to keep strict ordering across
@@ -207,13 +218,32 @@ var KafkaJsDriver = class {
       transactionTimeout: this.opts.transactionTimeoutMs,
       // Setting any partitioner choice silences kafkajs's
       // KafkaJSPartitionerNotSpecified warning.
-      createPartitioner
-    });
+      createPartitioner,
+      // Power-user escape hatch — merged LAST so raw keys win against the
+      // translated ones. That's the contract: anything you put here is
+      // final, even if it overrides idempotent/transactionalId/etc.
+      ...this.opts.rawKafkaJsProducerConfig ?? {}
+    };
   }
   async disconnect() {
     await this.producer?.disconnect();
     this.producer = null;
   }
+  /**
+   * Construct a kafkajs admin client wrapped in the eventferry-facing
+   * `KafkaDriverAdmin` shape. The publisher calls `.connect()` on the
+   * returned object before exposing it via `publisher.admin()`.
+   */
+  async admin() {
+    const mod = await importKafkaJs();
+    const kafka = new mod.Kafka({
+      clientId: this.opts.clientId ?? "eventferry-admin",
+      brokers: this.opts.brokers,
+      ssl: this.opts.ssl,
+      sasl: this.opts.sasl
+    });
+    return new KafkaJsAdmin(kafka.admin());
+  }
   async sendBatch(messages) {
     if (!this.producer) throw new Error("KafkaJsDriver not connected");
     const topicMessages = groupByTopic(messages, this.opts.compression);
@@ -302,6 +332,69 @@ function warnUnsupportedKafkajsOptions(opts) {
 function _resetKafkajsWarnDedup() {
   warnedKafkajsKeys.clear();
 }
+var KafkaJsAdmin = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async connect() {
+    await this.client.connect();
+  }
+  async close() {
+    await this.client.disconnect();
+  }
+  async listTopics() {
+    return await this.client.listTopics();
+  }
+  async describeTopics(topics) {
+    if (topics.length === 0) return [];
+    const all = new Set(await this.client.listTopics());
+    const existing = topics.filter((t) => all.has(t));
+    const missing = topics.filter((t) => !all.has(t));
+    const meta = existing.length ? await this.client.fetchTopicMetadata({ topics: existing }) : { topics: [] };
+    const byName = new Map(meta.topics.map((t) => [t.name, t]));
+    return topics.map((topic) => {
+      if (missing.includes(topic)) return { topic, partitions: [] };
+      const found = byName.get(topic);
+      if (!found) return { topic, partitions: [] };
+      return {
+        topic,
+        partitions: found.partitions.map((p) => ({
+          partitionId: p.partitionId,
+          leader: p.leader,
+          replicas: p.replicas,
+          isr: p.isr
+        }))
+      };
+    });
+  }
+  async createTopics(specs) {
+    if (specs.length === 0) return;
+    const topics = specs.map((s) => ({
+      topic: s.topic,
+      numPartitions: s.numPartitions,
+      replicationFactor: s.replicationFactor,
+      configEntries: s.configEntries ? Object.entries(s.configEntries).map(([name, value]) => ({ name, value })) : void 0
+    }));
+    try {
+      await this.client.createTopics({ topics, waitForLeaders: true });
+    } catch (err) {
+      const e = err;
+      if (e?.type === "TOPIC_ALREADY_EXISTS") return;
+      if (/already exists/i.test(e?.message ?? "")) return;
+      throw err;
+    }
+  }
+  async createPartitions(specs) {
+    if (specs.length === 0) return;
+    await this.client.createPartitions({
+      topicPartitions: specs.map((s) => ({
+        topic: s.topic,
+        count: s.totalCount
+      }))
+    });
+  }
+};
 async function importKafkaJs() {
   try {
     return await import("kafkajs");
@@ -434,6 +527,9 @@ function buildConfluentClientConfig(opts) {
   if (opts.transactionTimeoutMs !== void 0) {
     librdkafka["transaction.timeout.ms"] = opts.transactionTimeoutMs;
   }
+  if (opts.compressionLevel !== void 0) {
+    librdkafka["compression.level"] = opts.compressionLevel;
+  }
   const tlsRequested = opts.ssl === true || isTlsConfig(opts.ssl);
   const saslRequested = !!opts.sasl;
   if (saslRequested && tlsRequested) {
@@ -463,6 +559,9 @@ function buildConfluentClientConfig(opts) {
   if (opts.sasl) {
     kafkaJS["sasl"] = opts.sasl;
   }
+  if (opts.rawProducerConfig) {
+    Object.assign(librdkafka, opts.rawProducerConfig);
+  }
   return { kafkaJS, librdkafka };
 }
 function isTlsConfig(v) {
@@ -516,6 +615,17 @@ var ConfluentDriver = class {
     await this.producer?.disconnect();
     this.producer = null;
   }
+  /**
+   * Construct a librdkafka-backed admin client wrapped in the eventferry
+   * `KafkaDriverAdmin` shape. The publisher's `connect()` is called before
+   * the admin reaches the user.
+   */
+  async admin() {
+    const mod = await importConfluent();
+    const { kafkaJS, librdkafka } = buildConfluentClientConfig(this.opts);
+    const kafka = new mod.KafkaJS.Kafka({ kafkaJS, ...librdkafka });
+    return new ConfluentAdmin(kafka.admin());
+  }
   async sendBatch(messages) {
     if (!this.producer) throw new Error("ConfluentDriver not connected");
     const topicMessages = groupByTopic2(messages);
@@ -584,6 +694,69 @@ function groupByTopic2(messages) {
     messages: msgs
   }));
 }
+var ConfluentAdmin = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async connect() {
+    await this.client.connect();
+  }
+  async close() {
+    await this.client.disconnect();
+  }
+  async listTopics() {
+    return await this.client.listTopics();
+  }
+  async describeTopics(topics) {
+    if (topics.length === 0) return [];
+    const all = new Set(await this.client.listTopics());
+    const existing = topics.filter((t) => all.has(t));
+    const missing = topics.filter((t) => !all.has(t));
+    const meta = existing.length ? await this.client.fetchTopicMetadata({ topics: existing }) : { topics: [] };
+    const byName = new Map(meta.topics.map((t) => [t.name, t]));
+    return topics.map((topic) => {
+      if (missing.includes(topic)) return { topic, partitions: [] };
+      const found = byName.get(topic);
+      if (!found) return { topic, partitions: [] };
+      return {
+        topic,
+        partitions: found.partitions.map((p) => ({
+          partitionId: p.partitionId,
+          leader: p.leader,
+          replicas: p.replicas,
+          isr: p.isr
+        }))
+      };
+    });
+  }
+  async createTopics(specs) {
+    if (specs.length === 0) return;
+    const topics = specs.map((s) => ({
+      topic: s.topic,
+      numPartitions: s.numPartitions,
+      replicationFactor: s.replicationFactor,
+      configEntries: s.configEntries ? Object.entries(s.configEntries).map(([name, value]) => ({ name, value })) : void 0
+    }));
+    try {
+      await this.client.createTopics({ topics, waitForLeaders: true });
+    } catch (err) {
+      const e = err;
+      if (e?.code === 36 || e?.name === "TOPIC_ALREADY_EXISTS") return;
+      if (/already exists/i.test(e?.message ?? "")) return;
+      throw err;
+    }
+  }
+  async createPartitions(specs) {
+    if (specs.length === 0) return;
+    await this.client.createPartitions({
+      topicPartitions: specs.map((s) => ({
+        topic: s.topic,
+        count: s.totalCount
+      }))
+    });
+  }
+};
 async function importConfluent() {
   try {
     return await import("@confluentinc/kafka-javascript");
@@ -634,10 +807,12 @@ var KafkaPublisher = class {
   logger;
   hooks;
   tracer;
+  validateTopicsOnConnect;
   constructor(opts) {
     this.logger = opts.logger;
     this.hooks = opts.hooks ?? {};
     this.tracer = opts.tracer ?? new NoopKafkaTracer();
+    this.validateTopicsOnConnect = opts.validateTopicsOnConnect ? Object.freeze([...opts.validateTopicsOnConnect]) : void 0;
     const onTransactionAbort = this.hooks.onTransactionAbort ? (error) => {
       void safeHook(
         this.logger,
@@ -649,8 +824,90 @@ var KafkaPublisher = class {
   }
   async connect() {
     await this.driver.connect();
+    if (this.validateTopicsOnConnect && this.validateTopicsOnConnect.length) {
+      await this.assertTopicsExist(this.validateTopicsOnConnect);
+    }
     await safeHook(this.logger, "onConnect", () => this.hooks.onConnect?.());
   }
+  /**
+   * Borrow a new admin client from the driver. The returned admin is
+   * connected and ready to use; the CALLER must `close()` it. Throws if the
+   * driver does not implement admin (custom driver lacking the capability).
+   */
+  async admin() {
+    const driverAdmin = await this.openDriverAdmin();
+    return driverAdmin;
+  }
+  /**
+   * Idempotently provision topics. Each spec creates the topic if absent;
+   * existing topics are skipped without error. If `growPartitions: true`
+   * (default false), topics whose current partition count is below the
+   * requested `numPartitions` are grown via `createPartitions`.
+   *
+   * Replication factor and config entries on EXISTING topics are NOT
+   * reconciled — Kafka does not provide a safe in-place alter for those
+   * (changing replication requires reassignment; configs use alterConfigs).
+   * Reach for the raw admin if you need that.
+   */
+  async ensureTopics(specs, opts = {}) {
+    if (specs.length === 0) return;
+    const admin = await this.openDriverAdmin();
+    try {
+      const topicNames = specs.map((s) => s.topic);
+      const existing = await admin.describeTopics(topicNames);
+      const existingByName = new Map(existing.map((t) => [t.topic, t]));
+      const toCreate = specs.filter(
+        (s) => (existingByName.get(s.topic)?.partitions.length ?? 0) === 0
+      );
+      if (toCreate.length) await admin.createTopics(toCreate);
+      if (opts.growPartitions) {
+        const grow = [];
+        for (const s of specs) {
+          if (s.numPartitions === void 0) continue;
+          const current = existingByName.get(s.topic);
+          const currentCount = current?.partitions.length ?? 0;
+          if (currentCount > 0 && currentCount < s.numPartitions) {
+            grow.push({ topic: s.topic, totalCount: s.numPartitions });
+          }
+        }
+        if (grow.length) await admin.createPartitions(grow);
+      }
+    } finally {
+      await admin.close();
+    }
+  }
+  /**
+   * Borrow a fresh admin from the driver and connect it. Throws when the
+   * driver does not implement admin (custom drivers without that capability).
+   */
+  async openDriverAdmin() {
+    if (!this.driver.admin) {
+      throw new Error(
+        "KafkaPublisher: configured driver does not implement admin(). Use the built-in kafkajs or confluent driver, or extend your custom driver."
+      );
+    }
+    const admin = await this.driver.admin();
+    await admin.connect();
+    return admin;
+  }
+  /**
+   * Open an admin, list topics, throw if any required topic is missing.
+   * Always closes the admin (success or failure).
+   */
+  async assertTopicsExist(required) {
+    const admin = await this.openDriverAdmin();
+    try {
+      const all = new Set(await admin.listTopics());
+      const missing = required.filter((t) => !all.has(t));
+      if (missing.length) {
+        throw new Error(
+          `KafkaPublisher: validateTopicsOnConnect failed \u2014 topics missing on cluster: ${missing.join(", ")}`
+        );
+      }
+    } finally {
+      await admin.close();
+    }
+  }
   async disconnect() {
     await this.driver.disconnect();
     await safeHook(
@@ -662,9 +919,14 @@ var KafkaPublisher = class {
   async publish(messages) {
     if (messages.length === 0) return [];
     const span = this.startBatchSpan(messages);
+    const outgoing = this.tracer.inject ? messages.map((m) => {
+      const headers = { ...m.headers };
+      this.tracer.inject(span, headers);
+      return { ...m, headers };
+    }) : messages;
     let results;
     try {
-      results = await this.driver.sendBatch(messages);
+      results = await this.driver.sendBatch(outgoing);
     } catch (err) {
       const error = err instanceof Error ? err : new Error(String(err));
       span.setStatus({ code: "error", message: error.message });