@relaybus/rabbitmq 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 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 } from '@relaybus/core';
 
 /**
  * The slice of amqplib this package relies on. Declaring it here keeps the
@@ -103,6 +103,113 @@ declare class AmqpLimitExceededError extends NonRetryableError {
     name: 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;
+
 /** Connection settings accepted by `amqplib.connect`, given as an object instead of a URL. */
 interface BrokerConnectionSettings {
     readonly protocol?: string;
@@ -209,6 +316,18 @@ interface RabbitMqTransportOptions {
     readonly publishTimeout?: Duration;
     /** How long `close` waits for running handlers. Default `'30s'`. */
     readonly shutdownTimeout?: Duration;
+    /**
+     * How consumed messages become events. Default: CloudEvents binary mode as
+     * relaybus producers write it (`cloudEvents:*` headers, AMQP properties as
+     * fallback); any other message is malformed and dead-lettered. Set it to
+     * consume messages from services that do not use relaybus:
+     * {@link decodeCloudEvent} also accepts structured mode, {@link plainJsonDecoder}
+     * maps plain JSON messages, and a function of your own can do anything else
+     * (switch on `message.fields.routingKey` to decode routing keys differently).
+     * Whatever a decoder throws marks the message as malformed: it is
+     * dead-lettered, the consumer keeps running.
+     */
+    readonly decode?: RabbitMqMessageDecoder;
     /** Default: `console`. */
     readonly logger?: RelayBusLogger;
     /** Random source for jitter. Default `Math.random`. Intended for tests. */
@@ -278,4 +397,33 @@ declare class RabbitMqTransport implements Transport {
     close(): 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 };
+/**
+ * Reads one header of an incoming message, for the `type`, `id`, `key` or
+ * `source` option of {@link plainJsonDecoder}. Header names are compared
+ * exactly (AMQP header names are case-sensitive). Returns undefined when the
+ * header is absent, so the decoder falls back to its default.
+ *
+ * ```ts
+ * plainJsonDecoder({ type: fromHeader('event-type'), id: fromHeader('message-id') })
+ * ```
+ */
+declare function fromHeader(name: string): (message: {
+    readonly headers: EventHeaders;
+}) => string | undefined;
+/**
+ * Reads a field of the JSON payload by a dotted path (`'meta.eventType'`), for
+ * the `type`, `id`, `key` or `source` option of {@link plainJsonDecoder}. A
+ * string is returned as is and a safe integer as its decimal text (numeric ids
+ * are common). Anything else returns undefined so the decoder falls back to its
+ * default: a missing field, and also a fraction or an integer beyond 2^53, which
+ * JSON parsing may already have rounded, so two different ids could collide.
+ *
+ * ```ts
+ * plainJsonDecoder({ type: fromPayloadField('eventType'), key: fromPayloadField('order.id') })
+ * ```
+ */
+declare function fromPayloadField(path: string): (message: {
+    readonly payload: unknown;
+}) => string | undefined;
+
+export { type AmqpChannel, type AmqpConfirmChannel, type AmqpConnection, AmqpLimitExceededError, type AmqpMessage, type AmqpMessageProperties, type AmqpPublishOptions, type BrokerConnectionSettings, type DecodedEvent, MalformedMessageError, type PlainJsonDecoderOptions, type PlainJsonMessage, type RabbitMqMessageDecoder, RabbitMqPublishRejectedError, RabbitMqTransport, type RabbitMqTransportOptions, RabbitMqUnavailableError, type ReconnectOptions, type RedeliveryOptions, UnroutableMessageError, UnserializablePayloadError, decodeCloudEvent, fromHeader, fromPayloadField, plainJsonDecoder };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 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 } from '@relaybus/core';
 
 /**
  * The slice of amqplib this package relies on. Declaring it here keeps the
@@ -103,6 +103,113 @@ declare class AmqpLimitExceededError extends NonRetryableError {
     name: 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;
+
 /** Connection settings accepted by `amqplib.connect`, given as an object instead of a URL. */
 interface BrokerConnectionSettings {
     readonly protocol?: string;
@@ -209,6 +316,18 @@ interface RabbitMqTransportOptions {
     readonly publishTimeout?: Duration;
     /** How long `close` waits for running handlers. Default `'30s'`. */
     readonly shutdownTimeout?: Duration;
+    /**
+     * How consumed messages become events. Default: CloudEvents binary mode as
+     * relaybus producers write it (`cloudEvents:*` headers, AMQP properties as
+     * fallback); any other message is malformed and dead-lettered. Set it to
+     * consume messages from services that do not use relaybus:
+     * {@link decodeCloudEvent} also accepts structured mode, {@link plainJsonDecoder}
+     * maps plain JSON messages, and a function of your own can do anything else
+     * (switch on `message.fields.routingKey` to decode routing keys differently).
+     * Whatever a decoder throws marks the message as malformed: it is
+     * dead-lettered, the consumer keeps running.
+     */
+    readonly decode?: RabbitMqMessageDecoder;
     /** Default: `console`. */
     readonly logger?: RelayBusLogger;
     /** Random source for jitter. Default `Math.random`. Intended for tests. */
@@ -278,4 +397,33 @@ declare class RabbitMqTransport implements Transport {
     close(): 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 };
+/**
+ * Reads one header of an incoming message, for the `type`, `id`, `key` or
+ * `source` option of {@link plainJsonDecoder}. Header names are compared
+ * exactly (AMQP header names are case-sensitive). Returns undefined when the
+ * header is absent, so the decoder falls back to its default.
+ *
+ * ```ts
+ * plainJsonDecoder({ type: fromHeader('event-type'), id: fromHeader('message-id') })
+ * ```
+ */
+declare function fromHeader(name: string): (message: {
+    readonly headers: EventHeaders;
+}) => string | undefined;
+/**
+ * Reads a field of the JSON payload by a dotted path (`'meta.eventType'`), for
+ * the `type`, `id`, `key` or `source` option of {@link plainJsonDecoder}. A
+ * string is returned as is and a safe integer as its decimal text (numeric ids
+ * are common). Anything else returns undefined so the decoder falls back to its
+ * default: a missing field, and also a fraction or an integer beyond 2^53, which
+ * JSON parsing may already have rounded, so two different ids could collide.
+ *
+ * ```ts
+ * plainJsonDecoder({ type: fromPayloadField('eventType'), key: fromPayloadField('order.id') })
+ * ```
+ */
+declare function fromPayloadField(path: string): (message: {
+    readonly payload: unknown;
+}) => string | undefined;
+
+export { type AmqpChannel, type AmqpConfirmChannel, type AmqpConnection, AmqpLimitExceededError, type AmqpMessage, type AmqpMessageProperties, type AmqpPublishOptions, type BrokerConnectionSettings, type DecodedEvent, MalformedMessageError, type PlainJsonDecoderOptions, type PlainJsonMessage, type RabbitMqMessageDecoder, RabbitMqPublishRejectedError, RabbitMqTransport, type RabbitMqTransportOptions, RabbitMqUnavailableError, type ReconnectOptions, type RedeliveryOptions, UnroutableMessageError, UnserializablePayloadError, decodeCloudEvent, fromHeader, fromPayloadField, plainJsonDecoder };