asyncz 0.14.0__tar.gz → 0.14.2__tar.gz

{asyncz-0.14.0 → asyncz-0.14.2}/.gitignore

@@ -17,6 +17,7 @@ results/
 site/
 target/
 
+*.zip
 # files
 **/*.so
 **/*.sqlite

{asyncz-0.14.0 → asyncz-0.14.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asyncz
-Version: 0.14.0
+Version: 0.14.2
 Summary: The scheduler that nobody wants but every application needs.
 Project-URL: Homepage, https://github.com/dymmond/asyncz
 Project-URL: Documentation, https://asyncz.dymmond.com/
@@ -41,7 +41,7 @@ Requires-Dist: monkay>=0.5.0
 Requires-Dist: pydantic<3.0.0,>=2.5.3
 Requires-Dist: sayer>=0.7.4
 Provides-Extra: dashboard
-Requires-Dist: lilya[standard]>=0.22.11; extra == 'dashboard'
+Requires-Dist: lilya[standard]>=0.22.15; extra == 'dashboard'
 Provides-Extra: docs
 Requires-Dist: griffe-typingdoc<1.0,>=0.2.2; extra == 'docs'
 Requires-Dist: mdx-include>=1.4.2; extra == 'docs'
@@ -61,7 +61,7 @@ Provides-Extra: testing
 Requires-Dist: freezegun; extra == 'testing'
 Requires-Dist: httpx; extra == 'testing'
 Requires-Dist: ipdb; extra == 'testing'
-Requires-Dist: lilya[standard]>=0.22.11; extra == 'testing'
+Requires-Dist: lilya[standard]>=0.22.15; extra == 'testing'
 Requires-Dist: loguru<0.8.0,>=0.7.0; extra == 'testing'
 Requires-Dist: mypy<2.0.0,>=0.982; extra == 'testing'
 Requires-Dist: pymongo<5.0.0,>=4.3.3; extra == 'testing'

{asyncz-0.14.0 → asyncz-0.14.2}/asyncz/__init__.py

@@ -2,7 +2,7 @@ from typing import TYPE_CHECKING
 
 from .monkay import create_monkay
 
-__version__ = "0.14.0"
+__version__ = "0.14.2"
 
 if TYPE_CHECKING:
     from .conf import settings

{asyncz-0.14.0 → asyncz-0.14.2}/asyncz/contrib/dashboard/admin/backends.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from collections.abc import Callable
 from typing import Any
 
+from lilya.compat import reverse
 from lilya.datastructures import FormData
 from lilya.requests import Request
 from lilya.responses import RedirectResponse, Response
@@ -103,8 +104,8 @@ class SimpleUsernamePasswordBackend(AuthBackend):
         }
 
         # Redirect to the requested 'next' URL or default to root
-        nxt: str = form.get("next") or "/"
-        return RedirectResponse(nxt, status_code=303)
+        next: str = form.get("next") or reverse("dashboard:index")
+        return RedirectResponse(next, status_code=303)
 
     async def logout(self, request: Request) -> Response:
         """
@@ -118,5 +119,4 @@ class SimpleUsernamePasswordBackend(AuthBackend):
         """
         # Remove user data from the session
         request.session.pop(self.session_key, None)
-
-        return RedirectResponse("/login", status_code=303)
+        return RedirectResponse(reverse("login"), status_code=303)

asyncz-0.14.2/asyncz/contrib/dashboard/admin/core.py

@@ -0,0 +1,280 @@
+from __future__ import annotations
+
+from functools import cached_property
+from typing import Any, cast
+
+from lilya.apps import ChildLilya, Lilya
+from lilya.middleware.base import DefineMiddleware
+from lilya.middleware.cors import CORSMiddleware
+from lilya.requests import Request
+from lilya.responses import Response
+from lilya.routing import Include, Path, Router
+from lilya.types import ASGIApp
+
+from asyncz import monkay
+from asyncz.contrib.dashboard import create_dashboard_app
+from asyncz.contrib.dashboard.admin.middleware import AuthGateMiddleware
+from asyncz.contrib.dashboard.admin.middleware.forward_root_path import (
+    ForwardedPrefixMiddleware,
+)
+from asyncz.contrib.dashboard.admin.protocols import AuthBackend
+from asyncz.contrib.dashboard.engine import templates
+from asyncz.contrib.dashboard.logs.storage import LogStorage
+from asyncz.schedulers.asyncio import AsyncIOScheduler
+
+
+async def not_found(request: Request, exc: Exception) -> Any:
+    return templates.get_template_response(
+        request,
+        "404.html",
+        context={
+            "title": "Not Found",
+            "url_prefix": monkay.settings.dashboard_config.dashboard_url_prefix,
+        },
+        status_code=404,
+    )
+
+
+class AsynczAdmin:
+    """
+    A configurable wrapper for the Asyncz web dashboard and management API.
+
+    This class handles the creation of a private `ChildLilya` application, configures
+    CORS, session management, and optional authentication (via AuthGateMiddleware),
+    and exposes a method to mount itself onto a parent Lilya application.
+    """
+
+    def __init__(
+        self,
+        enable_login: bool = False,
+        backend: AuthBackend | None = None,
+        enable_forward_middleware: bool = False,
+        url_prefix: str | None = None,
+        scheduler: AsyncIOScheduler | None = None,
+        include_session: bool = True,
+        include_cors: bool = True,
+        login_path: str = "/login",
+        allowlist: tuple[str, ...] = ("/login", "/logout", "/static", "/assets"),
+        log_storage: LogStorage | None = None,
+    ) -> None:
+        """
+        Initializes the Asyncz Admin dashboard instance.
+
+        Args:
+            enable_login: If True, enables session and authentication middleware, requiring a `backend`.
+            backend: The authentication backend implementing `AuthBackend` methods (required if `enable_login` is True).
+            url_prefix: The base URL path where the dashboard should be mounted (e.g., "/asyncz").
+                        Defaults to the value from `monkay.settings.dashboard_config`.
+            scheduler: The active `AsyncIOScheduler` instance to manage. If None, a new
+                       default scheduler is created (in-memory store).
+
+        Raises:
+            ValueError: If `enable_login` is True but no `backend` is provided.
+        """
+        if enable_login and not backend:
+            raise ValueError("`backend` must not be `None` when enable login is True")
+
+        # Resolve defaults
+        self.config = monkay.settings.dashboard_config
+        self.url_prefix: str = (url_prefix or self.config.dashboard_url_prefix).rstrip("/")
+        self.scheduler: AsyncIOScheduler = scheduler or AsyncIOScheduler(
+            stores={"default": {"type": "memory"}}
+        )
+
+        assert self.url_prefix.startswith("/"), "The dashboard url prefix must start with /."
+
+        self.enable_login: bool = enable_login
+        self.backend: AuthBackend = backend  # type: ignore[assignment]
+        self.enable_forward_middleware = enable_forward_middleware
+
+        # Extras
+        self.include_session = include_session
+        self.include_cors = include_cors
+        self.login_path = login_path
+        self.allowlist = allowlist
+
+        # Build the internal dashboard routing application immediately
+        self.log_storage: LogStorage | None = log_storage
+        self.child_app: Router = self.assemble_dashboard_router()
+
+    def add_sign_in_pages(self) -> list[Path | Include]:
+        """
+        Defines and registers the routes required for user login and logout pages.
+
+        This function delegates the core logic for rendering the form (GET) and processing
+        credentials/clearing sessions (POST) to the configured authentication backend (`self.backend`).
+
+        Returns:
+            A list of `Path` objects for the `/login` and `/logout` endpoints, ready
+            to be included in the application's routing table.
+        """
+        # The list of routes to be returned
+        routes: list[Path | Include] = []
+
+        # Assert self has backend attribute (required by logic)
+        backend: AuthBackend = self.backend
+
+        async def login(request: Request) -> Response:
+            """
+            Handler for the `/login` route. Delegates GET (form rendering) and
+            POST (credential processing) to the authentication backend.
+            """
+            return await backend.login(request)
+
+        async def logout(request: Request) -> Response:
+            """
+            Handler for the `/logout` route. Delegates the session clearing logic
+            to the authentication backend.
+            """
+            return await backend.logout(request)
+
+        # 1. Add /login route
+        routes.append(Path("/login", login, methods=["GET", "POST"], name="login"))
+
+        # 2. Add /logout route
+        routes.append(Path("/logout", logout, methods=["GET", "POST"], name="logout"))
+
+        return routes
+
+    @cached_property
+    def cors_middleware(self) -> DefineMiddleware:
+        """
+        Creates and caches the necessary middleware definition for handling HTTP requests,
+        specifically configuring **Cross-Origin Resource Sharing (CORS)**.
+
+        This property returns a single `DefineMiddleware` instance configured to be highly
+        permissive for development environments (`allow_origins=["*"]`, etc.).
+
+        The result is cached using `@cached_property`, meaning the configuration dictionary
+        is generated only once per object instance.
+
+        Returns:
+            DefineMiddleware: The fully configured middleware definition for CORS.
+                              (Though the type hint is often simplified to list[DefineMiddleware]
+                              in the consuming context, the property returns a single instance).
+        """
+        return DefineMiddleware(
+            CORSMiddleware,
+            allow_origins=["*"],
+            allow_methods=["*"],
+            allow_headers=["*"],
+            allow_credentials=True,
+        )
+
+    @cached_property
+    def auth_gate_middleware(self) -> DefineMiddleware:
+        """
+        Creates and caches the necessary middleware definition for enforcing authentication
+        across the dashboard application.
+
+        This middleware uses the configured `self.backend`'s `authenticate` method to
+        verify the user's credentials on every request, redirecting unauthorized users
+        to `self.login_path`, unless the path is in `self.allowlist`.
+
+        The result is cached using `@cached_property`, ensuring the middleware definition
+        is constructed only once per object instance.
+
+        Returns:
+            DefineMiddleware: The fully configured authentication gate middleware definition.
+        """
+        return DefineMiddleware(
+            AuthGateMiddleware,
+            authenticate=self.backend.authenticate,
+            login_path=self.login_path,
+            allowlist=self.allowlist,
+        )
+
+    def assemble_dashboard_router(self) -> Router:
+        """
+        Constructs the internal `ChildLilya` application with all necessary middlewares
+        and routes (dashboard, login/logout).
+
+        Returns:
+            The fully configured `ChildLilya` application instance.
+        """
+        # 1. Create the router app
+        app: Router = Router(
+            routes=[
+                Include(
+                    "/",
+                    app=create_dashboard_app(
+                        scheduler=self.scheduler, log_storage=self.log_storage
+                    ),
+                ),
+            ],
+        )
+
+        return app
+
+    def include_in(self, app: Lilya) -> None:
+        """
+        Mount the composed dashboard app at the host root.
+
+        The composed app (built with `with_url_prefix=True`) already:
+          - mounts the dashboard router under `self.url_prefix` (e.g., /dashboard)
+          - exposes root-level `/login` and `/logout` routes
+        So mounting it at "/" yields the desired final URLs:
+          - /login, /logout
+          - {self.url_prefix}/...
+        """
+        composed: ASGIApp = self.get_asgi_app(with_url_prefix=True)
+        app.add_child_lilya("/", cast(ChildLilya, composed))
+
+    def get_asgi_app(self, with_url_prefix: bool = False) -> ASGIApp | Lilya | ChildLilya:
+        """
+        Constructs and returns the final, self-contained ASGI application for the dashboard,
+        complete with nested routing, middleware, and authentication gates.
+
+        Args:
+            self: The instance of the class (e.g., AsynczAdmin) holding the configuration.
+            with_url_prefix: If `True`, mounts the application under `self.url_prefix`.
+                             If `False` (default), mounts it directly under the root `/`.
+
+        Returns:
+            ASGIApp | Lilya | ChildLilya: The top-level `Lilya` application instance, ready to be served.
+        """
+        # Determine the base path for mounting the application's internal routes
+        base: str = self.url_prefix if with_url_prefix else "/"
+        base_norm = "/" if base == "/" else base.rstrip("/")
+
+        # 1. Build Inner Routes (Dashboard Core + Auth Pages)
+        inner_routes: list[Path | Include] = [
+            Include("/", app=self.child_app)  # Mount the core dashboard routes
+        ]
+
+        # 2. Build Top-Level Routes (Mounting everything under the final prefix)
+        routes: list[Path | Include] = [
+            Include(path=base_norm, routes=inner_routes, name="dashboard")
+        ]
+        if self.enable_login:
+            # Add /login and /logout handlers if authentication is enabled at root level
+            routes.extend(self.add_sign_in_pages())
+
+        # 3. Build Middleware Stack (Order is critical)
+        middlewares: list[DefineMiddleware] = []
+
+        if self.enable_forward_middleware:
+            # X-Forwarded-Prefix handling (useful if mounted via proxy)
+            middlewares.append(DefineMiddleware(ForwardedPrefixMiddleware))
+
+        if self.include_cors:
+            # CORS handling
+            middlewares.append(self.cors_middleware)
+
+        if self.include_session:
+            # Session handling (required for SimpleUsernamePasswordBackend)
+            middlewares.append(self.config.session_middleware)
+
+        if self.enable_login:
+            # Authentication enforcement
+            middlewares.append(self.auth_gate_middleware)
+
+        # 4. Create Final Lilya Application
+        return cast(
+            ASGIApp,
+            Lilya(
+                routes=routes,
+                middleware=middlewares,
+                exception_handlers={404: not_found},
+            ),
+        )

asyncz-0.14.2/asyncz/contrib/dashboard/admin/middleware/__init__.py

@@ -0,0 +1,3 @@
+from .auth_gate import AuthGateMiddleware
+
+__all__ = ["AuthGateMiddleware"]

asyncz-0.14.2/asyncz/contrib/dashboard/admin/middleware/forward_root_path.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from lilya.types import ASGIApp, Receive, Scope, Send
+
+
+class ForwardedPrefixMiddleware:
+    """
+    ASGI middleware that automatically updates the `scope['root_path']` based on the
+    `X-Forwarded-Prefix` header provided by a reverse proxy (like Nginx).
+
+    This ensures that internal framework components, such as `url_for()` and `StaticFiles`,
+    generate correct absolute URLs that include the proxy's mount prefix (e.g., /base/static).
+    """
+
+    def __init__(self, app: ASGIApp, header_name: bytes = b"x-forwarded-prefix"):
+        """
+        Initializes the middleware.
+
+        Args:
+            app: The next ASGI application in the stack.
+            header_name: The byte string name of the HTTP header to check for the prefix.
+                         Defaults to `b"x-forwarded-prefix"`.
+        """
+        self.app: ASGIApp = app
+        self.header_name: bytes = header_name
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """
+        The ASGI entry point. Processes headers and updates the scope's root_path if necessary.
+
+        Args:
+            scope: The ASGI scope dictionary.
+            receive: The ASGI receive callable.
+            send: The ASGI send callable.
+        """
+        if scope["type"] in ("http", "websocket"):
+            # Normalize headers to a dictionary for easy, case-insensitive lookup
+            headers: dict[bytes, bytes] = {k.lower(): v for k, v in scope.get("headers", [])}
+
+            prefix_bytes: bytes | None = headers.get(self.header_name.lower())
+
+            if prefix_bytes:
+                # Decode and strip the prefix value
+                p: str = prefix_bytes.decode("latin-1").strip()
+
+                if p and p != "/":
+                    # 1. Ensure leading slash (e.g., 'base' -> '/base')
+                    if not p.startswith("/"):
+                        p = "/" + p
+
+                    # 2. Strip trailing slash unless it's just '/'
+                    if p != "/":
+                        p = p.rstrip("/")
+
+                    # 3. Combine with any existing root_path
+                    existing: str = scope.get("root_path") or ""
+
+                    # Ensure existing root_path also has a leading slash
+                    if existing and not existing.startswith("/"):
+                        existing = "/" + existing
+
+                    # Concatenate and clean up trailing slash (result is either '/base' or '/')
+                    combined: str = (p + existing).rstrip("/") or "/"
+
+                    # 4. Create a copy of the scope and update root_path
+                    scope = dict(scope)
+                    scope["root_path"] = combined
+
+        # Pass control to the next application
+        await self.app(scope, receive, send)

{asyncz-0.14.0 → asyncz-0.14.2}/asyncz/contrib/dashboard/application.py

@@ -1,12 +1,15 @@
+import logging
 from typing import Any
 
-from lilya.apps import Lilya
-from lilya.requests import Request
-from lilya.routing import Include, RoutePath
+from lilya.routing import Include, RoutePath, Router
 from lilya.staticfiles import StaticFiles
 
-from asyncz import monkay
 from asyncz.contrib.dashboard.controllers import home
+from asyncz.contrib.dashboard.controllers.logs import (
+    LogsPageController,
+    LogsTablePartialController,
+    get_log_storage,
+)
 from asyncz.contrib.dashboard.controllers.tasks import (
     TaskBulkPauseController,
     TaskBulkRemoveController,
@@ -20,32 +23,32 @@ from asyncz.contrib.dashboard.controllers.tasks import (
     TasklistController,
     TaskTablePartialController,
 )
-from asyncz.contrib.dashboard.engine import templates
-
-
-async def not_found(request: Request, exc: Exception) -> Any:
-    return templates.get_template_response(
-        request,
-        "404.html",
-        context={
-            "title": "Not Found",
-            "url_prefix": monkay.settings.dashboard_config.dashboard_url_prefix,
-        },
-        status_code=404,
-    )
+from asyncz.contrib.dashboard.logs.handler import install_task_log_handler
+from asyncz.contrib.dashboard.logs.storage import LogStorage
 
 
-def create_dashboard_app(scheduler: Any) -> Lilya:
+def create_dashboard_app(scheduler: Any, log_storage: LogStorage | None = None) -> Router:
     """
     Build a Lilya sub-application wired to an AsyncZ AsyncIOScheduler.
     The scheduler must be a live scheduler instance owned by the host app.
     """
-    app = Lilya(
+    install_task_log_handler(storage=get_log_storage(storage=log_storage))
+
+    # Ensure stdlib logs on the namespaced logger bubble up to our handler.
+    # Our TaskLogHandler is installed by install_task_log_handler() on a parent logger.
+    # Make sure the child logger used by tests (`asyncz.task`) propagates upward.
+    logging.getLogger("asyncz").setLevel(logging.INFO)
+    logging.getLogger("asyncz").propagate = True
+
+    app = Router(
         routes=[
-            RoutePath(
-                "/",
-                home.DashboardController.with_init(scheduler=scheduler),
-                name="dashboard:index",
+            Include(
+                path="/logs",
+                routes=[
+                    RoutePath("/", LogsPageController, name="index"),
+                    RoutePath("/partials/table", LogsTablePartialController, name="table"),
+                ],
+                name="logs",
             ),
             Include(
                 path="/tasks",
@@ -53,66 +56,71 @@ def create_dashboard_app(scheduler: Any) -> Lilya:
                     RoutePath(
                         "/",
                         TasklistController.with_init(scheduler=scheduler),
-                        name="tasks:index",
+                        name="index",
                     ),
                     RoutePath(
                         "/partials/table",
                         TaskTablePartialController.with_init(scheduler=scheduler),
-                        name="tasks:table",
+                        name="table",
                     ),
                     RoutePath(
                         "/create",
                         TaskCreateController.with_init(scheduler=scheduler),
-                        name="tasks:create",
+                        name="create",
                     ),
                     RoutePath(
                         "/hx/bulk/pause",
                         TaskBulkPauseController.with_init(scheduler=scheduler),
-                        name="tasks:bulk_pause",
+                        name="bulk_pause",
                     ),
                     RoutePath(
                         "/hx/bulk/resume",
                         TaskBulkResumeController.with_init(scheduler=scheduler),
-                        name="tasks:bulk_resume",
+                        name="bulk_resume",
                     ),
                     RoutePath(
                         "/hx/bulk/remove",
                         TaskBulkRemoveController.with_init(scheduler=scheduler),
-                        name="tasks:bulk_remove",
+                        name="bulk_remove",
                     ),
                     RoutePath(
                         "/hx/bulk/run",
                         TaskBulkRunController.with_init(scheduler=scheduler),
-                        name="tasks:bulk_run",
+                        name="bulk_run",
                     ),
                     RoutePath(
                         "/{task_id:str}/run",
                         TaskHXRunController.with_init(scheduler=scheduler),
-                        name="tasks:hx_run",
+                        name="hx_run",
                     ),
                     RoutePath(
                         "/{task_id:str}/pause",
                         TaskHXPauseController.with_init(scheduler=scheduler),
-                        name="tasks:hx_pause",
+                        name="hx_pause",
                     ),
                     RoutePath(
                         "/{task_id:str}/resume",
                         TaskHXResumeController.with_init(scheduler=scheduler),
-                        name="tasks:hx_resume",
+                        name="hx_resume",
                     ),
                     RoutePath(
                         "/{task_id:str}/remove",
                         TaskHXRemoveController.with_init(scheduler=scheduler),
-                        name="tasks:hx_remove",
+                        name="hx_remove",
                     ),
                 ],
+                name="tasks",
             ),
             Include(
                 "/static",
                 app=StaticFiles(packages=["asyncz.contrib.dashboard"], html=True),
                 name="statics",
             ),
+            RoutePath(
+                "/",
+                home.DashboardController.with_init(scheduler=scheduler),
+                name="index",
+            ),
         ],
-        exception_handlers={404: not_found},
     )
     return app

{asyncz-0.14.0 → asyncz-0.14.2}/asyncz/contrib/dashboard/config.py

@@ -1,6 +1,8 @@
 import secrets
 from dataclasses import dataclass
-from typing import Literal, cast
+from typing import Literal
+
+from lilya.requests import Request
 
 try:
     from lilya.middleware import DefineMiddleware
@@ -95,13 +97,37 @@ class DashboardConfig:
         )
 
 
-def get_effective_prefix() -> str:
-    """Compute an absolute dashboard base path, combining ASGI root_path and the
-    configured dashboard URL prefix.
+def _normalize_prefix(value: str | None) -> str:
+    """Ensure a leading slash and remove trailing slash (except for root)."""
+    if not value:
+        return "/"
+    v = value.strip()
+    if not v.startswith("/"):
+        v = "/" + v
+    return v if v == "/" else v.rstrip("/")
+
 
-    Guarantees:
-    - Always starts with '/'
-    - No trailing slash (except when the result is exactly '/')
-    - Never double-appends the configured prefix if it's already in root_path
+def get_effective_prefix(request: Request | None = None) -> str:
+    """Compute the effective base URL prefix for the dashboard.
+
+    - If *request* is **None**, return the configured dashboard prefix exactly as before
+      (leading '/', no trailing '/', except when it is '/'). This preserves
+      backward compatibility with tests that called the old zero-arg function.
+    - If *request* is provided, combine ASGI mount ``root_path`` (if any) with the
+      configured prefix, avoiding double-prefixing and double slashes.
     """
-    return cast(str, monkay.settings.dashboard_config.dashboard_url_prefix)
+    configured_prefix = _normalize_prefix(
+        getattr(monkay.settings.dashboard_config, "dashboard_url_prefix", "/")
+    )
+
+    # Prefer the configured prefix when it's meaningful (not '/')
+    if configured_prefix != "/":
+        return configured_prefix
+
+    # Only when configured is '/' do we consider the mount root
+    if request is not None:
+        scope = getattr(request, "scope", {}) or {}
+        mount_prefix = _normalize_prefix(scope.get("root_path") or "/")
+        return mount_prefix
+
+    return "/"