capsule-sdk 0.1.0__tar.gz

capsule_sdk-0.1.0/.gitignore

@@ -0,0 +1,101 @@
+# Pre-built binaries (use `make build` instead)
+bin/
+*.exe
+*.dll
+*.so
+*.dylib
+
+# Go build output (matches cmd/ directory names)
+/capsule-control-plane
+/data-snapshot-builder
+/capsule-manager
+/git-cache-builder
+/git-cache-freshness
+/onboard
+/snapshot-builder
+/snapshot-converter
+/capsule-thaw-agent
+/derive-snapshot
+
+# Build outputs (use `make build-rootfs`)
+images/microvm/output/
+*.img
+*.bin
+
+# Terraform
+deploy/terraform/**/.terraform/
+deploy/terraform/**/.terraform.lock.hcl
+deploy/terraform/**/*.tfplan
+deploy/terraform/**/*.tfstate
+deploy/terraform/**/*.tfstate.*
+deploy/terraform/**/*.tfvars
+!deploy/terraform/**/*.tfvars.example
+
+# Packer
+deploy/packer/*.pkr.hcl.bak
+*.box
+
+# Kubernetes secrets (generated)
+deploy/kubernetes/*-secrets.yaml
+deploy/kubernetes/*-secret.yaml
+
+# Helm
+deploy/helm/**/charts/
+deploy/helm/**/*.tgz
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets and credentials
+*.pem
+*.key
+*.crt
+*.p12
+*.pfx
+secrets/
+.env
+.env.*
+!.env.example
+
+# Logs
+*.log
+logs/
+
+# Go
+vendor/
+go.work
+go.work.sum
+
+# Test artifacts
+coverage.out
+coverage.html
+*.test
+*.prof
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+*.bak
+
+# Docker
+.docker/
+
+# Cache directories
+.cache/
+__pycache__/
+
+/deploy/terraform/tfplan
+
+.claude/
+
+# Terraform provider cache (non-glob match for root terraform dir)
+deploy/terraform/.terraform/

capsule_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: capsule-sdk
+Version: 0.1.0
+Summary: Python SDK for Capsule
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: websockets<15.0,>=12.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Capsule SDK
+
+The Capsule SDK is the recommended client surface for registering workloads,
+triggering builds, allocating runners, and interacting with running Capsule
+sandboxes from Python.
+
+## Requirements
+
+- Python `>= 3.10`
+- access to a running Capsule control plane
+- an API token if your deployment requires authenticated requests
+
+## Installation
+
+```bash
+pip install capsule-sdk
+```
+
+For local development:
+
+```bash
+cd sdk/python
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Configuration
+
+The SDK can be configured directly in code or through environment variables.
+
+| Parameter | Env var | Default |
+|---|---|---|
+| `base_url` | `CAPSULE_BASE_URL` | `http://localhost:8080` |
+| `token` | `CAPSULE_TOKEN` | `None` |
+| `request_timeout` | `CAPSULE_REQUEST_TIMEOUT` | `30.0` |
+| `startup_timeout` | `CAPSULE_STARTUP_TIMEOUT` | `45.0` |
+| `operation_timeout` | `CAPSULE_OPERATION_TIMEOUT` | `120.0` |
+
+Example:
+
+```bash
+export CAPSULE_BASE_URL="http://localhost:8080"
+export CAPSULE_TOKEN="my-token"
+```
+
+## Quickstart
+
+The fastest way to get started is the high-level `workloads` API.
+
+```python
+from capsule_sdk import CapsuleClient, RunnerConfig
+
+cfg = (
+    RunnerConfig("My dev sandbox")
+    .with_base_image("ubuntu:22.04")
+    .with_commands(["apt-get update", "apt-get install -y python3"])
+    .with_tier("m")
+    .with_ttl(3600)
+    .with_auto_pause(True)
+    .with_auto_rollout(True)
+)
+
+with CapsuleClient(base_url="http://localhost:8080", token="my-token") as client:
+    workload = client.workloads.onboard(cfg)
+
+    with client.workloads.start(workload) as runner:
+        output, code = runner.exec_collect("python3", "-c", "print('hello')")
+        print(output, code)
+
+        runner.write_text("/workspace/hello.txt", "hello")
+        print(runner.read_text("/workspace/hello.txt"))
+```
+
+## Onboard From YAML
+
+You can also onboard directly from an `onboard.yaml`-style file:
+
+```python
+from capsule_sdk import CapsuleClient
+
+with CapsuleClient(base_url="http://localhost:8080", token="my-token") as client:
+    workload = client.workloads.onboard_yaml(
+        "examples/afs/onboard.yaml",
+        name="afs-sandbox",
+    )
+
+    with client.workloads.start("afs-sandbox") as runner:
+        print(runner.read_text("/etc/hostname"))
+```
+
+The AFS example is an example workload name, not a special SDK mode. See
+`examples/afs/` for the underlying config shape.
+
+## Async Quickstart
+
+Use the async client in event-loop-native applications:
+
+```python
+import asyncio
+
+from capsule_sdk import AsyncCapsuleClient, RunnerConfig
+
+
+async def main() -> None:
+    cfg = (
+        RunnerConfig("My async sandbox")
+        .with_base_image("ubuntu:22.04")
+        .with_commands(["echo async-ready"])
+        .with_tier("m")
+        .with_ttl(3600)
+        .with_auto_pause(True)
+    )
+
+    async with AsyncCapsuleClient(base_url="http://localhost:8080", token="my-token") as client:
+        workload = await client.workloads.onboard(cfg)
+        runner = await client.workloads.start(workload)
+
+        async with runner:
+            result = await runner.exec_collect("sh", "-lc", "printf hello")
+            print(result.stdout, result.exit_code)
+
+
+asyncio.run(main())
+```
+
+## Low-Level APIs
+
+For finer control, work directly with the resource clients:
+
+```python
+from capsule_sdk import CapsuleClient
+
+with CapsuleClient(base_url="http://localhost:8080", token="my-token") as client:
+    with client.runners.allocate_ready("my-workload-key") as runner:
+        for event in runner.exec("echo", "hello"):
+            if event.type == "stdout":
+                print(event.data, end="")
+```
+
+Key low-level surfaces:
+
+- `client.runners`
+- `client.workloads`
+- `client.snapshots`
+- `client.runner_configs`
+
+## Key Concepts
+
+| SDK concept | Server primitive | Description |
+|---|---|---|
+| `RunnerConfig` | `LayeredConfig` | Declarative workload shape |
+| `workloads.onboard()` | create + build | Register a workload from Python or YAML |
+| `workloads.start()` | allocate + wait | Start a ready runner by workload name |
+| `runners.allocate_ready()` | `/runners/allocate` | Allocate and wait for a usable runner |
+| `RunnerSession` | runner handle | High-level exec, file, shell, pause, and resume API |
+
+## Retry And Timeout Behavior
+
+- `request_timeout` applies to a single HTTP request
+- `startup_timeout` covers "get me a usable runner"
+- `operation_timeout` applies to host-side file, PTY, and stream operations
+- `allocate()` retries transient control-plane and capacity errors until `startup_timeout`
+- `workloads.start()` is the preferred high-level path for named workloads
+- `from_config()` waits for runner readiness by default; use `wait_ready=False` for lower-level control
+
+## Host Reconnection
+
+The SDK caches host addresses returned by `allocate()` and `connect()`. If a
+host proxy becomes unavailable during a safe retryable operation, the SDK will
+refresh the host via `connect()` and retry once when possible.
+
+## Live End-To-End Test
+
+The repository includes an explicit live SDK E2E at `sdk/python/tests/e2e_live.py`.
+It exercises config registration, build enqueue, allocation, exec, file ops,
+PTY, pause/resume, release, and config cleanup against a real control plane.
+
+Run it with:
+
+```bash
+make sdk-python-e2e
+```
+
+If you are not using the default address:
+
+```bash
+CAPSULE_BASE_URL="http://localhost:8080" make sdk-python-e2e
+```
+
+## Development Checks
+
+```bash
+python -m ruff check src/capsule_sdk/ tests/
+python -m pyright src/capsule_sdk/
+python -m pytest tests/ -v --ignore=tests/e2e_live.py --ignore=tests/e2e_live_async.py
+```
+
+For contract tests against a live control plane:
+
+```bash
+CAPSULE_BASE_URL=http://localhost:8080 CAPSULE_TOKEN=test-token \
+  python -m pytest tests/test_contract.py -v -m contract
+```

capsule_sdk-0.1.0/README.md

@@ -0,0 +1,204 @@
+# Capsule SDK
+
+The Capsule SDK is the recommended client surface for registering workloads,
+triggering builds, allocating runners, and interacting with running Capsule
+sandboxes from Python.
+
+## Requirements
+
+- Python `>= 3.10`
+- access to a running Capsule control plane
+- an API token if your deployment requires authenticated requests
+
+## Installation
+
+```bash
+pip install capsule-sdk
+```
+
+For local development:
+
+```bash
+cd sdk/python
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Configuration
+
+The SDK can be configured directly in code or through environment variables.
+
+| Parameter | Env var | Default |
+|---|---|---|
+| `base_url` | `CAPSULE_BASE_URL` | `http://localhost:8080` |
+| `token` | `CAPSULE_TOKEN` | `None` |
+| `request_timeout` | `CAPSULE_REQUEST_TIMEOUT` | `30.0` |
+| `startup_timeout` | `CAPSULE_STARTUP_TIMEOUT` | `45.0` |
+| `operation_timeout` | `CAPSULE_OPERATION_TIMEOUT` | `120.0` |
+
+Example:
+
+```bash
+export CAPSULE_BASE_URL="http://localhost:8080"
+export CAPSULE_TOKEN="my-token"
+```
+
+## Quickstart
+
+The fastest way to get started is the high-level `workloads` API.
+
+```python
+from capsule_sdk import CapsuleClient, RunnerConfig
+
+cfg = (
+    RunnerConfig("My dev sandbox")
+    .with_base_image("ubuntu:22.04")
+    .with_commands(["apt-get update", "apt-get install -y python3"])
+    .with_tier("m")
+    .with_ttl(3600)
+    .with_auto_pause(True)
+    .with_auto_rollout(True)
+)
+
+with CapsuleClient(base_url="http://localhost:8080", token="my-token") as client:
+    workload = client.workloads.onboard(cfg)
+
+    with client.workloads.start(workload) as runner:
+        output, code = runner.exec_collect("python3", "-c", "print('hello')")
+        print(output, code)
+
+        runner.write_text("/workspace/hello.txt", "hello")
+        print(runner.read_text("/workspace/hello.txt"))
+```
+
+## Onboard From YAML
+
+You can also onboard directly from an `onboard.yaml`-style file:
+
+```python
+from capsule_sdk import CapsuleClient
+
+with CapsuleClient(base_url="http://localhost:8080", token="my-token") as client:
+    workload = client.workloads.onboard_yaml(
+        "examples/afs/onboard.yaml",
+        name="afs-sandbox",
+    )
+
+    with client.workloads.start("afs-sandbox") as runner:
+        print(runner.read_text("/etc/hostname"))
+```
+
+The AFS example is an example workload name, not a special SDK mode. See
+`examples/afs/` for the underlying config shape.
+
+## Async Quickstart
+
+Use the async client in event-loop-native applications:
+
+```python
+import asyncio
+
+from capsule_sdk import AsyncCapsuleClient, RunnerConfig
+
+
+async def main() -> None:
+    cfg = (
+        RunnerConfig("My async sandbox")
+        .with_base_image("ubuntu:22.04")
+        .with_commands(["echo async-ready"])
+        .with_tier("m")
+        .with_ttl(3600)
+        .with_auto_pause(True)
+    )
+
+    async with AsyncCapsuleClient(base_url="http://localhost:8080", token="my-token") as client:
+        workload = await client.workloads.onboard(cfg)
+        runner = await client.workloads.start(workload)
+
+        async with runner:
+            result = await runner.exec_collect("sh", "-lc", "printf hello")
+            print(result.stdout, result.exit_code)
+
+
+asyncio.run(main())
+```
+
+## Low-Level APIs
+
+For finer control, work directly with the resource clients:
+
+```python
+from capsule_sdk import CapsuleClient
+
+with CapsuleClient(base_url="http://localhost:8080", token="my-token") as client:
+    with client.runners.allocate_ready("my-workload-key") as runner:
+        for event in runner.exec("echo", "hello"):
+            if event.type == "stdout":
+                print(event.data, end="")
+```
+
+Key low-level surfaces:
+
+- `client.runners`
+- `client.workloads`
+- `client.snapshots`
+- `client.runner_configs`
+
+## Key Concepts
+
+| SDK concept | Server primitive | Description |
+|---|---|---|
+| `RunnerConfig` | `LayeredConfig` | Declarative workload shape |
+| `workloads.onboard()` | create + build | Register a workload from Python or YAML |
+| `workloads.start()` | allocate + wait | Start a ready runner by workload name |
+| `runners.allocate_ready()` | `/runners/allocate` | Allocate and wait for a usable runner |
+| `RunnerSession` | runner handle | High-level exec, file, shell, pause, and resume API |
+
+## Retry And Timeout Behavior
+
+- `request_timeout` applies to a single HTTP request
+- `startup_timeout` covers "get me a usable runner"
+- `operation_timeout` applies to host-side file, PTY, and stream operations
+- `allocate()` retries transient control-plane and capacity errors until `startup_timeout`
+- `workloads.start()` is the preferred high-level path for named workloads
+- `from_config()` waits for runner readiness by default; use `wait_ready=False` for lower-level control
+
+## Host Reconnection
+
+The SDK caches host addresses returned by `allocate()` and `connect()`. If a
+host proxy becomes unavailable during a safe retryable operation, the SDK will
+refresh the host via `connect()` and retry once when possible.
+
+## Live End-To-End Test
+
+The repository includes an explicit live SDK E2E at `sdk/python/tests/e2e_live.py`.
+It exercises config registration, build enqueue, allocation, exec, file ops,
+PTY, pause/resume, release, and config cleanup against a real control plane.
+
+Run it with:
+
+```bash
+make sdk-python-e2e
+```
+
+If you are not using the default address:
+
+```bash
+CAPSULE_BASE_URL="http://localhost:8080" make sdk-python-e2e
+```
+
+## Development Checks
+
+```bash
+python -m ruff check src/capsule_sdk/ tests/
+python -m pyright src/capsule_sdk/
+python -m pytest tests/ -v --ignore=tests/e2e_live.py --ignore=tests/e2e_live_async.py
+```
+
+For contract tests against a live control plane:
+
+```bash
+CAPSULE_BASE_URL=http://localhost:8080 CAPSULE_TOKEN=test-token \
+  python -m pytest tests/test_contract.py -v -m contract
+```

capsule_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling", "packaging>=24.2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "capsule-sdk"
+dynamic = ["version"]
+description = "Python SDK for Capsule"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+dependencies = [
+    "httpx>=0.27,<1.0",
+    "pydantic>=2.0,<3.0",
+    "PyYAML>=6.0",
+    "websockets>=12.0,<15.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-httpx>=0.30",
+    "ruff>=0.4",
+    "pyright>=1.1",
+    "respx>=0.21",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/capsule_sdk"]
+
+[tool.hatch.version]
+path = "src/capsule_sdk/_version.py"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "SIM"]
+ignore = ["N818", "SIM117"]
+
+[tool.pyright]
+pythonVersion = "3.10"
+typeCheckingMode = "strict"
+
+[tool.pytest.ini_options]
+markers = [
+    "contract: tests that run against a live control-plane instance",
+]

capsule_sdk-0.1.0/src/capsule_sdk/__init__.py

@@ -0,0 +1,60 @@
+"""capsule-sdk: Python SDK for capsule."""
+
+from capsule_sdk._errors import (
+    CapsuleAllocationTimeoutError,
+    CapsuleAuthError,
+    CapsuleConflict,
+    CapsuleConnectionError,
+    CapsuleError,
+    CapsuleHTTPError,
+    CapsuleNotFound,
+    CapsuleOperationTimeoutError,
+    CapsuleRateLimited,
+    CapsuleRequestTimeoutError,
+    CapsuleRunnerUnavailableError,
+    CapsuleServiceUnavailable,
+    CapsuleTimeoutError,
+)
+from capsule_sdk._shell_async import AsyncShellSession
+from capsule_sdk._version import __version__
+from capsule_sdk.async_client import AsyncCapsuleClient
+from capsule_sdk.async_runner_config import AsyncRunnerConfigs
+from capsule_sdk.async_runner_session import AsyncRunnerSession
+from capsule_sdk.client import CapsuleClient
+from capsule_sdk.models.workload import WorkloadSummary
+from capsule_sdk.resources.async_runners import AsyncRunners
+from capsule_sdk.resources.async_snapshots import AsyncSnapshots
+from capsule_sdk.resources.async_workloads import AsyncWorkloads
+from capsule_sdk.resources.workloads import Workloads
+from capsule_sdk.runner_config import RunnerConfig, RunnerConfigs
+from capsule_sdk.runner_session import RunnerSession
+
+__all__ = [
+    "CapsuleAuthError",
+    "CapsuleAllocationTimeoutError",
+    "AsyncCapsuleClient",
+    "AsyncRunners",
+    "AsyncRunnerConfigs",
+    "AsyncRunnerSession",
+    "AsyncShellSession",
+    "AsyncSnapshots",
+    "AsyncWorkloads",
+    "CapsuleClient",
+    "CapsuleConflict",
+    "CapsuleConnectionError",
+    "CapsuleError",
+    "CapsuleHTTPError",
+    "CapsuleNotFound",
+    "CapsuleOperationTimeoutError",
+    "CapsuleRequestTimeoutError",
+    "CapsuleRateLimited",
+    "CapsuleRunnerUnavailableError",
+    "CapsuleServiceUnavailable",
+    "CapsuleTimeoutError",
+    "RunnerConfig",
+    "RunnerConfigs",
+    "RunnerSession",
+    "WorkloadSummary",
+    "Workloads",
+    "__version__",
+]

capsule_sdk-0.1.0/src/capsule_sdk/_config.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from capsule_sdk._version import __version__
+
+
+@dataclass(frozen=True)
+class ConnectionConfig:
+    """Resolved connection configuration."""
+
+    base_url: str
+    token: str | None
+    request_timeout: float
+    startup_timeout: float
+    operation_timeout: float
+    user_agent: str
+
+    @property
+    def timeout(self) -> float:
+        """Backward-compatible alias for the request timeout."""
+        return self.request_timeout
+
+    @classmethod
+    def resolve(
+        cls,
+        *,
+        base_url: str | None = None,
+        token: str | None = None,
+        timeout: float = 30.0,
+        request_timeout: float | None = None,
+        startup_timeout: float | None = None,
+        operation_timeout: float | None = None,
+    ) -> ConnectionConfig:
+        resolved_base_url = (
+            base_url
+            or os.environ.get("CAPSULE_BASE_URL")
+            or "http://localhost:8080"
+        ).rstrip("/")
+
+        resolved_token = token if token is not None else os.environ.get("CAPSULE_TOKEN")
+        resolved_request_timeout = (
+            request_timeout
+            if request_timeout is not None
+            else float(os.environ.get("CAPSULE_REQUEST_TIMEOUT", timeout))
+        )
+        resolved_startup_timeout = (
+            startup_timeout
+            if startup_timeout is not None
+            else float(os.environ.get("CAPSULE_STARTUP_TIMEOUT", 45.0))
+        )
+        resolved_operation_timeout = (
+            operation_timeout
+            if operation_timeout is not None
+            else float(os.environ.get("CAPSULE_OPERATION_TIMEOUT", 120.0))
+        )
+
+        return cls(
+            base_url=resolved_base_url,
+            token=resolved_token,
+            request_timeout=resolved_request_timeout,
+            startup_timeout=resolved_startup_timeout,
+            operation_timeout=resolved_operation_timeout,
+            user_agent=f"capsule-sdk-python/{__version__}",
+        )