Aller au contenu
Français

ProducerController

Ce contenu n’est pas encore disponible dans votre langue.

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.
type ProducerControllerOptionsType<T> = {
consumer: ActorRef<Delivery<T>>;
resendTimeout?: number; // default 500
windowSize?: number; // default 16
producerId?: string; // randomly generated if omitted
};
FieldPurpose
consumerThe ConsumerController ref to deliver to.
resendTimeoutHow long to wait for an ack before retransmitting.
windowSizeFlow-control window — pauses queueing after N unacked messages in flight.
producerIdStable 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.

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.

windowSize: 16

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

When an ack doesn’t arrive within resendTimeout:

seq 5 sent at t=0
seq 5 ack never arrives
at t=500 → retransmit seq 5
at t=1000 → retransmit seq 5
... until ack arrives or producer stops

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

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. A confirm callback 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.

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:

  1. Persist each body before handing it to the producer.
  2. Persist that it is done when its confirm fires with null.
  3. 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.

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.

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

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 overhead

Use the controller only for streams where loss is unacceptable; raw tell for everything else.