Struct Client 

pub struct Client { /* private fields */ }

Client is the main handle for interacting with iroh-services. It communicates with iroh-services entirely through an iroh endpoint, and is configured through a builder. Client requires either an Ssh Key or ApiSecret

use iroh::{Endpoint, endpoint::presets};
use iroh_services::Client;

async fn build_client() -> anyhow::Result<()> {
    let endpoint = Endpoint::bind(presets::N0).await?;

    // needs IROH_SERVICES_API_SECRET set to an environment variable
    // client will now push endpoint metrics to iroh-services.
    let client = Client::builder(&endpoint)
        .api_secret_from_str("MY_API_SECRET")?
        .build()
        .await;

    Ok(())
}

Implementations

impl Client

pub fn builder(endpoint: &Endpoint) -> ClientBuilder

pub async fn name(&self) -> Result<Option<String>, Error>

Read the current endpoint name from the local client.

pub async fn group(&self) -> Result<Option<String>, Error>

Read the current endpoint group from the local client.

pub async fn set_name(&self, name: impl Into<String>) -> Result<(), Error>

Name the active endpoint cloud-side.

names can be any UTF-8 string, with a min length of 2 bytes, and maximum length of 128 bytes. name uniqueness is not enforced.

pub async fn set_group(&self, group: impl Into<String>) -> Result<(), Error>

Attach the active endpoint to a single named group cloud-side.

A group name must be 2 to 128 bytes of UTF-8.

pub async fn set_attributes<I, K, V>(&self, attrs: I) -> Result<(), Error>

where I: IntoIterator<Item = (K, V)>, K: Into<String>, V: Into<String>,

Replace the arbitrary key-value attributes on the active endpoint cloud-side.

Accepts any iterable of (key, value) pairs (arrays of tuples, Vecs, HashMaps, BTreeMaps, etc.), so most calls fit on a single line:

client
    .set_attributes([("env", "prod"), ("region", "us-west")])
    .await?;

Each key must be 2 to 128 bytes of UTF-8; values may be empty and are limited to 128 bytes; at most 128 entries are allowed. Each call fully replaces the prior set; passing an empty iterator clears all attributes.

pub async fn set_attribute( &self, key: impl Into<String>, value: impl Into<String>, ) -> Result<(), Error>

Set or replace a single attribute, merging it into the endpoint’s existing attributes rather than replacing the whole set.

A convenience over set_attributes when you only need to change one value. The key must be 2 to 128 bytes of UTF-8 and the value is limited to 128 bytes; the merged set must stay within 128 entries.

pub async fn ping(&self) -> Result<Pong, Error>

Pings the remote node.

pub async fn push_metrics(&self) -> Result<(), Error>

immediately send a single dump of metrics to iroh-services. It’s not necessary to call this function if you’re using a non-zero metrics interval, which will automatically propagate metrics on the set interval for you

pub async fn shutdown(&self)

Shuts down the client, after pushing one final round of metrics.

Calling this aborts any inflight requests, and all subsequent requests triggered via methods on Self will fail. If the client is currently connected, it will send one final metrics update before shutting down the client actor.

Dropping the client without calling this method immediately stops the actor without a final metrics push.

pub async fn grant_capability( &self, remote_id: EndpointId, caps: impl IntoIterator<Item = impl Into<Cap>>, ) -> Result<(), Error>

Grant capabilities to a remote endpoint. Creates a signed RCAN token and sends it to iroh-services for storage. The remote can then use this token when dialing back to authorize its requests.

pub async fn net_diagnostics( &self, send: bool, ) -> Result<DiagnosticsReport, Error>

run local network status diagnostics, optionally uploading the results

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Client

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

Formats the value using the given formatter.