@relaybus/rabbitmq 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,33 +1,47 @@
-import { RelayBusError, NonRetryableError, assertEventType, ConfigurationError, toErrorInfo, createRetryPolicy, toMilliseconds, computeRetryDelay, isRetryableError } from '@relaybus/core';
+import { RelayBusError, NonRetryableError, assertEventType, systemClock, ConfigurationError, toErrorInfo, computeRetryDelay, isRetryableError, createRetryPolicy, toMilliseconds } from '@relaybus/core';
+import { createCloudEventReaders, mediaTypeOf, isJsonObject, createJsonEnvelopeFormat, schedule, writeStructuredCloudEvent, assertPositiveInteger } from '@relaybus/core/internal';
+export { fromHeader, fromPayloadField } from '@relaybus/core/internal';
 
 // src/errors.ts
 var RabbitMqUnavailableError = class extends RelayBusError {
+  name = "RabbitMqUnavailableError";
+  code = "RELAYBUS_RABBITMQ_UNAVAILABLE";
 };
 var RabbitMqPublishRejectedError = class extends RelayBusError {
+  name = "RabbitMqPublishRejectedError";
+  code = "RELAYBUS_RABBITMQ_PUBLISH_REJECTED";
 };
 var UnroutableMessageError = class extends RelayBusError {
+  name = "UnroutableMessageError";
+  code = "RELAYBUS_RABBITMQ_UNROUTABLE_MESSAGE";
 };
 var MalformedMessageError = class extends RelayBusError {
+  name = "MalformedMessageError";
+  code = "RELAYBUS_RABBITMQ_MALFORMED_MESSAGE";
 };
 var UnserializablePayloadError = class extends NonRetryableError {
   name = "UnserializablePayloadError";
+  code = "RELAYBUS_RABBITMQ_UNSERIALIZABLE_PAYLOAD";
 };
 var AmqpLimitExceededError = class extends NonRetryableError {
   name = "AmqpLimitExceededError";
+  code = "RELAYBUS_RABBITMQ_AMQP_LIMIT_EXCEEDED";
+};
+var RabbitMqUnencodableEventError = class extends NonRetryableError {
+  name = "RabbitMqUnencodableEventError";
+  code = "RELAYBUS_RABBITMQ_UNENCODABLE_EVENT";
 };
-
-// src/abortable-sleep.ts
 function abortableSleep(milliseconds, signal) {
   if (signal.aborted) {
     return Promise.resolve();
   }
   return new Promise((resolve) => {
     const finish = () => {
-      clearTimeout(timer);
+      cancel();
       signal.removeEventListener("abort", finish);
       resolve();
     };
-    const timer = setTimeout(finish, milliseconds);
+    const cancel = schedule(systemClock, { run: finish, delayMs: milliseconds });
     signal.addEventListener("abort", finish, { once: true });
   });
 }
@@ -36,7 +50,17 @@ function abortableSleep(milliseconds, signal) {
 var ConnectionSupervisor = class {
   #settings;
   #stop = new AbortController();
+  /** Aborted by `forceClose`: destroys a socket that is still connecting. */
+  #force = new AbortController();
+  /** Resolves on `forceClose`: closing stops waiting for the broker. */
+  #forcing = new Promise((resolve) => {
+    this.#force.signal.addEventListener("abort", () => resolve(), { once: true });
+  });
   #current;
+  /** Connections being closed, until their closing handshake finishes. */
+  #closing = /* @__PURE__ */ new Set();
+  /** Set by `forceClose`: connections are cut instead of closed. */
+  #forced = false;
   #ready = false;
   #started = false;
   #closed = false;
@@ -83,7 +107,7 @@ var ConnectionSupervisor = class {
       return;
     }
     this.#handleLoss(connection, reason);
-    connection.close().catch(() => void 0);
+    void this.#closeConnection(connection);
   }
   /**
    * Stops reconnecting, runs `beforeDisconnect` while the connection is still
@@ -92,23 +116,54 @@ var ConnectionSupervisor = class {
   async close(beforeDisconnect) {
     this.#closed = true;
     this.#stop.abort();
-    await this.#reconnecting;
+    await Promise.race([this.#reconnecting, this.#forcing]);
     try {
-      await beforeDisconnect();
+      await Promise.race([beforeDisconnect(), this.#forcing]);
     } finally {
       const connection = this.#current;
       this.#current = void 0;
       this.#ready = false;
-      await connection?.close().catch(() => void 0);
+      if (connection !== void 0) {
+        await this.#closeConnection(connection);
+      }
+    }
+  }
+  /**
+   * Stops reconnecting and cuts every connection, open or closing, without the closing handshake. A
+   * connection that finishes opening afterwards is cut at once.
+   */
+  forceClose() {
+    this.#closed = true;
+    this.#forced = true;
+    this.#stop.abort();
+    this.#force.abort();
+    for (const connection of [this.#current, ...this.#closing]) {
+      if (connection !== void 0) {
+        destroySocket(connection);
+      }
     }
   }
+  /** Closes a connection, which `forceClose` can cut until the broker answered; cuts it once forced. */
+  async #closeConnection(connection) {
+    if (this.#forced) {
+      destroySocket(connection);
+      return;
+    }
+    this.#closing.add(connection);
+    await connection.close().catch(() => void 0);
+    this.#closing.delete(connection);
+  }
   async #establish() {
-    const connection = await this.#settings.connect();
+    const connection = await this.#settings.connect({ signal: this.#force.signal });
     connection.on("error", (error) => {
       this.#settings.logger.warn(
         `[ConnectionSupervisor](establish) Connection error | error=${error.message}`
       );
     });
+    if (this.#closed) {
+      await this.#closeConnection(connection);
+      throw new RabbitMqUnavailableError("[ConnectionSupervisor](establish) Transport is closed");
+    }
     connection.on("close", (error) => {
       this.#handleLoss(connection, error?.message ?? "closed by peer");
     });
@@ -131,7 +186,7 @@ var ConnectionSupervisor = class {
       this.#current = void 0;
     }
     this.#settings.onDisconnected();
-    await connection.close().catch(() => void 0);
+    await this.#closeConnection(connection);
   }
   #handleLoss(connection, reason) {
     if (connection !== this.#current) {
@@ -158,7 +213,7 @@ var ConnectionSupervisor = class {
     for (let attempt = 1; !this.#closed; attempt += 1) {
       const delayMs = computeRetryDelay(policy, attempt, this.#settings.random);
       this.#settings.logger.log(
-        `[ConnectionSupervisor](reconnect) Reconnecting | attempt=${attempt} delayMs=${delayMs}`
+        `[ConnectionSupervisor](reconnectUntilConnected) Reconnecting | attempt=${attempt} delayMs=${delayMs}`
       );
       await abortableSleep(delayMs, this.#stop.signal);
       if (this.#closed) {
@@ -167,78 +222,105 @@ var ConnectionSupervisor = class {
       try {
         await this.#establish();
         this.#settings.logger.log(
-          `[ConnectionSupervisor](reconnect) Reconnected | attempt=${attempt}`
+          `[ConnectionSupervisor](reconnectUntilConnected) Reconnected | attempt=${attempt}`
         );
         return;
       } catch (error) {
         this.#settings.logger.warn(
-          `[ConnectionSupervisor](reconnect) Attempt failed | attempt=${attempt} error=${toErrorInfo(error).message}`
+          `[ConnectionSupervisor](reconnectUntilConnected) Attempt failed | attempt=${attempt} error=${toErrorInfo(error).message}`
         );
       }
     }
   }
 };
+function destroySocket(connection) {
+  const model = connection;
+  model.connection?.stream?.destroy(
+    new RabbitMqUnavailableError("Connection cut: the shutdown deadline passed")
+  );
+}
 
 // src/json-payload.ts
 function assertJsonPayload(payload, eventId) {
-  visit(payload, "$", /* @__PURE__ */ new Set(), eventId);
+  visit(payload, { path: "$", ancestors: /* @__PURE__ */ new Set(), eventId });
 }
-function visit(value, path, ancestors, eventId) {
+function visit(value, {
+  path,
+  ancestors,
+  eventId
+}) {
   switch (typeof value) {
     case "string":
     case "boolean":
       return;
     case "number":
       if (!Number.isFinite(value)) {
-        throw refuse(eventId, path, `is ${value}, which JSON turns into null`);
+        throw refuse(eventId, { path, reason: `is ${value}, which JSON turns into null` });
       }
       return;
     case "object":
       if (value !== null) {
-        visitObject(value, path, ancestors, eventId);
+        visitObject(value, { path, ancestors, eventId });
       }
       return;
     default:
-      throw refuse(eventId, path, `is ${typeof value}, which JSON cannot represent`);
+      throw refuse(eventId, { path, reason: `is ${typeof value}, which JSON cannot represent` });
   }
 }
-function visitObject(value, path, ancestors, eventId) {
+function visitObject(value, {
+  path,
+  ancestors,
+  eventId
+}) {
   if (ancestors.has(value)) {
-    throw refuse(eventId, path, "is a circular reference");
+    throw refuse(eventId, { path, reason: "is a circular reference" });
   }
   ancestors.add(value);
   if (Array.isArray(value)) {
     for (let index = 0; index < value.length; index += 1) {
       if (!(index in value)) {
-        throw refuse(eventId, `${path}[${index}]`, "is an array hole, which JSON turns into null");
+        throw refuse(eventId, {
+          path: `${path}[${index}]`,
+          reason: "is an array hole, which JSON turns into null"
+        });
       }
-      visit(value[index], `${path}[${index}]`, ancestors, eventId);
+      visit(value[index], { path: `${path}[${index}]`, ancestors, eventId });
     }
   } else {
     const prototype = Object.getPrototypeOf(value);
     if (prototype !== Object.prototype && prototype !== null) {
-      throw refuse(eventId, path, "is not a plain object (class instance, Date, Map or Set)");
+      throw refuse(eventId, {
+        path,
+        reason: "is not a plain object (class instance, Date, Map or Set)"
+      });
     }
     if (Object.getOwnPropertySymbols(value).length > 0) {
-      throw refuse(eventId, path, "has a symbol key, which JSON drops");
+      throw refuse(eventId, { path, reason: "has a symbol key, which JSON drops" });
     }
     for (const key of Object.keys(value)) {
-      visit(value[key], `${path}.${key}`, ancestors, eventId);
+      visit(value[key], {
+        path: `${path}.${key}`,
+        ancestors,
+        eventId
+      });
     }
   }
   ancestors.delete(value);
 }
-function refuse(eventId, path, reason) {
+function refuse(eventId, { path, reason }) {
   return new UnserializablePayloadError(
     `Event ${eventId} has a payload JSON cannot represent faithfully: ${path} ${reason}`
   );
 }
 
 // src/wire-format.ts
+var MILLISECONDS_PER_SECOND = 1e3;
 var ATTRIBUTE_PREFIX = "cloudEvents:";
 var EVENT_HEADER_PREFIX = "relaybus:";
 var SPEC_VERSION = "1.0";
 var JSON_CONTENT_TYPE = "application/json";
+var STRUCTURED_CONTENT_TYPE = "application/cloudevents+json";
+var RESERVED_HEADER_PREFIXES = ["x-death", "x-first-death-", "x-last-death-", "x-relaybus-"];
 var SHORT_STRING_LIMIT_BYTES = 255;
 var RFC3339_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/i;
 function encodeEnvelope(envelope) {
@@ -274,7 +356,7 @@ function encodeEnvelope(envelope) {
       contentType: JSON_CONTENT_TYPE,
       persistent: true,
       messageId: envelope.id,
-      timestamp: Math.floor(envelope.occurredAt.getTime() / 1e3),
+      timestamp: Math.floor(envelope.occurredAt.getTime() / MILLISECONDS_PER_SECOND),
       ...mirror("type", envelope.type),
       ...mirror("appId", envelope.source),
       ...envelope.correlationId === null ? {} : mirror("correlationId", envelope.correlationId),
@@ -282,6 +364,43 @@ function encodeEnvelope(envelope) {
     }
   };
 }
+function encodeStructuredEnvelope(envelope) {
+  assertJsonPayload(envelope.payload, envelope.id);
+  assertShortString("Event id", envelope.id);
+  const document = writeStructuredCloudEvent(envelope, {
+    time: envelope.occurredAt.toISOString(),
+    data: JSON.stringify(envelope.payload)
+  });
+  return {
+    content: Buffer.from(document, "utf8"),
+    options: {
+      ...messageProperties(envelope),
+      contentType: STRUCTURED_CONTENT_TYPE,
+      headers: plainHeaders(envelope, envelope.headers)
+    }
+  };
+}
+function messageProperties(envelope) {
+  return {
+    persistent: true,
+    messageId: envelope.id,
+    timestamp: Math.floor(envelope.occurredAt.getTime() / MILLISECONDS_PER_SECOND),
+    ...mirror("type", envelope.type),
+    ...mirror("appId", envelope.source),
+    ...envelope.correlationId === null ? {} : mirror("correlationId", envelope.correlationId)
+  };
+}
+function plainHeaders(envelope, headers) {
+  for (const name of Object.keys(headers)) {
+    if (RESERVED_HEADER_PREFIXES.some((prefix) => name.startsWith(prefix))) {
+      throw new RabbitMqUnencodableEventError(
+        `Event ${envelope.id} has a header '${name}', a name the broker or the transport reserves`
+      );
+    }
+    assertShortString(`Header name '${name}'`, name);
+  }
+  return Object.fromEntries(Object.entries(headers));
+}
 function assertShortString(label, value) {
   const bytes = Buffer.byteLength(value, "utf8");
   if (bytes > SHORT_STRING_LIMIT_BYTES) {
@@ -339,7 +458,7 @@ function parsePayload(content) {
 }
 function parseTime(rawTime, timestampSeconds) {
   if (rawTime === void 0) {
-    const fallback = typeof timestampSeconds === "number" ? new Date(timestampSeconds * 1e3) : void 0;
+    const fallback = typeof timestampSeconds === "number" ? new Date(timestampSeconds * MILLISECONDS_PER_SECOND) : void 0;
     if (fallback === void 0 || Number.isNaN(fallback.getTime())) {
       throw new MalformedMessageError("Message has no valid time (header cloudEvents:time)");
     }
@@ -366,6 +485,8 @@ function required(attribute, value) {
 }
 
 // src/inbound-decoders.ts
+var MILLISECONDS_PER_SECOND2 = 1e3;
+var { optionalAttribute, requiredAttribute, assertValidType, assertJsonDataContentType } = createCloudEventReaders((reason) => new MalformedMessageError(reason));
 var STRUCTURED_MEDIA_TYPE = "application/cloudevents+json";
 var strictUtf8 = new TextDecoder("utf-8", { fatal: true });
 var SPEC_VERSION2 = "1.0";
@@ -432,12 +553,12 @@ function plainJsonDecoder(options) {
       headers: readForeignHeaders(properties),
       payload: parseJsonBody(message.content)
     };
-    const type = resolveText(options.type, plain, "type");
+    const type = resolveText(options.type, { message: plain, name: "type" });
     if (type === void 0) {
       throw new MalformedMessageError("Message has no event type: the type option found none");
     }
     assertValidType(type, "The event type");
-    const id = resolveText(options.id, plain, "id") ?? nonEmptyText(properties.messageId);
+    const id = resolveText(options.id, { message: plain, name: "id" }) ?? nonEmptyText(properties.messageId);
     if (id === void 0) {
       throw new MalformedMessageError(
         "Message has no id: set the messageId property on the producer or configure the id option"
@@ -446,8 +567,8 @@ function plainJsonDecoder(options) {
     return {
       id,
       type,
-      source: resolveText(options.source, plain, "source") ?? defaultSource(message),
-      key: resolveText(options.key, plain, "key") ?? null,
+      source: resolveText(options.source, { message: plain, name: "source" }) ?? defaultSource(message),
+      key: resolveText(options.key, { message: plain, name: "key" }) ?? null,
       payload: plain.payload,
       headers: plain.headers,
       correlationId: null,
@@ -490,47 +611,12 @@ function parseJsonBody(content) {
     throw new MalformedMessageError("Message body is not valid JSON");
   }
 }
-function mediaTypeOf(contentType) {
-  return typeof contentType === "string" ? contentType.split(";")[0].trim().toLowerCase() : void 0;
-}
-function isJsonObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function nonEmptyText(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
 }
 function defaultSource(message) {
   return nonEmptyText(message.properties.appId) ?? message.fields.routingKey;
 }
-function optionalAttribute(body, name) {
-  const value = body[name];
-  if (value !== void 0 && typeof value !== "string") {
-    throw new MalformedMessageError(`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 new MalformedMessageError(`Attribute '${name}' is missing or empty`);
-  }
-  return value;
-}
-function assertValidType(type, label) {
-  try {
-    assertEventType(type);
-  } catch (error) {
-    throw new MalformedMessageError(
-      `${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 new MalformedMessageError(`datacontenttype must be JSON, received '${dataContentType}'`);
-  }
-}
 function parseTime2(text2) {
   const time = new Date(text2);
   if (!RFC3339_PATTERN.test(text2) || Number.isNaN(time.getTime())) {
@@ -540,7 +626,7 @@ function parseTime2(text2) {
 }
 function propertyTimeOrNow(properties) {
   const { timestamp } = properties;
-  return typeof timestamp === "number" && Number.isFinite(timestamp) ? new Date(timestamp * 1e3) : /* @__PURE__ */ new Date();
+  return typeof timestamp === "number" && Number.isFinite(timestamp) ? new Date(timestamp * MILLISECONDS_PER_SECOND2) : /* @__PURE__ */ new Date();
 }
 function extensionAttributes(body) {
   return Object.fromEntries(
@@ -556,7 +642,7 @@ function readForeignHeaders(properties) {
     )
   );
 }
-function resolveText(option, message, name) {
+function resolveText(option, { message, name }) {
   const value = typeof option === "function" ? option(message) : option;
   if (value === void 0 || value === null) {
     return void 0;
@@ -585,9 +671,62 @@ function observeRejection(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 MESSAGE_ID_PROPERTY = "message-id-property";
+var DEFAULT_CONTENT_TYPE = "application/json";
+function jsonEnvelope(mapping) {
+  const format = createJsonEnvelopeFormat(mapping, {
+    transportIds: [MESSAGE_ID_PROPERTY],
+    failures: {
+      invalid: (reason) => new MalformedMessageError(reason),
+      unencodable: (reason) => new RabbitMqUnencodableEventError(reason)
+    }
+  });
+  const contentType = mapping.contentType ?? DEFAULT_CONTENT_TYPE;
+  return {
+    encode: (envelope) => {
+      assertJsonPayload(envelope.payload, envelope.id);
+      assertShortString("Event id", envelope.id);
+      const { body, headers } = format.write(envelope);
+      return {
+        content: Buffer.from(JSON.stringify(body), "utf8"),
+        options: {
+          ...messageProperties(envelope),
+          contentType,
+          headers: plainHeaders(envelope, headers)
+        }
+      };
+    },
+    decode: (message) => {
+      const fields = format.read({
+        body: parseJsonBody(message.content),
+        headers: readForeignHeaders(message.properties)
+      });
+      return { ...fields, id: fields.id ?? requireMessageId(message) };
+    }
+  };
+}
+function requireMessageId(message) {
+  const id = nonEmptyText(message.properties.messageId);
+  if (id === void 0) {
+    throw new MalformedMessageError("Message has no id: the messageId property is missing");
+  }
+  return id;
+}
 var REDELIVERIES_HEADER = "x-relaybus-redeliveries";
 var FIRST_FAILURE_HEADER = "x-relaybus-first-failure-at";
 var DEAD_LETTER_REASON_HEADER = "x-relaybus-dead-letter-reason";
+var DEAD_LETTER_ERROR_NAME_HEADER = "x-relaybus-dead-letter-error-name";
+var DEAD_LETTER_ERROR_CODE_HEADER = "x-relaybus-dead-letter-error-code";
 var ORIGINAL_ROUTING_KEY_HEADER = "x-relaybus-routing-key";
 var RELAYBUS_STATE_HEADERS = [REDELIVERIES_HEADER, FIRST_FAILURE_HEADER];
 var BROKER_COUNTER_HEADERS = ["x-delivery-count", "x-acquired-count"];
@@ -612,7 +751,7 @@ function buildRetryLadder(policy) {
     delay *= policy.factor;
   }
 }
-function chooseRetryTier(ladder, delayMs, random) {
+function chooseRetryTier(ladder, { delayMs, random }) {
   const upperIndex = ladder.findIndex((tier) => tier >= delayMs);
   if (upperIndex === -1) {
     return ladder.at(-1);
@@ -635,6 +774,8 @@ function copyForRepublish(message, headerChanges) {
   for (const name of [
     ...RELAYBUS_STATE_HEADERS,
     DEAD_LETTER_REASON_HEADER,
+    DEAD_LETTER_ERROR_NAME_HEADER,
+    DEAD_LETTER_ERROR_CODE_HEADER,
     ...BROKER_COUNTER_HEADERS
   ]) {
     delete headers[name];
@@ -664,6 +805,8 @@ function withOriginalRoutingKey(message) {
 }
 
 // src/options.ts
+var DEFAULT_PREFETCH = 50;
+var DEFAULT_DELIVERY_LIMIT = 10;
 var DEFAULT_HANDLER_RETRY = {
   attempts: 3,
   initialDelayMs: 200,
@@ -690,6 +833,14 @@ var DEFAULT_RECONNECT = {
   retryIf: void 0
 };
 function resolveSettings(options) {
+  const basics = resolveBasics(options);
+  return {
+    ...resolveTopology(options, basics),
+    ...resolveRetries(options, basics),
+    ...resolveRuntime(options, basics)
+  };
+}
+function resolveBasics(options) {
   const exchange = nonEmpty(options.exchange ?? "relaybus", "exchange");
   const failOnConnectError = options.failOnConnectError ?? true;
   if (!failOnConnectError && options.reconnect === false) {
@@ -698,11 +849,17 @@ function resolveSettings(options) {
     );
   }
   const ordered = options.ordered ?? false;
-  const prefetch = positiveInteger(options.prefetch ?? (ordered ? 1 : 50), "prefetch");
+  const prefetch = assertPositiveInteger(
+    options.prefetch ?? (ordered ? 1 : DEFAULT_PREFETCH),
+    "prefetch"
+  );
   if (ordered && prefetch !== 1) {
     throw new ConfigurationError(`ordered consumption needs prefetch 1, received ${prefetch}`);
   }
   const redelivery = createRetryPolicy(options.redelivery, DEFAULT_REDELIVERY);
+  return { exchange, failOnConnectError, ordered, prefetch, redelivery };
+}
+function resolveTopology(options, { exchange, prefetch }) {
   return {
     name: nonEmpty(options.name ?? "rabbitmq", "name"),
     connect: resolveConnect(options),
@@ -716,7 +873,14 @@ function resolveSettings(options) {
       "deadLetterExchange"
     ),
     deadLetterQueue: optionalNonEmpty(options.deadLetterQueue, "deadLetterQueue"),
-    deliveryLimit: positiveInteger(options.deliveryLimit ?? 10, "deliveryLimit"),
+    deliveryLimit: assertPositiveInteger(
+      options.deliveryLimit ?? DEFAULT_DELIVERY_LIMIT,
+      "deliveryLimit"
+    )
+  };
+}
+function resolveRetries(options, { ordered, redelivery }) {
+  return {
     handlerRetry: createRetryPolicy(options.handlerRetry, DEFAULT_HANDLER_RETRY),
     redelivery,
     retryLadder: ordered ? [] : buildRetryLadder(redelivery),
@@ -724,13 +888,17 @@ function resolveSettings(options) {
       options.redelivery?.maxAge ?? DEFAULT_REDELIVERY_MAX_AGE,
       "redelivery.maxAge"
     ),
-    ordered,
+    ordered
+  };
+}
+function resolveRuntime(options, { failOnConnectError }) {
+  return {
     reconnect: resolveReconnect(options.reconnect),
     failOnConnectError,
     allowUnroutable: options.allowUnroutable ?? false,
     publishTimeoutMs: positiveDuration(options.publishTimeout ?? "30s", "publishTimeout"),
     shutdownTimeoutMs: toMilliseconds(options.shutdownTimeout ?? "30s", "shutdownTimeout"),
-    decode: resolveDecode(options.decode),
+    ...resolveCodec(options),
     logger: options.logger ?? console,
     random: options.random ?? Math.random
   };
@@ -746,11 +914,21 @@ function resolveQueueName(settings) {
   }
   return `${settings.queuePrefix}.${settings.consumerGroup}`;
 }
-function resolveDecode(decode) {
-  if (decode === void 0) {
-    return decodeEnvelope;
+function resolveCodec({
+  codec,
+  decode
+}) {
+  if (decode !== void 0 && codec !== void 0) {
+    throw new ConfigurationError("Give 'codec' or the deprecated 'decode', not both");
+  }
+  const chosen = decode === void 0 ? codec ?? cloudEventsBinary : { encode: encodeEnvelope, decode };
+  if (chosen === cloudEventsBinary) {
+    return { encode: encodeEnvelope, decode: decodeEnvelope };
   }
-  return (message) => completeDecodedEvent(decode(message), message);
+  return {
+    encode: chosen.encode,
+    decode: (message) => completeDecodedEvent(chosen.decode(message), message)
+  };
 }
 function resolveConnect(options) {
   const { url, connect } = options;
@@ -760,9 +938,10 @@ function resolveConnect(options) {
   if (connect !== void 0) {
     return connect;
   }
-  return async () => {
+  return async ({ signal }) => {
     const amqplib = await import('amqplib');
-    return amqplib.connect(url);
+    const socketOptions = { signal };
+    return amqplib.connect(url, socketOptions);
   };
 }
 function resolveReconnect(reconnect) {
@@ -780,12 +959,6 @@ function nonEmpty(value, name) {
 function optionalNonEmpty(value, name) {
   return value === void 0 ? void 0 : nonEmpty(value, name);
 }
-function positiveInteger(value, name) {
-  if (!Number.isInteger(value) || value < 1) {
-    throw new ConfigurationError(`${name} must be a positive integer, received ${value}`);
-  }
-  return value;
-}
 function positiveDuration(value, name) {
   const milliseconds = toMilliseconds(value, name);
   if (milliseconds === 0) {
@@ -934,74 +1107,115 @@ var QueueConsumer = class {
     this.#inFlight.add(task);
   }
   async #process(channel, message) {
-    const { queue, handlerRetry } = this.#settings;
-    let envelope;
-    try {
-      envelope = this.#settings.decode(withOriginalRoutingKey(message));
-    } catch (error) {
-      this.#settings.logger.error(
-        `[QueueConsumer](process) Dead-lettering malformed message | queue=${queue} routingKey=${message.fields.routingKey} error=${toErrorInfo(error).message}`
-      );
-      await this.#deadLetter(channel, message, "malformed message");
+    const decoded = await this.#decodeOrDeadLetter(channel, message);
+    if (decoded === void 0) {
       return;
     }
-    let redeliveries = readCounterHeader(message, REDELIVERIES_HEADER) ?? 0;
-    let firstFailureAt = readCounterHeader(message, FIRST_FAILURE_HEADER);
+    const { envelope } = decoded;
+    const delivery = {
+      channel,
+      message,
+      envelope,
+      redeliveries: readCounterHeader(message, REDELIVERIES_HEADER) ?? 0,
+      firstFailureAt: readCounterHeader(message, FIRST_FAILURE_HEADER)
+    };
     for (let attempt = 1; ; attempt += 1) {
       try {
-        await this.#settings.onMessage(envelope);
-        this.#settle(channel, message, "ack");
+        await this.#settings.onMessage(envelope, { destination: message.fields.routingKey });
+        this.#settle(channel, { message, settlement: "ack" });
         return;
       } catch (error) {
-        const failure = `queue=${queue} eventId=${envelope.id} attempt=${attempt} error=${toErrorInfo(error).message}`;
-        if (!isRetryableError(handlerRetry, error)) {
-          this.#settings.logger.error(
-            `[QueueConsumer](process) Dead-lettering message the handler cannot process | ${failure}`
-          );
-          await this.#deadLetter(channel, message, "non-retryable handler error");
-          return;
-        }
-        if (attempt < handlerRetry.attempts) {
-          const delayMs2 = computeRetryDelay(handlerRetry, attempt, this.#settings.random);
-          this.#settings.logger.warn(
-            `[QueueConsumer](process) Handler failed, retrying | ${failure} delayMs=${delayMs2}`
-          );
-          if (await this.#interrupted(delayMs2)) {
-            this.#settle(channel, message, "requeue");
-            return;
-          }
-          continue;
-        }
-        redeliveries += 1;
-        const now = Date.now();
-        firstFailureAt ??= now;
-        const delayMs = this.#redeliveryDelay(redeliveries);
-        if (now + delayMs - firstFailureAt > this.#settings.redeliveryMaxAgeMs) {
-          this.#settings.logger.error(
-            `[QueueConsumer](process) Dead-lettering message that kept failing | ${failure} redeliveries=${redeliveries - 1} failingForMs=${now - firstFailureAt} maxAgeMs=${this.#settings.redeliveryMaxAgeMs}`
-          );
-          await this.#deadLetter(channel, message, "redelivery window exhausted");
-          return;
-        }
-        this.#settings.logger.warn(
-          `[QueueConsumer](process) Handler attempts spent, retrying later | ${failure} redeliveries=${redeliveries} delayMs=${delayMs}`
-        );
-        if (!this.#settings.ordered) {
-          await this.#redeliverLater(channel, message, delayMs, redeliveries, firstFailureAt);
-          return;
-        }
-        if (await this.#interrupted(delayMs)) {
-          this.#settle(channel, message, "requeue");
+        if (await this.#afterFailure(delivery, { attempt, error }) === "settled") {
           return;
         }
       }
     }
   }
+  /** The event of `message`, or undefined after dead-lettering a message that is not one. */
+  async #decodeOrDeadLetter(channel, message) {
+    try {
+      return { envelope: this.#settings.decode(withOriginalRoutingKey(message)) };
+    } catch (error) {
+      this.#settings.logger.error(
+        `[QueueConsumer](decodeOrDeadLetter) Dead-lettering malformed message | queue=${this.#settings.queue} routingKey=${message.fields.routingKey} ${describeError(error)}`
+      );
+      this.#settings.onInvalidMessage?.({ destination: message.fields.routingKey, error });
+      await this.#deadLetter(channel, { message, reason: "malformed message", error });
+      return void 0;
+    }
+  }
+  /**
+   * Decides what follows a failed attempt: dead-letter a non-retryable error, retry on the same
+   * delivery while local attempts remain, else redeliver later. `retry` runs the handler again.
+   */
+  async #afterFailure(delivery, { attempt, error }) {
+    const { channel, message, envelope } = delivery;
+    const { queue, handlerRetry } = this.#settings;
+    const failure = `queue=${queue} eventId=${envelope.id} attempt=${attempt} ${describeError(error)}`;
+    if (!isRetryableError(handlerRetry, error)) {
+      this.#settings.logger.error(
+        `[QueueConsumer](afterFailure) Dead-lettering message the handler cannot process | ${failure}`
+      );
+      await this.#deadLetter(channel, {
+        message,
+        reason: "non-retryable handler error",
+        error
+      });
+      return "settled";
+    }
+    if (attempt < handlerRetry.attempts) {
+      const delayMs = computeRetryDelay(handlerRetry, attempt, this.#settings.random);
+      this.#settings.logger.warn(
+        `[QueueConsumer](afterFailure) Handler failed, retrying | ${failure} delayMs=${delayMs}`
+      );
+      return this.#waitOrRequeue(delivery, delayMs);
+    }
+    return this.#afterSpentAttempts(delivery, { failure, error });
+  }
+  /**
+   * The local attempts are spent: dead-letter a message that kept failing past `redeliveryMaxAgeMs`,
+   * else park it in a retry queue, or, when ordered, wait and retry it in place.
+   */
+  async #afterSpentAttempts(delivery, { failure, error }) {
+    const { channel, message } = delivery;
+    delivery.redeliveries += 1;
+    const now = Date.now();
+    delivery.firstFailureAt ??= now;
+    const { redeliveries, firstFailureAt } = delivery;
+    const delayMs = this.#redeliveryDelay(redeliveries);
+    if (now + delayMs - firstFailureAt > this.#settings.redeliveryMaxAgeMs) {
+      this.#settings.logger.error(
+        `[QueueConsumer](afterSpentAttempts) Dead-lettering message that kept failing | ${failure} redeliveries=${redeliveries - 1} failingForMs=${now - firstFailureAt} maxAgeMs=${this.#settings.redeliveryMaxAgeMs}`
+      );
+      await this.#deadLetter(channel, {
+        message,
+        reason: "redelivery window exhausted",
+        error
+      });
+      return "settled";
+    }
+    this.#settings.logger.warn(
+      `[QueueConsumer](afterSpentAttempts) Handler attempts spent, retrying later | ${failure} redeliveries=${redeliveries} delayMs=${delayMs}`
+    );
+    if (!this.#settings.ordered) {
+      await this.#redeliverLater(channel, { message, delayMs, redeliveries, firstFailureAt });
+      return "settled";
+    }
+    return this.#waitOrRequeue(delivery, delayMs);
+  }
+  /** Waits `delayMs` before the next attempt; requeues instead when the consumer stops meanwhile. */
+  async #waitOrRequeue(delivery, delayMs) {
+    if (await this.#interrupted(delayMs)) {
+      this.#settle(delivery.channel, { message: delivery.message, settlement: "requeue" });
+      return "settled";
+    }
+    return "retry";
+  }
   /** The backoff before the next delayed redelivery: a retry queue's TTL, or an exact wait when ordered. */
   #redeliveryDelay(redeliveries) {
     const { redelivery, retryLadder, ordered, random } = this.#settings;
     const delayMs = computeRetryDelay(redelivery, redeliveries, random);
-    return ordered ? delayMs : chooseRetryTier(retryLadder, delayMs, random);
+    return ordered ? delayMs : chooseRetryTier(retryLadder, { delayMs, random });
   }
   /** Sleeps; true when the consumer is stopping, so the caller must give the message back. */
   async #interrupted(delayMs) {
@@ -1014,7 +1228,8 @@ var QueueConsumer = class {
    * the original is requeued after the same delay, so it is neither lost nor
    * hot-looped.
    */
-  async #redeliverLater(channel, message, delayMs, redeliveries, firstFailureAt) {
+  async #redeliverLater(channel, input) {
+    const { message, delayMs, redeliveries, firstFailureAt } = input;
     const { content, options } = copyForRepublish(message, {
       [REDELIVERIES_HEADER]: String(redeliveries),
       [FIRST_FAILURE_HEADER]: String(firstFailureAt),
@@ -1022,20 +1237,18 @@ var QueueConsumer = class {
     });
     try {
       await this.#settings.republish(
-        "",
-        retryQueueName(this.#settings.queue, delayMs),
-        content,
-        options
+        { exchange: "", routingKey: retryQueueName(this.#settings.queue, delayMs) },
+        { content, options }
       );
     } catch (error) {
       this.#settings.logger.warn(
         `[QueueConsumer](redeliverLater) Could not park the message in the retry queue, requeueing it | queue=${this.#settings.queue} delayMs=${delayMs} error=${toErrorInfo(error).message}`
       );
       await this.#interrupted(delayMs);
-      this.#settle(channel, message, "requeue");
+      this.#settle(channel, { message, settlement: "requeue" });
       return;
     }
-    this.#settle(channel, message, "ack");
+    this.#settle(channel, { message, settlement: "ack" });
   }
   /**
    * Moves the message to the dead-letter queue through a confirmed copy that
@@ -1043,27 +1256,29 @@ var QueueConsumer = class {
    * message is rejected without requeue, which makes the broker dead-letter it
    * (at-least-once), so it still ends up in the dead-letter queue.
    */
-  async #deadLetter(channel, message, reason) {
+  async #deadLetter(channel, input) {
+    const { message, reason, error } = input;
+    const { name, code } = toErrorInfo(error);
     const { content, options } = copyForRepublish(message, {
-      [DEAD_LETTER_REASON_HEADER]: reason
+      [DEAD_LETTER_REASON_HEADER]: reason,
+      [DEAD_LETTER_ERROR_NAME_HEADER]: name,
+      ...code === void 0 ? {} : { [DEAD_LETTER_ERROR_CODE_HEADER]: code }
     });
     try {
       await this.#settings.republish(
-        this.#settings.deadLetterExchange,
-        this.#settings.queue,
-        content,
-        options
+        { exchange: this.#settings.deadLetterExchange, routingKey: this.#settings.queue },
+        { content, options }
       );
-    } catch (error) {
+    } catch (error2) {
       this.#settings.logger.warn(
-        `[QueueConsumer](deadLetter) Could not publish to the dead-letter exchange, leaving it to the broker | queue=${this.#settings.queue} error=${toErrorInfo(error).message}`
+        `[QueueConsumer](deadLetter) Could not publish to the dead-letter exchange, leaving it to the broker | queue=${this.#settings.queue} error=${toErrorInfo(error2).message}`
       );
-      this.#settle(channel, message, "dead-letter");
+      this.#settle(channel, { message, settlement: "dead-letter" });
       return;
     }
-    this.#settle(channel, message, "ack");
+    this.#settle(channel, { message, settlement: "ack" });
   }
-  #settle(channel, message, settlement) {
+  #settle(channel, { message, settlement }) {
     try {
       if (settlement === "ack") {
         channel.ack(message);
@@ -1077,6 +1292,10 @@ var QueueConsumer = class {
     }
   }
 };
+function describeError(error) {
+  const { message, name, code } = toErrorInfo(error);
+  return `error=${message} errorName=${name}${code === void 0 ? "" : ` code=${code}`}`;
+}
 
 // src/serial-queue.ts
 var SerialQueue = class {
@@ -1092,13 +1311,14 @@ var SerialQueue = class {
 var NACK_MESSAGE = "message nacked";
 var RabbitMqTransport = class {
   name;
+  system = "rabbitmq";
   #settings;
   #supervisor;
   /** Serializes topology work so a subscription never races a reconnect. */
   #topologyWork = new SerialQueue();
   #live;
   #subscription;
-  #closed = false;
+  #closing;
   constructor(options) {
     this.#settings = resolveSettings(options);
     this.name = this.#settings.name;
@@ -1138,19 +1358,21 @@ var RabbitMqTransport = class {
    * @throws {RabbitMqUnavailableError} not connected, channel lost, or confirm timed out
    * @throws {RabbitMqPublishRejectedError} the broker nacked the message
    * @throws {UnroutableMessageError} no queue is bound to `destination` (unless `allowUnroutable`)
+   * @throws whatever the `codec`'s `encode` throws, such as {@link RabbitMqUnencodableEventError}
    */
   async publish(envelope, destination) {
     assertShortString("Destination (routing key)", destination);
-    const { content, options } = encodeEnvelope(envelope);
-    await this.#publishConfirmed(
-      this.#settings.exchange,
-      destination,
+    const { content, options } = this.#settings.encode(envelope);
+    await this.#publishConfirmed({
+      exchange: this.#settings.exchange,
+      routingKey: destination,
       content,
       options,
-      !this.#settings.allowUnroutable
-    );
+      mandatory: !this.#settings.allowUnroutable
+    });
   }
-  async #publishConfirmed(exchange, routingKey, content, options, mandatory) {
+  async #publishConfirmed(input) {
+    const { exchange, routingKey, content, options, mandatory } = input;
     const publisher = this.#live?.publisher;
     const eventId = options.messageId ?? "unknown";
     if (publisher === void 0) {
@@ -1160,18 +1382,21 @@ var RabbitMqTransport = class {
     }
     const returnKey = unroutableKey(options.messageId, routingKey);
     await new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        reject(
-          new RabbitMqUnavailableError(
-            `[RabbitMqTransport](publish) No broker confirm within ${this.#settings.publishTimeoutMs}ms | transport=${this.name} eventId=${eventId} destination=${routingKey}`
-          )
-        );
-      }, this.#settings.publishTimeoutMs);
+      const cancelTimeout = schedule(systemClock, {
+        run: () => {
+          reject(
+            new RabbitMqUnavailableError(
+              `[RabbitMqTransport](publish) No broker confirm within ${this.#settings.publishTimeoutMs}ms | transport=${this.name} eventId=${eventId} destination=${routingKey}`
+            )
+          );
+        },
+        delayMs: this.#settings.publishTimeoutMs
+      });
       const onConfirm = (error) => {
-        clearTimeout(timer);
+        cancelTimeout();
         const returned = takeUnroutable(publisher.unroutable, returnKey);
         if (error) {
-          reject(this.#toPublishError(error, eventId, routingKey));
+          reject(this.#toPublishError(error, { eventId, destination: routingKey }));
         } else if (returned) {
           reject(
             new UnroutableMessageError(
@@ -1191,8 +1416,8 @@ var RabbitMqTransport = class {
           onConfirm
         );
       } catch (error) {
-        clearTimeout(timer);
-        reject(this.#toPublishError(error, eventId, routingKey));
+        cancelTimeout();
+        reject(this.#toPublishError(error, { eventId, destination: routingKey }));
       }
     });
   }
@@ -1201,7 +1426,8 @@ var RabbitMqTransport = class {
    * to `onMessage`. Call it once per transport; give each subscription its own
    * transport instance, with its own `name` and `consumerGroup`.
    */
-  async subscribe(destinations, onMessage) {
+  // eslint-disable-next-line relaybus/max-two-params -- the Transport.subscribe signature
+  async subscribe(destinations, onMessage, hooks) {
     if (this.#subscription !== void 0) {
       throw new ConfigurationError(
         `Transport '${this.name}' already has a subscription; create another transport for another consumer group`
@@ -1231,9 +1457,10 @@ var RabbitMqTransport = class {
         redeliveryMaxAgeMs: this.#settings.redeliveryMaxAgeMs,
         ordered: this.#settings.ordered,
         deadLetterExchange: this.#settings.deadLetterExchange,
-        republish: (exchange, routingKey, content, options) => this.#publishConfirmed(exchange, routingKey, content, options, true),
+        republish: ({ exchange, routingKey }, { content, options }) => this.#publishConfirmed({ exchange, routingKey, content, options, mandatory: true }),
         shutdownTimeoutMs: this.#settings.shutdownTimeoutMs,
         onMessage,
+        ...hooks === void 0 ? {} : { onInvalidMessage: hooks.onInvalidMessage },
         decode: this.#settings.decode,
         onConsumerLost: (reason) => this.#supervisor.recover(reason),
         logger: this.#settings.logger,
@@ -1250,21 +1477,29 @@ var RabbitMqTransport = class {
   /**
    * Stops consuming, waits up to `shutdownTimeout` for running handlers
    * (messages still being retried go back to the queue), then closes the
-   * channels and the connection.
+   * channels and the connection. Once `options.signal` aborts (the bus shutdown deadline passed),
+   * the connection's socket is destroyed instead of waiting for the broker.
    */
-  async close() {
-    if (this.#closed) {
-      return;
+  async close(options = {}) {
+    const { signal } = options;
+    const force = () => this.#supervisor.forceClose();
+    if (signal?.aborted === true) {
+      force();
+    }
+    signal?.addEventListener("abort", force, { once: true });
+    try {
+      this.#closing ??= this.#supervisor.close(
+        () => this.#topologyWork.run(async () => {
+          const live = this.#live;
+          this.#live = void 0;
+          await this.#subscription?.consumer.stop();
+          await live?.publisher.channel.close().catch(() => void 0);
+        })
+      );
+      await this.#closing;
+    } finally {
+      signal?.removeEventListener("abort", force);
     }
-    this.#closed = true;
-    await this.#supervisor.close(
-      () => this.#topologyWork.run(async () => {
-        const live = this.#live;
-        this.#live = void 0;
-        await this.#subscription?.consumer.stop();
-        await live?.publisher.channel.close().catch(() => void 0);
-      })
-    );
   }
   async #establishChannels(connection) {
     await this.#topologyWork.run(async () => {
@@ -1308,7 +1543,7 @@ var RabbitMqTransport = class {
     this.#live = void 0;
     this.#subscription?.consumer.detach();
   }
-  #toPublishError(error, eventId, destination) {
+  #toPublishError(error, { eventId, destination }) {
     const { message } = toErrorInfo(error);
     const detail = `transport=${this.name} eventId=${eventId} destination=${destination} error=${message}`;
     return message === NACK_MESSAGE ? new RabbitMqPublishRejectedError(
@@ -1338,34 +1573,7 @@ function takeUnroutable(unroutable, key) {
   }
   return true;
 }
-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)) {
-    throw new ConfigurationError(
-      `fromPayloadField needs a dotted path of non-empty names, received '${path}'`
-    );
-  }
-  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;
-  };
-}
 
-export { AmqpLimitExceededError, MalformedMessageError, RabbitMqPublishRejectedError, RabbitMqTransport, RabbitMqUnavailableError, UnroutableMessageError, UnserializablePayloadError, decodeCloudEvent, fromHeader, fromPayloadField, plainJsonDecoder };
+export { AmqpLimitExceededError, MalformedMessageError, RabbitMqPublishRejectedError, RabbitMqTransport, RabbitMqUnavailableError, RabbitMqUnencodableEventError, UnroutableMessageError, UnserializablePayloadError, cloudEventsBinary, cloudEventsStructured, decodeCloudEvent, jsonEnvelope, plainJsonDecoder };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map