Developer SDK

Python examples

Install the SDK · View source on GitHub ↗

embed/main.py

python
"""The Python embed example: a console app for Windows, macOS and Linux that
embeds the URnetwork SDK in your own product (EMBED_CONTRACT.md). It obtains
this installation's scoped client JWT from your token server (or uses the one
your backend wrote), starts a local device with it, and shows the status and
this client's own data caps. The device carries only the app's own traffic:
continue with the Sockets and Messages examples.

Usage: main.py [run] | --self-test | --licenses | --version. --licenses prints
the SDK's licenses and data attributions, as JSON, to publish with the app.

Settings:
- URNETWORK_EMBED_STATE_DIR: the installation's private state directory
  (state.py), absolute. Required.
- URNETWORK_TOKEN_SERVER_URL and URNETWORK_DEMO_SESSION: the token server
  origin and the demo session token. Optional, as a pair; without them the app
  uses the client.jwt already in the state directory.
- URNETWORK_API_URL: the API origin for the cap reads, default
  https://api.bringyour.com.

The self-test needs only Python; the other commands load the urnetwork package,
and a native library older than the package exits 78 (sdk_load.py).

Exit codes, for supervisors: 0 stopped on request, 78 configuration or
credential problem (restarting does not help), 1 any other failure."""

import os
import platform
import queue
import signal
import sys

from client_token import TokenServerError, TokenServerRefused, fetch_client_jwt
from sdk_load import SdkLoadError, load_urnetwork, sdk_mismatch_message
from state import (
    LOG_DIR_NAME,
    ConfigError,
    check_state_dir,
    load_client_jwt,
    load_or_create_instance_id,
    parse_client_jwt_client_id,
)
from status import license_app, start_line
from transport import DEFAULT_API_URL, check_origin, urllib_transport

EXIT_STOPPED = 0
EXIT_FAILURE = 1
# sysexits EX_CONFIG
EXIT_CONFIG = 78

USAGE = "usage: main.py [run] | --self-test | --licenses | --version"

TOKEN_SERVER_URL_SETTING = "URNETWORK_TOKEN_SERVER_URL"
DEMO_SESSION_SETTING = "URNETWORK_DEMO_SESSION"
API_URL_SETTING = "URNETWORK_API_URL"


def main():
    """Exits with the code of the command."""
    sys.stdout.reconfigure(line_buffering=True)
    try:
        exit_code = run(sys.argv[1:])
    except KeyboardInterrupt:
        # ctrl-c before the app installed its own handler
        exit_code = EXIT_STOPPED
    sys.exit(exit_code)


def run(args: list, transport=urllib_transport) -> int:
    """Runs one command and returns the exit code. transport makes the token server
    and cap requests; the self-test passes a stand-in."""
    if args == ["--self-test"]:
        from selftest import run_self_test

        try:
            run_self_test()
        except Exception as error:
            print(f"embed self-test failed: {error}", file=sys.stderr)
            return EXIT_FAILURE
        print("embed self-test passed")
        return EXIT_STOPPED
    if args in (["--version"], ["--licenses"]):
        try:
            urnetwork = load_urnetwork()
        except SdkLoadError as error:
            print(error, file=sys.stderr)
            return error.exit_code
        if args == ["--version"]:
            print(urnetwork.version())
            return EXIT_STOPPED
        from session import take_string

        try:
            licenses = take_string(urnetwork.raw, urnetwork.raw.urnet_get_licenses(license_app(platform.system()).encode()))
        except AttributeError as error:
            return report_sdk_failure(error, "could not read the sdk licenses")
        if licenses is None:
            print("the sdk returned no licenses", file=sys.stderr)
            return EXIT_FAILURE
        print(licenses)
        return EXIT_STOPPED
    if args not in ([], ["run"]):
        print(USAGE, file=sys.stderr)
        return EXIT_CONFIG
    return run_embed(transport)


def run_embed(transport) -> int:
    """Obtains the client JWT, runs the device until a stop request and returns the
    exit code."""
    state_dir = os.environ.get("URNETWORK_EMBED_STATE_DIR", "")
    try:
        check_state_dir(state_dir)
        instance_id = load_or_create_instance_id(state_dir)
        api_origin = check_origin(os.environ.get(API_URL_SETTING) or DEFAULT_API_URL, API_URL_SETTING)
        client_jwt, first_cap_reading = obtain_client_jwt(state_dir, instance_id, transport)
        client_id = parse_client_jwt_client_id(client_jwt)
    except (ConfigError, TokenServerRefused) as error:
        print(error, file=sys.stderr)
        return EXIT_CONFIG
    except TokenServerError as error:
        print(error, file=sys.stderr)
        return EXIT_FAILURE

    try:
        urnetwork = load_urnetwork()
    except SdkLoadError as error:
        print(error, file=sys.stderr)
        return error.exit_code
    from session import EVENT_STOP, EmbedConfig, EmbedSession, configure_sdk_logs

    try:
        configure_sdk_logs(urnetwork, os.path.join(state_dir, LOG_DIR_NAME))
    except (OSError, AttributeError) as error:
        return report_sdk_failure(error, "could not set the sdk log directory")

    # the run loop's events; a stop request is one of them. SimpleQueue.put is
    # safe in a signal handler, which can interrupt the main thread anywhere.
    events = queue.SimpleQueue()

    def request_stop(_signal_number, _frame):
        """Asks the run loop to stop; the app then exits with 0."""
        events.put((EVENT_STOP,))

    signal.signal(signal.SIGINT, request_stop)
    signal.signal(signal.SIGTERM, request_stop)
    config = EmbedConfig(
        state_dir=state_dir,
        client_jwt=client_jwt,
        client_id=client_id,
        instance_id=instance_id,
        api_origin=api_origin,
        first_cap_reading=first_cap_reading,
    )
    try:
        session = EmbedSession(config, urnetwork, events, transport)
    except Exception as error:
        return report_sdk_failure(error, "could not start the device")
    try:
        print(start_line(client_id, instance_id))
        session.run()
        return EXIT_STOPPED
    except ConfigError as error:
        # the server rejected the client credential
        print(error, file=sys.stderr)
        return EXIT_CONFIG
    finally:
        session.close()


def report_sdk_failure(error: Exception, doing: str) -> int:
    """Prints why an SDK call failed and returns the exit code: 78 with the SDK
    version mismatch line for a C ABI function that the native library lacks, 1
    otherwise."""
    mismatch = sdk_mismatch_message(error)
    if mismatch is not None:
        print(mismatch, file=sys.stderr)
        return EXIT_CONFIG
    print(f"{doing}: {error}", file=sys.stderr)
    return EXIT_FAILURE


def obtain_client_jwt(state_dir: str, instance_id: str, transport):
    """The client JWT and the first cap reading (None to read at start): from the
    token server when one is configured, otherwise the client.jwt in the state
    directory. Raises ConfigError, TokenServerRefused or TokenServerError."""
    token_server_url = os.environ.get(TOKEN_SERVER_URL_SETTING, "")
    demo_session = os.environ.get(DEMO_SESSION_SETTING, "")
    if token_server_url or demo_session:
        if not token_server_url or not demo_session:
            raise ConfigError(f"set both {TOKEN_SERVER_URL_SETTING} and {DEMO_SESSION_SETTING}, or neither")
        if any(character.isspace() or not character.isprintable() for character in demo_session):
            raise ConfigError(f"{DEMO_SESSION_SETTING} must be one printable token without spaces")
        token_server_origin = check_origin(token_server_url, TOKEN_SERVER_URL_SETTING)
        fetched = fetch_client_jwt(state_dir, instance_id, token_server_origin, demo_session, transport)
        return fetched.client_jwt, fetched.data_cap
    client_jwt = load_client_jwt(state_dir)
    if not client_jwt:
        raise ConfigError(
            f"no token server and no client.jwt: set {TOKEN_SERVER_URL_SETTING} and {DEMO_SESSION_SETTING}, "
            "or write client.jwt with your backend tool's provision"
        )
    return client_jwt, None


if __name__ == "__main__":
    main()