@relaybus/kafka 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -1,16 +1,37 @@
 'use strict';
 
 var core = require('@relaybus/core');
+var internal = require('@relaybus/core/internal');
 
-// src/cloudevents-codec.ts
+// src/errors.ts
 var InvalidKafkaMessageError = class extends core.RelayBusError {
+  name = "InvalidKafkaMessageError";
+  code = "RELAYBUS_KAFKA_INVALID_MESSAGE";
 };
 var UnencodableEventError = class extends core.NonRetryableError {
   name = "UnencodableEventError";
+  code = "RELAYBUS_KAFKA_UNENCODABLE_EVENT";
+};
+var PublishTimeoutError = class extends core.RelayBusError {
+  name = "PublishTimeoutError";
+  code = "RELAYBUS_KAFKA_PUBLISH_TIMEOUT";
+};
+var TransportClosedError = class extends core.RelayBusError {
+  name = "TransportClosedError";
+  code = "RELAYBUS_KAFKA_TRANSPORT_CLOSED";
+};
+var GroupJoinTimeoutError = class extends core.RelayBusError {
+  name = "GroupJoinTimeoutError";
+  code = "RELAYBUS_KAFKA_GROUP_JOIN_TIMEOUT";
+};
+var HandlerFailedError = class extends core.RelayBusError {
+  name = "HandlerFailedError";
+  code = "RELAYBUS_KAFKA_HANDLER_FAILED";
 };
 var SPEC_VERSION = "1.0";
 var CONTENT_TYPE = "content-type";
 var JSON_MEDIA_TYPE = "application/json";
+var STRUCTURED_MEDIA_TYPE = "application/cloudevents+json";
 var CLOUDEVENTS_PREFIX = "ce_";
 var ESCAPE_PREFIX = "x-relaybus-h-";
 var RESERVED_PREFIXES = [CLOUDEVENTS_PREFIX, "x-relaybus-"];
@@ -25,6 +46,7 @@ var HEADER = {
   causationId: "ce_causationid"
 };
 var PROTOCOL_HEADERS = /* @__PURE__ */ new Set([...Object.values(HEADER), CONTENT_TYPE]);
+var MAXIMUM_RFC3339_YEAR = 9999;
 var RFC3339_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/i;
 var strictUtf8 = new TextDecoder("utf-8", { fatal: true });
 var lenientUtf8 = new TextDecoder("utf-8");
@@ -52,25 +74,39 @@ function encodeEnvelope(envelope) {
   }
   return { key: envelope.key, value, headers: Object.fromEntries(entries) };
 }
+function encodeStructuredEnvelope(envelope) {
+  const value = internal.writeStructuredCloudEvent(envelope, {
+    time: formatTime(envelope),
+    data: serializePayload(envelope)
+  });
+  const entries = Object.entries(envelope.headers).map(
+    ([name, headerValue]) => [escapeUserHeaderName(name), headerValue]
+  );
+  entries.push([CONTENT_TYPE, STRUCTURED_MEDIA_TYPE]);
+  return { key: envelope.key, value, headers: Object.fromEntries(entries) };
+}
 function serializePayload(envelope) {
-  let value;
+  return serializeJson(envelope, envelope.payload);
+}
+function serializeJson(envelope, value) {
+  let text;
   try {
-    value = JSON.stringify(envelope.payload);
+    text = JSON.stringify(value);
   } catch (error) {
     throw new UnencodableEventError(
       `Event ${envelope.id} has a payload that JSON cannot represent: ${error.message}`
     );
   }
-  if (value === void 0) {
+  if (text === void 0) {
     throw new UnencodableEventError(
       `Event ${envelope.id} has a payload that JSON cannot represent (undefined, a function or a symbol)`
     );
   }
-  return value;
+  return text;
 }
 function formatTime(envelope) {
   const year = envelope.occurredAt.getUTCFullYear();
-  if (Number.isNaN(year) || year < 0 || year > 9999) {
+  if (Number.isNaN(year) || year < 0 || year > MAXIMUM_RFC3339_YEAR) {
     throw new UnencodableEventError(
       `Event ${envelope.id} has an occurredAt that is not an RFC 3339 instant (invalid date or year outside 0..9999)`
     );
@@ -118,11 +154,14 @@ function readHeaders(incoming) {
     if (typeof raw !== "string" && !(raw instanceof Uint8Array)) {
       throw invalid(`Header '${name}' is repeated`);
     }
-    headers.set(name, decodeText(raw, PROTOCOL_HEADERS.has(name), `Header '${name}'`));
+    headers.set(
+      name,
+      decodeText(raw, { strict: PROTOCOL_HEADERS.has(name), label: `Header '${name}'` })
+    );
   }
   return headers;
 }
-function decodeText(raw, strict, label) {
+function decodeText(raw, { strict, label }) {
   if (typeof raw === "string") {
     return raw;
   }
@@ -145,21 +184,24 @@ function assertJsonContentType(contentType) {
     throw invalid(`${CONTENT_TYPE} must be '${JSON_MEDIA_TYPE}', received '${contentType ?? ""}'`);
   }
 }
-function resolveTime(text, recordTimestamp) {
+function resolveTime(text, recordTimestamp2) {
   if (text !== void 0 && text.length > 0) {
     return parseTime(text);
   }
-  const milliseconds = Number(recordTimestamp);
-  const time = new Date(milliseconds);
-  if (recordTimestamp === void 0 || recordTimestamp === "" || Number.isNaN(time.getTime())) {
+  const time = readRecordTimestamp(recordTimestamp2);
+  if (time === void 0) {
     throw invalid(`${HEADER.time} is missing and the record has no usable timestamp`);
   }
   return time;
 }
-function parseTime(text) {
+function readRecordTimestamp(recordTimestamp2) {
+  const time = new Date(Number(recordTimestamp2));
+  return recordTimestamp2 === void 0 || recordTimestamp2 === "" || Number.isNaN(time.getTime()) ? void 0 : time;
+}
+function parseTime(text, label = HEADER.time) {
   const time = new Date(text);
   if (!RFC3339_PATTERN.test(text) || Number.isNaN(time.getTime())) {
-    throw invalid(`${HEADER.time} is not an RFC 3339 timestamp: '${text}'`);
+    throw invalid(`${label} is not an RFC 3339 timestamp: '${text}'`);
   }
   return time;
 }
@@ -167,7 +209,7 @@ function parsePayload(value) {
   if (value === null) {
     throw invalid("Message has no value");
   }
-  const text = decodeText(value, true, "Message value");
+  const text = decodeText(value, { strict: true, label: "Message value" });
   try {
     return JSON.parse(text);
   } catch {
@@ -175,12 +217,15 @@ function parsePayload(value) {
   }
 }
 function resolveKey(subject, recordKey) {
-  const keyText = recordKey === null ? null : decodeText(recordKey, true, "Message key");
+  const keyText = readRecordKey(recordKey);
   if (subject !== void 0 && keyText !== null && subject !== keyText) {
     throw invalid(`${HEADER.subject} does not match the message key`);
   }
   return subject ?? keyText;
 }
+function readRecordKey(recordKey) {
+  return recordKey === null ? null : decodeText(recordKey, { strict: true, label: "Message key" });
+}
 function collectUserHeaders(headers) {
   const entries = [];
   for (const [name, value] of headers) {
@@ -208,12 +253,250 @@ function toOutgoingHeaders(incoming) {
 function toBufferOrString(value) {
   return typeof value === "string" ? value : Buffer.from(value);
 }
-var PublishTimeoutError = class extends core.RelayBusError {
-  name = "PublishTimeoutError";
-};
-var HandlerFailedError = class extends core.RelayBusError {
-  name = "HandlerFailedError";
-};
+var { optionalAttribute, requiredAttribute, assertValidType, assertJsonDataContentType } = internal.createCloudEventReaders(invalid);
+var STRUCTURED_MEDIA_TYPE2 = "application/cloudevents+json";
+var exactUtf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+var SPEC_VERSION2 = "1.0";
+var SPEC_VERSION_HEADER = "ce_specversion";
+var STRUCTURED_ATTRIBUTES = /* @__PURE__ */ new Set([
+  "specversion",
+  "id",
+  "type",
+  "source",
+  "time",
+  "subject",
+  "datacontenttype",
+  "dataschema",
+  "data",
+  "data_base64",
+  "correlationid",
+  "causationid"
+]);
+function decodeCloudEvent(record) {
+  const headers = readHeaders(record.headers);
+  if (internal.mediaTypeOf(headers.get(CONTENT_TYPE)) !== STRUCTURED_MEDIA_TYPE2) {
+    return decodeEnvelope(record);
+  }
+  const body = parsePayload(record.value);
+  if (!internal.isJsonObject(body)) {
+    throw invalid("A structured CloudEvent must be a JSON object");
+  }
+  if (body["specversion"] !== SPEC_VERSION2) {
+    throw invalid(`specversion must be '${SPEC_VERSION2}'`);
+  }
+  const type = requiredAttribute(body, "type");
+  assertValidType(type, "type");
+  assertJsonDataContentType(optionalAttribute(body, "datacontenttype"));
+  if (Object.hasOwn(body, "data_base64")) {
+    throw invalid("data_base64 is not supported: relaybus payloads are JSON, send them as data");
+  }
+  const time = optionalAttribute(body, "time");
+  return {
+    id: requiredAttribute(body, "id"),
+    type,
+    source: requiredAttribute(body, "source"),
+    key: optionalAttribute(body, "subject") ?? readRecordKey(record.key),
+    payload: Object.hasOwn(body, "data") ? body["data"] : null,
+    headers: { ...collectUserHeaders(headers), ...extensionAttributes(body) },
+    correlationId: optionalAttribute(body, "correlationid") ?? null,
+    causationId: optionalAttribute(body, "causationid") ?? null,
+    occurredAt: time === void 0 ? requireRecordTimestamp(record) : parseTime(time, "time")
+  };
+}
+function plainJsonDecoder(options) {
+  if (typeof options.type === "string") {
+    core.assertEventType(options.type);
+  }
+  return (record) => {
+    const headers = readHeadersLeniently(record.headers);
+    if (record.headers?.[SPEC_VERSION_HEADER] !== void 0 || internal.mediaTypeOf(headers[CONTENT_TYPE]) === STRUCTURED_MEDIA_TYPE2) {
+      return decodeCloudEvent(record);
+    }
+    const plain = {
+      topic: record.topic,
+      partition: record.partition,
+      offset: record.offset,
+      key: readKeyLeniently(record.key),
+      headers,
+      payload: parsePayload(record.value),
+      timestamp: record.timestamp
+    };
+    const type = resolveText(options.type, { record: plain, name: "type" });
+    if (type === void 0) {
+      throw invalid("Record has no event type: the type option found none");
+    }
+    assertValidType(type, "The event type");
+    return {
+      id: resolveText(options.id, { record: plain, name: "id" }) ?? `kafka:${record.topic}:${record.partition}:${record.offset}`,
+      type,
+      source: resolveText(options.source, { record: plain, name: "source" }) ?? record.topic,
+      key: options.key === void 0 ? plain.key : resolveText(options.key, { record: plain, name: "key" }) ?? null,
+      payload: plain.payload,
+      headers,
+      correlationId: null,
+      causationId: null,
+      occurredAt: resolveOccurredAt(options.occurredAt, { plain, record })
+    };
+  };
+}
+function completeDecodedEvent(decoded, record) {
+  if (typeof decoded !== "object" || decoded === null) {
+    throw invalid("The decoder must return an event object synchronously");
+  }
+  if ("then" in decoded) {
+    observeRejection(decoded);
+    throw invalid("The decoder must return an event object synchronously");
+  }
+  const event = decoded;
+  return {
+    id: event.id,
+    type: event.type,
+    source: event.source ?? record.topic,
+    key: event.key === void 0 ? readRecordKey(record.key) : event.key,
+    payload: event.payload,
+    headers: event.headers ?? {},
+    correlationId: event.correlationId ?? null,
+    causationId: event.causationId ?? null,
+    occurredAt: event.occurredAt ?? requireRecordTimestamp(record)
+  };
+}
+function extensionAttributes(body) {
+  return Object.fromEntries(
+    Object.entries(body).filter(
+      (entry) => !STRUCTURED_ATTRIBUTES.has(entry[0]) && typeof entry[1] === "string"
+    )
+  );
+}
+function requireRecordTimestamp(record) {
+  const time = readRecordTimestamp(record.timestamp);
+  if (time === void 0) {
+    throw invalid("The event has no time and the record has no usable timestamp");
+  }
+  return time;
+}
+function readHeadersLeniently(incoming) {
+  const entries = [];
+  for (const [name, raw] of Object.entries(incoming ?? {})) {
+    const value = Array.isArray(raw) ? raw.at(-1) : raw;
+    const text = value === void 0 ? void 0 : decodeUtf8OrUndefined(value);
+    if (text !== void 0) {
+      entries.push([name, text]);
+    }
+  }
+  return Object.fromEntries(entries);
+}
+function decodeUtf8OrUndefined(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  try {
+    return exactUtf8.decode(value);
+  } catch {
+    return void 0;
+  }
+}
+function readKeyLeniently(key) {
+  if (key === null) {
+    return null;
+  }
+  try {
+    return readRecordKey(key);
+  } catch {
+    return Buffer.from(key).toString("base64");
+  }
+}
+function resolveText(option, { record, name }) {
+  const value = typeof option === "function" ? option(record) : option;
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (typeof value !== "string") {
+    observeRejection(value);
+    throw invalid(`The ${name} option returned ${typeof value}, expected a string`);
+  }
+  return value.length === 0 ? void 0 : value;
+}
+function resolveOccurredAt(option, { plain, record }) {
+  const value = option?.(plain);
+  if (value === void 0) {
+    return requireRecordTimestamp(record);
+  }
+  if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+    observeRejection(value);
+    throw invalid("The occurredAt option returned no valid Date");
+  }
+  return value;
+}
+function observeRejection(value) {
+  if (typeof value === "object" && value !== null && "then" in value) {
+    Promise.resolve(value).catch(() => void 0);
+  }
+}
+
+// src/codecs.ts
+var cloudEventsBinary = Object.freeze({
+  encode: encodeEnvelope,
+  decode: decodeEnvelope
+});
+var cloudEventsStructured = Object.freeze({
+  encode: encodeStructuredEnvelope,
+  decode: decodeCloudEvent
+});
+var RECORD_POSITION = "record-position";
+var EVENT_ID_HEADER = "relaybus-event-id";
+var DEFAULT_CONTENT_TYPE = "application/json";
+function jsonEnvelope(mapping) {
+  const format = internal.createJsonEnvelopeFormat(mapping, {
+    transportIds: [RECORD_POSITION],
+    failures: { invalid, unencodable: (reason) => new UnencodableEventError(reason) }
+  });
+  const contentType = mapping.contentType ?? DEFAULT_CONTENT_TYPE;
+  const stampsTime = mapping.occurredAt === void 0;
+  const ownHeaders = (envelope) => mapping.id === RECORD_POSITION ? { [CONTENT_TYPE]: contentType, [EVENT_ID_HEADER]: envelope.id } : { [CONTENT_TYPE]: contentType };
+  return {
+    encode: (envelope) => {
+      assertRepresentable(envelope);
+      const { body, headers } = format.write(envelope);
+      const taken = [CONTENT_TYPE, EVENT_ID_HEADER].find((name) => Object.hasOwn(headers, name));
+      if (taken !== void 0) {
+        throw new UnencodableEventError(
+          `Event ${envelope.id} has a header '${taken}', which the codec writes itself`
+        );
+      }
+      return {
+        key: envelope.key,
+        value: serializeJson(envelope, body),
+        headers: { ...headers, ...ownHeaders(envelope) },
+        ...stampsTime ? { timestamp: recordTimestamp(envelope) } : {}
+      };
+    },
+    decode: (record) => {
+      const { [EVENT_ID_HEADER]: eventId, ...headers } = withoutContentType(
+        readHeadersLeniently(record.headers)
+      );
+      const fields = format.read({ body: parsePayload(record.value), headers });
+      return {
+        ...fields,
+        id: fields.id ?? (eventId === void 0 || eventId === "" ? `kafka:${record.topic}:${record.partition}:${record.offset}` : eventId)
+      };
+    }
+  };
+}
+function withoutContentType(headers) {
+  return Object.fromEntries(Object.entries(headers).filter(([name]) => name !== CONTENT_TYPE));
+}
+function assertRepresentable(envelope) {
+  const kind = typeof envelope.payload;
+  if (kind === "undefined" || kind === "function" || kind === "symbol") {
+    throw new UnencodableEventError(
+      `Event ${envelope.id} has a payload that JSON cannot represent (undefined, a function or a symbol)`
+    );
+  }
+}
+function recordTimestamp(envelope) {
+  formatTime(envelope);
+  return String(envelope.occurredAt.getTime());
+}
 var DEFAULTS = {
   name: "kafka",
   maxInFlightRequests: 1,
@@ -228,6 +511,7 @@ var DEFAULTS = {
 };
 var KafkaTransport = class {
   name;
+  system = "kafka";
   #kafka;
   #groupId;
   #fromBeginning;
@@ -235,6 +519,7 @@ var KafkaTransport = class {
   #producerConfig;
   #consumerConfig;
   #invalidPolicy;
+  #codec;
   #logger;
   #settings;
   #sleepers = /* @__PURE__ */ new Set();
@@ -253,15 +538,13 @@ var KafkaTransport = class {
     this.#kafka = options.kafka;
     this.#groupId = options.groupId;
     this.#fromBeginning = options.fromBeginning ?? true;
-    this.#maxInFlightRequests = options.maxInFlightRequests ?? DEFAULTS.maxInFlightRequests;
-    if (!Number.isInteger(this.#maxInFlightRequests) || this.#maxInFlightRequests < 1 || this.#maxInFlightRequests > 5) {
-      throw new core.ConfigurationError(
-        `maxInFlightRequests must be an integer from 1 to 5, received ${this.#maxInFlightRequests}`
-      );
-    }
+    this.#maxInFlightRequests = assertMaxInFlightRequests(
+      options.maxInFlightRequests ?? DEFAULTS.maxInFlightRequests
+    );
     this.#producerConfig = options.producerConfig ?? {};
     this.#consumerConfig = options.consumerConfig ?? {};
     this.#invalidPolicy = options.onInvalidMessage ?? "dead-letter";
+    this.#codec = resolveCodec(options);
     this.#logger = options.logger ?? console;
     this.#settings = resolveSettings(options);
   }
@@ -291,11 +574,10 @@ var KafkaTransport = class {
   }
   async publish(envelope, destination) {
     const producer = await this.#connectedProducer();
-    const { key, value, headers } = encodeEnvelope(envelope);
     await this.#send(producer, {
       topic: destination,
       acks: -1,
-      messages: [{ key, value, headers }]
+      messages: [this.#codec.encode(envelope)]
     });
   }
   /**
@@ -305,13 +587,14 @@ var KafkaTransport = class {
    * @throws ConfigurationError when `groupId` is missing, `destinations` is empty
    * or the transport already subscribed (create one transport per subscription).
    */
-  async subscribe(destinations, onMessage) {
+  // eslint-disable-next-line relaybus/max-two-params -- the Transport.subscribe signature
+  async subscribe(destinations, onMessage, hooks) {
     this.#assertCanSubscribe(destinations);
     this.#state = "subscribed";
     const consumer = this.#kafka.consumer({ ...this.#consumerConfig, groupId: this.#groupId });
     this.#consumer = consumer;
     this.#observeConsumer(consumer);
-    const start = () => this.#startConsumer(consumer, [...destinations], onMessage);
+    const start = () => this.#startConsumer(consumer, { destinations: [...destinations], onMessage, hooks });
     this.#startConsuming = start;
     try {
       await start();
@@ -327,12 +610,18 @@ var KafkaTransport = class {
       `[KafkaTransport](subscribe) Consuming | transport=${this.name} group=${this.#groupId} topics=${destinations.join(",")}`
     );
   }
-  async #startConsumer(consumer, destinations, onMessage) {
+  async #startConsumer(consumer, {
+    destinations,
+    onMessage,
+    hooks
+  }) {
     await consumer.connect();
     await consumer.subscribe({ topics: destinations, fromBeginning: this.#fromBeginning });
     const joined = this.#waitForGroupJoin(consumer);
     try {
-      await consumer.run({ eachMessage: (payload) => this.#handleMessage(payload, onMessage) });
+      await consumer.run({
+        eachMessage: (payload) => this.#handleMessage(payload, { onMessage, hooks })
+      });
       await joined.promise;
     } finally {
       joined.dispose();
@@ -350,7 +639,7 @@ var KafkaTransport = class {
     for (const wake of this.#sleepers) {
       wake();
     }
-    this.#joinWaiter?.reject(new core.RelayBusError(`Transport '${this.name}' is closed`));
+    this.#joinWaiter?.reject(new TransportClosedError(`Transport '${this.name}' is closed`));
     await this.#restartLoop;
     const producer = await pendingProducer?.catch(() => void 0);
     const results = await Promise.allSettled([
@@ -364,7 +653,7 @@ var KafkaTransport = class {
   }
   #assertCanSubscribe(destinations) {
     if (this.#state === "closed") {
-      throw new core.RelayBusError(`Transport '${this.name}' is closed`);
+      throw new TransportClosedError(`Transport '${this.name}' is closed`);
     }
     if (this.#state === "subscribed") {
       throw new core.ConfigurationError(
@@ -400,27 +689,30 @@ var KafkaTransport = class {
   }
   /** Sends with the publish timeout; the late outcome of a timed-out send is ignored. */
   async #send(producer, record) {
-    let timer;
+    let cancel;
     const timeout = new Promise((_resolve, reject) => {
-      timer = setTimeout(() => {
-        reject(
-          new PublishTimeoutError(
-            `Transport '${this.name}' got no broker ack for topic '${record.topic}' within ${this.#settings.publishTimeoutMs}ms`
-          )
-        );
-      }, this.#settings.publishTimeoutMs);
+      cancel = internal.schedule(core.systemClock, {
+        run: () => {
+          reject(
+            new PublishTimeoutError(
+              `Transport '${this.name}' got no broker ack for topic '${record.topic}' within ${this.#settings.publishTimeoutMs}ms`
+            )
+          );
+        },
+        delayMs: this.#settings.publishTimeoutMs
+      });
     });
     const sending = producer.send(record);
     sending.catch(() => void 0);
     try {
       await Promise.race([sending, timeout]);
     } finally {
-      clearTimeout(timer);
+      cancel?.();
     }
   }
   #connectedProducer() {
     if (this.#state === "closed") {
-      return Promise.reject(new core.RelayBusError(`Transport '${this.name}' is closed`));
+      return Promise.reject(new TransportClosedError(`Transport '${this.name}' is closed`));
     }
     this.#producer ??= this.#openProducer();
     return this.#producer;
@@ -440,40 +732,63 @@ var KafkaTransport = class {
     this.#producerConnected = this.#state !== "closed";
     return producer;
   }
-  async #handleMessage(payload, onMessage) {
+  async #handleMessage(payload, {
+    onMessage,
+    hooks
+  }) {
     let envelope;
     try {
-      envelope = decodeEnvelope(payload.message);
+      envelope = this.#decodeRecord(payload);
     } catch (error) {
-      if (!(error instanceof InvalidKafkaMessageError)) {
+      if (this.#codec === cloudEventsBinary && !(error instanceof InvalidKafkaMessageError)) {
         throw toHandlerFailure(error);
       }
-      await this.#withRetries(
-        payload,
-        "handleInvalid",
-        () => this.#handleInvalid(payload, error.message)
-      );
+      hooks?.onInvalidMessage({ destination: payload.topic, error });
+      await this.#withRetries(payload, {
+        method: "handleInvalid",
+        operation: () => this.#handleInvalid(payload, error)
+      });
       return;
     }
-    await this.#withRetries(payload, "deliver", async () => {
-      try {
-        await onMessage(envelope);
-      } catch (error) {
-        if (!(error instanceof core.NonRetryableError)) {
-          throw error;
+    await this.#withRetries(payload, {
+      method: "deliver",
+      operation: async () => {
+        try {
+          await onMessage(envelope, { destination: payload.topic });
+        } catch (error) {
+          if (!(error instanceof core.NonRetryableError)) {
+            throw error;
+          }
+          await this.#handleInvalid(payload, error);
         }
-        await this.#handleInvalid(payload, error.message);
       }
     });
   }
-  async #handleInvalid(payload, reason) {
+  #decodeRecord({ topic, partition, message }) {
+    if (this.#codec === cloudEventsBinary) {
+      return decodeEnvelope(message);
+    }
+    const record = {
+      topic,
+      partition,
+      offset: message.offset,
+      key: message.key,
+      value: message.value,
+      headers: message.headers,
+      timestamp: message.timestamp
+    };
+    return completeDecodedEvent(this.#codec.decode(record), record);
+  }
+  async #handleInvalid(payload, error) {
     const { topic, partition, message } = payload;
+    const { message: reason, name, code } = core.toErrorInfo(error);
     const location = `topic=${topic} partition=${partition} offset=${message.offset}`;
+    const errorFields = `errorName=${name}${code === void 0 ? "" : ` code=${code}`}`;
     const policy = this.#invalidPolicy;
     const deadLetterTopic = this.#deadLetterTopicFor(topic);
     if (policy === "skip") {
       this.#logger.error(
-        `[KafkaTransport](handleInvalid) Skipping malformed message | ${location} reason=${reason}`
+        `[KafkaTransport](handleInvalid) Skipping malformed message | ${location} reason=${reason} ${errorFields}`
       );
     } else if (typeof policy === "function") {
       await policy({
@@ -485,6 +800,19 @@ var KafkaTransport = class {
         value: message.value
       });
     } else {
+      const headers = {
+        ...toOutgoingHeaders(message.headers),
+        "relaybus-invalid-reason": reason,
+        "relaybus-source-topic": topic,
+        "relaybus-source-partition": String(partition),
+        "relaybus-source-offset": message.offset,
+        "relaybus-error-name": name
+      };
+      if (code === void 0) {
+        delete headers["relaybus-error-code"];
+      } else {
+        headers["relaybus-error-code"] = code;
+      }
       const producer = await this.#connectedProducer();
       await this.#send(producer, {
         topic: deadLetterTopic,
@@ -493,18 +821,12 @@ var KafkaTransport = class {
           {
             key: message.key === null ? null : Buffer.from(message.key),
             value: message.value === null ? null : Buffer.from(message.value),
-            headers: {
-              ...toOutgoingHeaders(message.headers),
-              "relaybus-invalid-reason": reason,
-              "relaybus-source-topic": topic,
-              "relaybus-source-partition": String(partition),
-              "relaybus-source-offset": message.offset
-            }
+            headers
           }
         ]
       });
       this.#logger.error(
-        `[KafkaTransport](handleInvalid) Dead-lettered malformed message | ${location} deadLetterTopic=${deadLetterTopic} reason=${reason}`
+        `[KafkaTransport](handleInvalid) Dead-lettered malformed message | ${location} deadLetterTopic=${deadLetterTopic} reason=${reason} ${errorFields}`
       );
     }
   }
@@ -513,7 +835,7 @@ var KafkaTransport = class {
    * last error is rethrown so the client leaves the offset uncommitted and
    * redelivers the record; heartbeats between attempts keep the session alive.
    */
-  async #withRetries(payload, method, operation) {
+  async #withRetries(payload, { method, operation }) {
     const { maxAttempts, initialBackoffMs, maxBackoffMs } = this.#settings;
     const location = `topic=${payload.topic} partition=${payload.partition} offset=${payload.message.offset}`;
     const partitionKey = `${payload.topic}:${payload.partition}`;
@@ -527,12 +849,12 @@ var KafkaTransport = class {
         if (attempt >= maxAttempts || this.#state === "closed") {
           this.#stalledPartitions.add(partitionKey);
           this.#logger.error(
-            `[KafkaTransport](${method}) Giving up for now, the record stays uncommitted and will be redelivered | ${location} attempts=${attempt} error=${reason}`
+            `[KafkaTransport](withRetries) Giving up for now, the record stays uncommitted and will be redelivered | operation=${method} ${location} attempts=${attempt} error=${reason}`
           );
           throw toHandlerFailure(error);
         }
         this.#logger.warn(
-          `[KafkaTransport](${method}) Attempt failed, retrying | ${location} attempt=${attempt} error=${reason}`
+          `[KafkaTransport](withRetries) Attempt failed, retrying | operation=${method} ${location} attempt=${attempt} error=${reason}`
         );
         await this.#sleepWithHeartbeats(
           Math.min(initialBackoffMs * 2 ** (attempt - 1), maxBackoffMs),
@@ -554,11 +876,11 @@ var KafkaTransport = class {
   #sleep(milliseconds) {
     return new Promise((resolve) => {
       const wake = () => {
-        clearTimeout(timer);
+        cancel();
         this.#sleepers.delete(wake);
         resolve();
       };
-      const timer = setTimeout(wake, milliseconds);
+      const cancel = internal.schedule(core.systemClock, { run: wake, delayMs: milliseconds });
       this.#sleepers.add(wake);
     });
   }
@@ -640,42 +962,53 @@ var KafkaTransport = class {
     if (!this.#tracksMembership(consumer)) {
       return { promise: Promise.resolve(), dispose: () => void 0 };
     }
-    let timer;
+    let cancel;
     const promise = new Promise((resolve, reject) => {
       this.#joinWaiter = { resolve, reject };
-      timer = setTimeout(() => {
-        reject(
-          new core.RelayBusError(
-            `Consumer of transport '${this.name}' did not join group '${this.#groupId}' within ${this.#settings.startupTimeoutMs}ms`
-          )
-        );
-      }, this.#settings.startupTimeoutMs);
+      cancel = internal.schedule(core.systemClock, {
+        run: () => {
+          reject(
+            new GroupJoinTimeoutError(
+              `Consumer of transport '${this.name}' did not join group '${this.#groupId}' within ${this.#settings.startupTimeoutMs}ms`
+            )
+          );
+        },
+        delayMs: this.#settings.startupTimeoutMs
+      });
     });
     promise.catch(() => void 0);
     return {
       promise,
       dispose: () => {
-        clearTimeout(timer);
+        cancel?.();
         this.#joinWaiter = void 0;
       }
     };
   }
 };
-function resolveSettings(options) {
-  const maxAttempts = options.processing?.maxAttempts ?? DEFAULTS.maxAttempts;
-  if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
-    throw new core.ConfigurationError(
-      `processing.maxAttempts must be a positive integer, received ${maxAttempts}`
-    );
+function resolveCodec({ codec, decode }) {
+  if (decode === void 0) {
+    return codec ?? cloudEventsBinary;
   }
+  if (codec !== void 0) {
+    throw new core.ConfigurationError("Give 'codec' or the deprecated 'decode', not both");
+  }
+  return { encode: encodeEnvelope, decode };
+}
+function resolveSettings(options) {
+  const processing = options.processing ?? {};
+  const maxAttempts = internal.assertPositiveInteger(
+    processing.maxAttempts ?? DEFAULTS.maxAttempts,
+    "processing.maxAttempts"
+  );
   return {
     maxAttempts,
     initialBackoffMs: core.toMilliseconds(
-      options.processing?.initialBackoff ?? DEFAULTS.initialBackoff,
+      processing.initialBackoff ?? DEFAULTS.initialBackoff,
       "processing.initialBackoff"
     ),
     maxBackoffMs: core.toMilliseconds(
-      options.processing?.maxBackoff ?? DEFAULTS.maxBackoff,
+      processing.maxBackoff ?? DEFAULTS.maxBackoff,
       "processing.maxBackoff"
     ),
     startupTimeoutMs: core.toMilliseconds(
@@ -689,31 +1022,60 @@ function resolveSettings(options) {
     heartbeatIntervalMs: Math.max(
       1,
       core.toMilliseconds(
-        options.processing?.heartbeatInterval ?? DEFAULTS.heartbeatInterval,
+        processing.heartbeatInterval ?? DEFAULTS.heartbeatInterval,
         "processing.heartbeatInterval"
       )
     ),
+    ...resolveRestartSettings(options.restart ?? {})
+  };
+}
+function resolveRestartSettings(restart) {
+  return {
     restartInitialBackoffMs: core.toMilliseconds(
-      options.restart?.initialBackoff ?? DEFAULTS.restartInitialBackoff,
+      restart.initialBackoff ?? DEFAULTS.restartInitialBackoff,
       "restart.initialBackoff"
     ),
     restartMaxBackoffMs: core.toMilliseconds(
-      options.restart?.maxBackoff ?? DEFAULTS.restartMaxBackoff,
+      restart.maxBackoff ?? DEFAULTS.restartMaxBackoff,
       "restart.maxBackoff"
     )
   };
 }
+var MAXIMUM_IN_FLIGHT_REQUESTS = 5;
+function assertMaxInFlightRequests(value) {
+  if (!Number.isInteger(value) || value < 1 || value > MAXIMUM_IN_FLIGHT_REQUESTS) {
+    throw new core.ConfigurationError(
+      `maxInFlightRequests must be an integer from 1 to 5, received ${value}`
+    );
+  }
+  return value;
+}
 function toHandlerFailure(error) {
   const { name, message } = core.toErrorInfo(error);
   return new HandlerFailedError(`${name}: ${message}`);
 }
 
+Object.defineProperty(exports, "fromHeader", {
+  enumerable: true,
+  get: function () { return internal.fromHeader; }
+});
+Object.defineProperty(exports, "fromPayloadField", {
+  enumerable: true,
+  get: function () { return internal.fromPayloadField; }
+});
+exports.GroupJoinTimeoutError = GroupJoinTimeoutError;
 exports.HandlerFailedError = HandlerFailedError;
 exports.InvalidKafkaMessageError = InvalidKafkaMessageError;
 exports.KafkaTransport = KafkaTransport;
 exports.PublishTimeoutError = PublishTimeoutError;
+exports.TransportClosedError = TransportClosedError;
 exports.UnencodableEventError = UnencodableEventError;
+exports.cloudEventsBinary = cloudEventsBinary;
+exports.cloudEventsStructured = cloudEventsStructured;
+exports.decodeCloudEvent = decodeCloudEvent;
 exports.decodeEnvelope = decodeEnvelope;
 exports.encodeEnvelope = encodeEnvelope;
+exports.jsonEnvelope = jsonEnvelope;
+exports.plainJsonDecoder = plainJsonDecoder;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map