rustlavel_discovery/lib.rs
1//! rustlavel-discovery: a service registry, and the client that uses it.
2//!
3//! **Read this before reaching for it.** On Kubernetes, ECS or Nomad you do not
4//! need a registry: the platform already knows which instances are ready and
5//! already balances across them, and a registry there is a second copy of that
6//! fact which will eventually disagree with the first. Use
7//! [`Dns`](resolve::Dns). This crate is for the case the platforms do not
8//! cover — services on plain machines or across two clouds, or a Spring estate
9//! already speaking Eureka that a Rustlavel service has to join.
10//!
11//! Three answers to "where is this service" sit behind one trait, so moving
12//! between them is a line of configuration rather than a rewrite:
13//!
14//! - [`Static`](resolve::Static) — the list you wrote. Where everybody starts,
15//! and where a great many applications correctly stay.
16//! - [`Dns`](resolve::Dns) — a name the platform already resolves.
17//! - [`Discovery`](client::Discovery) — this registry, with a cache that
18//! outlives the registry being down.
19//!
20//! # Running a registry
21//!
22//! ```ignore
23//! App::new()
24//! .plugin(RegistryServer::new().peers(Peers::new(nodes).excluding(own_url)))
25//! .run()
26//! .await
27//! ```
28//!
29//! It speaks Eureka's wire format, so a Spring Cloud service registers against
30//! it with its stock configuration and nothing else changed.
31//!
32//! # Joining one
33//!
34//! ```ignore
35//! let registrar = Arc::new(Registrar::new(nodes, Instance::new("orders", host, port)));
36//! registrar.clone().start();
37//! ```
38//!
39//! # What this deliberately does not do
40//!
41//! The registry is in memory and there is no timer evicting anything. Both are
42//! on purpose. Persistence would buy nothing — every instance re-registers
43//! within a heartbeat of a restart, so the state rebuilds itself faster than it
44//! could be loaded, and a durable copy would only ever be *wrong* on the way
45//! back up. And staleness is decided by whoever reads, not by a sweep: it is
46//! what lets the registry notice that *most* of itself went quiet at once and
47//! conclude that the network broke rather than that the estate died. See
48//! [`registry`].
49
50pub mod client;
51pub mod eureka;
52#[cfg(feature = "gateway")]
53pub mod gateway;
54pub mod instance;
55pub mod registry;
56pub mod replicate;
57pub mod resolve;
58pub mod server;
59pub mod ui;
60
61pub use client::{Discovery, Registrar};
62#[cfg(feature = "gateway")]
63pub use gateway::Balancer;
64pub use instance::{Instance, Status};
65pub use registry::{Mode, Registry};
66pub use replicate::{Change, Peers};
67pub use resolve::{Balance, Dns, Resolve, RoundRobin, Static};
68pub use server::RegistryServer;