ProducerController
ProducerController umwickelt die ausgehenden Nachrichten eines
Senders, vergibt Sequence Numbers und hält sie, bis sie vom
Consumer geACKt sind.
import { ProducerControllerOptions, ReliableDelivery } from 'actor-ts/delivery';
const producerControllerOptions = ProducerControllerOptions.create<OrderEvent>() .withProducerId('orders') // stable identity .withConsumer(consumerRef) .withWindowSize(16) // flow-control window .withResendTimeout(500);const producer = ReliableDelivery.producer<OrderEvent>(system, producerControllerOptions, 'producer');
producer.tell({ orderId: 'o-1' });ReliableDelivery.producer spawnt den Controller und legt
actor-ts.reliable-delivery.producer unter die Optionen (siehe Aus HOCON).
Einen ProducerController selbst zu konstruieren und an system.spawn zu
übergeben, ist nur für ein Paar richtig, das über Cluster-Knoten hinweg reicht —
das können die Controller der Fassade nicht (siehe Cluster-aware).
Intern:
- Vergibt Seq 1 für die erste Nachricht, 2 für die nächste, …
- Sendet jede via Wrapped Tell an den Consumer.
- Hält sie in einem Buffer, bis sie geACKt sind.
- Retransmittiert, wenn binnen
resendTimeoutkein ACK kommt.
Konfiguration
Abschnitt betitelt „Konfiguration“type ProducerControllerOptionsType<T> = { consumer: ActorRef<Delivery<T>>; resendTimeout?: number; // Default 500 windowSize?: number; // Default 16 producerId?: string; // wird zufällig generiert, wenn weggelassen};| Feld | Zweck |
|---|---|
consumer | Die ConsumerController-Ref, an die zugestellt wird. |
resendTimeout | Wie lange auf ein ACK gewartet wird, bevor retransmittiert wird. |
windowSize | Flow-Control-Window — pausiert das Queuing nach N unbestätigten In-Flight-Nachrichten. |
producerId | Stabiler Identifier, an dem der Consumer seinen Dedup-State festmacht. Wird zufällig generiert, wenn weggelassen; setze ihn fest, wenn du über Restarts hinweg eine Identität in Logs, Metriken und der Map des Consumers willst. Er trägt kein Dedup-Fenster über einen Restart — siehe Restart und die Producer-Inkarnation. |
Aus HOCON
Abschnitt betitelt „Aus HOCON“resendTimeout und windowSize werden zusätzlich aus
actor-ts.reliable-delivery.producer
gelesen, in der üblichen Reihenfolge des Projekts: explizite Optionen
schlagen HOCON, und HOCON schlägt die eingebauten Defaults (500 ms und 16).
actor-ts.reliable-delivery.producer { resend-timeout = 2s window-size = 64}consumer und producerId haben keinen Schlüssel, aus zwei verschiedenen
Gründen: eine Actor-Referenz lässt sich in HOCON nicht ausdrücken, und eine
prozessweit geteilte producerId ist kein Setting, sondern ein
Korrektheitsfehler — der Consumer schlüsselt seinen Dedup-State darauf, zwei
Producer mit derselben Id setzen sich also gegenseitig das Fenster zurück.
Das Layering passiert in ReliableDelivery.producer(...), also sieht nur
dieser Pfad es. Ein ProducerController, den du selbst konstruierst und an
system.spawn übergibst, behält seine eingebauten Defaults: kein Controller
kann in seinem Konstruktor Konfiguration lesen, denn system ist ein Getter
über einen Kontext, den die Zelle erst nach der Konstruktion injiziert.
Eine generierte producerId ist zufällig, nicht fortlaufend. Früher war
sie ein Modul-Zähler — producer-1, producer-2, … — und das war gleich
doppelt falsch. Ein Acknowledgment nennt eine producerId und eine seq,
und die Seq ist bauartbedingt eine kleine ganze Zahl; ein Zähler ließ von
diesem Paar also keine Hälfte mehr zu erraten übrig. Der Zähler war außerdem
geteilt: zwei Prozesse desselben Service erzeugten beide producer-1,
stempelten dieselbe Identität auf ihre Deliveries und setzten sich danach
gegenseitig laufend das Dedup-Fenster bei einem gemeinsamen Consumer zurück.
Das Framework zieht jetzt stattdessen 16 Hex-Zeichen.
Diese Id wird bei jeder Konstruktion neu gezogen — producerId wegzulassen
heißt also, dass es gar keine Identität gibt, die stabil sein könnte. Setze
sie selbst, sobald irgendetwas weiter unten diesen Producer nach einem Restart
wiedererkennen soll.
Backpressure
Abschnitt betitelt „Backpressure“windowSize: 16Der Producer hält bis zu 16 unbestätigte Nachrichten in Flight.
Darüber hinaus werden eingehende
{ kind: 'reliable-delivery.send' }-Nachrichten
eingereiht — das tell des Callers ist erfolgreich, aber das
eigentliche Senden pausiert, bis ACKs den Slot freigeben.
Es gibt kein Signal zurück an den Caller, wenn dieses Queuing passiert:
ein reliable-delivery.send ist Fire-and-Forget — der Producer
antwortet nie darauf, es gibt also kein ask-basiertes
“Ich habe sie gesendet”-ACK, auf das man warten könnte.
Für Sender, die wissen müssen, ob eine Nachricht durchgekommen ist,
übergibst du einen confirm-Callback als zweites Argument von tell. Er
feuert, sobald der Consumer diese Nachricht per ACK bestätigt — mit null
bei Erfolg oder einem Error, wenn der Producer stoppt, bevor das ACK
eintrifft:
producer.tell({ orderId: 'o-1' }, (err) => { if (err) console.error('delivery failed', err); else console.log('delivered and acked');});Um daraus echtes Backpressure zu machen, richte dein Sende-Tempo nach diesen Bestätigungen aus — halte die nächste Charge zurück, bis frühere Nachrichten bestätigt sind.
Ein Callback, der wirft, bleibt beim Producer. confirm läuft im
eigenen Turn des Producers; ein Throw daraus wird dort abgefangen und auf
error-Level geloggt, mit dem Producer und der Nachricht — über ihre Seq
oder als noch eingereiht — samt dem, was geworfen wurde. Sonst ändert sich
nichts: Der Producer wird nicht neu gestartet, eine Nachricht, deren Callback
bei ihrem ACK geworfen hat, gilt trotzdem als zugestellt, eingereihte Sends
rücken weiter ins Fenster nach, und ein stoppender Producer schließt jeden
anderen Send trotzdem ab. Der Callback darf auch async sein: Das Promise,
das er zurückgibt, wird nicht abgewartet, und seine Rejection wird genauso
geloggt, statt als Unhandled Rejection aufzuschlagen, die den Prozess
beenden würde. Das gilt für jeden Wert: Kann der Logger ihn nicht
darstellen — etwa einen Error, dessen message-Getter wirft, oder einen
widerrufenen Proxy —, wird die Zeile ohne ihn geschrieben.
Retransmission
Abschnitt betitelt „Retransmission“Wenn ein ACK nicht binnen resendTimeout eintrifft:
Seq 5 zum Zeitpunkt t=0 gesendetACK für Seq 5 kommt niebei t=500 → Seq 5 retransmittenbei t=1000 → Seq 5 retransmitten... bis das ACK kommt oder der Producer stopptRetransmits nutzen dieselbe Seq wie das Original — und dieselbe Producer-Inkarnation, damit der Consumer sie als dieselbe Nachricht erkennt.
Ein Retransmit, den der Consumer ablehnt — sein tell wirft, wie es eine
begrenzte Mailbox mit der Overflow-Policy reject tut —, wird als Warnung mit
seiner Seq geloggt und nach dem nächsten resendTimeout erneut gesendet.
Eine abgelehnte erste Übertragung ist etwas anderes: Sie geschieht im
eigenen Turn des Producers und lässt ihn fehlschlagen (siehe Restart und die
Producer-Inkarnation).
Restart und die Producer-Inkarnation
Abschnitt betitelt „Restart und die Producer-Inkarnation“Jede Konstruktion eines ProducerController erzeugt ein frisches, nicht
erratbares Inkarnations-Token und stempelt es auf jedes Delivery. Es ist
nicht konfigurierbar; es existiert, weil producerId allein zwei Fragen nicht
beantworten kann.
Ist das ein Retransmit oder ein neu gestarteter Producer? Der
Sequenz-Zähler liegt im Speicher, also nummeriert ein neu gestarteter Producer
wieder ab 1, während producerId unverändert bleibt. Ein Consumer, der nur an
producerId festmacht, würde das ganze Präfix nach dem Restart als schon
behandelte Sequenznummern sehen, es als Duplikate absorbieren und — weil ein
absorbiertes Delivery trotzdem bestätigt wird — jede einzelne Nachricht als
erfolgreich zugestellt zurückmelden. Der Consumer macht stattdessen an
(producerId, incarnation) fest, also eröffnet eine neue Inkarnation ein
frisches Dedup-Fenster und ihre Nachrichten erreichen den Handler.
Kam dieses Acknowledgment von einem echten Delivery? producerId und
seq sind beide erratbar, ein dreifeldriges Ack ließe sich also von allem
fabrizieren, das den Producer adressieren kann — es würde den Retransmit
abbrechen und dein confirm mit Erfolg auslösen. Das Inkarnations-Token
verlässt den Producer nur auf Deliveries, die er tatsächlich gesendet hat; es
zurückzuspiegeln ist damit der Nachweis, den der Producer verlangt.
Ein Ack mit der falschen Inkarnation — gefälscht oder ein Nachläufer der
vorherigen Inkarnation derselben producerId — wird ignoriert.
Was ein verlorener Producer kostet, hängt davon ab, wie er verloren ging:
- Der Actor schlägt fehl und sein Supervisor startet ihn neu. Jeder
Send in Flight und jeder noch eingereihte Send wird mit
Error('producer stopped')abgeschlossen, und die neue Inkarnation nummeriert ab Seq 1 — der Consumer behandelt, was sie sendet, also als neu und nicht als Duplikat. Einconfirm-Callback, der wirft, ist kein solcher Fehlschlag; der Producer fängt ihn ab (siehe Backpressure). - Der Prozess stirbt. Nichts wird abgeschlossen, und jeder Send, der noch nicht bestätigt war, ist mit ihm verloren.
Es gibt noch keine durable Producer-Queue
Abschnitt betitelt „Es gibt noch keine durable Producer-Queue“ProducerController hält sein Fenster und seine Warteschlange im Speicher
und nirgends sonst. Nichts darin persistiert einen Send, baut beim
Recovery einen Buffer wieder auf oder setzt eine Sequenz fort — das Framework
hat heute keine durable Producer-Queue, und
#460 verfolgt, eine zu
bauen. Bis sie da ist, ist ein durabler Producer ein
PersistentActor-Wrapper, den du baust, um den confirm-Callback herum:
- Persistiere jeden Body, bevor du ihn dem Producer übergibst.
- Persistiere, dass er erledigt ist, sobald sein
confirmmitnullfeuert. - Übergib beim Recovery jeden Body, der nicht als erledigt markiert ist, erneut dem Producer.
Der Producer kann nicht dort weitermachen, wo der verlorene aufgehört hat. Er beginnt bei Seq 1 unter einer neuen Inkarnation, also empfängt der Consumer die erneut gesendeten Bodies als neue Nachrichten — und ein Body, dessen ACK zusammen mit dem alten Producer verloren ging, erreicht den Handler ein zweites Mal. Das ist at-least-once, und die Idempotenz des Handlers selbst muss es abfangen (siehe at-least-once vs. effectively-once im Überblick). Für einen ephemeren Stream ist der In-Memory-Producer alles, was du brauchst.
Mehrere Consumer
Abschnitt betitelt „Mehrere Consumer“Ein ProducerController stellt an genau einen Consumer zu. Um mehrere zu
versorgen, betreibe einen Producer pro Consumer, jeden mit seiner eigenen
producerId, und lass deinen Code wählen, zu welchem Stream eine Nachricht
gehört:
import { ProducerControllerOptions, ReliableDelivery } from 'actor-ts/delivery';
const euConsumer = ReliableDelivery.consumer<OrderEvent>(system, { handler: shipFromEu });const usConsumer = ReliableDelivery.consumer<OrderEvent>(system, { handler: shipFromUs });
const euProducerOptions = ProducerControllerOptions.create<OrderEvent>() .withProducerId('orders-eu') .withConsumer(euConsumer.ref);const euProducer = ReliableDelivery.producer<OrderEvent>(system, euProducerOptions);
const usProducerOptions = ProducerControllerOptions.create<OrderEvent>() .withProducerId('orders-us') .withConsumer(usConsumer.ref);const usProducer = ReliableDelivery.producer<OrderEvent>(system, usProducerOptions);
const producerFor = (order: OrderEvent) => (order.region === 'eu' ? euProducer : usProducer);producerFor(order).tell(order);Jeder Producer ist sein eigener (producerId, incarnation)-Stream mit
eigenen Sequenznummern, also sieht jeder Consumer eine lückenlose Folge. Über
ReliableDelivery.producer gebaut, beziehen beide ihr Tuning außerdem aus
actor-ts.reliable-delivery.producer (siehe Aus HOCON) — ein Controller,
den du selbst konstruierst und spawnst, tut das nicht.
Der Stream eines Producers lässt sich nicht auf mehrere Consumer
aufteilen — nicht durch einen Router davor und durch nichts anderes. Ein
Consumer schlüsselt sein Fenster auf den Stream und rückt nur über eine
lückenlose Folge von Sequenznummern vor; einer, der nur jede zweite Sequenz
bekommt, sieht seine Lücken also nie geschlossen: er behandelt maxOutOfOrder
Sequenzen oberhalb der ersten Lücke, verweigert den Rest ohne ACK, und der
Producer bleibt auf Retransmits stehen, die ihrerseits verweigert werden.
Wähle den Stream vor dem Producer, wie oben, nie danach.
Jede Nachricht an den Consumer zu geben, der gerade Kapazität hat — Work-Pulling —, braucht ein Demand-Signal der Consumer, das dieses Protokoll nicht hat; #1470 verfolgt das.
Cluster-aware
Abschnitt betitelt „Cluster-aware“Ein Consumer auf einem anderen Cluster-Node ist erreichbar, wenn beide
Controller solche sind, die du selbst unter /user spawnst. Deliveries und
ACKs laufen dann über den Cluster-Transport, und Retransmission funktioniert
wie in einem Prozess. Mit eingeschaltetem actor-ts.remote.untrusted-mode
müssen beide Pfade außerdem in trusted-selection-paths stehen (siehe
Cluster-Sicherheit).
Die ReliableDelivery-Fassade spawnt ihre Controller unter
/system/delivery/, und ein Node verweigert jeden /system-Pfad, der von
einem anderen Node kommt. Ein Fassaden-Consumer ist über Nodes hinweg also
nicht erreichbar, und ein Fassaden-Producer ebenso wenig, denn seine ACKs
kommen ebenfalls an einen /system-Pfad zurück. Auf einen Consumer auf einem
anderen Node gerichtet, bringt ein Fassaden-Producer entweder nichts durch,
oder seine Nachricht wird behandelt, ohne dass er je davon hört. So oder so
retransmittiert er, solange er läuft, und confirm feuert nie; die
Verweigerung zeigt sich nur auf dem Node, der verweigert hat, als gedrosselte
refused … inbound envelope frame(s)-Warnung und in
cluster_envelope_refusals_total{reason="system-path"}. Halte ein
Fassaden-Paar auf einem Node.
Controller, die du selbst spawnst, liegen außerhalb der
Konfigurationsschicht der Fassade: sie laufen mit ihren eingebauten Defaults,
solange du keine expliziten Optionen übergibst, denn nur die Fassade liest
actor-ts.reliable-delivery (siehe Aus HOCON).
Wo er auch läuft, hält der Producer sein Fenster und seine Warteschlange im Speicher auf seinem eigenen Node — stirbt dieser Node, stirbt mit ihm jeder Send, den er noch nicht bestätigt hatte (siehe Es gibt noch keine durable Producer-Queue).
Vergleich mit rohem tell
Abschnitt betitelt „Vergleich mit rohem tell“ref.tell(msg): ProducerController:- Keine Seq, kein ACK, kein Retransmit - Vertrag zuverlässige Zustellung- Verloren bei totem Empfänger - Übersteht transiente Fehler- Sub-Mikrosekunden-Kosten - ~50µs Overhead pro NachrichtNimm den Controller nur für Streams, in denen Verlust inakzeptabel
ist; rohes tell für alles andere.
Wohin als Nächstes
Abschnitt betitelt „Wohin als Nächstes“- Delivery im Überblick — das Gesamtbild.
- ConsumerController — die Empfänger-Seite.
- ACK-Semantik — wann ACKs feuern und was sie bedeuten.
- PersistentActor — für durable Producer-State.
