Developer SDK

Python examples

Install the SDK · View source on GitHub ↗

provider/session.py

python
"""A running provider over the SDK's C ABI, through the urnetwork package
(ctypes): the network space manager, the provider device with the
installation's identity, and the listeners that feed its status.

SDK callbacks run on SDK threads. They copy what they carry, then either count
it under the clients-served lock or hand it to the run loop through the events
queue; the run loop's thread owns every other field and makes every other SDK
call. The ctypes callback objects stay referenced for the life of the process,
because the SDK can still answer a wallet read after the device closes.

The urnetwork package is passed in rather than imported, so that the self-test
never loads the native runtime and the tests can run the lifecycle against a
stand-in for the C ABI."""

from contextlib import ExitStack
import ctypes as C
import os
import queue
import sys
import time

from state import (
    CLIENT_JWT_FILE_NAME,
    IDENTITY_FILE_NAME,
    ConfigError,
    ProviderIdentity,
    provider_key_material,
    save_provider_identity,
    write_private_file,
)
from status import (
    CLIENTS_SERVED_LIMIT,
    PAYOUT_WALLET_CHECKING,
    PAYOUT_WALLET_NOT_SET,
    PAYOUT_WALLET_UNAVAILABLE,
    PROVIDE_MODE_NONE,
    PROVIDE_MODE_PUBLIC,
    ClientsServed,
    ProviderStatus,
    json_text,
    parse_client_limit_status,
    parse_data_provided_byte_count,
    parse_json_object,
    payout_wallet_scope,
    provider_state,
)

# How often the status is read, and the longest gap between status lines.
STATUS_POLL_INTERVAL_SECONDS = 1
STATUS_REPEAT_INTERVAL_SECONDS = 60

# How often the payout wallet is read again. The wallet is fixed; a reread shows
# a mapping that the backend completes while the provider runs.
WALLET_SYNC_INTERVAL_SECONDS = 10 * 60

# The device description and spec recorded for this installation's device.
DEVICE_DESCRIPTION = "Python provider example"
DEVICE_SPEC = "urnetwork-examples/python-provider"
APP_VERSION = "1"

# The provider extender role's two device settings (PROVIDER_CONTRACT.md,
# "Extender role"), passed explicitly and both on. PROVIDE_EXTENDER_ENABLED is
# the embedder's hard switch: False means the role never runs.
# DEFAULT_PROVIDE_EXTENDER is the setting the device uses until the user sets
# one: False turns the default off.
PROVIDE_EXTENDER_ENABLED = True
DEFAULT_PROVIDE_EXTENDER = True

# the ur.network main network space, as the integration helpers create it
NETWORK_SPACE_KEY_JSON = b'{"host_name":"ur.network","env_name":"main"}'
NETWORK_SPACE_VALUES_JSON = b'{"migration_host_name":"bringyour.com"}'

# run loop events, each a tuple that starts with one of these
EVENT_STOP = "stop"
EVENT_JWT_REFRESHED = "jwt refreshed"
EVENT_AUTH_LOGOUT = "auth logout"
EVENT_WALLET_SYNCED = "wallet synced"

# ctypes callback objects that the SDK may still call; one set per session
_callback_roots = []


def take_string(raw, pointer) -> str | None:
    """The text of a string that the C ABI returned, freed after the copy; None
    for NULL."""
    if not pointer:
        return None
    try:
        return C.string_at(pointer).decode("utf-8", errors="replace")
    finally:
        raw.urnet_free_string(pointer)


def configure_sdk_logs(sdk, log_dir: str):
    """Keeps the SDK's log files in log_dir, which the SDK bounds (16 MiB files, the
    newest four kept at each start), instead of the system temp directory. The
    SDK also copies its log lines to stderr, and the C ABI keeps that copy.
    Raises OSError."""
    os.makedirs(log_dir, mode=0o700, exist_ok=True)
    error = C.c_void_p()
    if not sdk.raw.urnet_set_log_dir(log_dir.encode("utf-8"), C.byref(error)):
        raise OSError(take_string(sdk.raw, error.value) or "the sdk refused the log directory")


def new_key_material(raw, key_material) -> int:
    """A native key material handle for the device constructor, which the caller
    releases after the call; 0 without key material (the first run)."""
    if key_material is None:
        return 0

    def buffer(data: bytes):
        if not data:
            return None, 0
        return (C.c_uint8 * len(data)).from_buffer_copy(data), len(data)

    seed, seed_length = buffer(key_material.client_key_seed)
    certificate, certificate_length = buffer(key_material.provide_tls_certificate_pem)
    private_key, private_key_length = buffer(key_material.provide_tls_private_key_pem)
    handle = raw.urnet_new_device_local_key_material(
        seed,
        seed_length,
        certificate,
        certificate_length,
        private_key,
        private_key_length,
    )
    if not handle:
        raise RuntimeError("the sdk did not create the key material")
    if key_material.extender_key_seed:
        extender_seed, extender_seed_length = buffer(key_material.extender_key_seed)
        raw.urnet_device_local_key_material_set_extender_key_seed(handle, extender_seed, extender_seed_length)
    return handle


def read_device_bytes(getter, device: int) -> bytes:
    """Bytes from a buffer-out getter of the C ABI: the first call asks for the
    size, the second copies. b"" when the device has none."""
    size = C.c_int32(0)
    getter(device, None, C.byref(size))
    if size.value <= 0:
        return b""
    buffer = (C.c_uint8 * size.value)()
    if not getter(device, buffer, C.byref(size)):
        return b""
    return bytes(buffer[: size.value])


class ProviderSession:
    """One run of the provider. The constructor starts providing; run shows the
    status until a stop request; close stops providing."""

    def __init__(self, config, sdk, events: queue.SimpleQueue):
        """Creates the provider device with the installation's identity and the
        extender role's settings on, saves a new identity on first run, and starts
        providing publicly. The SDK declares provide intent on the device's
        platform connections by itself while the provide mode is public. sdk is
        the urnetwork package; events is the run loop's queue, which also
        carries stop requests."""
        self._config = config
        self._raw = sdk.raw
        self._events = events
        self._clients_served = ClientsServed(CLIENTS_SERVED_LIMIT)
        # PAYOUT_WALLET_CHECKING, PAYOUT_WALLET_UNAVAILABLE, PAYOUT_WALLET_NOT_SET
        # or the mapped coldkey
        self._payout_wallet = PAYOUT_WALLET_CHECKING
        self._payout_wallet_scope = ""
        self._subs = []
        self._closed = False

        callback_types = sdk._raw
        self._jwt_refresh_callback = callback_types.urnet_jwt_refresh_cb(self._jwt_refreshed)
        self._auth_logout_callback = callback_types.urnet_auth_logout_cb(self._auth_logout)
        self._ingress_callback = callback_types.urnet_contract_details_change_cb(self._ingress_contract_details_changed)
        self._egress_callback = callback_types.urnet_contract_details_change_cb(self._egress_contract_details_changed)
        self._wallet_callback = callback_types.urnet_sn_get_wallet_cb(self._wallet_synced)
        _callback_roots.extend(
            (
                self._jwt_refresh_callback,
                self._auth_logout_callback,
                self._ingress_callback,
                self._egress_callback,
                self._wallet_callback,
            )
        )

        raw = self._raw
        # on an error the stack closes what exists, in reverse order
        with ExitStack() as stack:
            manager = stack.enter_context(sdk.Handle(raw.urnet_new_network_space_manager_no_storage()))
            stack.callback(raw.urnet_network_space_manager_close, manager.handle)
            space = stack.enter_context(
                sdk.Handle(
                    raw.urnet_network_space_manager_update_network_space_values(
                        manager.handle,
                        NETWORK_SPACE_KEY_JSON,
                        NETWORK_SPACE_VALUES_JSON,
                    )
                )
            )
            api = stack.enter_context(sdk.Handle(raw.urnet_network_space_get_api(space.handle)))
            raw.urnet_api_set_by_jwt(api.handle, config.client_jwt.encode())
            self._device = stack.enter_context(sdk.Device(self._new_device(space.handle)))
            if config.identity is None:
                # keep the new identity, so later starts present the same provider
                self._save_new_identity()
            device = self._device.handle
            self._subs = [
                raw.urnet_device_add_jwt_refresh_listener(device, self._jwt_refresh_callback, None),
                raw.urnet_device_add_auth_logout_listener(device, self._auth_logout_callback, None),
                raw.urnet_device_add_provider_ingress_contract_details_change_listener(device, self._ingress_callback, None),
                raw.urnet_device_add_provider_egress_contract_details_change_listener(device, self._egress_callback, None),
            ]
            stack.callback(self._close_subs)
            raw.urnet_device_set_provide_mode(device, PROVIDE_MODE_PUBLIC)
            # close unwinds this stack: the subscriptions, the device, then the manager
            self._close_stack = stack.pop_all()
        self.sync_wallet()

    def _new_device(self, space: int) -> int:
        """Creates the device with the extender-aware constructor: one call for both
        runs. On first run there is no identity, the key material is 0 and the
        device makes a new identity, which the caller saves."""
        raw = self._raw
        config = self._config
        key_material = new_key_material(raw, provider_key_material(config.identity))
        try:
            error = C.c_void_p()
            device = raw.urnet_new_device_local_with_provide_extender(
                space,
                config.client_jwt.encode(),
                DEVICE_DESCRIPTION.encode(),
                DEVICE_SPEC.encode(),
                APP_VERSION.encode(),
                config.instance_id.encode(),
                False,
                key_material,
                PROVIDE_EXTENDER_ENABLED,
                DEFAULT_PROVIDE_EXTENDER,
                C.byref(error),
            )
            message = take_string(raw, error.value)
        finally:
            if key_material:
                raw.urnet_release(key_material)
        if message:
            raise RuntimeError(message)
        if not device:
            raise RuntimeError("the sdk did not create the device")
        return device

    def _save_new_identity(self):
        """Saves the device's new identity as identity.json, on first run."""
        raw = self._raw
        device = self._device.handle
        identity = ProviderIdentity(
            client_id=self._config.client_id,
            client_key_seed=read_device_bytes(raw.urnet_device_local_get_client_key_seed, device),
            provide_tls_certificate_pem=read_device_bytes(raw.urnet_device_local_get_provide_tls_certificate_pem, device),
            provide_tls_private_key_pem=read_device_bytes(raw.urnet_device_local_get_provide_tls_private_key_pem, device),
            extender_key_seed=read_device_bytes(raw.urnet_device_local_get_extender_key_seed, device),
        )
        if len(identity.client_key_seed) != 32:
            raise RuntimeError("the device has no provider identity to save")
        try:
            save_provider_identity(self._config.state_dir, identity)
        except OSError as error:
            raise RuntimeError(f"save {IDENTITY_FILE_NAME}: {error}") from None

    def status(self) -> ProviderStatus:
        """Reads the status from the device getters and the listener state."""
        raw = self._raw
        device = self._device.handle
        # "client_limit_exceeded" with the hold's end in RetryTime while the
        # platform holds this client off for its network's client limit
        client_limit_status, client_limit_retry_time = parse_client_limit_status(
            take_string(raw, raw.urnet_device_get_client_limit_status(device))
        )
        # urnet_device_get_provider_ready also waits for processed client key
        # registration, which default device settings do not enable, so the
        # connected carrier is the readiness signal here
        state = provider_state(
            raw.urnet_device_get_provide_mode(device),
            client_limit_status,
            raw.urnet_device_get_provide_paused(device),
            raw.urnet_device_get_provide_enabled(device),
            raw.urnet_device_local_get_provider_connected(device),
        )
        data_provided_byte_count = parse_data_provided_byte_count(
            take_string(raw, raw.urnet_device_get_provider_packet_stats(device))
        )
        clients_served, clients_served_at_limit = self._clients_served.count()
        return ProviderStatus(
            state=state,
            client_limit_retry_time=client_limit_retry_time,
            clients_served=clients_served,
            clients_served_at_limit=clients_served_at_limit,
            data_provided_byte_count=data_provided_byte_count,
            payout_wallet=self._payout_wallet,
            payout_wallet_scope=self._payout_wallet_scope,
        )

    def sync_wallet(self):
        """Reads the payout wallet (GET /sn/wallet with the client credential). The
        app only displays the wallet: the backend maps it, never the app."""
        self._raw.urnet_device_local_sync_sn_wallet(self._device.handle, self._wallet_callback, None)

    def run(self):
        """Prints status lines until a stop request. Raises ConfigError when the
        server rejects the client credential."""
        last_key = None
        last_print_time = 0.0
        next_wallet_sync_time = time.monotonic() + WALLET_SYNC_INTERVAL_SECONDS
        while True:
            status = self.status()
            now = time.monotonic()
            if status.key() != last_key or STATUS_REPEAT_INTERVAL_SECONDS <= now - last_print_time:
                print(status.line())
                last_key = status.key()
                last_print_time = now
            if next_wallet_sync_time <= now:
                self.sync_wallet()
                next_wallet_sync_time = now + WALLET_SYNC_INTERVAL_SECONDS
            if self._apply_events_until(now + STATUS_POLL_INTERVAL_SECONDS):
                return

    def _apply_events_until(self, deadline: float) -> bool:
        """Applies run loop events as they arrive until the deadline; True when a
        stop was requested."""
        while True:
            timeout = deadline - time.monotonic()
            if timeout <= 0:
                return False
            try:
                event = self._events.get(timeout=timeout)
            except queue.Empty:
                return False
            if self._apply_event(event):
                return True

    def _apply_event(self, event: tuple) -> bool:
        """Applies one run loop event; True for a stop request. Raises ConfigError
        when the server rejected the client credential."""
        kind = event[0]
        if kind == EVENT_STOP:
            return True
        if kind == EVENT_AUTH_LOGOUT:
            raise ConfigError("the server rejected the client credential; issue a new scoped client JWT from your backend")
        if kind == EVENT_JWT_REFRESHED:
            self._save_client_jwt(event[1])
        elif kind == EVENT_WALLET_SYNCED:
            self._record_wallet_read(event[1], event[2])
        return False

    def close(self):
        """Stops providing, closes the subscriptions, the device and then the
        manager, and saves a refreshed credential that arrived meanwhile."""
        if self._closed:
            return
        self._closed = True
        self._raw.urnet_device_set_provide_mode(self._device.handle, PROVIDE_MODE_NONE)
        self._close_stack.close()
        # keep a refresh that arrived after the run loop's last read
        while True:
            try:
                event = self._events.get_nowait()
            except queue.Empty:
                break
            if event[0] == EVENT_JWT_REFRESHED:
                self._save_client_jwt(event[1])
        print("status: stopped")

    def _close_subs(self):
        """Closes and releases the listener subscriptions."""
        for sub in self._subs:
            self._raw.urnet_sub_close(sub)
            self._raw.urnet_release(sub)
        self._subs = []

    def _save_client_jwt(self, client_jwt: bytes | None):
        """Keeps the refreshed credential, so the next start uses a valid token."""
        if not client_jwt:
            return
        try:
            write_private_file(os.path.join(self._config.state_dir, CLIENT_JWT_FILE_NAME), client_jwt + b"\n")
        except OSError as error:
            # never print the token itself
            print(f"could not save the refreshed client credential: {error}", file=sys.stderr)

    def _record_wallet_read(self, result_json: bytes | None, error_text: bytes | None):
        """Records a payout wallet read. A failure keeps the last known wallet."""
        result = parse_json_object(result_json)
        if error_text is not None or result is None or result.get("error") is not None:
            if self._payout_wallet == PAYOUT_WALLET_CHECKING:
                self._payout_wallet = PAYOUT_WALLET_UNAVAILABLE
            return
        # the sdk caches the effective wallet before the callback: this client's
        # own consent, else the network consent, else (with hotkey delegations)
        # the network's hotkey entry, else a non-consent wallet
        wallet = parse_json_object(take_string(self._raw, self._raw.urnet_device_local_get_sn_wallet(self._device.handle)))
        coldkey = json_text(wallet.get("coldkey_ss58")) if wallet else ""
        if not coldkey:
            self._payout_wallet = PAYOUT_WALLET_NOT_SET
            self._payout_wallet_scope = ""
            return
        self._payout_wallet = coldkey
        self._payout_wallet_scope = payout_wallet_scope(
            json_text(wallet.get("consent_scope")),
            json_text(wallet.get("client_id")),
            self._config.client_id,
        )

    def _jwt_refreshed(self, _user_data, client_jwt):
        """Hands a refreshed client JWT to the run loop, which saves it. Runs on an
        SDK thread."""
        self._events.put((EVENT_JWT_REFRESHED, client_jwt))

    def _auth_logout(self, _user_data):
        """Ends the run: the server no longer accepts this client's credential. Runs
        on an SDK thread."""
        self._events.put((EVENT_AUTH_LOGOUT,))

    def _ingress_contract_details_changed(self, _user_data, details_json):
        """Counts the peer of a receive contract. Runs on an SDK thread."""
        self._clients_served.add(parse_json_object(details_json), receive=True)

    def _egress_contract_details_changed(self, _user_data, details_json):
        """Counts the peer of a send contract. Runs on an SDK thread."""
        self._clients_served.add(parse_json_object(details_json), receive=False)

    def _wallet_synced(self, _user_data, result_json, error_text):
        """Hands a payout wallet read to the run loop. Runs on an SDK thread."""
        self._events.put((EVENT_WALLET_SYNCED, result_json, error_text))