Trait PeerResolver

Source

pub trait PeerResolver {
    // Required method
    fn locate(&self, workspace: &str) -> PeerLookup;

    // Provided method
    fn locate_document(&self, workspace: &str, id: &Id) -> Option<PeerLocation> { ... }
}

Expand description

A host’s map from a workspace name to where that workspace is.

This is the trait a host implements to make foreign references followable. It is not generic over anything and takes &self throughout, so it is dyn-compatible: a consumer can hold &dyn PeerResolver and be handed prov-cli’s device-local peer file, diaryx’s ARK resolution, or NoPeers, without being written twice.

The implementor’s obligation is the one prov cannot enforce from here: build every answer through PeerLookup::confirm when the peer’s own name is readable, and through unreadable / unchecked when it is not. Returning Confirmed for a location whose occupant was never read is the one way to defeat this design, and it takes deliberate effort.

Required Methods§

Source

fn locate(&self, workspace: &str) -> PeerLookup

Where the workspace named workspace is.

A name that is not well-formed has no workspace to find and should answer Unknown rather than be looked up: it cannot be any workspace’s workspace_id, so a map entry matching it was hand-written wrong.

Provided Methods§

Source

fn locate_document(&self, workspace: &str, id: &Id) -> Option<PeerLocation>

Where one document in that workspace is — the whole reference answered at once, rather than the workspace it lives in.

Defaults to None, because most resolvers cannot answer it. Turning id:notes/ajp7eq into a file means opening notes and reading its registry, which the host can do and this crate cannot; turning it into a permalink means knowing that host’s URL scheme. A caller that gets None falls back to locate and does the opening itself.

The same obligation applies twice over: answer only for a workspace whose identity you have confirmed. There is no PeerLookup wrapper on this one to carry the doubt in, so an unconfirmed answer here is indistinguishable from a confirmed one.