pycentauri 0.1.1__tar.gz → 0.2.0__tar.gz

{pycentauri-0.1.1 → pycentauri-0.2.0}/CHANGELOG.md

@@ -6,6 +6,27 @@ Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-04-22
+
+### Added
+- **HTTP + SSE server.** `centauri server [--host IP] [--bind 127.0.0.1]
+  [--port 8787] [--enable-control]` runs a FastAPI app that wraps the
+  same client library used by the CLI and MCP server:
+  - `GET /` — health, version, connection state
+  - `GET /status` — latest status snapshot (JSON)
+  - `GET /attributes` — printer attributes (JSON)
+  - `GET /snapshot` — single JPEG frame from the webcam
+  - `GET /discover` — UDP LAN scan
+  - `GET /events/status` — Server-Sent Events stream of live status pushes
+  - `POST /print/{start,pause,resume,stop}` — only registered with
+    `--enable-control` (mirrors the MCP security posture — the routes
+    literally don't exist without the flag)
+- New optional extra: `pip install 'pycentauri[server]'` pulls in
+  FastAPI + uvicorn + sse-starlette.
+- The server holds a single long-lived WebSocket for its lifetime with
+  auto-reconnect and exponential backoff, so it never bumps against the
+  printer's 5-slot limit and HTTP requests return cached pushes instantly.
+
 ## [0.1.1] - 2026-04-22
 
 ### Fixed

{pycentauri-0.1.1 → pycentauri-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycentauri
-Version: 0.1.1
+Version: 0.2.0
 Summary: Python client and MCP server for Elegoo Centauri Carbon 3D printers
 Project-URL: Homepage, https://github.com/bjan/pycentauri
 Project-URL: Repository, https://github.com/bjan/pycentauri
@@ -28,13 +28,22 @@ Requires-Dist: pydantic>=2.7
 Requires-Dist: typer>=0.12
 Requires-Dist: websockets>=12.0
 Provides-Extra: dev
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mcp>=1.2; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: sse-starlette>=2.0; extra == 'dev'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'dev'
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == 'server'
+Requires-Dist: sse-starlette>=2.0; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'server'
 Description-Content-Type: text/markdown
 
 # pycentauri
@@ -43,12 +52,14 @@ Python client, CLI, and MCP server for the [Elegoo Centauri
 Carbon](https://www.elegoo.com/) 3D printer.
 
 `pycentauri` speaks the printer's native SDCP v3 protocol over its local
-WebSocket (port 3030) — no cloud account required. It exposes three surfaces:
+WebSocket (port 3030) — no cloud account required. It exposes four surfaces:
 
 1. An **async Python library** for direct integration.
 2. A **`centauri` CLI** for quick status checks, snapshots, and control.
 3. An **MCP server** so AI agents (Claude Code, Claude Desktop, Cursor, any
    MCP-compatible client) can monitor and drive the printer as a tool.
+4. An **HTTP + SSE server** for dashboards, reverse-proxy integration, and
+   anything that wants a plain REST API.
 
 > **Status:** alpha. The protocol has been reverse-engineered from the official
 > [`elegoo-link`](https://github.com/ELEGOO-3D/elegoo-link) C++ SDK and the
@@ -59,8 +70,10 @@ WebSocket (port 3030) — no cloud account required. It exposes three surfaces:
 ## Install
 
 ```sh
-pip install pycentauri            # library + CLI
-pip install "pycentauri[mcp]"     # + MCP server dependencies
+pip install pycentauri                    # library + CLI
+pip install "pycentauri[mcp]"             # + MCP server
+pip install "pycentauri[server]"          # + HTTP REST/SSE server
+pip install "pycentauri[mcp,server]"      # everything
 ```
 
 ## Quick start — CLI
@@ -112,6 +125,31 @@ async def main():
 asyncio.run(main())
 ```
 
+## Quick start — HTTP server
+
+```sh
+# Read-only, bound to loopback so only this box can hit it:
+centauri server --host 192.168.1.209 --port 8787
+
+# Read + write, bound to all interfaces (put a reverse proxy in front):
+centauri server --host 192.168.1.209 --bind 0.0.0.0 --port 8787 --enable-control
+```
+
+| Method | Path | Notes |
+|---|---|---|
+| `GET` | `/` | Health + version |
+| `GET` | `/status` | Latest status push (cached; updates every ~5s) |
+| `GET` | `/attributes` | Printer attributes |
+| `GET` | `/snapshot` | `image/jpeg` response |
+| `GET` | `/discover` | LAN scan |
+| `GET` | `/events/status` | Server-Sent Events stream of pushes |
+| `POST` | `/print/start` | Body: `{"filename": "cube.gcode"}`. Requires `--enable-control`. |
+| `POST` | `/print/{pause,resume,stop}` | Requires `--enable-control`. |
+
+The server holds a single long-lived WebSocket to the printer and reuses
+it for every request — no per-request reconnect, and it won't bump into
+the firmware's 5-slot limit.
+
 ## Quick start — MCP
 
 Register the server with your agent. With Claude Code:

{pycentauri-0.1.1 → pycentauri-0.2.0}/README.md

@@ -4,12 +4,14 @@ Python client, CLI, and MCP server for the [Elegoo Centauri
 Carbon](https://www.elegoo.com/) 3D printer.
 
 `pycentauri` speaks the printer's native SDCP v3 protocol over its local
-WebSocket (port 3030) — no cloud account required. It exposes three surfaces:
+WebSocket (port 3030) — no cloud account required. It exposes four surfaces:
 
 1. An **async Python library** for direct integration.
 2. A **`centauri` CLI** for quick status checks, snapshots, and control.
 3. An **MCP server** so AI agents (Claude Code, Claude Desktop, Cursor, any
    MCP-compatible client) can monitor and drive the printer as a tool.
+4. An **HTTP + SSE server** for dashboards, reverse-proxy integration, and
+   anything that wants a plain REST API.
 
 > **Status:** alpha. The protocol has been reverse-engineered from the official
 > [`elegoo-link`](https://github.com/ELEGOO-3D/elegoo-link) C++ SDK and the
@@ -20,8 +22,10 @@ WebSocket (port 3030) — no cloud account required. It exposes three surfaces:
 ## Install
 
 ```sh
-pip install pycentauri            # library + CLI
-pip install "pycentauri[mcp]"     # + MCP server dependencies
+pip install pycentauri                    # library + CLI
+pip install "pycentauri[mcp]"             # + MCP server
+pip install "pycentauri[server]"          # + HTTP REST/SSE server
+pip install "pycentauri[mcp,server]"      # everything
 ```
 
 ## Quick start — CLI
@@ -73,6 +77,31 @@ async def main():
 asyncio.run(main())
 ```
 
+## Quick start — HTTP server
+
+```sh
+# Read-only, bound to loopback so only this box can hit it:
+centauri server --host 192.168.1.209 --port 8787
+
+# Read + write, bound to all interfaces (put a reverse proxy in front):
+centauri server --host 192.168.1.209 --bind 0.0.0.0 --port 8787 --enable-control
+```
+
+| Method | Path | Notes |
+|---|---|---|
+| `GET` | `/` | Health + version |
+| `GET` | `/status` | Latest status push (cached; updates every ~5s) |
+| `GET` | `/attributes` | Printer attributes |
+| `GET` | `/snapshot` | `image/jpeg` response |
+| `GET` | `/discover` | LAN scan |
+| `GET` | `/events/status` | Server-Sent Events stream of pushes |
+| `POST` | `/print/start` | Body: `{"filename": "cube.gcode"}`. Requires `--enable-control`. |
+| `POST` | `/print/{pause,resume,stop}` | Requires `--enable-control`. |
+
+The server holds a single long-lived WebSocket to the printer and reuses
+it for every request — no per-request reconnect, and it won't bump into
+the firmware's 5-slot limit.
+
 ## Quick start — MCP
 
 Register the server with your agent. With Claude Code:

{pycentauri-0.1.1 → pycentauri-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycentauri"
-version = "0.1.1"
+version = "0.2.0"
 description = "Python client and MCP server for Elegoo Centauri Carbon 3D printers"
 readme = "README.md"
 license = "Apache-2.0"
@@ -35,12 +35,15 @@ dependencies = [
 
 [project.optional-dependencies]
 mcp = ["mcp>=1.2"]
+server = ["fastapi>=0.110", "uvicorn[standard]>=0.29", "sse-starlette>=2.0"]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
     "ruff>=0.5",
     "mypy>=1.10",
     "pytest-cov>=5.0",
+    "httpx>=0.27",
+    "pycentauri[mcp,server]",
 ]
 
 [project.scripts]
@@ -63,6 +66,10 @@ target-version = "py310"
 select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
 ignore = ["E501"]
 
+[tool.ruff.lint.per-file-ignores]
+# FastAPI's idiomatic DI uses `Depends()` in default values; that's B008.
+"src/pycentauri/server.py" = ["B008"]
+
 [tool.mypy]
 python_version = "3.10"
 strict = true

{pycentauri-0.1.1 → pycentauri-0.2.0}/src/pycentauri/__init__.py

@@ -15,4 +15,4 @@ __all__ = [
     "discover",
 ]
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"

{pycentauri-0.1.1 → pycentauri-0.2.0}/src/pycentauri/cli.py

@@ -336,6 +336,38 @@ def cmd_print_stop(host: HostOpt = None, enable_control: ControlOpt = False) ->
     _run(run())
 
 
+@app.command("server")
+def cmd_server(
+    host: HostOpt = None,
+    bind: str = typer.Option(
+        "127.0.0.1", "--bind", help="Interface to bind. Use 0.0.0.0 to expose on LAN."
+    ),
+    port: int = typer.Option(8787, "--port", "-p"),
+    enable_control: ControlOpt = False,
+    log_level: str = typer.Option("info", "--log-level"),
+) -> None:
+    """Run the HTTP + SSE server (requires `pip install 'pycentauri[server]'`)."""
+    try:
+        from pycentauri.server import run as run_server
+    except ImportError as err:
+        _echo_err("Server support not installed. Install with: pip install 'pycentauri[server]'")
+        _echo_err(f"(missing dependency: {err})")
+        raise typer.Exit(code=1) from err
+
+    async def resolve() -> tuple[str, str | None]:
+        return await _resolve_target(host)
+
+    h, mid = asyncio.run(resolve())
+    run_server(
+        h,
+        bind=bind,
+        port=port,
+        enable_control=enable_control,
+        mainboard_id=mid,
+        log_level=log_level,
+    )
+
+
 @app.command("mcp")
 def cmd_mcp(
     enable_control: ControlOpt = False,

pycentauri-0.2.0/src/pycentauri/server.py

@@ -0,0 +1,396 @@
+"""FastAPI HTTP server exposing the printer over REST + SSE.
+
+A single long-lived :class:`~pycentauri.client.Printer` connection is held for
+the lifetime of the server and reused across requests. That keeps us
+well under the Elegoo firmware's 5-WebSocket slot limit and means
+``GET /status`` returns the in-memory cached push rather than opening a
+fresh connection on every request.
+
+On WebSocket errors we reconnect in the background with exponential
+backoff. The mainboard ID learned from the first successful discovery is
+cached so reconnects don't have to wait on an Attributes push.
+
+Surfaces (register with ``centauri server``):
+
+* ``GET /`` — health and version info
+* ``GET /status`` — latest status snapshot (JSON)
+* ``GET /attributes`` — printer attributes (JSON)
+* ``GET /snapshot`` — single JPEG frame from the webcam
+* ``GET /discover`` — UDP LAN scan
+* ``GET /events/status`` — Server-Sent Events stream of live status pushes
+* ``POST /print/{start,pause,resume,stop}`` — only registered when the
+  server is launched with ``--enable-control``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+from fastapi import Depends, FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse, Response
+from pydantic import BaseModel, Field
+from sse_starlette.sse import EventSourceResponse
+
+from pycentauri import __version__
+from pycentauri.client import ControlDisabledError, Printer, PrinterError
+from pycentauri.discovery import DiscoveredPrinter
+from pycentauri.discovery import discover as lan_discover
+
+log = logging.getLogger(__name__)
+
+RECONNECT_BACKOFF_START = 1.0
+RECONNECT_BACKOFF_MAX = 30.0
+
+
+class PrinterManager:
+    """Owns a single long-lived :class:`Printer` connection for the whole server.
+
+    Runs a background supervisor that keeps a connection open, reconnects
+    with exponential backoff on failure, and re-subscribes to status pushes
+    after each reconnect. The Printer instance is exposed via :attr:`printer`
+    for tool use — callers that need write operations should pass
+    ``enable_control=True`` at construction.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        *,
+        enable_control: bool = False,
+        mainboard_id: str | None = None,
+    ) -> None:
+        self.host = host
+        self.enable_control = enable_control
+        self._mainboard_id = mainboard_id
+        self._printer: Printer | None = None
+        self._supervisor: asyncio.Task[None] | None = None
+        self._ready = asyncio.Event()
+        self._closing = False
+
+    @property
+    def printer(self) -> Printer:
+        """The currently active Printer. Raises if not connected."""
+        if self._printer is None or self._printer._closed:
+            raise HTTPException(status_code=503, detail="printer connection not ready")
+        return self._printer
+
+    async def start(self) -> None:
+        """Launch the supervisor task and wait for the first connection."""
+        self._supervisor = asyncio.create_task(self._run(), name="pycentauri-supervisor")
+        # Don't block startup indefinitely; server is still useful even while
+        # reconnecting (endpoints will 503 cleanly).
+        with contextlib.suppress(asyncio.TimeoutError):
+            await asyncio.wait_for(self._ready.wait(), timeout=10.0)
+
+    async def stop(self) -> None:
+        self._closing = True
+        if self._supervisor is not None and not self._supervisor.done():
+            self._supervisor.cancel()
+            with contextlib.suppress(asyncio.CancelledError, Exception):
+                await self._supervisor
+        if self._printer is not None:
+            with contextlib.suppress(Exception):
+                await self._printer.close()
+
+    async def _run(self) -> None:
+        backoff = RECONNECT_BACKOFF_START
+        while not self._closing:
+            # Learn the mainboard via discovery if we don't have one yet.
+            if self._mainboard_id is None:
+                found = await lan_discover(timeout=1.5, retries=2)
+                for p in found:
+                    if p.host == self.host and p.mainboard_id:
+                        self._mainboard_id = p.mainboard_id
+                        log.info("learned mainboard id %s", self._mainboard_id)
+                        break
+
+            try:
+                self._printer = await Printer.connect(
+                    self.host,
+                    enable_control=self.enable_control,
+                    mainboard_id=self._mainboard_id,
+                )
+                # Prime the subscription so status pushes start flowing.
+                with contextlib.suppress(Exception):
+                    await asyncio.wait_for(
+                        self._printer._ensure_subscribed(),
+                        timeout=5.0,
+                    )
+                log.info("connected to %s", self.host)
+                self._ready.set()
+                backoff = RECONNECT_BACKOFF_START
+                # Hold until the reader dies (disconnect).
+                reader = self._printer._reader
+                if reader is not None:
+                    await reader
+            except Exception as e:
+                log.warning("connection to %s failed: %r", self.host, e)
+
+            if self._closing:
+                break
+            self._ready.clear()
+            await asyncio.sleep(backoff)
+            backoff = min(backoff * 2, RECONNECT_BACKOFF_MAX)
+
+
+# --- Pydantic request bodies ------------------------------------------------
+
+
+class StartPrintBody(BaseModel):
+    filename: str = Field(..., description="File name as it appears on the printer.")
+    storage: str = Field("local", description="'local' or 'udisk'.")
+    auto_leveling: bool = True
+    timelapse: bool = False
+
+
+# --- Dependency helpers -----------------------------------------------------
+
+
+def get_manager(request: Request) -> PrinterManager:
+    mgr: PrinterManager | None = getattr(request.app.state, "manager", None)
+    if mgr is None:
+        raise HTTPException(status_code=503, detail="printer manager not initialised")
+    return mgr
+
+
+def require_control(manager: PrinterManager = Depends(get_manager)) -> PrinterManager:
+    if not manager.enable_control:
+        raise HTTPException(
+            status_code=403,
+            detail=(
+                "control actions are disabled. Launch the server with "
+                "--enable-control to enable POST /print/* endpoints."
+            ),
+        )
+    return manager
+
+
+# --- App factory ------------------------------------------------------------
+
+
+def create_app(
+    host: str,
+    *,
+    enable_control: bool = False,
+    mainboard_id: str | None = None,
+) -> FastAPI:
+    """Build the FastAPI app. ``host`` is the printer's IP/hostname.
+
+    The app runs a single background :class:`PrinterManager` that owns the
+    WebSocket lifecycle. Control endpoints are registered only when
+    ``enable_control`` is ``True``.
+    """
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        manager = PrinterManager(host, enable_control=enable_control, mainboard_id=mainboard_id)
+        app.state.manager = manager
+        await manager.start()
+        try:
+            yield
+        finally:
+            await manager.stop()
+
+    app = FastAPI(
+        title="pycentauri HTTP API",
+        version=__version__,
+        description=(
+            "HTTP + SSE surface for an Elegoo Centauri Carbon 3D printer. "
+            "Wrapping the same client library that powers the `centauri` "
+            "CLI and the MCP server."
+        ),
+        lifespan=lifespan,
+    )
+
+    @app.get("/", tags=["meta"])
+    async def root(manager: PrinterManager = Depends(get_manager)) -> dict[str, Any]:
+        return {
+            "service": "pycentauri",
+            "version": __version__,
+            "printer_host": manager.host,
+            "mainboard_id": manager._mainboard_id,
+            "connected": manager._printer is not None and not manager._printer._closed,
+            "enable_control": manager.enable_control,
+        }
+
+    @app.get("/status", tags=["read"])
+    async def status_endpoint(
+        manager: PrinterManager = Depends(get_manager),
+    ) -> dict[str, Any]:
+        try:
+            st = await asyncio.wait_for(manager.printer.status(), timeout=10)
+        except asyncio.TimeoutError as err:
+            raise HTTPException(status_code=504, detail="printer status timeout") from err
+        except PrinterError as err:
+            raise HTTPException(status_code=502, detail=str(err)) from err
+        return {
+            "state": st.state,
+            "print_status": st.print_status,
+            "progress": st.progress,
+            "filename": st.filename,
+            "layer": {
+                "current": st.print_info.current_layer if st.print_info else None,
+                "total": st.print_info.total_layer if st.print_info else None,
+            },
+            "temperatures": {
+                "nozzle": {"actual": st.temp_nozzle, "target": st.temp_nozzle_target},
+                "bed": {"actual": st.temp_bed, "target": st.temp_bed_target},
+                "chamber": {"actual": st.temp_chamber, "target": st.temp_chamber_target},
+            },
+            "position": st.coord,
+            "z_offset": st.z_offset,
+            "fans": st.fan_speed,
+            "raw": st.raw,
+        }
+
+    @app.get("/attributes", tags=["read"])
+    async def attributes_endpoint(
+        manager: PrinterManager = Depends(get_manager),
+    ) -> dict[str, Any]:
+        try:
+            attrs = await asyncio.wait_for(manager.printer.attributes(), timeout=10)
+        except asyncio.TimeoutError as err:
+            raise HTTPException(status_code=504, detail="printer attributes timeout") from err
+        except PrinterError as err:
+            raise HTTPException(status_code=502, detail=str(err)) from err
+        return {
+            "mainboard_id": attrs.mainboard_id,
+            "name": attrs.name,
+            "machine_name": attrs.machine_name,
+            "firmware_version": attrs.firmware_version,
+            "capabilities": attrs.capabilities,
+            "raw": attrs.raw,
+        }
+
+    @app.get("/snapshot", tags=["read"], response_class=Response)
+    async def snapshot_endpoint(
+        manager: PrinterManager = Depends(get_manager),
+    ) -> Response:
+        try:
+            jpeg = await asyncio.wait_for(manager.printer.snapshot(), timeout=15)
+        except Exception as err:
+            raise HTTPException(status_code=502, detail=f"snapshot failed: {err}") from err
+        return Response(
+            content=jpeg,
+            media_type="image/jpeg",
+            headers={"Cache-Control": "no-store"},
+        )
+
+    @app.get("/discover", tags=["read"])
+    async def discover_endpoint() -> list[dict[str, Any]]:
+        found: list[DiscoveredPrinter] = await lan_discover(timeout=2.0, retries=2)
+        return [
+            {
+                "host": p.host,
+                "mainboard_id": p.mainboard_id,
+                "name": p.name,
+                "machine_name": p.machine_name,
+                "firmware_version": p.firmware_version,
+            }
+            for p in found
+        ]
+
+    @app.get("/events/status", tags=["read"])
+    async def status_stream(
+        request: Request, manager: PrinterManager = Depends(get_manager)
+    ) -> EventSourceResponse:
+        """Server-Sent Events stream of live status pushes.
+
+        Clients subscribe once and receive one ``data:`` line per push.
+        Disconnects are handled silently on the server side.
+        """
+
+        async def gen() -> AsyncIterator[dict[str, str]]:
+            try:
+                async for st in manager.printer.watch():
+                    if await request.is_disconnected():
+                        break
+                    yield {"event": "status", "data": json.dumps(st.raw, default=str)}
+            except PrinterError as err:
+                yield {"event": "error", "data": str(err)}
+
+        return EventSourceResponse(gen())
+
+    if not enable_control:
+        return app
+
+    # --- Control endpoints (registered only when --enable-control) ----------
+
+    @app.post("/print/start", tags=["control"])
+    async def start_print(
+        body: StartPrintBody, manager: PrinterManager = Depends(require_control)
+    ) -> dict[str, Any]:
+        try:
+            result = await manager.printer.start_print(
+                body.filename,
+                storage=body.storage,
+                auto_leveling=body.auto_leveling,
+                timelapse=body.timelapse,
+            )
+        except ControlDisabledError as err:
+            raise HTTPException(status_code=403, detail=str(err)) from err
+        except PrinterError as err:
+            raise HTTPException(status_code=502, detail=str(err)) from err
+        return {"ok": True, "response": result.inner}
+
+    @app.post("/print/pause", tags=["control"])
+    async def pause_print(
+        manager: PrinterManager = Depends(require_control),
+    ) -> dict[str, Any]:
+        try:
+            result = await manager.printer.pause()
+        except PrinterError as err:
+            raise HTTPException(status_code=502, detail=str(err)) from err
+        return {"ok": True, "response": result.inner}
+
+    @app.post("/print/resume", tags=["control"])
+    async def resume_print(
+        manager: PrinterManager = Depends(require_control),
+    ) -> dict[str, Any]:
+        try:
+            result = await manager.printer.resume()
+        except PrinterError as err:
+            raise HTTPException(status_code=502, detail=str(err)) from err
+        return {"ok": True, "response": result.inner}
+
+    @app.post("/print/stop", tags=["control"])
+    async def stop_print(
+        manager: PrinterManager = Depends(require_control),
+    ) -> dict[str, Any]:
+        try:
+            result = await manager.printer.stop()
+        except PrinterError as err:
+            raise HTTPException(status_code=502, detail=str(err)) from err
+        return {"ok": True, "response": result.inner}
+
+    return app
+
+
+def run(
+    host: str,
+    *,
+    bind: str = "127.0.0.1",
+    port: int = 8787,
+    enable_control: bool = False,
+    mainboard_id: str | None = None,
+    log_level: str = "info",
+) -> None:
+    """Launch the server with uvicorn (blocks).
+
+    Defaults bind to loopback. Set ``bind="0.0.0.0"`` to expose on the LAN —
+    in that case put an authenticating reverse proxy in front, since the
+    HTTP surface itself is unauthenticated in v0.2.
+    """
+    import uvicorn
+
+    app = create_app(host, enable_control=enable_control, mainboard_id=mainboard_id)
+    uvicorn.run(app, host=bind, port=port, log_level=log_level)
+
+
+__all__ = ["JSONResponse", "PrinterManager", "create_app", "run"]

pycentauri-0.2.0/tests/test_server.py

@@ -0,0 +1,106 @@
+"""Tests for the FastAPI HTTP server.
+
+Uses the existing ``_FakePrinter`` fixture from ``test_client`` to stand up
+a local SDCP WebSocket server, then spins up the FastAPI app against it.
+We hit the app through httpx's ASGI transport — no real HTTP port bound.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+import pytest
+
+pytest.importorskip("fastapi")
+
+from pycentauri import server as server_module
+from tests.test_client import MAINBOARD, _FakePrinter
+
+
+async def _asgi_client(app: Any) -> httpx.AsyncClient:
+    transport = httpx.ASGITransport(app=app)
+    return httpx.AsyncClient(transport=transport, base_url="http://test")
+
+
+async def test_read_endpoints(monkeypatch: pytest.MonkeyPatch) -> None:
+    server = _FakePrinter()
+    await server.start()
+    monkeypatch.setattr("pycentauri.client.WS_PORT", server.port)
+
+    app = server_module.create_app("127.0.0.1", mainboard_id=MAINBOARD)
+    # Mimic the lifespan manager manually: the async-context machinery
+    # under httpx.AsyncClient doesn't drive lifespan, so do it ourselves.
+    async with app.router.lifespan_context(app), await _asgi_client(app) as client:
+        r = await client.get("/")
+        assert r.status_code == 200
+        body = r.json()
+        assert body["service"] == "pycentauri"
+        assert body["printer_host"] == "127.0.0.1"
+
+        r = await client.get("/status")
+        assert r.status_code == 200
+        s = r.json()
+        assert s["print_status"] == 13
+        assert s["temperatures"]["nozzle"]["actual"] == 210.0
+
+        r = await client.get("/attributes")
+        assert r.status_code == 200
+        assert r.json()["mainboard_id"] == MAINBOARD
+
+    await server.stop()
+
+
+async def test_control_endpoints_404_by_default(monkeypatch: pytest.MonkeyPatch) -> None:
+    server = _FakePrinter()
+    await server.start()
+    monkeypatch.setattr("pycentauri.client.WS_PORT", server.port)
+
+    app = server_module.create_app("127.0.0.1", mainboard_id=MAINBOARD)
+    async with app.router.lifespan_context(app), await _asgi_client(app) as client:
+        for path in ("/print/start", "/print/pause", "/print/resume", "/print/stop"):
+            r = await client.post(
+                path, json={"filename": "x.gcode"} if path.endswith("start") else {}
+            )
+            assert r.status_code == 404, (
+                f"control endpoint {path} should not exist without enable_control"
+            )
+    await server.stop()
+
+
+async def test_control_endpoints_registered_when_enabled(monkeypatch: pytest.MonkeyPatch) -> None:
+    server = _FakePrinter()
+    await server.start()
+    monkeypatch.setattr("pycentauri.client.WS_PORT", server.port)
+
+    app = server_module.create_app("127.0.0.1", enable_control=True, mainboard_id=MAINBOARD)
+    async with app.router.lifespan_context(app), await _asgi_client(app) as client:
+        r = await client.post("/print/pause")
+        assert r.status_code == 200
+        assert r.json()["ok"] is True
+
+        r = await client.post("/print/resume")
+        assert r.status_code == 200
+
+    # The fake printer recorded the Cmd.PAUSE_PRINT + Cmd.RESUME_PRINT commands.
+    from pycentauri.sdcp import Cmd
+
+    cmds = [m["Data"]["Cmd"] for m in server.received]
+    assert int(Cmd.PAUSE_PRINT) in cmds
+    assert int(Cmd.RESUME_PRINT) in cmds
+    await server.stop()
+
+
+async def test_start_print_request_body_validation(monkeypatch: pytest.MonkeyPatch) -> None:
+    server = _FakePrinter()
+    await server.start()
+    monkeypatch.setattr("pycentauri.client.WS_PORT", server.port)
+
+    app = server_module.create_app("127.0.0.1", enable_control=True, mainboard_id=MAINBOARD)
+    async with app.router.lifespan_context(app), await _asgi_client(app) as client:
+        r = await client.post("/print/start", json={})
+        assert r.status_code == 422  # filename is required
+
+        r = await client.post("/print/start", json={"filename": "cube.gcode"})
+        assert r.status_code == 200
+    await server.stop()