@relaybus/kafka 0.3.0 → 0.3.1

package/dist/index.cjs

@@ -312,25 +312,17 @@ function plainJsonDecoder(options) {
     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" });
+    const plain = plainRecordOf(record, headers);
+    const type = KAFKA_EVENTS.text(options.type, { 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}`,
+      id: KAFKA_EVENTS.text(options.id, { 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,
+      source: KAFKA_EVENTS.text(options.source, { plain, name: "source" }) ?? record.topic,
+      key: options.key === void 0 ? plain.key : KAFKA_EVENTS.text(options.key, { plain, name: "key" }) ?? null,
       payload: plain.payload,
       headers,
       correlationId: null,
@@ -339,27 +331,38 @@ function plainJsonDecoder(options) {
     };
   };
 }
-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;
+function plainRecordOf(record, headers) {
   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)
+    topic: record.topic,
+    partition: record.partition,
+    offset: record.offset,
+    key: readKeyLeniently(record.key),
+    headers,
+    payload: parsePayload(record.value),
+    timestamp: record.timestamp
   };
 }
+var KafkaDecodedEvents = class extends internal.DecodedEventReader {
+  invalid(reason) {
+    return invalid(reason);
+  }
+  /** The topic. */
+  defaultSource(record) {
+    return record.topic;
+  }
+  /** The record key as UTF-8 text. */
+  defaultKey(record) {
+    return readRecordKey(record.key);
+  }
+  /** The record timestamp; a record without a usable one is malformed. */
+  defaultTime(record) {
+    return requireRecordTimestamp(record);
+  }
+};
+var KAFKA_EVENTS = new KafkaDecodedEvents();
+function completeDecodedEvent(decoded, record) {
+  return KAFKA_EVENTS.complete(decoded, record);
+}
 function extensionAttributes(body) {
   return Object.fromEntries(
     Object.entries(body).filter(
@@ -405,33 +408,17 @@ function readKeyLeniently(key) {
     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);
+    internal.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({
@@ -454,32 +441,34 @@ function jsonEnvelope(mapping) {
   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)
-      };
-    }
+    encode: (envelope) => encodeJson(envelope, { format, stampsTime, ownHeaders }),
+    decode: (record) => decodeJson(record, format)
+  };
+}
+function encodeJson(envelope, { format, stampsTime, ownHeaders }) {
+  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) } : {}
+  };
+}
+function decodeJson(record, format) {
+  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) {
@@ -497,6 +486,139 @@ function recordTimestamp(envelope) {
   formatTime(envelope);
   return String(envelope.occurredAt.getTime());
 }
+function tracksMembership(consumer) {
+  return consumer.on !== void 0 && consumer.events?.GROUP_JOIN !== void 0;
+}
+var GroupJoinWatch = class {
+  #settings;
+  #waiter;
+  constructor(settings) {
+    this.#settings = settings;
+  }
+  /** The consumer joined its group. */
+  joined() {
+    this.#waiter?.resolve();
+  }
+  /** The consumer crashed while it was joining. */
+  failed(error) {
+    this.#waiter?.reject(error);
+  }
+  /** The transport closed while the consumer was joining. */
+  closed() {
+    this.#waiter?.reject(new TransportClosedError(`Transport '${this.#settings.name}' is closed`));
+  }
+  /** Connects and subscribes the consumer, runs it and resolves once it joined its group. */
+  async start(consumer, {
+    topics,
+    fromBeginning,
+    eachMessage
+  }) {
+    await consumer.connect();
+    await consumer.subscribe({ topics, fromBeginning });
+    const joined = this.#wait(consumer);
+    try {
+      await consumer.run({ eachMessage });
+      await joined.promise;
+    } finally {
+      joined.dispose();
+    }
+  }
+  #wait(consumer) {
+    if (!tracksMembership(consumer)) {
+      return { promise: Promise.resolve(), dispose: () => void 0 };
+    }
+    const { name, groupId, timings } = this.#settings;
+    let cancel;
+    const promise = new Promise((resolve, reject) => {
+      this.#waiter = { resolve, reject };
+      cancel = internal.schedule(core.systemClock, {
+        run: () => {
+          reject(
+            new GroupJoinTimeoutError(
+              `Consumer of transport '${name}' did not join group '${groupId}' within ${timings.startupTimeoutMs}ms`
+            )
+          );
+        },
+        delayMs: timings.startupTimeoutMs
+      });
+    });
+    promise.catch(() => void 0);
+    return {
+      promise,
+      dispose: () => {
+        cancel?.();
+        this.#waiter = void 0;
+      }
+    };
+  }
+};
+var KafkaProducerSession = class {
+  #settings;
+  /** Whether the transport is closed: then nothing connects any more. */
+  #isClosed;
+  #producer;
+  #connected = false;
+  constructor(settings, isClosed) {
+    this.#settings = settings;
+    this.#isClosed = isClosed;
+  }
+  /** True once the producer connected, until the transport closes. */
+  get isConnected() {
+    return this.#connected;
+  }
+  /** The producer opened so far, if any: what closing must disconnect. */
+  get pending() {
+    return this.#producer;
+  }
+  markClosed() {
+    this.#connected = false;
+  }
+  connected() {
+    if (this.#isClosed()) {
+      return Promise.reject(
+        new TransportClosedError(`Transport '${this.#settings.name}' is closed`)
+      );
+    }
+    this.#producer ??= this.#open();
+    return this.#producer;
+  }
+  /** Sends with the publish timeout; the late outcome of a timed-out send is ignored. */
+  async send(producer, record) {
+    const { name, timings } = this.#settings;
+    let cancel;
+    const timeout = new Promise((_resolve, reject) => {
+      cancel = internal.schedule(core.systemClock, {
+        run: () => {
+          reject(
+            new PublishTimeoutError(
+              `Transport '${name}' got no broker ack for topic '${record.topic}' within ${timings.publishTimeoutMs}ms`
+            )
+          );
+        },
+        delayMs: timings.publishTimeoutMs
+      });
+    });
+    const sending = producer.send(record);
+    sending.catch(() => void 0);
+    try {
+      await Promise.race([sending, timeout]);
+    } finally {
+      cancel?.();
+    }
+  }
+  async #open() {
+    const { kafka, producerConfig, maxInFlightRequests } = this.#settings;
+    const producer = kafka.producer({ ...producerConfig, idempotent: true, maxInFlightRequests });
+    try {
+      await producer.connect();
+    } catch (error) {
+      this.#producer = void 0;
+      throw error;
+    }
+    this.#connected = !this.#isClosed();
+    return producer;
+  }
+};
 var DEFAULTS = {
   name: "kafka",
   maxInFlightRequests: 1,
@@ -509,44 +631,224 @@ var DEFAULTS = {
   restartInitialBackoff: "1s",
   restartMaxBackoff: "30s"
 };
-var KafkaTransport = class {
+var MAXIMUM_IN_FLIGHT_REQUESTS = 5;
+function resolveKafkaSettings(options) {
+  return {
+    name: options.name ?? DEFAULTS.name,
+    kafka: options.kafka,
+    groupId: options.groupId,
+    fromBeginning: options.fromBeginning ?? true,
+    maxInFlightRequests: internal.BoundedInteger.of(
+      options.maxInFlightRequests ?? DEFAULTS.maxInFlightRequests,
+      { name: "maxInFlightRequests", minimum: 1, maximum: MAXIMUM_IN_FLIGHT_REQUESTS }
+    ),
+    producerConfig: options.producerConfig ?? {},
+    consumerConfig: options.consumerConfig ?? {},
+    invalidPolicy: options.onInvalidMessage ?? "dead-letter",
+    codec: resolveCodec(options),
+    logger: options.logger ?? console,
+    timings: resolveTimings(options)
+  };
+}
+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 resolveTimings(options) {
+  const processing = options.processing ?? {};
+  const maxAttempts = internal.PositiveInteger.of(
+    processing.maxAttempts ?? DEFAULTS.maxAttempts,
+    "processing.maxAttempts"
+  );
+  return {
+    maxAttempts,
+    processingBackoff: new internal.ExponentialBackoff({
+      initialMs: internal.Milliseconds.of(
+        processing.initialBackoff ?? DEFAULTS.initialBackoff,
+        "processing.initialBackoff"
+      ),
+      maxMs: internal.Milliseconds.of(processing.maxBackoff ?? DEFAULTS.maxBackoff, "processing.maxBackoff")
+    }),
+    startupTimeoutMs: internal.Milliseconds.of(
+      options.startupTimeout ?? DEFAULTS.startupTimeout,
+      "startupTimeout"
+    ),
+    publishTimeoutMs: internal.Milliseconds.of(
+      options.publishTimeout ?? DEFAULTS.publishTimeout,
+      "publishTimeout"
+    ),
+    heartbeatIntervalMs: Math.max(
+      1,
+      internal.Milliseconds.of(
+        processing.heartbeatInterval ?? DEFAULTS.heartbeatInterval,
+        "processing.heartbeatInterval"
+      )
+    ),
+    restartBackoff: resolveRestartBackoff(options.restart ?? {})
+  };
+}
+function resolveRestartBackoff(restart) {
+  return new internal.ExponentialBackoff({
+    initialMs: internal.Milliseconds.of(
+      restart.initialBackoff ?? DEFAULTS.restartInitialBackoff,
+      "restart.initialBackoff"
+    ),
+    maxMs: internal.Milliseconds.of(restart.maxBackoff ?? DEFAULTS.restartMaxBackoff, "restart.maxBackoff")
+  });
+}
+function deadLetterTopicFor(policy, sourceTopic) {
+  if (policy === "dead-letter") {
+    return `${sourceTopic}.dead`;
+  }
+  if (typeof policy === "object") {
+    const { deadLetterTopic } = policy;
+    return typeof deadLetterTopic === "function" ? deadLetterTopic(sourceTopic) : deadLetterTopic;
+  }
+  return void 0;
+}
+function toHandlerFailure(error) {
+  const { name, message } = core.toErrorInfo(error);
+  return new HandlerFailedError(`${name}: ${message}`);
+}
+function assertCanSubscribe(state, {
+  settings,
+  destinations
+}) {
+  const { name, groupId, invalidPolicy } = settings;
+  if (state === "closed") {
+    throw new TransportClosedError(`Transport '${name}' is closed`);
+  }
+  if (state === "subscribed") {
+    throw new core.ConfigurationError(
+      `Transport '${name}' already subscribed; list every topic in one subscription or use one KafkaTransport per consumer group`
+    );
+  }
+  if (groupId === void 0 || groupId.length === 0) {
+    throw new core.ConfigurationError(`Transport '${name}' needs a groupId to subscribe`);
+  }
+  if (destinations.length === 0) {
+    throw new core.ConfigurationError(`Transport '${name}' subscribed to no topics`);
+  }
+  for (const topic of destinations) {
+    const deadLetterTopic = deadLetterTopicFor(invalidPolicy, topic);
+    if (deadLetterTopic !== void 0 && destinations.includes(deadLetterTopic)) {
+      throw new core.ConfigurationError(
+        `Dead letter topic '${deadLetterTopic}' is also consumed, which would loop`
+      );
+    }
+  }
+}
+
+// src/kafka-records.ts
+function decodeRecord(codec, { topic, partition, message }) {
+  if (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(codec.decode(record), record);
+}
+function deadLetterRecord({ topic, partition, message }, {
+  reason,
+  name,
+  code,
+  deadLetterTopic
+}) {
+  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;
+  }
+  return {
+    topic: deadLetterTopic,
+    acks: -1,
+    messages: [
+      {
+        key: message.key === null ? null : Buffer.from(message.key),
+        value: message.value === null ? null : Buffer.from(message.value),
+        headers
+      }
+    ]
+  };
+}
+var WakeableSleeps = class {
+  #sleepers = /* @__PURE__ */ new Set();
+  sleep(milliseconds) {
+    return new Promise((resolve) => {
+      const wake = () => {
+        cancel();
+        this.#sleepers.delete(wake);
+        resolve();
+      };
+      const cancel = internal.schedule(core.systemClock, { run: wake, delayMs: milliseconds });
+      this.#sleepers.add(wake);
+    });
+  }
+  wakeAll() {
+    for (const wake of this.#sleepers) {
+      wake();
+    }
+  }
+  /**
+   * Sleeps `milliseconds` in slices of at most `sliceMs`, running `between` after each, until done
+   * or `stopped`: a long backoff then never outlives the session timeout.
+   */
+  async sleepInSlices(milliseconds, {
+    sliceMs,
+    between,
+    stopped
+  }) {
+    let remaining = milliseconds;
+    do {
+      const slice = Math.min(remaining, sliceMs);
+      await this.sleep(slice);
+      await between();
+      remaining -= slice;
+    } while (remaining > 0 && !stopped());
+  }
+};
+
+// src/kafka-transport.ts
+var KafkaTransport = class extends internal.SubscribingTransport {
   name;
   system = "kafka";
-  #kafka;
-  #groupId;
-  #fromBeginning;
-  #maxInFlightRequests;
-  #producerConfig;
-  #consumerConfig;
-  #invalidPolicy;
-  #codec;
-  #logger;
   #settings;
-  #sleepers = /* @__PURE__ */ new Set();
-  #state = "idle";
   #producer;
+  #groupJoin;
+  #sleeps = new WakeableSleeps();
+  #state = "idle";
   #consumer;
   #groupJoined = false;
   #consuming = false;
-  #producerConnected = false;
   #restartLoop;
   #stalledPartitions = /* @__PURE__ */ new Set();
   #startConsuming;
-  #joinWaiter;
   constructor(options) {
-    this.name = options.name ?? DEFAULTS.name;
-    this.#kafka = options.kafka;
-    this.#groupId = options.groupId;
-    this.#fromBeginning = options.fromBeginning ?? true;
-    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);
+    super();
+    this.#settings = resolveKafkaSettings(options);
+    this.name = this.#settings.name;
+    this.#producer = new KafkaProducerSession(this.#settings, () => this.#state === "closed");
+    this.#groupJoin = new GroupJoinWatch(this.#settings);
   }
   /**
    * True while the consumer is joined to its group, not between a crash or
@@ -563,21 +865,21 @@ var KafkaTransport = class {
    * dead consumer is being restarted.
    */
   isReady() {
-    if (this.#state === "closed" || !this.#producerConnected) {
+    if (this.#state === "closed" || !this.#producer.isConnected) {
       return false;
     }
     return this.#state === "idle" || this.isConsuming();
   }
   /** Connects the producer. Called by the bus on start; `publish` also connects on demand. */
   async connect() {
-    await this.#connectedProducer();
+    await this.#producer.connected();
   }
   async publish(envelope, destination) {
-    const producer = await this.#connectedProducer();
-    await this.#send(producer, {
+    const producer = await this.#producer.connected();
+    await this.#producer.send(producer, {
       topic: destination,
       acks: -1,
-      messages: [this.#codec.encode(envelope)]
+      messages: [this.#settings.codec.encode(envelope)]
     });
   }
   /**
@@ -587,14 +889,21 @@ var KafkaTransport = class {
    * @throws ConfigurationError when `groupId` is missing, `destinations` is empty
    * or the transport already subscribed (create one transport per subscription).
    */
-  // eslint-disable-next-line relaybus/max-two-params -- the Transport.subscribe signature
-  async subscribe(destinations, onMessage, hooks) {
-    this.#assertCanSubscribe(destinations);
+  openSubscription(subscription) {
+    return this.#subscribe(subscription);
+  }
+  async #subscribe({ destinations, onMessage, hooks }) {
+    assertCanSubscribe(this.#state, { settings: this.#settings, destinations });
     this.#state = "subscribed";
-    const consumer = this.#kafka.consumer({ ...this.#consumerConfig, groupId: this.#groupId });
+    const { kafka, consumerConfig, groupId } = this.#settings;
+    const consumer = kafka.consumer({ ...consumerConfig, groupId });
     this.#consumer = consumer;
     this.#observeConsumer(consumer);
-    const start = () => this.#startConsumer(consumer, { destinations: [...destinations], onMessage, hooks });
+    const start = () => this.#groupJoin.start(consumer, {
+      topics: [...destinations],
+      fromBeginning: this.#settings.fromBeginning,
+      eachMessage: (payload) => this.#handleMessage(payload, { onMessage, hooks })
+    });
     this.#startConsuming = start;
     try {
       await start();
@@ -606,40 +915,21 @@ var KafkaTransport = class {
       throw error;
     }
     this.#consuming = true;
-    this.#logger.log(
-      `[KafkaTransport](subscribe) Consuming | transport=${this.name} group=${this.#groupId} topics=${destinations.join(",")}`
+    this.#settings.logger.log(
+      `[KafkaTransport](subscribe) Consuming | transport=${this.name} group=${groupId} topics=${destinations.join(",")}`
     );
   }
-  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, hooks })
-      });
-      await joined.promise;
-    } finally {
-      joined.dispose();
-    }
-  }
   /** Stops consuming and disconnects the consumer and the producer. Safe to call twice. */
   async close() {
     if (this.#state === "closed") {
       return;
     }
     this.#state = "closed";
-    const pendingProducer = this.#producer;
+    const pendingProducer = this.#producer.pending;
     this.#groupJoined = false;
-    this.#producerConnected = false;
-    for (const wake of this.#sleepers) {
-      wake();
-    }
-    this.#joinWaiter?.reject(new TransportClosedError(`Transport '${this.name}' is closed`));
+    this.#producer.markClosed();
+    this.#sleeps.wakeAll();
+    this.#groupJoin.closed();
     await this.#restartLoop;
     const producer = await pendingProducer?.catch(() => void 0);
     const results = await Promise.allSettled([
@@ -651,99 +941,15 @@ var KafkaTransport = class {
       throw failure.reason;
     }
   }
-  #assertCanSubscribe(destinations) {
-    if (this.#state === "closed") {
-      throw new TransportClosedError(`Transport '${this.name}' is closed`);
-    }
-    if (this.#state === "subscribed") {
-      throw new core.ConfigurationError(
-        `Transport '${this.name}' already subscribed; list every topic in one subscription or use one KafkaTransport per consumer group`
-      );
-    }
-    if (this.#groupId === void 0 || this.#groupId.length === 0) {
-      throw new core.ConfigurationError(`Transport '${this.name}' needs a groupId to subscribe`);
-    }
-    if (destinations.length === 0) {
-      throw new core.ConfigurationError(`Transport '${this.name}' subscribed to no topics`);
-    }
-    for (const topic of destinations) {
-      const deadLetterTopic = this.#deadLetterTopicFor(topic);
-      if (deadLetterTopic !== void 0 && destinations.includes(deadLetterTopic)) {
-        throw new core.ConfigurationError(
-          `Dead letter topic '${deadLetterTopic}' is also consumed, which would loop`
-        );
-      }
-    }
-  }
-  /** The dead-letter topic for records of `sourceTopic`, or undefined when the policy does not use one. */
-  #deadLetterTopicFor(sourceTopic) {
-    const policy = this.#invalidPolicy;
-    if (policy === "dead-letter") {
-      return `${sourceTopic}.dead`;
-    }
-    if (typeof policy === "object") {
-      const { deadLetterTopic } = policy;
-      return typeof deadLetterTopic === "function" ? deadLetterTopic(sourceTopic) : deadLetterTopic;
-    }
-    return void 0;
-  }
-  /** Sends with the publish timeout; the late outcome of a timed-out send is ignored. */
-  async #send(producer, record) {
-    let cancel;
-    const timeout = new Promise((_resolve, reject) => {
-      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 {
-      cancel?.();
-    }
-  }
-  #connectedProducer() {
-    if (this.#state === "closed") {
-      return Promise.reject(new TransportClosedError(`Transport '${this.name}' is closed`));
-    }
-    this.#producer ??= this.#openProducer();
-    return this.#producer;
-  }
-  async #openProducer() {
-    const producer = this.#kafka.producer({
-      ...this.#producerConfig,
-      idempotent: true,
-      maxInFlightRequests: this.#maxInFlightRequests
-    });
-    try {
-      await producer.connect();
-    } catch (error) {
-      this.#producer = void 0;
-      throw error;
-    }
-    this.#producerConnected = this.#state !== "closed";
-    return producer;
-  }
-  async #handleMessage(payload, {
-    onMessage,
-    hooks
-  }) {
+  async #handleMessage(payload, route) {
     let envelope;
     try {
-      envelope = this.#decodeRecord(payload);
+      envelope = decodeRecord(this.#settings.codec, payload);
     } catch (error) {
-      if (this.#codec === cloudEventsBinary && !(error instanceof InvalidKafkaMessageError)) {
+      if (this.#settings.codec === cloudEventsBinary && !(error instanceof InvalidKafkaMessageError)) {
         throw toHandlerFailure(error);
       }
-      hooks?.onInvalidMessage({ destination: payload.topic, error });
+      route.hooks?.onInvalidMessage({ destination: payload.topic, error });
       await this.#withRetries(payload, {
         method: "handleInvalid",
         operation: () => this.#handleInvalid(payload, error)
@@ -754,7 +960,7 @@ var KafkaTransport = class {
       method: "deliver",
       operation: async () => {
         try {
-          await onMessage(envelope, { destination: payload.topic });
+          await route.onMessage(envelope, { destination: payload.topic });
         } catch (error) {
           if (!(error instanceof core.NonRetryableError)) {
             throw error;
@@ -764,30 +970,15 @@ var KafkaTransport = class {
       }
     });
   }
-  #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);
+    const policy = this.#settings.invalidPolicy;
+    const deadLetterTopic = deadLetterTopicFor(policy, topic);
     if (policy === "skip") {
-      this.#logger.error(
+      this.#settings.logger.error(
         `[KafkaTransport](handleInvalid) Skipping malformed message | ${location} reason=${reason} ${errorFields}`
       );
     } else if (typeof policy === "function") {
@@ -800,32 +991,15 @@ 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,
-        acks: -1,
-        messages: [
-          {
-            key: message.key === null ? null : Buffer.from(message.key),
-            value: message.value === null ? null : Buffer.from(message.value),
-            headers
-          }
-        ]
+      const record = deadLetterRecord(payload, {
+        reason,
+        name,
+        code,
+        deadLetterTopic
       });
-      this.#logger.error(
+      const producer = await this.#producer.connected();
+      await this.#producer.send(producer, record);
+      this.#settings.logger.error(
         `[KafkaTransport](handleInvalid) Dead-lettered malformed message | ${location} deadLetterTopic=${deadLetterTopic} reason=${reason} ${errorFields}`
       );
     }
@@ -836,7 +1010,8 @@ var KafkaTransport = class {
    * redelivers the record; heartbeats between attempts keep the session alive.
    */
   async #withRetries(payload, { method, operation }) {
-    const { maxAttempts, initialBackoffMs, maxBackoffMs } = this.#settings;
+    const { maxAttempts, processingBackoff } = this.#settings.timings;
+    const { logger } = this.#settings;
     const location = `topic=${payload.topic} partition=${payload.partition} offset=${payload.message.offset}`;
     const partitionKey = `${payload.topic}:${payload.partition}`;
     for (let attempt = 1; ; attempt += 1) {
@@ -848,51 +1023,28 @@ var KafkaTransport = class {
         const reason = core.toErrorInfo(error).message;
         if (attempt >= maxAttempts || this.#state === "closed") {
           this.#stalledPartitions.add(partitionKey);
-          this.#logger.error(
+          logger.error(
             `[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(
+        logger.warn(
           `[KafkaTransport](withRetries) Attempt failed, retrying | operation=${method} ${location} attempt=${attempt} error=${reason}`
         );
-        await this.#sleepWithHeartbeats(
-          Math.min(initialBackoffMs * 2 ** (attempt - 1), maxBackoffMs),
-          payload
-        );
+        await this.#sleeps.sleepInSlices(processingBackoff.delayFor(attempt), {
+          sliceMs: this.#settings.timings.heartbeatIntervalMs,
+          between: () => payload.heartbeat(),
+          stopped: () => this.#state === "closed"
+        });
       }
     }
   }
-  /** Sleeps in slices and heartbeats after each, so a long backoff never outlives the session timeout. */
-  async #sleepWithHeartbeats(milliseconds, payload) {
-    let remaining = milliseconds;
-    do {
-      const slice = Math.min(remaining, this.#settings.heartbeatIntervalMs);
-      await this.#sleep(slice);
-      await payload.heartbeat();
-      remaining -= slice;
-    } while (remaining > 0 && this.#state !== "closed");
-  }
-  #sleep(milliseconds) {
-    return new Promise((resolve) => {
-      const wake = () => {
-        cancel();
-        this.#sleepers.delete(wake);
-        resolve();
-      };
-      const cancel = internal.schedule(core.systemClock, { run: wake, delayMs: milliseconds });
-      this.#sleepers.add(wake);
-    });
-  }
-  /** Whether the client exposes the instrumentation needed to follow the group membership. */
-  #tracksMembership(consumer) {
-    return consumer.on !== void 0 && consumer.events?.GROUP_JOIN !== void 0;
-  }
   #observeConsumer(consumer) {
-    if (!this.#tracksMembership(consumer)) {
+    if (!tracksMembership(consumer)) {
       this.#groupJoined = true;
       return;
     }
+    const { logger, groupId } = this.#settings;
     const names = consumer.events;
     const listen = (name, listener) => {
       if (name !== void 0) {
@@ -901,29 +1053,28 @@ var KafkaTransport = class {
     };
     listen(names.GROUP_JOIN, () => {
       this.#groupJoined = true;
-      this.#joinWaiter?.resolve();
-      this.#logger.log(`[KafkaTransport](observeConsumer) Joined group | group=${this.#groupId}`);
+      this.#groupJoin.joined();
+      logger.log(`[KafkaTransport](observeConsumer) Joined group | group=${groupId}`);
     });
     listen(names.REBALANCING, () => {
       this.#groupJoined = false;
       this.#stalledPartitions.clear();
-      this.#logger.warn(`[KafkaTransport](observeConsumer) Rebalancing | group=${this.#groupId}`);
+      logger.warn(`[KafkaTransport](observeConsumer) Rebalancing | group=${groupId}`);
     });
     listen(names.CRASH, (event) => this.#handleCrash(event));
-    listen(names.STOP, () => {
-      this.#groupJoined = false;
-    });
-    listen(names.DISCONNECT, () => {
+    const leftGroup = () => {
       this.#groupJoined = false;
-    });
+    };
+    listen(names.STOP, leftGroup);
+    listen(names.DISCONNECT, leftGroup);
   }
   #handleCrash(event) {
     const { error, restart } = event.payload ?? {};
     this.#groupJoined = false;
-    this.#logger.error(
-      `[KafkaTransport](handleCrash) Consumer crashed | group=${this.#groupId} restart=${String(restart)} error=${core.toErrorInfo(error).message}`
+    this.#settings.logger.error(
+      `[KafkaTransport](handleCrash) Consumer crashed | group=${this.#settings.groupId} restart=${String(restart)} error=${core.toErrorInfo(error).message}`
     );
-    this.#joinWaiter?.reject(error);
+    this.#groupJoin.failed(error);
     if (restart === false && this.#consuming && this.#restartLoop === void 0) {
       this.#restartLoop = this.#restartConsumer().finally(() => {
         this.#restartLoop = void 0;
@@ -935,125 +1086,28 @@ var KafkaTransport = class {
    * again, with bounded backoff, until it joined or the transport closed.
    */
   async #restartConsumer() {
-    const { restartInitialBackoffMs, restartMaxBackoffMs } = this.#settings;
+    const { logger, groupId, timings } = this.#settings;
     const consumer = this.#consumer;
     for (let attempt = 1; this.#state === "subscribed"; attempt += 1) {
-      await this.#sleep(
-        Math.min(restartInitialBackoffMs * 2 ** (attempt - 1), restartMaxBackoffMs)
-      );
+      await this.#sleeps.sleep(timings.restartBackoff.delayFor(attempt));
       if (this.#state !== "subscribed") {
         return;
       }
       await consumer.disconnect().catch(() => void 0);
       try {
         await this.#startConsuming();
-        this.#logger.log(
-          `[KafkaTransport](restartConsumer) Consumer restarted | group=${this.#groupId} attempt=${attempt}`
+        logger.log(
+          `[KafkaTransport](restartConsumer) Consumer restarted | group=${groupId} attempt=${attempt}`
         );
         return;
       } catch (error) {
-        this.#logger.error(
-          `[KafkaTransport](restartConsumer) Restart failed, will retry | group=${this.#groupId} attempt=${attempt} error=${core.toErrorInfo(error).message}`
+        logger.error(
+          `[KafkaTransport](restartConsumer) Restart failed, will retry | group=${groupId} attempt=${attempt} error=${core.toErrorInfo(error).message}`
         );
       }
     }
   }
-  #waitForGroupJoin(consumer) {
-    if (!this.#tracksMembership(consumer)) {
-      return { promise: Promise.resolve(), dispose: () => void 0 };
-    }
-    let cancel;
-    const promise = new Promise((resolve, reject) => {
-      this.#joinWaiter = { resolve, reject };
-      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: () => {
-        cancel?.();
-        this.#joinWaiter = void 0;
-      }
-    };
-  }
 };
-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(
-      processing.initialBackoff ?? DEFAULTS.initialBackoff,
-      "processing.initialBackoff"
-    ),
-    maxBackoffMs: core.toMilliseconds(
-      processing.maxBackoff ?? DEFAULTS.maxBackoff,
-      "processing.maxBackoff"
-    ),
-    startupTimeoutMs: core.toMilliseconds(
-      options.startupTimeout ?? DEFAULTS.startupTimeout,
-      "startupTimeout"
-    ),
-    publishTimeoutMs: core.toMilliseconds(
-      options.publishTimeout ?? DEFAULTS.publishTimeout,
-      "publishTimeout"
-    ),
-    heartbeatIntervalMs: Math.max(
-      1,
-      core.toMilliseconds(
-        processing.heartbeatInterval ?? DEFAULTS.heartbeatInterval,
-        "processing.heartbeatInterval"
-      )
-    ),
-    ...resolveRestartSettings(options.restart ?? {})
-  };
-}
-function resolveRestartSettings(restart) {
-  return {
-    restartInitialBackoffMs: core.toMilliseconds(
-      restart.initialBackoff ?? DEFAULTS.restartInitialBackoff,
-      "restart.initialBackoff"
-    ),
-    restartMaxBackoffMs: core.toMilliseconds(
-      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,