Trait RemoteSource 

pub trait RemoteSource:
    Send
    + Sync
    + 'static {
    // Required methods
    fn fetch(&self) -> Result<Fetched, Error>;
    fn describe(&self) -> String;

    // Provided methods
    fn watch_capability(&self) -> WatchCapability { ... }
    fn watch(
        &self,
        watching: &Watching,
        interval: Duration,
        on_change: &mut dyn FnMut(Fetched) -> Result<(), Error>,
    ) -> Result<(), Error> { ... }
}

A remote store that can be read without an async runtime.

The right trait for anything with a plain HTTP API — Consul and Vault both are — because implementing it needs no runtime and using it needs no runtime either. fetch may block; it is called from refresh_remote(), never from load().

Required Methods

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

Reads the current document.

Errors

Whatever going wrong looks like for this store. Use Error::remote so the failure is categorised consistently, or Error::auth for a credential the store itself refused — that is the distinction a watch loop backs off on rather than stopping.

fn describe(&self) -> String

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

Provided Methods

fn watch_capability(&self) -> WatchCapability

How this store learns that its document changed.

Interval unless a store says otherwise, which is the honest default: a store that has not been asked the question has no push to offer.

fn watch( &self, watching: &Watching, interval: Duration, on_change: &mut dyn FnMut(Fetched) -> Result<(), Error>, ) -> Result<(), Error>

Watches until the handle is dropped, calling on_change with every document that differs from the last one delivered.

Override this with the store’s own mechanism — a blocking query, a stream, a subscription — and say so in watch_capability. An override may ignore interval: a store that reports Native gets its resync from Remote::watch, which reads on the interval alongside the store’s own watch. That is not belt and braces — the failure mode of a stream is silence, and a subscription the broker forgot looks exactly like a store where nothing has changed.

The default polls: fetch, deliver anything new, wait, repeat. The waits are spread so a fleet does not poll in lockstep, and they grow after a failure so a store that is down is not hammered by everything that depends on it — Pace is that policy, and an implementation with its own loop should use it rather than sleep a flat interval.

Called from a thread the caller owns. It returns when the watch is stopped, or when on_change refuses.

Errors

If on_change refuses a document. A fetch failing is not an error here: a watch outlives an outage by design, so it is backed off from rather than returned.

Nothing here records it. A source is handed a store and a callback; the status a Remote keeps is not reachable from either, so a loop that wants status().reachable() to tell the truth through an outage reports failures itself — RemoteSink::failed is that call, and the store crates’ reporting_to wires it. Said here because the alternative reading is expensive: a watch that has been failing for an hour while its status says the store is fine.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors