boxd 0.1.0.dev2__py3-none-any.whl

boxd/client.py

@@ -0,0 +1,141 @@
+"""Compute — main entry point for the boxd SDK."""
+
+from __future__ import annotations
+
+import os
+
+import grpc
+import grpc.aio
+
+from ._generated import api_pb2, api_pb2_grpc
+from ._utils import resolve_endpoint
+from .auth import TokenAuth
+from .boxes import BoxService
+from .disks import DiskService
+from .domains import DomainService
+from .errors import AuthenticationError, from_grpc_error
+from .networks import NetworkService
+from .templates import TemplateService
+from .tokens import TokenService
+from .types import ConfigResult, WhoamiResult
+
+_DEFAULT_API_URL = "http://boxd.sh:9443"
+_DEFAULT_EXCHANGE_URL = "https://boxd.sh/api/v1/auth/token"
+
+
+class Compute:
+    """Main client for the boxd API.
+
+    Usage::
+
+        async with Compute(api_key="bxk_...") as c:
+            box = await c.box.create("my-vm")
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        token: str | None = None,
+        api_url: str | None = None,
+        exchange_url: str | None = None,
+    ) -> None:
+        self._api_url = (
+            api_url
+            or os.environ.get("BOXD_API_URL")
+            or _DEFAULT_API_URL
+        )
+        self._exchange_url = (
+            exchange_url
+            or os.environ.get("BOXD_EXCHANGE_URL")
+            or _DEFAULT_EXCHANGE_URL
+        )
+
+        resolved_key = api_key or os.environ.get("BOXD_API_KEY")
+        resolved_token = token or os.environ.get("BOXD_TOKEN")
+
+        if not resolved_key and not resolved_token:
+            raise AuthenticationError(
+                "provide api_key, token, or set BOXD_API_KEY / BOXD_TOKEN"
+            )
+
+        self._auth = TokenAuth(
+            api_key=resolved_key,
+            token=resolved_token,
+            exchange_url=self._exchange_url,
+        )
+
+        self._channel: grpc.aio.Channel | None = None
+        self._stub: api_pb2_grpc.BoxdApiStub | None = None
+
+        # Sub-services
+        self.box = BoxService(self)
+        self.template = TemplateService(self)
+        self.disk = DiskService(self)
+        self.domain = DomainService(self)
+        self.network = NetworkService(self)
+        self.token = TokenService(self)
+
+    async def _ensure_channel(self) -> api_pb2_grpc.BoxdApiStub:
+        """Lazily create the gRPC channel and return the stub."""
+        if self._stub is not None:
+            return self._stub
+
+        interceptor = self._auth.interceptor()
+        endpoint = resolve_endpoint(self._api_url)
+
+        if endpoint.use_tls:
+            creds = grpc.ssl_channel_credentials()
+            channel = grpc.aio.secure_channel(
+                endpoint.host,
+                creds,
+                interceptors=[interceptor],
+            )
+        else:
+            channel = grpc.aio.insecure_channel(
+                endpoint.host,
+                interceptors=[interceptor],
+            )
+
+        self._channel = channel
+        self._stub = api_pb2_grpc.BoxdApiStub(channel)
+        return self._stub
+
+    async def _call(self, method_name: str, request):
+        """Call a gRPC method on the stub, converting errors."""
+        stub = await self._ensure_channel()
+        method = getattr(stub, method_name)
+        try:
+            return await method(request)
+        except grpc.aio.AioRpcError as e:
+            raise from_grpc_error(e) from e
+
+    async def whoami(self) -> WhoamiResult:
+        """Return information about the authenticated user."""
+        resp = await self._call("Whoami", api_pb2.WhoamiRequest())
+        return WhoamiResult(
+            user_id=resp.user_id,
+            fingerprints=list(resp.pubkey_fingerprints),
+            default_network_id=resp.default_network_id,
+        )
+
+    async def config(self) -> ConfigResult:
+        """Return server configuration."""
+        resp = await self._call("GetConfig", api_pb2.GetConfigRequest())
+        return ConfigResult(
+            default_image=resp.default_image,
+            zone=resp.zone,
+        )
+
+    async def close(self) -> None:
+        """Close the gRPC channel."""
+        if self._channel is not None:
+            await self._channel.close()
+            self._channel = None
+            self._stub = None
+
+    async def __aenter__(self) -> Compute:
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.close()

boxd/disks.py

@@ -0,0 +1,111 @@
+"""DiskService — create and list persistent disks; DiskHandle — attach, detach, destroy."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from ._generated import api_pb2
+from ._utils import GrpcCaller, parse_size
+
+if TYPE_CHECKING:
+    from .box import Box
+    from .client import Compute
+
+
+def _resolve_vm_id(box: Box | str) -> str:
+    """Extract a VM ID from a Box object or string."""
+    return box if isinstance(box, str) else box.id
+
+
+@dataclass
+class DiskHandle(GrpcCaller):
+    """A handle to a persistent disk with attach/detach/destroy operations."""
+
+    id: str
+    name: str
+    size_bytes: int
+    status: str
+    _client: Compute = field(repr=False)
+
+    async def attach(
+        self,
+        box: Box | str,
+        mount_path: str,
+        read_only: bool = False,
+    ) -> None:
+        """Attach this disk to a VM.
+
+        Args:
+            box: A Box object or VM ID string.
+            mount_path: Path at which to mount the disk inside the VM.
+            read_only: Whether to mount the disk read-only.
+        """
+        await self._call(
+            "AttachDisk",
+            api_pb2.AttachDiskRequest(
+                disk_id=self.id,
+                vm_id=_resolve_vm_id(box),
+                mount_path=mount_path,
+                read_only=read_only,
+            ),
+        )
+
+    async def detach(self, box: Box | str) -> None:
+        """Detach this disk from a VM.
+
+        Args:
+            box: A Box object or VM ID string.
+        """
+        await self._call(
+            "DetachDisk",
+            api_pb2.DetachDiskRequest(disk_id=self.id, vm_id=_resolve_vm_id(box)),
+        )
+
+    async def destroy(self) -> None:
+        """Permanently destroy this disk."""
+        await self._call("DestroyDisk", api_pb2.DestroyDiskRequest(disk_id=self.id))
+        self.status = "destroyed"
+
+
+class DiskService(GrpcCaller):
+    """Manage persistent disks."""
+
+    def __init__(self, client: Compute) -> None:
+        self._client = client
+
+    async def create(self, name: str, size: str) -> DiskHandle:
+        """Create a new persistent disk.
+
+        Args:
+            name: Disk name.
+            size: Human-readable size string, e.g. ``"10G"`` or ``"512M"``.
+
+        Returns:
+            A DiskHandle for the created disk.
+        """
+        resp = await self._call(
+            "CreateDisk",
+            api_pb2.CreateDiskRequest(name=name, size_bytes=parse_size(size)),
+        )
+        return DiskHandle(
+            id=resp.disk_id,
+            name=resp.name,
+            size_bytes=resp.size_bytes,
+            status=resp.status,
+            _client=self._client,
+        )
+
+    async def list(self) -> list[DiskHandle]:
+        """List all disks."""
+        resp = await self._call("ListDisks", api_pb2.ListDisksRequest())
+        return [
+            DiskHandle(
+                id=d.disk_id,
+                name=d.name,
+                size_bytes=d.size_bytes,
+                status=d.status,
+                _client=self._client,
+            )
+            for d in resp.disks
+        ]

boxd/domains.py

@@ -0,0 +1,54 @@
+"""DomainService — bind, unbind, and list external domains."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ._generated import api_pb2
+from ._utils import GrpcCaller
+from .types import Domain
+
+if TYPE_CHECKING:
+    from .box import Box
+    from .client import Compute
+
+
+class DomainService(GrpcCaller):
+    """Manage external domains bound to VMs."""
+
+    def __init__(self, client: Compute) -> None:
+        self._client = client
+
+    async def bind(self, domain: str, vm: Box | str) -> None:
+        """Bind an external domain to a VM.
+
+        Args:
+            domain: The external domain name (e.g. ``"app.example.com"``).
+            vm: A Box object, VM name, or VM ID.
+
+        The domain's DNS must already point to the boxd proxy. This call only
+        configures the proxy to route traffic for ``domain`` to the given VM.
+        """
+        # Resolve Box/name/id to VM ID
+        if hasattr(vm, "id"):
+            vm_id = vm.id
+        else:
+            resolved = await self._client.box.get(vm)
+            vm_id = resolved.id
+
+        await self._call(
+            "BindDomain",
+            api_pb2.BindDomainRequest(domain=domain, vm_id=vm_id),
+        )
+
+    async def unbind(self, domain: str) -> None:
+        """Remove the binding for an external domain."""
+        await self._call(
+            "UnbindDomain",
+            api_pb2.UnbindDomainRequest(domain=domain),
+        )
+
+    async def list(self) -> list[Domain]:
+        """List all external domains bound to this user's VMs."""
+        resp = await self._call("ListDomains", api_pb2.ListDomainsRequest())
+        return [Domain(domain=d.domain, vm_id=d.vm_id) for d in resp.domains]

boxd/errors.py

@@ -0,0 +1,62 @@
+"""Exception hierarchy for the boxd SDK."""
+
+from __future__ import annotations
+
+import grpc
+
+
+class BoxdError(Exception):
+    """Base exception for all boxd SDK errors."""
+
+    def __init__(self, message: str, grpc_code: int | None = None):
+        super().__init__(message)
+        self.message = message
+        self.grpc_code = grpc_code
+
+
+class AuthenticationError(BoxdError):
+    """API key invalid, expired, or revoked."""
+
+
+class NotFoundError(BoxdError):
+    """Resource not found."""
+
+
+class QuotaExceededError(BoxdError):
+    """Resource limit reached."""
+
+
+class InvalidArgumentError(BoxdError):
+    """Invalid request parameters."""
+
+
+class InternalError(BoxdError):
+    """Server-side error."""
+
+
+class TimeoutError(BoxdError):
+    """Operation timed out."""
+
+
+class ConnectionError(BoxdError):
+    """Failed to connect to boxd API."""
+
+
+_STATUS_MAP = {
+    grpc.StatusCode.UNAUTHENTICATED: AuthenticationError,
+    grpc.StatusCode.PERMISSION_DENIED: AuthenticationError,
+    grpc.StatusCode.NOT_FOUND: NotFoundError,
+    grpc.StatusCode.ALREADY_EXISTS: InvalidArgumentError,
+    grpc.StatusCode.RESOURCE_EXHAUSTED: QuotaExceededError,
+    grpc.StatusCode.INVALID_ARGUMENT: InvalidArgumentError,
+    grpc.StatusCode.INTERNAL: InternalError,
+    grpc.StatusCode.UNKNOWN: InternalError,
+    grpc.StatusCode.DEADLINE_EXCEEDED: TimeoutError,
+    grpc.StatusCode.UNAVAILABLE: ConnectionError,
+}
+
+
+def from_grpc_error(err: grpc.aio.AioRpcError) -> BoxdError:
+    """Convert a gRPC error to the appropriate BoxdError subclass."""
+    cls = _STATUS_MAP.get(err.code(), BoxdError)
+    return cls(err.details() or str(err), grpc_code=err.code().value[0])

boxd/exec.py

@@ -0,0 +1,122 @@
+"""Exec primitives: result, stream readers/writers, and process handle."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ExecResult:
+    """Result of a non-streaming exec call."""
+
+    stdout: str
+    stderr: str
+    exit_code: int
+
+    @property
+    def success(self) -> bool:
+        return self.exit_code == 0
+
+
+class StreamReader:
+    """Async reader that buffers chunks from an exec stream."""
+
+    def __init__(self) -> None:
+        self._queue: asyncio.Queue[bytes | None] = asyncio.Queue()
+        self._eof = False
+
+    async def read(self) -> bytes:
+        """Read the next chunk, or return empty bytes on EOF."""
+        if self._eof:
+            return b""
+        chunk = await self._queue.get()
+        if chunk is None:
+            self._eof = True
+            return b""
+        return chunk
+
+    def _feed(self, data: bytes) -> None:
+        self._queue.put_nowait(data)
+
+    def _feed_eof(self) -> None:
+        self._queue.put_nowait(None)
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self) -> bytes:
+        chunk = await self.read()
+        if not chunk and self._eof:
+            raise StopAsyncIteration
+        return chunk
+
+
+class StreamWriter:
+    """Async writer that queues stdin chunks for an exec stream."""
+
+    def __init__(self) -> None:
+        self._queue: asyncio.Queue[bytes | None] = asyncio.Queue()
+        self._closed = False
+
+    def write(self, data: bytes | str) -> None:
+        """Queue data to be sent to stdin."""
+        if self._closed:
+            raise RuntimeError("writer is closed")
+        if isinstance(data, str):
+            data = data.encode("utf-8")
+        self._queue.put_nowait(data)
+
+    def write_eof(self) -> None:
+        """Signal end of stdin."""
+        if not self._closed:
+            self._closed = True
+            self._queue.put_nowait(None)
+
+    async def drain(self) -> None:
+        """Wait until the queue is empty."""
+        await self._queue.join()
+
+    async def _get(self) -> bytes | None:
+        return await self._queue.get()
+
+    def _task_done(self) -> None:
+        self._queue.task_done()
+
+
+@dataclass
+class ExecProcess:
+    """Handle to a streaming exec process."""
+
+    stdout: StreamReader
+    stderr: StreamReader
+    stdin: StreamWriter
+    _exit_code: int | None = field(default=None, repr=False)
+    _error: BaseException | None = field(default=None, repr=False)
+    _done: asyncio.Event = field(default_factory=asyncio.Event, repr=False)
+    _relay_task: asyncio.Task | None = field(default=None, repr=False)
+
+    async def wait(self) -> int:
+        """Wait for the process to exit and return the exit code.
+
+        Raises the original exception if the exec stream failed.
+        """
+        await self._done.wait()
+        if self._error is not None:
+            raise self._error
+        return self._exit_code if self._exit_code is not None else -1
+
+    def close(self) -> None:
+        """Cancel the relay task and close stdin."""
+        self.stdin.write_eof()
+        if self._relay_task and not self._relay_task.done():
+            self._relay_task.cancel()
+
+    def _set_exit_code(self, code: int) -> None:
+        self._exit_code = code
+        self._done.set()
+
+    def _set_error(self, error: BaseException) -> None:
+        self._error = error
+        self._exit_code = -1
+        self._done.set()

boxd/networks.py

@@ -0,0 +1,43 @@
+"""NetworkService — create and list user networks."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ._generated import api_pb2
+from ._utils import GrpcCaller
+from .types import Network
+
+if TYPE_CHECKING:
+    from .client import Compute
+
+
+class NetworkService(GrpcCaller):
+    """Manage user networks."""
+
+    def __init__(self, client: Compute) -> None:
+        self._client = client
+
+    async def create(self, name: str = "") -> Network:
+        """Create a new network.
+
+        Args:
+            name: Optional network name.
+
+        Returns:
+            A Network with only ``id`` populated. Call :meth:`list` to get
+            subnet and status.
+        """
+        resp = await self._call(
+            "CreateNetwork",
+            api_pb2.CreateNetworkRequest(name=name),
+        )
+        return Network(id=resp.network_id, subnet="", status="")
+
+    async def list(self) -> list[Network]:
+        """List all of this user's networks."""
+        resp = await self._call("ListNetworks", api_pb2.ListNetworksRequest())
+        return [
+            Network(id=n.network_id, subnet=n.subnet, status=n.status)
+            for n in resp.networks
+        ]

boxd/templates.py

@@ -0,0 +1,113 @@
+"""TemplateService — create, list, delete, and instantiate VM templates."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ._generated import api_pb2
+from ._utils import GrpcCaller, parse_size
+from .types import BoxConfig, Template
+
+if TYPE_CHECKING:
+    from .box import Box
+    from .client import Compute
+
+
+def _template_info_to_template(info) -> Template:
+    """Convert a TemplateInfo proto to a Template dataclass."""
+    return Template(
+        id=info.template_id,
+        name=info.name,
+        image=info.image_ref,
+        status=info.status,
+        vcpu=info.vcpu,
+        memory_bytes=info.memory_bytes,
+    )
+
+
+class TemplateService(GrpcCaller):
+    """Manage VM templates."""
+
+    def __init__(self, client: Compute) -> None:
+        self._client = client
+
+    async def create(
+        self,
+        name: str,
+        image: str = "",
+        config: BoxConfig | None = None,
+    ) -> Template:
+        """Create a new VM template.
+
+        Args:
+            name: Template name.
+            image: Base image reference.
+            config: Optional VM configuration.
+
+        Returns:
+            The created Template.
+        """
+        from .boxes import _box_config_to_proto
+
+        req = api_pb2.CreateTemplateRequest(name=name)
+        if image:
+            req.image_ref = image
+        if config is not None:
+            proto_config = _box_config_to_proto(config)
+            if proto_config is not None:
+                req.config.CopyFrom(proto_config)
+
+        resp = await self._call("CreateTemplate", req)
+        return Template(
+            id=resp.template_id,
+            name=resp.name,
+            image=image,
+            status=resp.status,
+            vcpu=config.vcpu if config else 0,
+            memory_bytes=parse_size(config.memory) if config and config.memory else 0,
+        )
+
+    async def list(self) -> list[Template]:
+        """List all templates."""
+        resp = await self._call("ListTemplates", api_pb2.ListTemplatesRequest())
+        return [_template_info_to_template(t) for t in resp.templates]
+
+    async def delete(self, template_id: str) -> None:
+        """Delete a template by ID."""
+        await self._call(
+            "DeleteTemplate",
+            api_pb2.DeleteTemplateRequest(template_id=template_id),
+        )
+
+    async def create_vm(
+        self,
+        template: Template | str,
+        name: str = "",
+        config: BoxConfig | None = None,
+    ) -> Box:
+        """Create a VM from a template.
+
+        Args:
+            template: A Template object or template ID string.
+            name: Optional name for the new VM.
+            config: Optional VM configuration overrides.
+
+        Returns:
+            The newly created Box.
+        """
+        from .boxes import _box_config_to_proto
+
+        template_id = template.id if isinstance(template, Template) else template
+
+        req = api_pb2.CreateVmFromTemplateRequest(template_id=template_id)
+        if name:
+            req.name = name
+        if config is not None:
+            proto_config = _box_config_to_proto(config)
+            if proto_config is not None:
+                req.config.CopyFrom(proto_config)
+
+        resp = await self._call("CreateVmFromTemplate", req)
+        from .boxes import _vm_response_to_box
+
+        return _vm_response_to_box(resp, self._client, has_url=True)

boxd/tokens.py

@@ -0,0 +1,51 @@
+"""TokenService — create, list, and revoke scoped JWT tokens."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ._generated import api_pb2
+from ._utils import GrpcCaller
+from .types import Token, TokenInfo
+
+if TYPE_CHECKING:
+    from .client import Compute
+
+
+class TokenService(GrpcCaller):
+    """Manage scoped JWT tokens for delegated access."""
+
+    def __init__(self, client: Compute) -> None:
+        self._client = client
+
+    async def create(self, expires_in: int = 0) -> Token:
+        """Create a new scoped JWT token for the current user.
+
+        Args:
+            expires_in: TTL in seconds. 0 means server default (24h).
+
+        Returns:
+            A :class:`Token` with the raw JWT string. Save it — the raw token
+            cannot be retrieved later via :meth:`list`.
+        """
+        resp = await self._call(
+            "CreateToken",
+            api_pb2.CreateTokenRequest(expires_in_secs=expires_in),
+        )
+        return Token(token=resp.token, expires_at=resp.expires_at)
+
+    async def list(self) -> list[TokenInfo]:
+        """List metadata about previously-issued tokens (no raw token strings)."""
+        resp = await self._call("ListTokens", api_pb2.ListTokensRequest())
+        return [
+            TokenInfo(
+                jti=t.jti,
+                created_at=t.created_at,
+                expires_at=t.expires_at,
+            )
+            for t in resp.tokens
+        ]
+
+    async def revoke(self, jti: str) -> None:
+        """Revoke a token by its JTI (JWT ID)."""
+        await self._call("RevokeToken", api_pb2.RevokeTokenRequest(jti=jti))