MeshSync: durable delivery via NATS JetStream (design)
- Dominant language
- Go
- Stars
- 90
- Forks
- 96
- PR merge metrics
- No merged PRs in 30d
Description
## Summary
Make MeshSync -> Server delivery at-least-once and durable. Today MeshSync publishes to core NATS fire-and-forget; an event published while Meshery Server is disconnected is lost until a full re-list resync.
## Key decisions
- **Additive capability, not a competing interface**: optional `DurablePublisher`/`DurableSubscriber`/`Subscription` interfaces in MeshKit's broker, discovered via type assertion; core `Publish`/`Subscribe` stay unchanged for every existing consumer. Also closes the standing `broker.Handler` `Unsubscribe` gap (which the exec-subscription leak needs too).
- JetStream `MESHSYNC_EVENTS` stream (file storage, LimitsPolicy + DiscardOld) + one durable pull consumer per Server instance, named from `InstanceID` for resume-from-last-acked. Explicit ack after DB upsert; Nak on transient error; Term -> DLQ on poison messages.
- Idempotency key `ID|resourceVersion|eventType` (broker-side dedup) + consumer-side idempotent upsert (`ON CONFLICT DO UPDATE`), hardening today's accidental idempotency. At-least-once + idempotent consumer = net-effect-once (not protocol exactly-once).
- Operator: additive `BrokerSpec.JetStream`, aligning with the existing `broker-nats-direct-consumption` proposal.
## Rollout
Capability negotiation **is** the flag - dual-mode by design, no synchronized cutover. Complementary to periodic reconciliation (companion blueprint): JetStream covers Server-down; reconcile covers MeshSync-missed-watch-event.
## Full design
[docs/design/fd4-jetstream-durable-delivery.md](https://github.com/meshery/meshsync/blob/master/docs/design/fd4-jetstream-durable-delivery.md) (added in #576).
Contributor guide
Research direction
Start with docs/design/fd4-jetstream-durable-delivery.md, then compare its broker interfaces and rollout decisions with the broker-nats-direct-consumption proposal mentioned in the issue. Trace how MeshSync-to-Server delivery, acknowledgements, deduplication, and reconciliation fit together. Done means the design is validated and its required implementation work is clearly scoped.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- distributed-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100