Developer SDK

Rust examples

Install the SDK · View source on GitHub ↗

provider/src/status.rs

rust
//! The provider status that every provider example shows, with the exact text rules of
//! PROVIDER_CONTRACT.md ("Status"): providing state, clients served, data provided and the payout
//! wallet, read only. Everything here is pure, so the self-test checks it without the native SDK, a
//! network or credentials.

use std::{
    collections::HashSet,
    fmt,
    sync::{Mutex, PoisonError},
    time::{Duration, Instant},
};

use serde::Deserialize;

use crate::id::{ZERO_ID, parse_id};

/// Shown at start by the console app, next to the start control in the GUI, and in every README.
/// The app that integrates a provider owns the consent screen; this example starts without asking.
pub const CONSENT_DISCLAIMER: &str = "Consent disclaimer: an app that integrates a URnetwork provider must collect the user's consent before it provides.
Providing shares the user's internet connection: other URnetwork users' traffic exits through the user's device and IP address.
This example starts providing without asking, because the consent screen belongs to your app.";

/// Provide mode off (C ABI `URNET_PROVIDE_MODE_NONE`).
pub const PROVIDE_MODE_NONE: i64 = 0;
/// Provide to the device's own network only (`URNET_PROVIDE_MODE_NETWORK`).
pub const PROVIDE_MODE_NETWORK: i64 = 1;
/// Provide to everyone (`URNET_PROVIDE_MODE_PUBLIC`); the SDK then declares provide intent by
/// itself.
pub const PROVIDE_MODE_PUBLIC: i64 = 3;

/// No client limit hold (C ABI `URNET_CLIENT_LIMIT_STATUS_NONE`).
pub const CLIENT_LIMIT_STATUS_NONE: &str = "";
/// The platform disconnected this client for its network's client limit
/// (`URNET_CLIENT_LIMIT_STATUS_EXCEEDED`).
pub const CLIENT_LIMIT_STATUS_EXCEEDED: &str = "client_limit_exceeded";

/// The `consent_scope` of a network's hotkey delegation in `GET /sn/wallet`. Hotkey delegations
/// come with a later server and SDK change; the app only labels them.
pub const SN_WALLET_CONSENT_SCOPE_HOTKEY: &str = "hotkey";
/// The `consent_scope` of the network consent.
pub const SN_WALLET_CONSENT_SCOPE_NETWORK: &str = "network";
/// The `consent_scope` of a per-provider consent.
pub const SN_WALLET_CONSENT_SCOPE_PROVIDER: &str = "provider";

/// Distinct clients are counted up to this many; beyond it the count is a lower bound, shown with a
/// trailing `+`.
pub const CLIENTS_SERVED_LIMIT: usize = 100 * 1000;

/// How long the console waits before it repeats an unchanged status line.
pub const STATUS_REPEAT_INTERVAL: Duration = Duration::from_secs(60);

/// The providing state, from the device getters.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ProviderState {
    /// The provide mode is not public.
    Stopped,
    /// The platform disconnected this client for its network's client limit, and the SDK holds off
    /// reconnecting until the retry time.
    ClientLimit,
    /// Public, but not yet enabled and connected to the platform.
    Starting,
    /// Providing is paused.
    Paused,
    /// Enabled and connected to the platform.
    Providing,
}

impl ProviderState {
    /// The state's text in the status line.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Stopped => "stopped",
            Self::ClientLimit => "client limit",
            Self::Starting => "starting",
            Self::Paused => "paused",
            Self::Providing => "providing",
        }
    }
}

/// Which owner the effective payout wallet belongs to.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PayoutWalletScope {
    /// The network's hotkey delegation.
    Hotkey,
    /// This provider client's own mapping.
    ThisProvider,
    /// The network's wallet.
    Network,
    /// Another provider client of the network.
    AnotherProvider,
}

impl PayoutWalletScope {
    /// The label after the address, without its parentheses.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Hotkey => "hotkey",
            Self::ThisProvider => "this provider",
            Self::Network => "network",
            Self::AnotherProvider => "another provider",
        }
    }
}

/// The payout wallet as the app shows it, read only.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum PayoutWallet {
    /// Before the first wallet read finishes.
    Checking,
    /// The first wallet read failed; a later failure keeps the last value instead.
    Unavailable,
    /// No wallet is mapped.
    NotSet,
    /// The mapped coldkey (ss58) and the owner of its mapping.
    Mapped {
        coldkey_ss58: String,
        scope: PayoutWalletScope,
    },
}

impl fmt::Display for PayoutWallet {
    /// `checking`, `unavailable`, `not set`, or the address with its scope in parentheses, such as
    /// `5Grw... (network)`.
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Checking => formatter.write_str("checking"),
            Self::Unavailable => formatter.write_str("unavailable"),
            Self::NotSet => formatter.write_str("not set"),
            Self::Mapped {
                coldkey_ss58,
                scope,
            } => write!(formatter, "{coldkey_ss58} ({})", scope.as_str()),
        }
    }
}

/// One status snapshot.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ProviderStatus {
    pub state: ProviderState,
    /// The end of the client limit hold in unix milliseconds, shown with the client limit state; 0
    /// when unknown.
    pub client_limit_retry_time: i64,
    pub clients_served: usize,
    pub clients_served_at_limit: bool,
    pub data_provided_byte_count: u64,
    pub payout_wallet: PayoutWallet,
}

impl ProviderStatus {
    /// A stopped provider that has not served anyone yet and has not read its wallet.
    pub fn stopped() -> Self {
        Self {
            state: ProviderState::Stopped,
            client_limit_retry_time: 0,
            clients_served: 0,
            clients_served_at_limit: false,
            data_provided_byte_count: 0,
            payout_wallet: PayoutWallet::Checking,
        }
    }

    /// The status field, with the retry time for the client limit state.
    pub fn status_text(&self) -> String {
        provider_status_text(self.state, self.client_limit_retry_time)
    }

    /// The clients-served field, with a trailing `+` once the count stopped at its limit.
    pub fn clients_served_text(&self) -> String {
        if self.clients_served_at_limit {
            format!("{}+", self.clients_served)
        } else {
            self.clients_served.to_string()
        }
    }

    /// The data-provided field.
    pub fn data_provided_text(&self) -> String {
        format_byte_count(self.data_provided_byte_count)
    }

    /// The payout wallet field.
    pub fn payout_wallet_text(&self) -> String {
        self.payout_wallet.to_string()
    }

    /// The fields that change rarely. A change prints a status line at once; the data counter alone
    /// only prints on the periodic line. The status text carries the client limit retry time,
    /// so a new retry time prints too.
    pub fn key(&self) -> String {
        format!(
            "{}|{}|{}",
            self.status_text(),
            self.clients_served_text(),
            self.payout_wallet_text()
        )
    }
}

impl fmt::Display for ProviderStatus {
    /// The status line, for example:
    ///
    /// ```text
    /// status: providing | clients served: 3 | data provided: 12.4 MiB | payout wallet: 5Grw... (network)
    /// ```
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            formatter,
            "status: {} | clients served: {} | data provided: {} | payout wallet: {}",
            self.status_text(),
            self.clients_served_text(),
            self.data_provided_text(),
            self.payout_wallet_text(),
        )
    }
}

/// Decides when the console prints a status line: at once when the status text, the clients-served
/// count or the payout wallet changes, otherwise once every [`STATUS_REPEAT_INTERVAL`].
#[derive(Default)]
pub struct StatusLines {
    last_key: Option<String>,
    last_print_time: Option<Instant>,
}

impl StatusLines {
    /// The line to print for the status read at `now`, or none.
    pub fn next_line(&mut self, status: &ProviderStatus, now: Instant) -> Option<String> {
        let key = status.key();
        let changed = self.last_key.as_deref() != Some(key.as_str());
        let repeat_due = self.last_print_time.is_none_or(|last_print_time| {
            STATUS_REPEAT_INTERVAL <= now.saturating_duration_since(last_print_time)
        });
        if !changed && !repeat_due {
            return None;
        }
        self.last_key = Some(key);
        self.last_print_time = Some(now);
        Some(status.to_string())
    }
}

/// The status field text: the state, and for the client limit state the time the SDK retries, for
/// example `client limit, retry at 19:05 UTC`. The retry time (unix milliseconds) is rounded up to
/// the next whole minute in UTC, so the shown time is never before the real retry; a retry time of
/// 0 shows `client limit`.
pub fn provider_status_text(state: ProviderState, client_limit_retry_time: i64) -> String {
    if state != ProviderState::ClientLimit || client_limit_retry_time <= 0 {
        return state.as_str().to_string();
    }
    let retry_minute = (client_limit_retry_time as u64).div_ceil(60 * 1000);
    let hour = (retry_minute / 60) % 24;
    let minute = retry_minute % 60;
    format!(
        "{}, retry at {hour:02}:{minute:02} UTC",
        ProviderState::ClientLimit.as_str()
    )
}

/// Binary units with one decimal: `0 B`, `1023 B`, `1.0 KiB`, `12.4 MiB`. Values round to the
/// nearest tenth with ties to even, as Go's `%.1f` does: 1280 bytes (1.25 KiB) is `1.2 KiB` and
/// 1792 bytes (1.75 KiB) is `1.8 KiB`. Rust's `{:.1}` rounds the exact binary value that way. A
/// value that rounds to 1024.0 moves to the next unit.
pub fn format_byte_count(byte_count: u64) -> String {
    if byte_count < 1024 {
        return format!("{byte_count} B");
    }
    let units = ["KiB", "MiB", "GiB", "TiB", "PiB", "EiB"];
    let mut value = byte_count as f64 / 1024.0;
    let mut unit_index = 0;
    while unit_index < units.len() - 1 && 1024.0 <= (value * 10.0).round_ties_even() / 10.0 {
        value /= 1024.0;
        unit_index += 1;
    }
    format!("{value:.1} {}", units[unit_index])
}

/// The providing state from the device getters, in this order: stopped unless the provide mode is
/// public; client limit while the SDK holds this client off for its network's client limit; paused
/// while paused; providing once the provider is enabled and its platform carrier is connected;
/// starting otherwise.
pub fn provider_state(
    provide_mode: i64,
    client_limit_status: &str,
    provide_paused: bool,
    provide_enabled: bool,
    provider_connected: bool,
) -> ProviderState {
    if provide_mode != PROVIDE_MODE_PUBLIC {
        ProviderState::Stopped
    } else if client_limit_status == CLIENT_LIMIT_STATUS_EXCEEDED {
        ProviderState::ClientLimit
    } else if provide_paused {
        ProviderState::Paused
    } else if provide_enabled && provider_connected {
        ProviderState::Providing
    } else {
        ProviderState::Starting
    }
}

/// Which owner the effective payout wallet belongs to. The consent scope comes first: a hotkey
/// delegation is network-level, with no client id, but is not the network's wallet. Otherwise by
/// the wallet's client id: this provider's own mapping, the network's wallet, or another provider
/// of the network.
pub fn payout_wallet_scope(
    wallet_consent_scope: Option<&str>,
    wallet_client_id: Option<&str>,
    client_id: &str,
) -> PayoutWalletScope {
    let wallet_client_id = wallet_client_id.unwrap_or("");
    if wallet_consent_scope == Some(SN_WALLET_CONSENT_SCOPE_HOTKEY) {
        PayoutWalletScope::Hotkey
    } else if wallet_client_id.is_empty() {
        PayoutWalletScope::Network
    } else if wallet_client_id == client_id
        || parse_id(wallet_client_id).as_deref() == Some(client_id)
    {
        PayoutWalletScope::ThisProvider
    } else {
        PayoutWalletScope::AnotherProvider
    }
}

/// One provider contract, as the C ABI's contract details listeners deliver it (Go field names).
#[derive(Clone, Debug, Default, Deserialize)]
#[serde(rename_all = "PascalCase")]
pub struct ContractDetails {
    pub contract_id: Option<String>,
    pub contract_transfer_path: Option<TransferPath>,
}

/// The source, destination and stream of a contract.
#[derive(Clone, Debug, Default, Deserialize)]
#[serde(rename_all = "PascalCase")]
pub struct TransferPath {
    pub source_id: Option<String>,
    pub destination_id: Option<String>,
    pub stream_id: Option<String>,
}

/// The peer of one provider contract, by direction as the SDK's contract screens resolve it: the
/// source of a receive (ingress) contract, the destination of a send (egress) contract. A path
/// without that client id is keyed by its stream id, then by the contract id. None when the
/// contract names no id at all.
pub fn contract_peer_key(details: &ContractDetails, receive: bool) -> Option<String> {
    // an id that parses and is not the all-zero id, in canonical form
    let present = |id: &Option<String>| id.as_deref().and_then(parse_id).filter(|id| id != ZERO_ID);
    if let Some(path) = &details.contract_transfer_path {
        let peer_id = if receive {
            &path.source_id
        } else {
            &path.destination_id
        };
        if let Some(peer_id) = present(peer_id) {
            return Some(peer_id);
        }
        if let Some(stream_id) = present(&path.stream_id) {
            return Some(format!("stream:{stream_id}"));
        }
    }
    present(&details.contract_id).map(|contract_id| format!("contract:{contract_id}"))
}

/// The distinct clients that held a contract with this provider since the app started. Safe for
/// concurrent use: the SDK delivers contract details on its own threads.
pub struct ClientsServed {
    limit: usize,
    state: Mutex<ClientsServedState>,
}

/// The counted peers, guarded by [`ClientsServed::state`].
#[derive(Default)]
struct ClientsServedState {
    /// set of [`contract_peer_key`] values
    peer_keys: HashSet<String>,
    at_limit: bool,
}

impl ClientsServed {
    /// An empty count that keeps at most `limit` distinct peers.
    pub fn new(limit: usize) -> Self {
        Self {
            limit,
            state: Mutex::new(ClientsServedState::default()),
        }
    }

    /// Counts the peer of one provider contract.
    pub fn add(&self, details: &ContractDetails, receive: bool) {
        let Some(peer_key) = contract_peer_key(details, receive) else {
            return;
        };
        let mut state = self.state.lock().unwrap_or_else(PoisonError::into_inner);
        if state.peer_keys.contains(&peer_key) {
            return;
        }
        if self.limit <= state.peer_keys.len() {
            state.at_limit = true;
            return;
        }
        state.peer_keys.insert(peer_key);
    }

    /// The distinct count, and whether the count stopped at the limit.
    pub fn count(&self) -> (usize, bool) {
        let state = self.state.lock().unwrap_or_else(PoisonError::into_inner);
        (state.peer_keys.len(), state.at_limit)
    }
}