Zum Inhalt springen
Deutsch

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 resendTimeout kein ACK kommt.
type ProducerControllerOptionsType<T> = {
consumer: ActorRef<Delivery<T>>;
resendTimeout?: number; // Default 500
windowSize?: number; // Default 16
producerId?: string; // wird zufällig generiert, wenn weggelassen
};
FeldZweck
consumerDie ConsumerController-Ref, an die zugestellt wird.
resendTimeoutWie lange auf ein ACK gewartet wird, bevor retransmittiert wird.
windowSizeFlow-Control-Window — pausiert das Queuing nach N unbestätigten In-Flight-Nachrichten.
producerIdStabiler 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.

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.

windowSize: 16

Der 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.

Wenn ein ACK nicht binnen resendTimeout eintrifft:

Seq 5 zum Zeitpunkt t=0 gesendet
ACK für Seq 5 kommt nie
bei t=500 → Seq 5 retransmitten
bei t=1000 → Seq 5 retransmitten
... bis das ACK kommt oder der Producer stoppt

Retransmits 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).

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. Ein confirm-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.

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:

  1. Persistiere jeden Body, bevor du ihn dem Producer übergibst.
  2. Persistiere, dass er erledigt ist, sobald sein confirm mit null feuert.
  3. Ü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.

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.

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).

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 Nachricht

Nimm den Controller nur für Streams, in denen Verlust inakzeptabel ist; rohes tell für alles andere.