@eventferry/kafka 3.3.0 → 3.4.0

package/dist/index.d.ts

@@ -1,5 +1,97 @@
 import { PublishableMessage, PublishResult, Logger, PublishErrorKind, Publisher } from '@eventferry/core';
 
+/**
+ * Admin surface for `KafkaPublisher`. A typed wrapper over each driver's
+ * underlying admin client — implementations live in `kafkajs-driver.ts` and
+ * `confluent-driver.ts`. The publisher exposes this via `publisher.admin()`
+ * (returns a connected admin) and `publisher.ensureTopics()` (idempotent
+ * topic provisioning built on top).
+ *
+ * Scope is deliberately the most-used subset of the Kafka AdminClient
+ * protocol — listing, describing, creating topics and partitions. ACL
+ * management, quota inspection, and consumer-group operations are left to
+ * the underlying client (reach for kafkajs's `Admin` directly if needed).
+ */
+/** Specification for creating one topic. */
+interface TopicCreateSpec {
+    topic: string;
+    /** Default: cluster's `num.partitions` broker setting. */
+    numPartitions?: number;
+    /** Default: cluster's `default.replication.factor` broker setting. */
+    replicationFactor?: number;
+    /**
+     * Per-topic config entries (e.g. `{ "retention.ms": "604800000" }`).
+     * See Kafka broker docs for the full set.
+     */
+    configEntries?: Record<string, string>;
+}
+/** Topic + partition descriptor returned by describeTopics. */
+interface TopicMetadata {
+    topic: string;
+    /** Empty when the topic doesn't exist (so callers can detect absence cheaply). */
+    partitions: PartitionMetadata[];
+}
+interface PartitionMetadata {
+    partitionId: number;
+    /** Broker id of the partition leader; -1 if no leader is known. */
+    leader: number;
+    /** Replica broker ids. */
+    replicas: number[];
+    /** In-sync replica broker ids. */
+    isr: number[];
+}
+/** Specification for growing a topic's partition count (never shrink). */
+interface PartitionGrowSpec {
+    topic: string;
+    /** Total partition count after the change. MUST be ≥ the current count. */
+    totalCount: number;
+}
+/**
+ * Typed admin surface exposed by {@link KafkaPublisher.admin}.
+ *
+ * The returned object is already connected — call `.close()` (or let the
+ * publisher's `disconnect()` cascade close it) when done.
+ *
+ * All methods may throw native errors from the underlying client. The
+ * publisher does not classify admin errors via the `errorKind` machinery
+ * because admin failures are operator-facing and don't flow through the
+ * relay's retry path.
+ */
+interface KafkaAdmin {
+    /** All topic names visible to this principal, including internal topics. */
+    listTopics(): Promise<string[]>;
+    /**
+     * Metadata for the given topics. Topics that don't exist on the cluster
+     * are returned with an empty `partitions` array — callers detect absence
+     * cheaply without a try/catch.
+     */
+    describeTopics(topics: string[]): Promise<TopicMetadata[]>;
+    /**
+     * Create topics. Idempotent at this layer: topics that already exist are
+     * silently skipped (the underlying client may throw `TopicExistsError`;
+     * we swallow it). Use `ensureTopics` on the publisher for partition-count
+     * + replication-factor coherence checks.
+     */
+    createTopics(specs: TopicCreateSpec[]): Promise<void>;
+    /**
+     * Grow each topic's partition count. Never shrinks (Kafka does not
+     * support shrinking partitions). Specs whose `totalCount` equals the
+     * current partition count are silently skipped.
+     */
+    createPartitions(specs: PartitionGrowSpec[]): Promise<void>;
+    /** Disconnect the admin client. */
+    close(): Promise<void>;
+}
+/**
+ * Optional driver-level hook returned by {@link KafkaDriver.admin}. Drivers
+ * implement this thin contract; the publisher composes the higher-level
+ * `KafkaAdmin` and `ensureTopics` on top.
+ */
+interface KafkaDriverAdmin extends KafkaAdmin {
+    /** Called by the publisher before any method is invoked. */
+    connect(): Promise<void>;
+}
+
 /**
  * Low-level driver contract. Each concrete driver (kafkajs, confluent)
  * adapts its native client to this minimal surface. The KafkaPublisher
@@ -19,6 +111,14 @@ interface KafkaDriver {
      * uses this to decide whether `sendBatch` is atomic.
      */
     readonly transactional: boolean;
+    /**
+     * Construct a NEW admin client. The returned admin is not yet connected —
+     * the publisher calls `.connect()` before handing it to the user.
+     *
+     * Optional: drivers without an admin surface may omit this; the publisher
+     * throws a clear error when `publisher.admin()` is called on such a driver.
+     */
+    admin?(): Promise<KafkaDriverAdmin>;
 }
 /**
  * TLS configuration for client connections. Pass a full {@link TlsConfig}
@@ -149,6 +249,14 @@ interface ProducerBehaviorConfig {
     acks?: number;
     /** Compression codec. Driver maps to its native enum. */
     compression?: "none" | "gzip" | "snappy" | "lz4" | "zstd";
+    /**
+     * (confluent only) Compression level for the chosen codec. Defaults vary
+     * per codec — librdkafka picks the broker-friendly default when unset.
+     * Common ranges: gzip 1–9, lz4 0–12, zstd 1–22 (higher = smaller + slower).
+     *
+     * No-op on the kafkajs driver (kafkajs does not expose codec levels).
+     */
+    compressionLevel?: number;
     /**
      * (confluent only) How long the producer waits to accumulate records before
      * flushing a partition batch. Default 0 (ship-immediately). Increase to
@@ -199,6 +307,36 @@ interface ProducerBehaviorConfig {
      * whether this callback throws.
      */
     onTransactionAbort?: (error: Error) => void;
+    /**
+     * (confluent only) Raw librdkafka producer-config keys merged on top of
+     * eventferry's translated config. Use for tuning surface area we don't
+     * expose typed (e.g. `queue.buffering.max.messages`, `socket.keepalive.enable`,
+     * `statistics.interval.ms`). Native keys win against the translated ones,
+     * so this can also be used to override defaults.
+     *
+     * Ignored by the kafkajs driver — log a one-time warning instead of
+     * silently dropping. Use `rawKafkaJsProducerConfig` for kafkajs-side tuning.
+     */
+    rawProducerConfig?: Record<string, unknown>;
+    /**
+     * (kafkajs only) Raw producer-config keys merged into kafkajs's
+     * `kafka.producer({...})` call. Native keys win against the translated
+     * ones. Use for kafkajs-internal knobs like `retry`, `metadataMaxAge`,
+     * `idempotent` overrides, etc.
+     *
+     * No-op on the confluent driver — use `rawProducerConfig` there.
+     */
+    rawKafkaJsProducerConfig?: Record<string, unknown>;
+    /**
+     * (kafkajs only) Custom partitioner factory passed straight to
+     * `kafka.producer({ createPartitioner })`. Overrides {@link partitioner}
+     * preset entirely. See kafkajs docs for the factory signature:
+     * `() => (args: { topic, partitionMetadata, message }) => number`.
+     *
+     * Ignored by the confluent driver — librdkafka's partitioner is a C
+     * extension point, not a JS callback.
+     */
+    customPartitioner?: () => (args: unknown) => number;
 }
 type DriverKind = "kafkajs" | "confluent";
 
@@ -213,6 +351,11 @@ interface KjsTransaction {
     commit(): Promise<void>;
     abort(): Promise<void>;
 }
+interface KjsPartitionersNamespace {
+    DefaultPartitioner: () => unknown;
+    LegacyPartitioner: () => unknown;
+    JavaCompatiblePartitioner: () => unknown;
+}
 interface KafkaJsDriverOptions extends KafkaConnectionConfig, ProducerBehaviorConfig {
     /**
      * Optional logger for the driver's own diagnostics (e.g. warnings about
@@ -235,7 +378,19 @@ declare class KafkaJsDriver implements KafkaDriver {
      * the send/transaction logic can be exercised without a real broker.
      */
     protected createProducer(): Promise<KjsProducer>;
+    /**
+     * 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.
+     */
+    protected buildProducerOptions(partitioners: KjsPartitionersNamespace | undefined): Promise<Record<string, unknown>>;
     disconnect(): Promise<void>;
+    /**
+     * 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()`.
+     */
+    admin(): Promise<KafkaDriverAdmin>;
     sendBatch(messages: PublishableMessage[]): Promise<PublishResult[]>;
 }
 /** Internal — used by tests. Resets the dedup so warnings can be observed in isolation. */
@@ -288,6 +443,12 @@ declare class ConfluentDriver implements KafkaDriver {
      */
     protected createProducer(): Promise<CkProducer>;
     disconnect(): Promise<void>;
+    /**
+     * Construct a librdkafka-backed admin client wrapped in the eventferry
+     * `KafkaDriverAdmin` shape. The publisher's `connect()` is called before
+     * the admin reaches the user.
+     */
+    admin(): Promise<KafkaDriverAdmin>;
     sendBatch(messages: PublishableMessage[]): Promise<PublishResult[]>;
 }
 
@@ -423,6 +584,21 @@ interface KafkaTracer {
      *                    server.address/port).
      */
     startPublishSpan(name: string, attributes: Record<string, SpanAttributeValue>): SpanLike;
+    /**
+     * OPTIONAL: inject the active trace context (W3C `traceparent` +
+     * `tracestate`) into a per-message header map. Called by the publisher
+     * AFTER the batch span is created and BEFORE the records hit the wire.
+     *
+     * Implementations typically wrap OpenTelemetry's `propagation.inject(...)`
+     * or your tracing SDK's equivalent. Mutate the `headers` object in
+     * place — the publisher allocates a fresh copy per message so this is
+     * safe and matches the propagation API of every major SDK.
+     *
+     * Tracers without distributed-context propagation (or that only care
+     * about local spans) may leave this off — consumers can still derive
+     * trace headers themselves by other means.
+     */
+    inject?(span: SpanLike, headers: Record<string, string>): void;
 }
 /**
  * No-op tracer. Used when the user does not configure one. Cheap allocation
@@ -457,6 +633,16 @@ interface KafkaPublisherOptions extends KafkaConnectionConfig, ProducerBehaviorC
      * Use a thin adapter over your tracing SDK (see {@link KafkaTracer}).
      */
     tracer?: KafkaTracer;
+    /**
+     * If set, `connect()` checks that every topic in this list exists on the
+     * cluster and throws a descriptive error if any are missing. Use this to
+     * fail-fast at startup instead of letting the first send-time error
+     * surprise you.
+     *
+     * Validation runs AFTER the producer connects but BEFORE `onConnect` hooks
+     * fire. Driver must implement `admin()` (the built-ins do).
+     */
+    validateTopicsOnConnect?: string[];
 }
 /**
  * The Publisher the Relay talks to. Wraps a pluggable KafkaDriver and adds
@@ -469,8 +655,39 @@ declare class KafkaPublisher implements Publisher {
     private readonly logger;
     private readonly hooks;
     private readonly tracer;
+    private readonly validateTopicsOnConnect;
     constructor(opts: KafkaPublisherOptions);
     connect(): Promise<void>;
+    /**
+     * 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).
+     */
+    admin(): Promise<KafkaAdmin>;
+    /**
+     * 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.
+     */
+    ensureTopics(specs: TopicCreateSpec[], opts?: {
+        growPartitions?: boolean;
+    }): Promise<void>;
+    /**
+     * Borrow a fresh admin from the driver and connect it. Throws when the
+     * driver does not implement admin (custom drivers without that capability).
+     */
+    private openDriverAdmin;
+    /**
+     * Open an admin, list topics, throw if any required topic is missing.
+     * Always closes the admin (success or failure).
+     */
+    private assertTopicsExist;
     disconnect(): Promise<void>;
     publish(messages: PublishableMessage[]): Promise<PublishResult[]>;
     /**
@@ -491,4 +708,4 @@ declare class KafkaPublisher implements Publisher {
     private startBatchSpan;
 }
 
-export { type ConfluentClientConfig, ConfluentDriver, type ConfluentDriverOptions, type DriverKind, type KafkaConnectionConfig, type KafkaDriver, KafkaJsDriver, type KafkaJsDriverOptions, type KafkaJsPartitionerChoice, KafkaPublisher, type KafkaPublisherHooks, type KafkaPublisherOptions, type KafkaTracer, NoopKafkaTracer, type OauthBearerToken, type ProducerBehaviorConfig, type SaslConfig, type SaslOauthbearerConfig, type SaslPasswordConfig, type SpanAttributeValue, type SpanLike, type TlsConfig, _resetKafkajsWarnDedup, buildConfluentClientConfig, classifyConfluentError, classifyKafkajsError, safeHook };
+export { type ConfluentClientConfig, ConfluentDriver, type ConfluentDriverOptions, type DriverKind, type KafkaAdmin, type KafkaConnectionConfig, type KafkaDriver, type KafkaDriverAdmin, KafkaJsDriver, type KafkaJsDriverOptions, type KafkaJsPartitionerChoice, KafkaPublisher, type KafkaPublisherHooks, type KafkaPublisherOptions, type KafkaTracer, NoopKafkaTracer, type OauthBearerToken, type PartitionGrowSpec, type PartitionMetadata, type ProducerBehaviorConfig, type SaslConfig, type SaslOauthbearerConfig, type SaslPasswordConfig, type SpanAttributeValue, type SpanLike, type TlsConfig, type TopicCreateSpec, type TopicMetadata, _resetKafkajsWarnDedup, buildConfluentClientConfig, classifyConfluentError, classifyKafkajsError, safeHook };

package/dist/index.js

@@ -104,7 +104,10 @@ var UNSUPPORTED_BY_KAFKAJS = [
   "lingerMs",
   "batchSize",
   "deliveryTimeoutMs",
-  "maxRequestSize"
+  "maxRequestSize",
+  // Confluent-only escape hatches; ignored on kafkajs.
+  "compressionLevel",
+  "rawProducerConfig"
 ];
 var KafkaJsDriver = class {
   transactional;
@@ -143,13 +146,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
@@ -163,13 +174,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);
@@ -258,6 +288,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");
@@ -390,6 +483,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) {
@@ -419,6 +515,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) {
@@ -472,6 +571,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);
@@ -540,6 +650,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");
@@ -590,10 +763,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,
@@ -605,8 +780,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(
@@ -618,9 +875,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 });