@rapidmx/web-client 0.18.0 → 0.20.0

package/apps/shared/auth/adminAccess.ts

@@ -1,99 +1,99 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import { authApiFetch } from "@rapidmx/react-shared/util/api.js";
-
-/**
- * Whether the signed-in user holds an administrator role, learned without elevating.
- *
- * The JWT the browser carries can't say: auth-server strips every trusted role from a token that isn't elevated
- * (`TokenUtils.resolveTokenUser()`), so `trusted` (from the JWT) is false for a real administrator until they confirm
- * their identity on auth-server's elevation page. The role itself lives on the caller's own `User` record, which they may
- * always read - `GET {authServerUrl}/api/users/me` (the same call auth-server's own UI makes "to check for admin access") -
- * so the answer is read from there, with the same cross-origin credentials the profile lookups use.
- *
- * This only decides whether a menu item is shown. The `/admin` pages and API stay authoritative: they check the role and
- * the elevation themselves, and the link only navigates (`/admin` then runs the elevation redirect), so a wrong answer
- * - a stale cache, a tampered `sessionStorage` - can show a link that leads to "no administrator access", never more.
- */
-
-/** The roles the server treats as trusted when it isn't configured otherwise (`trusted_roles`, default `["admin"]`). */
-export const DEFAULT_TRUSTED_ROLES: readonly string[] = ["admin"];
-
-/** `sessionStorage` key prefix of a remembered answer; the user's uid follows, so another account signing in in the same
- * tab never inherits it. */
-export const ADMIN_ACCESS_KEY_PREFIX = "rapidmx-admin-access:";
-
-/** How long a remembered answer is trusted - long enough that navigating between the apps costs no request, short enough
- * that a role granted or removed shows up within the sitting. */
-export const ADMIN_ACCESS_TTL_MS = 30 * 60 * 1000;
-
-/** Lookups in flight, by key, so two components asking at once make one request. */
-const lookups = new Map<string, Promise<boolean | undefined>>();
-
-/** Forgets the lookups in flight (tests). */
-export function resetAdminAccessLookups(): void {
-    lookups.clear();
-}
-
-function readRemembered(key: string, now: number): boolean | undefined {
-    try {
-        const stored = JSON.parse(sessionStorage.getItem(key) ?? "null") as { admin?: unknown; at?: unknown } | null;
-        if (typeof stored?.admin === "boolean" && typeof stored.at === "number" && now - stored.at >= 0 && now - stored.at < ADMIN_ACCESS_TTL_MS) {
-            return stored.admin;
-        }
-    } catch {
-        // Unreadable, or storage unavailable - ask again.
-    }
-    return undefined;
-}
-
-function remember(key: string, admin: boolean, now: number): void {
-    try {
-        sessionStorage.setItem(key, JSON.stringify({ admin, at: now }));
-    } catch {
-        // Storage unavailable - the next page load asks again.
-    }
-}
-
-/**
- * Resolves `true` when `userUid`'s own `User` record on auth-server carries one of `trustedRoles`, `false` when it
- * doesn't, and `undefined` when that couldn't be established (unreachable, blocked by CORS, not signed in, an unexpected
- * body, or a record that isn't this user's). Only a real answer is remembered; a failure is asked again on the next page.
- * Never rejects.
- */
-export function lookUpAdminAccess(
-    authServerUrl: string,
-    userUid: string,
-    trustedRoles: readonly string[] = DEFAULT_TRUSTED_ROLES,
-    now: number = Date.now(),
-): Promise<boolean | undefined> {
-    const key = `${ADMIN_ACCESS_KEY_PREFIX}${userUid}`;
-    const remembered = readRemembered(key, now);
-    if (remembered !== undefined) {
-        return Promise.resolve(remembered);
-    }
-    const inFlight = lookups.get(key);
-    if (inFlight) {
-        return inFlight;
-    }
-    const lookup = (async (): Promise<boolean | undefined> => {
-        try {
-            const user = await authApiFetch<{ uid?: unknown; roles?: unknown } | null>(authServerUrl, "/users/me");
-            if (!user || user.uid !== userUid || !Array.isArray(user.roles)) {
-                return undefined;
-            }
-            const admin = user.roles.some((role) => typeof role === "string" && trustedRoles.includes(role));
-            remember(key, admin, now);
-            return admin;
-        } catch {
-            return undefined;
-        } finally {
-            // Answered: what was learned is in storage; a failure may be asked again.
-            lookups.delete(key);
-        }
-    })();
-    lookups.set(key, lookup);
-    return lookup;
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { authApiFetch } from "@rapidmx/react-shared/util/api.js";
+
+/**
+ * Whether the signed-in user holds an administrator role, learned without elevating.
+ *
+ * The JWT the browser carries can't say: auth-server strips every trusted role from a token that isn't elevated
+ * (`TokenUtils.resolveTokenUser()`), so `trusted` (from the JWT) is false for a real administrator until they confirm
+ * their identity on auth-server's elevation page. The role itself lives on the caller's own `User` record, which they may
+ * always read - `GET {authServerUrl}/api/users/me` (the same call auth-server's own UI makes "to check for admin access") -
+ * so the answer is read from there, with the same cross-origin credentials the profile lookups use.
+ *
+ * This only decides whether a menu item is shown. The `/admin` pages and API stay authoritative: they check the role and
+ * the elevation themselves, and the link only navigates (`/admin` then runs the elevation redirect), so a wrong answer
+ * - a stale cache, a tampered `sessionStorage` - can show a link that leads to "no administrator access", never more.
+ */
+
+/** The roles the server treats as trusted when it isn't configured otherwise (`trusted_roles`, default `["admin"]`). */
+export const DEFAULT_TRUSTED_ROLES: readonly string[] = ["admin"];
+
+/** `sessionStorage` key prefix of a remembered answer; the user's uid follows, so another account signing in in the same
+ * tab never inherits it. */
+export const ADMIN_ACCESS_KEY_PREFIX = "rapidmx-admin-access:";
+
+/** How long a remembered answer is trusted - long enough that navigating between the apps costs no request, short enough
+ * that a role granted or removed shows up within the sitting. */
+export const ADMIN_ACCESS_TTL_MS = 30 * 60 * 1000;
+
+/** Lookups in flight, by key, so two components asking at once make one request. */
+const lookups = new Map<string, Promise<boolean | undefined>>();
+
+/** Forgets the lookups in flight (tests). */
+export function resetAdminAccessLookups(): void {
+    lookups.clear();
+}
+
+function readRemembered(key: string, now: number): boolean | undefined {
+    try {
+        const stored = JSON.parse(sessionStorage.getItem(key) ?? "null") as { admin?: unknown; at?: unknown } | null;
+        if (typeof stored?.admin === "boolean" && typeof stored.at === "number" && now - stored.at >= 0 && now - stored.at < ADMIN_ACCESS_TTL_MS) {
+            return stored.admin;
+        }
+    } catch {
+        // Unreadable, or storage unavailable - ask again.
+    }
+    return undefined;
+}
+
+function remember(key: string, admin: boolean, now: number): void {
+    try {
+        sessionStorage.setItem(key, JSON.stringify({ admin, at: now }));
+    } catch {
+        // Storage unavailable - the next page load asks again.
+    }
+}
+
+/**
+ * Resolves `true` when `userUid`'s own `User` record on auth-server carries one of `trustedRoles`, `false` when it
+ * doesn't, and `undefined` when that couldn't be established (unreachable, blocked by CORS, not signed in, an unexpected
+ * body, or a record that isn't this user's). Only a real answer is remembered; a failure is asked again on the next page.
+ * Never rejects.
+ */
+export function lookUpAdminAccess(
+    authServerUrl: string,
+    userUid: string,
+    trustedRoles: readonly string[] = DEFAULT_TRUSTED_ROLES,
+    now: number = Date.now(),
+): Promise<boolean | undefined> {
+    const key = `${ADMIN_ACCESS_KEY_PREFIX}${userUid}`;
+    const remembered = readRemembered(key, now);
+    if (remembered !== undefined) {
+        return Promise.resolve(remembered);
+    }
+    const inFlight = lookups.get(key);
+    if (inFlight) {
+        return inFlight;
+    }
+    const lookup = (async (): Promise<boolean | undefined> => {
+        try {
+            const user = await authApiFetch<{ uid?: unknown; roles?: unknown } | null>(authServerUrl, "/users/me");
+            if (!user || user.uid !== userUid || !Array.isArray(user.roles)) {
+                return undefined;
+            }
+            const admin = user.roles.some((role) => typeof role === "string" && trustedRoles.includes(role));
+            remember(key, admin, now);
+            return admin;
+        } catch {
+            return undefined;
+        } finally {
+            // Answered: what was learned is in storage; a failure may be asked again.
+            lookups.delete(key);
+        }
+    })();
+    lookups.set(key, lookup);
+    return lookup;
+}

package/apps/shared/components/admin/diagnostics/HostCard.tsx

@@ -7,6 +7,7 @@ import type { DiagnosticsDiskMetrics, DiagnosticsMetrics } from "./diagnosticsAp
 import { formatBytes, formatCores, formatPercent, NO_VALUE, percentOf } from "./format.js";
 import { seriesOf } from "./metricsHistory.js";
 import MetricTile from "./MetricTile.js";
+import PressureTiles from "./PressureTiles.js";
 import UsageMeter from "./UsageMeter.js";
 
 const percentLabel = (value: number) => formatPercent(value);
@@ -91,6 +92,7 @@ export default function HostCard({ host, history }: HostCardProps) {
                         />
                         <MetricTile label="Load average" value={formatLoad(host.loadAverage)} detail="1, 5 and 15 minutes" />
                     </div>
+                    <PressureTiles host={host} history={history} />
                     <h3 className="mt-4 mb-2 text-xs uppercase tracking-wide text-text-muted">Disks</h3>
                     {disks.length === 0 ? (
                         <p className="text-sm text-text-muted">No disks were reported.</p>

package/apps/shared/components/admin/diagnostics/PressureTiles.tsx

@@ -0,0 +1,108 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+import type { DiagnosticsMetrics, DiagnosticsPressure } from "./diagnosticsApi.js";
+import { formatBytes, formatPercent, percentOf } from "./format.js";
+import { seriesOf } from "./metricsHistory.js";
+import MetricTile from "./MetricTile.js";
+
+/** From this share of the last 10 seconds spent stalled, pressure is called elevated ... */
+export const ELEVATED_PRESSURE_PERCENT = 10;
+
+/** ... and from this, high. Kernel documentation treats a few percent as ordinary and tens of percent as a machine that is struggling. */
+export const HIGH_PRESSURE_PERCENT = 30;
+
+export type PressureLevel = "Low" | "Elevated" | "High";
+
+/** Pressure in words, so that it is never only a number or a colour. */
+export function pressureLevel(percent: number): PressureLevel {
+    if (percent >= HIGH_PRESSURE_PERCENT) {
+        return "High";
+    }
+    return percent >= ELEVATED_PRESSURE_PERCENT ? "Elevated" : "Low";
+}
+
+type Host = NonNullable<DiagnosticsMetrics["host"]>;
+type Resource = keyof NonNullable<Host["pressure"]>;
+
+const RESOURCES: { key: Resource; label: string; waiting: string }[] = [
+    { key: "memory", label: "Memory pressure", waiting: "waiting for memory" },
+    { key: "io", label: "I/O pressure", waiting: "waiting for the disk" },
+    { key: "cpu", label: "CPU pressure", waiting: "waiting for a CPU" },
+];
+
+function PressureTile({ label, waiting, stall, history, resource }: { label: string; waiting: string; stall: DiagnosticsPressure; history: DiagnosticsMetrics[]; resource: Resource }) {
+    const level = pressureLevel(stall.some.avg10);
+    return (
+        <MetricTile
+            label={label}
+            value={formatPercent(stall.some.avg10)}
+            detail={`${level}: tasks ${waiting}, last 10 seconds`}
+            history={{
+                values: seriesOf(history, (sample) => sample.host?.pressure?.[resource]?.some.avg10),
+                max: 100,
+                format: formatPercent,
+            }}
+        >
+            <div className="mt-2 text-xs text-text-muted">
+                Last minute {formatPercent(stall.some.avg60)}, last 5 minutes {formatPercent(stall.some.avg300)}
+                {stall.full && ` · every task waiting: ${formatPercent(stall.full.avg10)}`}
+            </div>
+        </MetricTile>
+    );
+}
+
+export interface PressureTilesProps {
+    host: Host;
+    history: DiagnosticsMetrics[];
+}
+
+/**
+ * How stalled the node is (Linux pressure stall information: the share of recent time tasks spent waiting for memory, the disk or
+ * a CPU), and how much memory the hypervisor holds in the machine's balloon. Both explain a node that is slow while nothing on it
+ * uses much: a guest counts ballooned memory as used though no process holds it, and a machine short of memory stalls on the disk.
+ * Nothing is shown where the kernel gives no such figures.
+ */
+export default function PressureTiles({ host, history }: PressureTilesProps) {
+    const tiles = RESOURCES.filter(({ key }) => host.pressure?.[key]);
+    const balloon = host.balloon;
+    if (tiles.length === 0 && !balloon) {
+        return null;
+    }
+    const heldPercent = percentOf(balloon?.heldBytes, host.memoryTotalBytes);
+    return (
+        <>
+            <h3 className="mt-4 mb-2 text-xs uppercase tracking-wide text-text-muted">Pressure</h3>
+            <div className="grid grid-cols-1 gap-3 md:grid-cols-2 lg:grid-cols-4">
+                {RESOURCES.map(({ key, label, waiting }) => {
+                    const stall = host.pressure?.[key];
+                    return stall && <PressureTile key={key} label={label} waiting={waiting} stall={stall} history={history} resource={key} />;
+                })}
+                {balloon && (
+                    <MetricTile
+                        label="Held by the hypervisor"
+                        value={formatBytes(balloon.heldBytes)}
+                        detail={`of ${formatBytes(host.memoryTotalBytes)}`}
+                        usage={
+                            heldPercent === undefined
+                                ? undefined
+                                : { percent: heldPercent, detail: `${formatBytes(balloon.heldBytes)} in the memory balloon`, flag: false }
+                        }
+                        history={{
+                            values: seriesOf(history, (sample) => sample.host?.balloon?.heldBytes),
+                            max: host.memoryTotalBytes,
+                            format: formatBytes,
+                        }}
+                    >
+                        <div className="mt-2 text-xs text-text-muted">
+                            Memory the hypervisor has taken back through the balloon. It counts as used above though no process holds it.{" "}
+                            {formatBytes(balloon.inflatedTotalBytes)} taken since the node booted.
+                        </div>
+                    </MetricTile>
+                )}
+            </div>
+        </>
+    );
+}

package/apps/shared/components/admin/diagnostics/PvcTable.tsx

@@ -7,26 +7,40 @@ import type { DiagnosticsPvcMetrics } from "./diagnosticsApi.js";
 import { formatBytes, NO_VALUE, percentOf } from "./format.js";
 import UsageMeter from "./UsageMeter.js";
 
-const HEADINGS = ["Volume", "Phase", "Storage class", "Size", "Usage"];
+const HEADINGS = ["Volume", "Phase", "Storage class", "Allocated", "Usage"];
 
 function Usage({ pvc }: { pvc: DiagnosticsPvcMetrics }) {
     if (!pvc.mountedByServer) {
         return <span className="text-text-muted">Usage not available: not mounted in the server pod.</span>;
     }
-    const percent = percentOf(pvc.usedBytes, pvc.capacityBytes);
+    // On the node's disk the filesystem's figures are the disk's, so only a measured directory says what the volume holds (an
+    // older server sent the disk's figures without saying so).
+    const own = pvc.sharesNodeDisk && pvc.measuredBy !== "directory" ? undefined : pvc.usedBytes;
+    const percent = percentOf(own, pvc.capacityBytes);
     if (percent === undefined) {
-        return <span className="text-text-muted">The server has no usage figures for this volume.</span>;
+        return (
+            <span className="text-text-muted">
+                {pvc.sharesNodeDisk
+                    ? "Shares the node\u2019s disk, and what the volume holds could not be measured."
+                    : "The server has no usage figures for this volume."}
+            </span>
+        );
     }
     return (
         <div>
             <UsageMeter
                 label={`Usage of volume ${pvc.name}`}
                 percent={percent}
-                detail={`${formatBytes(pvc.usedBytes)} of ${formatBytes(pvc.capacityBytes)}`}
-                flag={!pvc.sharesNodeDisk}
+                detail={`${pvc.usedPartial ? "At least " : ""}${formatBytes(own)} of ${formatBytes(pvc.capacityBytes)} allocated`}
             />
+            {pvc.usedPartial && (
+                <p className="mt-1 text-xs text-text-muted">The volume is too large to measure completely, so this is a lower bound.</p>
+            )}
             {pvc.sharesNodeDisk && (
-                <p className="mt-1 text-xs text-text-muted">Shares the node&rsquo;s disk; the volume&rsquo;s size is not enforced.</p>
+                <p className="mt-1 text-xs text-text-muted">
+                    Measured from the volume&rsquo;s directory. It shares the node&rsquo;s disk, which has {formatBytes(pvc.availableBytes)} free; the
+                    volume&rsquo;s allocation is not enforced.
+                </p>
             )}
         </div>
     );

package/apps/shared/components/admin/diagnostics/diagnosticsApi.ts

@@ -124,9 +124,22 @@ export interface DiagnosticsHostMetrics {
     memoryTotalBytes: number;
     memoryUsedBytes: number;
     loadAverage: [number, number, number];
+    /**
+     * Memory the hypervisor holds in the machine's memory balloon. It counts in `memoryUsedBytes` (a guest sees ballooned memory
+     * as used) though no process holds it. Absent where no balloon has ever taken any.
+     */
+    balloon?: { heldBytes: number; inflatedTotalBytes: number };
+    /** How stalled the node is waiting for memory, disk and CPU (Linux pressure stall information). Absent without kernel support. */
+    pressure?: { memory?: DiagnosticsPressure; io?: DiagnosticsPressure; cpu?: DiagnosticsPressure };
     disks: DiagnosticsDiskMetrics[];
 }
 
+/** The share (0 to 100) of the last 10, 60 and 300 seconds that tasks were stalled. `some`: at least one waited. `full`: every one did. */
+export interface DiagnosticsPressure {
+    some: { avg10: number; avg60: number; avg300: number };
+    full?: { avg10: number; avg60: number; avg300: number };
+}
+
 /** From the metrics API (metrics-server): absent when it is not installed. */
 export interface DiagnosticsPodMetrics {
     name: string;
@@ -136,8 +149,11 @@ export interface DiagnosticsPodMetrics {
 }
 
 /**
- * `usedBytes`/`availableBytes` exist only for a volume the server pod mounts (`mountedByServer`). `sharesNodeDisk` means the
- * figures are the whole node filesystem's, and the volume's own size is not enforced.
+ * `usedBytes` (what the volume holds) exists only for a volume the server pod mounts (`mountedByServer`), and `measuredBy`
+ * says how it was found: from the volume's own filesystem, or - when the volume is a directory of the node's disk
+ * (`sharesNodeDisk`, such as k3s's local-path), where the filesystem is the whole disk - by measuring the directory.
+ * `capacityBytes` is the volume's allocation, which a volume that shares the node's disk does not enforce; `availableBytes` is
+ * what is left of the filesystem it is on.
  */
 export interface DiagnosticsPvcMetrics {
     name: string;
@@ -147,6 +163,9 @@ export interface DiagnosticsPvcMetrics {
     capacityBytes?: number;
     usedBytes?: number;
     availableBytes?: number;
+    measuredBy?: "filesystem" | "directory";
+    /** The directory could not be measured completely, so `usedBytes` is a lower bound. */
+    usedPartial?: boolean;
     mountedByServer: boolean;
     sharesNodeDisk?: boolean;
 }