Developer SDK

Python examples

Install the SDK · View source on GitHub ↗

embed/caps.py

python
"""The client's data caps (EMBED_CONTRACT.md, "Backend: per-user data caps"): the
cap object, and the app's read of its own caps with its client JWT. The
backend sets caps with the root credential; the app only reads them. Pure
Python apart from the transport it is given (transport.py)."""

from dataclasses import dataclass
import json

# GET with the client JWT reads that client's own caps
CAP_ROUTE = "/network/client-data-cap"

CAPPED_REASON_MONTHLY = "monthly"
CAPPED_REASON_TOTAL = "total"

# The server refuses the cap read with this message while the team has not
# enabled Embed for the network (EMBED_CONTRACT.md, "Embed enablement").
EMBED_NOT_ENABLED_MESSAGE = "Embed isn't enabled for this network."


class EmbedNotEnabled:
    """What read_own_caps returns for the Embed-not-enabled refusal. Unlike a
    failed read, it clears the last reading, so both data fields read
    unavailable."""


EMBED_NOT_ENABLED = EmbedNotEnabled()


@dataclass(frozen=True)
class CapReading:
    """One cap object. A limit is None when that cap is not set; a used count is
    in bytes."""

    client_id: str
    monthly_byte_limit: int | None
    monthly_used_byte_count: int
    # RFC 3339 in UTC: when the monthly usage resets
    monthly_period_end: str
    total_byte_limit: int | None
    total_used_byte_count: int
    # true while a cap is reached: the client gets no new transfer contracts
    capped: bool
    # "monthly", "total", or "" when the client is not capped
    capped_reason: str


# a field value of the wrong type
_INVALID = object()


def _byte_limit(value):
    """A byte limit: None for null or absent, an integer of 0 or more, or _INVALID."""
    if value is None:
        return None
    if isinstance(value, int) and not isinstance(value, bool) and 0 <= value:
        return value
    return _INVALID


def _byte_count(value):
    """A used byte count: 0 for null or absent, an integer of 0 or more, or _INVALID."""
    if value is None:
        return 0
    return _byte_limit(value)


def _text(value):
    """A text field: "" for null or absent, the string, or _INVALID."""
    if value is None:
        return ""
    return value if isinstance(value, str) else _INVALID


def parse_cap_object(fields) -> CapReading | None:
    """The cap object in parsed JSON, or None when it is not one: not an object,
    an error answer, or a field of the wrong type. A null or absent limit is no
    cap, and a null or absent used count is 0. An unknown capped_reason is kept
    as it is: the status reads it as capped without a reset time."""
    if not isinstance(fields, dict) or fields.get("error") is not None:
        return None
    values = {
        "client_id": _text(fields.get("client_id")),
        "monthly_byte_limit": _byte_limit(fields.get("monthly_byte_limit")),
        "monthly_used_byte_count": _byte_count(fields.get("monthly_used_byte_count")),
        "monthly_period_end": _text(fields.get("monthly_period_end")),
        "total_byte_limit": _byte_limit(fields.get("total_byte_limit")),
        "total_used_byte_count": _byte_count(fields.get("total_used_byte_count")),
        "capped_reason": _text(fields.get("capped_reason")),
    }
    capped = fields.get("capped")
    if capped is None:
        capped = False
    if not isinstance(capped, bool) or any(value is _INVALID for value in values.values()):
        return None
    return CapReading(capped=capped, **values)


def is_embed_not_enabled(fields) -> bool:
    """Whether parsed JSON is the Embed-not-enabled refusal,
    {"error": {"message": "Embed isn't enabled for this network."}}."""
    error = fields.get("error") if isinstance(fields, dict) else None
    return isinstance(error, dict) and error.get("message") == EMBED_NOT_ENABLED_MESSAGE


def parse_cap_answer(answer: bytes) -> CapReading | None:
    """The cap object in an answer body, or None."""
    try:
        return parse_cap_object(json.loads(answer))
    except ValueError:
        return None


def read_own_caps(api_origin: str, client_jwt: str, transport) -> CapReading | EmbedNotEnabled | None:
    """GET /network/client-data-cap with the client JWT: this client's own caps.
    None for any failure: the API unreachable, an HTTP error (a server without
    the cap routes answers 404), or an answer that is not a cap object;
    EMBED_NOT_ENABLED for the Embed-not-enabled refusal."""
    headers = {"Authorization": "Bearer " + client_jwt, "Accept": "application/json"}
    try:
        status, answer = transport("GET", api_origin + CAP_ROUTE, headers, None)
    except (OSError, ValueError):
        return None
    if status != 200:
        return None
    try:
        fields = json.loads(answer)
    except ValueError:
        return None
    if is_embed_not_enabled(fields):
        return EMBED_NOT_ENABLED
    return parse_cap_object(fields)