spate_coordination/lib.rs
1//! Distributed work coordination for Spate sources.
2//!
3//! A leader-elected worker runs the source's
4//! [`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 are epoch-fenced compare-and-swap writes on the
9//! durable split record. A fenced commit writes **nothing**, and committed
10//! progress can only replay, never regress. Delivery is at-least-once, so
11//! duplicates are possible and records are never lost.
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// The `testing` feature also carries `bench_seams`, which reaches the pure,
30// synchronous decisions an instruction-count bench cannot get to through an
31// async surface. The module is `#[doc(hidden)]`, so a link to it dangles on
32// docs.rs (where the feature is off) and renders as literal text in the
33// published API reference (where it is on).
34#[cfg(feature = "testing")]
35#[doc(hidden)]
36pub mod bench_seams;
37// Time seam behind every deadline in the control loop: `SystemClock` in
38// production, a clock the test advances in tests. `#[doc(hidden)]` hides the
39// *module path* only. `Clock`, `SystemClock` and `Sleep` are re-exported
40// below without it, so the trait is public, documented, semver-stable
41// surface. Adding a required method to it is a breaking change.
42#[doc(hidden)]
43pub mod clock;
44mod coordinator;
45mod error;
46mod leader;
47mod protocol;
48mod records;
49mod task;
50
51// `Sleep` is the return type of a required `Clock` method, so an external
52// implementor has to be able to name it.
53pub use clock::{Clock, Sleep, SystemClock};
54pub use config::CoordinationConfig;
55pub use coordinator::StoreCoordinator;
56
57/// [`StoreCoordinator`] over the in-memory store: tests and
58/// single-process embedding.
59pub type MemoryCoordinator = StoreCoordinator<store::memory::MemoryStore>;
60
61/// [`StoreCoordinator`] over NATS JetStream KV: the production backend
62/// (server >= 2.11). Build the store with
63/// [`NatsStore::new`](store::nats::NatsStore::new). Construction is
64/// synchronous; the connection is made lazily under the startup budget.
65#[cfg(feature = "nats")]
66pub type NatsCoordinator = StoreCoordinator<store::nats::NatsStore>;