roboapi 0.4.2__py3-none-any.whl

roboapi/web/server.py

@@ -0,0 +1,419 @@
+"""Browser model API interaction, device status and installation endpoints."""
+
+from __future__ import annotations
+
+import json
+import logging
+import mimetypes
+import os
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from importlib.resources import files
+from pathlib import PurePosixPath
+from urllib.parse import parse_qs, unquote, urlsplit
+
+from ..errors import ControlNotReady, LoopRunning, PolicyUnavailable
+from ..images import preview_jpeg
+from ..config import DEFAULT_CONFIG
+from .presets import Presets
+
+logger = logging.getLogger(__name__)
+
+
+def _asset(name):
+    path = PurePosixPath(unquote(name))
+    if path.is_absolute() or ".." in path.parts or "\\" in str(path) or "\x00" in str(path):
+        raise FileNotFoundError(name)
+    return files("roboapi.web").joinpath("static", *path.parts).read_bytes()
+
+
+def _public_policy_config(config: dict) -> dict:
+    """Browser settings and connection state, never the token path or token value."""
+    return {
+        "url": config.get("url"),
+        "model": config.get("model"),
+        "api_key_configured": bool(config.get("api_key_configured")),
+        "policy_ready": bool(config.get("policy_ready")),
+        "inter_chunk_pause_s": config["inter_chunk_pause_s"],
+    }
+
+
+def _handler(runner, presets):
+    class Handler(BaseHTTPRequestHandler):
+        protocol_version = "HTTP/1.1"
+
+        def handle(self) -> None:
+            try:
+                super().handle()
+            except (BrokenPipeError, ConnectionResetError):
+                pass  # Closing a browser tab can reset a keep-alive connection.
+
+        def log_message(self, *args) -> None:  # keep stderr for the app's own logs
+            pass
+
+        def _send(self, body: bytes, ctype: str, status: int = 200) -> None:
+            self.send_response(status)
+            self.send_header("Content-Type", ctype)
+            self.send_header("Content-Length", str(len(body)))
+            self.send_header("Cache-Control", "no-store")
+            self.send_header("X-Content-Type-Options", "nosniff")
+            self.send_header("X-Frame-Options", "DENY")
+            self.end_headers()
+            self.wfile.write(body)
+
+        def _json(self, value, status: int = 200) -> None:
+            self._send(json.dumps(value, allow_nan=False).encode(), "application/json", status)
+
+        def _camera_jpeg(self) -> bytes:
+            if not runner.emb.camera.live:
+                raise RuntimeError("Camera disconnected")
+            try:
+                image, age = runner.emb.get_camera()
+            except Exception as exc:
+                raise RuntimeError("Could not read camera frame") from exc
+            if not 0 <= age <= runner.emb.cfg.camera.stale_after_s:
+                raise RuntimeError("Camera feed is stale")
+            try:
+                return preview_jpeg(image)
+            except Exception as exc:
+                raise RuntimeError("Could not encode camera frame") from exc
+
+        def _camera_stream(self) -> None:
+            try:
+                jpg = self._camera_jpeg()
+            except RuntimeError as exc:
+                logger.debug("camera preview unavailable", exc_info=True)
+                self._json({"error": str(exc)}, 503)
+                return
+
+            # An interrupted multipart response must end with EOF, not an idle keep-alive socket.
+            self.close_connection = True
+            self.connection.settimeout(3)
+            try:
+                self.send_response(200)
+                # Safari cancels fetch() responses using the image-only x-mixed-replace type.
+                self.send_header("Content-Type", "multipart/mixed; boundary=frame")
+                self.send_header("Cache-Control", "no-store")
+                self.send_header("Connection", "close")
+                self.send_header("X-Content-Type-Options", "nosniff")
+                self.send_header("X-Frame-Options", "DENY")
+                self.end_headers()
+                while True:
+                    started = time.monotonic()
+                    self.wfile.write(b"--frame\r\nContent-Type: image/jpeg\r\nContent-Length: "
+                                     + str(len(jpg)).encode() + b"\r\n\r\n" + jpg + b"\r\n")
+                    self.wfile.flush()
+                    time.sleep(max(0, 0.2 - (time.monotonic() - started)))
+                    jpg = self._camera_jpeg()
+            except RuntimeError:
+                logger.debug("camera preview stream ended", exc_info=True)
+            except OSError:
+                pass  # Disconnected or slow clients must not keep a preview worker alive.
+
+        def do_POST(self) -> None:
+            # Close even on validation errors: unread request bytes must not become requests.
+            self.close_connection = True
+            path = urlsplit(self.path).path
+            origin = self.headers.get("Origin")
+            try:
+                cross_origin = origin and (urlsplit(origin).scheme not in {"http", "https"}
+                                           or urlsplit(origin).netloc != self.headers.get("Host"))
+            except ValueError:
+                cross_origin = True
+            if cross_origin or self.headers.get("Sec-Fetch-Site") not in {None, "same-origin", "none"}:
+                self._json({"error": "Cross-origin requests are not allowed"}, 403)
+                return
+            if path == "/api/stop":
+                self._json(runner.stop("web stop"))
+                return
+            actions = {"acquire", "confirm_home", "confirm_plane_a", "confirm_plane_b", "confirm_plane_c", "return_home", "return_a", "save", "undo", "enable_control", "set_guiding_axis"}
+            instruction_paths = {"/api/instruction", "/api/policy/start"}
+            control_paths = {"/api/policy/pause", "/api/policy/resume", "/api/robot/reset",
+                             "/api/robot/recover", "/api/errors/clear", "/api/devices/connect", "/api/devices/release"}
+            task_route = path.strip("/").split("/")
+            task_action = (task_route[3] if len(task_route) == 4 and task_route[:2] == ["api", "tasks"]
+                           and task_route[3] in {"feedback", "delete"} else None)
+            calibration_action = path.rsplit("/", 1)[-1] if path.startswith("/api/calibration/") else None
+            if (path not in instruction_paths and path not in control_paths and
+                    path not in {"/api/policy/config", "/api/workspace/config", "/api/presets", "/api/recording/config", "/api/storage/cleanup", "/api/calibration/check"}
+                    and task_action is None and calibration_action not in actions):
+                self._json({"error": "Unknown action"}, 404)
+                return
+            if self.headers.get("Content-Type", "").split(";", 1)[0].strip() != "application/json":
+                self._json({"error": "Content-Type must be application/json"}, 415)
+                return
+            try:
+                length = int(self.headers.get("Content-Length", "0"))
+                limit = 131072 if path in {"/api/presets", "/api/storage/cleanup"} else 16384
+                if length <= 0 or length > limit or self.headers.get("Transfer-Encoding"):
+                    self._json({"error": f"A JSON body of 1–{limit} bytes is required"}, 413)
+                    return
+                self.connection.settimeout(5)
+                body = json.loads(self.rfile.read(length))
+                if not isinstance(body, dict):
+                    raise ValueError("JSON body must be an object")
+                if path == "/api/calibration/check":
+                    if set(body) != {"direction"} or not isinstance(body["direction"], str):
+                        raise ValueError("direction is required")
+                    self._json(runner.check_direction(body["direction"]))
+                elif path == "/api/storage/cleanup":
+                    ids = body.get("task_ids")
+                    if (set(body) - {"kind", "task_ids"} or "kind" not in body
+                            or ("task_ids" in body and (not isinstance(ids, list)
+                                or not all(isinstance(item, str) for item in ids)))):
+                        raise ValueError("kind and optional task_ids list are required")
+                    self._json(runner.tasks.cleanup(body["kind"], ids))
+                elif task_action == "feedback":
+                    if set(body) != {"rating", "note"} or body["rating"] not in (None, "up", "down") or not isinstance(body["note"], str):
+                        raise ValueError("rating and note are required")
+                    self._json(runner.tasks.feedback(task_route[2], body["rating"], body["note"]))
+                elif task_action == "delete":
+                    if body:
+                        raise ValueError("delete body must be empty")
+                    runner.tasks.delete(task_route[2])
+                    self._json({"ok": True})
+                elif path == "/api/recording/config":
+                    if set(body) != {"enabled"} or not isinstance(body["enabled"], bool):
+                        raise ValueError("enabled must be a boolean")
+                    self._json(runner.tasks.settings(body["enabled"]))
+                elif path == "/api/presets":
+                    if set(body) != {"instructions"}:
+                        raise ValueError("instructions is required")
+                    self._json({"instructions": presets.save(body["instructions"])})
+                elif path == "/api/workspace/config":
+                    if set(body) != {"enabled", "min_xyz_m", "max_xyz_m"}:
+                        raise ValueError("enabled, min_xyz_m and max_xyz_m are required")
+                    self._json(runner.configure_workspace(**body))
+                elif path == "/api/policy/config":
+                    required = {"url", "model", "inter_chunk_pause_s"}
+                    if (set(body) not in (required, required | {"api_key"})
+                            or not isinstance(body["url"], str) or not isinstance(body["model"], str)
+                            or not 1 <= len(body["url"]) <= 2048 or not 1 <= len(body["model"]) <= 128
+                            or ("api_key" in body and (not isinstance(body["api_key"], str)
+                                or not 1 <= len(body["api_key"]) <= 4096))):
+                        raise ValueError("url, model and inter_chunk_pause_s are required; api_key is optional")
+                    result = runner.configure_policy(**body)
+                    self._json({"ok": True, **_public_policy_config(result)})
+                elif path in {"/api/instruction", "/api/policy/start"}:
+                    allowed = {"instruction", "new_task"} if path == "/api/policy/start" else {"instruction"}
+                    if ("instruction" not in body or set(body) - allowed or not isinstance(body["instruction"], str)
+                            or ("new_task" in body and not isinstance(body["new_task"], bool))):
+                        raise ValueError("instruction must be a string")
+                    instruction = body["instruction"].strip()
+                    if not 1 <= len(instruction) <= 1000:
+                        raise ValueError("instruction must contain 1–1000 characters")
+                    hardware = runner.status()
+                    if not hardware["arm_connected"]:
+                        self._json({"error": "Robot disconnected"}, 409)
+                        return
+                    if path == "/api/policy/start" and not hardware["camera_connected"]:
+                        self._json({"error": "Camera disconnected"}, 409)
+                        return
+                    options = {"new_task": body["new_task"]} if "new_task" in body else {}
+                    self._json(runner.start(instruction, source="web", **options) if path == "/api/policy/start"
+                               else runner.set_instruction(instruction, source="web"))
+                elif path in control_paths:
+                    if body:
+                        raise ValueError("control body must be empty")
+                    state = runner.status()
+                    if path == "/api/policy/pause" and state["mode"] != "running":
+                        self._json({"error": "Policy is not running"}, 409)
+                        return
+                    if path == "/api/policy/resume" and state["mode"] != "paused":
+                        self._json({"error": "Policy is not paused"}, 409)
+                        return
+                    if path == "/api/robot/reset" and not state["alive"]:
+                        self._json({"error": "Robot unavailable; restore connection first"}, 409)
+                        return
+                    if path == "/api/errors/clear" and not state["alive"]:
+                        self._json({"error": "Fault still active; recover the device first"}, 409)
+                        return
+                    if path == "/api/policy/pause":
+                        result = runner.pause(source="web")
+                    elif path == "/api/policy/resume":
+                        result = runner.resume(source="web")
+                    elif path == "/api/robot/reset":
+                        result = {**runner.reset(), **runner.status()}
+                    elif path == "/api/robot/recover":
+                        result = {**runner.recover(), **runner.status()}
+                    elif path == "/api/devices/connect":
+                        result = runner.preview()
+                    elif path == "/api/devices/release":
+                        result = runner.release()
+                    else:
+                        result = runner.clear_monitor_errors()
+                    self._json(result)
+                else:
+                    result = runner.calibration.action(calibration_action, body)
+                    messages = {"enable_control": "Control enabled",
+                                "acquire": "Calibration started", "save": "Calibration saved", "undo": "Calibration record undone"}
+                    if calibration_action in messages:
+                        runner.records.event(messages[calibration_action])
+                    self._json(result)
+            except KeyError:
+                self._json({"error": "Task not found"}, 404)
+            except (ValueError, UnicodeDecodeError) as exc:
+                self._json({"error": str(exc)}, 400)
+            except PolicyUnavailable as exc:
+                detail = str(exc).lower()
+                if "authentication rejected" in detail:
+                    message = "API key authentication failed"
+                elif "model not authorized" in detail:
+                    message = "Current key cannot use this model"
+                elif "connect timeout" in detail:
+                    message = "Model connection timed out"
+                elif "read timeout" in detail:
+                    message = "Model response timed out"
+                else:
+                    message = "Model connection failed; check Base URL, model, and API key"
+                self._json({"error": message}, 502)
+            except ControlNotReady as exc:
+                self._json({"error": str(exc), "kind": exc.error}, 409)
+            except LoopRunning as exc:
+                self._json({"error": str(exc)}, 409)
+            except RuntimeError as exc:
+                self._json({"error": "Model settings cannot be changed now" if path == "/api/policy/config"
+                            else "Policy could not start; check device and model connections" if path == "/api/policy/start"
+                            else "Robot recovery failed; check the current fault" if path == "/api/robot/recover"
+                            else "Robot reset failed; check the current fault" if path == "/api/robot/reset"
+                            else str(exc)}, 409)
+            except TimeoutError:
+                self._json({"error": "Request body timed out"}, 408)
+            except Exception:
+                logger.exception("monitor action failed")
+                self._json({"error": "Model settings failed; check service logs." if path == "/api/policy/config"
+                            else "Could not save workspace settings; check service logs." if path == "/api/workspace/config"
+                            else "Could not save instruction presets." if path == "/api/presets"
+                            else "Could not save task data; check service logs." if task_action or path in {"/api/recording/config", "/api/storage/cleanup"}
+                            else "Robot operation failed; check the current fault." if path in control_paths
+                            else "Calibration operation failed; check service logs."}, 500)
+
+        def _video(self, path, task_id: str) -> None:
+            # Keep one file descriptor while a continuation atomically publishes a new MP4.
+            with path.open("rb") as video:
+                size = os.fstat(video.fileno()).st_size
+                start, end = 0, size - 1
+                requested = self.headers.get("Range")
+                if requested:
+                    try:
+                        unit, bounds = requested.split("=", 1)
+                        first, last = bounds.split("-", 1)
+                        if unit != "bytes" or "," in bounds:
+                            raise ValueError
+                        if first:
+                            start = int(first)
+                            end = min(int(last), size - 1) if last else size - 1
+                        else:
+                            suffix = int(last)
+                            if suffix <= 0:
+                                raise ValueError
+                            start = max(0, size - suffix)
+                        if not 0 <= start <= end < size:
+                            raise ValueError
+                    except ValueError:
+                        self.send_response(416)
+                        self.send_header("Content-Range", f"bytes */{size}")
+                        self.send_header("Content-Length", "0")
+                        self.end_headers()
+                        return
+                self.send_response(206 if requested else 200)
+                self.send_header("Content-Type", "video/mp4")
+                self.send_header("Accept-Ranges", "bytes")
+                self.send_header("Content-Length", str(end - start + 1))
+                self.send_header("Cache-Control", "no-store")
+                self.send_header("X-Content-Type-Options", "nosniff")
+                if requested:
+                    self.send_header("Content-Range", f"bytes {start}-{end}/{size}")
+                if parse_qs(urlsplit(self.path).query).get("download") == ["1"]:
+                    self.send_header("Content-Disposition", f'attachment; filename="task-{task_id}.mp4"')
+                self.end_headers()
+                video.seek(start)
+                remaining = end - start + 1
+                while remaining > 0:
+                    chunk = video.read(min(65536, remaining))
+                    if not chunk:
+                        break
+                    self.wfile.write(chunk)
+                    remaining -= len(chunk)
+
+        def do_GET(self) -> None:
+            path = urlsplit(self.path).path
+            if path.startswith("/assets/"):
+                try:
+                    asset = _asset(path.lstrip("/"))
+                except (FileNotFoundError, IsADirectoryError):
+                    self.send_error(404)
+                    return
+                self._send(asset, mimetypes.guess_type(path)[0] or "application/octet-stream")
+                return
+
+            if path == "/":
+                try:
+                    page = _asset("index.html")
+                except FileNotFoundError:
+                    self._json({"error": "Web assets missing. Install a release wheel or build frontend with npm run build."}, 503)
+                    return
+                self._send(page, "text/html; charset=utf-8")
+            elif path == "/api/calibration/check":
+                self._json(runner.direction_check_status())
+            elif path == "/api/calibration":
+                try:
+                    self._json(runner.calibration.status())
+                except Exception:
+                    logger.exception("calibration status failed")
+                    self._json({"error": "Could not load calibration status. Check the service logs."}, 500)
+            elif path == "/api/policy/config":
+                try:
+                    self._json(_public_policy_config(runner.policy_config()))
+                except Exception:
+                    logger.exception("policy settings read failed")
+                    self._json({"error": "Could not load model settings"}, 500)
+            elif path == "/api/workspace/config":
+                self._json(runner.workspace_config())
+            elif path == "/api/status":
+                self._json(runner.status())
+            elif path == "/api/storage":
+                try:
+                    self._json(runner.tasks.storage())
+                except OSError:
+                    logger.exception("task storage read failed")
+                    self._json({"error": "Could not read task storage"}, 500)
+            elif path == "/api/tasks" or path.startswith("/api/tasks/"):
+                try:
+                    route = path.strip("/").split("/")
+                    if len(route) == 2:
+                        task = runner.tasks.current()
+                        self._json({"tasks": runner.tasks.list(),
+                                    "current_task_id": task["id"] if task else None,
+                                    "recording_enabled": runner.tasks.settings()["enabled"]})
+                    elif len(route) == 3:
+                        self._json(runner.tasks.get(route[2]))
+                    elif len(route) == 4 and route[3] == "video":
+                        self._video(runner.tasks.video_path(route[2]), route[2])
+                    else:
+                        self._json({"error": "Unknown task action"}, 404)
+                except (KeyError, FileNotFoundError):
+                    self._json({"error": "Task or video not found"}, 404)
+            elif path == "/api/logs":
+                self._json({"events": runner.records.activity()})
+            elif path == "/api/presets":
+                try:
+                    self._json({"instructions": presets.read()})
+                except (OSError, ValueError, TypeError):
+                    self._json({"error": "Could not load instruction presets"}, 500)
+            elif path == "/api/camera/stream":
+                self._camera_stream()
+            else:
+                self.send_error(404)
+
+    return Handler
+
+
+def start_web(runner, cfg) -> ThreadingHTTPServer:
+    presets = Presets(getattr(runner, "config_path", None) or DEFAULT_CONFIG)
+    server = ThreadingHTTPServer((cfg.host, cfg.port), _handler(runner, presets))
+    server.daemon_threads = True
+    threading.Thread(target=server.serve_forever, name="web", daemon=True).start()
+    logger.info("web interface at http://%s:%d", cfg.host, server.server_port)
+    return server

roboapi/web/static/assets/Bundler-LICENSE.txt

@@ -0,0 +1,48 @@
+# Vite core license
+Vite is released under the MIT license:
+
+MIT License
+
+Copyright (c) 2019-present, VoidZero Inc. and Vite contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+# Rolldown runtime license
+
+MIT License
+
+Copyright (c) 2024-present VoidZero Inc. & Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.