Skip to content

Durable subscriptions

Durable subscriptions provide at-least-once delivery with an explicit ack/nack checkpoint stored under the server data directory.

  • One subscription_id owns a stream filter, start position, and checkpoint
  • consumer_name labels the logical consumer/group identity
  • Pull claims matching events exclusively until ack or nack
  • Checkpoint advances over a contiguous prefix of acknowledged positions

Multiple clients may call PullEvents on the same subscription_id concurrently.

Semantics:

  1. Each matching event is claimed by at most one in-flight pull (exclusive lease)
  2. In-flight claims are bounded by MaxInFlight (server config)
  3. Ack may complete out of order; the durable checkpoint only moves forward through contiguous completed claims
  4. Nack releases the claim for redelivery and increments the subscription retry counter
  5. After MaxRetryCount nacks the subscription becomes poisoned and the event is recorded as a dead letter

This is competing consumers on one subscription (scale one handler).

Partition workload across members: each event is delivered to one member where global_position % N == member_index.

Terminal window
./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-b

See Consumer groups.

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