boxd 0.1.0.dev2__py3-none-any.whl

boxd/_sync.py

@@ -0,0 +1,448 @@
+"""Synchronous wrappers for the boxd async API.
+
+These thin wrappers run the async methods on a dedicated event loop,
+providing a blocking API that doesn't require async/await.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from .exec import ExecResult
+from .types import (
+    BoxConfig,
+    ConfigResult,
+    Domain,
+    Network,
+    Proxy,
+    ResumeResult,
+    SuspendResult,
+    Template,
+    Token,
+    TokenInfo,
+    WhoamiResult,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class _SyncBase:
+    """Mixin that holds a reference to a shared event loop."""
+
+    _loop: asyncio.AbstractEventLoop
+
+    def _run(self, coro):
+        return self._loop.run_until_complete(coro)
+
+
+class Box(_SyncBase):
+    """A boxd VM (synchronous API).
+
+    Data attributes (id, name, image, public_ip, status, url, boot_time_ms)
+    are forwarded automatically from the underlying async Box.
+    """
+
+    def __init__(self, async_box, loop: asyncio.AbstractEventLoop) -> None:
+        from .box import Box as AsyncBox
+
+        self._async: AsyncBox = async_box
+        self._loop = loop
+
+    def __getattr__(self, name: str):
+        # Forward data attributes from the async Box dataclass
+        if name in ("id", "name", "image", "public_ip", "status", "url", "boot_time_ms"):
+            return getattr(self._async, name)
+        raise AttributeError(f"{type(self).__name__!r} object has no attribute {name!r}")
+
+    def __repr__(self) -> str:
+        return (
+            f"Box(id={self.id!r}, name={self.name!r}, image={self.image!r}, "
+            f"public_ip={self.public_ip!r}, status={self.status!r})"
+        )
+
+    # ── Lifecycle ────────────────────────────────────────────────
+
+    def destroy(self) -> None:
+        """Destroy this VM."""
+        self._run(self._async.destroy())
+
+    def reboot(self) -> None:
+        """Reboot this VM."""
+        self._run(self._async.reboot())
+
+    def start(self) -> None:
+        """Start this VM."""
+        self._run(self._async.start())
+
+    def stop(self) -> None:
+        """Stop this VM."""
+        self._run(self._async.stop())
+
+    def suspend(self) -> SuspendResult:
+        """Suspend this VM."""
+        return self._run(self._async.suspend())
+
+    def resume(self) -> ResumeResult:
+        """Resume this VM from suspension."""
+        return self._run(self._async.resume())
+
+    # ── Exec ─────────────────────────────────────────────────────
+
+    def exec(
+        self,
+        *args: str,
+        stream: bool = False,
+        interactive: bool = False,
+        pty: bool = False,
+        text: bool = True,
+        timeout: float | None = None,
+        env: dict[str, str] | None = None,
+    ) -> ExecResult | SyncExecProcess:
+        """Execute a command in this VM."""
+        result = self._run(
+            self._async.exec(
+                *args,
+                stream=stream,
+                interactive=interactive,
+                pty=pty,
+                text=text,
+                timeout=timeout,
+                env=env,
+            )
+        )
+        if isinstance(result, ExecResult):
+            return result
+        return SyncExecProcess(result, self._loop)
+
+    # ── Files ────────────────────────────────────────────────────
+
+    def write_file(self, source: str | bytes | Path, dest: str) -> None:
+        """Write a file to the VM."""
+        self._run(self._async.write_file(source, dest))
+
+    def read_file(self, path: str) -> bytes:
+        """Download a file from the VM."""
+        return self._run(self._async.read_file(path))
+
+    # ── Proxies ──────────────────────────────────────────────────
+
+    def proxies(self) -> list[Proxy]:
+        """List proxies for this VM."""
+        return self._run(self._async.proxies())
+
+    def create_proxy(self, name: str, port: int = 0) -> Proxy:
+        """Create a new proxy subdomain for this VM."""
+        return self._run(self._async.create_proxy(name, port))
+
+    def delete_proxy(self, name: str) -> None:
+        """Delete a proxy subdomain."""
+        self._run(self._async.delete_proxy(name))
+
+    def set_proxy_port(self, port: int, name: str = "") -> None:
+        """Change the port for a proxy."""
+        self._run(self._async.set_proxy_port(port, name))
+
+    # ── Logs ─────────────────────────────────────────────────────
+
+    def stream_logs(self, follow: bool = False):
+        """Stream console log chunks from the VM.
+
+        Args:
+            follow: If True, keep the stream open for new chunks.
+
+        Yields:
+            ``bytes`` chunks of raw log data.
+        """
+        agen = self._async.stream_logs(follow=follow)
+        while True:
+            try:
+                yield self._run(agen.__anext__())
+            except StopAsyncIteration:
+                return
+
+
+class SyncExecProcess(_SyncBase):
+    """Synchronous handle to a streaming exec process."""
+
+    def __init__(self, async_process, loop: asyncio.AbstractEventLoop) -> None:
+        from .exec import ExecProcess as AsyncExecProcess
+
+        self._async: AsyncExecProcess = async_process
+        self._loop = loop
+
+    def wait(self) -> int:
+        """Wait for the process to exit and return the exit code."""
+        return self._run(self._async.wait())
+
+    def close(self) -> None:
+        """Cancel the relay task and close stdin."""
+        self._async.close()
+
+    @property
+    def stdin(self):
+        """Access the stdin writer (write/write_eof are sync)."""
+        return self._async.stdin
+
+    def read_stdout(self) -> bytes:
+        """Read the next stdout chunk, or empty bytes on EOF."""
+        return self._run(self._async.stdout.read())
+
+    def iter_stdout(self):
+        """Iterate over stdout chunks until EOF."""
+        while True:
+            chunk = self.read_stdout()
+            if not chunk:
+                break
+            yield chunk
+
+
+class BoxService(_SyncBase):
+    """Create, list, get, and fork VMs (synchronous API)."""
+
+    def __init__(self, async_service, loop: asyncio.AbstractEventLoop) -> None:
+        from .boxes import BoxService as AsyncBoxService
+
+        self._async: AsyncBoxService = async_service
+        self._loop = loop
+
+    def _wrap(self, async_box) -> Box:
+        return Box(async_box, self._loop)
+
+    def create(
+        self,
+        name: str = "",
+        image: str = "",
+        config: BoxConfig | None = None,
+    ) -> Box:
+        """Create a new VM."""
+        return self._wrap(self._run(self._async.create(name, image, config)))
+
+    def list(self) -> list[Box]:
+        """List all VMs."""
+        return [self._wrap(b) for b in self._run(self._async.list())]
+
+    def get(self, vm_id: str) -> Box:
+        """Get a VM by ID or name."""
+        return self._wrap(self._run(self._async.get(vm_id)))
+
+    def fork(
+        self,
+        source: str,
+        name: str | None = None,
+        config: BoxConfig | None = None,
+    ) -> Box:
+        """Fork (clone) a VM."""
+        return self._wrap(self._run(self._async.fork(source, name, config)))
+
+
+class TemplateService(_SyncBase):
+    """Manage VM templates (synchronous API)."""
+
+    def __init__(self, async_service, loop: asyncio.AbstractEventLoop) -> None:
+        from .templates import TemplateService as AsyncTemplateService
+
+        self._async: AsyncTemplateService = async_service
+        self._loop = loop
+
+    def create(
+        self,
+        name: str,
+        image: str = "",
+        config: BoxConfig | None = None,
+    ) -> Template:
+        """Create a new VM template."""
+        return self._run(self._async.create(name, image, config))
+
+    def list(self) -> list[Template]:
+        """List all templates."""
+        return self._run(self._async.list())
+
+    def delete(self, template_id: str) -> None:
+        """Delete a template by ID."""
+        self._run(self._async.delete(template_id))
+
+    def create_vm(
+        self,
+        template: Template | str,
+        name: str = "",
+        config: BoxConfig | None = None,
+    ) -> Box:
+        """Create a VM from a template."""
+        return Box(self._run(self._async.create_vm(template, name, config)), self._loop)
+
+
+class DiskHandle(_SyncBase):
+    """A handle to a persistent disk (synchronous API).
+
+    Data attributes (id, name, size_bytes, status) are forwarded
+    automatically from the underlying async DiskHandle.
+    """
+
+    def __init__(self, async_handle, loop: asyncio.AbstractEventLoop) -> None:
+        from .disks import DiskHandle as AsyncDiskHandle
+
+        self._async: AsyncDiskHandle = async_handle
+        self._loop = loop
+
+    def __getattr__(self, name: str):
+        if name in ("id", "name", "size_bytes", "status"):
+            return getattr(self._async, name)
+        raise AttributeError(f"{type(self).__name__!r} object has no attribute {name!r}")
+
+    def __repr__(self) -> str:
+        return (
+            f"DiskHandle(id={self.id!r}, name={self.name!r}, "
+            f"size_bytes={self.size_bytes}, status={self.status!r})"
+        )
+
+    def attach(self, box: Box | str, mount_path: str, read_only: bool = False) -> None:
+        """Attach this disk to a VM."""
+        target = box._async if isinstance(box, Box) else box
+        self._run(self._async.attach(target, mount_path, read_only))
+
+    def detach(self, box: Box | str) -> None:
+        """Detach this disk from a VM."""
+        target = box._async if isinstance(box, Box) else box
+        self._run(self._async.detach(target))
+
+    def destroy(self) -> None:
+        """Permanently destroy this disk."""
+        self._run(self._async.destroy())
+
+
+class DiskService(_SyncBase):
+    """Manage persistent disks (synchronous API)."""
+
+    def __init__(self, async_service, loop: asyncio.AbstractEventLoop) -> None:
+        from .disks import DiskService as AsyncDiskService
+
+        self._async: AsyncDiskService = async_service
+        self._loop = loop
+
+    def create(self, name: str, size: str) -> DiskHandle:
+        """Create a new persistent disk."""
+        return DiskHandle(self._run(self._async.create(name, size)), self._loop)
+
+    def list(self) -> list[DiskHandle]:
+        """List all disks."""
+        return [DiskHandle(h, self._loop) for h in self._run(self._async.list())]
+
+
+class DomainService(_SyncBase):
+    """Manage external domains bound to VMs (synchronous API)."""
+
+    def __init__(self, async_service, loop: asyncio.AbstractEventLoop) -> None:
+        from .domains import DomainService as AsyncDomainService
+
+        self._async: AsyncDomainService = async_service
+        self._loop = loop
+
+    def bind(self, domain: str, vm: Box | str) -> None:
+        """Bind an external domain to a VM."""
+        target = vm._async if isinstance(vm, Box) else vm
+        self._run(self._async.bind(domain, target))
+
+    def unbind(self, domain: str) -> None:
+        """Remove the binding for an external domain."""
+        self._run(self._async.unbind(domain))
+
+    def list(self) -> list[Domain]:
+        """List bound domains."""
+        return self._run(self._async.list())
+
+
+class NetworkService(_SyncBase):
+    """Manage user networks (synchronous API)."""
+
+    def __init__(self, async_service, loop: asyncio.AbstractEventLoop) -> None:
+        from .networks import NetworkService as AsyncNetworkService
+
+        self._async: AsyncNetworkService = async_service
+        self._loop = loop
+
+    def create(self, name: str = "") -> Network:
+        """Create a new network."""
+        return self._run(self._async.create(name))
+
+    def list(self) -> list[Network]:
+        """List networks."""
+        return self._run(self._async.list())
+
+
+class TokenService(_SyncBase):
+    """Manage scoped JWT tokens (synchronous API)."""
+
+    def __init__(self, async_service, loop: asyncio.AbstractEventLoop) -> None:
+        from .tokens import TokenService as AsyncTokenService
+
+        self._async: AsyncTokenService = async_service
+        self._loop = loop
+
+    def create(self, expires_in: int = 0) -> Token:
+        """Create a scoped JWT."""
+        return self._run(self._async.create(expires_in))
+
+    def list(self) -> list[TokenInfo]:
+        """List token metadata."""
+        return self._run(self._async.list())
+
+    def revoke(self, jti: str) -> None:
+        """Revoke a token by JTI."""
+        self._run(self._async.revoke(jti))
+
+
+class Compute(_SyncBase):
+    """Main client for the boxd API (synchronous API).
+
+    Usage::
+
+        with Compute(api_key="bxk_...") as c:
+            box = c.box.create("my-vm")
+            result = box.exec("echo", "hello")
+            print(result.stdout)
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        token: str | None = None,
+        api_url: str | None = None,
+        exchange_url: str | None = None,
+    ) -> None:
+        from .client import Compute as AsyncCompute
+
+        self._loop = asyncio.new_event_loop()
+        self._async = AsyncCompute(
+            api_key=api_key,
+            token=token,
+            api_url=api_url,
+            exchange_url=exchange_url,
+        )
+        self.box = BoxService(self._async.box, self._loop)
+        self.template = TemplateService(self._async.template, self._loop)
+        self.disk = DiskService(self._async.disk, self._loop)
+        self.domain = DomainService(self._async.domain, self._loop)
+        self.network = NetworkService(self._async.network, self._loop)
+        self.token = TokenService(self._async.token, self._loop)
+
+    def whoami(self) -> WhoamiResult:
+        """Return information about the authenticated user."""
+        return self._run(self._async.whoami())
+
+    def config(self) -> ConfigResult:
+        """Return server configuration."""
+        return self._run(self._async.config())
+
+    def close(self) -> None:
+        """Close the gRPC channel and event loop."""
+        self._run(self._async.close())
+        self._loop.close()
+
+    def __enter__(self) -> Compute:
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()

boxd/_utils.py

@@ -0,0 +1,73 @@
+"""Internal helpers."""
+
+from __future__ import annotations
+
+import re
+from typing import NamedTuple, TYPE_CHECKING
+
+import grpc.aio
+
+from .errors import from_grpc_error
+
+if TYPE_CHECKING:
+    from .client import Compute
+
+
+class Endpoint(NamedTuple):
+    """Resolved gRPC endpoint: bare ``host:port`` and whether to use TLS."""
+
+    host: str
+    use_tls: bool
+
+
+def resolve_endpoint(url: str) -> Endpoint:
+    """Resolve an api_url into a ``(host, use_tls)`` pair.
+
+    - ``http://...``  → plaintext, scheme stripped
+    - ``https://...`` → TLS, scheme stripped
+    - bare ``host:port`` → TLS, except ``localhost``/``127.*`` which stay plaintext
+
+    Production gRPC currently lives at ``boxd.sh:9443`` over plain HTTP/2, so the
+    package default uses an explicit ``http://`` scheme. Self-hosted/dev clusters
+    can pass ``api_url="http://my-cluster:9443"`` to opt into plaintext.
+    """
+    if url.startswith("http://"):
+        return Endpoint(host=url[len("http://"):], use_tls=False)
+    if url.startswith("https://"):
+        return Endpoint(host=url[len("https://"):], use_tls=True)
+    is_local = url.startswith("localhost") or url.startswith("127.")
+    return Endpoint(host=url, use_tls=not is_local)
+
+
+def parse_size(s: str) -> int:
+    """Parse a human-readable size string to bytes.
+
+    Examples: "8G" -> 8589934592, "512M" -> 536870912, "100G" -> 107374182400
+    """
+    if not s:
+        return 0
+    m = re.match(r"^(\d+)\s*([KMGT]?)i?[Bb]?$", s.strip(), re.IGNORECASE)
+    if not m:
+        raise ValueError(f"invalid size: {s!r}")
+    num = int(m.group(1))
+    unit = m.group(2).upper()
+    multipliers = {"": 1, "K": 1024, "M": 1024**2, "G": 1024**3, "T": 1024**4}
+    return num * multipliers[unit]
+
+
+class GrpcCaller:
+    """Mixin for classes that call gRPC methods through a Compute client.
+
+    Subclasses must have a ``_client`` attribute of type :class:`Compute`.
+    """
+
+    _client: Compute
+
+    async def _call(self, method_name: str, request):
+        """Call a gRPC method on the stub, converting errors."""
+        stub = await self._client._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

boxd/aio.py

@@ -0,0 +1,96 @@
+"""Async API for the boxd SDK.
+
+Usage::
+
+    from boxd.aio import Compute
+
+    async with Compute(api_key="bxk_...") as c:
+        box = await c.box.create("my-vm")
+        result = await box.exec("echo", "hello")
+        print(result.stdout)
+"""
+
+# Re-export async classes under their original names
+from .client import Compute
+from .box import Box
+from .exec import ExecResult, ExecProcess, StreamReader, StreamWriter
+from .boxes import BoxService
+from .templates import TemplateService
+from .disks import DiskService, DiskHandle
+from .domains import DomainService
+from .networks import NetworkService
+from .tokens import TokenService
+
+# Types and errors are shared — re-export for convenience
+from .types import (
+    BoxConfig,
+    ConfigResult,
+    Disk,
+    DiskAttachment,
+    Domain,
+    LifecycleConfig,
+    Network,
+    NetworkConfig,
+    Proxy,
+    ProxyEntry,
+    PtyInfo,
+    ResumeResult,
+    SuspendResult,
+    Template,
+    Token,
+    TokenInfo,
+    VolumeMount,
+    WhoamiResult,
+)
+from .errors import (
+    BoxdError,
+    AuthenticationError,
+    NotFoundError,
+    QuotaExceededError,
+    InvalidArgumentError,
+    InternalError,
+    TimeoutError,
+    ConnectionError,
+)
+
+__all__ = [
+    "Compute",
+    "Box",
+    "BoxService",
+    "ExecResult",
+    "ExecProcess",
+    "StreamReader",
+    "StreamWriter",
+    "TemplateService",
+    "DiskService",
+    "DiskHandle",
+    "DomainService",
+    "NetworkService",
+    "TokenService",
+    "BoxConfig",
+    "LifecycleConfig",
+    "NetworkConfig",
+    "ProxyEntry",
+    "VolumeMount",
+    "Proxy",
+    "Template",
+    "Disk",
+    "DiskAttachment",
+    "Domain",
+    "Network",
+    "Token",
+    "TokenInfo",
+    "SuspendResult",
+    "ResumeResult",
+    "PtyInfo",
+    "WhoamiResult",
+    "ConfigResult",
+    "BoxdError",
+    "AuthenticationError",
+    "NotFoundError",
+    "QuotaExceededError",
+    "InvalidArgumentError",
+    "InternalError",
+    "TimeoutError",
+    "ConnectionError",
+]