Durable subscriptions

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

Model

• 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

Competing consumers

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

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-b

See Consumer groups.

Transient catch-up mode

When a subscriber is slower than live delivery, the server switches to catch-up mode instead of disconnecting (ErrSlowSubscriber). Disable legacy behavior with CHRONACTA_SUBSCRIPTION_CATCHUP_MODE=false.

Use pkg/client/resilience SubscribeLive for auto-resubscribe after server restarts.

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.