briq-cloud 0.1.1__py3-none-any.whl

briq_cloud/__init__.py

@@ -0,0 +1,21 @@
+"""Python client for briq: sandboxes you create, run commands in, and read files from."""
+
+from ._async import AsyncBriq, AsyncSandbox
+from ._errors import BriqError, Code
+from ._models import ExecResult, FileInfo, OutputChunk, SandboxInfo
+from ._sync import Briq, Sandbox
+from ._version import __version__
+
+__all__ = [
+    "AsyncBriq",
+    "AsyncSandbox",
+    "Briq",
+    "BriqError",
+    "Code",
+    "ExecResult",
+    "FileInfo",
+    "OutputChunk",
+    "Sandbox",
+    "SandboxInfo",
+    "__version__",
+]

briq_cloud/_async.py

@@ -0,0 +1,300 @@
+"""The asynchronous client: the flows of ``_flows`` driven over ``httpx.AsyncClient``."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from collections.abc import Callable, Mapping, Sequence
+from types import TracebackType
+from typing import Any, TypeVar
+
+import httpx
+
+from . import _flows as f
+from ._config import headers, resolve, timeout_of
+from ._errors import BriqError
+from ._models import ExecResult, FileInfo, OutputChunk, SandboxInfo
+
+T = TypeVar("T")
+
+
+async def _pause(seconds: float) -> None:  # a name of its own, so tests can skip the waits
+    await asyncio.sleep(seconds)
+
+
+class AsyncBriq:
+    """A client for the briq API.
+
+    ``api_key`` falls back to ``BRIQ_API_KEY`` and ``base_url`` to ``BRIQ_API_URL``, then to the
+    public API. ``timeout`` is the seconds each request may take, a command and a sandbox's start
+    each add their own. ``http_client`` is an ``httpx.AsyncClient`` of your own (a proxy, a CA
+    bundle, a mounted transport): it is used as it is, except that no redirect is ever followed,
+    its ``base_url`` is ignored, and ``close`` leaves it open. ``transport`` is for tests.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._key, self._origin = resolve(api_key, base_url)
+        self._timeout = timeout
+        # The environment's proxy and CA settings apply (``HTTP(S)_PROXY``, ``SSL_CERT_FILE``).
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.AsyncClient(transport=transport)
+
+    async def close(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncBriq:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def create_sandbox(
+        self,
+        *,
+        name: str | None = None,
+        size: str | None = None,
+        image: str | None = None,
+        env: Mapping[str, str] | None = None,
+        secret_env: Mapping[str, str] | None = None,
+        sleep: str | None = None,
+        wait_timeout: float = 120.0,
+        idempotency_key: str | None = None,
+    ) -> AsyncSandbox:
+        """Make a sandbox and wait until it runs.
+
+        ``env`` values show in the sandbox's status; ``secret_env`` values are kept write-only
+        (the API must support it, else ``unsupported``). The request is sent once. When no
+        usable answer comes, the error is ``outcome_unknown``: the sandbox may exist, and the
+        same ``idempotency_key`` makes a second call return it instead of another.
+        """
+        info = await self._run(
+            f.create_sandbox(
+                name=name,
+                size=size,
+                env=env,
+                secret_env=secret_env,
+                sleep=sleep,
+                image=image,
+                wait_timeout=wait_timeout,
+                idempotency_key=idempotency_key,
+            )
+        )
+        return AsyncSandbox(self, info)
+
+    async def sandbox(self, id: str) -> AsyncSandbox:
+        """Reconnect to a sandbox by id. It must exist: ``not_found`` otherwise."""
+        return AsyncSandbox(self, await self._run(f.get_sandbox(id)))
+
+    # --- the driver ---
+
+    async def _send(self, request: f.Request) -> f.Reply:
+        built = self._http.build_request(
+            request.method,
+            self._origin + request.path,
+            params=request.query,
+            json=request.json,
+            content=request.content,
+            headers=headers(self._key, request.headers),
+            timeout=timeout_of(request.timeout or self._timeout),
+        )
+        try:
+            response = await self._http.send(built, stream=True, follow_redirects=False)
+        except (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout) as exc:
+            raise f.NoAnswer(never_sent=True) from exc
+        except httpx.HTTPError as exc:
+            raise f.NoAnswer(never_sent=False) from exc
+        try:
+            body = bytearray()
+            too_large = False
+            async for chunk in response.aiter_bytes():
+                body += chunk
+                if len(body) > request.max_bytes:
+                    too_large = True
+                    break
+        except httpx.HTTPError as exc:
+            raise f.NoAnswer(never_sent=False) from exc
+        finally:
+            await response.aclose()
+        return f.Reply(
+            response.status_code,
+            dict(response.headers),
+            bytes(body),
+            too_large,
+            response.num_bytes_downloaded,
+        )
+
+    async def _perform(self, step: f.Request | f.Pause | f.Emit) -> Any:
+        if isinstance(step, f.Request):
+            return await self._send(step)
+        if isinstance(step, f.Pause):
+            await _pause(step.seconds)
+        else:
+            result = step.callback(step.chunk)
+            if inspect.isawaitable(result):
+                await result
+        return None
+
+    async def _run(self, flow: f.Flow[T]) -> T:
+        """Drive a flow: perform what it yields, send back the answer, throw in what fails."""
+        answer: Any = None
+        error: Exception | None = None
+        try:
+            while True:
+                try:
+                    step = flow.throw(error) if error else flow.send(answer)
+                except StopIteration as done:
+                    return done.value  # type: ignore[no-any-return]
+                answer, error = None, None
+                try:
+                    answer = await self._perform(step)
+                except Exception as exc:
+                    error = exc
+                except BaseException as interrupt:  # a cancel, a timeout, an interrupt
+                    await self._unwind(flow, interrupt)
+        finally:
+            flow.close()
+
+    async def _unwind(self, flow: f.Flow[T], interrupt: BaseException) -> None:
+        """A cancel (or interrupt) reached the driver: let the flow clean up, shielded from it.
+
+        The flow gets it thrown in, may yield more steps to undo what it started (destroy a
+        sandbox, stop a command), and ends by raising it again. Each step runs as a task of its
+        own, so a second cancel does not cut the cleanup short.
+        """
+        thrown: BaseException | None = interrupt
+        answer: Any = None
+        while True:
+            try:
+                step = flow.throw(thrown) if thrown else flow.send(answer)
+            except StopIteration:
+                raise interrupt from None
+            thrown, answer = None, None
+            task = asyncio.ensure_future(self._perform(step))
+            while not task.done():
+                try:
+                    await asyncio.wait({task})
+                except asyncio.CancelledError:
+                    continue  # the first cancel is what is re-raised; this one waits too
+            if task.cancelled():
+                continue
+            if (failure := task.exception()) is not None:
+                if not isinstance(failure, Exception):
+                    raise failure
+                thrown = failure
+            else:
+                answer = task.result()
+
+
+class AsyncSandbox:
+    """One sandbox. ``id`` is all that is needed to reconnect to it with ``AsyncBriq.sandbox``."""
+
+    def __init__(self, client: AsyncBriq, info: SandboxInfo) -> None:
+        self._client = client
+        self.info = info
+
+    @property
+    def id(self) -> str:
+        return self.info.id
+
+    async def refresh(self) -> SandboxInfo:
+        """Read the sandbox's state again."""
+        self.info = await self._client._run(f.get_sandbox(self.id))
+        return self.info
+
+    async def exec(
+        self,
+        command: str | Sequence[str],
+        *,
+        cwd: str | None = None,
+        env: Mapping[str, str] | None = None,
+        stdin: str | None = None,
+        timeout: float = 60.0,
+        on_output: Callable[[OutputChunk], Any] | None = None,
+    ) -> ExecResult:
+        """Run a command and wait for it.
+
+        A string runs in a shell, a list is the program and its arguments. With ``on_output`` the
+        output reaches it as it is written, and the command may run up to 24 hours. A command that
+        outlives ``timeout`` is stopped: ``timed_out`` is true and ``exit_code`` is ``None``.
+        A command is sent once; when its end is not known the error is ``outcome_unknown``.
+        """
+        return await self._client._run(
+            f.exec_command(
+                self.id,
+                command,
+                cwd=cwd,
+                env=env,
+                stdin=stdin,
+                timeout=timeout,
+                on_output=on_output,
+            )
+        )
+
+    async def write_file(self, path: str, data: bytes, *, mode: int | None = None) -> None:
+        """Write a file, and any directory above it that is missing. ``mode`` is e.g. ``0o755``."""
+        await self._client._run(f.write_file(self.id, path, data, mode))
+
+    async def read_file(self, path: str) -> bytes:
+        """The bytes of a file. ``file_not_found`` when it is not there."""
+        return await self._client._run(f.read_file(self.id, path))
+
+    async def list_files(self, path: str) -> list[FileInfo]:
+        """The entries of a directory. Needs ``python3`` in the sandbox."""
+        return await self._client._run(f.list_files(self.id, path))
+
+    async def remove(self, path: str, *, recursive: bool = False) -> None:
+        """Remove a file, or with ``recursive`` a directory. A path that is not there is fine."""
+        await self._client._run(f.remove(self.id, path, recursive))
+
+    async def preview_url(self, port: int, *, public: bool = False) -> str:
+        """A URL for a port of the sandbox. Private: only whoever holds the URL can open it."""
+        return await self._client._run(f.preview_url(self.id, port, public))
+
+    async def stop(self) -> SandboxInfo:
+        """Stop it; the disk is kept and nothing is billed until ``start``."""
+        self.info = await self._client._run(f.stop_sandbox(self.id))
+        return self.info
+
+    async def start(self, *, wait_timeout: float = 120.0) -> SandboxInfo:
+        """Start a stopped or sleeping sandbox and wait until it runs. Any call wakes it too."""
+        self.info = await self._client._run(f.start_sandbox(self.id, wait_timeout))
+        return self.info
+
+    async def set_sleep(self, after: str) -> SandboxInfo:
+        """How long without use before it sleeps: ``"30m"``, ``"3h"``, ``"7d"`` or ``"never"``."""
+        self.info = await self._client._run(f.set_sleep(self.id, after))
+        return self.info
+
+    async def destroy(self) -> None:
+        """Destroy it and wait until it is gone. Destroying one that is gone is fine."""
+        await self._client._run(f.destroy(self.id))
+
+    async def __aenter__(self) -> AsyncSandbox:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        """Destroy it when the block ends."""
+        try:
+            await self.destroy()
+        except BriqError:
+            if exc is None:
+                raise

briq_cloud/_config.py

@@ -0,0 +1,59 @@
+"""The key and the API origin: arguments first, then the environment, then the public API."""
+
+from __future__ import annotations
+
+import os
+from urllib.parse import urlsplit
+
+import httpx
+
+from ._errors import BriqError
+from ._version import __version__
+
+DEFAULT_URL = "https://api.briq.cloud"
+USER_AGENT = f"briq-cloud-python/{__version__}"
+
+
+def resolve(api_key: str | None, base_url: str | None) -> tuple[str, str]:
+    """The key and the origin to use. A bad one fails here, before anything is sent."""
+    key = api_key or os.environ.get("BRIQ_API_KEY") or ""
+    if not key:
+        raise BriqError("auth", "A briq API key is required: pass api_key or set BRIQ_API_KEY")
+    if any(c.isspace() or ord(c) < 32 or ord(c) > 126 for c in key):
+        raise BriqError("auth", "The API key holds a character a key never has")
+    return key, origin_of(base_url or os.environ.get("BRIQ_API_URL") or DEFAULT_URL)
+
+
+def origin_of(url: str) -> str:
+    """``scheme://host[:port]`` of an API URL. It is nothing more: the client builds the paths."""
+    try:
+        parts = urlsplit(url)
+        valid = (
+            parts.scheme in ("http", "https")
+            and bool(parts.hostname)
+            and not parts.username
+            and not parts.password
+            and not parts.query
+            and not parts.fragment
+            and parts.path in ("", "/")
+            and parts.port != 0
+        )
+    except ValueError:
+        valid = False
+    if not valid:
+        raise BriqError("invalid_argument", "The API URL must be an HTTP(S) origin")
+    return f"{parts.scheme}://{parts.netloc}"
+
+
+def headers(key: str, extra: dict[str, str]) -> dict[str, str]:
+    return {
+        "authorization": f"Bearer {key}",
+        "user-agent": USER_AGENT,
+        "accept": "application/json, */*",
+        **extra,
+    }
+
+
+def timeout_of(seconds: float) -> httpx.Timeout:
+    """A deadline for each step of a request; connecting is never given more than ten seconds."""
+    return httpx.Timeout(seconds, connect=min(seconds, 10.0))

briq_cloud/_errors.py

@@ -0,0 +1,153 @@
+"""The one exception the client raises, and how an HTTP answer becomes one."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from typing import Any, Literal
+
+#: What went wrong, as a stable word. The same words as the TypeScript client's.
+#:
+#: - ``auth``: no key, a wrong key, or a key that may not do this.
+#: - ``not_found``: the sandbox does not exist (or is not yours).
+#: - ``file_not_found``: the file or directory does not exist.
+#: - ``quota``: a limit stopped it: credits, plan, spend cap, rate limit, size.
+#: - ``unavailable``: briq could not take the call; it was not applied. Safe to try again.
+#: - ``invalid_argument``: the call is wrong; trying again changes nothing.
+#: - ``provider``: briq answered with a refusal that fits none of the others.
+#: - ``outcome_unknown``: the call was sent and its result is not known (a command may have run,
+#:   a sandbox may exist). The client never repeats such a call itself.
+#: - ``timeout``: a deadline of the client ended the call.
+#: - ``unsupported``: this API or image cannot do what was asked.
+#: - ``aborted``: kept for parity with the TypeScript client, which cancels with an abort signal.
+Code = Literal[
+    "auth",
+    "not_found",
+    "file_not_found",
+    "quota",
+    "unavailable",
+    "invalid_argument",
+    "provider",
+    "outcome_unknown",
+    "timeout",
+    "unsupported",
+    "aborted",
+]
+
+
+class BriqError(Exception):
+    """A call to briq failed. ``code`` says how; the other fields say what briq answered."""
+
+    def __init__(
+        self,
+        code: Code,
+        message: str,
+        *,
+        status: int | None = None,
+        api_code: str | None = None,
+        request_id: str | None = None,
+        retry_after: int | None = None,
+        details: Any = None,
+        idempotency_key: str | None = None,
+        sandbox_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code: Code = code
+        self.message = message
+        #: The HTTP status, when briq answered.
+        self.status = status
+        #: The API's own error code (``payment_required``, ``plan_limit``, ``invalid_state``...).
+        self.api_code = api_code
+        #: The API's id for the failed request: quote it when asking for help.
+        self.request_id = request_id
+        #: On a rate limit (429): the seconds until the window ends.
+        self.retry_after = retry_after
+        #: What the API said about the limit or the operation, as codes, ids and numbers only
+        #: (``{"limit": "size", "plan": "hobby"}``, ``{"op": "exec"}``). The text a provider
+        #: gave is never kept: it is not for a caller's logs.
+        self.details = details
+        #: On a create whose result is not known: the key it was sent with. Pass it as
+        #: ``idempotency_key`` to repeat the call; the API then returns the sandbox it made.
+        self.idempotency_key = idempotency_key
+        #: The sandbox the error is about, when it is known (a create that could not clean up).
+        self.sandbox_id = sandbox_id
+
+    def __str__(self) -> str:
+        return f"{self.message} ({self.code})"
+
+
+def status_code(status: int, api_code: str | None = None) -> Code:
+    """The code for an HTTP status, as the TypeScript client maps it."""
+    if status in (402, 429, 507, 413) or api_code == "plan_limit":
+        return "quota"
+    if status in (401, 403):
+        return "auth"
+    if status == 404:
+        return "not_found"
+    if status >= 500:
+        return "unavailable"
+    if status in (400, 422):
+        return "invalid_argument"
+    return "provider"
+
+
+_ID = re.compile(r"^[\w.-]{1,64}$")
+#: A value of ``details`` worth keeping: a code, an id, a plan or an operation name.
+_WORD = re.compile(r"^[\w.:-]{1,64}$")
+
+
+def request_id_of(value: object) -> str | None:
+    """A request id worth repeating in an error: the API's own, shaped as ours."""
+    return value if isinstance(value, str) and _ID.match(value) else None
+
+
+def safe_details(details: Any) -> Any:
+    """The codes, ids and numbers of an error's ``details``; the text of a provider is dropped."""
+    if not isinstance(details, dict):
+        return None
+    kept = {
+        key: value
+        for key, value in details.items()
+        if isinstance(key, str)
+        and _WORD.match(key)
+        and key != "providerSaid"
+        and (
+            isinstance(value, (bool, int, float))
+            or (isinstance(value, str) and _WORD.match(value) is not None)
+        )
+    }
+    return kept or None
+
+
+def envelope(content: bytes) -> dict[str, Any]:
+    """The ``error`` object of an error answer; empty when the body is not ours (a proxy's page)."""
+    try:
+        error = json.loads(content).get("error")
+    except (ValueError, AttributeError):
+        return {}
+    return error if isinstance(error, dict) else {}
+
+
+def refusal(
+    status: int,
+    headers: Mapping[str, str],
+    content: bytes,
+    code: Code | None = None,
+) -> BriqError:
+    """An error answer as a ``BriqError``: ``code`` by status unless the caller knows better."""
+    error = envelope(content)
+    said_code, said = error.get("code"), error.get("message")
+    api_code = said_code if isinstance(said_code, str) else None
+    message = said if isinstance(said, str) else f"HTTP {status}"
+    retry = headers.get("retry-after", "")
+    return BriqError(
+        code or status_code(status, api_code),
+        message,
+        status=status,
+        api_code=api_code,
+        request_id=request_id_of(headers.get("x-request-id"))
+        or request_id_of(error.get("requestId")),
+        retry_after=int(retry) if status == 429 and re.fullmatch(r"\d{1,4}", retry) else None,
+        details=safe_details(error.get("details")),
+    )