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), },});Settings
Abschnitt betitelt „Settings“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.
Exchanges und Routing
Abschnitt betitelt „Exchanges und Routing“| Typ | Routing |
|---|---|
direct | Exakter Match auf den Routing-Key. |
topic | Wildcard-Pattern-Match (* = ein Segment, # = viele). |
fanout | Alle gebundenen Queues, Routing-Key ignoriert. |
headers | Match 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).
ACK / NACK
Abschnitt betitelt „ACK / NACK“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
Abschnitt betitelt „Prefetch“prefetch: 10 // bis zu 10 ungeackte gleichzeitig pro Consumer konsumierenDer 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.
Peer-Dependency
Abschnitt betitelt „Peer-Dependency“npm install amqplib# oder: bun add amqplibWann AMQP
Abschnitt betitelt „Wann AMQP“Drei primäre Szenarien:
- Work-Queues — mehrere Consumer konkurrieren um Nachrichten auf einer Queue, pro Nachricht gewinnt ein Consumer.
- Routing + Filterung — Topic-Exchanges mit reichen Routing-Keys.
- 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.
Wohin als Nächstes
Abschnitt betitelt „Wohin als Nächstes“- I/O-Übersicht — das große Bild.
- BrokerActor-Basis — der gemeinsame Lifecycle.
- Kafka — fürs Streaming.
- NATS / MQTT — leichtere Alternativen.
