@relaybus/kafka 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,14 +1,36 @@
-import { RelayBusError, NonRetryableError, assertEventType, ConfigurationError, toErrorInfo, toMilliseconds } from '@relaybus/core';
+import { RelayBusError, NonRetryableError, assertEventType, ConfigurationError, systemClock, toErrorInfo, toMilliseconds } from '@relaybus/core';
+import { createCloudEventReaders, mediaTypeOf, isJsonObject, createJsonEnvelopeFormat, schedule, assertPositiveInteger, writeStructuredCloudEvent } from '@relaybus/core/internal';
+export { fromHeader, fromPayloadField } from '@relaybus/core/internal';
 
-// src/cloudevents-codec.ts
+// src/errors.ts
 var InvalidKafkaMessageError = class extends RelayBusError {
+  name = "InvalidKafkaMessageError";
+  code = "RELAYBUS_KAFKA_INVALID_MESSAGE";
 };
 var UnencodableEventError = class extends NonRetryableError {
   name = "UnencodableEventError";
+  code = "RELAYBUS_KAFKA_UNENCODABLE_EVENT";
+};
+var PublishTimeoutError = class extends RelayBusError {
+  name = "PublishTimeoutError";
+  code = "RELAYBUS_KAFKA_PUBLISH_TIMEOUT";
+};
+var TransportClosedError = class extends RelayBusError {
+  name = "TransportClosedError";
+  code = "RELAYBUS_KAFKA_TRANSPORT_CLOSED";
+};
+var GroupJoinTimeoutError = class extends RelayBusError {
+  name = "GroupJoinTimeoutError";
+  code = "RELAYBUS_KAFKA_GROUP_JOIN_TIMEOUT";
+};
+var HandlerFailedError = class extends 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-"];
@@ -23,6 +45,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");
@@ -50,25 +73,39 @@ function encodeEnvelope(envelope) {
   }
   return { key: envelope.key, value, headers: Object.fromEntries(entries) };
 }
+function encodeStructuredEnvelope(envelope) {
+  const value = 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)`
     );
@@ -116,11 +153,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;
   }
@@ -143,19 +183,19 @@ 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 time = readRecordTimestamp(recordTimestamp);
+  const time = readRecordTimestamp(recordTimestamp2);
   if (time === void 0) {
     throw invalid(`${HEADER.time} is missing and the record has no usable timestamp`);
   }
   return time;
 }
-function readRecordTimestamp(recordTimestamp) {
-  const time = new Date(Number(recordTimestamp));
-  return recordTimestamp === void 0 || recordTimestamp === "" || Number.isNaN(time.getTime()) ? void 0 : time;
+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);
@@ -168,7 +208,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 {
@@ -183,7 +223,7 @@ function resolveKey(subject, recordKey) {
   return subject ?? keyText;
 }
 function readRecordKey(recordKey) {
-  return recordKey === null ? null : decodeText(recordKey, true, "Message key");
+  return recordKey === null ? null : decodeText(recordKey, { strict: true, label: "Message key" });
 }
 function collectUserHeaders(headers) {
   const entries = [];
@@ -212,7 +252,8 @@ function toOutgoingHeaders(incoming) {
 function toBufferOrString(value) {
   return typeof value === "string" ? value : Buffer.from(value);
 }
-var STRUCTURED_MEDIA_TYPE = "application/cloudevents+json";
+var { optionalAttribute, requiredAttribute, assertValidType, assertJsonDataContentType } = 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";
@@ -232,7 +273,7 @@ var STRUCTURED_ATTRIBUTES = /* @__PURE__ */ new Set([
 ]);
 function decodeCloudEvent(record) {
   const headers = readHeaders(record.headers);
-  if (mediaTypeOf(headers.get(CONTENT_TYPE)) !== STRUCTURED_MEDIA_TYPE) {
+  if (mediaTypeOf(headers.get(CONTENT_TYPE)) !== STRUCTURED_MEDIA_TYPE2) {
     return decodeEnvelope(record);
   }
   const body = parsePayload(record.value);
@@ -267,7 +308,7 @@ function plainJsonDecoder(options) {
   }
   return (record) => {
     const headers = readHeadersLeniently(record.headers);
-    if (record.headers?.[SPEC_VERSION_HEADER] !== void 0 || mediaTypeOf(headers[CONTENT_TYPE]) === STRUCTURED_MEDIA_TYPE) {
+    if (record.headers?.[SPEC_VERSION_HEADER] !== void 0 || mediaTypeOf(headers[CONTENT_TYPE]) === STRUCTURED_MEDIA_TYPE2) {
       return decodeCloudEvent(record);
     }
     const plain = {
@@ -279,21 +320,21 @@ function plainJsonDecoder(options) {
       payload: parsePayload(record.value),
       timestamp: record.timestamp
     };
-    const type = resolveText(options.type, plain, "type");
+    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, plain, "id") ?? `kafka:${record.topic}:${record.partition}:${record.offset}`,
+      id: resolveText(options.id, { record: plain, name: "id" }) ?? `kafka:${record.topic}:${record.partition}:${record.offset}`,
       type,
-      source: resolveText(options.source, plain, "source") ?? record.topic,
-      key: options.key === void 0 ? plain.key : resolveText(options.key, plain, "key") ?? null,
+      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)
+      occurredAt: resolveOccurredAt(options.occurredAt, { plain, record })
     };
   };
 }
@@ -318,39 +359,6 @@ function completeDecodedEvent(decoded, record) {
     occurredAt: event.occurredAt ?? requireRecordTimestamp(record)
   };
 }
-function mediaTypeOf(contentType) {
-  return contentType?.split(";")[0]?.trim().toLowerCase();
-}
-function isJsonObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function optionalAttribute(body, name) {
-  const value = body[name];
-  if (value !== void 0 && typeof value !== "string") {
-    throw invalid(`Attribute '${name}' must be a string`);
-  }
-  return value;
-}
-function requiredAttribute(body, name) {
-  const value = optionalAttribute(body, name);
-  if (value === void 0 || value.length === 0) {
-    throw invalid(`Attribute '${name}' is missing or empty`);
-  }
-  return value;
-}
-function assertValidType(type, label) {
-  try {
-    assertEventType(type);
-  } catch (error) {
-    throw invalid(`${label} is not a valid event type: ${error.message}`);
-  }
-}
-function assertJsonDataContentType(dataContentType) {
-  const mediaType = mediaTypeOf(dataContentType);
-  if (mediaType !== void 0 && mediaType !== "application/json" && mediaType !== "text/json" && !mediaType.endsWith("+json")) {
-    throw invalid(`datacontenttype must be JSON, received '${dataContentType}'`);
-  }
-}
 function extensionAttributes(body) {
   return Object.fromEntries(
     Object.entries(body).filter(
@@ -396,7 +404,7 @@ function readKeyLeniently(key) {
     return Buffer.from(key).toString("base64");
   }
 }
-function resolveText(option, record, name) {
+function resolveText(option, { record, name }) {
   const value = typeof option === "function" ? option(record) : option;
   if (value === void 0 || value === null) {
     return void 0;
@@ -407,7 +415,7 @@ function resolveText(option, record, name) {
   }
   return value.length === 0 ? void 0 : value;
 }
-function resolveOccurredAt(option, plain, record) {
+function resolveOccurredAt(option, { plain, record }) {
   const value = option?.(plain);
   if (value === void 0) {
     return requireRecordTimestamp(record);
@@ -424,13 +432,70 @@ function observeRejection(value) {
   }
 }
 
-// src/kafka-transport.ts
-var PublishTimeoutError = class extends RelayBusError {
-  name = "PublishTimeoutError";
-};
-var HandlerFailedError = class extends RelayBusError {
-  name = "HandlerFailedError";
-};
+// 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 = 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,
@@ -445,6 +510,7 @@ var DEFAULTS = {
 };
 var KafkaTransport = class {
   name;
+  system = "kafka";
   #kafka;
   #groupId;
   #fromBeginning;
@@ -452,7 +518,7 @@ var KafkaTransport = class {
   #producerConfig;
   #consumerConfig;
   #invalidPolicy;
-  #decode;
+  #codec;
   #logger;
   #settings;
   #sleepers = /* @__PURE__ */ new Set();
@@ -471,16 +537,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 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.#decode = options.decode;
+    this.#codec = resolveCodec(options);
     this.#logger = options.logger ?? console;
     this.#settings = resolveSettings(options);
   }
@@ -510,11 +573,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)]
     });
   }
   /**
@@ -524,13 +586,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();
@@ -546,12 +609,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();
@@ -569,7 +638,7 @@ var KafkaTransport = class {
     for (const wake of this.#sleepers) {
       wake();
     }
-    this.#joinWaiter?.reject(new 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([
@@ -583,7 +652,7 @@ var KafkaTransport = class {
   }
   #assertCanSubscribe(destinations) {
     if (this.#state === "closed") {
-      throw new RelayBusError(`Transport '${this.name}' is closed`);
+      throw new TransportClosedError(`Transport '${this.name}' is closed`);
     }
     if (this.#state === "subscribed") {
       throw new ConfigurationError(
@@ -619,27 +688,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 = schedule(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 RelayBusError(`Transport '${this.name}' is closed`));
+      return Promise.reject(new TransportClosedError(`Transport '${this.name}' is closed`));
     }
     this.#producer ??= this.#openProducer();
     return this.#producer;
@@ -659,31 +731,40 @@ var KafkaTransport = class {
     this.#producerConnected = this.#state !== "closed";
     return producer;
   }
-  async #handleMessage(payload, onMessage) {
+  async #handleMessage(payload, {
+    onMessage,
+    hooks
+  }) {
     let envelope;
     try {
       envelope = this.#decodeRecord(payload);
     } catch (error) {
-      if (this.#decode === void 0 && !(error instanceof InvalidKafkaMessageError)) {
+      if (this.#codec === cloudEventsBinary && !(error instanceof InvalidKafkaMessageError)) {
         throw toHandlerFailure(error);
       }
-      const reason = toErrorInfo(error).message;
-      await this.#withRetries(payload, "handleInvalid", () => this.#handleInvalid(payload, reason));
+      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 NonRetryableError)) {
-          throw error;
+    await this.#withRetries(payload, {
+      method: "deliver",
+      operation: async () => {
+        try {
+          await onMessage(envelope, { destination: payload.topic });
+        } catch (error) {
+          if (!(error instanceof NonRetryableError)) {
+            throw error;
+          }
+          await this.#handleInvalid(payload, error);
         }
-        await this.#handleInvalid(payload, error.message);
       }
     });
   }
   #decodeRecord({ topic, partition, message }) {
-    if (this.#decode === void 0) {
+    if (this.#codec === cloudEventsBinary) {
       return decodeEnvelope(message);
     }
     const record = {
@@ -695,16 +776,18 @@ var KafkaTransport = class {
       headers: message.headers,
       timestamp: message.timestamp
     };
-    return completeDecodedEvent(this.#decode(record), record);
+    return completeDecodedEvent(this.#codec.decode(record), record);
   }
-  async #handleInvalid(payload, reason) {
+  async #handleInvalid(payload, error) {
     const { topic, partition, message } = payload;
+    const { message: reason, name, code } = 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({
@@ -716,6 +799,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,
@@ -724,18 +820,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}`
       );
     }
   }
@@ -744,7 +834,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}`;
@@ -758,12 +848,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),
@@ -785,11 +875,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 = schedule(systemClock, { run: wake, delayMs: milliseconds });
       this.#sleepers.add(wake);
     });
   }
@@ -871,42 +961,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 RelayBusError(
-            `Consumer of transport '${this.name}' did not join group '${this.#groupId}' within ${this.#settings.startupTimeoutMs}ms`
-          )
-        );
-      }, this.#settings.startupTimeoutMs);
+      cancel = schedule(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 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 ConfigurationError("Give 'codec' or the deprecated 'decode', not both");
   }
+  return { encode: encodeEnvelope, decode };
+}
+function resolveSettings(options) {
+  const processing = options.processing ?? {};
+  const maxAttempts = assertPositiveInteger(
+    processing.maxAttempts ?? DEFAULTS.maxAttempts,
+    "processing.maxAttempts"
+  );
   return {
     maxAttempts,
     initialBackoffMs: toMilliseconds(
-      options.processing?.initialBackoff ?? DEFAULTS.initialBackoff,
+      processing.initialBackoff ?? DEFAULTS.initialBackoff,
       "processing.initialBackoff"
     ),
     maxBackoffMs: toMilliseconds(
-      options.processing?.maxBackoff ?? DEFAULTS.maxBackoff,
+      processing.maxBackoff ?? DEFAULTS.maxBackoff,
       "processing.maxBackoff"
     ),
     startupTimeoutMs: toMilliseconds(
@@ -920,52 +1021,39 @@ function resolveSettings(options) {
     heartbeatIntervalMs: Math.max(
       1,
       toMilliseconds(
-        options.processing?.heartbeatInterval ?? DEFAULTS.heartbeatInterval,
+        processing.heartbeatInterval ?? DEFAULTS.heartbeatInterval,
         "processing.heartbeatInterval"
       )
     ),
+    ...resolveRestartSettings(options.restart ?? {})
+  };
+}
+function resolveRestartSettings(restart) {
+  return {
     restartInitialBackoffMs: toMilliseconds(
-      options.restart?.initialBackoff ?? DEFAULTS.restartInitialBackoff,
+      restart.initialBackoff ?? DEFAULTS.restartInitialBackoff,
       "restart.initialBackoff"
     ),
     restartMaxBackoffMs: toMilliseconds(
-      options.restart?.maxBackoff ?? DEFAULTS.restartMaxBackoff,
+      restart.maxBackoff ?? DEFAULTS.restartMaxBackoff,
       "restart.maxBackoff"
     )
   };
 }
-function toHandlerFailure(error) {
-  const { name, message } = toErrorInfo(error);
-  return new HandlerFailedError(`${name}: ${message}`);
-}
-function fromHeader(name) {
-  if (name.length === 0) {
-    throw new ConfigurationError("fromHeader needs a header name");
-  }
-  return (message) => Object.hasOwn(message.headers, name) ? message.headers[name] : void 0;
-}
-function fromPayloadField(path) {
-  const segments = path.split(".");
-  if (segments.some((segment) => segment.length === 0)) {
+var MAXIMUM_IN_FLIGHT_REQUESTS = 5;
+function assertMaxInFlightRequests(value) {
+  if (!Number.isInteger(value) || value < 1 || value > MAXIMUM_IN_FLIGHT_REQUESTS) {
     throw new ConfigurationError(
-      `fromPayloadField needs a dotted path of non-empty names, received '${path}'`
+      `maxInFlightRequests must be an integer from 1 to 5, received ${value}`
     );
   }
-  return (message) => {
-    let value = message.payload;
-    for (const segment of segments) {
-      if (typeof value !== "object" || value === null || !Object.hasOwn(value, segment)) {
-        return void 0;
-      }
-      value = value[segment];
-    }
-    if (typeof value === "string") {
-      return value;
-    }
-    return Number.isSafeInteger(value) ? String(value) : void 0;
-  };
+  return value;
+}
+function toHandlerFailure(error) {
+  const { name, message } = toErrorInfo(error);
+  return new HandlerFailedError(`${name}: ${message}`);
 }
 
-export { HandlerFailedError, InvalidKafkaMessageError, KafkaTransport, PublishTimeoutError, UnencodableEventError, decodeCloudEvent, decodeEnvelope, encodeEnvelope, fromHeader, fromPayloadField, plainJsonDecoder };
+export { GroupJoinTimeoutError, HandlerFailedError, InvalidKafkaMessageError, KafkaTransport, PublishTimeoutError, TransportClosedError, UnencodableEventError, cloudEventsBinary, cloudEventsStructured, decodeCloudEvent, decodeEnvelope, encodeEnvelope, jsonEnvelope, plainJsonDecoder };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map