Developer SDK

Python examples

Install the SDK · View source on GitHub ↗

embed/server/backend.py

python
"""SERVER ONLY. The Python embed backend tool (EMBED_CONTRACT.md, "Backend
tools"). It extends the integration allocator (../../integration/server/
allocator.py): the same settings, map format, key pattern, lock and response
checks, plus the embed commands.

  python3 backend.py provision <key> <client-jwt-file>
  python3 backend.py cap <key> [--monthly <bytes>|--monthly null] [--total <bytes>|--total null] [--reset-total]
  python3 backend.py usage <key>
  python3 backend.py usage-all
  python3 backend.py remove <key>
  python3 backend.py acl <key> default|isolated
  python3 backend.py status
  python3 backend.py --self-test

<key> is user:<service-user-id>, or user:<service-user-id>:<installation-id>
for one client per running installation. Your service authenticates the user
and supplies the key itself, never from a raw request field.

Settings:
- URNETWORK_ROOT_JWT: the root credential, an API key (urn_...) or a network
  JWT, from the backend's secret store. Never sent to an app.
- URNETWORK_CLIENT_MAP: absolute filename of this tool's private client map,
  in an existing private, service-owned directory. Not the token server's map.
- URNETWORK_API_URL: optional HTTPS origin, default https://api.bringyour.com.
- URNETWORK_DEFAULT_ACL_GROUP: optional, the ACL group of each new client:
  isolated (the default), so your users never see each other in the peer
  list, or default, for an app that uses Messages.

Exit codes: 0 success; 78 a configuration or credential problem (missing
settings, an invalid key or map, the root credential refused, the client
limit); 1 any other failure. Each failure prints one stderr line, which never
carries a secret."""

import base64
import contextlib
import io
import json
import os
from pathlib import Path
import re
import secrets
import sys
import tempfile
import urllib.error
import urllib.parse
import urllib.request

sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "integration" / "server"))
import allocator  # noqa: E402  the integration allocator this tool extends

DESCRIPTION = "embed client"
DEVICE_SPEC = "urnetwork-examples/python-embed-server"

AUTH_CLIENT_ROUTE = "/network/auth-client"
REMOVE_CLIENT_ROUTE = "/network/remove-client"
CAP_ROUTE = "/network/client-data-cap"
CAPS_ROUTE = "/network/client-data-caps"
ACL_ROUTE = "/network/client-acl-group"
EMBED_ROUTE = "/network/embed"
USAGE_ALL_PAGE_LIMIT = 1000

MAX_BYTE_COUNT = 9223372036854775807
BYTE_COUNT_PATTERN = re.compile(r"[0-9]{1,19}")

CLIENT_DOES_NOT_EXIST = "Client does not exist."
CLIENT_LIMIT_MESSAGE = "client limit reached: your network is at its client limit; see https://ur.io/services"
UNMAPPED_MESSAGE = "no client is mapped for that key; run provision first"
ACL_UNSUPPORTED_MESSAGE = "/network/client-acl-group answered 404: the server predates ACL groups"
# The server refuses the data-cap and ACL-group routes with this message while
# the team has not enabled Embed for the network (EMBED_CONTRACT.md, "Embed
# enablement"); caps and groups set earlier stay enforced.
EMBED_NOT_ENABLED_MESSAGE = "Embed isn't enabled for this network."
# cap, usage, usage-all and acl print this for the refusal and exit 78
EMBED_NOT_ENABLED_LINE = "embed not enabled: Embed isn't enabled for this network; see https://ur.io/services"
# provision prints this on stderr when the client's default ACL group stays
# pending because Embed isn't enabled, and exits 0
EMBED_PENDING_LINE = "embed not enabled: the client's defaults stay pending until Embed is enabled; see https://ur.io/services"
EMBED_UNSUPPORTED_MESSAGE = "/network/embed answered 404: the server predates Embed enablement"

ACL_GROUP_DEFAULT = "default"
ACL_GROUP_ISOLATED = "isolated"
ACL_GROUPS = (ACL_GROUP_DEFAULT, ACL_GROUP_ISOLATED)

# a language tool's map has only these fields, pending_acl only while it is not
# empty; the token server's adds pending_caps
MAP_FIELDS = {"version", "clients", "pending_acl"}

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

# the longest API error message the tool shows
ERROR_MESSAGE_LIMIT = 300

USAGE = (
    "usage: backend.py provision <key> <client-jwt-file> | cap <key> [--monthly <bytes>|--monthly null] "
    "[--total <bytes>|--total null] [--reset-total] | usage <key> | usage-all | remove <key> | acl <key> default|isolated | status | --self-test"
)


class ToolError(Exception):
    """A failure with its exit code and its stderr line, which never carries a
    secret."""

    def __init__(self, exit_code: int, message: str):
        super().__init__(message)
        self.exit_code = exit_code
        self.message = message


def config_problem(message: str) -> ToolError:
    return ToolError(EXIT_CONFIG, message)


def failure(message: str) -> ToolError:
    return ToolError(EXIT_FAILURE, message)


def check_key(key: str) -> str:
    """A map key in the allocator's pattern."""
    if not isinstance(key, str) or not allocator.USER.fullmatch(key):
        raise config_problem("invalid key: use user:<service-user-id> or user:<service-user-id>:<installation-id>")
    return key


def api_origin(base: str) -> str:
    """The API origin with the allocator's rules: HTTPS, or explicit loopback HTTP
    for local mocks; no credentials, path, query or fragment."""
    try:
        allocator.endpoint(base)
    except ValueError:
        raise config_problem("URNETWORK_API_URL must be an HTTPS origin; HTTP is allowed only for explicit loopback mocks") from None
    if "?" in base or "#" in base:
        raise config_problem("URNETWORK_API_URL must be an origin, with no query or fragment")
    parts = urllib.parse.urlsplit(base)
    return f"{parts.scheme}://{parts.netloc}"


def load_map(path: Path) -> dict:
    """The allocator's private map, with an optional pending_acl: the keys whose
    new clients still owe their default ACL group. A map with other fields (the
    token server's map has pending_caps) is refused, so that two tools never
    rewrite each other's map."""
    try:
        data = allocator.load_map(path)
    except (OSError, ValueError) as error:
        raise config_problem(f"invalid client map: {error}") from None
    extra = sorted(set(data) - MAP_FIELDS)
    if extra:
        raise config_problem(f"the client map has fields other than version, clients and pending_acl ({', '.join(extra)}); give this tool its own map")
    pending = data.setdefault("pending_acl", [])
    if (
        not isinstance(pending, list)
        or any(not isinstance(key, str) or key not in data["clients"] for key in pending)
        or len(set(pending)) != len(pending)
    ):
        raise config_problem("the client map's pending_acl is not a list of mapped keys")
    return data


def save_map(path: Path, data: dict):
    """Saves the map; pending_acl only while it is not empty."""
    saved = {"version": data["version"], "clients": data["clients"]}
    if data.get("pending_acl"):
        saved["pending_acl"] = data["pending_acl"]
    try:
        allocator.save_map(path, saved)
    except OSError as error:
        raise failure(f"save the client map: {error}") from None


def set_acl_pending(data: dict, key: str, pending: bool):
    """Records that key's new client owes its default ACL group, or drops the
    record."""
    keys = [entry for entry in data.get("pending_acl", []) if entry != key]
    if pending:
        keys.append(key)
    data["pending_acl"] = keys


@contextlib.contextmanager
def map_lock(path: Path):
    """The allocator's exclusive <map>.lock, held through the remote call and the
    map update."""
    try:
        lock = allocator.map_lock(path)
        lock.__enter__()
    except ValueError as error:
        raise config_problem(str(error)) from None
    except FileExistsError:
        raise failure("the client map is locked by another run; retry when it finishes") from None
    except OSError as error:
        raise failure(f"lock the client map: {error}") from None
    try:
        yield
    finally:
        lock.__exit__(None, None, None)


def write_private_file(path: str, data: bytes):
    """Replaces a file atomically with owner-only permissions: a private temporary
    file in the same directory is written, synced and renamed over it."""
    directory = os.path.dirname(os.path.abspath(path))
    temp_path = os.path.join(directory, f".{os.path.basename(path)}.{secrets.token_hex(8)}")
    fd = os.open(temp_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0), 0o600)
    try:
        with os.fdopen(fd, "wb") as file:
            if os.name != "nt":
                os.fchmod(file.fileno(), 0o600)
            file.write(data)
            file.flush()
            os.fsync(file.fileno())
        os.replace(temp_path, path)
    except BaseException:
        with contextlib.suppress(OSError):
            os.remove(temp_path)
        raise


def message_of(error) -> str:
    """An API error object's message on one bounded line."""
    message = error.get("message") if isinstance(error, dict) else None
    if not isinstance(message, str):
        return "no message"
    return " ".join(message.split())[:ERROR_MESSAGE_LIMIT]


def is_client_does_not_exist(answer: dict) -> bool:
    error = answer.get("error")
    return isinstance(error, dict) and error.get("message") == CLIENT_DOES_NOT_EXIST


def check_client_limit(answer: dict):
    """A refusal for either client limit flag is a configuration problem."""
    error = answer.get("error")
    if isinstance(error, dict) and (error.get("client_limit_exceeded") is True or error.get("upgrade_required") is True):
        raise config_problem(CLIENT_LIMIT_MESSAGE)


def is_embed_not_enabled(answer: dict) -> bool:
    error = answer.get("error")
    return isinstance(error, dict) and error.get("message") == EMBED_NOT_ENABLED_MESSAGE


def check_embed_enabled(answer: dict):
    """The Embed-not-enabled refusal is a configuration problem with the fixed
    line."""
    if is_embed_not_enabled(answer):
        raise config_problem(EMBED_NOT_ENABLED_LINE)


def check_cap_object(value) -> dict:
    """A cap object: a JSON object with a client_id and no error."""
    if isinstance(value, dict):
        check_embed_enabled(value)
    if isinstance(value, dict) and value.get("error") is not None:
        raise failure("the cap request was refused: " + message_of(value["error"]))
    if not isinstance(value, dict) or not isinstance(value.get("client_id"), str):
        raise failure("the API answered something that is not a cap object")
    for name in ("monthly_byte_limit", "total_byte_limit"):
        limit = value.get(name)
        if limit is not None and (not isinstance(limit, int) or isinstance(limit, bool)):
            raise failure(f"the cap object has an invalid {name}")
    return value


def compact(value) -> str:
    return json.dumps(value, separators=(",", ":"))


def parse_byte_limit(text: str):
    """A byte count option: a decimal integer from 0 to 9223372036854775807 with no
    units, or null to clear the cap."""
    if text == "null":
        return None
    if not BYTE_COUNT_PATTERN.fullmatch(text) or MAX_BYTE_COUNT < int(text):
        raise config_problem("a byte count is a decimal integer from 0 to 9223372036854775807, with no units, or null")
    return int(text)


def parse_cap_options(args: list) -> dict:
    """The fields to merge: only the options given, so an omitted cap is absent
    from the request and keeps its value."""
    fields = {}
    index = 0
    while index < len(args):
        option = args[index]
        if option in ("--monthly", "--total"):
            name = "monthly_byte_limit" if option == "--monthly" else "total_byte_limit"
            if name in fields:
                raise config_problem(f"{option} is given twice")
            if len(args) <= index + 1:
                raise config_problem(f"{option} needs a byte count or null")
            fields[name] = parse_byte_limit(args[index + 1])
            index += 2
        elif option == "--reset-total":
            if "reset_total" in fields:
                raise config_problem("--reset-total is given twice")
            fields["reset_total"] = True
            index += 1
        else:
            raise config_problem(USAGE)
    if not fields:
        raise config_problem("cap needs at least one of --monthly, --total or --reset-total")
    return fields


class Api:
    """The URnetwork API with the root credential. transport(method, path, body)
    returns (status, answer bytes); the self-test passes a stand-in."""

    def __init__(self, transport):
        self._transport = transport

    def call(self, method: str, path: str, body=None) -> dict:
        data = None if body is None else json.dumps(body).encode()
        status, answer = self._transport(method, path, data)
        route = path.split("?", 1)[0]
        if status in (401, 403):
            raise config_problem("the root credential was refused; check URNETWORK_ROOT_JWT")
        if status == 404:
            # a server that predates the route (EMBED_CONTRACT.md, "Backend tools")
            if route == ACL_ROUTE:
                raise failure(ACL_UNSUPPORTED_MESSAGE)
            if route in (CAP_ROUTE, CAPS_ROUTE):
                raise failure(f"{route} answered 404: the server predates the data-cap routes")
            if route == EMBED_ROUTE:
                raise failure(EMBED_UNSUPPORTED_MESSAGE)
            raise failure(f"{route} answered 404")
        if not 200 <= status < 300:
            raise failure(f"{route} failed with HTTP {status}")
        try:
            value = json.loads(answer)
        except ValueError:
            value = None
        if not isinstance(value, dict):
            raise failure(f"{route} answered something that is not a JSON object")
        return value


def urllib_transport(origin: str, root: str):
    """The real transport: urllib with the allocator's no-redirect handler and its
    answer size limit."""
    if not root or any(character.isspace() for character in root):
        raise config_problem("set a valid URNETWORK_ROOT_JWT on the backend")
    opener = urllib.request.build_opener(allocator.NoRedirect)

    def send(method: str, path: str, body: bytes | None):
        headers = {"Authorization": "Bearer " + root, "Accept": "application/json"}
        if body is not None:
            headers["Content-Type"] = "application/json"
        request = urllib.request.Request(origin + path, data=body, headers=headers, method=method)
        try:
            response = opener.open(request, timeout=15)
        except urllib.error.HTTPError as error:
            response = error
        except OSError:
            # the reason can name the host; it never carries the credential
            raise failure("could not reach the URnetwork API; check URNETWORK_API_URL and the network") from None
        try:
            status = response.getcode()
            answer = response.read(allocator.LIMIT + 1)
        finally:
            response.close()
        if allocator.LIMIT < len(answer):
            raise failure("the API answer is too large")
        return status, answer

    return send


def provision(api: Api, path: Path, key: str, client_jwt_file: str, acl_group: str):
    """Reissues the key's client, or provisions a new one; on Client does not
    exist. it drops the mapping and provisions a new client. A new client goes
    into acl_group, with a pending_acl record until the group is applied, before
    any client JWT is written. Writes the client JWT to client_jwt_file and
    prints only the client ID. While Embed isn't enabled the record stays, with
    a line on stderr, and a provision after the team enables Embed applies
    it."""
    embed_enabled = True
    with map_lock(path):
        data = load_map(path)
        old = data["clients"].get(key)
        answer = None
        if old is not None:
            answer = api.call("POST", AUTH_CLIENT_ROUTE, {"client_id": old, "description": DESCRIPTION, "device_spec": DEVICE_SPEC})
            if is_client_does_not_exist(answer):
                # deactivated after 30 days without connecting, or removed
                del data["clients"][key]
                set_acl_pending(data, key, False)
                save_map(path, data)
                old = None
        if old is None:
            # a new top-level client: neither client_id nor source_client_id
            answer = api.call("POST", AUTH_CLIENT_ROUTE, {"description": DESCRIPTION, "device_spec": DEVICE_SPEC})
        check_client_limit(answer)
        if answer.get("error") is not None:
            raise failure("provisioning was refused: " + message_of(answer["error"]))
        try:
            result = allocator.parse_response(json.dumps(answer), old)
        except (ValueError, TypeError) as error:
            raise failure(f"the provisioning answer failed its checks: {error}") from None
        if old is None:
            if result["client_id"] in data["clients"].values():
                raise failure("the API returned a client that the map assigns to another key")
            data["clients"][key] = result["client_id"]
            # the mapping and the record that the client owes its group, in one save
            set_acl_pending(data, key, acl_group == ACL_GROUP_ISOLATED)
            save_map(path, data)
        if key in data["pending_acl"]:
            # a new client is "default": only an isolated default needs the request.
            # A failure raises with the record kept, before any client JWT is written.
            if acl_group == ACL_GROUP_ISOLATED:
                embed_enabled = post_acl_group(api, result["client_id"], ACL_GROUP_ISOLATED, allow_not_enabled=True)
            # while Embed isn't enabled the record stays and the client works
            if embed_enabled:
                set_acl_pending(data, key, False)
                save_map(path, data)
        try:
            write_private_file(client_jwt_file, (result["by_client_jwt"] + "\n").encode())
        except OSError as error:
            raise failure(f"write the client JWT file: {error}") from None
    print(compact({"client_id": result["client_id"]}))
    if not embed_enabled:
        print(EMBED_PENDING_LINE, file=sys.stderr)


def mapped_client(path: Path, key: str) -> str:
    client = load_map(path)["clients"].get(key)
    if client is None:
        raise config_problem(UNMAPPED_MESSAGE)
    return client


def post_acl_group(api: Api, client: str, acl_group: str, allow_not_enabled=False) -> bool:
    """Sets the client's ACL group; the answer must name the client and the
    group. The Embed-not-enabled refusal exits 78, or returns False when
    allow_not_enabled is set."""
    answer = api.call("POST", ACL_ROUTE, {"client_id": client, "acl_group": acl_group})
    if allow_not_enabled and is_embed_not_enabled(answer):
        return False
    check_embed_enabled(answer)
    if answer.get("error") is not None:
        raise failure("the ACL group request was refused: " + message_of(answer["error"]))
    if answer.get("client_id") != client or answer.get("acl_group") != acl_group:
        raise failure("the API answered another client or ACL group")
    return True


def acl(api: Api, path: Path, key: str, acl_group: str):
    """Sets the ACL group of the key's client and prints {"client_id": ...,
    "acl_group": ...}. An explicit group settles a pending default group, so the
    record is dropped."""
    with map_lock(path):
        data = load_map(path)
        client = data["clients"].get(key)
        if client is None:
            raise config_problem(UNMAPPED_MESSAGE)
        post_acl_group(api, client, acl_group)
        if key in data["pending_acl"]:
            set_acl_pending(data, key, False)
            save_map(path, data)
    print(compact({"client_id": client, "acl_group": acl_group}))


def cap(api: Api, path: Path, key: str, fields: dict):
    """Posts only the given fields to POST /network/client-data-cap and prints the
    cap object."""
    with map_lock(path):
        client = mapped_client(path, key)
        answer = api.call("POST", CAP_ROUTE, {"client_id": client, **fields})
    print(compact(check_cap_object(answer)))


def usage(api: Api, path: Path, key: str):
    """Prints the key's cap object, read with the root credential."""
    client = mapped_client(path, key)
    answer = api.call("GET", CAP_ROUTE + "?" + urllib.parse.urlencode({"client_id": client}))
    print(compact(check_cap_object(answer)))


def usage_all(api: Api):
    """Pages through GET /network/client-data-caps and prints one cap object per
    line, stopping at a null cursor or a repeated one."""
    cursor = None
    seen = set()
    while True:
        query = {"limit": str(USAGE_ALL_PAGE_LIMIT)}
        if cursor is not None:
            query["cursor"] = cursor
        answer = api.call("GET", CAPS_ROUTE + "?" + urllib.parse.urlencode(query))
        check_embed_enabled(answer)
        if answer.get("error") is not None:
            raise failure("the cap list was refused: " + message_of(answer["error"]))
        clients = answer.get("clients")
        if not isinstance(clients, list):
            raise failure("the cap list has no clients array")
        for value in clients:
            print(compact(check_cap_object(value)))
        next_cursor = answer.get("next_cursor")
        if next_cursor is None:
            return
        if not isinstance(next_cursor, str):
            raise failure("the cap list has an invalid next_cursor")
        if next_cursor in seen:
            # a server that repeats a cursor would page forever
            return
        seen.add(next_cursor)
        cursor = next_cursor


def is_count(value) -> bool:
    return isinstance(value, int) and not isinstance(value, bool) and 0 <= value


def status(api: Api):
    """Prints the network's Embed state from GET /network/embed as one line,
    "embed enabled: yes | client limit: 5000 | active clients: 1234". A refusal,
    such as for a client JWT, is a configuration problem."""
    answer = api.call("GET", EMBED_ROUTE)
    if answer.get("error") is not None:
        raise config_problem("the Embed state request was refused: " + message_of(answer["error"]))
    enabled = answer.get("enabled")
    client_limit = answer.get("client_limit")
    active_client_count = answer.get("active_client_count")
    if not isinstance(enabled, bool) or not is_count(client_limit) or not is_count(active_client_count):
        raise failure(f"{EMBED_ROUTE} answered something that is not an Embed state")
    print(f"embed enabled: {'yes' if enabled else 'no'} | client limit: {client_limit} | active clients: {active_client_count}")


def remove(api: Api, path: Path, key: str):
    """Removes the key's client, then its mapping, also when the client is already
    gone."""
    with map_lock(path):
        data = load_map(path)
        client = data["clients"].get(key)
        if client is None:
            raise config_problem(UNMAPPED_MESSAGE)
        answer = api.call("POST", REMOVE_CLIENT_ROUTE, {"client_id": client})
        if answer.get("error") is not None and not is_client_does_not_exist(answer):
            raise failure("remove was refused: " + message_of(answer["error"]))
        del data["clients"][key]
        set_acl_pending(data, key, False)
        save_map(path, data)
    print(compact({"removed": client}))


def run(args: list, environ=None, transport_factory=urllib_transport) -> int:
    """Runs one command and returns the exit code. transport_factory(origin, root)
    makes the API transport; the self-test passes a stand-in."""
    environ = os.environ if environ is None else environ
    try:
        if args == ["--self-test"]:
            try:
                self_test()
            except Exception as error:
                # test data only: the self-test has no credentials to expose
                print(f"embed backend self-test failed: {error}", file=sys.stderr)
                return EXIT_FAILURE
            print("embed backend self-test passed")
            return EXIT_OK
        if not args or args[0] not in ("provision", "cap", "usage", "usage-all", "remove", "acl", "status"):
            raise config_problem(USAGE)
        command, operands = args[0], args[1:]
        if command == "provision" and len(operands) != 2:
            raise config_problem(USAGE)
        if command in ("usage", "remove") and len(operands) != 1:
            raise config_problem(USAGE)
        if command == "cap" and not operands:
            raise config_problem(USAGE)
        if command in ("usage-all", "status") and operands:
            raise config_problem(USAGE)
        if command == "acl" and (len(operands) != 2 or operands[1] not in ACL_GROUPS):
            raise config_problem(USAGE)
        key = check_key(operands[0]) if command not in ("usage-all", "status") else None
        fields = parse_cap_options(operands[1:]) if command == "cap" else None

        root = environ.get("URNETWORK_ROOT_JWT", "")
        if not root:
            raise config_problem("set URNETWORK_ROOT_JWT from the backend's secret store")
        origin = api_origin(environ.get("URNETWORK_API_URL") or "https://api.bringyour.com")
        acl_group = environ.get("URNETWORK_DEFAULT_ACL_GROUP") or ACL_GROUP_ISOLATED
        if acl_group not in ACL_GROUPS:
            raise config_problem("URNETWORK_DEFAULT_ACL_GROUP must be default or isolated")
        path = None
        if command not in ("usage-all", "status"):
            map_name = environ.get("URNETWORK_CLIENT_MAP", "")
            if not map_name:
                raise config_problem("set URNETWORK_CLIENT_MAP to this tool's private client map")
            path = Path(map_name)
            if not path.is_absolute() or not path.parent.is_dir():
                raise config_problem("URNETWORK_CLIENT_MAP must be absolute, in an existing service-owned directory")
        api = Api(transport_factory(origin, root))
        if command == "provision":
            provision(api, path, key, operands[1], acl_group)
        elif command == "cap":
            cap(api, path, key, fields)
        elif command == "usage":
            usage(api, path, key)
        elif command == "usage-all":
            usage_all(api)
        elif command == "acl":
            acl(api, path, key, operands[1])
        elif command == "status":
            status(api)
        else:
            remove(api, path, key)
        return EXIT_OK
    except ToolError as error:
        print(error.message, file=sys.stderr)
        return error.exit_code
    except Exception:
        # neither remote bodies nor exception text may expose a credential
        print("embed backend failed: check the key, the private map and the API configuration", file=sys.stderr)
        return EXIT_FAILURE


# ---------------------------------------------------------------- self-test

SELF_TEST_ROOT = "urn_self-test-root-credential"
SELF_TEST_CLIENT = "11111111-1111-1111-1111-111111111111"
SELF_TEST_OTHER_CLIENT = "22222222-2222-2222-2222-222222222222"
SELF_TEST_KEY = "user:alice:33333333-3333-3333-3333-333333333333"


class SelfTestError(Exception):
    """A self-test check that failed."""


def self_test_jwt(client_id: str) -> str:
    """An unsigned client JWT carrying client_id, for the claim checks only."""
    payload = json.dumps({"client_id": client_id}).encode()
    return "e30." + base64.urlsafe_b64encode(payload).decode().rstrip("=") + ".c2lnbmF0dXJl"


class StandInApi:
    """A stand-in URnetwork API: answers each request from a queue of (status,
    JSON value) answers and logs the requests with their parsed bodies."""

    def __init__(self, *answers):
        self.answers = list(answers)
        self.requests = []

    def factory(self, origin: str, root: str):
        if root != SELF_TEST_ROOT:
            raise SelfTestError("the tool passed a different root credential")
        return self

    def __call__(self, method, path, body):
        self.requests.append({"method": method, "path": path, "body": None if body is None else json.loads(body)})
        if not self.answers:
            raise SelfTestError(f"unexpected request {method} {path}")
        answer = self.answers.pop(0)
        if isinstance(answer, OSError):
            raise answer
        status, value = answer
        return status, json.dumps(value).encode()


def self_test():
    """The credential-free self-test: allocator rules, re-provision, the client JWT
    file, the merge request bodies, cap objects, paging, remove, map refusal and
    the exit codes."""
    with tempfile.TemporaryDirectory() as directory:
        if os.name != "nt":
            os.chmod(directory, 0o700)
        map_path = os.path.join(directory, "clients.json")
        jwt_path = os.path.join(directory, "client.jwt")
        # the checks before the ACL group checks keep new clients in "default",
        # which sends no ACL request
        environ = {
            "URNETWORK_ROOT_JWT": SELF_TEST_ROOT,
            "URNETWORK_CLIENT_MAP": map_path,
            "URNETWORK_API_URL": "http://127.0.0.1:1",
            "URNETWORK_DEFAULT_ACL_GROUP": ACL_GROUP_DEFAULT,
        }

        def tool(args, api, settings=None):
            out, err = io.StringIO(), io.StringIO()
            with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
                code = run(args, environ if settings is None else settings, api.factory)
            text = out.getvalue() + err.getvalue()
            if SELF_TEST_ROOT in text:
                raise SelfTestError("the root credential reached the output")
            return code, out.getvalue(), err.getvalue()

        def expect(condition, message):
            if not condition:
                raise SelfTestError(message)

        client_jwt = self_test_jwt(SELF_TEST_CLIENT)
        provisioned = {"client_id": SELF_TEST_CLIENT, "by_client_jwt": client_jwt}

        # a new key provisions a top-level client; the token goes only to the file
        api = StandInApi((200, provisioned))
        code, out, err = tool(["provision", SELF_TEST_KEY, jwt_path], api)
        expect(code == EXIT_OK and json.loads(out) == {"client_id": SELF_TEST_CLIENT}, f"provision must print the client ID: {code} {err}")
        body = api.requests[0]["body"]
        expect(api.requests[0]["path"] == AUTH_CLIENT_ROUTE, "provision must post /network/auth-client")
        expect(body == {"description": DESCRIPTION, "device_spec": DEVICE_SPEC}, "a new client sends neither client_id nor source_client_id")
        expect(client_jwt not in out + err, "the client JWT must never reach stdout or stderr")
        expect(Path(jwt_path).read_text() == client_jwt + "\n", "the client JWT file must hold the token")
        if os.name != "nt":
            expect(os.stat(jwt_path).st_mode & 0o777 == 0o600, "the client JWT file must be private (0600)")
            expect(os.stat(map_path).st_mode & 0o077 == 0, "the map must be private")
        expect(load_map(Path(map_path))["clients"] == {SELF_TEST_KEY: SELF_TEST_CLIENT}, "the map must round-trip")

        # a mapped key reissues with its client_id
        api = StandInApi((200, provisioned))
        code, _, _ = tool(["provision", SELF_TEST_KEY, jwt_path], api)
        expect(code == EXIT_OK and api.requests[0]["body"].get("client_id") == SELF_TEST_CLIENT, "a mapped key must reissue with its client_id")
        expect("source_client_id" not in api.requests[0]["body"], "a reissue never sends source_client_id")

        # Client does not exist. drops the mapping and provisions a new client
        other = {"client_id": SELF_TEST_OTHER_CLIENT, "by_client_jwt": self_test_jwt(SELF_TEST_OTHER_CLIENT)}
        api = StandInApi((200, {"error": {"message": CLIENT_DOES_NOT_EXIST}}), (200, other))
        code, out, _ = tool(["provision", SELF_TEST_KEY, jwt_path], api)
        expect(code == EXIT_OK and json.loads(out)["client_id"] == SELF_TEST_OTHER_CLIENT, "a deactivated client must be re-provisioned")
        expect("client_id" not in api.requests[1]["body"], "the re-provision must create a new client")
        expect(load_map(Path(map_path))["clients"][SELF_TEST_KEY] == SELF_TEST_OTHER_CLIENT, "the map must hold the new client")

        # response and claim checks
        mismatch = {"client_id": SELF_TEST_CLIENT, "by_client_jwt": self_test_jwt("44444444-4444-4444-4444-444444444444")}
        for bad in (mismatch, {"client_id": SELF_TEST_CLIENT}, {"by_client_jwt": client_jwt}, {"client_id": "not-a-uuid", "by_client_jwt": client_jwt}):
            code, _, _ = tool(["provision", "user:bob", jwt_path], StandInApi((200, bad)))
            expect(code == EXIT_FAILURE, f"a provisioning answer {bad} must fail its checks")
        # a client the map already assigns to another key is refused
        taken = {"client_id": SELF_TEST_OTHER_CLIENT, "by_client_jwt": self_test_jwt(SELF_TEST_OTHER_CLIENT)}
        code, _, _ = tool(["provision", "user:carol", jwt_path], StandInApi((200, taken)))
        expect(code == EXIT_FAILURE, "a client assigned to another key must be refused")

        # the client limit: either flag, exit 78 with the exact line
        for flags in ({"client_limit_exceeded": True, "message": "Client limit exceeded."}, {"client_limit_exceeded": False, "upgrade_required": True, "message": "upgrade"}):
            code, _, err = tool(["provision", "user:dave", jwt_path], StandInApi((200, {"error": flags})))
            expect(code == EXIT_CONFIG and err.strip() == CLIENT_LIMIT_MESSAGE, f"a client limit refusal must exit 78 with the limit line: {flags}")

        # the merge request bodies: only the given fields, null as JSON null, integers
        cap_answer = {"client_id": SELF_TEST_OTHER_CLIENT, "monthly_byte_limit": 10000000000, "total_byte_limit": None, "capped": False, "capped_reason": ""}
        cases = [
            (["--monthly", "10000000000"], {"monthly_byte_limit": 10000000000}),
            (["--total", "null"], {"total_byte_limit": None}),
            (["--monthly", "0"], {"monthly_byte_limit": 0}),
            (["--reset-total"], {"reset_total": True}),
            (["--monthly", "20000000000", "--total", "9223372036854775807", "--reset-total"], {"monthly_byte_limit": 20000000000, "total_byte_limit": 9223372036854775807, "reset_total": True}),
        ]
        for options, fields in cases:
            api = StandInApi((200, cap_answer))
            code, out, err = tool(["cap", SELF_TEST_KEY, *options], api)
            expect(code == EXIT_OK, f"cap {options} must succeed: {err}")
            sent = api.requests[0]["body"]
            expect(api.requests[0]["path"] == CAP_ROUTE and api.requests[0]["method"] == "POST", "cap must post /network/client-data-cap")
            expect(sent == {"client_id": SELF_TEST_OTHER_CLIENT, **fields}, f"cap {options} must send {fields}, sent {sent}")
            for name, value in fields.items():
                expect(type(sent[name]) is type(value), f"{name} must keep its JSON type")
            expect(json.loads(out) == cap_answer, "cap must print the cap object")
        for options in ([], ["--monthly"], ["--monthly", "-1"], ["--monthly", "1e3"], ["--monthly", "10GB"], ["--total", "9223372036854775808"], ["--monthly", "1", "--monthly", "2"], ["--weekly", "1"]):
            code, _, _ = tool(["cap", SELF_TEST_KEY, *options], StandInApi())
            expect(code == EXIT_CONFIG, f"cap {options} must be a usage error")
        code, _, _ = tool(["cap", SELF_TEST_KEY, "--monthly", "1"], StandInApi((200, {"error": {"message": "no such client"}})))
        expect(code == EXIT_FAILURE, "a refused cap request must fail")
        code, _, _ = tool(["cap", SELF_TEST_KEY, "--monthly", "1"], StandInApi((404, {})))
        expect(code == EXIT_FAILURE, "a server without the cap routes must fail")

        # usage reads the key's client with the root credential
        api = StandInApi((200, cap_answer))
        code, out, _ = tool(["usage", SELF_TEST_KEY], api)
        expect(code == EXIT_OK and json.loads(out) == cap_answer, "usage must print the cap object")
        expect(api.requests[0] == {"method": "GET", "path": CAP_ROUTE + "?client_id=" + SELF_TEST_OTHER_CLIENT, "body": None}, "usage must GET the key's client")

        # usage-all pages until a null cursor, and stops at a repeated cursor
        page = lambda client, cursor: (200, {"clients": [{**cap_answer, "client_id": client}], "next_cursor": cursor})  # noqa: E731
        api = StandInApi(page("a", "c1"), page("b", "c2"), page("c", None))
        code, out, _ = tool(["usage-all"], api)
        expect(code == EXIT_OK and [json.loads(line)["client_id"] for line in out.splitlines()] == ["a", "b", "c"], "usage-all must print every page")
        expect([request["path"] for request in api.requests] == [CAPS_ROUTE + "?limit=1000", CAPS_ROUTE + "?limit=1000&cursor=c1", CAPS_ROUTE + "?limit=1000&cursor=c2"], "usage-all must page with the cursor")
        api = StandInApi(page("a", "c1"), page("b", "c1"))
        code, out, _ = tool(["usage-all"], api)
        expect(code == EXIT_OK and len(out.splitlines()) == 2 and len(api.requests) == 2, "usage-all must stop at a repeated cursor")

        # remove drops the mapping for both answers, and keeps it on a refusal
        code, _, _ = tool(["remove", SELF_TEST_KEY], StandInApi((200, {"error": {"message": "not allowed"}})))
        expect(code == EXIT_FAILURE and SELF_TEST_KEY in load_map(Path(map_path))["clients"], "a refused remove must keep the mapping")
        api = StandInApi((200, {}))
        code, out, _ = tool(["remove", SELF_TEST_KEY], api)
        expect(code == EXIT_OK and json.loads(out) == {"removed": SELF_TEST_OTHER_CLIENT}, "remove must print the removed client")
        expect(api.requests[0]["body"] == {"client_id": SELF_TEST_OTHER_CLIENT}, "remove must post the client_id")
        expect(SELF_TEST_KEY not in load_map(Path(map_path))["clients"], "remove must drop the mapping")
        tool(["provision", SELF_TEST_KEY, jwt_path], StandInApi((200, provisioned)))
        code, _, _ = tool(["remove", SELF_TEST_KEY], StandInApi((200, {"error": {"message": CLIENT_DOES_NOT_EXIST}})))
        expect(code == EXIT_OK and SELF_TEST_KEY not in load_map(Path(map_path))["clients"], "remove must drop the mapping of a client that is already gone")

        # a map with other fields, such as the token server's, is refused
        token_server_map = os.path.join(directory, "token-server.json")
        write_private_file(token_server_map, json.dumps({"version": 1, "clients": {}, "pending_caps": []}).encode())
        code, _, _ = run_with(tool, environ, token_server_map, ["usage", SELF_TEST_KEY])
        expect(code == EXIT_CONFIG, "a map with pending_caps must be refused")

        # key and argument rejection, settings, credential refusal and the network
        for args in (["provision", SELF_TEST_CLIENT, jwt_path], ["provision", "user:../a", jwt_path], ["provision", SELF_TEST_KEY], ["usage"], ["usage-all", "extra"], ["status", "extra"], ["bogus"], []):
            code, _, _ = tool(args, StandInApi())
            expect(code == EXIT_CONFIG, f"{args} must be a usage error")
        missing_root = dict(environ, URNETWORK_ROOT_JWT="")
        expect(run_quietly(["usage-all"], missing_root) == EXIT_CONFIG, "a missing root credential must exit 78")
        relative_map = dict(environ, URNETWORK_CLIENT_MAP="clients.json")
        expect(run_quietly(["usage", SELF_TEST_KEY], relative_map) == EXIT_CONFIG, "a relative map must exit 78")
        bad_api = dict(environ, URNETWORK_API_URL="http://example.com")
        expect(run_quietly(["usage-all"], bad_api) == EXIT_CONFIG, "a non-HTTPS API must exit 78")
        code, _, _ = tool(["usage-all"], StandInApi((401, {})))
        expect(code == EXIT_CONFIG, "a refused root credential must exit 78")
        code, _, _ = tool(["usage-all"], StandInApi(failure_transport_error()))
        expect(code == EXIT_FAILURE, "an unreachable API must exit 1")
        for args in (["acl"], ["acl", SELF_TEST_KEY], ["acl", SELF_TEST_KEY, "public"], ["acl", SELF_TEST_KEY, "Default"], ["acl", SELF_TEST_KEY, "default", "extra"], ["acl", "alice", "default"]):
            code, _, _ = tool(args, StandInApi())
            expect(code == EXIT_CONFIG, f"{args} must be a usage error")
        bad_group = dict(environ, URNETWORK_DEFAULT_ACL_GROUP="private")
        code, _, err = tool(["provision", "user:x", jwt_path], StandInApi(), bad_group)
        expect(code == EXIT_CONFIG and err.strip() == "URNETWORK_DEFAULT_ACL_GROUP must be default or isolated", "an invalid default ACL group must exit 78")

        self_test_acl_groups(directory, environ, tool, expect)
        self_test_embed_not_enabled(directory, environ, tool, expect)
        self_test_embed_status(environ, tool, expect)
        self_test_failure_texts(directory, environ, tool, expect)


def self_test_acl_groups(directory, environ, tool, expect):
    """The default ACL group: applied to a new client only, with pending_acl set
    before and cleared after, kept and retried after a failure, kept on a server
    without ACL groups, and settled by acl; the acl command."""
    acl_map = os.path.join(directory, "acl.json")
    isolated = {name: value for name, value in dict(environ, URNETWORK_CLIENT_MAP=acl_map).items() if name != "URNETWORK_DEFAULT_ACL_GROUP"}
    jwt_path = os.path.join(directory, "acl.jwt")

    def pending():
        return load_map(Path(acl_map))["pending_acl"]

    def provisioned(client):
        return (200, {"client_id": client, "by_client_jwt": self_test_jwt(client)})

    def applied(client, group):
        return (200, {"client_id": client, "acl_group": group})

    # unset means isolated: the new client, then one ACL request, then no record
    api = StandInApi(provisioned(SELF_TEST_CLIENT), applied(SELF_TEST_CLIENT, ACL_GROUP_ISOLATED))
    code, _, err = tool(["provision", "user:ivan", jwt_path], api, isolated)
    expect(code == EXIT_OK and [request["path"] for request in api.requests] == [AUTH_CLIENT_ROUTE, ACL_ROUTE], f"a new client must be put in isolated: {err}")
    expect(api.requests[1]["body"] == {"client_id": SELF_TEST_CLIENT, "acl_group": ACL_GROUP_ISOLATED}, "the ACL request must name the client and isolated")
    expect(pending() == [] and "pending_acl" not in Path(acl_map).read_text(), "an applied group must leave no record")
    expect(Path(jwt_path).read_text() == self_test_jwt(SELF_TEST_CLIENT) + "\n", "the client JWT must be written after the group")
    api = StandInApi(provisioned(SELF_TEST_CLIENT))
    code, _, _ = tool(["provision", "user:ivan", jwt_path], api, isolated)
    expect(code == EXIT_OK and len(api.requests) == 1, "a reissue must send no ACL request")

    # a failed request keeps the record and writes no client JWT; the next issue retries
    judy_jwt = os.path.join(directory, "judy.jwt")
    code, _, _ = tool(["provision", "user:judy", judy_jwt], StandInApi(provisioned(SELF_TEST_OTHER_CLIENT), (500, {})), isolated)
    expect(code == EXIT_FAILURE and not os.path.exists(judy_jwt) and pending() == ["user:judy"], "a failed ACL request must keep the record and write no client JWT")
    expect(load_map(Path(acl_map))["clients"]["user:judy"] == SELF_TEST_OTHER_CLIENT, "the new client must be mapped with its record")
    api = StandInApi(provisioned(SELF_TEST_OTHER_CLIENT), applied(SELF_TEST_OTHER_CLIENT, ACL_GROUP_ISOLATED))
    code, _, _ = tool(["provision", "user:judy", judy_jwt], api, isolated)
    expect(code == EXIT_OK and api.requests[1]["path"] == ACL_ROUTE and pending() == [] and os.path.exists(judy_jwt), "a pending group must be applied on the next issue")

    # a server without ACL groups: exit 1 with the record kept; a default of default then provisions
    older_map = os.path.join(directory, "older.json")
    kim_jwt = os.path.join(directory, "kim.jwt")
    older_isolated = dict(isolated, URNETWORK_CLIENT_MAP=older_map)
    kim = "55555555-5555-5555-5555-555555555555"
    code, _, err = tool(["provision", "user:kim", kim_jwt], StandInApi(provisioned(kim), (404, {})), older_isolated)
    expect(code == EXIT_FAILURE and err.strip() == ACL_UNSUPPORTED_MESSAGE and not os.path.exists(kim_jwt), f"a server without ACL groups must exit 1 with its line: {err}")
    expect(load_map(Path(older_map))["pending_acl"] == ["user:kim"], "a server without ACL groups must keep the record")
    api = StandInApi(provisioned(kim))
    code, _, _ = tool(["provision", "user:kim", kim_jwt], api, dict(older_isolated, URNETWORK_DEFAULT_ACL_GROUP=ACL_GROUP_DEFAULT))
    expect(code == EXIT_OK and len(api.requests) == 1 and load_map(Path(older_map))["pending_acl"] == [] and os.path.exists(kim_jwt), "a default of default must settle the record without a request")

    # the acl command: the request, the printed answer, and its refusals
    api = StandInApi(applied(SELF_TEST_CLIENT, ACL_GROUP_DEFAULT))
    code, out, _ = tool(["acl", "user:ivan", ACL_GROUP_DEFAULT], api, isolated)
    expect(code == EXIT_OK and json.loads(out) == {"client_id": SELF_TEST_CLIENT, "acl_group": ACL_GROUP_DEFAULT}, "acl must print the answer")
    expect(api.requests == [{"method": "POST", "path": ACL_ROUTE, "body": {"client_id": SELF_TEST_CLIENT, "acl_group": ACL_GROUP_DEFAULT}}], "acl must post the client and the group")
    code, _, _ = tool(["acl", "user:ivan", ACL_GROUP_ISOLATED], StandInApi(applied(SELF_TEST_CLIENT, ACL_GROUP_DEFAULT)), isolated)
    expect(code == EXIT_FAILURE, "an answer for another group must fail")
    code, _, _ = tool(["acl", "user:ivan", ACL_GROUP_ISOLATED], StandInApi((200, {"error": {"message": CLIENT_DOES_NOT_EXIST}})), isolated)
    expect(code == EXIT_FAILURE, "a refused ACL request must fail")
    code, _, err = tool(["acl", "user:ivan", ACL_GROUP_ISOLATED], StandInApi((404, {})), isolated)
    expect(code == EXIT_FAILURE and err.strip() == ACL_UNSUPPORTED_MESSAGE, f"acl on a server without ACL groups must print its line: {err}")

    # an explicit group settles a pending record, so a later issue keeps it
    mia = "66666666-6666-6666-6666-666666666666"
    tool(["provision", "user:mia", os.path.join(directory, "mia.jwt")], StandInApi(provisioned(mia), (500, {})), isolated)
    expect(pending() == ["user:mia"], "the failed group must be recorded")
    code, _, _ = tool(["acl", "user:mia", ACL_GROUP_DEFAULT], StandInApi(applied(mia, ACL_GROUP_DEFAULT)), isolated)
    expect(code == EXIT_OK and pending() == [], "acl must settle a pending record")
    api = StandInApi(provisioned(mia))
    code, _, _ = tool(["provision", "user:mia", os.path.join(directory, "mia.jwt")], api, isolated)
    expect(code == EXIT_OK and len(api.requests) == 1, "a settled group must not be overridden on the next issue")

    # remove drops a pending record with its mapping
    noor = "77777777-7777-7777-7777-777777777777"
    tool(["provision", "user:noor", os.path.join(directory, "noor.jwt")], StandInApi(provisioned(noor), (500, {})), isolated)
    code, _, _ = tool(["remove", "user:noor"], StandInApi((200, {})), isolated)
    expect(code == EXIT_OK and pending() == [], "remove must drop a pending record")

    # a pending_acl that is not a list of distinct mapped keys is refused untouched
    pending_map = os.path.join(directory, "pending.json")
    for value in (
        {"version": 1, "clients": {}, "pending_acl": ["user:x"]},
        {"version": 1, "clients": {"user:x": SELF_TEST_CLIENT}, "pending_acl": ["user:x", "user:x"]},
        {"version": 1, "clients": {"user:x": SELF_TEST_CLIENT}, "pending_acl": "user:x"},
        {"version": 1, "clients": {"user:x": SELF_TEST_CLIENT}, "pending_acl": [1]},
    ):
        text = json.dumps(value).encode()
        write_private_file(pending_map, text)
        api = StandInApi()
        code, _, _ = tool(["provision", "user:x", jwt_path], api, dict(environ, URNETWORK_CLIENT_MAP=pending_map))
        expect(code == EXIT_CONFIG and Path(pending_map).read_bytes() == text and not api.requests, f"the map {value} must be refused untouched")


def self_test_embed_not_enabled(directory, environ, tool, expect):
    """The Embed-not-enabled refusal: cap, usage, usage-all and acl exit 78 with
    the fixed line; provision still provisions and writes the client JWT, keeps
    the default group pending with the fixed stderr line, and a provision after
    the team enables Embed applies it."""
    embed_map = os.path.join(directory, "embed.json")
    isolated = {name: value for name, value in dict(environ, URNETWORK_CLIENT_MAP=embed_map).items() if name != "URNETWORK_DEFAULT_ACL_GROUP"}
    refusal = (200, {"error": {"message": EMBED_NOT_ENABLED_MESSAGE}})
    pia = "88888888-8888-8888-8888-888888888888"
    pia_answer = (200, {"client_id": pia, "by_client_jwt": self_test_jwt(pia)})
    code, _, _ = tool(["provision", "user:pia", os.path.join(directory, "pia.jwt")], StandInApi(pia_answer, (200, {"client_id": pia, "acl_group": ACL_GROUP_ISOLATED})), isolated)
    expect(code == EXIT_OK, "provision before the refusal failed")
    for args in (["cap", "user:pia", "--monthly", "1"], ["usage", "user:pia"], ["usage-all"], ["acl", "user:pia", ACL_GROUP_ISOLATED]):
        code, out, err = tool(args, StandInApi(refusal), isolated)
        expect(code == EXIT_CONFIG and out == "" and err == EMBED_NOT_ENABLED_LINE + "\n", f"{args[0]} while Embed isn't enabled: {code} {err}")
    quinn = "99999999-9999-9999-9999-999999999999"
    quinn_jwt = os.path.join(directory, "quinn.jwt")
    quinn_answer = (200, {"client_id": quinn, "by_client_jwt": self_test_jwt(quinn)})
    api = StandInApi(quinn_answer, refusal)
    code, out, err = tool(["provision", "user:quinn", quinn_jwt], api, isolated)
    expect(code == EXIT_OK and json.loads(out) == {"client_id": quinn} and err == EMBED_PENDING_LINE + "\n", f"provision while Embed isn't enabled: {code} {out} {err}")
    expect([request["path"] for request in api.requests] == [AUTH_CLIENT_ROUTE, ACL_ROUTE], "provision while Embed isn't enabled must try the group")
    expect(Path(quinn_jwt).read_text() == self_test_jwt(quinn) + "\n" and load_map(Path(embed_map))["pending_acl"] == ["user:quinn"], "provision while Embed isn't enabled must write the client JWT and keep the record")
    api = StandInApi(quinn_answer, (200, {"client_id": quinn, "acl_group": ACL_GROUP_ISOLATED}))
    code, _, err = tool(["provision", "user:quinn", quinn_jwt], api, isolated)
    expect(code == EXIT_OK and err == "" and load_map(Path(embed_map))["pending_acl"] == [], f"provision after Embed was enabled must apply the group: {err}")
    expect(api.requests[1]["body"] == {"client_id": quinn, "acl_group": ACL_GROUP_ISOLATED}, "provision after Embed was enabled must post isolated")


def self_test_embed_status(environ, tool, expect):
    """The status command: GET /network/embed with the root credential, printed
    as the fixed line for an enabled and a not enabled network; a refusal exits
    78; a server without the route and an invalid answer exit 1."""
    api = StandInApi((200, {"enabled": True, "client_limit": 5000, "active_client_count": 1234}))
    code, out, err = tool(["status"], api)
    expect(code == EXIT_OK and out == "embed enabled: yes | client limit: 5000 | active clients: 1234\n" and err == "", f"status printed {out} {err}")
    expect(api.requests == [{"method": "GET", "path": EMBED_ROUTE, "body": None}], "status must GET /network/embed")
    code, out, _ = tool(["status"], StandInApi((200, {"enabled": False, "client_limit": 100, "active_client_count": 0})))
    expect(code == EXIT_OK and out == "embed enabled: no | client limit: 100 | active clients: 0\n", f"status while Embed isn't enabled printed {out}")
    code, out, err = tool(["status"], StandInApi((200, {"error": {"message": "Invalid credential."}})))
    expect(code == EXIT_CONFIG and out == "" and "Invalid credential." in err and err.count("\n") == 1, f"status on a refusal: {code} {err}")
    code, _, _ = tool(["status"], StandInApi((401, {})))
    expect(code == EXIT_CONFIG, "status with a refused root credential must exit 78")
    code, _, err = tool(["status"], StandInApi((404, {})))
    expect(code == EXIT_FAILURE and err.strip() == EMBED_UNSUPPORTED_MESSAGE, f"status on a server without Embed enablement: {code} {err}")
    for value in (
        {"enabled": True},
        {"enabled": "yes", "client_limit": 1, "active_client_count": 1},
        {"enabled": True, "client_limit": -1, "active_client_count": 0},
        {"enabled": True, "client_limit": 1.5, "active_client_count": 0},
        {"enabled": 1, "client_limit": 1, "active_client_count": 1},
        {"enabled": True, "client_limit": True, "active_client_count": 1},
    ):
        code, out, _ = tool(["status"], StandInApi((200, value)))
        expect(code == EXIT_FAILURE and out == "", f"status must refuse {value}")


def self_test_failure_texts(directory, environ, tool, expect):
    """The unmapped-key and 404 texts."""
    texts = dict(environ, URNETWORK_CLIENT_MAP=os.path.join(directory, "texts.json"))
    for args in (["cap", "user:nobody", "--monthly", "1"], ["usage", "user:nobody"], ["remove", "user:nobody"], ["acl", "user:nobody", ACL_GROUP_DEFAULT]):
        api = StandInApi()
        code, _, err = tool(args, api, texts)
        expect(code == EXIT_CONFIG and err.strip() == UNMAPPED_MESSAGE and not api.requests, f"{args[0]} for an unmapped key must exit 78 with the unmapped line: {err}")
    olga = {"client_id": SELF_TEST_CLIENT, "by_client_jwt": self_test_jwt(SELF_TEST_CLIENT)}
    tool(["provision", "user:olga", os.path.join(directory, "olga.jwt")], StandInApi((200, olga)), texts)
    for args, route in ((["cap", "user:olga", "--monthly", "1"], CAP_ROUTE), (["usage", "user:olga"], CAP_ROUTE), (["usage-all"], CAPS_ROUTE)):
        code, _, err = tool(args, StandInApi((404, {})), texts)
        expect(code == EXIT_FAILURE and err.strip() == f"{route} answered 404: the server predates the data-cap routes", f"{args[0]} on a server without the cap routes: {err}")


def failure_transport_error():
    """What the real transport raises for an unreachable API."""
    return OSError("connection refused")


def run_with(tool, environ, map_path, args):
    """Runs args against another map."""
    other = dict(environ, URNETWORK_CLIENT_MAP=map_path)
    out, err = io.StringIO(), io.StringIO()
    with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
        code = run(args, other, StandInApi().factory)
    return code, out.getvalue(), err.getvalue()


def run_quietly(args, environ) -> int:
    with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
        return run(args, environ, StandInApi().factory)


if __name__ == "__main__":
    sys.exit(run(sys.argv[1:]))