@eventferry/kafka 3.4.0 → 3.5.0

package/dist/index.js

@@ -7,6 +7,7 @@ function classifyKafkajsError(err) {
   if (e.name === "KafkaJSNonRetriableError") return "fatal";
   const type = typeof e.type === "string" ? e.type : void 0;
   if (type) {
+    if (FENCED_TYPES.has(type)) return "fenced";
     if (RETRIABLE_TYPES.has(type)) return "retriable";
     if (POISON_TYPES.has(type)) return "poison";
     if (FATAL_TYPES.has(type)) return "fatal";
@@ -40,9 +41,11 @@ var POISON_TYPES = /* @__PURE__ */ new Set([
   "INVALID_REQUIRED_ACKS",
   "INVALID_PARTITIONS"
 ]);
-var FATAL_TYPES = /* @__PURE__ */ new Set([
+var FENCED_TYPES = /* @__PURE__ */ new Set([
   "INVALID_PRODUCER_EPOCH",
-  "PRODUCER_FENCED",
+  "PRODUCER_FENCED"
+]);
+var FATAL_TYPES = /* @__PURE__ */ new Set([
   "TOPIC_AUTHORIZATION_FAILED",
   "CLUSTER_AUTHORIZATION_FAILED",
   "TRANSACTIONAL_ID_AUTHORIZATION_FAILED",
@@ -73,8 +76,8 @@ var CODE_TO_KIND = /* @__PURE__ */ new Map([
   // TOPIC_AUTHORIZATION_FAILED
   [31, "fatal"],
   // CLUSTER_AUTHORIZATION_FAILED
-  [47, "fatal"],
-  // INVALID_PRODUCER_EPOCH
+  [47, "fenced"],
+  // INVALID_PRODUCER_EPOCH — retryable once via publisher reconnect
   [58, "fatal"],
   // SASL_AUTHENTICATION_FAILED
   [74, "retriable"],
@@ -107,7 +110,10 @@ var UNSUPPORTED_BY_KAFKAJS = [
   "maxRequestSize",
   // Confluent-only escape hatches; ignored on kafkajs.
   "compressionLevel",
-  "rawProducerConfig"
+  "rawProducerConfig",
+  // librdkafka stats — kafkajs has no equivalent surface.
+  "onStats",
+  "statsIntervalMs"
 ];
 var KafkaJsDriver = class {
   transactional;
@@ -393,8 +399,8 @@ var CODE_TO_KIND2 = /* @__PURE__ */ new Map([
   // ERR__TRANSPORT
   [-198, "poison"],
   // ERR__BAD_COMPRESSION
-  [-144, "fatal"],
-  // ERR__FENCED — producer fenced by another with same txn id
+  [-144, "fenced"],
+  // ERR__FENCED — producer fenced; publisher reconnect attempts a transparent recovery once
   [-150, "fatal"],
   // ERR__FATAL — unrecoverable librdkafka error
   [-169, "fatal"],
@@ -426,8 +432,8 @@ var CODE_TO_KIND2 = /* @__PURE__ */ new Map([
   // TOPIC_AUTHORIZATION_FAILED
   [31, "fatal"],
   // CLUSTER_AUTHORIZATION_FAILED
-  [47, "fatal"],
-  // INVALID_PRODUCER_EPOCH
+  [47, "fenced"],
+  // INVALID_PRODUCER_EPOCH — retryable once via publisher reconnect
   [58, "fatal"],
   // SASL_AUTHENTICATION_FAILED
   [74, "retriable"],
@@ -441,7 +447,7 @@ var CODE_TO_KIND2 = /* @__PURE__ */ new Map([
 ]);
 var NAME_TO_KIND = /* @__PURE__ */ new Map([
   ["ERR__QUEUE_FULL", "backpressure"],
-  ["ERR__FENCED", "fatal"],
+  ["ERR__FENCED", "fenced"],
   ["ERR__FATAL", "fatal"],
   ["ERR__AUTHENTICATION", "fatal"],
   ["ERR__SSL", "fatal"],
@@ -450,7 +456,7 @@ var NAME_TO_KIND = /* @__PURE__ */ new Map([
   ["ERR__BAD_COMPRESSION", "poison"],
   ["ERR_TOPIC_AUTHORIZATION_FAILED", "fatal"],
   ["ERR_CLUSTER_AUTHORIZATION_FAILED", "fatal"],
-  ["ERR_INVALID_PRODUCER_EPOCH", "fatal"],
+  ["ERR_INVALID_PRODUCER_EPOCH", "fenced"],
   ["ERR_SASL_AUTHENTICATION_FAILED", "fatal"],
   ["ERR_CORRUPT_MESSAGE", "poison"],
   ["ERR_MSG_SIZE_TOO_LARGE", "poison"],
@@ -486,6 +492,12 @@ function buildConfluentClientConfig(opts) {
   if (opts.compressionLevel !== void 0) {
     librdkafka["compression.level"] = opts.compressionLevel;
   }
+  if (opts.onStats) {
+    librdkafka["stats_cb"] = wrapStatsCallback(opts.onStats);
+    librdkafka["statistics.interval.ms"] = opts.statsIntervalMs ?? 3e4;
+  } else if (opts.statsIntervalMs !== void 0) {
+    librdkafka["statistics.interval.ms"] = opts.statsIntervalMs;
+  }
   const tlsRequested = opts.ssl === true || isTlsConfig(opts.ssl);
   const saslRequested = !!opts.sasl;
   if (saslRequested && tlsRequested) {
@@ -523,6 +535,20 @@ function buildConfluentClientConfig(opts) {
 function isTlsConfig(v) {
   return typeof v === "object" && v !== null;
 }
+function wrapStatsCallback(onStats) {
+  return (raw) => {
+    let parsed;
+    try {
+      parsed = typeof raw === "string" ? JSON.parse(raw) : raw;
+    } catch {
+      return;
+    }
+    try {
+      onStats(parsed);
+    } catch {
+    }
+  };
+}
 function stringifyPem(input) {
   if (Array.isArray(input)) {
     return input.map((x) => typeof x === "string" ? x : x.toString("utf8")).join("\n");
@@ -764,11 +790,17 @@ var KafkaPublisher = class {
   hooks;
   tracer;
   validateTopicsOnConnect;
+  autoRecoverFromFence;
+  // Serialize reconnects so concurrent publish() calls hitting a fence
+  // all observe the same single reconnect attempt — the second publish
+  // doesn't try to disconnect a producer the first is still re-initing.
+  fenceRecovery = null;
   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;
+    this.autoRecoverFromFence = opts.autoRecoverFromFence ?? false;
     const onTransactionAbort = this.hooks.onTransactionAbort ? (error) => {
       void safeHook(
         this.logger,
@@ -891,6 +923,20 @@ var KafkaPublisher = class {
       await safeHook(this.logger, "onError", () => this.hooks.onError?.(error));
       throw err;
     }
+    const firstFenced = results.find(
+      (r) => !r.ok && r.errorKind === "fenced"
+    );
+    if (firstFenced) {
+      const fenceErr = firstFenced.error ?? new Error("producer fenced");
+      await safeHook(
+        this.logger,
+        "onProducerFenced",
+        () => this.hooks.onProducerFenced?.(fenceErr)
+      );
+      if (this.autoRecoverFromFence) {
+        results = await this.recoverAndRetry(outgoing, results);
+      }
+    }
     const byId = new Map(messages.map((m) => [m.recordId, m]));
     let allOk = true;
     for (const r of results) {
@@ -941,6 +987,110 @@ var KafkaPublisher = class {
   get transactional() {
     return this.driver.transactional;
   }
+  /**
+   * Cheap reachability probe. Borrows a fresh admin client, calls
+   * `listTopics`, and returns timing + outcome. Useful as the body of a
+   * `/healthz` or `/readyz` endpoint — proves the broker is reachable
+   * AND that the configured credentials still authenticate against it,
+   * without writing a record.
+   *
+   * Does NOT exercise the producer's send path — a healthy admin
+   * connection doesn't guarantee `publish()` will succeed (a fenced
+   * transactional producer would still answer healthy here). Treat this
+   * as "broker reachable + auth still good", not "publisher is fully
+   * operational".
+   *
+   * Default timeout 5_000 ms — long enough to ride out a single broker
+   * leader election, short enough to fail a liveness probe meaningfully.
+   * Set `timeoutMs: 0` to disable the timer entirely.
+   *
+   * The driver must implement `admin()` (the built-ins do); custom
+   * drivers without admin get `{ ok: false, error: ... }` instead of
+   * the throw `publisher.admin()` would surface — health checks are
+   * not the place to crash.
+   */
+  async healthCheck(opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 5e3;
+    const startedAt = Date.now();
+    if (!this.driver.admin) {
+      return {
+        ok: false,
+        latencyMs: 0,
+        timestamp: startedAt,
+        error: new Error(
+          "KafkaPublisher.healthCheck: configured driver does not implement admin()"
+        )
+      };
+    }
+    let admin = null;
+    try {
+      admin = await this.driver.admin();
+      await admin.connect();
+      const probe = admin.listTopics();
+      if (timeoutMs > 0) {
+        await raceWithTimeout(probe, timeoutMs, "healthCheck");
+      } else {
+        await probe;
+      }
+      return {
+        ok: true,
+        latencyMs: Date.now() - startedAt,
+        timestamp: startedAt
+      };
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      return {
+        ok: false,
+        latencyMs: Date.now() - startedAt,
+        timestamp: startedAt,
+        error
+      };
+    } finally {
+      try {
+        await admin?.close();
+      } catch {
+      }
+    }
+  }
+  /**
+   * Disconnect + re-connect the driver and re-send the batch ONCE. Used
+   * by the fence-recovery path. Concurrent fence recoveries dedupe on a
+   * shared in-flight promise (`fenceRecovery`) so we don't tear the
+   * producer down while another batch is mid-restart.
+   *
+   * If the second send STILL reports any fenced records, those failures
+   * are returned unchanged — another instance has almost certainly taken
+   * the same `transactionalId` and silently retrying again would mask
+   * the misconfiguration.
+   */
+  async recoverAndRetry(outgoing, firstResults) {
+    if (!this.fenceRecovery) {
+      this.fenceRecovery = (async () => {
+        try {
+          await this.driver.disconnect();
+          await this.driver.connect();
+        } finally {
+          this.fenceRecovery = null;
+        }
+      })();
+    }
+    try {
+      await this.fenceRecovery;
+    } catch (err) {
+      const reconnectErr = err instanceof Error ? err : new Error(String(err));
+      await safeHook(
+        this.logger,
+        "onError",
+        () => this.hooks.onError?.(reconnectErr)
+      );
+      return firstResults;
+    }
+    try {
+      return await this.driver.sendBatch(outgoing);
+    } catch {
+      return firstResults;
+    }
+  }
   /**
    * Start a span for the batch following the OTel messaging conventions.
    *
@@ -959,6 +1109,26 @@ var KafkaPublisher = class {
     });
   }
 };
+function raceWithTimeout(p, ms, label) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${ms}ms`));
+    }, ms);
+    if (typeof timer.unref === "function") {
+      timer.unref();
+    }
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      }
+    );
+  });
+}
 function selectDriver(opts) {
   const kind = opts.driver ?? "kafkajs";
   switch (kind) {