Ir al contenido
Español

Delivery overview

Esta página aún no está disponible en tu idioma.

By default, tell is fire-and-forget. Messages may be lost (stopped recipient, mailbox overflow, network drops in cluster setups). For workloads where loss is unacceptable, the framework provides reliable delivery via the ProducerController / ConsumerController pair.

ConsumerControllerProducerControllerConsumerControllerProducerControllerbuffer + dispatch to handler...msgackmsg

Adds sequence numbers + acks to the basic tell contract. Producer holds unacked messages; consumer dedups by seq.

For workloads where:

  • Loss is unacceptable — payment instructions, audit records, billing events.
  • Duplicates are tolerable but rare — at-least-once with consumer-side dedup is fine.
  • Order matters within a stream — sequence numbers preserve.

For workloads where loss is acceptable (telemetry, metrics, fire-and-forget UX updates), use plain tell.

The framework’s reliable delivery is at-least-once by default — a message may reach the handler more than once, for instance when the consumer restarts after handling it but before the producer has its ack: the producer retransmits, and the restarted consumer has no dedup state left to recognise it by.

For effectively-once, the controller already dedupes incoming duplicates per (producerId, producer incarnation, seq) — but only within its in-memory lifetime, and only within one incarnation of the producer. If you need dedup that survives either side restarting, persist your own processed-seq alongside the business state in the handler:

new ConsumerController<DeliveryMessage>({
handler: async (body) => {
if (await alreadyProcessed(body.id)) return; // your idempotency check
await this.handle(body);
await markProcessed(body.id);
},
});

The controller’s in-memory dedup handles the common retransmit-before-ack case; your handler’s persisted dedup handles consumer crashes mid-processing. Together they give effectively-once in the durable sense.

ControllerRole
ProducerControllerWraps the sender side — assigns sequence numbers, holds unacked messages, retransmits.
ConsumerControllerWraps the receiver side — orders messages by seq, dedupes, sends acks.

Pair them via a producer-consumer link — each producer talks to exactly one consumer, and one stream never spans two consumers. To feed N consumers, run N producers; Multiple consumers on the ProducerController page shows how, and why a router splitting one stream stalls.

import { ProducerControllerOptions, ReliableDelivery } from 'actor-ts/delivery';
// Consumer side — handler function, auto-ack on resolve:
const consumer = ReliableDelivery.consumer<OrderEvent>(system, {
handler: async (order) => {
await processOrder(order);
},
});
// Producer side — wraps outgoing messages in seq + ack tracking:
const producerControllerOptions = ProducerControllerOptions.create<OrderEvent>()
.withProducerId('order-producer-1')
.withConsumer(consumer.ref)
.withWindowSize(16);
const producer = ReliableDelivery.producer<OrderEvent>(system, producerControllerOptions);
producer.tell({ orderId: 'o-1', amount: 100 });

The framework handles seq assignment, retransmission, ordering — your code handles the business logic + dedup.

ReliableDelivery spawns both controllers and layers actor-ts.reliable-delivery under the options you pass, which is why it is the path to reach for. Construct a ProducerController / ConsumerController yourself and hand it to system.spawn only when the pair has to span cluster nodes — the facade’s controllers live under /system, which another node cannot address — and pass every tunable explicitly there, because that path reads no configuration (see Cluster-aware on the ProducerController page).

Each producer assigns strictly increasing seq numbers, starting at 1:
msg 1, msg 2, msg 3, ...
The consumer sees them IN ORDER (after retransmissions sort out):
msg 1, msg 2, msg 3, ...
Duplicates (due to retransmit) appear with the SAME seq:
msg 1, msg 1 (dup), msg 2, ...
→ consumer dedupes by seq

The seq is per-producer — multiple producers have independent seq spaces.

For durability across producer and consumer crashes both sides persist, and both halves are code you write — the framework has no durable producer queue yet (#460):

  • Producer side — persist each body before handing it to the producer, mark it done when its confirm fires with null, and on recovery send again whatever is not marked done. The producer starts over at seq 1 under a new incarnation, so those bodies arrive as new messages, not as retransmits.
  • Consumer side — in the handler, persist the id of each body it processed alongside the business state, and skip a body whose id is already there.

Together they give end-to-end effectively-once: a producer that crashes mid-send loses nothing it had not confirmed, and a consumer that crashes mid-process skips what it had already done, whether that comes back as a retransmit or as a re-send. The id has to travel in the body — a re-sent body gets a new sequence number, so the sequence number cannot recognise it.

Without persistence, recovery resets to zero on both sides — the producer forgets unconfirmed sends and the consumer’s in-memory dedup is gone.

Producer/ConsumerController: in-cluster reliable delivery
Kafka / RabbitMQ / NATS: external broker-mediated delivery

Both achieve at-least-once + dedup-via-seq. Differences:

AspectIn-cluster controllersExternal broker
Operational complexityLow — part of the clusterHigh — separate broker to run
LatencySub-millisecondNetwork + broker overhead
ThroughputBounded by single-actor processingHigher (broker scales independently)
External consumersNo (cluster-internal)Yes
PersistenceVia PersistentActorBuilt into broker

For cluster-internal reliable delivery, use the controllers. For external systems or cross-cluster, use a broker (Kafka, etc.).