arker 0.1.0__tar.gz

arker-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Build artifacts
+build/
+dist/
+*.egg-info/
+*.whl
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+
+# OS
+.DS_Store

arker-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: arker
+Version: 0.1.0
+Summary: Python client for the Arker virtual computer platform.
+Project-URL: Homepage, https://arker.ai
+Project-URL: Documentation, https://arker.ai/docs
+Project-URL: Source, https://github.com/ArkerHQ/arker-python-sdk
+Project-URL: Issues, https://github.com/ArkerHQ/arker-python-sdk/issues
+Author-email: Arker <support@arker.ai>
+License-Expression: Apache-2.0
+Keywords: agent,arker,code-execution,sandbox,vm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Arker — Python SDK
+
+Single-file Python client for the [Arker](https://arker.ai) virtual computer
+platform. Spawn isolated Linux sandboxes, run shell / Python / Node code in
+them, read and write files. Zero runtime dependencies (stdlib `urllib`).
+
+## Install
+
+```bash
+pip install arker
+```
+
+Or, while in alpha:
+
+```bash
+pip install git+https://github.com/ArkerHQ/arker-python-sdk@v0.1.0
+```
+
+## Quickstart
+
+```python
+from arker import Arker, ArkerError
+
+arker  = Arker(api_key="ark_live_...")
+vm     = arker.vm("arkuntu").fork(name="hello")     # fresh VM from base image
+result = vm.run("python3 -c 'print(2+2)'")
+print(result.stdout.decode())                        # → "4\n"
+
+vm.sync.write_file("/home/user/data.csv", b"a,b\n1,2\n")
+data = vm.sync.read_file("/home/user/data.csv")      # → b"a,b\n1,2\n"
+
+child = vm.fork(name="branch")                       # constant-time copy-on-write
+child.delete()
+vm.delete()
+```
+
+List your VMs:
+
+```python
+page = arker.list(limit=10, sort="-created_at")
+print(f"{page.total} total")
+for summary in page:                                 # iterable; also page.items
+    print(summary.vm_id, summary.name, summary.region, summary.created_at)
+```
+
+## API
+
+```
+Arker(api_key, base_url=None)
+    .vm(vm_id) -> Computer                          # open handle (no network call)
+    .list(*, limit=25, offset=0, q=None, sort=None) -> VmList
+
+Computer
+    .id, .delete()
+    .fork(*, name=, is_public=, region=) -> Computer
+    .run(command, *, session_id=, timeout=) -> RunResult
+    .sync.read_file(path) -> bytes
+    .sync.write_file(path, data: bytes | str)
+
+RunResult: stdout, stderr (bytes), exit_code, duration_ms, session_id, cwd
+VmSummary: vm_id, name, base_image, region, created_at (ISO 8601)
+VmList: items (list[VmSummary]), total (int);  iterable, len()-able
+
+ArkerError(code, message, status)                   # one exception type for everything
+```
+
+### Routing
+
+`fork`, `run`, `sync`, and `delete` use the regional endpoint set on the
+client (default `https://aws-us-west-2.burst.arker.ai`).
+
+`list` always goes through `https://arker.ai` regardless of `base_url`,
+because list data is served from a global host rather than a regional
+one.
+
+Public base-image names like `"arkuntu"` resolve to a ULID **client-side**
+(see `SOURCE_ALIASES` in `computer.py`), so `arker.vm("arkuntu").fork()`
+works on the default endpoint with no extra round-trip. Override
+`base_url` or set `ARKER_BASE_URL` to point at a different region or a
+self-hosted deployment.
+
+### Errors
+
+Every server-side error becomes an `ArkerError`:
+
+```python
+try:
+    vm.sync.read_file("/home/user/missing")
+except ArkerError as err:
+    print(err.code)      # "not_found"
+    print(err.message)   # "file not found: /home/user/missing"
+    print(err.status)    # 404
+```
+
+`code` is a stable enum: `bad_request`, `unauthorized`, `payment_required`,
+`forbidden`, `not_found`, `conflict`, `payload_too_large`, `internal`,
+`not_implemented`, `vm_busy`, `unsupported_*`, `command_not_found`.
+
+### What the SDK does for you
+
+Hidden behind these six methods:
+
+- **Write strategy**: files up to 100 MB. Small payloads go in one call;
+  larger ones use a direct upload path so the bytes don't traverse the
+  API layer. `write_file` returns once the bytes are durably stored.
+- **Read coalescing**: `read_file` always returns raw `bytes`, regardless
+  of whether the server inlined the content or returned a signed URL.
+- **Idempotent retry**: transient errors are retried with exponential
+  backoff. Writes are server-side idempotent on `upload_id`, so retries
+  never produce duplicates.
+- **Path validation**: only `/home/user/...` paths accepted; `..` rejected.
+
+## Demo / smoke test
+
+Run the full surface against a live deployment:
+
+```bash
+ARKER_API_KEY=ark_live_... python tests/demo.py
+```
+
+It exercises every method (`list`, `vm`, `fork`, `run`, `sync.write_file`,
+`sync.read_file`, error path, child fork, `delete`) and prints what each
+call hits on the wire — useful as living documentation.
+
+## License
+
+Apache-2.0.

arker-0.1.0/README.md

@@ -0,0 +1,127 @@
+# Arker — Python SDK
+
+Single-file Python client for the [Arker](https://arker.ai) virtual computer
+platform. Spawn isolated Linux sandboxes, run shell / Python / Node code in
+them, read and write files. Zero runtime dependencies (stdlib `urllib`).
+
+## Install
+
+```bash
+pip install arker
+```
+
+Or, while in alpha:
+
+```bash
+pip install git+https://github.com/ArkerHQ/arker-python-sdk@v0.1.0
+```
+
+## Quickstart
+
+```python
+from arker import Arker, ArkerError
+
+arker  = Arker(api_key="ark_live_...")
+vm     = arker.vm("arkuntu").fork(name="hello")     # fresh VM from base image
+result = vm.run("python3 -c 'print(2+2)'")
+print(result.stdout.decode())                        # → "4\n"
+
+vm.sync.write_file("/home/user/data.csv", b"a,b\n1,2\n")
+data = vm.sync.read_file("/home/user/data.csv")      # → b"a,b\n1,2\n"
+
+child = vm.fork(name="branch")                       # constant-time copy-on-write
+child.delete()
+vm.delete()
+```
+
+List your VMs:
+
+```python
+page = arker.list(limit=10, sort="-created_at")
+print(f"{page.total} total")
+for summary in page:                                 # iterable; also page.items
+    print(summary.vm_id, summary.name, summary.region, summary.created_at)
+```
+
+## API
+
+```
+Arker(api_key, base_url=None)
+    .vm(vm_id) -> Computer                          # open handle (no network call)
+    .list(*, limit=25, offset=0, q=None, sort=None) -> VmList
+
+Computer
+    .id, .delete()
+    .fork(*, name=, is_public=, region=) -> Computer
+    .run(command, *, session_id=, timeout=) -> RunResult
+    .sync.read_file(path) -> bytes
+    .sync.write_file(path, data: bytes | str)
+
+RunResult: stdout, stderr (bytes), exit_code, duration_ms, session_id, cwd
+VmSummary: vm_id, name, base_image, region, created_at (ISO 8601)
+VmList: items (list[VmSummary]), total (int);  iterable, len()-able
+
+ArkerError(code, message, status)                   # one exception type for everything
+```
+
+### Routing
+
+`fork`, `run`, `sync`, and `delete` use the regional endpoint set on the
+client (default `https://aws-us-west-2.burst.arker.ai`).
+
+`list` always goes through `https://arker.ai` regardless of `base_url`,
+because list data is served from a global host rather than a regional
+one.
+
+Public base-image names like `"arkuntu"` resolve to a ULID **client-side**
+(see `SOURCE_ALIASES` in `computer.py`), so `arker.vm("arkuntu").fork()`
+works on the default endpoint with no extra round-trip. Override
+`base_url` or set `ARKER_BASE_URL` to point at a different region or a
+self-hosted deployment.
+
+### Errors
+
+Every server-side error becomes an `ArkerError`:
+
+```python
+try:
+    vm.sync.read_file("/home/user/missing")
+except ArkerError as err:
+    print(err.code)      # "not_found"
+    print(err.message)   # "file not found: /home/user/missing"
+    print(err.status)    # 404
+```
+
+`code` is a stable enum: `bad_request`, `unauthorized`, `payment_required`,
+`forbidden`, `not_found`, `conflict`, `payload_too_large`, `internal`,
+`not_implemented`, `vm_busy`, `unsupported_*`, `command_not_found`.
+
+### What the SDK does for you
+
+Hidden behind these six methods:
+
+- **Write strategy**: files up to 100 MB. Small payloads go in one call;
+  larger ones use a direct upload path so the bytes don't traverse the
+  API layer. `write_file` returns once the bytes are durably stored.
+- **Read coalescing**: `read_file` always returns raw `bytes`, regardless
+  of whether the server inlined the content or returned a signed URL.
+- **Idempotent retry**: transient errors are retried with exponential
+  backoff. Writes are server-side idempotent on `upload_id`, so retries
+  never produce duplicates.
+- **Path validation**: only `/home/user/...` paths accepted; `..` rejected.
+
+## Demo / smoke test
+
+Run the full surface against a live deployment:
+
+```bash
+ARKER_API_KEY=ark_live_... python tests/demo.py
+```
+
+It exercises every method (`list`, `vm`, `fork`, `run`, `sync.write_file`,
+`sync.read_file`, error path, child fork, `delete`) and prints what each
+call hits on the wire — useful as living documentation.
+
+## License
+
+Apache-2.0.

arker-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "arker"
+version = "0.1.0"
+description = "Python client for the Arker virtual computer platform."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "Arker", email = "support@arker.ai" }]
+keywords = ["arker", "vm", "sandbox", "agent", "code-execution"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+# Zero runtime dependencies — stdlib `urllib` only.
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=8.0"]
+
+[project.urls]
+Homepage = "https://arker.ai"
+Documentation = "https://arker.ai/docs"
+Source = "https://github.com/ArkerHQ/arker-python-sdk"
+Issues = "https://github.com/ArkerHQ/arker-python-sdk/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/arker"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# `test_e2e.py` and `test_presigned.py` hit a live deployment; skip
+# unless ARKER_API_KEY is set in the environment.
+addopts = "-q"

arker-0.1.0/src/arker/__init__.py

@@ -0,0 +1,7 @@
+"""Arker — single-file Python client for the Arker virtual computer
+platform. See README.md for the quickstart, `arker/computer.py` for
+the implementation, and `docs/sync-api.md` for wire-level details."""
+from .computer import Arker, Computer, Sync, RunResult, VmSummary, VmList, ArkerError
+
+__all__ = ["Arker", "Computer", "Sync", "RunResult", "VmSummary", "VmList", "ArkerError"]
+__version__ = "0.1.0"

arker-0.1.0/src/arker/computer.py

@@ -0,0 +1,319 @@
+"""Arker SDK — single-file Python client.
+
+Quickstart:
+
+    from arker import Arker
+    arker = Arker(api_key="ark_live_...")
+    vm    = arker.vm("arkuntu").fork(name="hello")     # fresh VM from base image
+    result = vm.run("echo hi")                          # result.stdout: bytes, result.exit_code: int
+
+    vm.sync.write_file("/home/user/data.bin", b"...")
+    blob = vm.sync.read_file("/home/user/data.bin")    # → bytes
+
+    child = vm.fork(name="branch")                     # branch off this VM
+    child.delete(); vm.delete()
+
+    # List your VMs (paginated):
+    page = arker.list(limit=10)
+    for summary in page.items:
+        print(summary.vm_id, summary.name, summary.created_at)
+
+    # Re-open an existing VM by ID (no network call):
+    same_vm = arker.vm("01ABC...XYZ_d8c0")
+
+Errors raise `ArkerError(code, message, status)`.
+"""
+from __future__ import annotations
+import base64, dataclasses, json, os, secrets, time, urllib.error, urllib.parse, urllib.request
+from typing import Any
+
+DEFAULT_BASE_URL = "https://aws-us-west-2.burst.arker.ai"
+LIST_BASE_URL    = "https://arker.ai"   # `list` is served from a different host than the rest;
+                                        # used regardless of the client's base_url.
+SOURCE_ALIASES   = {"arkuntu": "01KQBYKEV5WJ7YB010603T1DCT_d8c0"}  # public base images
+CHUNK_SIZE       = 4 * 1024 * 1024     # files above this go through a direct upload
+PRESIGN_EXPIRES  = 900                  # signed-URL lifetime (s)
+RETRYABLE_HTTP   = {429, 502, 503, 504}
+# Substring matches in `error.message` that mark a transient failure
+# the server expects clients to retry. Matched verbatim against the
+# message returned in the error envelope.
+_TRANSIENT_HINTS = ("503", "Service Unavailable", "throttle", "SlowDown", "ThrottlingException")
+MAX_ATTEMPTS     = 4
+BACKOFF_S        = 0.2
+ULID_ALPHABET    = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+
+class ArkerError(Exception):
+    def __init__(self, code: str, message: str, status: int) -> None:
+        super().__init__(f"{code}: {message}")
+        self.code, self.message, self.status = code, message, status
+
+
+@dataclasses.dataclass
+class RunResult:
+    stdout: bytes; stderr: bytes; exit_code: int
+    duration_ms: float; session_id: str; cwd: str
+
+
+@dataclasses.dataclass
+class VmSummary:
+    """One row from `Arker.list()`. `created_at` is ISO 8601 UTC."""
+    vm_id: str
+    name: str | None
+    base_image: str
+    region: str
+    created_at: str
+
+
+@dataclasses.dataclass
+class VmList:
+    items: list[VmSummary]
+    total: int                          # total matching the query, ignoring limit/offset
+    def __iter__(self): return iter(self.items)
+    def __len__(self): return len(self.items)
+
+
+def _ulid() -> str:
+    """26-char Crockford-base32 ULID; not strictly monotonic, but unique
+    enough — the server's `If-None-Match: *` catches any duplicates."""
+    raw = ((int(time.time() * 1000) & ((1 << 48) - 1)) << 80) | secrets.randbits(80)
+    out = []
+    for _ in range(26):
+        out.append(ULID_ALPHABET[raw & 31]); raw >>= 5
+    return "".join(reversed(out))
+
+
+def _looks_like_vm_id(s: str) -> bool:
+    """ULID-shape check: 26 Crockford chars, optionally `_<region>` suffix
+    of 1+ alphanumeric chars (e.g. `_uswe`, `_d8c0`). Used by `fork()`
+    to dispatch by-id vs by-ref."""
+    if "_" in s:
+        head, _, tail = s.partition("_")
+        if not tail or not all(c.isalnum() for c in tail):
+            return False
+    else:
+        head = s
+    if len(head) != 26:
+        return False
+    return all(c in ULID_ALPHABET for c in head.upper())
+
+
+def _decode_stream(text: Any, encoding: Any) -> bytes:
+    s = text or ""
+    if encoding == "base64":
+        try: return base64.b64decode(s)
+        except Exception: pass
+    return (s if isinstance(s, str) else "").encode("utf-8", "replace")
+
+
+def _is_transient(err: dict | None) -> bool:
+    if not err or err.get("code") != "internal":
+        return False
+    return any(h in (err.get("message") or "") for h in _TRANSIENT_HINTS)
+
+
+def _http(method: str, url: str, headers: dict, body: bytes | None) -> tuple[int, bytes]:
+    """Single-shot urllib request. Retry policy lives in `Arker._request`."""
+    req = urllib.request.Request(url, method=method, headers=headers, data=body)
+    try:
+        resp = urllib.request.urlopen(req, timeout=120)
+        return resp.status, resp.read()
+    except urllib.error.HTTPError as e:
+        return e.code, e.read()
+
+
+class Arker:
+    """Top-level client. Default `base_url` points at the production
+    regional endpoint; override per-client or via the `ARKER_BASE_URL`
+    env var to use a different region or a self-hosted deployment."""
+    def __init__(self, api_key: str, base_url: str | None = None) -> None:
+        if not api_key: raise ValueError("api_key is required")
+        self._api_key = api_key
+        self._base_url = (base_url or os.environ.get("ARKER_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+
+    def _request(self, method: str, path: str, body: dict | None = None,
+                 *, base_url: str | None = None) -> dict:
+        """One retry budget covering both transient HTTP statuses and
+        envelope-level transient errors. `base_url=` overrides the client
+        default for routes that live on a different host (e.g. `list`)."""
+        headers = {"authorization": f"Bearer {self._api_key}", "content-type": "application/json"}
+        data = json.dumps(body).encode() if body is not None else None
+        url = (base_url.rstrip("/") if base_url else self._base_url) + path
+        last_status, last_err, last_payload = 0, None, None
+        for attempt in range(MAX_ATTEMPTS):
+            status, raw = _http(method, url, headers, data)
+            try: payload = json.loads(raw) if raw else {}
+            except json.JSONDecodeError: payload = None
+            last_status, last_payload = status, payload
+            envelope_err = (payload.get("error") if isinstance(payload, dict) and payload.get("ok") is False else None)
+            last_err = envelope_err
+            if status in RETRYABLE_HTTP or _is_transient(envelope_err):
+                if attempt == MAX_ATTEMPTS - 1: break
+                time.sleep(BACKOFF_S * (2 ** attempt) + secrets.randbelow(50) / 1000.0)
+                continue
+            if envelope_err is not None:
+                raise ArkerError(envelope_err.get("code", "internal"), envelope_err.get("message", ""), status)
+            if status >= 400:
+                raise ArkerError("internal", str(payload)[:200], status)
+            return payload  # type: ignore[return-value]
+        if last_err is not None:
+            raise ArkerError(last_err.get("code", "internal"), last_err.get("message", ""), last_status)
+        raise ArkerError("internal", str(last_payload)[:200], last_status)
+
+    def vm(self, vm_id: str) -> "Computer":
+        """Open a handle to a VM by ULID *or* by template name (e.g.
+        `"arkuntu"`). Names resolve on `.fork()` only — you can't
+        `.run()` against a name handle. No network call here."""
+        return Computer(self, vm_id)
+
+    def list(self, *, limit: int = 25, offset: int = 0,
+             q: str | None = None, sort: str | None = None) -> VmList:
+        """List VMs in the caller's organization. Always hits
+        `https://arker.ai` regardless of the client's `base_url` — list
+        data is served from a global host rather than the regional one.
+
+        Args:
+            limit:  1–100, default 25.
+            offset: ≥0, default 0.
+            q:      substring filter on VM name.
+            sort:   `created_at` | `-created_at` | `region` | `-region`.
+                    Default `-created_at` (newest first).
+        """
+        params: dict[str, str] = {}
+        if limit  != 25:    params["limit"]  = str(limit)
+        if offset != 0:     params["offset"] = str(offset)
+        if q is not None:   params["q"]      = q
+        if sort is not None: params["sort"]  = sort
+        path = "/api/v1/vms/list"
+        if params:
+            path += "?" + urllib.parse.urlencode(params)
+        r = self._request("GET", path, base_url=LIST_BASE_URL)
+        items = [VmSummary(
+            vm_id      = i["vm_id"],
+            name       = i.get("name"),
+            base_image = i["base_image"],
+            region     = i["region"],
+            created_at = i["created_at"],
+        ) for i in r.get("items", [])]
+        return VmList(items=items, total=int(r.get("total", 0)))
+
+
+class Computer:
+    """A handle on one VM. Methods: `.delete()`, `.fork(...)`, `.run(...)`,
+    `.sync.read_file(path)`, `.sync.write_file(path, data)`."""
+    def __init__(self, client: Arker, vm_id: str) -> None:
+        self._client, self.id = client, vm_id
+        self._default_session: str | None = None
+        self.sync = Sync(self)
+
+    def delete(self) -> None:
+        self._client._request("DELETE", f"/api/v1/vms/{self.id}")
+
+    def fork(self, *, name: str | None = None, is_public: bool = False,
+             region: str | None = None) -> "Computer":
+        """Branch off this VM. Aliases like `"arkuntu"` resolve to a
+        ULID client-side via `SOURCE_ALIASES`; the request then uses
+        the by-id endpoint so it works on the default `base_url`."""
+        body: dict[str, Any] = {"is_public": is_public}
+        if name is not None:   body["name"] = name
+        if region is not None: body["region"] = region
+        resolved = SOURCE_ALIASES.get(self.id, self.id)
+        if _looks_like_vm_id(resolved):
+            r = self._client._request("POST", f"/api/v1/vms/{resolved}/fork", body)
+        else:
+            # Unknown name; let the global host resolve it.
+            body["from"] = self.id
+            r = self._client._request("POST", "/api/v1/vms/fork", body, base_url=LIST_BASE_URL)
+        if not r.get("vm_id"):
+            raise ArkerError("internal", "fork response missing vm_id", 200)
+        return Computer(self._client, r["vm_id"])
+
+    def run(self, command: str, *, session_id: str | int | None = None,
+            timeout: int | None = None) -> RunResult:
+        body: dict[str, Any] = {"command": command,
+                                "session_id": session_id if session_id is not None else (self._default_session or 0)}
+        if timeout is not None: body["timeout"] = timeout
+        r = self._client._request("POST", f"/api/v1/vms/{self.id}/run", body)
+        return RunResult(
+            stdout=_decode_stream(r.get("stdout"), r.get("stdout_encoding")),
+            stderr=_decode_stream(r.get("stderr"), r.get("stderr_encoding")),
+            exit_code=int(r.get("exit_code", 0)),
+            duration_ms=float(r.get("duration_ms", 0.0)),
+            session_id=str(r.get("session_id", "")),
+            cwd=str(r.get("cwd", "")),
+        )
+
+
+class Sync:
+    """File I/O for one VM. Routes through `/api/v1/vms/{id}/sync`. Hides
+    chunk-vs-presigned write strategy and inline-vs-presigned reads."""
+    def __init__(self, vm: Computer) -> None:
+        self._vm, self._client = vm, vm._client
+
+    def _path(self) -> str: return f"/api/v1/vms/{self._vm.id}/sync"
+
+    def read_file(self, path: str) -> bytes:
+        r = self._client._request("POST", self._path(), {"op": "read", "path": path})
+        if "content" in r:
+            c = r["content"]
+            return base64.b64decode(c) if r.get("encoding") == "base64" else c.encode("utf-8")
+        url = r.get("presigned_url")
+        if not url: raise ArkerError("internal", "read response missing content/presigned_url", 200)
+        with urllib.request.urlopen(url, timeout=300) as resp:
+            return resp.read()
+
+    def write_file(self, path: str, data: bytes | str) -> None:
+        if isinstance(data, str): data = data.encode("utf-8")
+        if not data: raise ArkerError("bad_request", "write_file: empty data", 400)
+        if len(data) <= CHUNK_SIZE:
+            self._fast_path(path, data)
+        else:
+            self._presigned(path, data)
+
+    def _fast_path(self, path: str, data: bytes) -> None:
+        """Single-chunk write for payloads ≤ CHUNK_SIZE: one round-trip,
+        bytes carried inline."""
+        size = len(data)
+        entry = {"path": path, "size": size, "upload_id": _ulid(),
+                 "start": 0, "end": size,
+                 "content": base64.b64encode(data).decode("ascii")}
+        result = self._send_one(entry)
+        if not (result.get("complete") and result.get("written")):
+            raise ArkerError("internal", "fast-path write returned without complete+written", 200)
+
+    def _presigned(self, path: str, data: bytes) -> None:
+        """> CHUNK_SIZE: request a signed upload URL, PUT bytes directly,
+        then commit. Bytes never pass through the API layer."""
+        size = len(data)
+        # Step 1 — request the signed URL.
+        e1 = self._send_one({"path": path, "size": size, "presigned": True})
+        url, upload_id = e1["presigned_url"], e1["upload_id"]
+        # Step 2 — direct PUT to the upload URL, retrying transient HTTP statuses.
+        for attempt in range(MAX_ATTEMPTS):
+            try:
+                req = urllib.request.Request(url, method="PUT", data=data)
+                with urllib.request.urlopen(req, timeout=600) as resp:
+                    if resp.status >= 400:
+                        raise urllib.error.HTTPError(url, resp.status, "fail", {}, None)
+                break
+            except urllib.error.HTTPError as e:
+                if e.code not in RETRYABLE_HTTP or attempt == MAX_ATTEMPTS - 1:
+                    raise ArkerError("internal", f"upload PUT failed: {e.code}", e.code)
+                time.sleep(BACKOFF_S * (2 ** attempt))
+        # Step 3 — commit.
+        self._send_one({"path": path, "size": size, "upload_id": upload_id})
+
+    def _send_one(self, entry: dict) -> dict:
+        """POST a single-entry write request, retrying transient
+        envelope-level errors (HTTP 200 with `error.code:"internal"` and
+        a throttling-style hint in the message)."""
+        last_err = None
+        for attempt in range(MAX_ATTEMPTS):
+            r = self._client._request("POST", self._path(), {"op": "write", "writes": [entry]})
+            result = (r.get("results") or [{}])[0]
+            err = result.get("error")
+            if not err: return result
+            last_err = err
+            if not _is_transient(err) or attempt == MAX_ATTEMPTS - 1: break
+            time.sleep(BACKOFF_S * (2 ** attempt) + secrets.randbelow(50) / 1000.0)
+        raise ArkerError(last_err.get("code", "internal"), last_err.get("message", ""), 200)

arker-0.1.0/tests/demo.py

@@ -0,0 +1,209 @@
+"""Live SDK demo: exercises every public method against the production
+deployment, printing what each call sends on the wire and the result.
+Doubles as smoke test and as documentation — if you wonder "what does
+`a.list(q='hello')` actually do?", look at the printed line and the
+returned data.
+
+Run:
+    ARKER_API_KEY=ark_live_... python sdk/python/tests/demo.py
+
+Exits 0 on full pass, 1 on any failure.
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import secrets
+import sys
+import time
+import urllib.request
+
+import arker
+from arker import Arker, ArkerError, Computer, RunResult, VmList, VmSummary
+
+API_KEY = os.environ.get("ARKER_API_KEY") or os.environ.get("AUTH_KEY")
+if not API_KEY:
+    print("ARKER_API_KEY is required", file=sys.stderr)
+    sys.exit(2)
+
+# ── Wire-level request tracing ─────────────────────────────────────────
+# Wrap urlopen so every HTTP call the SDK makes is printed verbatim.
+# This is what makes the demo double as documentation.
+_orig_urlopen = urllib.request.urlopen
+
+
+def _trace_urlopen(req, *args, **kwargs):
+    if hasattr(req, "full_url"):
+        method = req.get_method()
+        url = req.full_url
+        body_preview = ""
+        if req.data:
+            n = len(req.data)
+            body_preview = f"  ({n} byte body)" if n > 200 else f"  body={req.data[:200]!r}"
+        print(f"    → {method} {url}{body_preview}")
+    else:
+        print(f"    → GET {req}")
+    return _orig_urlopen(req, *args, **kwargs)
+
+
+urllib.request.urlopen = _trace_urlopen  # type: ignore[assignment]
+
+# ── Test harness ───────────────────────────────────────────────────────
+results: list[tuple[str, bool, str]] = []
+
+
+def section(title: str) -> None:
+    print(f"\n━━━ {title} ━━━")
+
+
+def check(name: str, ok: bool, detail: str = "") -> None:
+    results.append((name, ok, detail))
+    icon = "✅" if ok else "❌"
+    suffix = f"  [{detail}]" if detail else ""
+    print(f"  {icon} {name}{suffix}")
+
+
+# ── 0. Construct client ────────────────────────────────────────────────
+section("Arker(api_key=...)")
+print(f"  arker version: {arker.__version__}")
+arker_client = Arker(api_key=API_KEY)
+print(f"  default base_url: {arker_client._base_url}")
+check("client constructed", isinstance(arker_client, Arker))
+
+# ── 1. list() — paginated VMs (always hits arker.ai) ───────────────────
+section("arker_client.list(limit=5) — should hit https://arker.ai")
+page_before = arker_client.list(limit=5)
+check(
+    "returns VmList",
+    isinstance(page_before, VmList) and all(isinstance(item, VmSummary) for item in page_before),
+    f"total={page_before.total} items={len(page_before)}",
+)
+for summary in page_before.items[:3]:
+    print(f"     · {summary.vm_id}  name={summary.name!r}  region={summary.region}  created={summary.created_at}")
+
+# ── 2. vm() — open handle, no network call ─────────────────────────────
+section('arker_client.vm("arkuntu") — handle, no network call')
+arkuntu = arker_client.vm("arkuntu")
+check(
+    'arker_client.vm("arkuntu") returns Computer',
+    isinstance(arkuntu, Computer) and arkuntu.id == "arkuntu",
+    f"id={arkuntu.id!r}",
+)
+
+# ── 3. fork() — alias resolves client-side, hits regional endpoint by-id ─
+section('arkuntu.fork(name="demo") — alias resolved client-side')
+vm = arkuntu.fork(name="sdk-demo")
+check(
+    "fork returns Computer with new ULID id",
+    isinstance(vm, Computer) and vm.id != "arkuntu" and len(vm.id) >= 26,
+    f"vm.id={vm.id}",
+)
+
+try:
+    # ── 4. run(simple command) ─────────────────────────────────────────
+    section('vm.run("echo hello") — POST .../run')
+    run_result = vm.run("echo hello-from-sdk")
+    check(
+        "run returns RunResult",
+        isinstance(run_result, RunResult),
+        f"exit={run_result.exit_code} duration_ms={run_result.duration_ms:.0f}",
+    )
+    check("stdout matches", run_result.stdout == b"hello-from-sdk\n", f"stdout={run_result.stdout!r}")
+
+    # ── 5. write_file (small / fast path) ──────────────────────────────
+    section('vm.sync.write_file("/home/user/small.txt", b"...") — single call')
+    payload_small = b"hello-small-payload\n"
+    vm.sync.write_file("/home/user/small.txt", payload_small)
+    check("small write returned", True, f"{len(payload_small)} bytes")
+
+    # ── 6. read_file (small / inline) ──────────────────────────────────
+    section('vm.sync.read_file("/home/user/small.txt") — inline response')
+    back_small = vm.sync.read_file("/home/user/small.txt")
+    check("small round-trip", back_small == payload_small)
+
+    # ── 7. cat the file via run() — proves wire is consistent ──────────
+    section('vm.run("cat /home/user/small.txt") — same bytes via shell')
+    cat_result = vm.run("cat /home/user/small.txt")
+    check(
+        "shell sees the SDK-written file",
+        cat_result.exit_code == 0 and cat_result.stdout == payload_small,
+        f"stdout={cat_result.stdout!r}",
+    )
+
+    # ── 8. write_file (large / presigned bypass) ───────────────────────
+    section('vm.sync.write_file(big_blob)  — large payload uses presigned upload')
+    payload_big = secrets.token_bytes(8 * 1024 * 1024)  # 8 MiB → presigned bypass
+    t0 = time.monotonic()
+    vm.sync.write_file("/home/user/big.bin", payload_big)
+    check("8 MiB write returned", True, f"{(time.monotonic()-t0)*1000:.0f}ms")
+
+    # ── 9. read_file (large / inline, since 8 MiB still fits) ──────────
+    section('vm.sync.read_file(big_blob) — handles inline-or-presigned automatically')
+    t0 = time.monotonic()
+    back_big = vm.sync.read_file("/home/user/big.bin")
+    check(
+        "8 MiB round-trip integrity",
+        hashlib.sha256(back_big).digest() == hashlib.sha256(payload_big).digest(),
+        f"{(time.monotonic()-t0)*1000:.0f}ms, sha256 match",
+    )
+
+    # ── 10. fork from existing VM (non-alias path) ────────────────────
+    section('vm.fork(name="branch") — fork an existing VM')
+    child = vm.fork(name="sdk-demo-child")
+    check(
+        "child has new id",
+        isinstance(child, Computer) and child.id != vm.id,
+        f"child.id={child.id}",
+    )
+
+    # ── 11. child sees parent's filesystem ────────────────────────────
+    section('child.run("cat /home/user/small.txt") — child inherits parent state')
+    child_cat = child.run("cat /home/user/small.txt")
+    check(
+        "child sees parent's file",
+        child_cat.exit_code == 0 and child_cat.stdout == payload_small,
+        f"stdout={child_cat.stdout!r}",
+    )
+    child.delete()
+    check("child.delete() succeeded", True)
+
+    # ── 12. error path — read missing file raises ArkerError ──────────
+    section("error path: vm.sync.read_file('/home/user/does-not-exist.txt')")
+    try:
+        vm.sync.read_file("/home/user/does-not-exist.txt")
+        check("missing file raises ArkerError", False, "no exception raised")
+    except ArkerError as err:
+        check(
+            "ArkerError(not_found, status=404)",
+            err.code == "not_found" and err.status == 404,
+            f"code={err.code!r} status={err.status}",
+        )
+
+    # ── 13. list() shows our new VM ───────────────────────────────────
+    section('arker_client.list(q="sdk-demo") — filter shows the VMs we just made')
+    page_after = arker_client.list(q="sdk-demo")
+    check(
+        "list filters by name substring",
+        any(summary.vm_id == vm.id for summary in page_after),
+        f"total={page_after.total} matched",
+    )
+
+finally:
+    # ── 14. delete() — cleanup ────────────────────────────────────────
+    section("vm.delete() — cleanup")
+    try:
+        vm.delete()
+        check("vm.delete() succeeded", True)
+    except Exception as e:
+        check("vm.delete() succeeded", False, str(e))
+
+# ── Summary ────────────────────────────────────────────────────────────
+total = len(results)
+passed = sum(1 for _, ok, _ in results if ok)
+print(f"\n━━━ SUMMARY ━━━\n  {passed}/{total} passed")
+if passed != total:
+    print("  Failures:")
+    for name, ok, detail in results:
+        if not ok:
+            print(f"    × {name}  [{detail}]")
+sys.exit(0 if passed == total else 1)