Developer SDK

Python examples

Install the SDK · View source on GitHub ↗

embed/status.py

python
"""The status that every embed example shows, with the exact rules of
EMBED_CONTRACT.md ("Status"): the status field, data this month and data total.
Pure Python, so the self-test checks every rule and golden vector without the
native SDK, a network or credentials."""

from dataclasses import dataclass
from datetime import datetime, timedelta, timezone
import json
import re

from caps import CAPPED_REASON_MONTHLY, CAPPED_REASON_TOTAL, EMBED_NOT_ENABLED, CapReading, EmbedNotEnabled

# the status field, in rule order. Console examples never show the first two.
STATUS_SIGNED_OUT = "signed out"
STATUS_STOPPED = "stopped"
# the platform disconnected this client for its network's concurrent client
# limit, and the SDK holds its platform connections until the retry time
STATUS_CLIENT_LIMIT = "client limit"
STATUS_PAUSED = "paused"
STATUS_DATA_CAP_REACHED = "data cap reached"
STATUS_CONNECTED = "connected"
STATUS_CONNECTING = "connecting"

# the data fields before a reading, when the first reading failed, and for a
# cap that is not set
DATA_CHECKING = "checking"
DATA_UNAVAILABLE = "unavailable"
DATA_NO_CAP = "no cap"

# client limit status values (URNET_CLIENT_LIMIT_STATUS_NONE and _EXCEEDED)
CLIENT_LIMIT_STATUS_NONE = ""
CLIENT_LIMIT_STATUS_EXCEEDED = "client_limit_exceeded"

# decimal units, because data plans and the Embed plan's budget are sold in them
DECIMAL_UNITS = ("kB", "MB", "GB", "TB", "PB", "EB")

# RFC 3339 with optional fractional seconds, as Go writes time.Time in JSON
RFC3339_PATTERN = re.compile(
    r"\A(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?(?:([Zz])|([+-])(\d{2}):(\d{2}))\Z"
)

MINUTE_MILLIS = 60 * 1000
MINUTES_PER_DAY = 24 * 60


def format_byte_count(byte_count: int) -> str:
    """Decimal units with one decimal: "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"."""
    if byte_count < 1000:
        return f"{byte_count} B"
    # the bytes in a tenth of the unit
    tenth = 100
    for unit_index, unit in enumerate(DECIMAL_UNITS):
        tenths, remainder = divmod(byte_count, tenth)
        if tenth < 2 * remainder or (2 * remainder == tenth and tenths % 2 == 1):
            tenths += 1
        if tenths < 10000 or unit_index == len(DECIMAL_UNITS) - 1:
            return f"{tenths // 10}.{tenths % 10} {unit}"
        tenth *= 1000
    raise AssertionError("unreachable")


def start_line(client_id: str, instance_id: str) -> str:
    """The line the console app prints once the device runs (EMBED_CONTRACT.md,
    "Status")."""
    return f"embed client {client_id}, installation {instance_id}"


def license_app(system: str) -> str:
    """The kind of app whose licenses --licenses prints, from platform.system():
    "apple" on macOS, "windows" on Windows, "linux" elsewhere."""
    return {"Darwin": "apple", "Windows": "windows"}.get(system, "linux")


def reset_time_text(monthly_period_end: str) -> str | None:
    """"resets YYYY-MM-DD HH:MM UTC" for a monthly period end in RFC 3339: in UTC,
    with the seconds rounded up to the next whole minute, so the shown time is
    never before the reset. None when the text does not parse."""
    match = RFC3339_PATTERN.match(monthly_period_end) if isinstance(monthly_period_end, str) else None
    if match is None:
        return None
    year, month, day, hour, minute, second = (int(group) for group in match.groups()[:6])
    fraction = match.group(7) or ""
    try:
        if match.group(8):
            offset = timedelta(0)
        else:
            offset_hours, offset_minutes = int(match.group(10)), int(match.group(11))
            if 23 < offset_hours or 59 < offset_minutes:
                return None
            offset = timedelta(hours=offset_hours, minutes=offset_minutes)
            if match.group(9) == "-":
                offset = -offset
        instant = datetime(year, month, day, hour, minute, second, tzinfo=timezone(offset))
        reset = instant.astimezone(timezone.utc).replace(second=0)
        if second or fraction.strip("0"):
            reset += timedelta(minutes=1)
    except (ValueError, OverflowError):
        return None
    return f"resets {reset:%Y-%m-%d %H:%M} UTC"


def client_limit_text(client_limit_retry_time: int) -> str:
    """"client limit, retry at HH:MM UTC": the retry time (unix milliseconds)
    rounded up to the next whole minute in UTC, as the provider contract rounds
    it, so the shown time is never before the retry; 0 shows "client limit"."""
    if client_limit_retry_time <= 0:
        return STATUS_CLIENT_LIMIT
    retry_minute = (client_limit_retry_time + MINUTE_MILLIS - 1) // MINUTE_MILLIS
    # unix time has no leap seconds, so every utc day is 24 * 60 minutes
    minute_of_day = retry_minute % MINUTES_PER_DAY
    return f"{STATUS_CLIENT_LIMIT}, retry at {minute_of_day // 60:02d}:{minute_of_day % 60:02d} UTC"


def capped_limit(reading: CapReading) -> int | None:
    """The limit of the cap that capped_reason names; None for an unknown reason
    or an unset cap."""
    if reading.capped_reason == CAPPED_REASON_MONTHLY:
        return reading.monthly_byte_limit
    if reading.capped_reason == CAPPED_REASON_TOTAL:
        return reading.total_byte_limit
    return None


def embed_status(
    started: bool,
    signed_out: bool,
    client_limit_status: str,
    client_limit_retry_time: int,
    reading: CapReading | None,
    providers_added: int,
) -> str:
    """The status field: the first rule that applies. signed out; stopped; client
    limit while the SDK holds this client off; paused while the latest reading
    is capped and the cap that capped_reason names is 0; data cap reached while
    capped, with the reset time for the monthly cap; connected once the window
    has a provider added; connecting otherwise."""
    if signed_out:
        return STATUS_SIGNED_OUT
    if not started:
        return STATUS_STOPPED
    if client_limit_status == CLIENT_LIMIT_STATUS_EXCEEDED:
        return client_limit_text(client_limit_retry_time)
    if reading is not None and reading.capped:
        if capped_limit(reading) == 0:
            return STATUS_PAUSED
        if reading.capped_reason == CAPPED_REASON_MONTHLY:
            reset = reset_time_text(reading.monthly_period_end)
            if reset is not None:
                return f"{STATUS_DATA_CAP_REACHED}, {reset}"
        return STATUS_DATA_CAP_REACHED
    if 1 <= providers_added:
        return STATUS_CONNECTED
    return STATUS_CONNECTING


class CapState:
    """The cap readings behind the data fields: none yet, a first reading that
    failed, or the latest successful reading, which a later failure keeps; the
    Embed-not-enabled refusal clears it. Owned by the run loop's thread."""

    def __init__(self, reading: CapReading | None = None):
        """No reading yet, or a first reading such as the token server's data_cap."""
        self.reading = reading
        self.failed = False

    def record(self, reading: CapReading | EmbedNotEnabled | None):
        """Records a reading; None is a failed read, and EMBED_NOT_ENABLED, the
        Embed-not-enabled refusal, clears the last reading, so both data fields
        read unavailable and the status rules see no cap reading."""
        if reading is EMBED_NOT_ENABLED:
            self.reading = None
            self.failed = True
        elif reading is not None:
            self.reading = reading
            self.failed = False
        elif self.reading is None:
            self.failed = True


def data_field_text(cap_state: CapState, monthly: bool) -> str:
    """Data this month (monthly) or data total: checking until the first reading;
    unavailable when it failed; no cap for an unset cap, never a used count;
    otherwise "<used> of <limit>"."""
    reading = cap_state.reading
    if reading is None:
        return DATA_UNAVAILABLE if cap_state.failed else DATA_CHECKING
    if monthly:
        limit, used = reading.monthly_byte_limit, reading.monthly_used_byte_count
    else:
        limit, used = reading.total_byte_limit, reading.total_used_byte_count
    if limit is None:
        return DATA_NO_CAP
    return f"{format_byte_count(used)} of {format_byte_count(limit)}"


@dataclass(frozen=True)
class EmbedStatus:
    """One status snapshot."""

    status: str
    data_this_month: str
    data_total: str

    def line(self) -> str:
        """The console status line."""
        return f"status: {self.status} | data this month: {self.data_this_month} | data total: {self.data_total}"


def status_snapshot(
    started: bool,
    signed_out: bool,
    client_limit_status: str,
    client_limit_retry_time: int,
    cap_state: CapState,
    providers_added: int,
) -> EmbedStatus:
    """The three status fields."""
    return EmbedStatus(
        status=embed_status(
            started,
            signed_out,
            client_limit_status,
            client_limit_retry_time,
            cap_state.reading,
            providers_added,
        ),
        data_this_month=data_field_text(cap_state, monthly=True),
        data_total=data_field_text(cap_state, monthly=False),
    )


def parse_json_object(text) -> dict | None:
    """A JSON object from the C ABI (str or bytes), or None for NULL, JSON null or
    anything that is not an object."""
    if not text:
        return None
    try:
        value = json.loads(text)
    except ValueError:
        return None
    return value if isinstance(value, dict) else None


def json_int(value) -> int:
    """A JSON integer field, or 0 when it is missing or not an integer."""
    if isinstance(value, int) and not isinstance(value, bool):
        return value
    return 0


def json_text(value) -> str:
    """A JSON string field, or "" when it is missing or not a string."""
    return value if isinstance(value, str) else ""


def parse_client_limit_status(status_json) -> tuple[str, int]:
    """The client limit status and its retry time (unix milliseconds) from the JSON
    of urnet_device_get_client_limit_status; NULL reads as no limit."""
    status = parse_json_object(status_json)
    if status is None:
        return CLIENT_LIMIT_STATUS_NONE, 0
    return json_text(status.get("Status")), json_int(status.get("RetryTime"))


def parse_providers_added(window_status_json) -> int:
    """ProviderStateAdded from the JSON of urnet_device_get_window_status; 0 before
    the window exists (NULL)."""
    window_status = parse_json_object(window_status_json)
    if window_status is None:
        return 0
    return json_int(window_status.get("ProviderStateAdded"))