mirrorwall 0.2.0__py3-none-any.whl

mirrorwall/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

mirrorwall/__init__.py

@@ -0,0 +1,116 @@
+"""MirrorWall — the shared UI and web-edge toolkit for the suite's three applications.
+
+Design tokens, a layout shell, component macros, template filters, JSON and error envelopes, SSE
+plumbing, request-ID, Host-validation and CSRF middleware, static mounting and health
+primitives — so FreeWeight, LoadCoach and IdeaPress look and behave like one product family
+without sharing a single page.
+
+It knows nothing about benchmarks, routing or content, and a term-scan test enforces that: no
+application vocabulary appears anywhere in this package, in Python, in a template, in a CSS class
+name or in a JS module name.
+"""
+
+from __future__ import annotations
+
+from mirrorwall.__about__ import __version__
+from mirrorwall.filters import (
+    EM_DASH,
+    STATIC_URL_PREFIX,
+    asset_url,
+    bytes_human,
+    duration_human,
+    is_supported_test,
+    json_pretty,
+    measurement,
+    register_filters,
+    timestamp,
+    truncate_middle,
+)
+from mirrorwall.health import (
+    ComponentHealth,
+    ComponentStatus,
+    health_payload,
+    worst_status,
+)
+from mirrorwall.middleware import (
+    CSRF_COOKIE_NAME,
+    CSRF_FIELD_NAME,
+    CsrfMiddleware,
+    HostValidationMiddleware,
+    RequestIdMiddleware,
+    issue_csrf_token,
+    loopback_allowlist,
+)
+from mirrorwall.responses import (
+    DEFAULT_PAGE_LIMIT,
+    MAX_PAGE_LIMIT,
+    clamp_limit,
+    error_body,
+    error_response,
+    json_response,
+    paginated_response,
+)
+from mirrorwall.sse import (
+    TOKEN_EVENT,
+    Event,
+    EventBroker,
+    EventSource,
+    Subscription,
+    format_frame,
+    parse_last_event_id,
+    sse_response,
+)
+from mirrorwall.static import HashedStaticFiles, mount_static
+from mirrorwall.templating import (
+    DEFAULT_THEME_STORAGE_KEY,
+    PACKAGE_STATIC_DIR,
+    PACKAGE_TEMPLATE_DIR,
+    create_template_environment,
+)
+
+__all__ = [
+    "CSRF_COOKIE_NAME",
+    "CSRF_FIELD_NAME",
+    "DEFAULT_PAGE_LIMIT",
+    "DEFAULT_THEME_STORAGE_KEY",
+    "EM_DASH",
+    "MAX_PAGE_LIMIT",
+    "PACKAGE_STATIC_DIR",
+    "PACKAGE_TEMPLATE_DIR",
+    "STATIC_URL_PREFIX",
+    "TOKEN_EVENT",
+    "ComponentHealth",
+    "ComponentStatus",
+    "CsrfMiddleware",
+    "Event",
+    "EventBroker",
+    "EventSource",
+    "HashedStaticFiles",
+    "HostValidationMiddleware",
+    "RequestIdMiddleware",
+    "Subscription",
+    "__version__",
+    "asset_url",
+    "bytes_human",
+    "clamp_limit",
+    "create_template_environment",
+    "duration_human",
+    "error_body",
+    "error_response",
+    "format_frame",
+    "health_payload",
+    "is_supported_test",
+    "issue_csrf_token",
+    "json_pretty",
+    "json_response",
+    "loopback_allowlist",
+    "measurement",
+    "mount_static",
+    "paginated_response",
+    "parse_last_event_id",
+    "register_filters",
+    "sse_response",
+    "timestamp",
+    "truncate_middle",
+    "worst_status",
+]

mirrorwall/filters.py

@@ -0,0 +1,248 @@
+"""mirrorwall.filters — the template filters every application in the suite renders through.
+
+One rule shapes most of this module. An absent measurement is an em dash, never a zero
+(:doc:`ADR-0016 <../../adr/0016-unsupported-vs-zero>`, UI/UX standards §3): a machine that could
+not read its GPU temperature did not read it as zero degrees, and a zero is indistinguishable
+from a real reading the moment it reaches an average or a chart.
+
+:func:`measurement` is the **only** sanctioned way a template touches a
+:class:`~baseaicore.Measurement` (spec §2). ``UNSUPPORTED`` refuses ``__bool__``, so
+``{% if value %}`` on a measurement raises rather than rendering blank — correct behaviour, and
+worth knowing before it happens. Templates write ``{{ value | measurement }}`` and
+``{% if value is supported %}``.
+"""
+
+from __future__ import annotations
+
+import json
+import posixpath
+from datetime import datetime, timedelta
+from typing import Any, Final
+
+from baseaicore import UNSUPPORTED, is_supported
+from baseaicore.timeutil import to_rfc3339
+from markupsafe import Markup, escape
+
+__all__ = [
+    "EM_DASH",
+    "STATIC_URL_PREFIX",
+    "asset_url",
+    "bytes_human",
+    "duration_human",
+    "is_supported_test",
+    "json_pretty",
+    "measurement",
+    "register_filters",
+    "timestamp",
+    "truncate_middle",
+]
+
+EM_DASH: Final = "—"
+"""What an absent value renders as, everywhere in the suite. Never ``0``, never blank."""
+
+STATIC_URL_PREFIX: Final = "/static/mirrorwall"
+"""Where :func:`mount_static` serves this package's own assets from."""
+
+_BYTE_UNITS: Final = ("KiB", "MiB", "GiB", "TiB", "PiB")
+
+
+def bytes_human(value: object) -> str:
+    """Render a byte count at human scale.
+
+    Args:
+        value: A byte count, ``None``, or ``UNSUPPORTED``.
+
+    Returns:
+        The scaled string, or an em dash for an absent value — never ``"0 B"``, which is a real
+        measurement of an empty thing and must stay distinguishable from an unmeasured one.
+    """
+    if value is None or not is_supported(value) or not isinstance(value, (int, float)):
+        return EM_DASH
+    if value < 1024:
+        return f"{int(value)} B"
+    scaled = float(value)
+    for unit in _BYTE_UNITS:
+        scaled /= 1024
+        if scaled < 1024 or unit == _BYTE_UNITS[-1]:
+            return f"{scaled:.1f} {unit}"
+    raise AssertionError("unreachable: the final unit always returns")  # pragma: no cover
+
+
+def duration_human(value: object) -> str:
+    """Render a duration in seconds at human scale.
+
+    Args:
+        value: Seconds as a number, a :class:`~datetime.timedelta`, ``None``, or ``UNSUPPORTED``.
+
+    Returns:
+        ``"820 ms"``, ``"1.4 s"``, ``"2m 05s"`` or ``"3h 12m"``; an em dash for an absent value.
+    """
+    if isinstance(value, timedelta):
+        value = value.total_seconds()
+    if value is None or not is_supported(value) or not isinstance(value, (int, float)):
+        return EM_DASH
+    seconds = float(value)
+    if seconds < 1:
+        return f"{seconds * 1000:.0f} ms"
+    if seconds < 60:
+        return f"{seconds:.1f} s"
+    if seconds < 3600:
+        return f"{int(seconds // 60)}m {int(seconds % 60):02d}s"
+    return f"{int(seconds // 3600)}h {int(seconds % 3600 // 60):02d}m"
+
+
+def timestamp(value: object) -> str:
+    """Render an instant as RFC 3339 in UTC.
+
+    Args:
+        value: A timezone-aware :class:`~datetime.datetime`, ``None``, or ``UNSUPPORTED``.
+
+    Returns:
+        The RFC 3339 string, or an em dash.
+    """
+    if not isinstance(value, datetime):
+        return EM_DASH
+    return to_rfc3339(value)
+
+
+def measurement(value: object, reason: str | None = None, unit: str | None = None) -> Markup:
+    """Render a measurement, or an em dash carrying why it is absent.
+
+    The only sanctioned way a template touches a :class:`~baseaicore.Measurement`. An
+    ``UNSUPPORTED`` value renders as an em dash with the producer's own reason in a ``title``
+    attribute and in ``aria-label``, so the absence is visible to a reader and to a screen reader
+    alike, and is never a zero.
+
+    Args:
+        value: The measurement.
+        reason: Why it is unavailable, from the producer (SweatMeter's ``unavailable_reasons``,
+            a run's ``unsupported_reason`` column). Rendered as a tooltip.
+        unit: A unit suffix appended to a present value, e.g. ``"W"``.
+
+    Returns:
+        Escaped markup: an ``<span>`` for an absent value, the escaped number otherwise.
+    """
+    if value is None or value is UNSUPPORTED or not is_supported(value):
+        explanation = reason or "not measurable in this environment"
+        return Markup(
+            '<span class="muted" title="{reason}" aria-label="Unavailable: {reason}">{dash}</span>'
+        ).format(reason=explanation, dash=EM_DASH)
+    rendered = f"{value:g}" if isinstance(value, float) else str(value)
+    if unit:
+        return Markup("{value} <span class='unit'>{unit}</span>").format(value=rendered, unit=unit)
+    return escape(rendered)
+
+
+def is_supported_test(value: object) -> bool:
+    """Jinja test: whether a measurement carries a real reading.
+
+    Registered as ``supported`` so a template writes ``{% if value is supported %}``. It exists
+    because ``{% if value %}`` on an ``UNSUPPORTED`` raises — deliberately (ADR-0016) — and a
+    template needs a way to ask the question that does not.
+
+    Args:
+        value: The measurement.
+
+    Returns:
+        Whether it can be rendered as a number.
+    """
+    return value is not None and is_supported(value)
+
+
+def truncate_middle(value: object, length: int = 40, ellipsis: str = "…") -> str:
+    """Shorten a long identifier from the middle, keeping both ends readable.
+
+    A canonical model ID is distinguished by its tail as much as its head, so an ordinary
+    right-truncation removes the half that disambiguates it.
+
+    Args:
+        value: The string to shorten.
+        length: The maximum rendered length, including the ellipsis.
+        ellipsis: What replaces the removed middle.
+
+    Returns:
+        The original string when it already fits, otherwise head + ellipsis + tail.
+
+    Raises:
+        ValueError: ``length`` is too small to hold the ellipsis and one character either side.
+    """
+    text = "" if value is None else str(value)
+    minimum = len(ellipsis) + 2
+    if length < minimum:
+        message = (
+            f"length must be at least {minimum} to hold {ellipsis!r} and one character either side"
+        )
+        raise ValueError(message)
+    if len(text) <= length:
+        return text
+    room = length - len(ellipsis)
+    head = room - room // 2
+    return f"{text[:head]}{ellipsis}{text[len(text) - room // 2 :]}"
+
+
+def json_pretty(value: object, indent: int = 2) -> str:
+    """Render a value as indented JSON for a ``<pre>`` block.
+
+    Args:
+        value: Anything JSON-serializable. Anything else is rendered with ``str`` rather than
+            raising, because a viewer that crashes the page it is diagnosing is useless.
+        indent: Indentation width.
+
+    Returns:
+        The JSON text. Not marked safe: the caller's autoescaping still applies, which is what
+        keeps a ``<script>`` inside a payload inert.
+    """
+    try:
+        return json.dumps(value, indent=indent, sort_keys=True, default=str)
+    except (TypeError, ValueError):  # pragma: no cover — default=str covers all practical inputs
+        return str(value)
+
+
+def asset_url(path: str, *, prefix: str = STATIC_URL_PREFIX) -> str:
+    """Return the URL this package's asset is served from.
+
+    Phase 1 emits a plain, traversal-safe path. Phase 2's :mod:`mirrorwall.static` replaces the
+    implementation with the content-hashed form; the template seam is this function's name and
+    signature, so that change is invisible to every consumer's templates.
+
+    Args:
+        path: A path relative to ``mirrorwall/static/``, e.g. ``"css/tokens.css"``.
+        prefix: The URL the static mount serves from.
+
+    Returns:
+        The absolute URL path.
+
+    Raises:
+        ValueError: ``path`` is absolute or escapes the static root — a template must not be able
+            to address anything outside the package's own assets.
+    """
+    cleaned = path.strip()
+    if cleaned.startswith("/") or "\\" in cleaned:
+        message = f"asset path must be relative to the static root: {path!r}"
+        raise ValueError(message)
+    normalized = posixpath.normpath(cleaned)
+    if normalized.startswith("..") or normalized == ".":
+        message = f"asset path escapes the static root: {path!r}"
+        raise ValueError(message)
+    return f"{prefix}/{normalized}"
+
+
+def register_filters(filters: dict[str, Any], tests: dict[str, Any]) -> None:
+    """Install every shared filter and test onto a Jinja environment's registries.
+
+    Args:
+        filters: The environment's ``filters`` mapping.
+        tests: The environment's ``tests`` mapping.
+    """
+    filters.update(
+        {
+            "bytes_human": bytes_human,
+            "duration_human": duration_human,
+            "timestamp": timestamp,
+            "measurement": measurement,
+            "truncate_middle": truncate_middle,
+            "json_pretty": json_pretty,
+            "asset_url": asset_url,
+        }
+    )
+    tests["supported"] = is_supported_test

mirrorwall/gallery.py

@@ -0,0 +1,4 @@
+"""mirrorwall.gallery.
+
+TODO: implement per docs/packages/mirrorwall/development-plan.md.
+"""

mirrorwall/health.py

@@ -0,0 +1,125 @@
+"""mirrorwall.health — the health payload primitives every application's ``/health`` is built on.
+
+The package supplies the shape and the roll-up rule; each application supplies its own components
+(a database, a provider, a queue) and decides what makes each one degraded. That split is the
+point: three applications answer "are you healthy?" in the same words, about different things.
+
+``NOT_CONFIGURED`` is a first-class status, not a synonym for ``UNAVAILABLE``. A component nobody
+asked for is not broken, and rolling it up as though it were turns every default install into a
+red dashboard — the same distinction between "absent" and "bad" that ADR-0016 makes for a
+measurement.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import TYPE_CHECKING, Any
+
+from baseaicore.timeutil import to_rfc3339, utc_now
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from datetime import datetime
+
+__all__ = ["ComponentHealth", "ComponentStatus", "health_payload", "worst_status"]
+
+
+class ComponentStatus(StrEnum):
+    """One component's verdict.
+
+    Ordered worst-last in :data:`_SEVERITY` rather than by declaration, so adding a status cannot
+    silently change how an existing one rolls up.
+    """
+
+    OK = "ok"
+    DEGRADED = "degraded"
+    UNAVAILABLE = "unavailable"
+    NOT_CONFIGURED = "not_configured"
+
+
+_SEVERITY: dict[ComponentStatus, int] = {
+    ComponentStatus.NOT_CONFIGURED: 0,
+    ComponentStatus.OK: 1,
+    ComponentStatus.DEGRADED: 2,
+    ComponentStatus.UNAVAILABLE: 3,
+}
+
+
+@dataclass(frozen=True, slots=True)
+class ComponentHealth:
+    """One named component's status, with whatever numbers explain it.
+
+    Attributes:
+        name: The component, e.g. ``"database"``. Stable across releases: a dashboard keys on it.
+        status: The verdict.
+        detail: One human-readable sentence. Free of secrets and of paths outside the data root.
+        data: Structured figures behind the verdict — free bytes, a latency, a queue depth.
+        checked_at: When the check ran. Defaults to now at payload time.
+    """
+
+    name: str
+    status: ComponentStatus
+    detail: str = ""
+    data: Mapping[str, Any] = field(default_factory=dict)
+    checked_at: datetime | None = None
+
+
+def worst_status(components: Sequence[ComponentHealth]) -> ComponentStatus:
+    """Roll several components up into one overall verdict.
+
+    ``NOT_CONFIGURED`` never worsens the roll-up: a component nobody asked for is not a fault. An
+    empty component list is ``OK`` — an application with nothing to check has nothing wrong.
+
+    Args:
+        components: The components to roll up.
+
+    Returns:
+        The most severe status present, ``OK`` when the only statuses are ``OK`` and
+        ``NOT_CONFIGURED``, and ``NOT_CONFIGURED`` only when every component is.
+    """
+    if not components:
+        return ComponentStatus.OK
+    statuses = [component.status for component in components]
+    if all(status is ComponentStatus.NOT_CONFIGURED for status in statuses):
+        return ComponentStatus.NOT_CONFIGURED
+    return max(statuses, key=lambda status: _SEVERITY[status])
+
+
+def health_payload(
+    *,
+    application: str,
+    version: str,
+    components: Sequence[ComponentHealth],
+    checked_at: datetime | None = None,
+) -> dict[str, Any]:
+    """Build the ``/health`` body.
+
+    Args:
+        application: The application's distribution name, lowercase.
+        version: Its version.
+        components: Every component it checked.
+        checked_at: The instant to record for components that did not carry their own. Injected
+            so a test can assert a whole payload without patching the clock.
+
+    Returns:
+        The body: overall status, the application's identity, and one entry per component in the
+        order given — never reordered, because a dashboard's rows should not move between polls.
+    """
+    now = checked_at or utc_now()
+    return {
+        "status": worst_status(components).value,
+        "application": application,
+        "version": version,
+        "checked_at": to_rfc3339(now),
+        "components": [
+            {
+                "name": component.name,
+                "status": component.status.value,
+                "detail": component.detail,
+                "data": dict(component.data),
+                "checked_at": to_rfc3339(component.checked_at or now),
+            }
+            for component in components
+        ],
+    }