@relaybus/rabbitmq 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,5 +1,7 @@
 import { EventEmitter } from 'node:events';
-import { NonRetryableError, RelayBusError, RetryPolicyOptions, Duration, RelayBusLogger, Transport, EventEnvelope, TransportMessageHandler } from '@relaybus/core';
+import { NonRetryableError, RelayBusError, EventHeaders, EventEnvelope, RetryPolicyOptions, Duration, RelayBusLogger, Transport, TransportMessageHandler, TransportSubscriptionHooks, CloseOptions } from '@relaybus/core';
+import { JsonEnvelopeMapping } from '@relaybus/core/internal';
+export { fromHeader, fromPayloadField } from '@relaybus/core/internal';
 
 /**
  * The slice of amqplib this package relies on. Declaring it here keeps the
@@ -74,18 +76,26 @@ interface AmqpConnection extends EventEmitter {
  * Always retryable; the outbox keeps the delivery and tries again.
  */
 declare class RabbitMqUnavailableError extends RelayBusError {
+    name: string;
+    readonly code: string;
 }
 /** The broker negatively acknowledged a published message. Retryable. */
 declare class RabbitMqPublishRejectedError extends RelayBusError {
+    name: string;
+    readonly code: string;
 }
 /**
  * The broker accepted the message but no queue is bound to its routing key, so
  * it would have been discarded. Retryable: it succeeds once a consumer binds.
  */
 declare class UnroutableMessageError extends RelayBusError {
+    name: string;
+    readonly code: string;
 }
 /** A received message is not a valid relaybus CloudEvent. It is dead-lettered. */
 declare class MalformedMessageError extends RelayBusError {
+    name: string;
+    readonly code: string;
 }
 /**
  * The payload of an event cannot be represented as JSON without losing or
@@ -94,6 +104,7 @@ declare class MalformedMessageError extends RelayBusError {
  */
 declare class UnserializablePayloadError extends NonRetryableError {
     name: string;
+    readonly code: string;
 }
 /**
  * A value exceeds a protocol limit of AMQP 0-9-1, for example an event id or a
@@ -101,8 +112,191 @@ declare class UnserializablePayloadError extends NonRetryableError {
  */
 declare class AmqpLimitExceededError extends NonRetryableError {
     name: string;
+    readonly code: string;
+}
+/**
+ * An event the configured codec cannot write: a header name the format
+ * reserves, or a type a fixed-type route does not carry. Never retried.
+ */
+declare class RabbitMqUnencodableEventError extends NonRetryableError {
+    name: string;
+    readonly code: string;
 }
 
+/**
+ * The event a decoder extracted from a message. `id`, `type` and `payload` are
+ * required; every other field may be left out and is then filled by the
+ * transport: `source` with the `appId` property (else the routing key), `key`
+ * with null, `headers` with none, `correlationId` and `causationId` with null,
+ * and `occurredAt` with the `timestamp` property (else the time of receipt).
+ */
+interface DecodedEvent {
+    readonly id: string;
+    readonly type: string;
+    readonly payload: unknown;
+    readonly source?: string;
+    readonly key?: string | null;
+    readonly headers?: EventHeaders;
+    readonly correlationId?: string | null;
+    readonly causationId?: string | null;
+    readonly occurredAt?: Date;
+}
+/**
+ * Turns a consumed message into an event, for queues fed by producers that do
+ * not use relaybus. Must be synchronous and free of side effects: it runs again
+ * on every redelivery, so the same message must always give the same event,
+ * above all the same `id`, which is what the inbox deduplicates on.
+ *
+ * Anything it throws marks the message as malformed: it is dead-lettered and
+ * the consumer moves on. An event the bus then rejects (empty id, invalid type
+ * or time) is dead-lettered the same way.
+ */
+type RabbitMqMessageDecoder = (message: AmqpMessage) => DecodedEvent;
+/** A plain JSON message, decoded for the extractor options of {@link plainJsonDecoder}. */
+interface PlainJsonMessage {
+    readonly routingKey: string;
+    /** The AMQP properties as delivered (`messageId`, `type`, `appId`, `timestamp`, ...). */
+    readonly properties: AmqpMessageProperties;
+    /**
+     * The message headers with string values, without the broker's and the
+     * transport's own (`x-death`, `x-first-death-*`, `x-last-death-*`, `x-relaybus-*`).
+     */
+    readonly headers: EventHeaders;
+    /** The body parsed as JSON. */
+    readonly payload: unknown;
+}
+/** Options of {@link plainJsonDecoder}. Extractors returning undefined or `''` select the default. */
+interface PlainJsonDecoderOptions {
+    /**
+     * Event type handlers subscribe to: a fixed name for a queue that carries one
+     * kind of event, or an extractor such as `fromHeader('event-type')`,
+     * `fromPayloadField('type')` or `(message) => message.properties.type`.
+     * Required; a message without a type is malformed.
+     */
+    readonly type: string | ((message: PlainJsonMessage) => string | undefined);
+    /**
+     * Event id the inbox deduplicates on. Default, and fallback when the
+     * extractor finds none: the `messageId` property, which survives
+     * redeliveries. A message with neither is malformed, because AMQP has no
+     * other identity that is stable across redeliveries; give producers a
+     * `messageId` (Spring AMQP can generate one with `setCreateMessageIds(true)`).
+     */
+    readonly id?: (message: PlainJsonMessage) => string | undefined;
+    /** Ordering key. Default: none. */
+    readonly key?: (message: PlainJsonMessage) => string | null | undefined;
+    /** Logical name of the producer. Default: the `appId` property, else the routing key. */
+    readonly source?: string | ((message: PlainJsonMessage) => string | undefined);
+    /** When the event happened. Default: the `timestamp` property, else the time of receipt. */
+    readonly occurredAt?: (message: PlainJsonMessage) => Date | undefined;
+}
+/**
+ * Decodes a CloudEvents 1.0 message in either content mode:
+ * - structured (`contentType` property `application/cloudevents+json`): the
+ *   body is a JSON object with `specversion`, `id`, `type`, `source` and
+ *   optionally `time` (else the `timestamp` property, else the time of
+ *   receipt), `subject` (the key), `data` (the payload, null when absent) and
+ *   a JSON `datacontenttype`. `data_base64` is refused, because relaybus
+ *   payloads are JSON. Extension attributes with string values (`traceparent`,
+ *   ...) become event headers, as do the string message headers;
+ *   `correlationid` and `causationid` fill their envelope fields.
+ * - binary (anything else): exactly the default decoder, `cloudEvents:*`
+ *   headers with the AMQP properties as fallback.
+ *
+ * @throws MalformedMessageError for a message that is neither.
+ */
+declare function decodeCloudEvent(message: AmqpMessage): EventEnvelope;
+/**
+ * Creates a decoder for messages whose body is plain JSON, as published by a
+ * service that does not use relaybus (plain amqplib, Spring AMQP's
+ * `Jackson2JsonMessageConverter`, a Go or Python service): the body becomes the
+ * payload, the string headers become event headers, and the options say where
+ * the event type and id come from.
+ *
+ * A message that is a CloudEvent anyway (a `cloudEvents:specversion` header,
+ * or a structured `application/cloudevents+json` body) is decoded with
+ * {@link decodeCloudEvent} instead, so relaybus and foreign producers can feed
+ * one queue. A body that is not JSON, a missing or invalid type, a missing id
+ * and an extractor returning anything but a string are malformed.
+ *
+ * ```ts
+ * new RabbitMqTransport({
+ *   url,
+ *   consumerGroup: 'billing',
+ *   decode: plainJsonDecoder({ type: (message) => message.properties.type as string }),
+ * });
+ * ```
+ *
+ * @throws ConfigurationError when a fixed `type` is not a valid event type.
+ */
+declare function plainJsonDecoder(options: PlainJsonDecoderOptions): RabbitMqMessageDecoder;
+
+/** A serialized event, ready for `channel.publish`. */
+interface EncodedMessage {
+    readonly content: Buffer;
+    readonly options: AmqpPublishOptions;
+}
+
+/**
+ * The wire format of a {@link RabbitMqTransport}: how an event becomes a
+ * message (`encode`, on publish) and a consumed message becomes an event
+ * (`decode`).
+ *
+ * Both must be synchronous and free of side effects. What `encode` throws
+ * fails the publish: the outbox retries it, unless it is a `NonRetryableError`
+ * such as {@link RabbitMqUnencodableEventError}. Give every message a
+ * `messageId`: the transport matches broker returns of unroutable messages by
+ * it. What `decode` throws marks the message as malformed: it is
+ * dead-lettered and the consumer moves on. See {@link RabbitMqMessageDecoder}
+ * for the decode contract.
+ */
+interface RabbitMqCodec {
+    readonly encode: (envelope: EventEnvelope) => EncodedMessage;
+    readonly decode: RabbitMqMessageDecoder;
+}
+/**
+ * CloudEvents 1.0 binary content mode, the default: the body is the JSON
+ * payload, the attributes travel as `cloudEvents:*` headers mirrored in the
+ * AMQP properties. Decoding is strict: any other message is malformed.
+ */
+declare const cloudEventsBinary: RabbitMqCodec;
+/**
+ * CloudEvents 1.0 structured content mode: the body is one
+ * `application/cloudevents+json` document with the attributes and `data`.
+ * Decoding accepts structured and binary mode ({@link decodeCloudEvent}).
+ * Event headers travel under their own names; names starting with `x-death`,
+ * `x-first-death-`, `x-last-death-` or `x-relaybus-` are refused.
+ */
+declare const cloudEventsStructured: RabbitMqCodec;
+/**
+ * Where each value of a JSON message lives, for {@link jsonEnvelope}. Besides
+ * `{ body }` and `{ header }`, the id may be `'message-id-property'`: the
+ * AMQP `messageId` property, which the codec always writes and which survives
+ * redeliveries; a message without one is malformed.
+ */
+type RabbitMqJsonEnvelopeMapping = JsonEnvelopeMapping<'message-id-property'>;
+/**
+ * A JSON wire format declared by a mapping, in both directions: for queues
+ * shared with services that wrap events in their own envelope
+ * (`{ "eventName": ..., "data": {...} }`, MassTransit) or send the bare
+ * payload. Every message also gets the AMQP properties of binary mode:
+ * `messageId` (the event id), `type`, `appId` (the source), `correlationId`,
+ * `timestamp` (seconds) and `persistent`. Event
+ * headers that are message headers are written as they are, so a name the
+ * mapping uses for another field, or one the broker reserves, is refused
+ * with {@link RabbitMqUnencodableEventError}.
+ *
+ * ```ts
+ * codec: jsonEnvelope({
+ *   type: { body: 'eventName' },
+ *   id: 'message-id-property',
+ *   payload: { body: 'data' },
+ * })
+ * ```
+ *
+ * @throws ConfigurationError for an incomplete or self-overlapping mapping.
+ */
+declare function jsonEnvelope(mapping: RabbitMqJsonEnvelopeMapping): RabbitMqCodec;
+
 /** Connection settings accepted by `amqplib.connect`, given as an object instead of a URL. */
 interface BrokerConnectionSettings {
     readonly protocol?: string;
@@ -139,9 +333,11 @@ interface RabbitMqTransportOptions {
     readonly url?: string | BrokerConnectionSettings;
     /**
      * Opens one connection. Called again after every connection loss. Use it for
-     * TLS options, custom credentials or an alternative amqplib instance.
+     * TLS options, custom credentials or an alternative amqplib instance. `signal` aborts when a
+     * shutdown runs past its deadline: pass it on (`amqplib.connect(url, { signal })`) so a broker
+     * that never answers the handshake cannot hold the socket open.
      */
-    readonly connect?: () => Promise<AmqpConnection>;
+    readonly connect?: (options: ConnectOptions) => Promise<AmqpConnection>;
     /** Topic exchange events are published to. Durable, created when missing. Default `'relaybus'`. */
     readonly exchange?: string;
     /**
@@ -209,11 +405,36 @@ interface RabbitMqTransportOptions {
     readonly publishTimeout?: Duration;
     /** How long `close` waits for running handlers. Default `'30s'`. */
     readonly shutdownTimeout?: Duration;
+    /**
+     * The wire format, both ways: how events become messages and consumed
+     * messages become events. Default {@link cloudEventsBinary}: CloudEvents
+     * binary mode (`cloudEvents:*` headers, AMQP properties as fallback), any
+     * other message is malformed and dead-lettered. {@link cloudEventsStructured}
+     * writes structured mode and reads both, {@link jsonEnvelope} maps a JSON
+     * format of your own (an envelope with the payload inside, or the bare
+     * payload), and an object with `encode` and `decode` can do anything else.
+     * Whatever `decode` throws marks the message as malformed: it is
+     * dead-lettered, the consumer keeps running.
+     */
+    readonly codec?: RabbitMqCodec;
+    /**
+     * How consumed messages become events; events are still written in
+     * CloudEvents binary mode.
+     *
+     * @deprecated Use `codec`: `decode: fn` is `codec: { encode: encodeEnvelope, decode: fn }`.
+     * Giving both `decode` and `codec` is a configuration error.
+     */
+    readonly decode?: RabbitMqMessageDecoder;
     /** Default: `console`. */
     readonly logger?: RelayBusLogger;
     /** Random source for jitter. Default `Math.random`. Intended for tests. */
     readonly random?: () => number;
 }
+/** What `connect` gets for each connection it opens. */
+interface ConnectOptions {
+    /** Aborted when a shutdown runs past its deadline; destroys a socket still connecting. */
+    readonly signal: AbortSignal;
+}
 
 /**
  * RabbitMQ {@link Transport} built on amqplib.
@@ -240,6 +461,7 @@ interface RabbitMqTransportOptions {
 declare class RabbitMqTransport implements Transport {
     #private;
     readonly name: string;
+    readonly system = "rabbitmq";
     constructor(options: RabbitMqTransportOptions);
     /**
      * True while the connection is open and publishing and consuming are set up.
@@ -262,6 +484,7 @@ declare class RabbitMqTransport implements Transport {
      * @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}
      */
     publish(envelope: EventEnvelope, destination: string): Promise<void>;
     /**
@@ -269,13 +492,14 @@ declare class RabbitMqTransport implements Transport {
      * to `onMessage`. Call it once per transport; give each subscription its own
      * transport instance, with its own `name` and `consumerGroup`.
      */
-    subscribe(destinations: readonly string[], onMessage: TransportMessageHandler): Promise<void>;
+    subscribe(destinations: readonly string[], onMessage: TransportMessageHandler, hooks?: TransportSubscriptionHooks): Promise<void>;
     /**
      * 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.
      */
-    close(): Promise<void>;
+    close(options?: CloseOptions): Promise<void>;
 }
 
-export { type AmqpChannel, type AmqpConfirmChannel, type AmqpConnection, AmqpLimitExceededError, type AmqpMessage, type AmqpMessageProperties, type AmqpPublishOptions, type BrokerConnectionSettings, MalformedMessageError, RabbitMqPublishRejectedError, RabbitMqTransport, type RabbitMqTransportOptions, RabbitMqUnavailableError, type ReconnectOptions, type RedeliveryOptions, UnroutableMessageError, UnserializablePayloadError };
+export { type AmqpChannel, type AmqpConfirmChannel, type AmqpConnection, AmqpLimitExceededError, type AmqpMessage, type AmqpMessageProperties, type AmqpPublishOptions, type BrokerConnectionSettings, type DecodedEvent, type EncodedMessage, MalformedMessageError, type PlainJsonDecoderOptions, type PlainJsonMessage, type RabbitMqCodec, type RabbitMqJsonEnvelopeMapping, type RabbitMqMessageDecoder, RabbitMqPublishRejectedError, RabbitMqTransport, type RabbitMqTransportOptions, RabbitMqUnavailableError, RabbitMqUnencodableEventError, type ReconnectOptions, type RedeliveryOptions, UnroutableMessageError, UnserializablePayloadError, cloudEventsBinary, cloudEventsStructured, decodeCloudEvent, jsonEnvelope, plainJsonDecoder };

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { EventEmitter } from 'node:events';
-import { NonRetryableError, RelayBusError, RetryPolicyOptions, Duration, RelayBusLogger, Transport, EventEnvelope, TransportMessageHandler } from '@relaybus/core';
+import { NonRetryableError, RelayBusError, EventHeaders, EventEnvelope, RetryPolicyOptions, Duration, RelayBusLogger, Transport, TransportMessageHandler, TransportSubscriptionHooks, CloseOptions } from '@relaybus/core';
+import { JsonEnvelopeMapping } from '@relaybus/core/internal';
+export { fromHeader, fromPayloadField } from '@relaybus/core/internal';
 
 /**
  * The slice of amqplib this package relies on. Declaring it here keeps the
@@ -74,18 +76,26 @@ interface AmqpConnection extends EventEmitter {
  * Always retryable; the outbox keeps the delivery and tries again.
  */
 declare class RabbitMqUnavailableError extends RelayBusError {
+    name: string;
+    readonly code: string;
 }
 /** The broker negatively acknowledged a published message. Retryable. */
 declare class RabbitMqPublishRejectedError extends RelayBusError {
+    name: string;
+    readonly code: string;
 }
 /**
  * The broker accepted the message but no queue is bound to its routing key, so
  * it would have been discarded. Retryable: it succeeds once a consumer binds.
  */
 declare class UnroutableMessageError extends RelayBusError {
+    name: string;
+    readonly code: string;
 }
 /** A received message is not a valid relaybus CloudEvent. It is dead-lettered. */
 declare class MalformedMessageError extends RelayBusError {
+    name: string;
+    readonly code: string;
 }
 /**
  * The payload of an event cannot be represented as JSON without losing or
@@ -94,6 +104,7 @@ declare class MalformedMessageError extends RelayBusError {
  */
 declare class UnserializablePayloadError extends NonRetryableError {
     name: string;
+    readonly code: string;
 }
 /**
  * A value exceeds a protocol limit of AMQP 0-9-1, for example an event id or a
@@ -101,8 +112,191 @@ declare class UnserializablePayloadError extends NonRetryableError {
  */
 declare class AmqpLimitExceededError extends NonRetryableError {
     name: string;
+    readonly code: string;
+}
+/**
+ * An event the configured codec cannot write: a header name the format
+ * reserves, or a type a fixed-type route does not carry. Never retried.
+ */
+declare class RabbitMqUnencodableEventError extends NonRetryableError {
+    name: string;
+    readonly code: string;
 }
 
+/**
+ * The event a decoder extracted from a message. `id`, `type` and `payload` are
+ * required; every other field may be left out and is then filled by the
+ * transport: `source` with the `appId` property (else the routing key), `key`
+ * with null, `headers` with none, `correlationId` and `causationId` with null,
+ * and `occurredAt` with the `timestamp` property (else the time of receipt).
+ */
+interface DecodedEvent {
+    readonly id: string;
+    readonly type: string;
+    readonly payload: unknown;
+    readonly source?: string;
+    readonly key?: string | null;
+    readonly headers?: EventHeaders;
+    readonly correlationId?: string | null;
+    readonly causationId?: string | null;
+    readonly occurredAt?: Date;
+}
+/**
+ * Turns a consumed message into an event, for queues fed by producers that do
+ * not use relaybus. Must be synchronous and free of side effects: it runs again
+ * on every redelivery, so the same message must always give the same event,
+ * above all the same `id`, which is what the inbox deduplicates on.
+ *
+ * Anything it throws marks the message as malformed: it is dead-lettered and
+ * the consumer moves on. An event the bus then rejects (empty id, invalid type
+ * or time) is dead-lettered the same way.
+ */
+type RabbitMqMessageDecoder = (message: AmqpMessage) => DecodedEvent;
+/** A plain JSON message, decoded for the extractor options of {@link plainJsonDecoder}. */
+interface PlainJsonMessage {
+    readonly routingKey: string;
+    /** The AMQP properties as delivered (`messageId`, `type`, `appId`, `timestamp`, ...). */
+    readonly properties: AmqpMessageProperties;
+    /**
+     * The message headers with string values, without the broker's and the
+     * transport's own (`x-death`, `x-first-death-*`, `x-last-death-*`, `x-relaybus-*`).
+     */
+    readonly headers: EventHeaders;
+    /** The body parsed as JSON. */
+    readonly payload: unknown;
+}
+/** Options of {@link plainJsonDecoder}. Extractors returning undefined or `''` select the default. */
+interface PlainJsonDecoderOptions {
+    /**
+     * Event type handlers subscribe to: a fixed name for a queue that carries one
+     * kind of event, or an extractor such as `fromHeader('event-type')`,
+     * `fromPayloadField('type')` or `(message) => message.properties.type`.
+     * Required; a message without a type is malformed.
+     */
+    readonly type: string | ((message: PlainJsonMessage) => string | undefined);
+    /**
+     * Event id the inbox deduplicates on. Default, and fallback when the
+     * extractor finds none: the `messageId` property, which survives
+     * redeliveries. A message with neither is malformed, because AMQP has no
+     * other identity that is stable across redeliveries; give producers a
+     * `messageId` (Spring AMQP can generate one with `setCreateMessageIds(true)`).
+     */
+    readonly id?: (message: PlainJsonMessage) => string | undefined;
+    /** Ordering key. Default: none. */
+    readonly key?: (message: PlainJsonMessage) => string | null | undefined;
+    /** Logical name of the producer. Default: the `appId` property, else the routing key. */
+    readonly source?: string | ((message: PlainJsonMessage) => string | undefined);
+    /** When the event happened. Default: the `timestamp` property, else the time of receipt. */
+    readonly occurredAt?: (message: PlainJsonMessage) => Date | undefined;
+}
+/**
+ * Decodes a CloudEvents 1.0 message in either content mode:
+ * - structured (`contentType` property `application/cloudevents+json`): the
+ *   body is a JSON object with `specversion`, `id`, `type`, `source` and
+ *   optionally `time` (else the `timestamp` property, else the time of
+ *   receipt), `subject` (the key), `data` (the payload, null when absent) and
+ *   a JSON `datacontenttype`. `data_base64` is refused, because relaybus
+ *   payloads are JSON. Extension attributes with string values (`traceparent`,
+ *   ...) become event headers, as do the string message headers;
+ *   `correlationid` and `causationid` fill their envelope fields.
+ * - binary (anything else): exactly the default decoder, `cloudEvents:*`
+ *   headers with the AMQP properties as fallback.
+ *
+ * @throws MalformedMessageError for a message that is neither.
+ */
+declare function decodeCloudEvent(message: AmqpMessage): EventEnvelope;
+/**
+ * Creates a decoder for messages whose body is plain JSON, as published by a
+ * service that does not use relaybus (plain amqplib, Spring AMQP's
+ * `Jackson2JsonMessageConverter`, a Go or Python service): the body becomes the
+ * payload, the string headers become event headers, and the options say where
+ * the event type and id come from.
+ *
+ * A message that is a CloudEvent anyway (a `cloudEvents:specversion` header,
+ * or a structured `application/cloudevents+json` body) is decoded with
+ * {@link decodeCloudEvent} instead, so relaybus and foreign producers can feed
+ * one queue. A body that is not JSON, a missing or invalid type, a missing id
+ * and an extractor returning anything but a string are malformed.
+ *
+ * ```ts
+ * new RabbitMqTransport({
+ *   url,
+ *   consumerGroup: 'billing',
+ *   decode: plainJsonDecoder({ type: (message) => message.properties.type as string }),
+ * });
+ * ```
+ *
+ * @throws ConfigurationError when a fixed `type` is not a valid event type.
+ */
+declare function plainJsonDecoder(options: PlainJsonDecoderOptions): RabbitMqMessageDecoder;
+
+/** A serialized event, ready for `channel.publish`. */
+interface EncodedMessage {
+    readonly content: Buffer;
+    readonly options: AmqpPublishOptions;
+}
+
+/**
+ * The wire format of a {@link RabbitMqTransport}: how an event becomes a
+ * message (`encode`, on publish) and a consumed message becomes an event
+ * (`decode`).
+ *
+ * Both must be synchronous and free of side effects. What `encode` throws
+ * fails the publish: the outbox retries it, unless it is a `NonRetryableError`
+ * such as {@link RabbitMqUnencodableEventError}. Give every message a
+ * `messageId`: the transport matches broker returns of unroutable messages by
+ * it. What `decode` throws marks the message as malformed: it is
+ * dead-lettered and the consumer moves on. See {@link RabbitMqMessageDecoder}
+ * for the decode contract.
+ */
+interface RabbitMqCodec {
+    readonly encode: (envelope: EventEnvelope) => EncodedMessage;
+    readonly decode: RabbitMqMessageDecoder;
+}
+/**
+ * CloudEvents 1.0 binary content mode, the default: the body is the JSON
+ * payload, the attributes travel as `cloudEvents:*` headers mirrored in the
+ * AMQP properties. Decoding is strict: any other message is malformed.
+ */
+declare const cloudEventsBinary: RabbitMqCodec;
+/**
+ * CloudEvents 1.0 structured content mode: the body is one
+ * `application/cloudevents+json` document with the attributes and `data`.
+ * Decoding accepts structured and binary mode ({@link decodeCloudEvent}).
+ * Event headers travel under their own names; names starting with `x-death`,
+ * `x-first-death-`, `x-last-death-` or `x-relaybus-` are refused.
+ */
+declare const cloudEventsStructured: RabbitMqCodec;
+/**
+ * Where each value of a JSON message lives, for {@link jsonEnvelope}. Besides
+ * `{ body }` and `{ header }`, the id may be `'message-id-property'`: the
+ * AMQP `messageId` property, which the codec always writes and which survives
+ * redeliveries; a message without one is malformed.
+ */
+type RabbitMqJsonEnvelopeMapping = JsonEnvelopeMapping<'message-id-property'>;
+/**
+ * A JSON wire format declared by a mapping, in both directions: for queues
+ * shared with services that wrap events in their own envelope
+ * (`{ "eventName": ..., "data": {...} }`, MassTransit) or send the bare
+ * payload. Every message also gets the AMQP properties of binary mode:
+ * `messageId` (the event id), `type`, `appId` (the source), `correlationId`,
+ * `timestamp` (seconds) and `persistent`. Event
+ * headers that are message headers are written as they are, so a name the
+ * mapping uses for another field, or one the broker reserves, is refused
+ * with {@link RabbitMqUnencodableEventError}.
+ *
+ * ```ts
+ * codec: jsonEnvelope({
+ *   type: { body: 'eventName' },
+ *   id: 'message-id-property',
+ *   payload: { body: 'data' },
+ * })
+ * ```
+ *
+ * @throws ConfigurationError for an incomplete or self-overlapping mapping.
+ */
+declare function jsonEnvelope(mapping: RabbitMqJsonEnvelopeMapping): RabbitMqCodec;
+
 /** Connection settings accepted by `amqplib.connect`, given as an object instead of a URL. */
 interface BrokerConnectionSettings {
     readonly protocol?: string;
@@ -139,9 +333,11 @@ interface RabbitMqTransportOptions {
     readonly url?: string | BrokerConnectionSettings;
     /**
      * Opens one connection. Called again after every connection loss. Use it for
-     * TLS options, custom credentials or an alternative amqplib instance.
+     * TLS options, custom credentials or an alternative amqplib instance. `signal` aborts when a
+     * shutdown runs past its deadline: pass it on (`amqplib.connect(url, { signal })`) so a broker
+     * that never answers the handshake cannot hold the socket open.
      */
-    readonly connect?: () => Promise<AmqpConnection>;
+    readonly connect?: (options: ConnectOptions) => Promise<AmqpConnection>;
     /** Topic exchange events are published to. Durable, created when missing. Default `'relaybus'`. */
     readonly exchange?: string;
     /**
@@ -209,11 +405,36 @@ interface RabbitMqTransportOptions {
     readonly publishTimeout?: Duration;
     /** How long `close` waits for running handlers. Default `'30s'`. */
     readonly shutdownTimeout?: Duration;
+    /**
+     * The wire format, both ways: how events become messages and consumed
+     * messages become events. Default {@link cloudEventsBinary}: CloudEvents
+     * binary mode (`cloudEvents:*` headers, AMQP properties as fallback), any
+     * other message is malformed and dead-lettered. {@link cloudEventsStructured}
+     * writes structured mode and reads both, {@link jsonEnvelope} maps a JSON
+     * format of your own (an envelope with the payload inside, or the bare
+     * payload), and an object with `encode` and `decode` can do anything else.
+     * Whatever `decode` throws marks the message as malformed: it is
+     * dead-lettered, the consumer keeps running.
+     */
+    readonly codec?: RabbitMqCodec;
+    /**
+     * How consumed messages become events; events are still written in
+     * CloudEvents binary mode.
+     *
+     * @deprecated Use `codec`: `decode: fn` is `codec: { encode: encodeEnvelope, decode: fn }`.
+     * Giving both `decode` and `codec` is a configuration error.
+     */
+    readonly decode?: RabbitMqMessageDecoder;
     /** Default: `console`. */
     readonly logger?: RelayBusLogger;
     /** Random source for jitter. Default `Math.random`. Intended for tests. */
     readonly random?: () => number;
 }
+/** What `connect` gets for each connection it opens. */
+interface ConnectOptions {
+    /** Aborted when a shutdown runs past its deadline; destroys a socket still connecting. */
+    readonly signal: AbortSignal;
+}
 
 /**
  * RabbitMQ {@link Transport} built on amqplib.
@@ -240,6 +461,7 @@ interface RabbitMqTransportOptions {
 declare class RabbitMqTransport implements Transport {
     #private;
     readonly name: string;
+    readonly system = "rabbitmq";
     constructor(options: RabbitMqTransportOptions);
     /**
      * True while the connection is open and publishing and consuming are set up.
@@ -262,6 +484,7 @@ declare class RabbitMqTransport implements Transport {
      * @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}
      */
     publish(envelope: EventEnvelope, destination: string): Promise<void>;
     /**
@@ -269,13 +492,14 @@ declare class RabbitMqTransport implements Transport {
      * to `onMessage`. Call it once per transport; give each subscription its own
      * transport instance, with its own `name` and `consumerGroup`.
      */
-    subscribe(destinations: readonly string[], onMessage: TransportMessageHandler): Promise<void>;
+    subscribe(destinations: readonly string[], onMessage: TransportMessageHandler, hooks?: TransportSubscriptionHooks): Promise<void>;
     /**
      * 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.
      */
-    close(): Promise<void>;
+    close(options?: CloseOptions): Promise<void>;
 }
 
-export { type AmqpChannel, type AmqpConfirmChannel, type AmqpConnection, AmqpLimitExceededError, type AmqpMessage, type AmqpMessageProperties, type AmqpPublishOptions, type BrokerConnectionSettings, MalformedMessageError, RabbitMqPublishRejectedError, RabbitMqTransport, type RabbitMqTransportOptions, RabbitMqUnavailableError, type ReconnectOptions, type RedeliveryOptions, UnroutableMessageError, UnserializablePayloadError };
+export { type AmqpChannel, type AmqpConfirmChannel, type AmqpConnection, AmqpLimitExceededError, type AmqpMessage, type AmqpMessageProperties, type AmqpPublishOptions, type BrokerConnectionSettings, type DecodedEvent, type EncodedMessage, MalformedMessageError, type PlainJsonDecoderOptions, type PlainJsonMessage, type RabbitMqCodec, type RabbitMqJsonEnvelopeMapping, type RabbitMqMessageDecoder, RabbitMqPublishRejectedError, RabbitMqTransport, type RabbitMqTransportOptions, RabbitMqUnavailableError, RabbitMqUnencodableEventError, type ReconnectOptions, type RedeliveryOptions, UnroutableMessageError, UnserializablePayloadError, cloudEventsBinary, cloudEventsStructured, decodeCloudEvent, jsonEnvelope, plainJsonDecoder };