Struct Etcd 

pub struct Etcd { /* private fields */ }

A key in etcd, as a configuration source.

Implementations

impl Etcd

pub async fn new<E, S>( endpoints: E, key: impl Into<String>, ) -> Result<Self, Error>

where E: IntoIterator<Item = S>, S: Into<String>,

Connects to endpoints and reads key.

The format is taken from the key’s extension — myapp/db.json is JSON. A key without one needs with_format.

Errors

If the endpoints cannot be parsed. Not if they are unreachable: the client connects lazily, so that surfaces on the first fetch.

pub async fn with_options<E, S>( endpoints: E, key: impl Into<String>, options: ConnectOptions, ) -> Result<Self, Error>

where E: IntoIterator<Item = S>, S: Into<String>,

As new, with etcd’s own connection options.

This is where authentication and TLS live, because that is where etcd-client puts them — there is no second vocabulary to learn, and options this crate has never heard of keep working.

let etcd = Etcd::with_options(
    ["https://etcd.internal:2379"],
    "myapp/db.json",
    ConnectOptions::new()
        .with_user("myapp", std::env::var("ETCD_PASSWORD").unwrap())
        .with_keep_alive(
            std::time::Duration::from_secs(30),
            std::time::Duration::from_secs(5),
        ),
)
.await?;

The credentials live in the client afterwards, which is what lets an expired auth token be replaced without rebuilding anything.

Errors

As new.

pub fn from_client(client: Client, key: impl Into<String>) -> Self

Uses a client the program already has.

For a caller that already talks to etcd and would rather not open a second connection to it. The client is Clone — cheaply, it is a handle — so sharing one costs nothing.

let etcd = Etcd::from_client(client, "myapp/db.json");

A shared client recovers from an expired auth token like any other: the credentials live in the client, so refreshing the token needs nothing this source would have to own.

pub fn with_format(self, format: Format) -> Self

States the format, for a key whose name does not.

pub async fn watch<F>(&self, on_change: F) -> Result<(), Error>

where F: FnMut(Fetched) -> Result<(), Error> + Send,

Calls on_change every time the key’s value moves, forever.

The first call happens when the first change arrives, not at startup: a watch reports changes, and reporting the current value as one would make every restart look like an edit. Fetch first if the starting value matters, which it usually does:

DbConfig::apply_remote(etcd.fetch().await?)?;
etcd.watch(DbConfig::apply_remote).await

Cancellation is dropping the future. There is no stop flag, because there is nothing to poll one between: this suspends on the stream, so any executor’s cancellation already ends it immediately.

A deletion is not a change this reports. The key holding no value is not a configuration, and calling back with the last one — or with nothing — would both be worse than leaving the running snapshot alone.

Errors

If the watch cannot be established, if the connection fails or ends, if etcd cancels the watch — compaction is the usual reason — or if on_change returns an error, which ends the watch, so a caller that wants to survive a bad document should log it and return Ok.

This never returns Ok: a watch either runs or has failed, and a silent success would leave a spawned task finished and a configuration frozen with nothing said about either. Callers that want to reconnect should loop around it.

Trait Implementations

impl AsyncRemoteSource for Etcd

fn fetch( &self, ) -> Pin<Box<dyn Future<Output = Result<Fetched, Error>> + Send + '_>>

Reads the current document.

fn describe(&self) -> String

How to name this source in an error or a report.

impl Debug for Etcd

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.