Struct Pool 

pub struct Pool { /* private fields */ }

A node’s station links. Cloning it shares the pool; the pool closes when Pool::close is called or its last handle is dropped.

Implementations

impl Pool

pub async fn call(&self, c: Call) -> Result<Value, PoolError>

Calls a procedure at a provider that serves it, as macula 12 calls one. A provider’s ERROR comes back as PoolError::Link(LinkError::Provider { .. }); when no candidate answers, PoolError::NoProvider names each one tried.

pub async fn call_report(&self, c: Call) -> Result<(Value, Report), PoolError>

Pool::call, returning with its result the call’s seal report (macula’s DESIGN_E2E_SEAL_REPORT): sealed 1 with the id of the key the request was sealed to, which is the key its answer opened under, or 0 and no key for a clear call; provider is the node the call was addressed to. An error comes with no report. It states that sealing ran on this exchange, nothing more.

pub async fn providers( &self, realm: &[u8; 32], procedure: &str, ) -> Result<Vec<Provider>, PoolError>

Every provider whose advertisement of procedure in realm the realm’s pinned key authorizes, with the station each serves from, freshest first.

pub async fn open_stream(&self, c: StreamCall) -> Result<Stream, PoolError>

Opens a streaming session at a provider of the procedure, reached as Pool::call reaches one: the next candidate only when a station cannot be reached, and the link’s own outcome is final. The stream is open once its STREAM_OPEN is sent; a provider’s or station’s refusal arrives on its first recv.

pub async fn station_target( &self, station: &[u8; 32], ) -> Result<Target, PoolError>

Where station is dialed, from the station_endpoint record the station signed itself; one another key signed is refused.

pub async fn link_to(&self, station: &[u8; 32]) -> Result<Link, PoolError>

A link to station: one the pool holds, or a direct link it dials to the address in the station’s own endpoint record, pinned by its node_id, within the default call timeout. A direct link that does not come up on its first dial is not kept.

pub async fn find_record(&self, key: &[u8; 32]) -> Result<Verified, PoolError>

The record under key, verified, from the first link that answers.

pub async fn find_records( &self, key: &[u8; 32], ) -> Result<(Vec<Verified>, usize), PoolError>

The records under key that verify, and how many did not, from the first link that answers.

pub async fn find_records_by_type( &self, t: RecordType, ) -> Result<(Vec<Verified>, usize), PoolError>

The records of type t that verify, and how many did not, from the first link that answers.

pub async fn put_record(&self, wire: &[u8]) -> Result<(), PoolError>

Puts a signed record through the first link whose station takes it.

impl Pool

pub async fn share_content( &self, realm: &[u8; 32], data: &[u8], name: &str, ) -> Result<Mcid, PoolError>

Keeps data, serves it on this node’s content procedure in realm and announces it, renewing the announcement until unshared or the pool is dropped. Data of at most one chunk is one raw block; larger data is a manifest over 256 KiB chunks, named name. Returns the content id.

pub async fn unshare_content( &self, realm: &[u8; 32], mcid: &Mcid, ) -> Result<(), PoolError>

Stops sharing mcid in realm: it is no longer served, and its announcement is withdrawn with a tombstone this node signs. Content not shared is nothing to do.

pub async fn get_content( &self, realm: &[u8; 32], mcid: &Mcid, opts: ContentOptions, ) -> Result<Vec<u8>, PoolError>

Fetches the content mcid names in realm from a node that shares it, as macula_content_fetch does: the announcements under the content id’s key that name it, realm, a serving station and a content procedure bound to their announcer; the sharers tried one at a time in a random order; a block that must hash to mcid, or a manifest that must match mcid before its sizes are read and fit opts before any chunk is asked for, each chunk on its own stream, opts.parallel at a time, checked against its own content id, and the whole against the manifest. No realm key is needed. Content nobody announces is PoolError::NotShared; when every sharer fails, PoolError::ContentUnavailable names each failure.

impl Pool

pub async fn subscribe( &self, realm: &[u8; 32], topic: &str, ) -> Result<Subscription, PoolError>

Subscribes the node to topic in realm on every link.

pub async fn publish(&self, p: Publication) -> Result<(), PoolError>

Signs p once and sends it on the first replication_factor links, in the pool’s selection order, succeeding when one of them takes it. Every copy is the same publication, so a subscriber delivers it once.

impl Pool

pub async fn serve(&self, o: Offer) -> Result<Served, PoolError>

Serves o on every link that is up, and on every link that comes up after. It succeeds when one link serves it; each link advertises it naming its own station, and renews it and puts it in the DHT as Link::serve does.

impl Pool

pub async fn connect(seeds: Vec<Seed>, opts: Opts) -> Result<Pool, PoolError>

Checks seeds and opts, dials every seed, and returns once one link is up, or PoolError::NoLink with each link’s last error when the connect timeout passes first. Links not yet up keep dialing.

pub fn node_id(&self) -> [u8; 32]

The node_id the pool links as.

pub fn status(&self) -> Vec<LinkStatus>

Every link the pool holds, seeds first.

pub async fn close(&self)

Ends every link with a GOODBYE and every subscription. It withdraws nothing: an advertisement lapses with its link.

Trait Implementations

impl Clone for Pool

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Pool

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

Formats the value using the given formatter.