Struct Consul 

pub struct Consul { /* private fields */ }

A key in Consul’s KV store, as a configuration source.

Not Clone: the session holds the current token, and two clones logging in separately would double the login traffic. Wrap it in an Arc if two places need one.

Implementations

impl Consul

pub fn new(address: impl Into<String>, key: impl Into<String>) -> Self

The key key, served by the Consul agent at address.

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

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

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

pub fn with_token(self, token: impl Into<String>) -> Self

The ACL token to authenticate with.

Shorthand for with_auth(Auth::token(..)). A token that stops working cannot be replaced, because there are no credentials here to log in again with; Auth::kubernetes and Auth::jwt can.

pub fn with_auth(self, auth: Auth) -> Self

How to obtain an ACL token.

// In Kubernetes, with no secret to distribute at all.
let consul = Consul::new("http://consul:8500", "myapp/db.json")
    .with_auth(Auth::kubernetes("kubernetes"));

// Or whatever the operator put in the environment.
let consul = Consul::new("http://consul:8500", "myapp/db.json")
    .with_auth(Auth::from_environment());

Logging in is lazy: this reaches nothing, and the first read does it.

pub fn with_agent(self, agent: Agent) -> Self

Uses an HTTP client the program already has.

For a caller with its own proxy settings, a private CA, a client certificate, or a connection pool it would rather not have a second copy of. The agent’s own timeout applies instead of with_timeout — including for the long blocking query watch issues, so an agent used for watching needs a timeout above with_wait.

pub fn with_datacenter(self, datacenter: impl Into<String>) -> Self

The datacenter to read from, when it is not the agent’s own.

pub fn with_timeout(self, timeout: Duration) -> Self

How long to wait before giving up. Ten seconds by default.

pub fn with_wait(self, wait: Duration) -> Self

How long a blocking query may hold the connection open, when watch is used. One minute by default.

This is also how long a stopped watch can take to notice, so it trades one against the other: longer means fewer requests, and a slower exit. Consul’s own ceiling is ten minutes, so anything above it is clamped there — the agent would cap it silently anyway, and this way the client-side timeout stays sized to what the agent will actually do.

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

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

Calls on_change whenever the key’s value changes.

Uses Consul’s blocking queries: each request carries the index the last one returned, and the agent holds it open until that index moves or with_wait expires. So this is change-driven, not a poll — the callback runs when the value actually moves.

The current value is not delivered at startup, for the same reason a file watcher does not report an edit when it starts. Fetch first if the starting value matters, which it usually does:

DbConfig::apply_remote(consul.fetch()?)?;
consul.watch(&watching, DbConfig::apply_remote)

A failed query does not end the watch: the agent restarting, a network blip, or a key that does not exist yet are all exactly what a watch is supposed to survive. It pauses briefly and tries again, and gives up only when watching says to. A document identical to the last one is not reported — Consul bumps the index on every write, including one that changed nothing.

Errors

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. Transport failures do not surface here; they are retried.

Trait Implementations

impl Debug for Consul

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

Formats the value using the given formatter.

impl RemoteSource for Consul

fn fetch(&self) -> Result<Fetched, Error>

Reads the current document.

fn describe(&self) -> String

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