spate_coordination/lib.rs
1//! Distributed work coordination for Spate sources.
2//!
3//! A leader-elected worker runs the source's
4//! [`SplitPlanner`](spate_core::coordination::SplitPlanner) to enumerate
5//! weighted work *splits* into a shared low-latency store, and publishes a
6//! desired assignment per instance; every worker leases the splits it was
7//! named for, heartbeats them, and cooperatively drains the ones it was
8//! not. Progress commits
9//! are epoch-fenced compare-and-swap writes on the durable split record: a
10//! fenced commit writes **nothing**, and committed progress can only
11//! replay, never regress (at-least-once — duplicates possible, loss never).
12//!
13//! This crate implements the `spate_core::coordination` seam (re-exported
14//! here) over the public [`store::CoordinationStore`] trait:
15//!
16//! - [`store::memory::MemoryStore`] — in-process, for tests and
17//! single-machine embedding.
18//! - A NATS JetStream KV store (default `nats` feature, server >= 2.11) —
19//! the production backend.
20//!
21//! Custom backends (Redis, etcd) implement the store trait; the protocol,
22//! fencing, election, and work assignment live above it and are shared.
23
24pub use spate_core::coordination::*;
25
26pub mod config;
27pub mod store;
28
29// Time seam behind every deadline in the control loop: `SystemClock` in
30// production, a clock the test advances in tests. `#[doc(hidden)]` hides the
31// *module path* only — `Clock`, `SystemClock` and `Sleep` are re-exported
32// below without it, so the trait is public, documented, semver-stable
33// surface. Adding a required method to it is a breaking change.
34#[doc(hidden)]
35pub mod clock;
36mod coordinator;
37mod error;
38mod leader;
39mod protocol;
40mod records;
41mod task;
42
43// `Sleep` is the return type of a required `Clock` method, so an external
44// implementor has to be able to name it.
45pub use clock::{Clock, Sleep, SystemClock};
46pub use config::CoordinationConfig;
47pub use coordinator::StoreCoordinator;
48
49/// [`StoreCoordinator`] over the in-memory store: tests and
50/// single-process embedding.
51pub type MemoryCoordinator = StoreCoordinator<store::memory::MemoryStore>;
52
53/// [`StoreCoordinator`] over NATS JetStream KV: the production backend
54/// (server >= 2.11). Build the store with
55/// [`NatsStore::new`](store::nats::NatsStore::new) — construction is
56/// synchronous; the connection is made lazily under the startup budget.
57#[cfg(feature = "nats")]
58pub type NatsCoordinator = StoreCoordinator<store::nats::NatsStore>;