macula-py 0.2.0__py3-none-win_amd64.whl

macula_py/__init__.py

@@ -0,0 +1,88 @@
+"""macula-py: a Python node on the macula 12 mesh, over macula-go's C ABI.
+
+    key = await NodeKey.generate("pq_hybrid")
+    async with await Pool.connect(key, [Seed(host, 4433, station_id)],
+                                  realm_trust={realm: realm_key}) as pool:
+        print(await pool.call(realm, "mcl-echo/echo", "hello"))
+"""
+
+from macula_py._wire import (
+    DEFAULT_CALL_TIMEOUT_MS,
+    DEFAULT_CONTENT_TIMEOUT_MS,
+    AlreadyAnsweredError,
+    ClosedError,
+    ContentUnavailableError,
+    InvalidArgumentError,
+    InvalidHandleError,
+    MaculaError,
+    MaculaTimeoutError,
+    NotFoundError,
+    NotSharedError,
+    ProviderError,
+    RefusedError,
+    RelayError,
+    StreamError,
+)
+from macula_py.key import NodeKey, Profile
+from macula_py.pool import (
+    DhtRecord,
+    Event,
+    FoundRecords,
+    LinkStatus,
+    Pool,
+    PoolEvent,
+    Provider,
+    RecordType,
+    Seed,
+    Served,
+    Subscription,
+)
+from macula_py.stream import (
+    Request,
+    Stream,
+    StreamData,
+    StreamEnd,
+    StreamEof,
+    StreamFrame,
+    StreamMode,
+    StreamReply,
+)
+
+__all__ = [
+    "DEFAULT_CALL_TIMEOUT_MS",
+    "DEFAULT_CONTENT_TIMEOUT_MS",
+    "AlreadyAnsweredError",
+    "ClosedError",
+    "ContentUnavailableError",
+    "DhtRecord",
+    "Event",
+    "FoundRecords",
+    "InvalidArgumentError",
+    "InvalidHandleError",
+    "LinkStatus",
+    "MaculaError",
+    "MaculaTimeoutError",
+    "NodeKey",
+    "NotFoundError",
+    "NotSharedError",
+    "Pool",
+    "PoolEvent",
+    "Profile",
+    "Provider",
+    "ProviderError",
+    "RecordType",
+    "RefusedError",
+    "RelayError",
+    "Request",
+    "Seed",
+    "Served",
+    "Stream",
+    "StreamData",
+    "StreamEnd",
+    "StreamEof",
+    "StreamError",
+    "StreamFrame",
+    "StreamMode",
+    "StreamReply",
+    "Subscription",
+]

macula_py/_abi.py

@@ -0,0 +1,91 @@
+"""macula-go's C ABI (abi/macula.h), declared for ctypes.
+
+Types are written as the header writes them, so tests/test_abi_declarations.py
+can hold this table to the header function for function; _native maps them to
+ctypes. Returned strings and byte buffers are declared as pointers (never
+c_char_p) so they can be freed with macula_free_string / macula_free_bytes.
+"""
+
+from __future__ import annotations
+
+ABI_VERSION = 1
+
+H = "macula_handle"
+ERR = "char**"
+REALM = "const uint8_t*"
+
+FUNCTIONS: dict[str, tuple[str, list[str]]] = {
+    # The library
+    "macula_abi_version": ("int32_t", []),
+    "macula_free_string": ("void", ["char*"]),
+    "macula_free_bytes": ("void", ["uint8_t*"]),
+    # Cancellation
+    "macula_cancel_new": (H, []),
+    "macula_cancel": ("void", [H]),
+    "macula_cancel_free": ("void", [H]),
+    # Node keys
+    "macula_key_generate": (H, ["const char*", H, ERR]),
+    "macula_key_load": (H, ["const char*", "const char*", ERR]),
+    "macula_key_load_or_create": (H, ["const char*", "const char*", H, ERR]),
+    "macula_key_save": ("void", [H, "const char*", ERR]),
+    "macula_key_node_id": ("void", [H, "uint8_t*", ERR]),
+    "macula_key_public_key": ("uint8_t*", [H, "size_t*", ERR]),
+    "macula_key_profile": ("char*", [H, ERR]),
+    "macula_key_sign": ("uint8_t*", [H, "const uint8_t*", "size_t", "size_t*", ERR]),
+    "macula_verify": (
+        "int32_t",
+        ["const uint8_t*", "size_t", "const uint8_t*", "size_t", "const uint8_t*", "size_t", "const char*", ERR],
+    ),
+    "macula_key_free": ("void", [H]),
+    # Pool
+    "macula_pool_connect": (H, [H, "const char*", "const char*", H, ERR]),
+    "macula_pool_close": ("void", [H]),
+    "macula_pool_node_id": ("void", [H, "uint8_t*", ERR]),
+    "macula_pool_status": ("char*", [H, ERR]),
+    "macula_pool_events_next": ("char*", [H, "int64_t", H, "int32_t*", ERR]),
+    # Calls
+    "macula_pool_call": ("char*", [H, REALM, "const char*", "const char*", "const uint8_t*", "int64_t", H, ERR]),
+    "macula_pool_providers": ("char*", [H, REALM, "const char*", "int64_t", H, ERR]),
+    # Publish / subscribe
+    "macula_pool_publish": ("void", [H, REALM, "const char*", "const char*", "int64_t", ERR]),
+    "macula_pool_subscribe": (H, [H, REALM, "const char*", ERR]),
+    "macula_subscription_next": ("char*", [H, "int64_t", H, "int32_t*", ERR]),
+    "macula_subscription_dropped": ("uint64_t", [H, ERR]),
+    "macula_subscription_stop": ("void", [H]),
+    # Serving
+    "macula_pool_serve": (H, [H, REALM, "const char*", ERR]),
+    "macula_pool_serve_stream": (H, [H, REALM, "const char*", "int32_t", ERR]),
+    "macula_served_next": ("char*", [H, "int64_t", H, "macula_handle*", "int32_t*", ERR]),
+    "macula_pending_reply": ("void", [H, "const char*", ERR]),
+    "macula_pending_error": ("void", [H, "const char*", ERR]),
+    "macula_served_stop": ("void", [H, ERR]),
+    # Streams
+    "macula_pool_open_stream": (
+        H,
+        [H, REALM, "const char*", "int32_t", "const char*", "const uint8_t*", "int64_t", "int64_t", H, ERR],
+    ),
+    "macula_stream_request": ("char*", [H, ERR]),
+    "macula_stream_send_bytes": ("void", [H, "const uint8_t*", "size_t", ERR]),
+    "macula_stream_send_json": ("void", [H, "const char*", ERR]),
+    "macula_stream_close_send": ("void", [H, ERR]),
+    "macula_stream_reply": ("void", [H, "const char*", ERR]),
+    "macula_stream_abort": ("void", [H, "const char*", "const char*", ERR]),
+    "macula_stream_close": ("void", [H, ERR]),
+    "macula_stream_recv": ("char*", [H, "int64_t", H, ERR]),
+    "macula_stream_free": ("void", [H]),
+    # Content
+    "macula_pool_share_content": (
+        "void",
+        [H, REALM, "const uint8_t*", "size_t", "const char*", "int64_t", H, "uint8_t*", ERR],
+    ),
+    "macula_pool_unshare_content": ("void", [H, REALM, "const uint8_t*", "int64_t", H, ERR]),
+    "macula_pool_get_content": (
+        "uint8_t*",
+        [H, REALM, "const uint8_t*", "const char*", "int64_t", H, "size_t*", ERR],
+    ),
+    # DHT records
+    "macula_pool_find_record": ("char*", [H, "const uint8_t*", "int64_t", H, ERR]),
+    "macula_pool_find_records": ("char*", [H, "const uint8_t*", "int64_t", H, ERR]),
+    "macula_pool_find_records_by_type": ("char*", [H, "int32_t", "int64_t", H, ERR]),
+    "macula_pool_put_record": ("void", [H, "const uint8_t*", "size_t", "int64_t", H, ERR]),
+}

macula_py/_blocking.py

@@ -0,0 +1,123 @@
+"""Running blocking native calls from asyncio.
+
+Every native call runs on a daemon thread of its own (ctypes releases the
+GIL for its duration), never on asyncio's default executor: inbox waits
+(served calls, subscriptions, stream receives) block for as long as their
+source lives, and a bounded shared pool full of them would starve every
+other call, including the cancellations meant to end them.
+
+run_blocking gives the call a cancel token of its own. Cancelling the
+awaiting task cancels the token, which ends the native call early instead of
+waiting out its timeout, and returns at once; the call's thread frees the
+token once the native call has returned. A result nobody awaits any more (it
+raced the cancellation, or landed in the same loop iteration) is handed to
+discard, so a handle it carries is released rather than leaked; an error is
+taken and dropped, however many times the task was cancelled.
+
+run_native runs a short native call that takes no token.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from typing import Callable, Protocol, TypeVar
+
+T = TypeVar("T")
+
+
+class Cancels(Protocol):
+    def new(self) -> int: ...
+    def cancel(self, h: int) -> None: ...
+    def free(self, h: int) -> None: ...
+
+
+class NativeCancelled(Exception):
+    """The native call ended with the error kind "cancelled"."""
+
+
+def _settle(future: asyncio.Future, result: object, error: BaseException | None) -> None:
+    if future.done():
+        return
+    if error is not None:
+        future.set_exception(error)
+    else:
+        future.set_result(result)
+
+
+def _start(work: Callable[[], T], name: str) -> asyncio.Future:
+    """work() on a thread of its own; its outcome settles the returned future."""
+    loop = asyncio.get_running_loop()
+    future: asyncio.Future = loop.create_future()
+    # Consume the outcome up front, so an outcome nobody awaits any more (the
+    # task was cancelled) is never reported as unretrieved.
+    future.add_done_callback(lambda f: f.cancelled() or f.exception())
+
+    def run() -> None:
+        try:
+            outcome: tuple[object, BaseException | None] = (work(), None)
+        except BaseException as e:  # handed to the awaiting task
+            outcome = (None, e)
+        try:
+            loop.call_soon_threadsafe(_settle, future, *outcome)
+        except RuntimeError:
+            pass  # the loop closed; nobody is waiting
+
+    threading.Thread(target=run, name=name, daemon=True).start()
+    return future
+
+
+async def run_native(call: Callable[[], T]) -> T:
+    """call() on a thread of its own. Not cancellable: cancelling the task
+    stops the waiting, and the native call runs to its end."""
+    return await asyncio.shield(_start(call, "macula-py native"))
+
+
+def _discard_on_result(future: asyncio.Future, discard: Callable[[T], None]) -> None:
+    def hand_over(f: asyncio.Future) -> None:
+        if f.cancelled() or f.exception() is not None:
+            return
+        threading.Thread(target=discard, args=(f.result(),), name="macula-py discard", daemon=True).start()
+
+    future.add_done_callback(hand_over)
+
+
+async def run_blocking(
+    call: Callable[[int], T], cancels: Cancels, discard: Callable[[T], None] | None = None
+) -> T:
+    """call(cancel_token) on a thread of its own, cancelled with the task.
+    discard(result) releases a result that arrives when nobody awaits it."""
+    cancelled = threading.Event()
+    token: list[int] = []
+
+    def work() -> T:
+        h = cancels.new()
+        token.append(h)
+        try:
+            if cancelled.is_set():
+                cancels.cancel(h)
+            return call(h)
+        except NativeCancelled as e:
+            if cancelled.is_set():
+                raise
+            # "cancelled" without our token cancelled is the native side's
+            # own failure, not a cancellation this task asked for.
+            from macula_py._wire import MaculaError
+
+            raise MaculaError(f"macula-py: {e}") from None
+        finally:
+            cancels.free(h)
+
+    future = _start(work, "macula-py blocking")
+    try:
+        return await asyncio.shield(future)
+    except NativeCancelled:
+        raise asyncio.CancelledError() from None
+    except asyncio.CancelledError:
+        if not future.done():
+            cancelled.set()
+            if token:
+                cancels.cancel(token[0])
+        if discard is not None:
+            _discard_on_result(future, discard)
+        raise

macula_py/_library.py

@@ -0,0 +1,38 @@
+"""Where macula-go's shared C ABI library is: the copy the platform wheel
+carries in macula_py/_native/, or the file MACULA_LIBRARY_PATH names."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+_PACKAGE_NATIVE_DIR = Path(__file__).parent / "_native"
+
+
+def library_file_name(platform: str = sys.platform) -> str:
+    """The library's file name on platform (a sys.platform value)."""
+    if platform.startswith("linux"):
+        return "libmacula.so"
+    if platform == "darwin":
+        return "libmacula.dylib"
+    if platform == "win32":
+        return "macula.dll"
+    raise OSError(f"macula-py: no macula-go library build for platform {platform!r}")
+
+
+def library_path(package_dir: Path = _PACKAGE_NATIVE_DIR) -> Path:
+    """The library file to load."""
+    override = os.environ.get("MACULA_LIBRARY_PATH")
+    if override:
+        path = Path(override)
+        if not path.is_file():
+            raise OSError(f"macula-py: MACULA_LIBRARY_PATH names {path}, which is not a file")
+        return path
+    path = package_dir / library_file_name()
+    if not path.is_file():
+        raise OSError(
+            f"macula-py: {path} is missing: there is no macula-py wheel for this platform "
+            "installed. Build macula-go's cabi as a shared library and set MACULA_LIBRARY_PATH to it."
+        )
+    return path

macula_py/_native.py

@@ -0,0 +1,115 @@
+"""macula-go's shared library, loaded once with ctypes and declared from
+_abi. A library built for another ABI version is refused on load.
+
+invoke() calls one function with the trailing err_out the contract gives
+every fallible call, and raises the error its JSON names. Strings and byte
+buffers the library returns are copied and freed here, so nothing above
+this module touches library memory.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import threading
+from typing import Any
+
+from macula_py._abi import ABI_VERSION, FUNCTIONS
+from macula_py._library import library_path
+from macula_py._wire import MaculaError, native_error
+
+_C_TYPES: dict[str, Any] = {
+    "void": None,
+    "int32_t": ctypes.c_int32,
+    "int64_t": ctypes.c_int64,
+    "uint64_t": ctypes.c_uint64,
+    "size_t": ctypes.c_size_t,
+    "macula_handle": ctypes.c_size_t,
+    # Returned memory stays a raw address, to be copied and freed.
+    "char*": ctypes.c_void_p,
+    "uint8_t*": ctypes.c_void_p,
+    "const char*": ctypes.c_char_p,
+    "const uint8_t*": ctypes.c_char_p,
+    "size_t*": ctypes.POINTER(ctypes.c_size_t),
+    "int32_t*": ctypes.POINTER(ctypes.c_int32),
+    "macula_handle*": ctypes.POINTER(ctypes.c_size_t),
+    "char**": ctypes.POINTER(ctypes.c_void_p),
+}
+
+
+class Native:
+    """The loaded library."""
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+        self.lib = ctypes.CDLL(path)
+        for name, (returns, parameters) in FUNCTIONS.items():
+            function = getattr(self.lib, name)
+            function.restype = _C_TYPES[returns]
+            function.argtypes = [_C_TYPES[p] for p in parameters]
+        version = self.lib.macula_abi_version()
+        if version != ABI_VERSION:
+            raise MaculaError(
+                f"macula-py: {path} is macula C ABI {version}, and this macula-py binds ABI {ABI_VERSION}"
+            )
+        self.cancels = _Cancels(self.lib)
+
+    def invoke(self, name: str, *args: Any) -> Any:
+        """name(*args, &err_out), raising the error err_out names."""
+        err = ctypes.c_void_p(None)
+        result = getattr(self.lib, name)(*args, ctypes.byref(err))
+        if err.value:
+            text = ctypes.string_at(err.value).decode("utf-8", "replace")
+            self.lib.macula_free_string(err.value)
+            raise native_error(text)
+        return result
+
+    def call(self, name: str, *args: Any) -> Any:
+        """name(*args) for a function with no err_out."""
+        return getattr(self.lib, name)(*args)
+
+    def take_string(self, address: int | None) -> str | None:
+        """The string at address, freed; None for NULL."""
+        if not address:
+            return None
+        try:
+            return ctypes.string_at(address).decode("utf-8")
+        finally:
+            self.lib.macula_free_string(address)
+
+    def take_bytes(self, address: int | None, length: int) -> bytes:
+        """length bytes at address, freed; b"" for NULL."""
+        if not address:
+            return b""
+        try:
+            return ctypes.string_at(address, length)
+        finally:
+            self.lib.macula_free_bytes(address)
+
+
+class _Cancels:
+    """Cancel tokens, as _blocking.run_blocking takes them."""
+
+    def __init__(self, lib: ctypes.CDLL) -> None:
+        self._lib = lib
+
+    def new(self) -> int:
+        return self._lib.macula_cancel_new()
+
+    def cancel(self, h: int) -> None:
+        self._lib.macula_cancel(h)
+
+    def free(self, h: int) -> None:
+        self._lib.macula_cancel_free(h)
+
+
+_native: Native | None = None
+_lock = threading.Lock()
+
+
+def native() -> Native:
+    """The library, loaded on first use."""
+    global _native
+    with _lock:
+        if _native is None:
+            _native = Native(str(library_path()))
+        return _native

macula_py/_wire.py

@@ -0,0 +1,213 @@
+"""The shapes every part of the API shares: payloads, ids, and the errors a
+call, a stream or a fetch ends with.
+
+A payload is what macula's wire CBOR carries: str, int (within int64), float,
+None, bytes, lists (or tuples) and dicts with str keys. There is no boolean on the wire;
+encode true/false as 1/0 yourself. Python's bool is an int, so a bool
+reaching the wire is refused here rather than silently sent as JSON true.
+
+Bytes go in as ``bytes`` and come out as ``bytes``, so a value received can
+be sent back unchanged.
+
+Errors: the native layer reports each failure as JSON with a fixed ``kind``
+(macula-go's cabi/CONTRACT.md "Errors"); native_error maps each kind to its
+class here.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+from typing import Union
+
+from macula_py._blocking import NativeCancelled
+
+JsonValue = Union[str, int, float, None, bytes, list["JsonValue"], tuple, dict[str, "JsonValue"]]
+Id = Union[str, bytes]
+Mcid = Union[str, bytes]
+
+DEFAULT_CALL_TIMEOUT_MS = 5_000
+DEFAULT_CONTENT_TIMEOUT_MS = 300_000
+
+
+class MaculaError(Exception):
+    """A failure the native layer reported (kind ``failed``), and the base of
+    every macula-py error."""
+
+
+class MaculaTimeoutError(MaculaError, TimeoutError):
+    """The call's timeout ran out."""
+
+
+class InvalidArgumentError(MaculaError, ValueError):
+    """A malformed id, JSON, profile, mode, size or payload."""
+
+
+class InvalidHandleError(MaculaError):
+    """A handle this process does not hold (freed, closed, or of another kind)."""
+
+
+class NotFoundError(MaculaError):
+    """No DHT record under that key."""
+
+
+class AlreadyAnsweredError(MaculaError):
+    """A served call was answered already."""
+
+
+class ClosedError(MaculaError):
+    """The pool, subscription, served procedure or stream has ended."""
+
+
+class RefusedError(MaculaError):
+    """The network refused it: an advertisement, an admission, a key."""
+
+
+class ProviderError(MaculaError):
+    """A provider's own ERROR for a call: ``handler_error`` with the handler's
+    text, ``temporary_relay_failure`` for a handler that crashed,
+    ``unknown_next_peer`` for a procedure it does not serve, or an admission
+    refusal (``expired``, ``request_copy``, ``caller_quota``, ...)."""
+
+    def __init__(self, code: str, detail: str) -> None:
+        super().__init__(f"macula-py: the provider answered {code}" + (f": {detail}" if detail else ""))
+        self.code = code
+        self.detail = detail
+
+
+class RelayError(MaculaError):
+    """A station's signed relay error for a call: it could not relay it."""
+
+    def __init__(self, code: str) -> None:
+        super().__init__(f"macula-py: the station could not relay the call: {code}")
+        self.code = code
+
+
+class StreamError(MaculaError):
+    """A stream ended by a STREAM_ERROR: the peer's, a relay error from the
+    station (``relay``), or this side's own (e.g. ``resource_exhausted``)."""
+
+    def __init__(self, code: str, detail: str, relay: bool) -> None:
+        super().__init__(f"macula-py: stream error {code}" + (f": {detail}" if detail else ""))
+        self.code = code
+        self.detail = detail
+        self.relay = relay
+
+
+class NotSharedError(MaculaError):
+    """Content no node announces in the realm."""
+
+
+class ContentUnavailableError(MaculaError):
+    """Content every announcing node failed to give; ``failures`` names each
+    failure (unreachable, not the content asked for, over the bounds, ...)."""
+
+    def __init__(self, failures: list[str]) -> None:
+        super().__init__("macula-py: no sharer gave the content: " + "; ".join(failures))
+        self.failures = failures
+
+
+_INT64_MIN, _INT64_MAX = -(2**63), 2**63 - 1
+
+
+def _to_wire(value: object) -> object:
+    if isinstance(value, bool):
+        raise TypeError("macula-py: no boolean on the macula wire; encode true/false as 1/0")
+    if isinstance(value, int):
+        if not _INT64_MIN <= value <= _INT64_MAX:
+            raise ValueError(f"macula-py: {value} is outside int64, the integers macula's wire carries")
+        return value
+    if value is None or isinstance(value, (str, float)):
+        return value
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return {"$bytes": base64.b64encode(bytes(value)).decode("ascii")}
+    if isinstance(value, (list, tuple)):
+        return [_to_wire(v) for v in value]
+    if isinstance(value, dict):
+        out = {}
+        for k, v in value.items():
+            if not isinstance(k, str):
+                raise TypeError(f"macula-py: map keys must be str, got {type(k).__name__}")
+            out[k] = _to_wire(v)
+        return out
+    raise TypeError(f"macula-py: a {type(value).__name__} has no macula wire form")
+
+
+def encode_payload(value: object) -> str:
+    """value as the JSON text the native layer converts to wire CBOR."""
+    return json.dumps(_to_wire(value), separators=(",", ":"), allow_nan=False)
+
+
+def _from_wire(obj: dict) -> object:
+    if len(obj) == 1 and isinstance(obj.get("$bytes"), str):
+        return base64.b64decode(obj["$bytes"], validate=True)
+    return obj
+
+
+def decode_payload(text: str) -> object:
+    """JSON text from the native layer as Python values, tagged bytes as bytes."""
+    return json.loads(text, object_hook=_from_wire)
+
+
+_HEX64 = re.compile(r"[0-9a-fA-F]{64}")
+_HEX100 = re.compile(r"[0-9a-fA-F]{100}")
+
+
+def id32(value: Id, what: str = "id") -> bytes:
+    """A 32-byte id (node_id, realm id, record key) from 64 hex chars or 32 bytes."""
+    if isinstance(value, str):
+        if not _HEX64.fullmatch(value):
+            raise ValueError(f"macula-py: {what} must be 64 hex characters")
+        return bytes.fromhex(value)
+    if len(value) != 32:
+        raise ValueError(f"macula-py: {what} must be 32 bytes, got {len(value)}")
+    return bytes(value)
+
+
+def mcid50(value: Mcid) -> bytes:
+    """A content id (MCID) from 100 hex chars or 50 bytes."""
+    if isinstance(value, str):
+        if not _HEX100.fullmatch(value):
+            raise ValueError("macula-py: a content id is 100 hex characters (50 bytes)")
+        return bytes.fromhex(value)
+    if len(value) != 50:
+        raise ValueError(f"macula-py: a content id is 50 bytes, got {len(value)}")
+    return bytes(value)
+
+
+_KINDS: dict[str, type[MaculaError]] = {
+    "timeout": MaculaTimeoutError,
+    "invalid_argument": InvalidArgumentError,
+    "invalid_handle": InvalidHandleError,
+    "not_found": NotFoundError,
+    "not_shared": NotSharedError,
+    "answered": AlreadyAnsweredError,
+    "closed": ClosedError,
+    "refused": RefusedError,
+    "failed": MaculaError,
+}
+
+
+def native_error(text: str) -> Exception:
+    """The native layer's error JSON as the class its kind names. A kind this
+    binding does not know, or text that is not the contract's JSON, comes out
+    as a MaculaError naming it, never silently as something else."""
+    try:
+        error = json.loads(text)
+        kind = error["kind"]
+        message = str(error.get("message") or kind)
+    except (ValueError, KeyError, TypeError):
+        return MaculaError(f"macula-py: the native layer failed with {text!r}")
+    if kind == "cancelled":
+        return NativeCancelled(message)
+    if kind == "provider_error":
+        return ProviderError(str(error.get("code") or ""), str(error.get("detail") or ""))
+    if kind == "relay_error":
+        return RelayError(str(error.get("code") or ""))
+    if kind == "unavailable":
+        return ContentUnavailableError([str(f) for f in error.get("failures") or []])
+    cls = _KINDS.get(kind)
+    if cls is None:
+        return MaculaError(f"macula-py: the native layer failed with unknown kind {kind!r}: {message}")
+    return cls(f"macula-py: {message}")