@magpiecloud/mags 1.8.14 → 1.8.16

package/python/src/mags/client.py

@@ -1,523 +0,0 @@
-"""Mags client for interacting with the Magpie VM infrastructure API."""
-
-from __future__ import annotations
-
-import os
-import time
-from pathlib import Path
-from typing import Any, Dict, List, Optional
-
-import requests
-
-
-class MagsError(Exception):
-    """Raised when the Mags API returns an error."""
-
-    def __init__(self, message: str, status_code: int | None = None):
-        super().__init__(message)
-        self.status_code = status_code
-
-
-class Mags:
-    """Client for the Mags API.
-
-    Args:
-        api_token: API token. Falls back to ``MAGS_API_TOKEN`` or ``MAGS_TOKEN`` env vars.
-        api_url: API base URL. Falls back to ``MAGS_API_URL`` env var or
-            ``https://api.magpiecloud.com``.
-        timeout: Default request timeout in seconds.
-    """
-
-    def __init__(
-        self,
-        api_token: str | None = None,
-        api_url: str | None = None,
-        timeout: int = 30,
-    ):
-        self.api_url = (
-            api_url
-            or os.environ.get("MAGS_API_URL")
-            or "https://api.magpiecloud.com"
-        ).rstrip("/")
-
-        self.api_token = (
-            api_token
-            or os.environ.get("MAGS_API_TOKEN")
-            or os.environ.get("MAGS_TOKEN")
-        )
-        if not self.api_token:
-            raise MagsError(
-                "API token required. Set MAGS_API_TOKEN env var or pass api_token."
-            )
-
-        self.timeout = timeout
-        self._session = requests.Session()
-        self._session.headers.update(
-            {
-                "Authorization": f"Bearer {self.api_token}",
-                "Content-Type": "application/json",
-            }
-        )
-
-    # ── helpers ──────────────────────────────────────────────────────
-
-    def _request(
-        self,
-        method: str,
-        path: str,
-        json: Any = None,
-        params: dict | None = None,
-        timeout: int | None = None,
-    ) -> Any:
-        url = f"{self.api_url}/api/v1{path}"
-        resp = self._session.request(
-            method,
-            url,
-            json=json,
-            params=params,
-            timeout=timeout or self.timeout,
-        )
-        if resp.status_code >= 400:
-            try:
-                body = resp.json()
-                msg = body.get("error") or body.get("message") or resp.text
-            except Exception:
-                msg = resp.text
-            raise MagsError(msg, status_code=resp.status_code)
-        if not resp.content:
-            return {}
-        return resp.json()
-
-    # ── jobs ─────────────────────────────────────────────────────────
-
-    def run(
-        self,
-        script: str,
-        *,
-        name: str | None = None,
-        workspace_id: str | None = None,
-        base_workspace_id: str | None = None,
-        persistent: bool = False,
-        no_sleep: bool = False,
-        ephemeral: bool = False,
-        startup_command: str | None = None,
-        environment: Dict[str, str] | None = None,
-        file_ids: List[str] | None = None,
-        disk_gb: int | None = None,
-        no_sync: bool = False,
-    ) -> dict:
-        """Submit a job for execution.
-
-        Args:
-            script: Shell script to execute inside the VM.
-            name: Optional job name.
-            workspace_id: Persistent workspace name (synced to S3).
-            base_workspace_id: Read-only base workspace to mount.
-            persistent: Keep VM alive after script finishes.
-            no_sleep: Never auto-sleep this VM (requires persistent=True).
-                The VM stays running 24/7 and auto-recovers if its host goes down.
-            ephemeral: No S3 sync (faster, truly ephemeral).
-            startup_command: Command to run when VM wakes from sleep.
-            environment: Key-value env vars injected into the VM.
-            file_ids: File IDs to download into VM before script runs.
-            disk_gb: Custom disk size in GB (default 2GB).
-            no_sync: Skip S3 sync, use local disk only.
-
-        Returns ``{"request_id": ..., "status": "accepted"}``.
-        """
-        if ephemeral and workspace_id:
-            raise MagsError("Cannot use ephemeral with workspace_id")
-        if ephemeral and persistent:
-            raise MagsError("Cannot use ephemeral with persistent")
-        if no_sleep and not persistent:
-            raise MagsError("no_sleep requires persistent=True")
-
-        payload = {
-            "script": script,
-            "type": "inline",
-            "persistent": persistent,
-        }
-        if no_sleep:
-            payload["no_sleep"] = True
-        if no_sync:
-            payload["no_sync"] = True
-        if name:
-            payload["name"] = name
-        if not ephemeral and workspace_id:
-            payload["workspace_id"] = workspace_id
-        if base_workspace_id:
-            payload["base_workspace_id"] = base_workspace_id
-        if startup_command:
-            payload["startup_command"] = startup_command
-        if environment:
-            payload["environment"] = environment
-        if file_ids:
-            payload["file_ids"] = file_ids
-        if disk_gb:
-            payload["disk_gb"] = disk_gb
-
-        return self._request("POST", "/mags-jobs", json=payload)
-
-    def run_and_wait(
-        self,
-        script: str,
-        *,
-        timeout: float = 60.0,
-        poll_interval: float = 1.0,
-        **run_kwargs: Any,
-    ) -> dict:
-        """Submit a job and block until it completes or times out.
-
-        Returns a dict with ``request_id``, ``status``, ``exit_code``,
-        ``duration_ms``, and ``logs``.
-        """
-        result = self.run(script, **run_kwargs)
-        request_id = result["request_id"]
-
-        deadline = time.monotonic() + timeout
-        while time.monotonic() < deadline:
-            status = self.status(request_id)
-            if status["status"] in ("completed", "error"):
-                logs_resp = self.logs(request_id)
-                return {
-                    "request_id": request_id,
-                    "status": status["status"],
-                    "exit_code": status.get("exit_code", 0),
-                    "duration_ms": status.get("script_duration_ms", 0),
-                    "logs": logs_resp.get("logs", []),
-                }
-            time.sleep(poll_interval)
-
-        raise MagsError(f"Job {request_id} timed out after {timeout}s")
-
-    def status(self, request_id: str) -> dict:
-        """Get the status of a job."""
-        return self._request("GET", f"/mags-jobs/{request_id}/status")
-
-    def logs(self, request_id: str) -> dict:
-        """Get logs for a job. Returns ``{"logs": [...]}`."""
-        return self._request("GET", f"/mags-jobs/{request_id}/logs")
-
-    def list_jobs(self, *, page: int = 1, page_size: int = 20) -> dict:
-        """List recent jobs. Returns ``{"jobs": [...], "total": N, ...}``."""
-        return self._request(
-            "GET", "/mags-jobs", params={"page": page, "page_size": page_size}
-        )
-
-    def update_job(
-        self,
-        request_id: str,
-        *,
-        startup_command: str | None = None,
-        no_sleep: bool | None = None,
-    ) -> dict:
-        """Update a job's settings.
-
-        Args:
-            request_id: The job/workspace ID to update.
-            startup_command: Command to run when VM wakes from sleep.
-            no_sleep: If True, VM never auto-sleeps. If False, re-enables auto-sleep.
-        """
-        payload: dict = {}
-        if startup_command is not None:
-            payload["startup_command"] = startup_command
-        if no_sleep is not None:
-            payload["no_sleep"] = no_sleep
-        return self._request("PATCH", f"/mags-jobs/{request_id}", json=payload)
-
-    def enable_access(self, request_id: str, *, port: int = 8080) -> dict:
-        """Enable external access (URL or SSH) for a persistent job's VM.
-
-        Use ``port=22`` for SSH access, or ``port=8080`` (default) for HTTP/URL access.
-        """
-        return self._request(
-            "POST", f"/mags-jobs/{request_id}/access", json={"port": port}
-        )
-
-    def stop(self, name_or_id: str) -> dict:
-        """Stop a running job.
-
-        Accepts a job ID, job name, or workspace ID.
-        """
-        request_id = self._resolve_job_id(name_or_id)
-        return self._request("POST", f"/mags-jobs/{request_id}/stop")
-
-    def resize(
-        self,
-        workspace: str,
-        disk_gb: int,
-        *,
-        timeout: float = 30.0,
-        poll_interval: float = 1.0,
-    ) -> dict:
-        """Resize a workspace's disk. Stops the existing VM, then creates a new one.
-
-        Workspace files are preserved in S3.
-        Returns ``{"request_id": ..., "status": "running"}``.
-        """
-        existing = self.find_job(workspace)
-        if existing and existing.get("status") == "running":
-            self._request("POST", f"/mags-jobs/{existing['request_id']}/sync")
-            self._request("POST", f"/mags-jobs/{existing['request_id']}/stop")
-            time.sleep(1)
-        elif existing and existing.get("status") == "sleeping":
-            self._request("POST", f"/mags-jobs/{existing['request_id']}/stop")
-            time.sleep(1)
-
-        return self.new(workspace, persistent=True, disk_gb=disk_gb,
-                        timeout=timeout, poll_interval=poll_interval)
-
-    def new(
-        self,
-        name: str,
-        *,
-        persistent: bool = False,
-        base_workspace_id: str | None = None,
-        disk_gb: int | None = None,
-        timeout: float = 30.0,
-        poll_interval: float = 1.0,
-    ) -> dict:
-        """Create a new VM sandbox and wait until it's running.
-
-        By default, data lives on local disk only (no S3 sync).
-        Pass ``persistent=True`` to enable S3 data persistence.
-
-        Equivalent to ``mags new <name>`` or ``mags new <name> -p``.
-
-        Returns ``{"request_id": ..., "status": "running"}``.
-        """
-        result = self.run(
-            "sleep infinity",
-            workspace_id=name,
-            persistent=True,
-            no_sync=not persistent,
-            base_workspace_id=base_workspace_id,
-            disk_gb=disk_gb,
-        )
-        request_id = result["request_id"]
-
-        deadline = time.monotonic() + timeout
-        while time.monotonic() < deadline:
-            st = self.status(request_id)
-            if st["status"] == "running" and st.get("vm_id"):
-                return {"request_id": request_id, "status": "running"}
-            if st["status"] in ("completed", "error"):
-                raise MagsError(f"Job {request_id} ended unexpectedly: {st['status']}")
-            time.sleep(poll_interval)
-
-        raise MagsError(f"Job {request_id} did not start within {timeout}s")
-
-    def find_job(self, name_or_id: str) -> dict | None:
-        """Find a running or sleeping job by name, workspace ID, or job ID.
-
-        Uses the same resolution priority as the CLI:
-        running/sleeping exact name → workspace ID → any status exact name.
-        Returns the job dict or ``None``.
-        """
-        jobs = self.list_jobs(page_size=50).get("jobs", [])
-
-        # Priority 1: exact name match, running/sleeping
-        for j in jobs:
-            if j.get("name") == name_or_id and j.get("status") in ("running", "sleeping"):
-                return j
-
-        # Priority 2: workspace_id match, running/sleeping
-        for j in jobs:
-            if j.get("workspace_id") == name_or_id and j.get("status") in ("running", "sleeping"):
-                return j
-
-        # Priority 3: exact name match, any status
-        for j in jobs:
-            if j.get("name") == name_or_id:
-                return j
-
-        # Priority 4: workspace_id match, any status
-        for j in jobs:
-            if j.get("workspace_id") == name_or_id:
-                return j
-
-        return None
-
-    def url(self, name_or_id: str, *, port: int = 8080) -> dict:
-        """Enable public URL access for a job's VM.
-
-        Accepts a job ID, job name, or workspace ID.
-        Returns dict with ``url`` and access details.
-        """
-        request_id = self._resolve_job_id(name_or_id)
-        st = self.status(request_id)
-        resp = self.enable_access(request_id, port=port)
-        subdomain = st.get("subdomain") or resp.get("subdomain")
-        if subdomain:
-            resp["url"] = f"https://{subdomain}.apps.magpiecloud.com"
-        return resp
-
-    def exec(self, name_or_id: str, command: str, *, timeout: int = 30) -> dict:
-        """Execute a command on an existing running/sleeping sandbox.
-
-        Equivalent to ``mags exec <workspace> '<command>'``.
-
-        Returns ``{"exit_code": int, "output": str, "stderr": str}``.
-        """
-        job = self.find_job(name_or_id)
-        if not job:
-            raise MagsError(f"No running or sleeping VM found for '{name_or_id}'")
-        if job["status"] not in ("running", "sleeping"):
-            raise MagsError(
-                f"VM for '{name_or_id}' is {job['status']}, needs to be running or sleeping"
-            )
-
-        request_id = job.get("request_id") or job.get("id")
-        resp = self._request(
-            "POST",
-            f"/mags-jobs/{request_id}/exec",
-            json={"command": command, "timeout": timeout},
-            timeout=timeout + 10,  # HTTP timeout > command timeout
-        )
-        return {
-            "exit_code": resp.get("exit_code", -1),
-            "output": resp.get("stdout", ""),
-            "stderr": resp.get("stderr", ""),
-        }
-
-    def usage(self, *, window_days: int = 30) -> dict:
-        """Get aggregated usage summary."""
-        return self._request(
-            "GET", "/mags-jobs/usage", params={"window_days": window_days}
-        )
-
-    # ── internal helpers ─────────────────────────────────────────────
-
-    def _resolve_job_id(self, name_or_id: str) -> str:
-        """Resolve a job name, workspace ID, or UUID to a request_id."""
-        # If it looks like a UUID, use directly
-        if len(name_or_id) >= 32 and "-" in name_or_id:
-            return name_or_id
-        job = self.find_job(name_or_id)
-        if not job:
-            raise MagsError(f"No job found for '{name_or_id}'")
-        return job.get("request_id") or job.get("id")
-
-    # ── file uploads ─────────────────────────────────────────────────
-
-    def upload_file(self, file_path: str) -> str:
-        """Upload a single file. Returns the file ID."""
-        p = Path(file_path)
-        if not p.exists():
-            raise MagsError(f"File not found: {file_path}")
-
-        url = f"{self.api_url}/api/v1/mags-files"
-        # Use a fresh request without the JSON content-type
-        resp = requests.post(
-            url,
-            files={"file": (p.name, p.read_bytes(), "application/octet-stream")},
-            headers={"Authorization": f"Bearer {self.api_token}"},
-            timeout=self.timeout,
-        )
-        if resp.status_code >= 400:
-            raise MagsError(resp.text, status_code=resp.status_code)
-        data = resp.json()
-        file_id = data.get("file_id")
-        if not file_id:
-            raise MagsError(f"Upload failed for {p.name}: {data}")
-        return file_id
-
-    def upload_files(self, file_paths: List[str]) -> List[str]:
-        """Upload multiple files. Returns a list of file IDs."""
-        return [self.upload_file(fp) for fp in file_paths]
-
-    # ── workspaces ────────────────────────────────────────────────────
-
-    def list_workspaces(self) -> dict:
-        """List all workspaces. Returns ``{"workspaces": [...], "total": N}``."""
-        return self._request("GET", "/mags-workspaces")
-
-    def delete_workspace(self, workspace_id: str) -> dict:
-        """Delete a workspace and all its stored data.
-
-        This permanently removes the workspace filesystem from S3.
-        Active jobs using the workspace must be stopped first.
-        """
-        return self._request("DELETE", f"/mags-workspaces/{workspace_id}")
-
-    def sync(self, request_id: str) -> dict:
-        """Sync a running job's workspace to S3 without stopping the VM.
-
-        Use this to persist workspace changes immediately, e.g. after
-        setting up a base image.
-        """
-        return self._request("POST", f"/mags-jobs/{request_id}/sync")
-
-    # ── cron jobs ────────────────────────────────────────────────────
-
-    def cron_create(
-        self,
-        *,
-        name: str,
-        cron_expression: str,
-        script: str,
-        workspace_id: str | None = None,
-        environment: Dict[str, str] | None = None,
-        persistent: bool = False,
-    ) -> dict:
-        """Create a scheduled cron job."""
-        payload = {
-            "name": name,
-            "cron_expression": cron_expression,
-            "script": script,
-            "persistent": persistent,
-        }
-        if workspace_id:
-            payload["workspace_id"] = workspace_id
-        if environment:
-            payload["environment"] = environment
-        return self._request("POST", "/mags-cron", json=payload)
-
-    def cron_list(self) -> dict:
-        """List all cron jobs."""
-        return self._request("GET", "/mags-cron")
-
-    def cron_get(self, cron_id: str) -> dict:
-        """Get a cron job by ID."""
-        return self._request("GET", f"/mags-cron/{cron_id}")
-
-    def cron_update(self, cron_id: str, **updates: Any) -> dict:
-        """Update a cron job. Pass fields as keyword arguments."""
-        return self._request("PATCH", f"/mags-cron/{cron_id}", json=updates)
-
-    def cron_delete(self, cron_id: str) -> dict:
-        """Delete a cron job."""
-        return self._request("DELETE", f"/mags-cron/{cron_id}")
-
-    # ── URL aliases ──────────────────────────────────────────────────
-
-    def url_alias_create(
-        self,
-        subdomain: str,
-        workspace_id: str,
-        domain: str = "apps.magpiecloud.com",
-    ) -> dict:
-        """Create a stable URL alias for a workspace.
-
-        The alias maps ``subdomain.<domain>`` to the active job in the workspace.
-        Use ``domain="app.lfg.run"`` for the LFG domain.
-
-        Returns ``{"id": ..., "subdomain": ..., "url": ...}``.
-        """
-        return self._request(
-            "POST",
-            "/mags-url-aliases",
-            json={
-                "subdomain": subdomain,
-                "workspace_id": workspace_id,
-                "domain": domain,
-            },
-        )
-
-    def url_alias_list(self) -> dict:
-        """List all URL aliases. Returns ``{"aliases": [...], "total": N}``."""
-        return self._request("GET", "/mags-url-aliases")
-
-    def url_alias_delete(self, subdomain: str) -> dict:
-        """Delete a URL alias by subdomain."""
-        return self._request("DELETE", f"/mags-url-aliases/{subdomain}")

package/python/test_sdk.py

@@ -1,78 +0,0 @@
-"""Test the Mags Python SDK: new, exec, url."""
-
-import os
-import sys
-import time
-
-os.environ["MAGS_API_TOKEN"] = "da214df72c164bda47970491fd839247a864c2599305ce90b38512d43ed034ea"
-
-# Use local src/ instead of installed package
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), "src"))
-
-from mags import Mags
-
-m = Mags()
-WS = "sdk-test-" + str(int(time.time()))
-
-print(f"=== Test 1: Create new VM ({WS}) ===")
-result = m.new(WS)
-print(f"  request_id: {result['request_id']}")
-print(f"  status:     {result['status']}")
-assert result["status"] == "running"
-print("  PASS\n")
-
-print("=== Test 2: find_job ===")
-job = m.find_job(WS)
-print(f"  found: workspace={job.get('workspace_id')} status={job.get('status')}")
-assert job is not None
-assert job["status"] == "running"
-print("  PASS\n")
-
-print("=== Test 3: exec - simple command ===")
-try:
-    result = m.exec(WS, "echo HELLO_FROM_SDK && uname -a", timeout=15)
-    print(f"  exit_code: {result['exit_code']}")
-    print(f"  output:    {result['output'].strip()}")
-    if result["stderr"]:
-        print(f"  stderr:    {result['stderr'].strip()}")
-    assert "HELLO_FROM_SDK" in result["output"]
-    print("  PASS\n")
-except Exception as e:
-    print(f"  FAIL: {e}\n")
-
-print("=== Test 4: exec - create HTML file ===")
-html = "<html><body><h1>Mags SDK Test</h1><p>Served from a microVM!</p></body></html>"
-try:
-    result = m.exec(WS, f"echo '{html}' > /root/index.html", timeout=15)
-    print(f"  exit_code: {result['exit_code']}")
-    result = m.exec(WS, "cat /root/index.html", timeout=15)
-    print(f"  content: {result['output'].strip()[:80]}...")
-    print("  PASS\n")
-except Exception as e:
-    print(f"  FAIL: {e}\n")
-
-print("=== Test 5: exec - start python HTTP server ===")
-try:
-    result = m.exec(WS, "nohup python3 -m http.server 8080 --directory /root > /tmp/srv.log 2>&1 & echo PID=$!", timeout=15)
-    print(f"  output: {result['output'].strip()}")
-    time.sleep(1)
-    # Verify it's running
-    result = m.exec(WS, "curl -s http://localhost:8080/index.html | head -1", timeout=15)
-    print(f"  curl:   {result['output'].strip()[:80]}")
-    print("  PASS\n")
-except Exception as e:
-    print(f"  FAIL: {e}\n")
-
-print("=== Test 6: url - enable public URL ===")
-try:
-    info = m.url(WS, port=8080)
-    print(f"  success: {info.get('success')}")
-    print(f"  url:     {info.get('url', 'N/A')}")
-    if info.get("url"):
-        print(f"\n  >>> Visit: {info['url']} <<<")
-    print("  PASS\n")
-except Exception as e:
-    print(f"  FAIL: {e}\n")
-
-print("=== All tests complete ===")
-print(f"Workspace: {WS}")