Struct ArtifactExchange 

pub struct ArtifactExchange { /* private fields */ }

Node-local state of the artifact piece protocol.

Implementations

impl ArtifactExchange

pub fn new( node_id: impl Into<String>, store: Arc<ArtifactStore>, config: ExchangeConfig, ) -> Result<Self, ExchangeError>

Exchange for node_id over store.

pub fn set_chain_manager(&mut self, cm: Arc<ChainManager>)

Chain transfer outcomes to cm.

pub fn node_id(&self) -> &str

This node’s id.

pub fn store(&self) -> &Arc<ArtifactStore>

Backing store.

pub fn config(&self) -> &ExchangeConfig

Configuration.

pub fn seed_reader( &self, reader: &mut dyn Read, expect: Option<([u8; 32], u64)>, ) -> Result<ArtifactDescriptor, ExchangeError>

Split reader into pieces, store each, and register the artifact. Streams: at most one piece is in memory. When expect is given (content hash, size), a mismatch is an error and nothing is registered.

pub fn seed_bytes( &self, content: &[u8], ) -> Result<ArtifactDescriptor, ExchangeError>

Self::seed_reader over an in-memory buffer.

pub fn descriptor(&self, id: &ArtifactId) -> Option<ArtifactDescriptor>

Verified descriptor by id.

pub fn is_verified(&self, id: &ArtifactId) -> bool

True when id is verified on this node.

pub fn resolve(&self, key: &ArtifactKey) -> Option<ArtifactDescriptor>

Verified descriptor by key.

pub fn have(&self, id: &ArtifactId) -> Option<Bitfield>

Pieces held locally for a verified or pending artifact, derived from the store.

pub fn read_to( &self, id: &ArtifactId, sink: &mut dyn FnMut(&[u8]) -> Result<(), ExchangeError>, ) -> Result<u64, ExchangeError>

Stream the whole artifact through sink in piece order, checking every piece and the whole-content hash. Returns the byte count.

pub fn read_all(&self, id: &ArtifactId) -> Result<Vec<u8>, ExchangeError>

Whole artifact in memory (bounded by materialize_limit).

pub fn is_servable(&self, d: &ArtifactDescriptor) -> bool

Governance: may d be listed in broadcast facts and seeded? It must be verified on this node (its pieces assemble to its content_hash), a signed manifest that verified here must list it, the redistribution policy must allow it for Audience::Advertise, and neither the package, its signers nor the content hash may be revoked. Serving a particular peer is Self::is_servable_to.

pub fn is_servable_to( &self, d: &ArtifactDescriptor, audience: &Audience<'_>, ) -> bool

Self::is_servable for a specific audience.

pub fn peer_have(&self, id: &ArtifactId, peer: &str) -> Option<Bitfield>

Last have announced by peer for id.

impl ArtifactExchange

pub fn seed_package( &self, manifest: &[u8], anchors: &TrustAnchors, open: &mut dyn FnMut(&FileRef) -> Result<Box<dyn Read>>, ) -> Result<ExchangedPackage, PackageExchangeError>

Seed a signed package. open yields each listed file’s bytes; files are streamed, so large payloads never sit in memory whole.

pub fn seed_package_in( &self, manifest: &[u8], anchors: &TrustAnchors, kinds: &KindRegistry, open: &mut dyn FnMut(&FileRef) -> Result<Box<dyn Read>>, ) -> Result<ExchangedPackage, PackageExchangeError>

Self::seed_package against a caller-supplied kind registry.

pub fn seed_package_dir( &self, dir: &Path, anchors: &TrustAnchors, ) -> Result<ExchangedPackage, PackageExchangeError>

Self::seed_package from an unpacked package directory.

pub fn seed_package_dir_in( &self, dir: &Path, anchors: &TrustAnchors, kinds: &KindRegistry, ) -> Result<ExchangedPackage, PackageExchangeError>

Self::seed_package_dir against a caller-supplied kind registry.

pub fn seed_package_dir_manifest( &self, dir: &Path, manifest: &[u8], anchors: &TrustAnchors, kinds: &KindRegistry, ) -> Result<ExchangedPackage, PackageExchangeError>

Self::seed_package_dir_in for a caller that already read the manifest bytes from dir (so the manifest is read once). manifest must be the content of dir’s cogpkg.json; it is verified here.

pub async fn fetch_package( &self, peers: &mut PeerSet, manifest_hash: &str, anchors: &TrustAnchors, ) -> Result<ExchangedPackage, PackageExchangeError>

Fetch a signed package by its manifest hash. Signatures are checked before any file is requested; each file must match its pinned size and hash. Once the manifest verifies, this node may serve the listed files it holds verified.

pub async fn fetch_package_in( &self, peers: &mut PeerSet, manifest_hash: &str, anchors: &TrustAnchors, kinds: &KindRegistry, ) -> Result<ExchangedPackage, PackageExchangeError>

Self::fetch_package against a caller-supplied kind registry. A node that places a registered non-cog kind from a peer must use this: with the builtin registry the kind is refused, failing closed.

impl ArtifactExchange

pub async fn serve( &self, stream: &mut dyn MeshStream, peer: &str, ) -> Result<ServeStats, ExchangeError>

Serve one peer until it closes the stream. Only pieces of servable artifacts (Self::is_servable) are sent. An oversize or malformed frame ends the session with an error, and so does a peer that sends nothing for serve_idle_timeout.

peer is only a claimed id (the peer is ServePeer::unverified): with a policy that serves verified peers only, nothing is served. Use Self::serve_as when admission authenticated the peer.

pub async fn serve_as( &self, stream: &mut dyn MeshStream, who: &ServePeer, ) -> Result<ServeStats, ExchangeError>

Self::serve for a peer whose identity the caller has (or has not) verified: the redistribution policy sees peer for every request.

pub async fn serve_frame( &self, stream: &mut dyn MeshStream, peer: &str, raw: &[u8], stats: &mut ServeStats, ) -> Result<(), ExchangeError>

Serve one frame already read from stream, for sessions that carry the piece protocol beside other traffic on one stream (the workload.ctl fetch-before-load, mesh-placement-12). Same rules as Self::serve: only servable artifacts are sent.

pub async fn serve_frame_as( &self, stream: &mut dyn MeshStream, who: &ServePeer, raw: &[u8], stats: &mut ServeStats, ) -> Result<(), ExchangeError>

Self::serve_frame with the peer’s verified-ness stated.

pub async fn fetch( &self, peers: &mut PeerSet, key: ArtifactKey, ) -> Result<FetchOutcome, FetchError>

Fetch key from peers with the v1 SequentialScheduler.

pub async fn fetch_with( &self, peers: &mut PeerSet, key: ArtifactKey, scheduler: &mut dyn PieceScheduler, ) -> Result<FetchOutcome, FetchError>

Fetch key, trying each live peer in turn until every piece is held and the whole content verifies. Pieces already held are never requested, so a repeated call resumes an interrupted transfer. A peer whose pieces do not assemble to its declared content is dropped and its descriptor discarded. The outcome (verified or failed) is chained as artifact.fetch.

impl ArtifactExchange

pub async fn swarm_fetch( self: &Arc<Self>, dialer: Arc<dyn PeerDialer>, candidates: Vec<PeerCandidate>, key: ArtifactKey, opts: &SwarmFetchOptions, ) -> Result<FetchOutcome, FetchError>

Fetch key from several holders at once (see the module docs). Pieces already held are not requested again, so a repeated call resumes. candidates are the peers that may hold it (from crate::mesh_swarm_lookup); banned peers are skipped.

A fetch by content hash trusts nobody’s descriptor: when the pieces a peer’s descriptor describes do not assemble to the content hash, that peer and the sources that vouched for the same descriptor are banned and the fetch carries on with the remaining candidates (up to three attempts), so one liar cannot block it or get honest peers blamed.

impl ArtifactExchange

pub fn set_revocations(&self, list: Arc<RevocationList>) -> bool

Use list as this node’s revocation list (first call wins).

pub fn is_revoked(&self, content_hash: &[u8; 32]) -> bool

True when the content hash is revoked, or every package that allowed it (or those packages’ signers) is. A package revoked while another, unrevoked one still lists the same content leaves the content allowed.

pub fn apply_revocations(&self) -> Vec<RevokedArtifact>

Apply the revocation list to everything held: drop each revoked grant; when no grant is left for a content hash, evict its bytes (and any partial copy), and chain artifact.revoke and artifact.evict. Safe to call repeatedly.

Revocation evicts even pinned cache entries (the bytes are removed and serving is blocked). This sweep does not touch a workload that is already running from them; stopping those is the host’s job (WorkloadHostService::enforce_revocations), which the daemon runs after every applied revocation.

Revocation is monotonic mesh-wide: entries are only ever added, by an operator command or a signed notice, and a notice is re-flooded to every peer. Removing one locally (unrevoke_subject) is undone by the next notice a peer re-sends; to lift a revocation, clear the list on every node or issue the package under a new key.

pub fn ban_peer(&self, peer: &str, reason: &str) -> bool

Ban peer: no more fetching from it or serving it. Returns true if newly banned (chained as artifact.peer_ban).

pub fn unban_peer(&self, peer: &str) -> bool

Lift a ban. Returns true if the peer was banned.

pub fn is_banned(&self, peer: &str) -> bool

True if peer is banned.

pub fn banned_peers(&self) -> Vec<(String, String)>

Banned peers and why.

pub fn link_stats(&self) -> &LinkStats

Measured link speeds to peers.

pub fn pending_bytes(&self) -> u64

Bytes of downloads in progress (what their descriptors claim).

pub fn servable_artifacts(&self) -> Vec<ArtifactDescriptor>

Verified artifacts this node may serve (verified, allowed, not revoked).

pub fn forget(&self, id: &ArtifactId, reason: &str) -> Option<Forgotten>

Remove id (verified or pending) and the blobs no other artifact lists. The grant is kept, so a later fetch can seed it again; revocation drops the grant itself. Chains artifact.evict.

Only blobs this exchange created and nobody else has stored since (store reference count 1) are removed: the store is shared with package verification and installed workloads, which may hold the same bytes. A pinned cache entry is not forgotten, except for revoked.

pub fn held_capabilities( &self, model_shards: &HashSet<[u8; 32]>, ) -> Vec<Capability>

Capabilities for what this node can serve, to merge into its facts: store.artifact.<16 hex of content hash> per artifact (attrs content, size) and, for content hashes in model_shards, model.present with the shard list. Held artifacts are probed: this node verified them itself.

impl ArtifactExchange

pub async fn who_has( self: &Arc<Self>, dialer: Arc<dyn PeerDialer>, peers: &[PeerCandidate], key: ArtifactKey, ) -> Vec<Holder>

Ask peers whether they hold key. Peers that refuse, fail or are banned are left out. Sorted by peer id.

pub async fn find_holders( self: &Arc<Self>, dialer: Arc<dyn PeerDialer>, facts: &NodeFactsCache, neighbors: &[PeerCandidate], key: ArtifactKey, now: u64, ) -> Vec<PeerCandidate>

Candidates for key: peers advertising it in their facts plus neighbors that answer a who_has query now.

impl ArtifactExchange

pub async fn swarm_fetch_package( self: &Arc<Self>, dialer: Arc<dyn PeerDialer>, candidates: &[PeerCandidate], manifest_hash: &str, anchors: &TrustAnchors, opts: &SwarmFetchOptions, ) -> Result<ExchangedPackage, PackageExchangeError>

Fetch a signed package by its manifest hash from candidates.

pub async fn swarm_fetch_package_in( self: &Arc<Self>, dialer: Arc<dyn PeerDialer>, candidates: &[PeerCandidate], manifest_hash: &str, anchors: &TrustAnchors, opts: &SwarmFetchOptions, kinds: &KindRegistry, ) -> Result<ExchangedPackage, PackageExchangeError>

Self::swarm_fetch_package against a caller-supplied kind registry.

impl ArtifactExchange

pub fn grant_checkout(&self, v: &VerifiedCheckoutGrant)

Make the bytes of a verified checkout grant shareable inside the mesh: one grant per listed BLAKE3, signed by the bound grant key, with GrantOrigin::Cognitum. A revoked key or hash is skipped by grant_with, and revocation applies through the usual sweep. This does not make the bytes runnable (see super::may_run).