meshery / meshery/meshsync

MeshSync: durable delivery via NATS JetStream (design)

Open
#580 1 comment 0 reactions 0 assignees View on GitHub
kind/feature language/go
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.