@relaybus/rabbitmq 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,281 @@
+import { EventEmitter } from 'node:events';
+import { NonRetryableError, RelayBusError, RetryPolicyOptions, Duration, RelayBusLogger, Transport, EventEnvelope, TransportMessageHandler } from '@relaybus/core';
+
+/**
+ * The slice of amqplib this package relies on. Declaring it here keeps the
+ * public types independent of the amqplib version (peer range `>=0.10`) and
+ * lets tests substitute fakes. Real amqplib connections and channels satisfy it.
+ */
+/** Message properties as delivered by the broker. */
+interface AmqpMessageProperties {
+    readonly messageId?: unknown;
+    readonly type?: unknown;
+    readonly appId?: unknown;
+    readonly correlationId?: unknown;
+    readonly timestamp?: unknown;
+    readonly contentType?: unknown;
+    readonly headers?: Readonly<Record<string, unknown>> | undefined;
+}
+/** A message delivered to a consumer or returned by the broker. */
+interface AmqpMessage {
+    readonly content: Buffer;
+    readonly fields: {
+        readonly routingKey: string;
+    };
+    readonly properties: AmqpMessageProperties;
+}
+/** Properties set on a published message. */
+interface AmqpPublishOptions {
+    readonly contentType: string;
+    readonly persistent: boolean;
+    readonly mandatory?: boolean;
+    readonly messageId?: string;
+    readonly type?: string;
+    readonly appId?: string;
+    readonly timestamp?: number;
+    readonly correlationId?: string;
+    readonly headers: Readonly<Record<string, unknown>>;
+}
+/** Channel used for consuming. */
+interface AmqpChannel extends EventEmitter {
+    assertExchange(exchange: string, type: string, options?: {
+        readonly durable?: boolean;
+    }): Promise<unknown>;
+    assertQueue(queue: string, options?: {
+        readonly durable?: boolean;
+        readonly arguments?: Record<string, unknown>;
+    }): Promise<unknown>;
+    bindQueue(queue: string, source: string, pattern: string): Promise<unknown>;
+    prefetch(count: number): Promise<unknown>;
+    consume(queue: string, onMessage: (message: AmqpMessage | null) => void, options?: {
+        readonly noAck?: boolean;
+    }): Promise<{
+        readonly consumerTag: string;
+    }>;
+    cancel(consumerTag: string): Promise<unknown>;
+    ack(message: AmqpMessage): void;
+    nack(message: AmqpMessage, allUpTo?: boolean, requeue?: boolean): void;
+    close(): Promise<void>;
+}
+/** Channel with publisher confirms. */
+interface AmqpConfirmChannel extends AmqpChannel {
+    publish(exchange: string, routingKey: string, content: Buffer, options: AmqpPublishOptions, callback: (error: Error | null | undefined) => void): boolean;
+}
+/** A broker connection. Emits `close` and `error`. */
+interface AmqpConnection extends EventEmitter {
+    createChannel(): Promise<AmqpChannel>;
+    createConfirmChannel(): Promise<AmqpConfirmChannel>;
+    close(): Promise<void>;
+}
+
+/**
+ * The broker cannot take or confirm a message right now: the transport is not
+ * connected, was closed, lost its channel, or the confirm did not arrive in time.
+ * Always retryable; the outbox keeps the delivery and tries again.
+ */
+declare class RabbitMqUnavailableError extends RelayBusError {
+}
+/** The broker negatively acknowledged a published message. Retryable. */
+declare class RabbitMqPublishRejectedError extends RelayBusError {
+}
+/**
+ * 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 {
+}
+/** A received message is not a valid relaybus CloudEvent. It is dead-lettered. */
+declare class MalformedMessageError extends RelayBusError {
+}
+/**
+ * The payload of an event cannot be represented as JSON without losing or
+ * changing data (`undefined`, functions, symbols, BigInt, NaN, Infinity, Dates,
+ * Maps, class instances, cycles). Never retried: the payload will not change.
+ */
+declare class UnserializablePayloadError extends NonRetryableError {
+    name: string;
+}
+/**
+ * A value exceeds a protocol limit of AMQP 0-9-1, for example an event id or a
+ * routing key longer than the 255 bytes of a short string. Never retried.
+ */
+declare class AmqpLimitExceededError extends NonRetryableError {
+    name: string;
+}
+
+/** Connection settings accepted by `amqplib.connect`, given as an object instead of a URL. */
+interface BrokerConnectionSettings {
+    readonly protocol?: string;
+    readonly hostname?: string;
+    readonly port?: number;
+    readonly username?: string;
+    readonly password?: string;
+    readonly vhost?: string;
+    /** Seconds. See "Operational notes" in the README for the heartbeat defaults of each amqplib version. */
+    readonly heartbeat?: number;
+}
+/** Backoff between reconnect attempts. Attempts are unlimited. */
+type ReconnectOptions = Pick<RetryPolicyOptions, 'initialDelay' | 'factor' | 'maxDelay' | 'jitter'>;
+/**
+ * Delayed redelivery of messages whose handler keeps failing. Each failed
+ * delivery goes to a retry queue and returns to the main queue after a growing
+ * delay, so an outage of the handler's dependency is waited out instead of
+ * burning through delivery attempts.
+ */
+type RedeliveryOptions = Pick<RetryPolicyOptions, 'initialDelay' | 'factor' | 'maxDelay' | 'jitter'> & {
+    /**
+     * How long a message may keep failing, counted from its first delayed
+     * redelivery, before it is dead-lettered. Default `'1h'`.
+     */
+    readonly maxAge?: Duration;
+};
+interface RabbitMqTransportOptions {
+    /** Name referenced by routes and subscriptions. Default `'rabbitmq'`. */
+    readonly name?: string;
+    /**
+     * Broker location, for example `amqp://user:pass@host:5672/vhost?heartbeat=30`.
+     * Give exactly one of `url` and `connect`.
+     */
+    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.
+     */
+    readonly connect?: () => Promise<AmqpConnection>;
+    /** Topic exchange events are published to. Durable, created when missing. Default `'relaybus'`. */
+    readonly exchange?: string;
+    /**
+     * Unacknowledged messages the consumer holds, which is also its concurrency.
+     * Default 50, or 1 when `ordered`.
+     */
+    readonly prefetch?: number;
+    /** Prefix of derived queue names. Default `'relaybus'`. */
+    readonly queuePrefix?: string;
+    /**
+     * Consumer group: services sharing it share one queue and split the messages,
+     * services with different groups each receive every message. The queue is
+     * `<queuePrefix>.<consumerGroup>`. Required when subscribing, unless `queue` is set.
+     */
+    readonly consumerGroup?: string;
+    /** Explicit queue name. Overrides `queuePrefix` and `consumerGroup`. */
+    readonly queue?: string;
+    /** Exchange poison messages are dead-lettered to. Default `'<exchange>.dead'`. */
+    readonly deadLetterExchange?: string;
+    /** Queue that keeps dead-lettered messages for inspection. Default `'<queue>.dead'`. */
+    readonly deadLetterQueue?: string;
+    /**
+     * Quorum queue `x-delivery-limit`: deliveries after which the broker itself
+     * dead-letters a message. Failing handlers do not consume it (they use
+     * `redelivery`); it only stops a message that crashes the consumer or its
+     * channel again and again. Default 10.
+     */
+    readonly deliveryLimit?: number;
+    /**
+     * Handler attempts on the same delivery, with backoff, before the message is
+     * scheduled for delayed redelivery. Absorbs short blips without a broker round
+     * trip. Default: 3 attempts, 200 ms initial delay, factor 2, 5 s cap, equal jitter.
+     */
+    readonly handlerRetry?: RetryPolicyOptions;
+    /**
+     * Delayed redelivery after `handlerRetry` is spent. Default: 2 s initial
+     * delay, factor 2, 5 min cap, equal jitter, dead-lettered after 1 h of
+     * failing (about 18 redeliveries). Delays are quantized to the retry queues,
+     * one per step of the exponential ladder (9 queues with the defaults).
+     * Ignored when `ordered`, where the same delays are waited in place.
+     */
+    readonly redelivery?: RedeliveryOptions;
+    /**
+     * Consume the queue strictly in order: a single active consumer across all
+     * replicas, one message at a time, a failing message is retried in place
+     * (blocking the queue) instead of being delayed. Needed when
+     * `EventEnvelope.key` order matters; costs throughput, because one handler
+     * runs at a time. Default false: handlers run concurrently and a delayed
+     * redelivery overtakes later messages, so order is not preserved.
+     */
+    readonly ordered?: boolean;
+    /** Reconnect backoff, or `false` to never reconnect. Default: 500 ms initial, factor 2, 30 s cap, equal jitter. */
+    readonly reconnect?: ReconnectOptions | false;
+    /**
+     * When true (default) `connect()` rejects if the broker is unreachable, which
+     * fails startup. When false it resolves and keeps trying in the background.
+     */
+    readonly failOnConnectError?: boolean;
+    /**
+     * When false (default) a message that no queue is bound to makes `publish`
+     * reject. When true it resolves and the broker silently discards the message.
+     */
+    readonly allowUnroutable?: boolean;
+    /** How long `publish` waits for the broker confirm. Default `'30s'`. */
+    readonly publishTimeout?: Duration;
+    /** How long `close` waits for running handlers. Default `'30s'`. */
+    readonly shutdownTimeout?: Duration;
+    /** Default: `console`. */
+    readonly logger?: RelayBusLogger;
+    /** Random source for jitter. Default `Math.random`. Intended for tests. */
+    readonly random?: () => number;
+}
+
+/**
+ * RabbitMQ {@link Transport} built on amqplib.
+ *
+ * Publishing: each event goes to a durable topic exchange as a persistent,
+ * mandatory message with the destination as routing key. `publish` resolves
+ * only after the broker confirmed it was persisted and routed to a queue, and
+ * rejects when the transport is disconnected, the broker nacks, the message is
+ * unroutable or no confirm arrives in time. It never drops a message silently,
+ * so the outbox retries the delivery.
+ *
+ * Subscribing: one durable quorum queue per consumer group, bound to the
+ * destinations (routing-key patterns such as `orders.*`). A message is
+ * acknowledged only after the handler resolved. A failing handler is retried
+ * on the same delivery, then through retry queues with growing delays (see
+ * `redelivery`), and finally dead-lettered after the retry window; poison
+ * messages are dead-lettered at once. Nothing is lost on the way.
+ *
+ * Reconnection: after a connection or channel loss the transport reconnects
+ * with capped, jittered backoff and restores channels, topology and the
+ * consumer. Events published meanwhile are rejected, and therefore retried by
+ * the outbox, rather than buffered in memory.
+ */
+declare class RabbitMqTransport implements Transport {
+    #private;
+    readonly name: string;
+    constructor(options: RabbitMqTransportOptions);
+    /**
+     * True while the connection is open and publishing and consuming are set up.
+     * Use it for readiness probes.
+     */
+    isConnected(): boolean;
+    /**
+     * True when the transport can publish and, once subscribed, is consuming: the
+     * connection is up, its channels are open and the consumer is registered. False while reconnecting and after a cancelled consumer.
+     */
+    isReady(): boolean;
+    /** Connects to the broker. Rejects when it is unreachable unless `failOnConnectError` is false. */
+    connect(): Promise<void>;
+    /**
+     * Publishes to the exchange with `destination` as routing key and resolves
+     * after the broker confirmed the message.
+     *
+     * @throws {UnserializablePayloadError} the payload is not representable as JSON (never retried)
+     * @throws {AmqpLimitExceededError} the event id, a header name or `destination` exceeds 255 bytes (never retried)
+     * @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`)
+     */
+    publish(envelope: EventEnvelope, destination: string): Promise<void>;
+    /**
+     * Binds one durable quorum queue to `destinations` and delivers its messages
+     * 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>;
+    /**
+     * 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.
+     */
+    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 };