tryorchard-sdk 0.0.1__py3-none-any.whl

orchard_sdk/__init__.py

@@ -0,0 +1,37 @@
+"""Orchard SDK — a Python client for the Orchard mobile-sandbox control plane.
+
+Quickstart::
+
+    from orchard_sdk import Orchard
+
+    orchard = Orchard.from_env()            # ORCHARD_API_URL + ORCHARD_API_KEY
+    for s in orchard.sandboxes.list()["instances"]:
+        print(s["name"], s["state"])
+
+    sb = orchard.sandbox("my-pixel")        # by uuid / uuid-prefix / name / tag
+    sb.tag("payments", "#22c55e")
+    with sb.logs() as stream:
+        for line in stream:
+            print(line)
+
+See https://docs.orchard.airoverflow.com for guides and the full API reference.
+"""
+from __future__ import annotations
+
+from ._bridge import LocalBridge
+from ._version import __version__
+from .client import Orchard
+from .config import Config, from_env
+from .errors import ApiError, ChannelClosedError, OrchardError, SelectorError
+
+__all__ = [
+    "Orchard",
+    "Config",
+    "from_env",
+    "OrchardError",
+    "ApiError",
+    "SelectorError",
+    "ChannelClosedError",
+    "LocalBridge",
+    "__version__",
+]

orchard_sdk/_bridge.py

@@ -0,0 +1,121 @@
+"""A local TCP listener bridged to a device WebSocket channel (adb, vnc, screen).
+
+This lets ordinary local tools reach a sandbox as if it were plugged in: the
+bridge opens a port and, for each TCP connection, opens a fresh channel to the
+device and pumps bytes both ways. So ``adb connect 127.0.0.1:<port>`` talks to
+the sandbox's adb, and a VNC viewer to its screen.
+
+It runs its own asyncio loop on a daemon thread, like :class:`SyncChannel`.
+"""
+from __future__ import annotations
+
+import asyncio
+import threading
+from typing import Any
+
+from . import _ws
+from .config import Config
+
+
+class LocalBridge:
+    """A local ``host:port`` listener forwarding to a device channel. Start it
+    (or use it as a context manager); read :attr:`port`; :meth:`close` when done.
+
+    >>> with sandbox.adb_bridge() as b:
+    ...     os.system(f"adb connect 127.0.0.1:{b.port}")
+    """
+
+    def __init__(self, cfg: Config, uuid: str, suffix: str, host: str = "127.0.0.1",
+                 port: int = 0, **params: Any):
+        self._url = _ws.ws_url(cfg, uuid, suffix, **params)
+        self.host = host
+        self._req_port = port
+        #: The bound local port (set once started; the OS picks one if port was 0).
+        self.port = 0
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+        self._server: asyncio.AbstractServer | None = None
+        self._ready = threading.Event()
+        self._err: BaseException | None = None
+
+    def start(self) -> "LocalBridge":
+        """Open the listener and return self once it is bound."""
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+        if not self._ready.wait(timeout=15):
+            raise RuntimeError("bridge did not start within 15s")
+        if self._err is not None:
+            raise self._err
+        return self
+
+    def __enter__(self) -> "LocalBridge":
+        return self.start()
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _run(self) -> None:
+        self._loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(self._loop)
+        try:
+            self._loop.run_until_complete(self._serve())
+        except BaseException as e:   # surfaced to start() via _ready/_err
+            self._err = e
+            self._ready.set()
+        finally:
+            self._loop.close()
+
+    async def _serve(self) -> None:
+        self._server = await asyncio.start_server(self._handle, self.host, self._req_port)
+        self.port = self._server.sockets[0].getsockname()[1]
+        self._ready.set()
+        async with self._server:
+            await self._server.serve_forever()
+
+    async def _handle(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        try:
+            async with _ws.connect(self._url) as ws:
+                await self._pump(ws, reader, writer)
+        except Exception:
+            with _suppress():
+                writer.close()
+
+    @staticmethod
+    async def _pump(ws: Any, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        async def to_ws() -> None:
+            try:
+                while chunk := await reader.read(65536):
+                    await ws.send(chunk)
+            except Exception:
+                pass
+            finally:
+                with _suppress():
+                    await ws.close()
+
+        async def to_local() -> None:
+            try:
+                async for msg in ws:
+                    writer.write(msg if isinstance(msg, (bytes, bytearray)) else msg.encode())
+                    await writer.drain()
+            except Exception:
+                pass
+            finally:
+                with _suppress():
+                    writer.close()
+
+        await asyncio.gather(to_ws(), to_local(), return_exceptions=True)
+
+    def close(self) -> None:
+        """Stop the listener and join the worker thread."""
+        if self._loop is not None and self._loop.is_running():
+            self._loop.call_soon_threadsafe(self._loop.stop)
+        if self._thread is not None:
+            self._thread.join(timeout=5)
+
+
+class _suppress:
+    def __enter__(self) -> None:
+        return None
+
+    def __exit__(self, *exc: object) -> bool:
+        return True   # swallow any exception in the with-body

orchard_sdk/_channels.py

@@ -0,0 +1,191 @@
+"""Synchronous wrappers over the async WebSocket core.
+
+:class:`SyncChannel` lets ordinary (non-asyncio) code consume a live channel as
+a plain iterator::
+
+    with sandbox.logs() as stream:
+        for line in stream:
+            print(line)
+
+It runs a private asyncio loop on a daemon thread, pushes decoded frames onto a
+queue, and shuts the loop down cleanly when the ``with`` block exits — including
+on ``break`` or Ctrl-C. :class:`Tunnel` drives the reverse-tunnel control channel.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+from queue import Queue
+from typing import Any, Callable, Iterator
+
+from . import _ws
+from .config import Config
+
+_SENTINEL = object()
+
+
+class SyncChannel:
+    """A live WebSocket channel exposed as a context-managed, synchronous iterator.
+
+    Args:
+        url: The fully-built channel URL (see :func:`orchard_sdk._ws.ws_url`).
+        decode: Per-frame decoder (text/json/bytes). Defaults to text.
+
+    The channel is lazy: the socket opens on ``__enter__`` and closes on
+    ``__exit__``. Iterating yields decoded frames until the stream ends or the
+    block is left. ``send()`` pushes data upstream (e.g. shell keystrokes).
+    """
+
+    def __init__(self, url: str, decode: Callable[[str | bytes], Any] = _ws.decode_text,
+                 queue_max: int = 0, open_send: str | bytes | None = None):
+        self._url = url
+        self._decode = decode
+        self._open_send = open_send
+        self._queue: "Queue[Any]" = Queue(maxsize=queue_max)
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+        self._ws: Any = None
+        self._stop = False
+        self._exc: BaseException | None = None
+
+    # -- lifecycle --------------------------------------------------------
+    def __enter__(self) -> "SyncChannel":
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _run(self) -> None:
+        self._loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(self._loop)
+        try:
+            self._loop.run_until_complete(self._pump())
+        except BaseException as e:  # surfaced to the consumer thread via the queue
+            self._exc = e
+        finally:
+            self._queue.put(_SENTINEL)
+            self._loop.close()
+
+    async def _pump(self) -> None:
+        async with _ws.connect(self._url) as ws:
+            self._ws = ws
+            if self._open_send is not None:   # e.g. a frida script sent on connect
+                await ws.send(self._open_send)
+            try:
+                async for frame in ws:
+                    if self._stop:
+                        break
+                    self._queue.put(self._decode(frame))
+            except Exception as e:  # ConnectionClosed w/ error code → re-raised to consumer
+                import websockets
+                if isinstance(e, websockets.ConnectionClosed):
+                    err = _ws._closed_err(e)
+                    if err is not None:
+                        raise err from None
+                elif not self._stop:
+                    raise
+
+    # -- consumer API -----------------------------------------------------
+    def __iter__(self) -> Iterator[Any]:
+        while True:
+            item = self._queue.get()
+            if item is _SENTINEL:
+                if self._exc is not None:
+                    raise self._exc
+                return
+            yield item
+
+    def send(self, data: str | bytes) -> None:
+        """Send a frame upstream (e.g. a shell keystroke or a resize JSON)."""
+        if self._loop is None or self._ws is None:
+            raise RuntimeError("channel not open")
+        fut = asyncio.run_coroutine_threadsafe(self._ws.send(data), self._loop)
+        fut.result(timeout=10)
+
+    def close(self) -> None:
+        """Stop the stream and join the worker thread."""
+        self._stop = True
+        if self._ws is not None and self._loop is not None and self._loop.is_running():
+            try:
+                asyncio.run_coroutine_threadsafe(self._ws.close(), self._loop).result(timeout=5)
+            except Exception:
+                pass
+        if self._thread is not None:
+            self._thread.join(timeout=5)
+
+
+class Tunnel:
+    """The reverse-tunnel control channel: forwards guest proxy connections into a
+    local proxy you run (Burp/mitmproxy). Context-managed; blocks in :meth:`run`.
+    """
+
+    def __init__(self, cfg: Config, uuid: str, to_host: str, to_port: int):
+        self._cfg = cfg
+        self._uuid = uuid
+        self._to = (to_host, to_port)
+
+    def run(self, on_event: Callable[[str, str], None] | None = None) -> int:
+        """Hold the tunnel open until the server closes it. ``on_event(level, text)``
+        receives ``ready``/``open``/``warn``/``error``/``close`` notifications."""
+        log = on_event or (lambda level, text: None)
+        return asyncio.run(self._run(log))
+
+    async def _run(self, log: Callable[[str, str], None]) -> int:
+        tasks: set[asyncio.Task] = set()
+        to_host, to_port = self._to
+
+        async def data(sid: str) -> None:
+            try:
+                async with _ws.connect(_ws.ws_url(self._cfg, self._uuid, "tunnel/data", sid=sid)) as ws:
+                    reader, writer = await asyncio.open_connection(to_host, to_port)
+                    await _pump(ws, reader, writer)
+            except Exception as e:
+                log("warn", f"stream {sid[:8]} ended: {e}")
+
+        async with _ws.connect(_ws.ws_url(self._cfg, self._uuid, "tunnel")) as control:
+            async for raw in control:
+                try:
+                    msg = json.loads(raw)
+                except Exception:
+                    continue
+                t = msg.get("t")
+                if t == "ready":
+                    log("ready", f"guest proxy -> {msg.get('proxy_target')}")
+                elif t == "open":
+                    task = asyncio.create_task(data(msg["sid"]))
+                    tasks.add(task)
+                    task.add_done_callback(tasks.discard)
+                elif t == "warn":
+                    log("warn", msg.get("detail", ""))
+                elif t == "error":
+                    log("error", msg.get("detail", "tunnel refused"))
+                    return 1
+                elif t == "close":
+                    log("close", "closed by server")
+                    return 0
+        return 0
+
+
+async def _pump(ws: Any, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+    async def to_ws() -> None:
+        try:
+            while chunk := await reader.read(65536):
+                await ws.send(chunk)
+        finally:
+            await ws.close()
+
+    async def to_local() -> None:
+        try:
+            async for msg in ws:
+                writer.write(msg if isinstance(msg, (bytes, bytearray)) else msg.encode())
+                await writer.drain()
+        finally:
+            try:
+                writer.close()
+            except Exception:
+                pass
+
+    await asyncio.gather(to_ws(), to_local(), return_exceptions=True)

orchard_sdk/_http.py

@@ -0,0 +1,100 @@
+"""The sync REST transport: one httpx client that knows Orchard's base URL,
+auth header, tenancy headers, and how a server error becomes an :class:`ApiError`.
+
+Internal — consumers use :class:`orchard_sdk.Orchard` and its resource namespaces,
+not this class directly.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from .config import Config
+from .errors import ApiError
+
+
+def _detail(r: httpx.Response) -> str:
+    try:
+        body = r.json()
+    except Exception:
+        return r.text[:300].strip()
+    if isinstance(body, dict):
+        return str(body.get("detail") or body)
+    return str(body)
+
+
+class HttpClient:
+    """Thin synchronous wrapper over ``httpx.Client`` scoped to one Orchard org/workspace."""
+
+    def __init__(self, cfg: Config):
+        self.cfg = cfg
+        headers = {"Authorization": f"Bearer {cfg.token}"}
+        if cfg.org:
+            headers["X-Orchard-Org"] = cfg.org
+        if cfg.ws:
+            headers["X-Orchard-Workspace"] = cfg.ws
+        self._c = httpx.Client(base_url=cfg.api_base, headers=headers, timeout=cfg.timeout)
+
+    def close(self) -> None:
+        self._c.close()
+
+    def __enter__(self) -> "HttpClient":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _request(self, method: str, path: str, **kw: Any) -> Any:
+        r = self._c.request(method, path, **kw)
+        if r.status_code >= 400:
+            raise ApiError(r.status_code, _detail(r))
+        if r.status_code == 204 or not r.content:
+            return None
+        return r.json()
+
+    def get(self, path: str, **kw: Any) -> Any:
+        return self._request("GET", path, **kw)
+
+    def get_content(self, path: str, **kw: Any) -> bytes:
+        """A GET whose body is raw bytes (screenshots, mitm CA)."""
+        r = self._c.request("GET", path, **kw)
+        if r.status_code >= 400:
+            raise ApiError(r.status_code, _detail(r))
+        return r.content
+
+    def post(self, path: str, json: Any = None, **kw: Any) -> Any:
+        return self._request("POST", path, json=json, **kw)
+
+    def patch(self, path: str, json: Any = None, **kw: Any) -> Any:
+        return self._request("PATCH", path, json=json, **kw)
+
+    def delete(self, path: str, **kw: Any) -> Any:
+        return self._request("DELETE", path, **kw)
+
+    def post_files(self, path: str, files: list[tuple[str, Path]],
+                   data: dict[str, Any] | None = None) -> Any:
+        """multipart POST (APK/IPA install, file upload). ``files`` is ``[(field, Path)]``."""
+        handles = [(field, (p.name, p.open("rb"))) for field, p in files]
+        try:
+            return self._request("POST", path, files=handles, data=data or {})
+        finally:
+            for _, (_, fh) in handles:
+                fh.close()
+
+    def download(self, absolute_url: str, dest: Path) -> int:
+        """Stream a signed-grant URL (full URL incl. ``?token=``) to a file.
+
+        The grant is itself the credential, so this request carries **no**
+        Authorization header. Returns the number of bytes written.
+        """
+        total = 0
+        with httpx.Client(timeout=300.0) as raw, raw.stream("GET", absolute_url) as r:
+            if r.status_code >= 400:
+                raise ApiError(r.status_code, _detail(r))
+            with dest.open("wb") as fh:
+                for chunk in r.iter_bytes(65536):
+                    fh.write(chunk)
+                    total += len(chunk)
+        return total

orchard_sdk/_version.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

orchard_sdk/_ws.py

@@ -0,0 +1,92 @@
+"""Async WebSocket core: URL assembly + a decoded frame iterator.
+
+A *channel* is one of Orchard's per-sandbox WebSocket streams (logs, shell,
+screen, adb, vnc, mitm, …). Frames arrive as text or binary depending on the
+channel; :func:`channel` decodes each frame with the caller-supplied ``decode``.
+Used directly by :mod:`orchard_sdk.aio`; :mod:`orchard_sdk._channels` wraps it
+for synchronous callers.
+"""
+from __future__ import annotations
+
+import json as _json
+from typing import Any, AsyncIterator, Callable
+from urllib.parse import urlencode
+
+import websockets
+
+from .config import Config
+from .errors import ChannelClosedError
+
+# Close codes the control plane emits.
+_ERR_CODES = {4401, 4403, 4404, 4502}
+
+
+def _closed_err(exc: "websockets.ConnectionClosed") -> ChannelClosedError | None:
+    """Map a ConnectionClosed to a ChannelClosedError when the code is an Orchard
+    error code, else None (a normal end-of-stream). Reads the close frame
+    directly to avoid the deprecated ``.code``/``.reason`` shims."""
+    frame = getattr(exc, "rcvd", None) or getattr(exc, "sent", None)
+    code = frame.code if frame is not None else 1006
+    if code in _ERR_CODES:
+        return ChannelClosedError(code, (frame.reason if frame is not None else "") or "")
+    return None
+
+
+def ws_url(cfg: Config, uuid: str, suffix: str, **extra: Any) -> str:
+    """Build ``wss?://host/ws/sandboxes/<uuid>/<suffix>?token=…`` with auth + extras.
+
+    ``extra`` values that are ``None`` are omitted (e.g. ``sid=None``).
+    """
+    q: dict[str, Any] = {"token": cfg.token}
+    if cfg.org:
+        q["org"] = cfg.org
+    if cfg.ws:
+        q["ws"] = cfg.ws
+    q.update({k: v for k, v in extra.items() if v is not None})
+    return f"{cfg.ws_base}/ws/sandboxes/{uuid}/{suffix}?{urlencode(q)}"
+
+
+def raw_ws_url(cfg: Config, path: str, **extra: Any) -> str:
+    """Build a WS URL for a non-sandbox path (e.g. ``ws/jobs/…``, ``ws/remote/…``)."""
+    q: dict[str, Any] = {"token": cfg.token}
+    if cfg.org:
+        q["org"] = cfg.org
+    if cfg.ws:
+        q["ws"] = cfg.ws
+    q.update({k: v for k, v in extra.items() if v is not None})
+    return f"{cfg.ws_base}/{path.lstrip('/')}?{urlencode(q)}"
+
+
+def connect(url: str):
+    """Open a client connection with the raw-transport settings binary channels need."""
+    return websockets.connect(url, max_size=None, open_timeout=15)
+
+
+def decode_text(frame: str | bytes) -> str:
+    return frame if isinstance(frame, str) else frame.decode(errors="replace")
+
+
+def decode_json(frame: str | bytes) -> Any:
+    return _json.loads(frame)
+
+
+def decode_bytes(frame: str | bytes) -> bytes:
+    return frame if isinstance(frame, (bytes, bytearray)) else frame.encode()
+
+
+async def channel(url: str, decode: Callable[[str | bytes], Any] = decode_text
+                  ) -> AsyncIterator[Any]:
+    """Async-iterate decoded frames from ``url`` until the socket closes cleanly.
+
+    Raises :class:`ChannelClosedError` if the server closes with an error code
+    (4401/4403/4404/4502).
+    """
+    async with connect(url) as ws:
+        try:
+            async for frame in ws:
+                yield decode(frame)
+        except websockets.ConnectionClosed as exc:
+            err = _closed_err(exc)
+            if err is not None:
+                raise err from None
+            # 1000/1001/etc. are a normal end-of-stream.

orchard_sdk/aio/__init__.py

@@ -0,0 +1,6 @@
+"""Asyncio-native WebSocket channels. REST stays synchronous on
+:class:`orchard_sdk.Orchard`; this exposes the async channel iterators."""
+from .._ws import channel
+from .channels import AsyncChannels
+
+__all__ = ["AsyncChannels", "channel"]

orchard_sdk/aio/channels.py

@@ -0,0 +1,57 @@
+"""Async WebSocket channels for asyncio callers.
+
+The synchronous :class:`orchard_sdk.resources.sandboxes.Sandbox` channels wrap
+these behind a thread. If you are already in an event loop, use these directly::
+
+    import asyncio
+    from orchard_sdk import from_env
+    from orchard_sdk.aio import AsyncChannels
+
+    async def main():
+        cfg = from_env()
+        async for line in AsyncChannels(cfg, "<uuid>").logs():
+            print(line)
+
+    asyncio.run(main())
+"""
+from __future__ import annotations
+
+from typing import Any, AsyncIterator
+
+from .. import _ws
+from ..config import Config
+
+
+class AsyncChannels:
+    """Async-iterable live channels for one sandbox uuid."""
+
+    def __init__(self, cfg: Config, uuid: str):
+        self._cfg = cfg
+        self._uuid = uuid
+
+    def _url(self, suffix: str, **extra: Any) -> str:
+        return _ws.ws_url(self._cfg, self._uuid, suffix, **extra)
+
+    def logs(self) -> AsyncIterator[str]:
+        """Async-iterate log lines."""
+        return _ws.channel(self._url("logs"), _ws.decode_text)
+
+    def shell(self) -> AsyncIterator[str]:
+        """Async-iterate shell output (read-only here; use the raw socket to send)."""
+        return _ws.channel(self._url("shell"), _ws.decode_text)
+
+    def screen(self, source: str = "scrcpy") -> AsyncIterator[bytes]:
+        """Async-iterate raw screen frames."""
+        return _ws.channel(self._url("screen/stream", source=source), _ws.decode_bytes)
+
+    def adb(self) -> AsyncIterator[bytes]:
+        """Async-iterate raw adb transport bytes."""
+        return _ws.channel(self._url("adb"), _ws.decode_bytes)
+
+    def vnc(self) -> AsyncIterator[bytes]:
+        """Async-iterate raw RFB bytes (iOS VM)."""
+        return _ws.channel(self._url("vnc"), _ws.decode_bytes)
+
+    def mitm_flows(self) -> AsyncIterator[Any]:
+        """Async-iterate captured flow summaries (decoded JSON)."""
+        return _ws.channel(self._url("mitm/flows"), _ws.decode_json)