decdn 0.1.0__py3-none-any.whl

decdn/__init__.py

@@ -0,0 +1,129 @@
+"""Python client for deCDN over a decdn gateway."""
+
+from decdn._version import __version__
+from decdn.base32 import (
+    base32_to_hash,
+    hash_to_base32,
+)
+from decdn.capability import (
+    Capability,
+    parse_capability,
+)
+from decdn.client import (
+    AsyncClient,
+    ByteRange,
+    Client,
+    Context,
+    HeadInfo,
+    Resolved,
+    VerifyMode,
+)
+from decdn.errors import (
+    DecdnError,
+    ErrorCode,
+)
+from decdn.hashing import (
+    Blake3Hasher,
+    blake3_hex,
+    create_blake3,
+)
+from decdn.loopback import (
+    AsyncLoopbackApi,
+    Delegate,
+    LoopbackApi,
+    RegisteredCapability,
+    Registration,
+)
+from decdn.manifest import (
+    MAX_MANIFEST_BYTES,
+    BundleManifest,
+    ManifestChunk,
+    ManifestEntry,
+    parse_manifest,
+)
+from decdn.pointer import (
+    AsyncPointerApi,
+    Pointer,
+    PointerApi,
+    PointerDomain,
+    PointerSet,
+    PointerSigner,
+    PointerTypedData,
+    TypedDataSigner,
+    pointer_signing_hash,
+    pointer_typed_data,
+    recover_pointer_signer,
+    sign_pointer,
+)
+from decdn.response import (
+    AsyncResponse,
+    ContentRange,
+    Response,
+)
+from decdn.uri import (
+    SCHEME,
+    DecdnUri,
+    UriKind,
+    format_uri,
+    parse_uri,
+)
+
+__all__ = [
+    "__version__",
+    # base32
+    "base32_to_hash",
+    "hash_to_base32",
+    # capability
+    "Capability",
+    "parse_capability",
+    # client
+    "AsyncClient",
+    "ByteRange",
+    "Client",
+    "Context",
+    "HeadInfo",
+    "Resolved",
+    "VerifyMode",
+    # errors
+    "DecdnError",
+    "ErrorCode",
+    # hashing
+    "Blake3Hasher",
+    "blake3_hex",
+    "create_blake3",
+    # loopback
+    "AsyncLoopbackApi",
+    "Delegate",
+    "LoopbackApi",
+    "RegisteredCapability",
+    "Registration",
+    # manifest
+    "MAX_MANIFEST_BYTES",
+    "BundleManifest",
+    "ManifestChunk",
+    "ManifestEntry",
+    "parse_manifest",
+    # pointer
+    "AsyncPointerApi",
+    "Pointer",
+    "PointerApi",
+    "PointerDomain",
+    "PointerSet",
+    "PointerSigner",
+    "PointerTypedData",
+    "TypedDataSigner",
+    "pointer_signing_hash",
+    "pointer_typed_data",
+    "recover_pointer_signer",
+    "sign_pointer",
+    # response
+    "AsyncResponse",
+    "ContentRange",
+    "Response",
+    # uri
+    "SCHEME",
+    "DecdnUri",
+    "UriKind",
+    "format_uri",
+    "parse_uri",
+]

decdn/_core.py

@@ -0,0 +1,324 @@
+"""The sans-I/O core of both clients: context selection, URLs, headers, the request plan of `get`,
+and what an answer's status and headers mean for its body.
+
+Nothing here touches the network. `Client` and `AsyncClient` parse, plan with this core, send,
+and hand the answer back to it.
+"""
+
+import json
+import re
+from collections import OrderedDict
+from dataclasses import dataclass
+from typing import Literal
+
+import httpx
+
+from decdn._hex import is_hash
+from decdn._mime import rewritten, site_type
+from decdn._verify import GuardOptions
+from decdn.base32 import hash_to_base32
+from decdn.errors import DecdnError
+from decdn.manifest import BundleManifest, ManifestEntry
+from decdn.pointer import PointerDomain
+from decdn.uri import SCHEME, DecdnUri, UriKind, format_uri, parse_uri
+
+Context = Literal["public", "loopback"]
+"""Where the client reaches the gateway: a public gateway, or the local one with its token."""
+
+VerifyMode = Literal["auto"] | bool
+"""`"auto"` verifies what can be verified; `True` refuses what cannot; `False` verifies nothing."""
+
+Verified = bool | Literal["skipped"]
+
+_DIGITS = re.compile(r"[0-9]+")
+_ETAG = re.compile(r'"?([0-9a-fA-F]{64})"?')
+_LOOPBACK_HOSTS = frozenset({"127.0.0.1", "localhost", "::1", "[::1]"})
+_RETRYABLE = frozenset({"PAYMENT_REQUIRED", "POOL_UNFUNDED", "RATE_LIMITED"})
+
+
+@dataclass(frozen=True)
+class ByteRange:
+    """A byte window: `length` bytes from `offset`, or to the end without `length`."""
+
+    offset: int
+    length: int | None = None
+
+
+@dataclass(frozen=True)
+class HeadInfo:
+    """What `head` knows about content without fetching it."""
+
+    size: int | None = None
+    hash: str | None = None
+    content_type: str | None = None
+
+
+@dataclass(frozen=True)
+class Resolved:
+    """What a URI names, once its manifest is read."""
+
+    kind: UriKind
+    # The URI's hash: of the blob, or of the bundle manifest.
+    hash: str
+    # The URI on the gateway's bare host.
+    bare_url: str
+    # The manifest entry an entry URI names.
+    entry: ManifestEntry | None = None
+    # The bundle or entry on its site origin.
+    site_url: str | None = None
+
+
+# Public through `decdn.client`, which re-exports them: reprs, docs and pickles name it.
+for _cls in (ByteRange, HeadInfo, Resolved):
+    _cls.__module__ = "decdn.client"
+
+
+@dataclass
+class Plan:
+    """One request `get` sends, and what its body must hash to."""
+
+    url: str
+    hash: str | None
+    length: int | None
+    verified: Verified
+    # The entry by its hash, unrewritten: where a verified entry comes from when its site answers
+    # with a type the gateway rewrites.
+    blob_url: str | None
+
+
+def config(message: str) -> DecdnError:
+    return DecdnError("CONFIG", message)
+
+
+def _digits(value: str | None) -> int | None:
+    """Return `value` as an int when it is ASCII digits only, else `None`."""
+    return int(value) if value is not None and _DIGITS.fullmatch(value) else None
+
+
+def parse(uri: str | DecdnUri) -> DecdnUri:
+    """Return `uri` parsed; a `DecdnUri` as is."""
+    return parse_uri(uri) if isinstance(uri, str) else uri
+
+
+def tail(uri: DecdnUri) -> str:
+    """Return `uri` without `decdn:` and the hash: `[/<path>][?ns=<id>]`, canonically encoded."""
+    return format_uri(uri)[len(SCHEME) + 64 :]
+
+
+def entry_of(manifest: BundleManifest, uri: DecdnUri) -> ManifestEntry:
+    """Return the manifest entry `uri` names; `NOT_FOUND` when the bundle has none."""
+    entry = manifest.entry(uri.path or "")
+    if entry is None:
+        named = json.dumps(uri.path, ensure_ascii=False)
+        raise DecdnError("NOT_FOUND", f"bundle {uri.hash} has no entry {named}")
+    return entry
+
+
+def retry_wait(error: DecdnError, retry: bool | float) -> int | None:
+    """Return the seconds to wait before the one retry `retry` asks for, or `None` for no retry.
+
+    A float caps the wait: a longer `Retry-After` is not waited out.
+    """
+    if retry is False or error.code not in _RETRYABLE or error.retry_after_secs is None:
+        return None
+    if not isinstance(retry, bool) and error.retry_after_secs > retry:
+        return None
+    return error.retry_after_secs
+
+
+class Core:
+    """A client's configuration, its manifest cache, and everything it decides without I/O."""
+
+    def __init__(
+        self,
+        gateway_url: str,
+        *,
+        token: str | None,
+        host: str | None,
+        pointer: PointerDomain | None,
+        verify: VerifyMode,
+        manifest_cache_size: int,
+    ) -> None:
+        try:
+            gateway = httpx.URL(gateway_url)
+        except httpx.InvalidURL as e:
+            raise config(f"not a gateway URL: {gateway_url}") from e
+        port = gateway.port
+        if gateway.scheme == "" or gateway.raw_host == b"" or (port is not None and not 0 <= port <= 65535):
+            raise config(f"not a gateway URL: {gateway_url}")
+        hostname = gateway.raw_host.decode("ascii")
+        self.context: Context = "loopback" if token is not None or hostname in _LOOPBACK_HOSTS else "public"
+        if token is not None and (host is None or host == ""):
+            raise config(
+                "a loopback token needs `host`: the host whose capability pays, sent as x-decdn-host"
+            )
+        self.scheme = gateway.scheme
+        self.port = port
+        bracketed = f"[{hostname}]" if ":" in hostname else hostname
+        # `host[:port]` of the gateway, the port only when it is not the scheme's default.
+        self.authority = bracketed if port is None else f"{bracketed}:{port}"
+        self.origin = f"{self.scheme}://{self.authority}"
+        self.token = token
+        self.host = host
+        self.pointer = pointer
+        self.verify: VerifyMode = verify
+        self.cache_size = manifest_cache_size
+        self.manifests: OrderedDict[str, BundleManifest] = OrderedDict()
+
+    def cache_get(self, hash: str) -> BundleManifest | None:
+        """Return the cached manifest of `hash`, now the most recently used, or `None`."""
+        manifest = self.manifests.get(hash)
+        if manifest is not None:
+            self.manifests.move_to_end(hash)
+        return manifest
+
+    def cache_put(self, hash: str, manifest: BundleManifest) -> None:
+        """Cache `manifest` by `hash`, evicting the least recently used past the cache size."""
+        self.manifests[hash] = manifest
+        self.manifests.move_to_end(hash)
+        while len(self.manifests) > self.cache_size:
+            self.manifests.popitem(last=False)
+
+    def auth_headers(self) -> dict[str, str]:
+        """Return the headers every bare-host request carries."""
+        if self.token is None or self.host is None:
+            return {}
+        return {"x-decdn-token": self.token, "x-decdn-host": self.host}
+
+    def is_bare(self, url: str) -> bool:
+        """Return whether `url` is on the gateway's bare host."""
+        return url.startswith(f"{self.origin}/")
+
+    def bare_url(self, uri: DecdnUri) -> str:
+        """Return the URI on the bare host."""
+        return f"{self.origin}/{uri.hash}{tail(uri)}"
+
+    def site_url(self, uri: str | DecdnUri) -> str:
+        """Return the site URL of a bundle or an entry."""
+        u = parse(uri)
+        if u.kind == "blob":
+            raise config("a blob has no site: only a bundle or an entry does")
+        label = hash_to_base32(u.hash)
+        host = label if u.namespace is None else f"{u.namespace}.{label}"
+        path = tail(DecdnUri(hash=u.hash, kind=u.kind, path=u.path))
+        if self.context == "loopback":
+            port = self.port if self.port is not None else 443 if self.scheme == "https" else 80
+            return f"{self.scheme}://{host}.localhost:{port}{path}"
+        return f"{self.scheme}://{host}.{self.authority}{path}"
+
+    def namespace_url(self, namespace: int) -> str:
+        """Return the host a namespace's pointer serves at on a public gateway: `https://<ns>.<host>/`."""
+        if isinstance(namespace, bool) or not isinstance(namespace, int):
+            raise config(f"a namespace id is an integer: got {namespace!r}")
+        if namespace <= 0:
+            raise config("a namespace id is at least 1")
+        if self.context == "loopback":
+            raise config("a loopback gateway holds no namespace pointers")
+        return f"{self.scheme}://{namespace}.{self.authority}/"
+
+    def manifest_hash(self, hash_or_uri: str | DecdnUri | None) -> str:
+        """Return the hash a manifest call names."""
+        if hash_or_uri is None:
+            raise config("manifest needs a hash outside a site page")
+        if isinstance(hash_or_uri, str) and is_hash(hash_or_uri):
+            return hash_or_uri.lower()
+        return parse(hash_or_uri).hash
+
+    def entry_blob_url(self, uri: DecdnUri, entry: ManifestEntry) -> str:
+        """Return an entry by its own hash, as a blob: the bytes the manifest names, unrewritten."""
+        return self.bare_url(DecdnUri(hash=entry.hash, kind="blob", namespace=uri.namespace))
+
+    def entry_url(self, uri: DecdnUri, entry: ManifestEntry | None) -> str:
+        """Return where an entry comes from, given its manifest entry when verifying."""
+        if entry is not None and rewritten(uri.path or "") and self.context != "loopback":
+            return self.entry_blob_url(uri, entry)
+        return self.bare_url(uri) if self.context == "loopback" else self.site_url(uri)
+
+    def needs_entry(self, uri: DecdnUri, mode: VerifyMode, ranged: bool) -> bool:
+        """Return whether planning `uri` needs its manifest entry: a verified whole entry does."""
+        return uri.kind == "entry" and mode is not False and not ranged
+
+    def plan(self, uri: DecdnUri, mode: VerifyMode, ranged: bool, entry: ManifestEntry | None) -> Plan:
+        """Return the request `get` sends for `uri`.
+
+        `entry` is the manifest entry, given exactly when `needs_entry` is true. Raises `CONFIG` for
+        what cannot be honoured as asked.
+        """
+        off: Verified = False if mode is False else "skipped"
+
+        def unverifiable(why: str) -> None:
+            if mode is True:
+                raise config(f"verify: true, but {why}")
+
+        if uri.kind == "blob":
+            # The gateway serves a blob whole: nothing declares its size, so a range would come
+            # back as every byte, or as an unverifiable window.
+            if ranged:
+                raise config("a blob has no declared size to range: fetch it whole, or range a bundle entry")
+            if mode is False:
+                return Plan(url=self.bare_url(uri), hash=None, length=None, verified=False, blob_url=None)
+            return Plan(url=self.bare_url(uri), hash=uri.hash, length=None, verified=True, blob_url=None)
+        if uri.kind == "bundle":
+            unverifiable("a bundle's index is a page the gateway rewrites")
+            url = self.bare_url(uri) if self.context == "loopback" else self.site_url(uri)
+            return Plan(url=url, hash=None, length=None, verified=off, blob_url=None)
+        if mode is False or ranged:
+            if ranged and mode is True:
+                raise config("verify: true, but a range cannot be verified")
+            return Plan(url=self.entry_url(uri, None), hash=None, length=None, verified=off, blob_url=None)
+        if entry is None:
+            raise ValueError("a verified entry is planned with its manifest entry")
+        url = self.entry_url(uri, entry)
+        blob_url = self.entry_blob_url(uri, entry)
+        return Plan(
+            url=url,
+            hash=entry.hash,
+            length=entry.size,
+            verified=True,
+            blob_url=blob_url if url != blob_url and self.context != "loopback" else None,
+        )
+
+    def range_header(self, r: ByteRange) -> str:
+        """Return the `Range` header of `r`; `CONFIG` unless the offset is at least 0 and the length 1."""
+        if (
+            isinstance(r.offset, bool)
+            or not isinstance(r.offset, int)
+            or r.offset < 0
+            or (r.length is not None and (isinstance(r.length, bool) or not isinstance(r.length, int)))
+            or (r.length is not None and r.length < 1)
+        ):
+            raise config("a range is a non-negative offset and a positive length")
+        end = "" if r.length is None else str(r.offset + r.length - 1)
+        return f"bytes={r.offset}-{end}"
+
+    def interpret(
+        self, plan: Plan, status: int, headers: httpx.Headers, ranged: ByteRange | None
+    ) -> tuple[Verified, GuardOptions]:
+        """Return what the answer to `plan` is: its `verified`, and the bounds its body is guarded by."""
+        # Only a window the caller asked for goes unhashed: whatever status the gateway answers a
+        # whole-body request with, its bytes must hash.
+        whole = ranged is None or status == 200
+        verified: Verified = "skipped" if plan.verified is True and not whole else plan.verified
+        hash_ = plan.hash if verified is True and plan.hash is not None else None
+        # The manifest's size bounds a whole entry both ways, and a window holds at most what was
+        # asked for. Content-Length bounds a body from below only: a body decoded on the way can
+        # run past it.
+        if whole and plan.length is not None:
+            return verified, GuardOptions(hash=hash_, length=plan.length, max=plan.length)
+        length = _digits(headers.get("content-length"))
+        max_ = ranged.length if not whole and ranged is not None and ranged.length is not None else None
+        return verified, GuardOptions(hash=hash_, length=length, max=max_)
+
+    def head_from_headers(self, headers: httpx.Headers) -> HeadInfo:
+        """Return what a public `HEAD` answer says: its size, hash (ETag) and type."""
+        size = _digits(headers.get("content-length"))
+        etag = _ETAG.fullmatch(headers.get("etag", ""))
+        return HeadInfo(
+            size=size,
+            hash=etag.group(1).lower() if etag is not None else None,
+            content_type=headers.get("content-type"),
+        )
+
+    def head_from_entry(self, entry: ManifestEntry) -> HeadInfo:
+        """Return what the manifest says of an entry."""
+        return HeadInfo(size=entry.size, hash=entry.hash, content_type=site_type(entry.path))

decdn/_hex.py

@@ -0,0 +1,23 @@
+"""Hex encoding helpers shared across the SDK."""
+
+import re
+
+_HEX_RE = re.compile(r"[0-9a-fA-F]*")
+_HASH_RE = re.compile(r"[0-9a-fA-F]{64}")
+
+
+def to_hex(data: bytes) -> str:
+    """Return the lowercase hex spelling of `data`."""
+    return data.hex()
+
+
+def from_hex(text: str) -> bytes | None:
+    """Return the bytes of an even-length hex string, or `None` if it is not hex."""
+    if len(text) % 2 != 0 or _HEX_RE.fullmatch(text) is None:
+        return None
+    return bytes.fromhex(text)
+
+
+def is_hash(text: str) -> bool:
+    """Return whether `text` is a BLAKE3 hash spelled as 64 hex characters."""
+    return _HASH_RE.fullmatch(text) is not None

decdn/_http.py

@@ -0,0 +1,88 @@
+"""Gateway answers as errors: every non-2xx answer becomes a `DecdnError` with the fields its
+contract carries (Retry-After, the `Link: <decdn:...>; rel="alternate"` fallback, the 402/503
+JSON body, the 416 size, the pointer 409 `seq`)."""
+
+import json
+import re
+from typing import Any
+
+import httpx
+
+from decdn.errors import DecdnError, ErrorCode
+
+CODES: dict[int, ErrorCode] = {
+    400: "BAD_URI",
+    401: "UNAUTHORIZED",
+    402: "PAYMENT_REQUIRED",
+    403: "FORBIDDEN",
+    404: "NOT_FOUND",
+    409: "CONFLICT",
+    413: "PAYLOAD_TOO_LARGE",
+    416: "RANGE_NOT_SATISFIABLE",
+    422: "UNPROCESSABLE",
+    429: "RATE_LIMITED",
+    502: "UPSTREAM",
+    503: "POOL_UNFUNDED",
+}
+
+_LINK = re.compile(r'<(decdn:[^>]+)>\s*;\s*rel="?alternate"?')
+_SEQ = re.compile(r'"seq"\s*:\s*([0-9]+)')
+_DIGITS = re.compile(r"[0-9]+")
+_RANGE_SIZE = re.compile(r"bytes \*/([0-9]+)")
+
+
+def is_success(status: int) -> bool:
+    """Return whether `status` is a 2xx answer."""
+    return 200 <= status <= 299
+
+
+def network_error(url: str, exc: Exception) -> DecdnError:
+    """Return the `NETWORK` error for a failure to reach the gateway at `url`.
+
+    The caller raises it `from exc`.
+    """
+    u = httpx.URL(url)
+    port = f":{u.port}" if u.port is not None else ""
+    return DecdnError("NETWORK", f"cannot reach {u.scheme}://{u.host}{port}: {exc}")
+
+
+def error_of(status: int, headers: httpx.Headers, body: str) -> DecdnError:
+    """Return the error for a gateway answer that is not a success.
+
+    `body` is the answer's text, read by the caller.
+    """
+    code: ErrorCode = CODES.get(status, "HTTP")
+    message = body.strip()
+    details: dict[str, Any] = {"status": status}
+    if message != "":
+        details["body"] = message
+    retry_after = headers.get("retry-after")
+    if retry_after is not None and _DIGITS.fullmatch(retry_after.strip()):
+        details["retry_after_secs"] = int(retry_after.strip())
+    link = _LINK.search(headers.get("link") or "")
+    if link is not None:
+        details["fallback_uri"] = link.group(1)
+    if headers.get("content-type", "").startswith("application/json"):
+        try:
+            parsed = json.loads(body)
+        except ValueError:
+            # Not JSON after all: the text stands.
+            parsed = None
+        if isinstance(parsed, dict):
+            if isinstance(parsed.get("error"), str):
+                message = parsed["error"]
+            if isinstance(parsed.get("uri"), str):
+                details["fallback_uri"] = parsed["uri"]
+            secs = parsed.get("retry_after_secs")
+            if isinstance(secs, int) and not isinstance(secs, bool) and secs >= 0:
+                details["retry_after_secs"] = secs
+        if parsed is not None:
+            # A u64 `seq` is read from its digits, as the gateway wrote it.
+            seq = _SEQ.search(body)
+            if seq is not None:
+                details["seq"] = int(seq.group(1))
+    if status == 416:
+        size = _RANGE_SIZE.fullmatch(headers.get("content-range", ""))
+        if size is not None:
+            details["size"] = int(size.group(1))
+    return DecdnError(code, message or f"gateway answered {status}", **details)

decdn/_mime.py

@@ -0,0 +1,68 @@
+"""MIME rules for site entries, mirroring the TypeScript SDK's `mime.ts`.
+
+What the gateway does with an entry by the extension of its name: whether a
+site rewrites it as it streams (the gateway rewrites the types mime_guess
+maps these extensions to:
+https://github.com/decdn/decdn/blob/main/crates/cli/src/commands/gateway/rewrite.rs),
+and the type a site serves it as, for the common web types. When it
+verifies off loopback, the client fetches these entries by their hash up
+front, and fetches by hash again any other entry a site answers with a
+type it rewrites.
+"""
+
+import re
+
+# Extensions a site serves as `text/html` or `text/css`, rewritten as they stream.
+_REWRITTEN_RE = re.compile(r"\.(html?|hxt|shtml|css)\Z", re.IGNORECASE)
+_EXTENSION_RE = re.compile(r"\.([^./]+)\Z")
+
+_TYPES: dict[str, str] = {
+    "html": "text/html",
+    "htm": "text/html",
+    "css": "text/css",
+    "js": "text/javascript",
+    "mjs": "text/javascript",
+    "json": "application/json",
+    "txt": "text/plain",
+    "md": "text/markdown",
+    "csv": "text/csv",
+    "xml": "text/xml",
+    "svg": "image/svg+xml",
+    "png": "image/png",
+    "jpg": "image/jpeg",
+    "jpeg": "image/jpeg",
+    "gif": "image/gif",
+    "webp": "image/webp",
+    "avif": "image/avif",
+    "ico": "image/x-icon",
+    "wasm": "application/wasm",
+    "pdf": "application/pdf",
+    "zip": "application/zip",
+    "gz": "application/gzip",
+    "tar": "application/x-tar",
+    "mp4": "video/mp4",
+    "webm": "video/webm",
+    "mp3": "audio/mpeg",
+    "ogg": "audio/ogg",
+    "woff": "font/woff",
+    "woff2": "font/woff2",
+}
+
+
+def rewritten(path: str) -> bool:
+    """Return whether a site rewrites the entry at `path`, so its bytes need not hash to the entry hash."""
+    return _REWRITTEN_RE.search(path) is not None
+
+
+def site_type(path: str) -> str:
+    """Return the type a site serves the entry at `path` as: text in UTF-8, bytes for an unknown extension."""
+    match = _EXTENSION_RE.search(path)
+    ext = match.group(1).lower() if match is not None else ""
+    content_type = _TYPES.get(ext, "application/octet-stream")
+    return f"{content_type}; charset=utf-8" if content_type.startswith("text/") else content_type
+
+
+def is_rewritten_type(content_type: str | None) -> bool:
+    """Return whether a response content type is one a site rewrites: `text/html` or `text/css`."""
+    essence = (content_type or "").split(";")[0].strip().lower()
+    return essence in ("text/html", "text/css")