跳转到内容
简体中文

Ack semantics

此内容尚不支持你的语言。

The ack is the core primitive of reliable delivery — the producer releases buffered messages once acked. The controller manages ack timing for you; how the handler resolves controls whether the ack fires.

1. ConsumerController admits the Delivery envelope
→ malformed (no replyTo, bad seq, over-long ids) → dead letter, no handler
2. Controller checks dedup state for (producerId, incarnation)
→ known seq → re-ack only, skip handler
→ new seq → call handler(body), wait for resolution
3. Handler resolves → controller sends Ack to msg.replyTo,
echoing the delivery's incarnation
Handler throws → controller does NOT ack
4. Producer checks the Ack echoes its own incarnation
→ mismatch → ignored, the retransmit timer stands
→ match → removes seq from its in-flight buffer
→ frees a window slot for the next send

The handler is the only user-facing knob. Whatever happens inside handler(body) is your code; whatever happens around it (dedup, ack, replyTo wiring, retransmit timing) is the controller’s job.

PatternHandler shapeGuarantee
Resolve on success (default)Handler does the work, returns void or resolved PromiseAt-least-once with in-memory dedup
Throw on failureHandler throws / rejects when processing failed → controller skips ack → producer resendsAt-least-once with retry
Persist before resolveHandler awaits a journal write before returningEffectively-once across consumer restart
new ConsumerController<T>({
handler: async (body) => {
await this.processIdempotently(body); // ack-on-resolve
},
});
1. Handler starts processing (body)
2. Handler completes (resolves)
3. Controller serialises an Ack envelope
4. Controller tells the producer's replyTo ref
5. Producer removes msg from unacked buffer

If the consumer crashes between 2 and 4, the ack never reaches the producer. Producer retransmits after resendTimeout. The controller’s in-memory dedup is gone after the crash, so the same seq runs the handler again — make it idempotent, or persist processed-seq alongside business state.

For effectively-once processing of side effects, await the journal write inside the handler. When handler(body) resolves, both your event AND the implicit “processed this seq” marker are durable; the controller’s subsequent Ack just tells the producer it can free its slot.

class PersistentEventLog extends PersistentActor<Command, Event, State> {
// …onCommand / onEvent omitted…
}
const log = system.spawnAnonymous(PersistentEventLog);
const consumer = system.spawn(
() => new ConsumerController<OrderEvent>({
handler: async (order) => {
// ask() resolves once the PersistentActor has journalled
// the event. If the consumer crashes before this resolves,
// the producer will retransmit and the handler runs again —
// but the PersistentActor's own dedup (event-id or seq in
// event payload) handles the rerun.
await log.ask({ kind: 'append', order }, 30_000);
},
}),
);

The sequence on a clean run:

  1. Delivery arrives.
  2. Controller calls handler(body).
  3. Handler asks the journal, the journal writes, the ask resolves.
  4. Controller sends Ack → producer frees its slot.

On crash between step 2’s start and step 3’s resolve:

  • Before the journal write commits: producer retransmits; the handler runs again; the journal-side dedup catches it. Net: zero duplication.
  • After the journal write commits, before the controller’s Ack reaches the producer: producer retransmits; the handler runs again; the journal-side dedup short-circuits and the controller re-acks immediately. Net: zero duplication.

For end-to-end durability the producer side has to persist too, and that half is yours to build: the framework has no durable producer queue yet (#460). There is no durable producer queue yet on the ProducerController page describes the wrapper and what it can and cannot promise.

Producer sends msg #5 → crash before transmit completes

Recovery: producer restarts — and msg #5 is not sent again by anything in the framework, because the producer keeps no journal of unacknowledged sends. A supervised restart settles it with Error('producer stopped') through its confirm, which is how your code learns what to send again; a process that dies takes it along unsettled. A producer that survives either is a PersistentActor wrapper you build until #460 ships one — see There is no durable producer queue yet on the ProducerController page.

Everything the restarted producer sends after that lands normally. The restart mints a new producer incarnation, so the consumer opens a fresh dedup window instead of treating the re-used sequence numbers as duplicates it has already handled — see Restart and the producer incarnation on the ProducerController page.

Consumer receives msg → crashes before handler runs

No ack sent; producer retransmits. Idempotent handler dedupes (or processes for the first time).

Producer sends msg #5
Consumer processes msg #5
Consumer sends ack #5
Network drops the ack envelope

Producer retransmits msg #5 after timeout. Consumer dedupes (highWatermark already at 5); re-acks.

The dedup + re-ack pattern means transient acks are recoverable — eventually one arrives.

Producer.windowSize = 16
Consumer takes 10s per message

Backpressure: after 16 unacked messages are in flight, the producer stops sending further messages until an Ack frees a slot. Incoming { kind: 'reliable-delivery.send' } tells queue inside the producer until the window opens.

This is good — the system can’t get further ahead of itself than the flow-control window.

Consumer on node-A processes msg #5; controller queues the Ack
Node-A crashes before the Ack tell completes

Producer doesn’t see Ack within resendTimeout → retransmits.

If the consumer is sharded (the entity moves during failover), the new instance:

  • Receives the retransmit.
  • Has empty in-memory dedup state (fresh ConsumerController).
  • Calls the handler — which must persist its own processed-seq for effectively-once.

For sharded consumers, always pair the handler with persistence — otherwise the controller’s dedup resets on every rebalance and you get full reprocessing.

The Ack is fire-and-forget from the controller to the producer’s replyTo. The controller doesn’t await its delivery — if the network drops the Ack, the producer retransmits after resendTimeout and the controller’s dedup re-acks immediately.

This means: your handler doesn’t pay any latency cost for the Ack. The controller emits the Ack after handler(body) resolves and moves on.

The consumer handler decides whether the Ack fires; the producer’s confirm callback is how your own code observes it landing. Reach for the ergonomic ReliableDelivery facade: ReliableDelivery.producer returns a ProducerHandle whose tell(body, confirm?) takes an optional ConfirmationCallback — (err: Error | null) => void.

const consumer = ReliableDelivery.consumer<OrderEvent>(system, {
handler: async (order) => {
await save(order);
},
});
const producerOptions = ProducerControllerOptions.create<OrderEvent>().withConsumer(consumer.ref);
const producer = ReliableDelivery.producer<OrderEvent>(system, producerOptions);
producer.tell(order, (err) => {
// err === null → the consumer Acked this seq; the slot is freed
// err !== null → the producer was stopped before the Ack arrived
});

confirm(null) fires exactly once — after the consumer’s Ack reaches the producer and the in-flight slot is freed. A redelivered (duplicate) Ack for the same seq is ignored, so the callback never double-fires. This is the only producer-side signal that a message landed; without it the send is fire-and-forget from your code’s point of view.

The signal is only as good as the Ack behind it, which is why the producer requires the Ack to echo its own incarnation token before acting on it. seq counts up from 1 and producerId is usually a name your own code chose, so neither is hard to guess; the incarnation is, and it leaves the producer only on deliveries it actually sent. Without that check, anything able to address the producer could cancel the retransmit and fire confirm(null) for a message the consumer had never seen — downgrading the stream to at-most-once while reporting success. Note what the signal still does not promise: it says the consumer accepted responsibility for the seq, so for a redelivery it means the handler ran on an earlier attempt, not on this one.

The token’s scope is one producer, not one message. It is minted once per ProducerController construction and stamped on every delivery that incarnation sends, so anything that legitimately receives one delivery — your consumer, a handler that forwards it on, a router fan-out — can settle every other in-flight seq of that producer, for as long as the actor lives. That is deliberate rather than an oversight: the party holding a delivery is the one expected to acknowledge it, and without a delivery it has no replyTo to reach the producer with in the first place. It is also what keeps the consumer’s dedup key stable, since that key is (producerId, incarnation) and a per-message token would reset the window on every sequence. What it does not give you is a capability you can hand out per message: forwarding one delivery to a component you trust less hands it the whole producer.

The check sits on the producer because that is the only side with something unguessable to check against. The consumer Acks to the replyTo on the envelope and cannot do better: a Delivery arrives with no sender attached — a producer tells with one argument, and so does the cluster’s envelope dispatch — so there is no authenticated identity to hold replyTo up against, and every other field on the envelope was written by whoever sent it.

How much rides on that is not settled here. An ActorRef does cross the cluster wire: a replyTo in a delivery travels as an address marker, and the receiving node decodes it back into a live ref — a local actor when the marker names that node, a remote one otherwise. So a peer able to send to a consumer under /user can point the Ack at an actor of its own choosing, one on the consumer’s node included, and resolving a marker that names that node consults none of the trust checks an envelope’s own target goes through. What arrives there is one Acknowledgment per delivery, carrying four fields the peer wrote itself, and a real producer at that address discards it, because the incarnation does not match. Whether a ref from the wire should resolve to any actor at all is a question for the ref decoder rather than for this protocol; #1572 tracks it.