zygo-sdk 0.1.2__py3-none-any.whl

zygo_sdk/__init__.py

@@ -0,0 +1,119 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Zygo — warm sandboxes for function-shaped code, from Python.
+
+    import zygo_sdk as zygo
+
+    client = zygo.connect()                      # `zygo api` on loopback
+    resize = client.fn("resize")                 # a function from sandbox.toml
+    out = resize({"url": "..."})                 # ~2 ms, a fresh process
+    print(out.result)
+
+A warm function costs about a millisecond and gets a clean process per request.
+A one-shot sandbox costs tens of milliseconds and needs nothing declared in
+advance:
+
+    r = client.run("python:3.12-slim", ["python3", "-c", "print(6*7)"])
+    print(r.stdout)
+
+For an event loop, ``zygo.aio`` is the same API with every call a coroutine:
+
+    async with zygo.aio.connect() as client:
+        out = await client.call("resize", {"url": "..."})
+
+A refused request — :class:`Busy`, or :class:`Unavailable` while the host is
+still building something — can be retried for you: ``zygo.connect(retries=3)``
+waits the server's ``Retry-After`` and sends it again. Off by default.
+
+This package talks to ``zygo api`` over HTTP — on a unix socket when the API is
+on this machine, which is the usual case and needs no token. It has no
+dependencies.
+
+What it is *not* is a second implementation of Zygo. Every boundary a sandbox
+has is built by the Zygo binary and enforced by the kernel; nothing here can
+widen one, and an API started without ``--allow-deploy`` will not let this
+package create a sandbox at all.
+"""
+
+from ._endpoint import DEFAULT_URL, Endpoint
+from ._errors import (
+    AuthError,
+    Busy,
+    Cancelled,
+    HandlerError,
+    NotFound,
+    SpecError,
+    Stuck,
+    Timeout,
+    TransportError,
+    Unavailable,
+    ZygoError,
+)
+from ._models import (
+    Deps,
+    Event,
+    Function,
+    LogEntry,
+    LogPage,
+    Metrics,
+    Minted,
+    Result,
+    Run,
+    Runtime,
+    Script,
+    Served,
+    Tenant,
+    Token,
+)
+from ._sync import Client, FunctionHandle, connect
+
+__version__ = "0.1.2"
+
+__all__ = [
+    "aio",
+    "Client",
+    "FunctionHandle",
+    "connect",
+    "DEFAULT_URL",
+    "Endpoint",
+    # results
+    "Deps",
+    "Event",
+    "Function",
+    "LogEntry",
+    "LogPage",
+    "Metrics",
+    "Minted",
+    "Result",
+    "Run",
+    "Runtime",
+    "Script",
+    "Served",
+    "Tenant",
+    "Token",
+    # failures
+    "AuthError",
+    "Busy",
+    "Cancelled",
+    "HandlerError",
+    "NotFound",
+    "SpecError",
+    "Stuck",
+    "Timeout",
+    "TransportError",
+    "Unavailable",
+    "ZygoError",
+]
+
+
+def __getattr__(name: str):  # noqa: ANN202 - PEP 562, a module attribute
+    """``zygo_sdk.aio`` without a second import line.
+
+    Loaded on first use rather than here, so that ``import zygo_sdk`` does not
+    pull in :mod:`asyncio` for a script that never opens an event loop. Both
+    ``import zygo_sdk.aio`` and ``zygo_sdk.aio`` reach the same module.
+    """
+    if name == "aio":
+        from importlib import import_module
+
+        return import_module(".aio", __name__)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

zygo_sdk/_endpoint.py

@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Where the API is, and how it was decided.
+
+One function, because the rule has to be the same for the synchronous and the
+asynchronous client. Two discovery orders that drift is a support question
+nobody can answer from the traceback.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+#: What ``zygo api`` listens on when nothing says otherwise.
+DEFAULT_URL = "http://127.0.0.1:7700"
+
+
+@dataclass(frozen=True)
+class Endpoint:
+    """A parsed address: either a unix socket path or a host and port."""
+
+    url: str
+    socket_path: Optional[str] = None
+    host: str = "127.0.0.1"
+    port: int = 7700
+    tls: bool = False
+
+    @property
+    def is_unix(self) -> bool:
+        return self.socket_path is not None
+
+    def __str__(self) -> str:
+        return self.url
+
+
+def resolve(url: Optional[str] = None) -> Endpoint:
+    """Work out which API to talk to.
+
+    In order: the argument, then ``ZYGO_API_URL``, then loopback on the port
+    ``zygo api`` uses by default. Accepts ``unix:///path/to.sock``,
+    ``http://host:port``, ``https://host:port`` and a bare ``host:port``.
+    """
+    text = url or os.environ.get("ZYGO_API_URL") or DEFAULT_URL
+    return parse(text)
+
+
+def parse(text: str) -> Endpoint:
+    text = text.strip()
+    if text.startswith("unix://"):
+        path = text[len("unix://") :]
+        if not path:
+            raise ValueError("unix:// needs a path, e.g. unix:///run/user/1000/zygo/api.sock")
+        return Endpoint(url=text, socket_path=path)
+
+    tls = False
+    rest = text
+    if text.startswith("https://"):
+        tls, rest = True, text[len("https://") :]
+    elif text.startswith("http://"):
+        rest = text[len("http://") :]
+    elif "://" in text:
+        scheme = text.split("://", 1)[0]
+        raise ValueError(f"`{scheme}://` is not an address Zygo serves; use http://, https:// or unix://")
+
+    # A trailing path is dropped rather than honoured: every route this client
+    # calls is rooted, and silently prefixing them would turn a typo in the
+    # address into a 404 on every call.
+    rest = rest.split("/", 1)[0]
+    host, _, port_text = rest.rpartition(":")
+    if not host:
+        host, port_text = rest, "443" if tls else "7700"
+    try:
+        port = int(port_text)
+    except ValueError as e:
+        raise ValueError(f"`{port_text}` is not a port number, in `{text}`") from e
+
+    scheme = "https" if tls else "http"
+    return Endpoint(url=f"{scheme}://{host}:{port}", host=host, port=port, tls=tls)

zygo_sdk/_errors.py

@@ -0,0 +1,241 @@
+# SPDX-License-Identifier: Apache-2.0
+"""What can go wrong, as types a caller can branch on.
+
+The distinctions here are the ones that change what a caller should do next,
+and no others. A handler that raised is not the same as a sandbox that ran out
+of time, which is not the same as a pool that is full — the first is a bug in
+the function, the second is a limit doing its job, and the third is worth
+retrying in a moment. Collapsing them into one exception with a message is how
+a caller ends up parsing English to decide whether to retry.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class ZygoError(Exception):
+    """Base class, so ``except zygo_sdk.ZygoError`` catches everything from here."""
+
+
+class TransportError(ZygoError):
+    """The API could not be reached, or answered with something unreadable.
+
+    Never raised because the *sandbox* failed: that always arrives as one of
+    the classes below, with the sandbox's own output attached.
+    """
+
+
+class AuthError(ZygoError):
+    """The token was missing, wrong, or not permitted to do this.
+
+    A 403 usually means the API was started without ``--allow-deploy`` and the
+    call was one that creates or destroys a sandbox.
+    """
+
+
+class NotFound(ZygoError):
+    """No function under that name."""
+
+
+class Busy(ZygoError):
+    """The function is at its concurrency limit and refused the request.
+
+    Not a failure of the call: it is backpressure, and the request never ran.
+    Retrying after ``retry_after`` seconds is the intended response.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        in_flight: int = 0,
+        queued: int = 0,
+        limit: int = 0,
+        retry_after: float = 1.0,
+    ) -> None:
+        super().__init__(message)
+        self.in_flight = in_flight
+        self.queued = queued
+        self.limit = limit
+        self.retry_after = retry_after
+
+
+class Unavailable(ZygoError):
+    """The host cannot do this *yet*: a `503`, and nothing about the request
+    needs changing.
+
+    Three things answer this way. A pool named against a dependency set that
+    is still building (``code == "deps_building"``, and the host suggests a
+    ``retry_after`` of a few seconds); a function whose zygote failed to warm
+    (``code == "warm_failed"``); and an API that is draining, which is what
+    :meth:`~zygo_sdk.Client.health` raises once the supervisor is stopping.
+
+    Like :class:`Busy`, the request never ran, so sending it again is safe.
+    Unlike :class:`Busy` it is not backpressure: the wait is for something the
+    host is doing, not for room.
+    """
+
+    def __init__(self, message: str, *, code: str = "", retry_after: float = 1.0) -> None:
+        super().__init__(message)
+        self.code = code
+        self.retry_after = retry_after
+
+
+class Timeout(ZygoError):
+    """The request exceeded the function's timeout and was killed.
+
+    Zygo's supervisor records that *it* killed the request, rather than
+    inferring it: a deadline kill and an out-of-memory kill both surface as
+    exit 137, and only the side that enforced the deadline can tell them apart.
+    So this is never a guess.
+    """
+
+    def __init__(self, message: str, *, stderr: str = "", metrics: Optional[Dict[str, Any]] = None) -> None:
+        super().__init__(message)
+        self.stderr = stderr
+        self.metrics = metrics or {}
+
+
+class Stuck(ZygoError):
+    """The sandbox stopped reporting this request, and it was killed.
+
+    Deliberately not a :class:`Timeout`. A timeout says the work is too slow or
+    the limit is too tight, and both are about numbers you chose. This says the
+    sandbox went quiet with budget left — an agent that stopped scheduling, a
+    child wedged where no signal it can send will reach it — so the thing to
+    look at is the function, not its `timeout`.
+
+    Only reachable for a request long enough to miss a heartbeat. A short one
+    that wedges is killed by its own deadline and raises :class:`Timeout`.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        request_id: str = "",
+        stdout: str = "",
+        stderr: str = "",
+        metrics: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.request_id = request_id
+        self.stdout = stdout
+        self.stderr = stderr
+        self.metrics = metrics or {}
+
+
+class Cancelled(ZygoError):
+    """Somebody stopped this request — usually the caller.
+
+    The third reading of exit 137. A cancel kill, a deadline kill and an
+    out-of-memory kill are one signal and three different things to tell a
+    caller, and only the side that sent the signal knows which it was: the
+    supervisor does, so this is never a guess either.
+
+    Distinct from :class:`Timeout` on purpose. A timeout says the work is too
+    slow or the limit is too tight; this says the answer stopped being wanted,
+    which needs no action at all.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        request_id: str = "",
+        stdout: str = "",
+        stderr: str = "",
+        metrics: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.request_id = request_id
+        self.stdout = stdout
+        self.stderr = stderr
+        self.metrics = metrics or {}
+
+
+class HandlerError(ZygoError):
+    """The handler raised. The exception text and both streams are attached."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        stdout: str = "",
+        stderr: str = "",
+        exit_code: int = 0,
+        metrics: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.stdout = stdout
+        self.stderr = stderr
+        self.exit_code = exit_code
+        self.metrics = metrics or {}
+
+
+class SpecError(ZygoError):
+    """The sandbox as described could not be resolved.
+
+    A bad image reference, a limit that contradicts another, a mount that has
+    to be absolute and is not. Always a problem with the request, never with
+    the host.
+    """
+
+
+def from_response(status: int, body: Dict[str, Any], retry_after: float = 1.0) -> ZygoError:
+    """Map one HTTP answer onto the exception a caller should see.
+
+    Status first, then the body's ``code`` where the status is ambiguous. The
+    fallback carries the status, because an unmapped code is a version skew
+    worth reporting rather than swallowing.
+    """
+    message = str(body.get("error") or body.get("message") or f"HTTP {status}")
+    if status in (401, 403):
+        return AuthError(message)
+    if status == 404:
+        return NotFound(message)
+    if status == 408:
+        return Timeout(message, stderr=str(body.get("stderr", "")), metrics=body.get("metrics"))
+    # 499 is nginx's for a client that went away, and the nearest thing to a
+    # registered code for a request the caller stopped.
+    if status == 504 or body.get("stuck") is True:
+        return Stuck(
+            message,
+            request_id=str(body.get("request_id", "")),
+            stdout=str(body.get("stdout", "")),
+            stderr=str(body.get("stderr", "")),
+            metrics=body.get("metrics"),
+        )
+    if status == 499 or body.get("cancelled") is True:
+        return Cancelled(
+            message,
+            request_id=str(body.get("request_id", "")),
+            stdout=str(body.get("stdout", "")),
+            stderr=str(body.get("stderr", "")),
+            metrics=body.get("metrics"),
+        )
+    if status == 429:
+        return Busy(
+            message,
+            in_flight=int(body.get("in_flight", 0)),
+            queued=int(body.get("queued", 0)),
+            limit=int(body.get("limit", 0)),
+            retry_after=retry_after,
+        )
+    if status == 400:
+        return SpecError(message)
+    if status == 503:
+        # `/healthz` says `status: stopping` and carries no `error`.
+        if "error" not in body and "message" not in body and body.get("status"):
+            message = f"the API is {body['status']}"
+        return Unavailable(message, code=str(body.get("code", "")), retry_after=retry_after)
+    if status == 500 and "exit_code" in body:
+        return HandlerError(
+            message,
+            stdout=str(body.get("stdout", "")),
+            stderr=str(body.get("stderr", "")),
+            exit_code=int(body.get("exit_code", 1)),
+            metrics=body.get("metrics"),
+        )
+    return ZygoError(f"{message} (HTTP {status})")