zmon 1.5.0__py3-none-any.whl

zmon/__init__.py

@@ -0,0 +1,8 @@
+"""zMon — monitoring for zCFD runs.
+
+Exposes the monitor API as a FastAPI router so it can be mounted into
+`zui_server_zcfd`, served standalone by `zmon.main`, or driven from the
+`zmon` console script. See docs/packaging-plan.md.
+"""
+
+__all__ = ["resolve"]

zmon/cli.py

@@ -0,0 +1,295 @@
+"""
+The `zmon` command: serve the monitor API, the bundled SPA, and open a browser.
+
+This is the only place that knows about static files, terminals, or browsers.
+Inside zui none of that applies — zui owns the frontend and the process — so the
+app itself stays in `zmon.main`.
+
+Port selection is deliberately not the user's problem: bind port 0 and let the
+kernel choose, then open the browser on whatever it picked. `--port` exists for
+the case where something else needs to know the number in advance (an SSH
+tunnel), and `ZMON_PORT` covers setting it once per machine.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import socket
+import sys
+import webbrowser
+from pathlib import Path
+from typing import Optional
+
+import uvicorn
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+
+from . import main as main_module
+from . import router as router_module
+
+DEFAULT_HOST = "127.0.0.1"
+
+# Seconds to wait for a first client before giving up, and to wait after the
+# last one leaves. Only consulted when --exit-when-idle is passed.
+STARTUP_GRACE_SECONDS = 30.0
+IDLE_GRACE_SECONDS = 5.0
+
+_WATCHDOG_TICK_SECONDS = 0.25
+
+
+def _say(message: str) -> None:
+    """
+    Tell the user something, now. stdout is block-buffered when it isn't a
+    terminal, so without an explicit flush the URL stays invisible for a
+    redirected or backgrounded run — which is how this gets used on a cluster.
+    """
+    print(message, flush=True)
+
+
+def _default_port() -> int:
+    """
+    0 means "let the kernel pick", which is what we want unless the user has
+    pinned a port. PORT is honoured for compatibility but is far too generic a
+    name to rely on — zmon-dev exported it, and so do many other tools.
+    """
+    for name in ("ZMON_PORT", "PORT"):
+        raw = os.environ.get(name)
+        if raw:
+            try:
+                return int(raw)
+            except ValueError:
+                print(f"Ignoring {name}={raw!r}: not a port number", file=sys.stderr)
+    return 0
+
+
+def _static_dir() -> Optional[Path]:
+    """
+    The built SPA. Wheels install as real directories, so a __file__-relative
+    lookup is enough; the frontend/dist fallback is for a source checkout whose
+    assets haven't been copied into the package yet.
+    """
+    packaged = Path(__file__).parent / "public"
+    if packaged.is_dir():
+        return packaged
+
+    dev = Path(__file__).resolve().parents[1] / "frontend" / "dist"
+    if dev.is_dir():
+        return dev
+
+    return None
+
+
+def build_app() -> FastAPI:
+    """The standalone app: the API, plus the SPA at the root if we have one."""
+    app = main_module.create_app()
+
+    static = _static_dir()
+    if static is not None:
+        # Mounted last, so the API routes registered above win.
+        app.mount("/", StaticFiles(directory=static, html=True), name="frontend")
+    else:
+        print(
+            "No built frontend found; serving the API only "
+            f"({main_module.API_PREFIX}).",
+            file=sys.stderr,
+            flush=True,
+        )
+
+    return app
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="zmon",
+        description="Monitor a zCFD run in your browser.",
+    )
+    parser.add_argument(
+        "file",
+        nargs="?",
+        help="control file (.py) or report CSV to open. Without it, pick one in "
+        "the browser.",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=None,
+        help="port to listen on. Defaults to ZMON_PORT, else an unused port "
+        "chosen by the OS.",
+    )
+    parser.add_argument(
+        "--host",
+        default=DEFAULT_HOST,
+        help=f"address to bind. Defaults to {DEFAULT_HOST}; anything else "
+        "exposes the file browser to other users on this machine.",
+    )
+    parser.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="don't try to open a browser.",
+    )
+    parser.add_argument(
+        "--exit-when-idle",
+        action="store_true",
+        help="shut down once no browser is connected. Off by default: it is "
+        "unsafe behind an SSH tunnel, where reconnects are routine.",
+    )
+    parser.add_argument("--version", action="version", version=_version())
+    return parser
+
+
+def _version() -> str:
+    try:
+        from importlib.metadata import version
+
+        return version("zmon")
+    except Exception:
+        return "unknown"
+
+
+def _open_browser(url: str) -> None:
+    try:
+        opened = webbrowser.open(url)
+    except Exception:
+        opened = False
+
+    if not opened:
+        # Headless login node, or no browser configured.
+        print(f"Open {url} in a browser to view.", file=sys.stderr)
+
+
+def _bound_url(server: uvicorn.Server, host: str) -> Optional[str]:
+    """The URL to actually visit, with the port the kernel handed us."""
+    for started in server.servers:
+        for sock in started.sockets:
+            try:
+                _, port = sock.getsockname()[:2]
+            except (OSError, ValueError):
+                continue
+            shown = "localhost" if host in ("0.0.0.0", "::", "127.0.0.1") else host
+            return f"http://{shown}:{port}"
+    return None
+
+
+async def _announce(server: uvicorn.Server, host: str, open_browser: bool) -> None:
+    while not server.started:
+        await asyncio.sleep(0.05)
+        if server.should_exit:
+            return
+
+    url = _bound_url(server, host)
+    if url is None:
+        return
+
+    _say(f"zMon is at {url}")
+    if open_browser:
+        _open_browser(url)
+
+
+async def _idle_watchdog(server: uvicorn.Server) -> None:
+    """
+    Stop the server once the last browser has gone, mirroring the old Bun
+    backend. Opt-in, because zui owns process lifecycle and an SSH tunnel drops
+    SSE connections often enough that this would kill a live session.
+    """
+    store = router_module.store
+    loop = asyncio.get_running_loop()
+
+    if not await _wait_for_subscriber(store, loop.time() + STARTUP_GRACE_SECONDS):
+        print("No browser connected; shutting down.", file=sys.stderr)
+        server.should_exit = True
+        return
+
+    while not server.should_exit:
+        if store.subscriber_count == 0:
+            deadline = loop.time() + IDLE_GRACE_SECONDS
+            while store.subscriber_count == 0:
+                if loop.time() >= deadline:
+                    print("No browsers left; shutting down.", file=sys.stderr)
+                    server.should_exit = True
+                    return
+                await asyncio.sleep(_WATCHDOG_TICK_SECONDS)
+        await asyncio.sleep(_WATCHDOG_TICK_SECONDS)
+
+
+async def _wait_for_subscriber(store, deadline: float) -> bool:
+    loop = asyncio.get_running_loop()
+    while store.subscriber_count == 0:
+        if loop.time() >= deadline:
+            return False
+        await asyncio.sleep(_WATCHDOG_TICK_SECONDS)
+    return True
+
+
+async def _run(args: argparse.Namespace) -> int:
+    initial: Optional[Path] = None
+    if args.file:
+        initial = Path(args.file).expanduser()
+        if not initial.exists():
+            print(f"File not found: {initial}", file=sys.stderr)
+            initial = None
+
+    # Where the file browser starts when the client doesn't say.
+    router_module.configure(initial_file=initial)
+
+    if initial is not None:
+        try:
+            session = await router_module.store.create(initial)
+            _say(f"Watching {session.name} ({session.type})")
+        except Exception as exc:
+            print(f"Could not open {initial}: {exc}", file=sys.stderr)
+    else:
+        _say("No file given; choose one in the browser.")
+
+    port = args.port if args.port is not None else _default_port()
+    config = uvicorn.Config(
+        build_app(),
+        host=args.host,
+        port=port,
+        log_level="warning",
+    )
+    server = uvicorn.Server(config)
+
+    tasks = [asyncio.create_task(_announce(server, args.host, not args.no_browser))]
+    if args.exit_when_idle:
+        tasks.append(asyncio.create_task(_idle_watchdog(server)))
+
+    try:
+        await server.serve()
+    finally:
+        for task in tasks:
+            task.cancel()
+
+    return 0
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.port and args.port != 0 and _port_in_use(args.host, args.port):
+        print(
+            f"Port {args.port} is already in use on {args.host}.",
+            file=sys.stderr,
+            flush=True,
+        )
+        return 1
+
+    try:
+        return asyncio.run(_run(args))
+    except KeyboardInterrupt:
+        return 0
+
+
+def _port_in_use(host: str, port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+        probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            probe.bind((host, port))
+        except OSError:
+            return True
+    return False
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

zmon/main.py

@@ -0,0 +1,79 @@
+"""
+Standalone ASGI application.
+
+`uvicorn zmon.main:app` serves the monitor API and nothing else. The SPA and the
+browser-opening live in `zmon.cli`; inside zui the frontend is zui's own.
+
+Auth mirrors `zui_server_zcfd`: the `X-ZUI-Token` header is required only when
+`ZUI_API_TOKEN` is set in the environment. Standalone, it usually isn't, and a
+loopback bind or a 0600 Unix socket is what protects the process.
+"""
+
+from __future__ import annotations
+
+import os
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from . import router as router_module
+
+API_PREFIX = "/api/monitor"
+
+TOKEN_HEADER = "X-ZUI-Token"
+TOKEN_ENV_VAR = "ZUI_API_TOKEN"
+
+
+class TokenAuthMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        if request.method != "OPTIONS":
+            expected = os.environ.get(TOKEN_ENV_VAR)
+            if expected and not self._authorised(request, expected):
+                return JSONResponse(
+                    status_code=403,
+                    content={"error": "Access forbidden: Invalid or missing token"},
+                )
+        return await call_next(request)
+
+    @staticmethod
+    def _authorised(request: Request, expected: str) -> bool:
+        if request.headers.get(TOKEN_HEADER) == expected:
+            return True
+        # EventSource cannot set headers, so the change stream has to be able to
+        # authenticate by query parameter. Safe enough here: the stream is only
+        # ever reached over loopback or an SSH tunnel.
+        return request.query_params.get("token") == expected
+
+
+@asynccontextmanager
+async def _lifespan(app: FastAPI):
+    # A session may already exist (zmon.cli creates one from argv before
+    # serving), in which case the file poller needs starting now that there is
+    # a running loop.
+    router_module.store.start()
+    try:
+        yield
+    finally:
+        router_module.store.stop()
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(title="zMon", lifespan=_lifespan)
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+    app.add_middleware(TokenAuthMiddleware)
+
+    app.include_router(router_module.router, prefix=API_PREFIX)
+    return app
+
+
+app = create_app()