@drarzter/kafka-client 0.9.4 → 0.11.0

package/dist/otel.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/otel.ts"],"sourcesContent":["import {\n  trace,\n  context,\n  propagation,\n  SpanKind,\n  SpanStatusCode,\n} from \"@opentelemetry/api\";\nimport type { BeforeConsumeResult, KafkaInstrumentation } from \"./client/types\";\nimport type { EventEnvelope } from \"./client/message/envelope\";\n\n/**\n * Create a `KafkaInstrumentation` that automatically propagates\n * W3C Trace Context via Kafka headers.\n *\n * Requires `@opentelemetry/api` as a peer dependency.\n *\n * **Send path:** injects `traceparent` into message headers from the\n * active OpenTelemetry context.\n *\n * **Consume path:** extracts `traceparent` from message headers,\n * starts a `CONSUMER` span as a child of the extracted context,\n * and ends it when the handler completes.\n *\n * @example\n * ```ts\n * import { otelInstrumentation } from '@drarzter/kafka-client/otel';\n *\n * const kafka = new KafkaClient('my-app', 'my-group', brokers, {\n *   instrumentation: [otelInstrumentation()],\n * });\n * ```\n */\nexport function otelInstrumentation(): KafkaInstrumentation {\n  const tracer = trace.getTracer(\"@drarzter/kafka-client\");\n  const activeSpans = new Map<string, ReturnType<typeof tracer.startSpan>>();\n\n  return {\n    beforeSend(_topic: string, headers: Record<string, string>) {\n      propagation.inject(context.active(), headers);\n    },\n\n    afterSend(_topic: string) {\n      // Span management for producers is left to the caller's OTel setup.\n      // We only inject context — creating producer spans here would be\n      // inaccurate since buildSendPayload runs synchronously per-message.\n    },\n\n    beforeConsume(envelope: EventEnvelope<any>): BeforeConsumeResult {\n      const parentCtx = propagation.extract(context.active(), envelope.headers);\n      const span = tracer.startSpan(\n        `kafka.consume ${envelope.topic}`,\n        {\n          kind: SpanKind.CONSUMER,\n          attributes: {\n            \"messaging.system\": \"kafka\",\n            \"messaging.destination.name\": envelope.topic,\n            \"messaging.message.id\": envelope.eventId,\n            \"messaging.kafka.partition\": envelope.partition,\n            \"messaging.kafka.offset\": envelope.offset,\n          },\n        },\n        parentCtx,\n      );\n      const spanCtx = trace.setSpan(parentCtx, span);\n      activeSpans.set(envelope.eventId, span);\n      return {\n        cleanup() {\n          span.end();\n          activeSpans.delete(envelope.eventId);\n        },\n        wrap(fn) {\n          return context.with(spanCtx, fn);\n        },\n      };\n    },\n\n    onConsumeError(envelope: EventEnvelope<any>, error: Error) {\n      const span = activeSpans.get(envelope.eventId);\n      if (span) {\n        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });\n        span.recordException(error);\n      }\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,iBAMO;AA0BA,SAAS,sBAA4C;AAC1D,QAAM,SAAS,iBAAM,UAAU,wBAAwB;AACvD,QAAM,cAAc,oBAAI,IAAiD;AAEzE,SAAO;AAAA,IACL,WAAW,QAAgB,SAAiC;AAC1D,6BAAY,OAAO,mBAAQ,OAAO,GAAG,OAAO;AAAA,IAC9C;AAAA,IAEA,UAAU,QAAgB;AAAA,IAI1B;AAAA,IAEA,cAAc,UAAmD;AAC/D,YAAM,YAAY,uBAAY,QAAQ,mBAAQ,OAAO,GAAG,SAAS,OAAO;AACxE,YAAM,OAAO,OAAO;AAAA,QAClB,iBAAiB,SAAS,KAAK;AAAA,QAC/B;AAAA,UACE,MAAM,oBAAS;AAAA,UACf,YAAY;AAAA,YACV,oBAAoB;AAAA,YACpB,8BAA8B,SAAS;AAAA,YACvC,wBAAwB,SAAS;AAAA,YACjC,6BAA6B,SAAS;AAAA,YACtC,0BAA0B,SAAS;AAAA,UACrC;AAAA,QACF;AAAA,QACA;AAAA,MACF;AACA,YAAM,UAAU,iBAAM,QAAQ,WAAW,IAAI;AAC7C,kBAAY,IAAI,SAAS,SAAS,IAAI;AACtC,aAAO;AAAA,QACL,UAAU;AACR,eAAK,IAAI;AACT,sBAAY,OAAO,SAAS,OAAO;AAAA,QACrC;AAAA,QACA,KAAK,IAAI;AACP,iBAAO,mBAAQ,KAAK,SAAS,EAAE;AAAA,QACjC;AAAA,MACF;AAAA,IACF;AAAA,IAEA,eAAe,UAA8B,OAAc;AACzD,YAAM,OAAO,YAAY,IAAI,SAAS,OAAO;AAC7C,UAAI,MAAM;AACR,aAAK,UAAU,EAAE,MAAM,0BAAe,OAAO,SAAS,MAAM,QAAQ,CAAC;AACrE,aAAK,gBAAgB,KAAK;AAAA,MAC5B;AAAA,IACF;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/otel.ts"],"sourcesContent":["import {\n  trace,\n  context,\n  propagation,\n  metrics,\n  SpanKind,\n  SpanStatusCode,\n} from \"@opentelemetry/api\";\nimport type { Meter, ObservableResult } from \"@opentelemetry/api\";\nimport type { BeforeConsumeResult, KafkaInstrumentation } from \"./client/types\";\nimport type { IKafkaAdmin } from \"./client/types/admin.interface\";\nimport type { TopicMapConstraint } from \"./client/types/common\";\nimport type { EventEnvelope } from \"./client/message/envelope\";\n\n/**\n * Create a `KafkaInstrumentation` that automatically propagates\n * W3C Trace Context via Kafka headers.\n *\n * Requires `@opentelemetry/api` as a peer dependency.\n *\n * **Send path:** injects `traceparent` into message headers from the\n * active OpenTelemetry context.\n *\n * **Consume path:** extracts `traceparent` from message headers,\n * starts a `CONSUMER` span as a child of the extracted context,\n * and ends it when the handler completes.\n *\n * @example\n * ```ts\n * import { otelInstrumentation } from '@drarzter/kafka-client/otel';\n *\n * const kafka = new KafkaClient('my-app', 'my-group', brokers, {\n *   instrumentation: [otelInstrumentation()],\n * });\n * ```\n */\nexport function otelInstrumentation(): KafkaInstrumentation {\n  const tracer = trace.getTracer(\"@drarzter/kafka-client\");\n  // Keyed by envelope object identity (not eventId) so two in-flight messages\n  // that share an eventId cannot overwrite each other's span. WeakMap also\n  // guarantees no leak if a cleanup path is ever missed.\n  const activeSpans = new WeakMap<\n    EventEnvelope<any>,\n    ReturnType<typeof tracer.startSpan>\n  >();\n\n  return {\n    beforeSend(_topic: string, headers: Record<string, string>) {\n      propagation.inject(context.active(), headers);\n    },\n\n    afterSend(_topic: string) {\n      // Span management for producers is left to the caller's OTel setup.\n      // We only inject context — creating producer spans here would be\n      // inaccurate since buildSendPayload runs synchronously per-message.\n    },\n\n    beforeConsume(envelope: EventEnvelope<any>): BeforeConsumeResult {\n      const parentCtx = propagation.extract(context.active(), envelope.headers);\n      const span = tracer.startSpan(\n        `kafka.consume ${envelope.topic}`,\n        {\n          kind: SpanKind.CONSUMER,\n          attributes: {\n            \"messaging.system\": \"kafka\",\n            \"messaging.destination.name\": envelope.topic,\n            \"messaging.message.id\": envelope.eventId,\n            \"messaging.kafka.partition\": envelope.partition,\n            \"messaging.kafka.offset\": envelope.offset,\n          },\n        },\n        parentCtx,\n      );\n      const spanCtx = trace.setSpan(parentCtx, span);\n      activeSpans.set(envelope, span);\n      return {\n        cleanup() {\n          span.end();\n          activeSpans.delete(envelope);\n        },\n        wrap(fn) {\n          return context.with(spanCtx, fn);\n        },\n      };\n    },\n\n    onConsumeError(envelope: EventEnvelope<any>, error: Error) {\n      const span = activeSpans.get(envelope);\n      if (span) {\n        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });\n        span.recordException(error);\n      }\n    },\n  };\n}\n\n/**\n * Create a `KafkaInstrumentation` that records OpenTelemetry **metrics** for\n * both the send and consume paths.\n *\n * Requires `@opentelemetry/api` as a peer dependency. Instruments are created\n * once per instrumentation instance (not per message), so a single call to this\n * factory registers all counters/histograms exactly once.\n *\n * Recorded instruments (all under meter `@drarzter/kafka-client`):\n *\n * | Instrument | Type | Attributes | Recorded in |\n * |---|---|---|---|\n * | `kafka.client.messages.sent` | Counter | `topic` | `afterSend` |\n * | `kafka.client.messages.processed` | Counter | `topic` | `onMessage` |\n * | `kafka.client.messages.retried` | Counter | `topic` | `onRetry` |\n * | `kafka.client.messages.dlq` | Counter | `topic`, `reason` | `onDlq` |\n * | `kafka.client.messages.duplicate` | Counter | `topic`, `strategy` | `onDuplicate` |\n * | `kafka.client.consume.errors` | Counter | `topic` | `onConsumeError` |\n * | `kafka.client.consume.duration` | Histogram (ms) | `topic` | `beforeConsume` → `cleanup()` |\n *\n * Composes with `otelInstrumentation()` (traces): list both in\n * `instrumentation`. They share nothing and can be added in any order.\n *\n * @param options.meter - Override the meter used to create instruments.\n *   Defaults to `metrics.getMeter(\"@drarzter/kafka-client\")`.\n *\n * @example\n * ```ts\n * import {\n *   otelInstrumentation,\n *   otelMetricsInstrumentation,\n * } from '@drarzter/kafka-client/otel';\n *\n * const kafka = new KafkaClient('my-app', 'my-group', brokers, {\n *   instrumentation: [otelInstrumentation(), otelMetricsInstrumentation()],\n * });\n * ```\n */\nexport function otelMetricsInstrumentation(options?: {\n  meter?: Meter;\n}): KafkaInstrumentation {\n  const meter = options?.meter ?? metrics.getMeter(\"@drarzter/kafka-client\");\n\n  const sentCounter = meter.createCounter(\"kafka.client.messages.sent\", {\n    description: \"Number of messages successfully sent to Kafka.\",\n  });\n  const processedCounter = meter.createCounter(\n    \"kafka.client.messages.processed\",\n    {\n      description: \"Number of messages successfully processed by a consumer.\",\n    },\n  );\n  const retriedCounter = meter.createCounter(\"kafka.client.messages.retried\", {\n    description: \"Number of messages queued for retry.\",\n  });\n  const dlqCounter = meter.createCounter(\"kafka.client.messages.dlq\", {\n    description: \"Number of messages routed to a DLQ topic.\",\n  });\n  const duplicateCounter = meter.createCounter(\n    \"kafka.client.messages.duplicate\",\n    {\n      description: \"Number of Lamport-clock duplicate messages detected.\",\n    },\n  );\n  const consumeErrorsCounter = meter.createCounter(\n    \"kafka.client.consume.errors\",\n    {\n      description: \"Number of consumer handler errors.\",\n    },\n  );\n  const consumeDuration = meter.createHistogram(\n    \"kafka.client.consume.duration\",\n    {\n      description: \"Consumer handler duration.\",\n      unit: \"ms\",\n    },\n  );\n\n  return {\n    afterSend(topic: string) {\n      sentCounter.add(1, { topic });\n    },\n\n    beforeConsume(envelope: EventEnvelope<any>): BeforeConsumeResult {\n      const topic = envelope.topic;\n      const start = Date.now();\n      return {\n        cleanup() {\n          consumeDuration.record(Date.now() - start, { topic });\n        },\n      };\n    },\n\n    onConsumeError(envelope: EventEnvelope<any>, _error: Error) {\n      consumeErrorsCounter.add(1, { topic: envelope.topic });\n    },\n\n    onRetry(envelope: EventEnvelope<any>, _attempt: number, _max: number) {\n      retriedCounter.add(1, { topic: envelope.topic });\n    },\n\n    onDlq(envelope: EventEnvelope<any>, reason: string) {\n      dlqCounter.add(1, { topic: envelope.topic, reason });\n    },\n\n    onDuplicate(\n      envelope: EventEnvelope<any>,\n      strategy: \"drop\" | \"dlq\" | \"topic\",\n    ) {\n      duplicateCounter.add(1, { topic: envelope.topic, strategy });\n    },\n\n    onMessage(envelope: EventEnvelope<any>) {\n      processedCounter.add(1, { topic: envelope.topic });\n    },\n  };\n}\n\n/**\n * Register an OpenTelemetry **ObservableGauge** `kafka.client.consumer.lag`\n * that reports per-partition consumer lag by polling `kafka.getConsumerLag()`\n * on each metric collection cycle.\n *\n * Requires `@opentelemetry/api` as a peer dependency. Accepts any object\n * implementing the `IKafkaAdmin` sub-interface (i.e. any `KafkaClient`).\n *\n * The async callback swallows errors silently — a broker query failure during\n * a collection cycle simply reports no lag samples for that cycle rather than\n * throwing inside the OTel metric reader.\n *\n * Gauge attributes: `topic`, `partition`, and `groupId` (empty string when the\n * client's default group is used).\n *\n * @param kafka - The client (or any `IKafkaAdmin`) to poll for lag.\n * @param options.meter - Override the meter. Defaults to\n *   `metrics.getMeter(\"@drarzter/kafka-client\")`.\n * @param options.groupId - Consumer group to query. Defaults to the client's\n *   constructor group.\n * @returns An unregister function that removes the observable callback. Call it\n *   on shutdown to stop observing.\n *\n * @example\n * ```ts\n * import { otelLagGauge } from '@drarzter/kafka-client/otel';\n *\n * const unregister = otelLagGauge(kafka, { groupId: 'billing-service' });\n * // ...later, on shutdown:\n * unregister();\n * ```\n */\nexport function otelLagGauge<T extends TopicMapConstraint<T>>(\n  kafka: IKafkaAdmin<T>,\n  options?: { meter?: Meter; groupId?: string },\n): () => void {\n  const meter = options?.meter ?? metrics.getMeter(\"@drarzter/kafka-client\");\n  const groupId = options?.groupId;\n\n  const gauge = meter.createObservableGauge(\"kafka.client.consumer.lag\", {\n    description: \"Consumer group lag per topic partition.\",\n  });\n\n  const callback = async (result: ObservableResult) => {\n    try {\n      const lag = await kafka.getConsumerLag(groupId);\n      for (const entry of lag) {\n        result.observe(entry.lag, {\n          topic: entry.topic,\n          partition: entry.partition,\n          groupId: groupId ?? \"\",\n        });\n      }\n    } catch {\n      // Swallow — a failed lag query should never break metric collection.\n    }\n  };\n\n  gauge.addCallback(callback);\n\n  return () => {\n    gauge.removeCallback(callback);\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/otel.mjs

@@ -5,12 +5,13 @@ import {
   trace,
   context,
   propagation,
+  metrics,
   SpanKind,
   SpanStatusCode
 } from "@opentelemetry/api";
 function otelInstrumentation() {
   const tracer = trace.getTracer("@drarzter/kafka-client");
-  const activeSpans = /* @__PURE__ */ new Map();
+  const activeSpans = /* @__PURE__ */ new WeakMap();
   return {
     beforeSend(_topic, headers) {
       propagation.inject(context.active(), headers);
@@ -34,11 +35,11 @@ function otelInstrumentation() {
         parentCtx
       );
       const spanCtx = trace.setSpan(parentCtx, span);
-      activeSpans.set(envelope.eventId, span);
+      activeSpans.set(envelope, span);
       return {
         cleanup() {
           span.end();
-          activeSpans.delete(envelope.eventId);
+          activeSpans.delete(envelope);
         },
         wrap(fn) {
           return context.with(spanCtx, fn);
@@ -46,7 +47,7 @@ function otelInstrumentation() {
       };
     },
     onConsumeError(envelope, error) {
-      const span = activeSpans.get(envelope.eventId);
+      const span = activeSpans.get(envelope);
       if (span) {
         span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
         span.recordException(error);
@@ -54,7 +55,99 @@ function otelInstrumentation() {
     }
   };
 }
+function otelMetricsInstrumentation(options) {
+  const meter = options?.meter ?? metrics.getMeter("@drarzter/kafka-client");
+  const sentCounter = meter.createCounter("kafka.client.messages.sent", {
+    description: "Number of messages successfully sent to Kafka."
+  });
+  const processedCounter = meter.createCounter(
+    "kafka.client.messages.processed",
+    {
+      description: "Number of messages successfully processed by a consumer."
+    }
+  );
+  const retriedCounter = meter.createCounter("kafka.client.messages.retried", {
+    description: "Number of messages queued for retry."
+  });
+  const dlqCounter = meter.createCounter("kafka.client.messages.dlq", {
+    description: "Number of messages routed to a DLQ topic."
+  });
+  const duplicateCounter = meter.createCounter(
+    "kafka.client.messages.duplicate",
+    {
+      description: "Number of Lamport-clock duplicate messages detected."
+    }
+  );
+  const consumeErrorsCounter = meter.createCounter(
+    "kafka.client.consume.errors",
+    {
+      description: "Number of consumer handler errors."
+    }
+  );
+  const consumeDuration = meter.createHistogram(
+    "kafka.client.consume.duration",
+    {
+      description: "Consumer handler duration.",
+      unit: "ms"
+    }
+  );
+  return {
+    afterSend(topic) {
+      sentCounter.add(1, { topic });
+    },
+    beforeConsume(envelope) {
+      const topic = envelope.topic;
+      const start = Date.now();
+      return {
+        cleanup() {
+          consumeDuration.record(Date.now() - start, { topic });
+        }
+      };
+    },
+    onConsumeError(envelope, _error) {
+      consumeErrorsCounter.add(1, { topic: envelope.topic });
+    },
+    onRetry(envelope, _attempt, _max) {
+      retriedCounter.add(1, { topic: envelope.topic });
+    },
+    onDlq(envelope, reason) {
+      dlqCounter.add(1, { topic: envelope.topic, reason });
+    },
+    onDuplicate(envelope, strategy) {
+      duplicateCounter.add(1, { topic: envelope.topic, strategy });
+    },
+    onMessage(envelope) {
+      processedCounter.add(1, { topic: envelope.topic });
+    }
+  };
+}
+function otelLagGauge(kafka, options) {
+  const meter = options?.meter ?? metrics.getMeter("@drarzter/kafka-client");
+  const groupId = options?.groupId;
+  const gauge = meter.createObservableGauge("kafka.client.consumer.lag", {
+    description: "Consumer group lag per topic partition."
+  });
+  const callback = async (result) => {
+    try {
+      const lag = await kafka.getConsumerLag(groupId);
+      for (const entry of lag) {
+        result.observe(entry.lag, {
+          topic: entry.topic,
+          partition: entry.partition,
+          groupId: groupId ?? ""
+        });
+      }
+    } catch {
+    }
+  };
+  gauge.addCallback(callback);
+  return () => {
+    gauge.removeCallback(callback);
+  };
+}
 export {
-  otelInstrumentation
+  otelInstrumentation,
+  otelLagGauge,
+  otelMetricsInstrumentation
 };
 //# sourceMappingURL=otel.mjs.map

package/dist/otel.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/otel.ts"],"sourcesContent":["import {\n  trace,\n  context,\n  propagation,\n  SpanKind,\n  SpanStatusCode,\n} from \"@opentelemetry/api\";\nimport type { BeforeConsumeResult, KafkaInstrumentation } from \"./client/types\";\nimport type { EventEnvelope } from \"./client/message/envelope\";\n\n/**\n * Create a `KafkaInstrumentation` that automatically propagates\n * W3C Trace Context via Kafka headers.\n *\n * Requires `@opentelemetry/api` as a peer dependency.\n *\n * **Send path:** injects `traceparent` into message headers from the\n * active OpenTelemetry context.\n *\n * **Consume path:** extracts `traceparent` from message headers,\n * starts a `CONSUMER` span as a child of the extracted context,\n * and ends it when the handler completes.\n *\n * @example\n * ```ts\n * import { otelInstrumentation } from '@drarzter/kafka-client/otel';\n *\n * const kafka = new KafkaClient('my-app', 'my-group', brokers, {\n *   instrumentation: [otelInstrumentation()],\n * });\n * ```\n */\nexport function otelInstrumentation(): KafkaInstrumentation {\n  const tracer = trace.getTracer(\"@drarzter/kafka-client\");\n  const activeSpans = new Map<string, ReturnType<typeof tracer.startSpan>>();\n\n  return {\n    beforeSend(_topic: string, headers: Record<string, string>) {\n      propagation.inject(context.active(), headers);\n    },\n\n    afterSend(_topic: string) {\n      // Span management for producers is left to the caller's OTel setup.\n      // We only inject context — creating producer spans here would be\n      // inaccurate since buildSendPayload runs synchronously per-message.\n    },\n\n    beforeConsume(envelope: EventEnvelope<any>): BeforeConsumeResult {\n      const parentCtx = propagation.extract(context.active(), envelope.headers);\n      const span = tracer.startSpan(\n        `kafka.consume ${envelope.topic}`,\n        {\n          kind: SpanKind.CONSUMER,\n          attributes: {\n            \"messaging.system\": \"kafka\",\n            \"messaging.destination.name\": envelope.topic,\n            \"messaging.message.id\": envelope.eventId,\n            \"messaging.kafka.partition\": envelope.partition,\n            \"messaging.kafka.offset\": envelope.offset,\n          },\n        },\n        parentCtx,\n      );\n      const spanCtx = trace.setSpan(parentCtx, span);\n      activeSpans.set(envelope.eventId, span);\n      return {\n        cleanup() {\n          span.end();\n          activeSpans.delete(envelope.eventId);\n        },\n        wrap(fn) {\n          return context.with(spanCtx, fn);\n        },\n      };\n    },\n\n    onConsumeError(envelope: EventEnvelope<any>, error: Error) {\n      const span = activeSpans.get(envelope.eventId);\n      if (span) {\n        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });\n        span.recordException(error);\n      }\n    },\n  };\n}\n"],"mappings":";;;AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AA0BA,SAAS,sBAA4C;AAC1D,QAAM,SAAS,MAAM,UAAU,wBAAwB;AACvD,QAAM,cAAc,oBAAI,IAAiD;AAEzE,SAAO;AAAA,IACL,WAAW,QAAgB,SAAiC;AAC1D,kBAAY,OAAO,QAAQ,OAAO,GAAG,OAAO;AAAA,IAC9C;AAAA,IAEA,UAAU,QAAgB;AAAA,IAI1B;AAAA,IAEA,cAAc,UAAmD;AAC/D,YAAM,YAAY,YAAY,QAAQ,QAAQ,OAAO,GAAG,SAAS,OAAO;AACxE,YAAM,OAAO,OAAO;AAAA,QAClB,iBAAiB,SAAS,KAAK;AAAA,QAC/B;AAAA,UACE,MAAM,SAAS;AAAA,UACf,YAAY;AAAA,YACV,oBAAoB;AAAA,YACpB,8BAA8B,SAAS;AAAA,YACvC,wBAAwB,SAAS;AAAA,YACjC,6BAA6B,SAAS;AAAA,YACtC,0BAA0B,SAAS;AAAA,UACrC;AAAA,QACF;AAAA,QACA;AAAA,MACF;AACA,YAAM,UAAU,MAAM,QAAQ,WAAW,IAAI;AAC7C,kBAAY,IAAI,SAAS,SAAS,IAAI;AACtC,aAAO;AAAA,QACL,UAAU;AACR,eAAK,IAAI;AACT,sBAAY,OAAO,SAAS,OAAO;AAAA,QACrC;AAAA,QACA,KAAK,IAAI;AACP,iBAAO,QAAQ,KAAK,SAAS,EAAE;AAAA,QACjC;AAAA,MACF;AAAA,IACF;AAAA,IAEA,eAAe,UAA8B,OAAc;AACzD,YAAM,OAAO,YAAY,IAAI,SAAS,OAAO;AAC7C,UAAI,MAAM;AACR,aAAK,UAAU,EAAE,MAAM,eAAe,OAAO,SAAS,MAAM,QAAQ,CAAC;AACrE,aAAK,gBAAgB,KAAK;AAAA,MAC5B;AAAA,IACF;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/otel.ts"],"sourcesContent":["import {\n  trace,\n  context,\n  propagation,\n  metrics,\n  SpanKind,\n  SpanStatusCode,\n} from \"@opentelemetry/api\";\nimport type { Meter, ObservableResult } from \"@opentelemetry/api\";\nimport type { BeforeConsumeResult, KafkaInstrumentation } from \"./client/types\";\nimport type { IKafkaAdmin } from \"./client/types/admin.interface\";\nimport type { TopicMapConstraint } from \"./client/types/common\";\nimport type { EventEnvelope } from \"./client/message/envelope\";\n\n/**\n * Create a `KafkaInstrumentation` that automatically propagates\n * W3C Trace Context via Kafka headers.\n *\n * Requires `@opentelemetry/api` as a peer dependency.\n *\n * **Send path:** injects `traceparent` into message headers from the\n * active OpenTelemetry context.\n *\n * **Consume path:** extracts `traceparent` from message headers,\n * starts a `CONSUMER` span as a child of the extracted context,\n * and ends it when the handler completes.\n *\n * @example\n * ```ts\n * import { otelInstrumentation } from '@drarzter/kafka-client/otel';\n *\n * const kafka = new KafkaClient('my-app', 'my-group', brokers, {\n *   instrumentation: [otelInstrumentation()],\n * });\n * ```\n */\nexport function otelInstrumentation(): KafkaInstrumentation {\n  const tracer = trace.getTracer(\"@drarzter/kafka-client\");\n  // Keyed by envelope object identity (not eventId) so two in-flight messages\n  // that share an eventId cannot overwrite each other's span. WeakMap also\n  // guarantees no leak if a cleanup path is ever missed.\n  const activeSpans = new WeakMap<\n    EventEnvelope<any>,\n    ReturnType<typeof tracer.startSpan>\n  >();\n\n  return {\n    beforeSend(_topic: string, headers: Record<string, string>) {\n      propagation.inject(context.active(), headers);\n    },\n\n    afterSend(_topic: string) {\n      // Span management for producers is left to the caller's OTel setup.\n      // We only inject context — creating producer spans here would be\n      // inaccurate since buildSendPayload runs synchronously per-message.\n    },\n\n    beforeConsume(envelope: EventEnvelope<any>): BeforeConsumeResult {\n      const parentCtx = propagation.extract(context.active(), envelope.headers);\n      const span = tracer.startSpan(\n        `kafka.consume ${envelope.topic}`,\n        {\n          kind: SpanKind.CONSUMER,\n          attributes: {\n            \"messaging.system\": \"kafka\",\n            \"messaging.destination.name\": envelope.topic,\n            \"messaging.message.id\": envelope.eventId,\n            \"messaging.kafka.partition\": envelope.partition,\n            \"messaging.kafka.offset\": envelope.offset,\n          },\n        },\n        parentCtx,\n      );\n      const spanCtx = trace.setSpan(parentCtx, span);\n      activeSpans.set(envelope, span);\n      return {\n        cleanup() {\n          span.end();\n          activeSpans.delete(envelope);\n        },\n        wrap(fn) {\n          return context.with(spanCtx, fn);\n        },\n      };\n    },\n\n    onConsumeError(envelope: EventEnvelope<any>, error: Error) {\n      const span = activeSpans.get(envelope);\n      if (span) {\n        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });\n        span.recordException(error);\n      }\n    },\n  };\n}\n\n/**\n * Create a `KafkaInstrumentation` that records OpenTelemetry **metrics** for\n * both the send and consume paths.\n *\n * Requires `@opentelemetry/api` as a peer dependency. Instruments are created\n * once per instrumentation instance (not per message), so a single call to this\n * factory registers all counters/histograms exactly once.\n *\n * Recorded instruments (all under meter `@drarzter/kafka-client`):\n *\n * | Instrument | Type | Attributes | Recorded in |\n * |---|---|---|---|\n * | `kafka.client.messages.sent` | Counter | `topic` | `afterSend` |\n * | `kafka.client.messages.processed` | Counter | `topic` | `onMessage` |\n * | `kafka.client.messages.retried` | Counter | `topic` | `onRetry` |\n * | `kafka.client.messages.dlq` | Counter | `topic`, `reason` | `onDlq` |\n * | `kafka.client.messages.duplicate` | Counter | `topic`, `strategy` | `onDuplicate` |\n * | `kafka.client.consume.errors` | Counter | `topic` | `onConsumeError` |\n * | `kafka.client.consume.duration` | Histogram (ms) | `topic` | `beforeConsume` → `cleanup()` |\n *\n * Composes with `otelInstrumentation()` (traces): list both in\n * `instrumentation`. They share nothing and can be added in any order.\n *\n * @param options.meter - Override the meter used to create instruments.\n *   Defaults to `metrics.getMeter(\"@drarzter/kafka-client\")`.\n *\n * @example\n * ```ts\n * import {\n *   otelInstrumentation,\n *   otelMetricsInstrumentation,\n * } from '@drarzter/kafka-client/otel';\n *\n * const kafka = new KafkaClient('my-app', 'my-group', brokers, {\n *   instrumentation: [otelInstrumentation(), otelMetricsInstrumentation()],\n * });\n * ```\n */\nexport function otelMetricsInstrumentation(options?: {\n  meter?: Meter;\n}): KafkaInstrumentation {\n  const meter = options?.meter ?? metrics.getMeter(\"@drarzter/kafka-client\");\n\n  const sentCounter = meter.createCounter(\"kafka.client.messages.sent\", {\n    description: \"Number of messages successfully sent to Kafka.\",\n  });\n  const processedCounter = meter.createCounter(\n    \"kafka.client.messages.processed\",\n    {\n      description: \"Number of messages successfully processed by a consumer.\",\n    },\n  );\n  const retriedCounter = meter.createCounter(\"kafka.client.messages.retried\", {\n    description: \"Number of messages queued for retry.\",\n  });\n  const dlqCounter = meter.createCounter(\"kafka.client.messages.dlq\", {\n    description: \"Number of messages routed to a DLQ topic.\",\n  });\n  const duplicateCounter = meter.createCounter(\n    \"kafka.client.messages.duplicate\",\n    {\n      description: \"Number of Lamport-clock duplicate messages detected.\",\n    },\n  );\n  const consumeErrorsCounter = meter.createCounter(\n    \"kafka.client.consume.errors\",\n    {\n      description: \"Number of consumer handler errors.\",\n    },\n  );\n  const consumeDuration = meter.createHistogram(\n    \"kafka.client.consume.duration\",\n    {\n      description: \"Consumer handler duration.\",\n      unit: \"ms\",\n    },\n  );\n\n  return {\n    afterSend(topic: string) {\n      sentCounter.add(1, { topic });\n    },\n\n    beforeConsume(envelope: EventEnvelope<any>): BeforeConsumeResult {\n      const topic = envelope.topic;\n      const start = Date.now();\n      return {\n        cleanup() {\n          consumeDuration.record(Date.now() - start, { topic });\n        },\n      };\n    },\n\n    onConsumeError(envelope: EventEnvelope<any>, _error: Error) {\n      consumeErrorsCounter.add(1, { topic: envelope.topic });\n    },\n\n    onRetry(envelope: EventEnvelope<any>, _attempt: number, _max: number) {\n      retriedCounter.add(1, { topic: envelope.topic });\n    },\n\n    onDlq(envelope: EventEnvelope<any>, reason: string) {\n      dlqCounter.add(1, { topic: envelope.topic, reason });\n    },\n\n    onDuplicate(\n      envelope: EventEnvelope<any>,\n      strategy: \"drop\" | \"dlq\" | \"topic\",\n    ) {\n      duplicateCounter.add(1, { topic: envelope.topic, strategy });\n    },\n\n    onMessage(envelope: EventEnvelope<any>) {\n      processedCounter.add(1, { topic: envelope.topic });\n    },\n  };\n}\n\n/**\n * Register an OpenTelemetry **ObservableGauge** `kafka.client.consumer.lag`\n * that reports per-partition consumer lag by polling `kafka.getConsumerLag()`\n * on each metric collection cycle.\n *\n * Requires `@opentelemetry/api` as a peer dependency. Accepts any object\n * implementing the `IKafkaAdmin` sub-interface (i.e. any `KafkaClient`).\n *\n * The async callback swallows errors silently — a broker query failure during\n * a collection cycle simply reports no lag samples for that cycle rather than\n * throwing inside the OTel metric reader.\n *\n * Gauge attributes: `topic`, `partition`, and `groupId` (empty string when the\n * client's default group is used).\n *\n * @param kafka - The client (or any `IKafkaAdmin`) to poll for lag.\n * @param options.meter - Override the meter. Defaults to\n *   `metrics.getMeter(\"@drarzter/kafka-client\")`.\n * @param options.groupId - Consumer group to query. Defaults to the client's\n *   constructor group.\n * @returns An unregister function that removes the observable callback. Call it\n *   on shutdown to stop observing.\n *\n * @example\n * ```ts\n * import { otelLagGauge } from '@drarzter/kafka-client/otel';\n *\n * const unregister = otelLagGauge(kafka, { groupId: 'billing-service' });\n * // ...later, on shutdown:\n * unregister();\n * ```\n */\nexport function otelLagGauge<T extends TopicMapConstraint<T>>(\n  kafka: IKafkaAdmin<T>,\n  options?: { meter?: Meter; groupId?: string },\n): () => void {\n  const meter = options?.meter ?? metrics.getMeter(\"@drarzter/kafka-client\");\n  const groupId = options?.groupId;\n\n  const gauge = meter.createObservableGauge(\"kafka.client.consumer.lag\", {\n    description: \"Consumer group lag per topic partition.\",\n  });\n\n  const callback = async (result: ObservableResult) => {\n    try {\n      const lag = await kafka.getConsumerLag(groupId);\n      for (const entry of lag) {\n        result.observe(entry.lag, {\n          topic: entry.topic,\n          partition: entry.partition,\n          groupId: groupId ?? \"\",\n        });\n      }\n    } catch {\n      // Swallow — a failed lag query should never break metric collection.\n    }\n  };\n\n  gauge.addCallback(callback);\n\n  return () => {\n    gauge.removeCallback(callback);\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/serde.d.ts

@@ -0,0 +1,157 @@
+import type { MessageSerde, SerdeContext } from "./client/message/serde";
+import type { SchemaRegistryClient } from "./client/message/schema-registry";
+export { JsonSerde } from "./client/message/serde";
+export type { MessageSerde, SerdeContext } from "./client/message/serde";
+export { SchemaRegistryClient } from "./client/message/schema-registry";
+/** Injectable dynamic-import function — overridable in tests. */
+type ImportFn = (specifier: string) => Promise<any>;
+/** Options common to the registry-backed serdes. */
+interface RegistrySerdeCommonOptions {
+    /** Schema Registry client used to resolve/register schema ids. */
+    registry: SchemaRegistryClient;
+    /**
+     * Subject name. Defaults to Confluent `TopicNameStrategy`
+     * (`<topic>-value` / `<topic>-key`). Provide a literal string or a
+     * function of the {@link SerdeContext} to override.
+     */
+    subject?: string | ((ctx: SerdeContext) => string);
+    /**
+     * Register `schema` on first serialize to obtain its id (dev-friendly).
+     * Default `false` → the id is resolved via `getLatestSchema(subject)`.
+     */
+    autoRegister?: boolean;
+    /** @internal Injectable dynamic import for tests. */
+    importFn?: ImportFn;
+}
+/** Options for {@link avroSerde}. */
+export interface AvroSerdeOptions extends RegistrySerdeCommonOptions {
+    /**
+     * Avro schema (JSON string or object) used to serialize, and as the
+     * write-schema fallback. Required to serialize; deserialize resolves the
+     * writer schema from the registry via the wire-format id.
+     */
+    schema?: string | object;
+}
+/**
+ * Confluent-wire-format **Avro** serde backed by a Schema Registry.
+ *
+ * Produces/consumes the exact byte layout Java/Go clients use, so this library
+ * interoperates with them through a shared registry:
+ *
+ * ```
+ * [magic 0x00][schema id: 4-byte big-endian][avro binary]
+ * ```
+ *
+ * Uses the optional peer dependency [`avsc`](https://www.npmjs.com/package/avsc)
+ * via dynamic import — install it to enable Avro:
+ *
+ * ```bash
+ * npm install avsc
+ * ```
+ *
+ * - **serialize**: resolves the subject from the context, obtains the schema id
+ *   (`registerSchema` when `autoRegister`, else `getLatestSchema`), Avro-encodes
+ *   `value` against `schema`, and frames the bytes.
+ * - **deserialize**: reads the magic byte + big-endian id, resolves the writer
+ *   schema via `registry.getSchemaById(id)` (cached forever), and Avro-decodes
+ *   the remainder. The reader schema equals the writer schema in v1 — full
+ *   reader-schema resolution / schema evolution is a future enhancement.
+ *
+ * The parsed `avsc` type is cached per schema string so repeated messages don't
+ * re-parse the schema.
+ *
+ * @example
+ * ```ts
+ * import { avroSerde } from '@drarzter/kafka-client/serde';
+ * import { SchemaRegistryClient } from '@drarzter/kafka-client';
+ *
+ * const registry = new SchemaRegistryClient({ baseUrl: 'http://localhost:8081' });
+ * const orderSchema = {
+ *   type: 'record',
+ *   name: 'Order',
+ *   fields: [{ name: 'orderId', type: 'string' }, { name: 'amount', type: 'double' }],
+ * };
+ *
+ * // Per-topic:
+ * const Orders = topic('orders')
+ *   .serde(avroSerde({ registry, schema: orderSchema }))
+ *   .type<Order>();
+ *
+ * // Client-wide:
+ * const kafka = new KafkaClient(id, group, brokers, {
+ *   serde: avroSerde({ registry, schema: orderSchema }),
+ * });
+ * ```
+ */
+export declare function avroSerde(options: AvroSerdeOptions): MessageSerde;
+/** Options for {@link protobufSerde}. */
+export interface ProtobufSerdeOptions extends RegistrySerdeCommonOptions {
+    /**
+     * Fully-qualified Protobuf message name to encode/decode,
+     * e.g. `"com.acme.orders.Order"`.
+     */
+    messageType: string;
+    /**
+     * `.proto` source string defining {@link ProtobufSerdeOptions.messageType}.
+     * Required to serialize; deserialize resolves the writer `.proto` from the
+     * registry via the wire-format id.
+     */
+    schema?: string;
+}
+/**
+ * Confluent-wire-format **Protobuf** serde backed by a Schema Registry.
+ *
+ * Produces/consumes the exact byte layout Java/Go clients use:
+ *
+ * ```
+ * [magic 0x00][schema id: 4-byte big-endian][message-index][protobuf binary]
+ * ```
+ *
+ * The **message-index** identifies which message type within the `.proto` file
+ * was used. For the first/top-level message type (index `[0]`) Confluent writes
+ * the single byte `0x00`. This serde implements that top-level case only —
+ * multiple/nested message types are a documented v1 limitation and cause a
+ * clear error on deserialize.
+ *
+ * Uses the optional peer dependency
+ * [`protobufjs`](https://www.npmjs.com/package/protobufjs) via dynamic import —
+ * install it to enable Protobuf:
+ *
+ * ```bash
+ * npm install protobufjs
+ * ```
+ *
+ * - **serialize**: obtains the schema id (`registerSchema` when `autoRegister`,
+ *   else `getLatestSchema`), encodes `value` with the `protobufjs` `Type`, and
+ *   frames it with the `0x00` message-index byte.
+ * - **deserialize**: reads the magic byte + big-endian id + message-index (which
+ *   must be the single `0x00` byte), resolves the writer `.proto` via
+ *   `registry.getSchemaById(id)` (cached forever), and decodes the remainder.
+ *
+ * The parsed `protobufjs` `Type` is cached per schema string so repeated
+ * messages don't re-parse the `.proto`.
+ *
+ * @example
+ * ```ts
+ * import { protobufSerde } from '@drarzter/kafka-client/serde';
+ * import { SchemaRegistryClient } from '@drarzter/kafka-client';
+ *
+ * const registry = new SchemaRegistryClient({ baseUrl: 'http://localhost:8081' });
+ * const proto = `
+ *   syntax = "proto3";
+ *   message Order { string orderId = 1; double amount = 2; }
+ * `;
+ *
+ * // Per-topic:
+ * const Orders = topic('orders')
+ *   .serde(protobufSerde({ registry, schema: proto, messageType: 'Order' }))
+ *   .type<Order>();
+ *
+ * // Client-wide:
+ * const kafka = new KafkaClient(id, group, brokers, {
+ *   serde: protobufSerde({ registry, schema: proto, messageType: 'Order' }),
+ * });
+ * ```
+ */
+export declare function protobufSerde(options: ProtobufSerdeOptions): MessageSerde;
+//# sourceMappingURL=serde.d.ts.map

package/dist/serde.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serde.d.ts","sourceRoot":"","sources":["../src/serde.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAI7E,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAKxE,iEAAiE;AACjE,KAAK,QAAQ,GAAG,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAqEpD,oDAAoD;AACpD,UAAU,0BAA0B;IAClC,kEAAkE;IAClE,QAAQ,EAAE,oBAAoB,CAAC;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,YAAY,KAAK,MAAM,CAAC,CAAC;IACnD;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,qCAAqC;AACrC,MAAM,WAAW,gBAAiB,SAAQ,0BAA0B;IAClE;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,CA4DjE;AAED,yCAAyC;AACzC,MAAM,WAAW,oBAAqB,SAAQ,0BAA0B;IACtE;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,YAAY,CAiFzE"}