Struct Resolver 

pub struct Resolver { /* private fields */ }

A composable chain of identity sources.

Use Resolver::with_defaults for the platform-appropriate default chain, or Resolver::new to start empty and build your own order with Resolver::push / Resolver::prepend.

Implementations

impl Resolver

pub fn new() -> Self

Start with an empty chain. No sources are tried until you add some.

pub fn with_defaults() -> Self

Start with the default chain for the current platform.

The chain begins with the HOST_IDENTITY environment variable override, then — on Linux, when the container feature is on — inserts the container source ahead of the host-level sources so containers get their own identity, then walks the platform’s native sources in recommended order. See sources::default_chain for the exact contents on each OS.

This chain is strictly local: no source makes network calls.

pub fn push<S: Source + 'static>(self, source: S) -> Self

Append a source to the end of the chain (lowest priority).

pub fn push_boxed(self, source: Box<dyn Source>) -> Self

Append an already-boxed source. Use when you have Box<dyn Source> already — for example when building a chain from runtime input via crate::ids::resolver_from_ids.

pub fn prepend<S: Source + 'static>(self, source: S) -> Self

Prepend a source to the front of the chain (highest priority).

O(n) in the existing chain length — each call shifts every other source. For a chain assembled from many prepends, build the full list first and pass it to Resolver::with_sources instead.

pub fn with_sources<I, S>(self, sources: I) -> Self

where I: IntoIterator<Item = S>, S: Source + 'static,

Replace the entire chain. All items must be the same concrete Source type; for heterogeneous chains use Resolver::with_boxed_sources.

pub fn into_boxed_sources(self) -> Vec<Box<dyn Source>>

Drain the chain, returning its boxed sources in chain order.

The wrap strategy is discarded — the caller reapplies one via Resolver::with_wrap when rebuilding. Use when you need to post-process the chain (for example, wrapping every source with crate::sources::AppSpecific) and feed the sources back via Resolver::with_boxed_sources.

pub fn with_boxed_sources<I>(self, sources: I) -> Self

where I: IntoIterator<Item = Box<dyn Source>>,

Replace the entire chain with an already-boxed, heterogeneous list. Use when you have sources of different concrete types — with_sources requires a single concrete type for all items, so a mixed chain has to be boxed first.

use host_identity::{Resolver, Source};
use host_identity::sources::{EnvOverride, FnSource};

let chain: Vec<Box<dyn Source>> = vec![
    Box::new(EnvOverride::new("HOST_IDENTITY")),
    Box::new(FnSource::new(SourceKind::custom("x"), || Ok(None))),
];
let resolver = Resolver::new().with_boxed_sources(chain);

pub fn with_wrap(self, wrap: Wrap) -> Self

Set the UUID-wrapping strategy applied to the raw identifier.

Defaults to Wrap::UuidV5Namespaced.

pub fn source_kinds(&self) -> Vec<SourceKind>

Inspect the configured chain — useful for tests, diagnostics, and logging the resolver shape at startup.

pub fn source_kinds_iter(&self) -> impl Iterator<Item = SourceKind> + '_

Non-allocating view of the chain’s source kinds, in order.

Use when you want to iterate without materialising a Vec — e.g. constructing a log line, or checking whether a specific kind is present. The returned iterator borrows self and must not outlive the resolver.

pub fn resolve(&self) -> Result<HostId, Error>

Walk the chain and return the first successful identity.

Errors

Returns Error::NoSource if every source returned Ok(None), or Error::Malformed if the selected Wrap is Wrap::Passthrough and the raw value is not a valid UUID. Other Error variants bubble up from the source that produced them (permission denied, sentinel value, platform-tool failure).

pub fn resolve_all(&self) -> Vec<ResolveOutcome>

Walk the entire chain without short-circuiting and return one ResolveOutcome per source.

Complements Resolver::resolve: the chain, wrap strategy, and container-detection logic are identical — only the stopping behaviour differs. Every source is consulted exactly once, in chain order, and neither a success nor an error stops the walk.

Use this to audit what each source would produce — operator diagnostics, debugging, or test harnesses that want to confirm that several sources agree. For normal resolution use Resolver::resolve, which stops at the first usable source.

To run a caller-chosen subset of sources, build the resolver with exactly those sources — the same builder that feeds resolve():

use host_identity::Resolver;
use host_identity::sources::{MachineIdFile, DmiProductUuid};

let report = Resolver::new()
    .push(MachineIdFile::default())
    .push(DmiProductUuid::default())
    .resolve_all();
for outcome in report {
    println!("{:?} → {:?}", outcome.source(), outcome.host_id());
}

Trait Implementations

impl Debug for Resolver

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

Formats the value using the given formatter.

impl Default for Resolver

fn default() -> Self

Returns the “default value” for a type.