qodalis-cli-server-plugin-admin 1.0.0b8__tar.gz → 1.0.0b24__tar.gz

{qodalis_cli_server_plugin_admin-1.0.0b8 → qodalis_cli_server_plugin_admin-1.0.0b24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: qodalis-cli-server-plugin-admin
-Version: 1.0.0b8
+Version: 1.0.0b24
 Summary: Admin dashboard plugin for Qodalis CLI servers
 Project-URL: Homepage, https://github.com/qodalis-solutions/cli-server-python
 Project-URL: Repository, https://github.com/qodalis-solutions/cli-server-python
@@ -20,3 +20,4 @@ Requires-Python: >=3.10
 Requires-Dist: fastapi>=0.100.0
 Requires-Dist: psutil>=5.9.0
 Requires-Dist: pyjwt>=2.0.0
+Requires-Dist: qodalis-cli-server-abstractions>=1.0.0b23

{qodalis_cli_server_plugin_admin-1.0.0b8 → qodalis_cli_server_plugin_admin-1.0.0b24}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "qodalis-cli-server-plugin-admin"
-version = "1.0.0b8"
+version = "1.0.0b24"
 description = "Admin dashboard plugin for Qodalis CLI servers"
 readme = { text = "", content-type = "text/plain" }
 license = "MIT"
@@ -27,6 +27,7 @@ dependencies = [
     "PyJWT>=2.0.0",
     "fastapi>=0.100.0",
     "psutil>=5.9.0",
+    "qodalis-cli-server-abstractions>=1.0.0b23",
 ]
 
 [project.urls]

{qodalis_cli_server_plugin_admin-1.0.0b8 → qodalis_cli_server_plugin_admin-1.0.0b24}/qodalis_cli_admin/__init__.py

@@ -6,6 +6,7 @@ from .auth.auth_middleware import create_auth_dependency
 from .auth.auth_controller import create_auth_router
 from .dashboard_resolver import resolve_dashboard_dir
 from .services.admin_config import AdminConfig
+from .services.admin_branding import is_branding_icon, validate_admin_branding
 from .services.admin_theme import (
     ADMIN_THEME_MODES,
     ADMIN_THEME_TOKENS,
@@ -30,7 +31,9 @@ __all__ = [
     "admin_theme_json",
     "create_auth_dependency",
     "create_auth_router",
+    "is_branding_icon",
     "is_theme_color",
     "resolve_dashboard_dir",
+    "validate_admin_branding",
     "validate_admin_theme",
 ]

{qodalis_cli_server_plugin_admin-1.0.0b8 → qodalis_cli_server_plugin_admin-1.0.0b24}/qodalis_cli_admin/auth/auth_controller.py

@@ -4,9 +4,10 @@ from __future__ import annotations
 
 import time
 from collections import defaultdict
-from typing import Any
+from typing import Any, Callable
 
 from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import JSONResponse
 from pydantic import BaseModel
 
 from .jwt_service import JwtService
@@ -52,6 +53,11 @@ class _RateLimiter:
 
 
 ADMIN_ACCESS = "admin:access"
+#: ``GET /auth/mode``: the dashboard's own username/password form.
+MODE_PASSWORD = "password"
+#: ``GET /auth/mode``: sign-in through the host application.
+MODE_EXTERNAL = "external"
+EXTERNAL_AUTH_CODE = "EXTERNAL_AUTH"
 
 
 def trusted_hops(trust_proxy: bool | int | None) -> int:
@@ -107,18 +113,44 @@ def create_auth_router(
     *,
     trust_proxy: bool | int = False,
     users_plugin: Any = None,
+    is_external: Callable[[], bool] | None = None,
 ) -> APIRouter:
-    """Create a FastAPI router with ``POST /login`` and ``GET /me``.
+    """Create a FastAPI router with ``GET /mode``, ``POST /login`` and
+    ``GET /me``.
 
     With ``users_plugin`` the login goes through the users auth service and
     requires the ``admin:access`` permission; the returned token is the
     users session token.  Otherwise the static admin credentials are used.
+    In external sign-in mode (``is_external()``: the server's
+    ``external_authentication``) the login answers 501.
     """
     router = APIRouter()
     limiter = _RateLimiter()
 
+    def external() -> bool:
+        return is_external is not None and is_external()
+
+    @router.get("/mode")
+    async def mode() -> JSONResponse:
+        """Which sign-in the dashboard shows (public).  ``external`` when the
+        host application signs users in (it hands its token to the dashboard
+        through ``/qcli/admin/#token=…``), otherwise ``password``."""
+        return JSONResponse(
+            {"mode": MODE_EXTERNAL if external() else MODE_PASSWORD, "signInUrl": admin_config.sign_in_url},
+            headers={"Cache-Control": "no-store"},
+        )
+
     @router.post("/login", response_model=LoginResponse)
     async def login(body: LoginRequest, request: Request) -> Any:
+        if external():
+            # The static admin credentials sign no one in here.
+            url = admin_config.sign_in_url
+            where = f" at {url}" if url is not None else " through the host application"
+            return JSONResponse(status_code=501, content={
+                "error": f"Sign-in is managed by the host application. Sign in{where}.",
+                "code": EXTERNAL_AUTH_CODE,
+                "signInUrl": url,
+            })
         ip = client_ip(request, trust_proxy)
         limiter.check(ip)
 

{qodalis_cli_server_plugin_admin-1.0.0b8 → qodalis_cli_server_plugin_admin-1.0.0b24}/qodalis_cli_admin/auth/auth_middleware.py

@@ -15,11 +15,18 @@ def create_users_auth_dependency(users_plugin: Any):
     ``admin:access`` (admin ``*`` has it)."""
 
     async def require_auth(request: Request) -> dict[str, Any]:
-        auth_header = request.headers.get("Authorization", "")
-        if not auth_header.startswith("Bearer "):
-            raise HTTPException(status_code=401, detail="Missing or invalid Authorization header")
-        await users_plugin.ensure_seeded()
-        ctx = await users_plugin.auth_service.authenticate_token(auth_header[7:].strip())
+        auth_service = users_plugin.auth_service
+        if auth_service.external_auth:
+            # The host application signs users in: its external auth adapter
+            # authenticates the request (e.g. the bearer token handed to the
+            # dashboard through /qcli/admin/#token=…).
+            ctx = await users_plugin.require_auth(request)
+        else:
+            auth_header = request.headers.get("Authorization", "")
+            if not auth_header.startswith("Bearer "):
+                raise HTTPException(status_code=401, detail="Missing or invalid Authorization header")
+            await users_plugin.ensure_seeded()
+            ctx = await auth_service.authenticate_token(auth_header[7:].strip())
         if ctx.must_change_password:
             raise HTTPException(status_code=403, detail="password change required")
         if not ctx.can("admin:access"):

{qodalis_cli_server_plugin_admin-1.0.0b8 → qodalis_cli_server_plugin_admin-1.0.0b24}/qodalis_cli_admin/cli_admin_builder.py

@@ -2,9 +2,10 @@
 
 from __future__ import annotations
 
+import json
 import os
 import time
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from collections.abc import Mapping
 from typing import Any, Callable, Awaitable
 
@@ -20,9 +21,11 @@ from .controllers.config_controller import create_config_router
 from .controllers.logs_controller import create_logs_router
 from .controllers.ws_clients_controller import create_ws_clients_router
 from .services.admin_config import AdminConfig
-from .services.admin_theme import admin_theme_json
+from .services.admin_branding import validate_admin_branding
+from .services.admin_theme import validate_admin_theme
 from .services.log_ring_buffer import LogRingBuffer
 from .services.module_registry import ModuleRegistry
+from .services.status_history import StatusHistory
 from .dashboard_resolver import resolve_dashboard_dir
 
 
@@ -36,11 +39,20 @@ class AdminBuildDeps:
     registry: Any  # CliCommandRegistry
     event_socket_manager: Any  # CliEventSocketManager
     builder: Any  # CliBuilder
+    #: Where the wire message of every log entry (``log:entry``) goes; by
+    #: default they are published on ``event_bus`` with the audience ``logs:read``.
     broadcast_fn: BroadcastFn | None = None
+    #: The server's event bus (``result.event_bus``); taken from the server
+    #: by ``mount_plugin`` when neither it nor ``broadcast_fn`` is given.
+    event_bus: Any = None
     enabled_features: list[str] | None = None
     #: When set, the dashboard authenticates through the users plugin
     #: (``admin:access`` permission); static credentials are not used.
     users_plugin: Any = None
+    #: The server's ``CliServerOptions`` (``result.options``): its
+    #: ``external_authentication`` selects the dashboard's sign-in mode.
+    #: Taken from the server by ``mount_plugin`` when not given.
+    server_options: Any = None
 
 
 @dataclass
@@ -54,6 +66,28 @@ class CliAdminPlugin:
     log_buffer: LogRingBuffer
     dashboard_app: Any  # ASGI app (SPA fallback) or None
     module_registry: ModuleRegistry | None = None
+    #: Status samples of ``GET /status/history``; sampling runs with the
+    #: app's lifespan once the plugin is mounted.
+    status_history: StatusHistory | None = None
+    #: Holds the server options read by ``GET /auth/mode`` (see on_mount).
+    _server: dict = field(default_factory=dict, repr=False)
+
+    def on_mount(self, server: Any) -> None:
+        """Hook called by ``CliServerResult.mount_plugin``: the sign-in mode
+        follows the server's ``options.external_authentication`` and the log
+        entries go to the server's event bus."""
+        if self._server.get("options") is None:
+            self._server["options"] = getattr(server, "options", None)
+        # Log entries are published on the server's bus (``log:entry``, audience ``logs:read``)
+        # unless the plugin was built with a bus or a broadcast function
+        if self.log_buffer.event_bus is None and self.log_buffer.broadcast_fn is None:
+            self.log_buffer.event_bus = getattr(server, "event_bus", None)
+        app = getattr(server, "app", None)
+        router = getattr(app, "router", None)
+        if self.status_history is not None and router is not None and not self._server.get("sampling"):
+            # Sample while the app runs; cancelled on shutdown.
+            router.lifespan_context = self.status_history.wrap_lifespan(router.lifespan_context)
+            self._server["sampling"] = True
 
 
 class CliAdminBuilder:
@@ -66,7 +100,9 @@ class CliAdminBuilder:
         self._dashboard_path: str | None = None
         self._trust_proxy = False
         self._users_plugin: Any = None
-        self._theme_json: bytes = admin_theme_json(None)
+        self._theme: dict[str, Any] = validate_admin_theme(None)
+        self._branding: dict[str, Any] | None = None
+        self._sign_in_url: str | None = None
 
     def set_credentials(self, username: str, password: str) -> CliAdminBuilder:
         """Set admin login credentials (overrides env vars)."""
@@ -112,7 +148,34 @@ class CliAdminBuilder:
                 "dark": {"primary": "#4f9be0", "background": "#0d1823"},
             })
         """
-        self._theme_json = admin_theme_json(theme)
+        self._theme = validate_admin_theme(theme)
+        return self
+
+    def set_branding(self, branding: Mapping[str, Any]) -> CliAdminBuilder:
+        """Ship the dashboard under your own name and icon, and name its terminal.
+
+        ``{"name": "RateBell", "icon_url": "/favicon.svg", "cli_name": "RateBell CLI"}``:
+        the name and icon of the browser tab, sidebar and sign-in page, and the
+        terminal's name in its welcome banner. The icon is an absolute http(s)
+        URL, a root-relative path or a base64 ``data:image`` URL. Unset values
+        keep the Qodalis defaults (Qodalis Cli Admin, the Qodalis Solutions
+        logo, Web CLI); a bad value raises :class:`ValueError` here.
+        """
+        self._branding = validate_admin_branding(branding)
+        return self
+
+    def _theme_json(self) -> bytes:
+        """The ``theme.json`` body: the color scheme, plus ``branding`` when set."""
+        doc = {**self._theme, "branding": self._branding} if self._branding else self._theme
+        return json.dumps(doc, separators=(",", ":")).encode()
+
+    def set_sign_in_url(self, url: str | None) -> CliAdminBuilder:
+        """Where the host application signs users in, shown by the dashboard
+        in external sign-in mode (users plugin with an external auth adapter)
+        and returned by ``GET /api/v1/qcli/auth/mode``.  An absolute
+        ``http(s)`` URL or a root-relative path (``/sign-in``); anything else
+        raises :class:`ValueError` in :meth:`build`."""
+        self._sign_in_url = url
         return self
 
     def set_users_plugin(self, users_plugin: Any) -> CliAdminBuilder:
@@ -130,9 +193,15 @@ class CliAdminBuilder:
             password=self._password,
             jwt_secret=self._jwt_secret,
             warn_default=users_plugin is None,
+            sign_in_url=self._sign_in_url,
         )
+        config.validate()
+        server: dict = {"options": deps.server_options}
+
+        def is_external() -> bool:
+            return bool(getattr(server["options"], "external_authentication", False))
         jwt_service = JwtService(secret=config.jwt_secret)
-        log_buffer = LogRingBuffer(broadcast_fn=deps.broadcast_fn)
+        log_buffer = LogRingBuffer(broadcast_fn=deps.broadcast_fn, event_bus=deps.event_bus)
         log_buffer.install_handler()
         module_registry = ModuleRegistry(deps.builder)
         if users_plugin is not None:
@@ -148,6 +217,7 @@ class CliAdminBuilder:
         auth_router = create_auth_router(
             config, jwt_service, auth_dependency=auth_dep,
             trust_proxy=self._trust_proxy, users_plugin=users_plugin,
+            is_external=is_external,
         )
         router.include_router(auth_router, prefix="/auth")
 
@@ -166,13 +236,15 @@ class CliAdminBuilder:
                     enabled_features.append("jobs")
                     break
 
+        status_history = StatusHistory(deps.event_socket_manager)
         status_router = create_status_router(
             start_time, deps.event_socket_manager, auth_dep, enabled_features,
-            registry=deps.registry,
+            registry=deps.registry, builder=deps.builder,
+            status_history=status_history,
         )
         router.include_router(status_router)
 
-        plugins_router = create_plugins_router(module_registry, auth_dep)
+        plugins_router = create_plugins_router(module_registry, auth_dep, deps.builder)
         router.include_router(plugins_router)
 
         config_router = create_config_router(config, auth_dep)
@@ -189,7 +261,7 @@ class CliAdminBuilder:
 
         if dashboard_dir:
             dashboard_app = SPAStaticFiles(
-                directory=dashboard_dir, html=True, theme_json=self._theme_json,
+                directory=dashboard_dir, html=True, theme_json=self._theme_json(),
             )
 
         return CliAdminPlugin(
@@ -200,4 +272,6 @@ class CliAdminBuilder:
             log_buffer=log_buffer,
             dashboard_app=dashboard_app,
             module_registry=module_registry,
+            status_history=status_history,
+            _server=server,
         )

qodalis_cli_server_plugin_admin-1.0.0b24/qodalis_cli_admin/controllers/logs_controller.py

@@ -0,0 +1,102 @@
+"""Logs controller — query the log ring buffer."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Depends, Query
+from fastapi.responses import JSONResponse
+
+from ..services.log_ring_buffer import HISTOGRAM_LEVELS, LogRingBuffer, histogram_level
+from ..services.time_range import RangeError, parse_buckets, parse_time, resolve_range
+
+
+def _levels(level: str | None) -> list[str]:
+    """The histogram levels named in ``level`` (comma-separated);
+    :class:`RangeError` for an unknown one."""
+    levels: list[str] = []
+    for name in (level or "").split(","):
+        if not name.strip():
+            continue
+        normalized = histogram_level(name)
+        if normalized is None:
+            raise RangeError(f"Unknown level '{name.strip()}': use {', '.join(HISTOGRAM_LEVELS)}.")
+        if normalized not in levels:
+            levels.append(normalized)
+    return levels
+
+
+def create_logs_router(
+    log_buffer: LogRingBuffer,
+    auth_dependency: Any,
+) -> APIRouter:
+    """Create a router with ``GET /logs`` and ``GET /logs/histogram``."""
+    router = APIRouter()
+
+    @router.get("/logs")
+    async def get_logs(
+        _user: dict[str, Any] = Depends(auth_dependency),
+        level: str | None = Query(None),
+        search: str | None = Query(None),
+        service: str | None = Query(None),
+        from_: str | None = Query(None, alias="from"),
+        to: str | None = Query(None),
+        limit: int = Query(100, le=1000),
+        offset: int = Query(0, ge=0),
+    ) -> Any:
+        """Buffered entries filtered by level, search, service and the time
+        range ``[from, to)`` (ISO 8601, no offset = UTC)."""
+        try:
+            since = parse_time(from_, "from")
+            until = parse_time(to, "to")
+        except RangeError as exc:
+            return JSONResponse(status_code=400, content={"error": str(exc)})
+        items, total = log_buffer.query(
+            level=level,
+            search=search,
+            service=service.strip() if service and service.strip() else None,
+            since=since,
+            until=until,
+            limit=limit,
+            offset=offset,
+        )
+        return {
+            "entries": items,
+            "total": total,
+            "limit": limit,
+            "offset": offset,
+            "hasMore": offset + len(items) < total,
+            # The dashboard filters on the server when it names its store.
+            "store": "memory",
+            "persistent": False,
+            "services": [],
+        }
+
+    @router.get("/logs/histogram")
+    async def get_logs_histogram(
+        _user: dict[str, Any] = Depends(auth_dependency),
+        from_: str | None = Query(None, alias="from"),
+        to: str | None = Query(None),
+        buckets: str | None = Query(None),
+        level: str | None = Query(None),
+        search: str | None = Query(None),
+        service: str | None = Query(None),
+    ) -> Any:
+        """Log entries per level in equal time columns of ``[from, to)``
+        (default: the last 24 hours), with the filters of ``GET /logs``."""
+        try:
+            since, until = resolve_range(from_, to)
+            count = parse_buckets(buckets)
+            levels = _levels(level)
+        except RangeError as exc:
+            return JSONResponse(status_code=400, content={"error": str(exc)})
+        return log_buffer.histogram(
+            since,
+            until,
+            count,
+            levels=levels or None,
+            search=search or None,
+            service=service.strip() if service and service.strip() else None,
+        )
+
+    return router

{qodalis_cli_server_plugin_admin-1.0.0b8 → qodalis_cli_server_plugin_admin-1.0.0b24}/qodalis_cli_admin/controllers/plugins_controller.py

@@ -13,10 +13,21 @@ from ..services.module_registry import ModuleRegistry
 def create_plugins_router(
     module_registry: ModuleRegistry,
     auth_dependency: Any,
+    builder: Any = None,
 ) -> APIRouter:
-    """Create a router with ``GET /plugins`` and ``POST /plugins/{id}/toggle``."""
+    """Create a router with ``GET /plugins``, ``GET /plugins/installed`` and
+    ``POST /plugins/{id}/toggle``."""
     router = APIRouter()
 
+    @router.get("/plugins/installed")
+    async def list_installed_plugins(
+        _user: dict[str, Any] = Depends(auth_dependency),
+    ) -> list[dict[str, Any]]:
+        """The installed server plugin packages (core, users, admin, jobs,
+        storage providers, ...) with their versions, in the order added."""
+        plugins = getattr(builder, "installed_plugins", None) or []
+        return [p.to_dict() for p in plugins]
+
     @router.get("/plugins")
     async def list_plugins(
         _user: dict[str, Any] = Depends(auth_dependency),

qodalis_cli_server_plugin_admin-1.0.0b24/qodalis_cli_admin/controllers/status_controller.py

@@ -0,0 +1,100 @@
+"""Status controller — server health and runtime information."""
+
+from __future__ import annotations
+
+import platform
+import time
+from datetime import datetime, timezone
+from typing import Any
+
+from fastapi import APIRouter, Depends, Query
+from fastapi.responses import JSONResponse
+
+from ..services.status_history import StatusHistory, memory_usage_mb
+
+#: ``GET /status/history``: default and longest window in minutes.
+DEFAULT_HISTORY_MINUTES = 60
+MAX_HISTORY_MINUTES = 1440
+
+
+def create_status_router(
+    start_time: float,
+    event_socket_manager: Any,
+    auth_dependency: Any,
+    enabled_features: list[str] | None = None,
+    registry: Any = None,
+    builder: Any = None,
+    status_history: StatusHistory | None = None,
+) -> APIRouter:
+    """Create a router that exposes ``GET /status`` and ``GET /status/history``."""
+    router = APIRouter()
+
+    @router.get("/status")
+    async def get_status(
+        _user: dict[str, Any] = Depends(auth_dependency),
+    ) -> dict[str, Any]:
+        uptime_seconds = time.time() - start_time
+
+        started_at = datetime.fromtimestamp(
+            start_time, tz=timezone.utc
+        ).isoformat()
+
+        registered_commands = len(registry.processors) if registry is not None else 0
+
+        return {
+            "uptimeSeconds": uptime_seconds,
+            "memoryUsageMb": memory_usage_mb(),
+            "startedAt": started_at,
+            "platform": "python",
+            "platformVersion": platform.python_version(),
+            "os": f"{platform.system()} {platform.release()}",
+            "activeWsConnections": len(event_socket_manager.get_clients()),
+            "activeShellSessions": 0,
+            "registeredCommands": registered_commands,
+            "registeredJobs": 0,
+            "enabledFeatures": _features(enabled_features, builder),
+        }
+
+    @router.get("/status/history")
+    async def get_status_history(
+        _user: dict[str, Any] = Depends(auth_dependency),
+        minutes: str | None = Query(None),
+    ) -> Any:
+        """The status samples (every 15 s, kept 24 h) of the last ``minutes``
+        (default 60, clamped to 1..1440), oldest first."""
+        window = DEFAULT_HISTORY_MINUTES
+        if minutes is not None and minutes.strip():
+            try:
+                window = int(minutes.strip())
+            except ValueError:
+                return JSONResponse(
+                    status_code=400,
+                    content={"error": f"'minutes' must be an integer, got '{minutes}'"},
+                )
+        window = min(max(window, 1), MAX_HISTORY_MINUTES)
+        history = status_history or StatusHistory(event_socket_manager)
+        return {
+            "intervalSeconds": history.interval,
+            "samples": history.history(window),
+        }
+
+    return router
+
+
+JOBS_DISTRIBUTION = "qodalis-cli-server-plugin-jobs"
+#: The audit plugin (the admin plugin does not depend on it).
+AUDIT_DISTRIBUTION = "qodalis-cli-server-plugin-audit"
+
+
+def _features(enabled_features: list[str] | None, builder: Any) -> list[str]:
+    """The enabled features (filesystem, jobs, audit, in that order): ``jobs``
+    when the jobs plugin is mounted, ``audit`` when the audit plugin (which
+    serves the audit log, ``GET /api/v1/qcli/audit``; the users plugin mounts
+    it) is."""
+    features = list(enabled_features or [])
+    installed = {p.id for p in (getattr(builder, "installed_plugins", None) or [])}
+    if "jobs" not in features and JOBS_DISTRIBUTION in installed:
+        features.append("jobs")
+    if "audit" not in features and AUDIT_DISTRIBUTION in installed:
+        features.append("audit")
+    return features