Delivery overview
このコンテンツはまだ日本語訳がありません。
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.
Adds sequence numbers + acks to the basic tell
contract. Producer holds unacked messages; consumer dedups by
seq.
When to reach for this
Section titled “When to reach for this”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.
At-least-once vs effectively-once
Section titled “At-least-once vs effectively-once”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.
The two controllers
Section titled “The two controllers”| Controller | Role |
|---|---|
| ProducerController | Wraps the sender side — assigns sequence numbers, holds unacked messages, retransmits. |
| ConsumerController | Wraps 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.
A minimal example
Section titled “A minimal example”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).
Sequence-number semantics
Section titled “Sequence-number semantics”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 seqThe seq is per-producer — multiple producers have independent seq spaces.
Combining with persistence
Section titled “Combining with persistence”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
confirmfires withnull, 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.
Comparison with broker-based delivery
Section titled “Comparison with broker-based delivery”Producer/ConsumerController: in-cluster reliable deliveryKafka / RabbitMQ / NATS: external broker-mediated deliveryBoth achieve at-least-once + dedup-via-seq. Differences:
| Aspect | In-cluster controllers | External broker |
|---|---|---|
| Operational complexity | Low — part of the cluster | High — separate broker to run |
| Latency | Sub-millisecond | Network + broker overhead |
| Throughput | Bounded by single-actor processing | Higher (broker scales independently) |
| External consumers | No (cluster-internal) | Yes |
| Persistence | Via PersistentActor | Built into broker |
For cluster-internal reliable delivery, use the controllers. For external systems or cross-cluster, use a broker (Kafka, etc.).
Where to next
Section titled “Where to next”- Producer controller — sender-side details.
- Consumer controller — receiver-side details.
- Ack semantics — what acks mean and when they fire.
- PersistentActor — pairing with persistence for full durability.
