Durable subscriptions
Durable subscriptions provide at-least-once delivery with an explicit ack/nack checkpoint stored under the server data directory.
- One
subscription_idowns a stream filter, start position, and checkpoint consumer_namelabels the logical consumer/group identity- Pull claims matching events exclusively until ack or nack
- Checkpoint advances over a contiguous prefix of acknowledged positions
Competing consumers
Section titled “Competing consumers”Multiple clients may call PullEvents on the same subscription_id concurrently.
Semantics:
- Each matching event is claimed by at most one in-flight pull (exclusive lease)
- In-flight claims are bounded by
MaxInFlight(server config) - Ack may complete out of order; the durable checkpoint only moves forward through contiguous completed claims
- Nack releases the claim for redelivery and increments the subscription retry counter
- After
MaxRetryCountnacks the subscription becomes poisoned and the event is recorded as a dead letter
This is competing consumers on one subscription (scale one handler).
Fan-out consumer groups
Section titled “Fan-out consumer groups”Partition workload across members: each event is delivered to one member where global_position % N == member_index.
./bin/chronacta consumer-group create -id workers -stream orders./bin/chronacta consumer-group join -id workers -member node-a./bin/chronacta consumer-group join -id workers -member node-bSee Consumer groups.
Transient catch-up mode
Section titled “Transient catch-up mode”When a subscriber is slower than live delivery, the server switches to catch-up mode instead of disconnecting immediately (ErrSlowSubscriber). Disable catch-up entirely with CHRONACTA_SUBSCRIPTION_CATCHUP_MODE=false.
Catch-up is bounded by CHRONACTA_SUBSCRIPTION_MAX_CATCHUP_QUEUE (default 65536 positions). If the queue fills because the client stays behind, the server disconnects with ErrSlowSubscriber so memory cannot grow without bound.
Dead-letter lists are capped by CHRONACTA_SUBSCRIPTION_MAX_DEAD_LETTERS (default 1000); oldest entries are dropped first.
Use pkg/client/resilience SubscribeLive for auto-resubscribe after server restarts.
| Env | Default | Effect |
|---|---|---|
CHRONACTA_SUBSCRIPTION_CATCHUP_MODE |
true |
Live-buffer overflow → catch-up instead of immediate disconnect |
CHRONACTA_SUBSCRIPTION_MAX_CATCHUP_QUEUE |
65536 |
Max queued catch-up positions; overflow → ErrSlowSubscriber |
CHRONACTA_SUBSCRIPTION_MAX_DEAD_LETTERS |
1000 |
Cap persisted dead letters (ring; oldest dropped) |
Client flow
Section titled “Client flow”CreateSubscription(id, stream, consumer, start)loop: events = PullEvents(id, max=1..N) process events Ack(id, position) or Nack(id, position, reason)Use Pause / Resume / Replay for operational control. Inspect dead letters after poison.

