Zum Inhalt springen
Deutsch

AMQP (RabbitMQ)

AmqpActor integriert mit RabbitMQ (und anderen AMQP-0.9.1- Brokern). Unterstützt Exchanges (direct / topic / fanout / headers), Queues, Routing-Keys, ACK/NACK-Semantik.

import { ActorSystem } from 'actor-ts';
import { AmqpActor, AmqpOptions } from 'actor-ts/io';
const amqpOptions = AmqpOptions.create()
.withUrl('amqp://guest:guest@rabbitmq:5672')
// Queue → Consumer-Actor-Verdrahtung läuft über `bindings` in
// den Settings — einmal beim Connect deklariert. Ein
// Runtime-Subscribe/Unsubscribe ist kein v1-Surface; wenn Du
// nach dem Start einen neuen Consumer anhängen musst, starte
// den Actor mit aktualisierten Bindings neu.
.withBindings([
{ queue: 'order-processor', exchange: 'orders', routingKey: 'placed.#', target: handler },
]);
const amqp = system.spawn(
() => new AmqpActor(
amqpOptions,
),
'amqp',
);
// An einen Exchange publishen:
amqp.tell({
kind: 'publish',
publish: {
exchange: 'orders',
routingKey: 'placed.priority',
content: JSON.stringify(order),
},
});
interface AmqpOptionsType extends BrokerCommonOptionsType {
url: string; // amqp:// oder amqps://
prefetch?: number; // ungeackte Nachrichten pro Consumer; Default 1
autoAcknowledge?: boolean; // ACK bei Auslieferung vs. nach Verarbeitung; Default true
bindings?: ReadonlyArray<AmqpQueueBinding>; // Queue ↔ Exchange ↔ Routing-Key ↔ Target
tls?: TlsTransportOptionsType; // Cert-Material für einen amqps://-Dial; nur im Code
}
type AmqpQueueBinding = {
queue: string;
exchange?: string; // weglassen für den Default-Exchange
routingKey?: string;
target: ActorRef<AmqpDelivery>; // Consumer-Actor für diese Queue
};

Bindings deklarieren die Queue, das Exchange-Binding UND den Consumer-Actor-Target auf einen Schlag — der Actor verdrahtet alles beim Connect (idempotente erneute Deklaration).

Dieselben Settings kommen auch aus HOCON, unter actor-ts.io.broker.amqp, unterhalb expliziter Optionen und oberhalb der eingebauten Defaults:

actor-ts.io.broker.amqp {
url = ${?ACTOR_TS_AMQP_URL} # amqp://user:password@rabbitmq:5672/vhost, or amqps://
prefetch = 10 # default 1; 0 = unlimited
auto-acknowledge = false # default true
}

Die URL trägt die Zugangsdaten, deshalb nimmt das Beispiel sie aus der Umgebung statt aus der Datei. Ein Wert aus der Umgebung wird zuerst als JSON gelesen, wo immer er sich als JSON parsen lässt; eine amqp://-URL tut das nie und kommt deshalb so an, wie sie geschrieben ist. Ein Wert, der es tut, käme verändert an oder ließe den Start scheitern: Einer, der sich wie eine Zahl liest, kommt in der Schreibweise dieser Zahl zurück — 1e3 als 1000, und eine ganze Zahl jenseits von Number.MAX_SAFE_INTEGER womöglich mit anderen letzten Ziffern (20261104123456789 als 20261104123456788) —, und einer, der sich wie null, eine Liste oder ein Objekt liest, lässt den Start mit einem ConfigError scheitern. Einen solchen Wert in der Variablen selbst quoten oder im Code setzen.

bindings und tls haben kein Blatt: Ein Binding benennt den Actor, an den seine Queue ausliefert, und TLS-Material ist ein privater Schlüssel — beides wird im Code gesetzt. Die Reconnect-, Circuit-Breaker- und Outbound-Buffer-Blätter, die sich alle Broker teilen, gehören unter denselben Root — siehe BrokerActor-Basis.

TypRouting
directExakter Match auf den Routing-Key.
topicWildcard-Pattern-Match (* = ein Segment, # = viele).
fanoutAlle gebundenen Queues, Routing-Key ignoriert.
headersMatch auf Nachrichten-Header, nicht Routing-Key.

AmqpActor deklariert keine Exchanges — sie müssen bereits auf dem Broker existieren (angelegt über die RabbitMQ-Konfiguration, das Management-UI oder dein Infrastruktur-Tooling). Beim Connect deklariert der Actor nur die in bindings genannten Queues und bindet sie an den angegebenen Exchange; das Publishen routet dann über diesen bestehenden Exchange per Name.

Häufigstes Muster: topic-Exchanges mit hierarchischen Routing-Keys (orders.placed.priority, orders.cancelled, payments.failed).

Setze autoAcknowledge: false in den Settings; dann teilt der Handler das Ergebnis per { kind: 'acknowledgment', delivery } oder { kind: 'negativeAcknowledgment', delivery, requeue } an die Ref des AMQP-Actors mit.

class OrderHandler extends Actor<AmqpDelivery> {
constructor(private readonly amqp: ActorRef<AmqpCommand>) { super(); }
override async onReceive(delivery: AmqpDelivery): Promise<void> {
try {
await processOrder(delivery);
this.amqp.tell({ kind: 'acknowledgment', delivery });
} catch (err) {
this.amqp.tell({ kind: 'negativeAcknowledgment', delivery, requeue: true });
}
}
}

Jede eingehende AmqpDelivery trägt einen opaken ackToken, mit dem der Actor die Broker-seitige Nachricht identifiziert — Du fasst ihn nicht direkt an, sondern reichst das ganze delivery- Objekt im ack/nack-Tell wieder zurück.

Der Broker hält die Nachricht im Unacked-Zustand, bis der Handler antwortet — wenn der Consumer crasht, liefert der Broker bei der nächsten Verbindung erneut aus. Nutze requeue: false, um an eine Dead-Letter-Queue zu senden (falls konfiguriert) — nützlich, wenn ein Retry nicht hilft.

prefetch: 10 // bis zu 10 ungeackte gleichzeitig pro Consumer konsumieren

Der Framework-Default ist 1 — eine einzige ungeackte Nachricht pro Consumer zur selben Zeit. (Der reine AMQP-Protokoll-Default ist 0 = unbegrenzt, aber der Actor setzt prefetch auf 1, sofern Du ihn nicht überschreibst.) Erhöhe ihn auf eine sinnvolle Batch-Größe (10–50), damit der Consumer ausgelastet, aber nicht überfordert wird.

Eine amqps://-URL startet den Handshake, und amqplib verifiziert den Broker gegen den System-Trust-Store. Hinter einer privaten CA — oder wenn der Broker ein Client-Zertifikat verlangt — kommt withTls dazu; es erreicht amqplib als dessen socketOptions-Argument:

const amqpOptions = AmqpOptions.create()
.withUrl('amqps://rabbitmq.example.com:5671')
.withTls({
ca: fs.readFileSync('./tls/ca.crt', 'utf8'),
cert: fs.readFileSync('./tls/client.crt', 'utf8'),
key: fs.readFileSync('./tls/client.key', 'utf8'),
});
new AmqpActor(amqpOptions);

Jedes Feld trägt das Material selbst, nie einen Pfad darauf — deshalb liest das Beispiel die Dateien. cert und key ergeben nur gemeinsam Sinn; eines ohne das andere wird beim Start des Actors abgelehnt, statt im Handshake zu werfen.

AMQP-URL-Query-Parameter tragen heartbeat, frameMax, channelMax und locale — nie Zertifikatsmaterial —, withTls ist also der einzige Weg dafür. Einen Config-Key hat es bewusst nicht: Ein Private Key gehört nicht in die application.conf.

Terminal-Fenster
npm install amqplib
# oder: bun add amqplib

Drei primäre Szenarien:

  1. Work-Queues — mehrere Consumer konkurrieren um Nachrichten auf einer Queue, pro Nachricht gewinnt ein Consumer.
  2. Routing + Filterung — Topic-Exchanges mit reichen Routing-Keys.
  3. Brücken zu bestehender RabbitMQ-Infrastruktur.

Für hochvolumiges Streaming skaliert Kafka besser. Für leichtgewichtiges Pub/Sub sind NATS oder MQTT schlanker. AMQP glänzt bei Enterprise-Style Queue + Routing, wo Features (DLQ, TTL, Prefetch, ACK-Semantik) zählen.