//! The status that every embed example shows, with the exact text rules of EMBED_CONTRACT.md
//! ("Status"): the status, the data used this month and the running total. Everything here is pure,
//! so the self-test checks it without the native SDK, a network or credentials.
use std::{
fmt,
time::{Duration, Instant},
};
use crate::caps::{CAPPED_REASON_MONTHLY, CapReading};
/// 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 concurrent client limit
/// (`URNET_CLIENT_LIMIT_STATUS_EXCEEDED`).
pub const CLIENT_LIMIT_STATUS_EXCEEDED: &str = "client_limit_exceeded";
/// How long the console waits before it repeats an unchanged status line.
pub const STATUS_REPEAT_INTERVAL: Duration = Duration::from_secs(60);
/// What the status rules read, in their order.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct StatusInputs {
/// a GUI's device runs; the console is always started
pub started: bool,
/// a GUI after an auth logout, or a 401 or 409 from the token server, until started again
pub signed_out: bool,
/// `""` or `"client_limit_exceeded"`
pub client_limit_status: String,
/// the end of the client limit hold in unix milliseconds, 0 when there is none
pub client_limit_retry_time: i64,
pub cap_reading: CapReading,
/// `ProviderStateAdded` of the window status
pub providers_added: i64,
}
impl StatusInputs {
/// A started console device that has read nothing yet.
pub fn started() -> Self {
Self {
started: true,
signed_out: false,
client_limit_status: CLIENT_LIMIT_STATUS_NONE.to_string(),
client_limit_retry_time: 0,
cap_reading: CapReading::Checking,
providers_added: 0,
}
}
/// A GUI before its first start.
pub fn stopped() -> Self {
Self {
started: false,
..Self::started()
}
}
}
/// One status snapshot: the three fields as text.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct EmbedStatus {
pub status: String,
pub data_this_month: String,
pub data_total: String,
}
impl EmbedStatus {
/// The fields for the inputs.
pub fn new(inputs: &StatusInputs) -> Self {
Self {
status: status_text(inputs),
data_this_month: data_field_text(&inputs.cap_reading, DataField::Monthly),
data_total: data_field_text(&inputs.cap_reading, DataField::Total),
}
}
}
impl fmt::Display for EmbedStatus {
/// The console status line:
///
/// ```text
/// status: connected | data this month: 1.2 GB of 5.0 GB | data total: no cap
/// ```
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
formatter,
"status: {} | data this month: {} | data total: {}",
self.status, self.data_this_month, self.data_total
)
}
}
/// The status field: the first rule that applies.
///
/// 1. `signed out`, after an auth logout or a token server refusal, until started again (GUI);
/// 2. `stopped`, before start or after stop (GUI);
/// 3. `client limit`, while the platform holds this client off for its network's client limit,
/// with the retry time;
/// 4. `paused`, while the latest cap reading is capped and the cap that `capped_reason` names is 0;
/// 5. `data cap reached, resets YYYY-MM-DD HH:MM UTC`, while capped by the monthly cap;
/// 6. `data cap reached`, while capped by the running total, or with a period end that does not
/// parse, or an unknown reason;
/// 7. `connected`, while the window has at least one provider added;
/// 8. `connecting` otherwise.
pub fn status_text(inputs: &StatusInputs) -> String {
if inputs.signed_out {
return "signed out".to_string();
}
if !inputs.started {
return "stopped".to_string();
}
if inputs.client_limit_status == CLIENT_LIMIT_STATUS_EXCEEDED {
return client_limit_text(inputs.client_limit_retry_time);
}
if let Some(data_cap) = inputs.cap_reading.data_cap().filter(|cap| cap.capped) {
if data_cap.named_cap_limit() == Some(Some(0)) {
return "paused".to_string();
}
let reset_text = if data_cap.capped_reason == CAPPED_REASON_MONTHLY {
data_cap
.monthly_period_end
.as_deref()
.and_then(reset_time_text)
} else {
None
};
// the running total, a period end that does not parse, or an unknown reason: no reset time
return match reset_text {
Some(reset_text) => format!("data cap reached, {reset_text}"),
None => "data cap reached".to_string(),
};
}
if 1 <= inputs.providers_added {
"connected".to_string()
} else {
"connecting".to_string()
}
}
/// Which data field.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum DataField {
/// data this month: `monthly_used_byte_count` of `monthly_byte_limit`
Monthly,
/// data total: `total_used_byte_count` of `total_byte_limit`
Total,
}
/// A data field: `checking` until the first cap reading, `unavailable` if that reading failed,
/// `no cap` for a null limit (never a used count: a server need not report usage for an uncapped
/// client), otherwise `<used> of <limit>`.
pub fn data_field_text(cap_reading: &CapReading, field: DataField) -> String {
match cap_reading {
CapReading::Checking => "checking".to_string(),
CapReading::Unavailable => "unavailable".to_string(),
CapReading::Read(data_cap) => {
let (used, limit) = match field {
DataField::Monthly => (
data_cap.monthly_used_byte_count,
data_cap.monthly_byte_limit,
),
DataField::Total => (data_cap.total_used_byte_count, data_cap.total_byte_limit),
};
match limit {
None => "no cap".to_string(),
Some(limit) => format!(
"{} of {}",
format_byte_count(used),
format_byte_count(limit)
),
}
}
}
}
/// `client limit, retry at HH:MM UTC`: the retry time (unix milliseconds) rounded up to the next
/// whole minute in UTC, so the shown time is never before the real retry; plain `client limit` when
/// the retry time is 0.
pub fn client_limit_text(retry_time: i64) -> String {
if retry_time <= 0 {
return "client limit".to_string();
}
let retry_minute = (retry_time as u64).div_ceil(60 * 1000);
let hour = (retry_minute / 60) % 24;
let minute = retry_minute % 60;
format!("client limit, retry at {hour:02}:{minute:02} UTC")
}
/// Decimal units with one decimal, because data plans and the Embed plan's monthly data budget are
/// sold in them: `0 B`, `999 B`, `1.0 kB`, `1.2 GB`. The tenths round half to even on the exact
/// integer, never on a binary fraction, so 1050 bytes is `1.0 kB` and 1150 bytes `1.2 kB`; a value
/// that rounds to 1000.0 moves to the next unit, so 999999 bytes is `1.0 MB`.
pub fn format_byte_count(byte_count: u64) -> String {
if byte_count < 1000 {
return format!("{byte_count} B");
}
let units = ["kB", "MB", "GB", "TB", "PB", "EB"];
// the bytes in a tenth of the unit
let mut tenth: u64 = 100;
let mut unit_index = 0;
loop {
let mut tenths = byte_count / tenth;
let remainder = byte_count % tenth;
if tenth < 2 * remainder || (2 * remainder == tenth && tenths % 2 == 1) {
tenths += 1;
}
if tenths < 10000 || unit_index == units.len() - 1 {
return format!("{}.{} {}", tenths / 10, tenths % 10, units[unit_index]);
}
tenth *= 1000;
unit_index += 1;
}
}
/// The line the console app prints once the device runs (EMBED_CONTRACT.md, "Status").
pub fn start_line(client_id: &str, instance_id: &str) -> String {
format!("embed client {client_id}, installation {instance_id}")
}
/// `resets YYYY-MM-DD HH:MM UTC` for a `monthly_period_end` in RFC 3339, converted to UTC with the
/// seconds rounded up to the next whole minute. None when the time does not parse.
pub fn reset_time_text(monthly_period_end: &str) -> Option<String> {
let (seconds, nanos) = parse_rfc3339(monthly_period_end)?;
// round up: a period end of 23:59:00.001 resets at 00:00
let minutes = if seconds.rem_euclid(60) == 0 && nanos == 0 {
seconds.div_euclid(60)
} else {
seconds.div_euclid(60) + 1
};
let days = minutes.div_euclid(24 * 60);
let minute_of_day = minutes.rem_euclid(24 * 60);
let (year, month, day) = civil_from_days(days);
Some(format!(
"resets {year:04}-{month:02}-{day:02} {:02}:{:02} UTC",
minute_of_day / 60,
minute_of_day % 60
))
}
/// An RFC 3339 date-time (`2026-10-31T19:00:00.5-05:00`, `2026-11-01T00:00:00Z`) as UTC unix seconds
/// and nanoseconds.
pub fn parse_rfc3339(text: &str) -> Option<(i64, u32)> {
let bytes = text.as_bytes();
let digits = |start: usize, count: usize| -> Option<i64> {
let part = bytes.get(start..start + count)?;
if !part.iter().all(u8::is_ascii_digit) {
return None;
}
std::str::from_utf8(part).ok()?.parse().ok()
};
let year = digits(0, 4)?;
if bytes.get(4) != Some(&b'-') || bytes.get(7) != Some(&b'-') {
return None;
}
let month = digits(5, 2)?;
let day = digits(8, 2)?;
if !matches!(bytes.get(10), Some(b'T' | b't' | b' ')) {
return None;
}
let hour = digits(11, 2)?;
if bytes.get(13) != Some(&b':') || bytes.get(16) != Some(&b':') {
return None;
}
let minute = digits(14, 2)?;
let second = digits(17, 2)?;
let mut index = 19;
let mut nanos: u32 = 0;
if bytes.get(index) == Some(&b'.') {
index += 1;
let start = index;
while bytes.get(index).is_some_and(u8::is_ascii_digit) {
index += 1;
}
let fraction = &text[start..index];
if fraction.is_empty() {
return None;
}
// nanoseconds: the first nine digits; any further digit rounds the fraction up by one
let mut padded: String = fraction.chars().take(9).collect();
while padded.len() < 9 {
padded.push('0');
}
nanos = padded.parse().ok()?;
if fraction.len() > 9 && fraction[9..].bytes().any(|b| b != b'0') {
nanos = nanos.saturating_add(1);
}
}
let offset_seconds = match bytes.get(index) {
Some(b'Z' | b'z') if index + 1 == bytes.len() => 0,
Some(sign @ (b'+' | b'-')) if index + 6 == bytes.len() && bytes[index + 3] == b':' => {
let offset_hour = digits(index + 1, 2)?;
let offset_minute = digits(index + 4, 2)?;
if 23 < offset_hour || 59 < offset_minute {
return None;
}
let offset = offset_hour * 3600 + offset_minute * 60;
if *sign == b'+' { offset } else { -offset }
}
_ => return None,
};
if !(1..=12).contains(&month)
|| day < 1
|| days_in_month(year, month) < day
|| 23 < hour
|| 59 < minute
|| 60 < second
{
return None;
}
let days = days_from_civil(year, month, day);
let local_seconds = days * 86400 + hour * 3600 + minute * 60 + second;
let mut seconds = local_seconds - offset_seconds;
// a fraction of 1e9 after rounding carries into the seconds
if 1_000_000_000 <= nanos {
nanos -= 1_000_000_000;
seconds += 1;
}
Some((seconds, nanos))
}
/// Days in a month of the proleptic Gregorian calendar.
fn days_in_month(year: i64, month: i64) -> i64 {
match month {
1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
4 | 6 | 9 | 11 => 30,
_ if (year % 4 == 0 && year % 100 != 0) || year % 400 == 0 => 29,
_ => 28,
}
}
/// Days since 1970-01-01 of a civil date (Howard Hinnant's algorithm).
pub fn days_from_civil(year: i64, month: i64, day: i64) -> i64 {
let year = if month <= 2 { year - 1 } else { year };
let era = year.div_euclid(400);
let year_of_era = year - era * 400;
let month_index = (month + 9) % 12;
let day_of_year = (153 * month_index + 2) / 5 + day - 1;
let day_of_era = year_of_era * 365 + year_of_era / 4 - year_of_era / 100 + day_of_year;
era * 146097 + day_of_era - 719468
}
/// The civil date of days since 1970-01-01 (Howard Hinnant's algorithm).
pub fn civil_from_days(days: i64) -> (i64, i64, i64) {
let days = days + 719468;
let era = days.div_euclid(146097);
let day_of_era = days - era * 146097;
let year_of_era =
(day_of_era - day_of_era / 1460 + day_of_era / 36524 - day_of_era / 146096) / 365;
let day_of_year = day_of_era - (365 * year_of_era + year_of_era / 4 - year_of_era / 100);
let month_index = (5 * day_of_year + 2) / 153;
let day = day_of_year - (153 * month_index + 2) / 5 + 1;
let month = if month_index < 10 {
month_index + 3
} else {
month_index - 9
};
let year = year_of_era + era * 400 + if month <= 2 { 1 } else { 0 };
(year, month, day)
}
/// Decides when the console prints a status line: at once when any field's text changes, otherwise
/// once every [`STATUS_REPEAT_INTERVAL`].
#[derive(Default)]
pub struct StatusLines {
last_line: 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: &EmbedStatus, now: Instant) -> Option<String> {
let line = status.to_string();
let changed = self.last_line.as_deref() != Some(line.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_line = Some(line.clone());
self.last_print_time = Some(now);
Some(line)
}
}