ProducerController
Esta página aún no está disponible en tu idioma.
ProducerController wraps a sender’s outgoing messages,
assigning sequence numbers + holding them until acked by
the consumer.
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 spawns the controller and layers
actor-ts.reliable-delivery.producer under the options (see From HOCON).
Construct a ProducerController yourself and hand it to system.spawn only
for a pair that spans cluster nodes, which the facade’s controllers cannot (see
Cluster-aware).
Internally:
- Assigns seq 1 to the first message, 2 to the next, …
- Sends each via wrapped tell to the consumer.
- Holds in a buffer until acked.
- Retransmits if no ack within
resendTimeout.
Configuration
Section titled “Configuration”type ProducerControllerOptionsType<T> = { consumer: ActorRef<Delivery<T>>; resendTimeout?: number; // default 500 windowSize?: number; // default 16 producerId?: string; // randomly generated if omitted};| Field | Purpose |
|---|---|
consumer | The ConsumerController ref to deliver to. |
resendTimeout | How long to wait for an ack before retransmitting. |
windowSize | Flow-control window — pauses queueing after N unacked messages in flight. |
producerId | Stable identifier the consumer keys its dedup state on. Randomly generated if omitted; pin it when you want one identity across restarts in logs, metrics and the consumer’s map. It does not carry a dedup window across a restart — see Restart and the producer incarnation. |
From HOCON
Section titled “From HOCON”resendTimeout and windowSize also read from
actor-ts.reliable-delivery.producer,
in the project’s usual order: explicit options beat HOCON, and HOCON beats
the built-in defaults (500 ms and 16).
actor-ts.reliable-delivery.producer { resend-timeout = 2s window-size = 64}consumer and producerId have no key, for two different reasons: an actor
reference is not something HOCON can express, and one shared producerId
across every producer in a process is a correctness bug rather than a setting —
the consumer keys its dedup state on it, so two producers sharing an id reset
each other’s window.
The layering happens in ReliableDelivery.producer(...), so that is the only
path that sees it. A ProducerController you construct yourself and hand to
system.spawn keeps its built-in defaults: neither controller can read
configuration in its constructor, because system is a getter over a context
the cell injects after construction.
A generated producerId is random, not sequential. It used to be a module
counter — producer-1, producer-2, … — which was wrong twice over. An
Acknowledgment names a producerId and a seq, and the seq is a small
integer by construction, so a counter left neither half of that pair to guess.
The counter was also shared: two processes running the same service each minted
producer-1, stamped one identity onto their deliveries, and then kept
resetting each other’s dedup window at a consumer they had in common. The
framework now draws 16 hex characters instead.
That id is minted fresh on every construction, so leaving producerId unset
means there is no identity to be stable about — set it yourself whenever
something downstream is supposed to recognise this producer after a restart.
Backpressure
Section titled “Backpressure”windowSize: 16The producer holds up to 16 unacked messages in flight. Beyond that,
incoming { kind: 'reliable-delivery.send' } messages are queued — the
caller’s tell succeeds, but actual sending pauses until the
consumer’s acks free up the buffer.
There is no signal back to the caller when this queueing happens: a
reliable-delivery.send is fire-and-forget — the producer never replies
to it, so there is no ask-based “I sent it” acknowledgment to await.
For senders that need to know a message got through, pass a confirm
callback as tell’s second argument. It fires once the consumer acks that
message — with null on success, or an Error if the producer stops before
the ack arrives:
producer.tell({ orderId: 'o-1' }, (err) => { if (err) console.error('delivery failed', err); else console.log('delivered and acked');});To turn that into real backpressure, pace your sends against these confirmations — hold off on the next batch until earlier messages confirm.
A callback that throws stops at the producer. confirm runs on the
producer’s own turn, and a throw from it is caught there and logged at
error level, naming the producer and the message — by its seq, or as still
queued — along with what was thrown. Nothing else changes: the producer is
not restarted, a message whose callback threw on its ack still counts as
delivered, queued sends keep moving into the window, and a stopping producer
still settles every other send. The callback may be async as well: the
promise it returns is not awaited, and its rejection is logged the same way
instead of surfacing as an unhandled rejection, which would end the process.
That holds whatever the value: when the logger cannot render it — an error
whose message getter throws, say, or a revoked proxy — the line is written
without it.
Retransmission
Section titled “Retransmission”When an ack doesn’t arrive within resendTimeout:
seq 5 sent at t=0seq 5 ack never arrivesat t=500 → retransmit seq 5at t=1000 → retransmit seq 5... until ack arrives or producer stopsRetransmits use the same seq as the original, and carry the same producer incarnation, so the consumer recognises them as the same message.
A retransmit the consumer refuses — its tell throws, as a bounded mailbox
with the reject overflow policy does — is logged as a warning naming the
seq, and sent again after the next resendTimeout. A refused first
transmission is different: it happens on the producer’s own turn and faults
it (see Restart and the producer incarnation).
Restart and the producer incarnation
Section titled “Restart and the producer incarnation”Every construction of a ProducerController mints a fresh, unguessable
incarnation token and stamps it onto each Delivery. Nothing configures
it; it exists because producerId alone cannot answer two questions.
Is this a retransmit or a restarted producer? The sequence counter is
in-memory, so a restarted producer numbers from 1 again while producerId
stays as configured. A consumer keyed on producerId alone would see the
whole post-restart prefix as sequence numbers it had already handled, absorb
them as duplicates, and — because an absorbed delivery is still acked — report
each one back as successfully delivered. The consumer keys on (producerId, incarnation) instead, so a new incarnation starts a fresh dedup window and
its messages reach the handler.
Did this acknowledgment come from a real delivery? producerId and seq
are both guessable, so a three-field ack could be manufactured by anything able
to address the producer, cancelling its retransmit and firing your confirm
with success. The incarnation travels only on deliveries the producer actually
sent, so echoing it back is the evidence the producer requires.
An ack that names the wrong incarnation — forged, or a straggler from the
previous incarnation of the same producerId — is ignored.
What a lost producer costs depends on how it was lost:
- The actor faults and its supervisor restarts it. Every send in flight
and every send still queued is settled with
Error('producer stopped'), and the new incarnation numbers from seq 1 — so the consumer treats what it sends as new rather than as duplicates. Aconfirmcallback that throws is not such a fault; the producer contains it (see Backpressure). - The process dies. Nothing is settled, and every send that was not yet confirmed is gone with it.
There is no durable producer queue yet
Section titled “There is no durable producer queue yet”ProducerController keeps its window and its queue in memory and nowhere
else. Nothing in it persists a send, rebuilds a buffer on recovery or
resumes a sequence — the framework has no durable producer queue today, and
#460 tracks building one.
Until it ships, a durable producer is a PersistentActor wrapper you
build, around the confirm callback:
- Persist each body before handing it to the producer.
- Persist that it is done when its
confirmfires withnull. - On recovery, hand every body not marked done to the producer again.
The producer cannot pick up where the lost one stopped. It starts at seq 1 under a new incarnation, so the consumer receives the re-sent bodies as new messages — and a body whose acknowledgment was lost along with the old producer reaches the handler a second time. That is at-least-once, which the handler’s own idempotency has to absorb (see At-least-once vs effectively-once on the overview). For an ephemeral stream the in-memory producer is all you need.
Multiple consumers
Section titled “Multiple consumers”A ProducerController delivers to exactly one consumer. To feed several,
run one producer per consumer, each with its own producerId, and let
your code choose the stream a message belongs to:
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);Each producer is its own (producerId, incarnation) stream with its own
sequence numbers, so each consumer sees a gap-free sequence. Built through
ReliableDelivery.producer, both also take their tuning from
actor-ts.reliable-delivery.producer (see From HOCON), which a controller
you construct and spawn yourself does not.
One producer’s stream cannot be split across consumers — not by a router
in front of them, not by anything else. A consumer keys its window on the
stream and advances only over a gap-free run of sequence numbers, so one that
receives every other sequence never sees its gaps close: it handles
maxOutOfOrder sequences above the first gap, then refuses the rest without
acknowledging them, and the producer stalls on retransmits that are refused
in turn. Choose the stream before the producer, as above, never after it.
Handing each message to whichever consumer has capacity — work-pulling — needs a demand signal from the consumers that this protocol does not have; #1470 tracks it.
Cluster-aware
Section titled “Cluster-aware”A consumer on another cluster node is reachable when both controllers are
ones you spawn yourself under /user. Deliveries and acknowledgments then
cross the cluster transport, and retransmission works as it does in one
process. With actor-ts.remote.untrusted-mode on, both paths also have to be
listed in trusted-selection-paths (see
cluster security).
The ReliableDelivery facade spawns its controllers under
/system/delivery/, and a node refuses every /system path that arrives
from another node. So a facade consumer cannot be reached across nodes, and
neither can a facade producer, whose acknowledgments come back to a /system
path too. Aimed at a consumer on another node, a facade producer either gets
nothing through or gets its message handled and never hears back. Either way
it retransmits for as long as it runs and confirm never fires; the refusal
shows only on the node that refused, as a paced
refused … inbound envelope frame(s) warning and in
cluster_envelope_refusals_total{reason="system-path"}. Keep a facade pair
on one node.
Controllers you spawn yourself are outside the facade’s configuration layer:
they run on their built-in defaults unless you pass explicit options, because
only the facade reads actor-ts.reliable-delivery (see From HOCON).
Wherever it runs, the producer holds its window and its queue in memory on its own node — if that node dies, every send it had not confirmed dies with it (see There is no durable producer queue yet).
Comparison with raw tell
Section titled “Comparison with raw tell”ref.tell(msg): ProducerController:- No seq, no ack, no retransmit - Reliable delivery contract- Lost on dead recipient - Survives transient failures- Sub-microsecond cost - ~50µs per message overheadUse the controller only for streams where loss is unacceptable;
raw tell for everything else.
Where to next
Section titled “Where to next”- Delivery overview — the bigger picture.
- ConsumerController — the receiver side.
- Ack semantics — when acks fire and what they mean.
- PersistentActor — for durable producer state.
