@rapidmx/web-client 0.17.2 → 0.19.0

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

@@ -0,0 +1,197 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { apiFetch } from "@rapidmx/react-shared/util/api.js";
+
+/**
+ * The client of the server's `/admin/diagnostics/*` endpoints (`versions`, `runtime`, `metrics`). All three are GET,
+ * trusted-administrator only and `@RequiresElevation()`: an elevated token is required (403 `api-104`, see
+ * `../elevation.ts`), and any other 403 means the caller is not an administrator. The server may leave any optional
+ * field out, so a caller reads them defensively.
+ *
+ * The server reads Kubernetes with namespace-scoped permissions only: it can list the install's own pods, but not the
+ * cluster's nodes or the kubelet's statistics. That is why a node here is only what the pods say of it, and why the
+ * machine figures are those of the node running the server, read from inside its own container.
+ */
+
+/** The components of a RapidMX install that run beside the server itself, in the order the server lists them. */
+export type DiagnosticsComponentName =
+    | "postfix"
+    | "postfix-bridge"
+    | "mongodb"
+    | "postgresql"
+    | "redis"
+    | "coturn"
+    | "rspamd"
+    | "clamav";
+
+export interface DiagnosticsContainer {
+    name: string;
+    image: string;
+    tag?: string;
+    digest?: string;
+    ready: boolean;
+    restartCount: number;
+}
+
+export interface DiagnosticsPod {
+    name: string;
+    phase: string;
+    ready: boolean;
+    restarts: number;
+    node?: string;
+    startedAt?: string;
+    containers: DiagnosticsContainer[];
+}
+
+export interface DiagnosticsComponent {
+    component: DiagnosticsComponentName;
+    /** `missing`: Kubernetes is reachable but no pod for it exists. `unknown`: Kubernetes is unavailable. */
+    status: "running" | "not-ready" | "missing" | "unknown";
+    /** The image tag of the component's main container. */
+    version?: string;
+    pods: DiagnosticsPod[];
+}
+
+export interface DiagnosticsVersions {
+    server: {
+        nodeVersion: string;
+        v8Version: string;
+        packageName: string;
+        packageVersion: string;
+        platform: string;
+        arch: string;
+        hostname: string;
+        pid: number;
+        startedAt: string;
+        uptimeSeconds: number;
+        nodeEnv: string;
+    };
+    /** Sorted by name. */
+    packages: { name: string; version: string; direct: boolean }[];
+    /** Always all eight, in the order of `DiagnosticsComponentName`. */
+    components: DiagnosticsComponent[];
+    kubernetes: { available: boolean; reason?: string };
+}
+
+/** A node that runs some of this install's pods, derived from the pods: nothing else about the node is readable. */
+export interface DiagnosticsNode {
+    name: string;
+    internalIP?: string;
+    /** How many of the install's pods run on it. */
+    podCount: number;
+}
+
+export type KubernetesDistribution = "k3s" | "rke2" | "eks" | "gke" | "aks" | "kubernetes";
+
+export interface DiagnosticsRuntime {
+    available: boolean;
+    reason?: string;
+    namespace?: string;
+    version?: {
+        gitVersion: string;
+        major: string;
+        minor: string;
+        platform: string;
+        goVersion?: string;
+        buildDate?: string;
+        distribution: KubernetesDistribution;
+    };
+    nodes: DiagnosticsNode[];
+}
+
+/** One filesystem of the node that runs the server, as the server's own container sees it. */
+export interface DiagnosticsDiskMetrics {
+    path: string;
+    /** The volume claim mounted there, when it is one. */
+    pvc?: string;
+    usedBytes: number;
+    capacityBytes: number;
+    availableBytes: number;
+    /** The figures are the whole node filesystem's, not a volume of its own (a hostPath-style volume, such as k3s local-path). */
+    sharesNodeDisk?: boolean;
+}
+
+/**
+ * The node the server pod runs on, as seen from inside the server's own container (on a single-node k3s that is the whole
+ * machine). In a cluster of several nodes it is only that one node.
+ */
+export interface DiagnosticsHostMetrics {
+    /** The whole host, 0 to 100 across all cores. */
+    cpuPercent: number;
+    cpuCount: number;
+    memoryTotalBytes: number;
+    memoryUsedBytes: number;
+    loadAverage: [number, number, number];
+    disks: DiagnosticsDiskMetrics[];
+}
+
+/** From the metrics API (metrics-server): absent when it is not installed. */
+export interface DiagnosticsPodMetrics {
+    name: string;
+    component?: DiagnosticsComponentName | "server";
+    cpuUsedCores?: number;
+    memoryUsedBytes?: number;
+}
+
+/**
+ * `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.
+ */
+export interface DiagnosticsPvcMetrics {
+    name: string;
+    phase: string;
+    storageClass?: string;
+    requestedBytes?: number;
+    capacityBytes?: number;
+    usedBytes?: number;
+    availableBytes?: number;
+    mountedByServer: boolean;
+    sharesNodeDisk?: boolean;
+}
+
+export interface DiagnosticsMetrics {
+    collectedAt: string;
+    process: {
+        cpuPercent: number;
+        rssBytes: number;
+        heapUsedBytes: number;
+        heapTotalBytes: number;
+        loadAverage: [number, number, number];
+        systemMemoryTotalBytes: number;
+        systemMemoryFreeBytes: number;
+        cpuCount: number;
+    };
+    host: DiagnosticsHostMetrics;
+    kubernetes: {
+        available: boolean;
+        reason?: string;
+        namespace?: {
+            name: string;
+            /** Whether the pod figures could be read: they need metrics-server. */
+            podMetricsAvailable: boolean;
+            podMetricsReason?: string;
+            cpuUsedCores?: number;
+            memoryUsedBytes?: number;
+            pods: DiagnosticsPodMetrics[];
+        };
+        pvcs: DiagnosticsPvcMetrics[];
+        errors: string[];
+    };
+}
+
+/** What is installed and running: the server process, its packages, and the other containers of the install. */
+export function getDiagnosticsVersions(): Promise<DiagnosticsVersions> {
+    return apiFetch<DiagnosticsVersions>("/admin/diagnostics/versions");
+}
+
+/** The Kubernetes version, and the nodes the install's pods run on. */
+export function getDiagnosticsRuntime(): Promise<DiagnosticsRuntime> {
+    return apiFetch<DiagnosticsRuntime>("/admin/diagnostics/runtime");
+}
+
+/** One sample of live resource use. Polled by the System tab. */
+export function getDiagnosticsMetrics(): Promise<DiagnosticsMetrics> {
+    return apiFetch<DiagnosticsMetrics>("/admin/diagnostics/metrics");
+}

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

@@ -0,0 +1,28 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/** Saves `content` to the viewer's computer as a file called `filename`. What the download buttons call, so a test can swap it. */
+export type SaveFile = (filename: string, content: string, mimeType: string) => void;
+
+/**
+ * The browser way to save text it made itself: a Blob behind an object URL, opened by a temporary `<a download>`. The URL is
+ * revoked once the click has been handled (not in the same turn: some browsers start the download after it).
+ */
+export const saveTextFile: SaveFile = (filename, content, mimeType) => {
+    const url = URL.createObjectURL(new Blob([content], { type: mimeType }));
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = filename;
+    link.style.display = "none";
+    document.body.appendChild(link);
+    link.click();
+    link.remove();
+    setTimeout(() => URL.revokeObjectURL(url), 0);
+};
+
+/** `rapidmx-server-logs-2026-09-26T10-30-00.000Z.log`: the name, then the time with the colons a file name cannot hold replaced. */
+export function timestampedFilename(name: string, extension: string, now: Date = new Date()): string {
+    return `${name}-${now.toISOString().replace(/:/g, "-")}.${extension}`;
+}

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

@@ -0,0 +1,106 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { isElevationRequired } from "../elevation.js";
+
+/** What is shown where a number is missing or not a number. */
+export const NO_VALUE = "—";
+
+const BYTE_UNITS = ["B", "KiB", "MiB", "GiB", "TiB", "PiB"];
+
+const isNumber = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
+
+/** `1536` as `1.5 KiB` (binary units, as Kubernetes reports them). */
+export function formatBytes(bytes: number | undefined): string {
+    if (!isNumber(bytes)) {
+        return NO_VALUE;
+    }
+    let value = Math.abs(bytes);
+    let unit = 0;
+    while (value >= 1024 && unit < BYTE_UNITS.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    const text = unit === 0 || value >= 100 ? value.toFixed(0) : value.toFixed(1);
+    return `${bytes < 0 ? "-" : ""}${text} ${BYTE_UNITS[unit]}`;
+}
+
+/** CPU as cores: `0.25 cores`, `1 core`, `4 cores`. */
+export function formatCores(cores: number | undefined): string {
+    if (!isNumber(cores)) {
+        return NO_VALUE;
+    }
+    const text = cores >= 10 ? cores.toFixed(0) : String(Number(cores.toFixed(2)));
+    return `${text} ${text === "1" ? "core" : "cores"}`;
+}
+
+/** `42.34` as `42.3%`. */
+export function formatPercent(percent: number | undefined): string {
+    return isNumber(percent) ? `${percent.toFixed(1)}%` : NO_VALUE;
+}
+
+/** `used` as a percentage of `capacity`, or `undefined` when either is missing or the capacity is not positive. */
+export function percentOf(used: number | undefined, capacity: number | undefined): number | undefined {
+    return isNumber(used) && isNumber(capacity) && capacity > 0 ? (used / capacity) * 100 : undefined;
+}
+
+/** Seconds as `3d 4h`, `4h 12m`, `12m 5s` or `5s`: the two largest units that are not zero. */
+export function formatUptime(seconds: number | undefined): string {
+    if (!isNumber(seconds) || seconds < 0) {
+        return NO_VALUE;
+    }
+    const total = Math.floor(seconds);
+    const parts: [number, string][] = [
+        [Math.floor(total / 86400), "d"],
+        [Math.floor((total % 86400) / 3600), "h"],
+        [Math.floor((total % 3600) / 60), "m"],
+        [total % 60, "s"],
+    ];
+    const start = parts.findIndex(([value]) => value > 0);
+    if (start === -1) {
+        return "0s";
+    }
+    return parts
+        .slice(start, start + 2)
+        .map(([value, unit]) => `${value}${unit}`)
+        .join(" ");
+}
+
+/** A date as the viewer's local date and time, or a dash for a missing one (an unreadable one is shown as it came). */
+export function formatDateTime(value: string | undefined): string {
+    if (!value) {
+        return NO_VALUE;
+    }
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? value : date.toLocaleString();
+}
+
+/** `sha256:0123456789abcdef...` as `0123456789ab`. */
+export function shortDigest(digest: string | undefined): string {
+    return digest ? digest.replace(/^[a-z0-9]+:/i, "").slice(0, 12) : NO_VALUE;
+}
+
+/** Shown when the server wants the administrator to have confirmed their identity recently (`api-104`). */
+export const ELEVATION_MESSAGE =
+    "Diagnostics needs you to have recently confirmed your identity. Reload this page, or sign in again, then try once more.";
+
+/** Shown for a 403 that is not about elevation, or a 401. */
+export const NOT_AUTHORISED_MESSAGE = "You are not authorised to view diagnostics.";
+
+/** Whether the caller is not (or no longer) allowed: retrying the same request would fail the same way. */
+export function isPermissionError(err: unknown): boolean {
+    return err instanceof ApiRequestError && (err.status === 403 || err.status === 401);
+}
+
+/** Why a request failed, in words for the administrator. */
+export function describeError(err: unknown, fallback: string): string {
+    if (isElevationRequired(err)) {
+        return ELEVATION_MESSAGE;
+    }
+    if (isPermissionError(err)) {
+        return NOT_AUTHORISED_MESSAGE;
+    }
+    return err instanceof ApiRequestError ? err.message || fallback : fallback;
+}

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

@@ -0,0 +1,231 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { apiUrl } from "@rapidmx/react-shared/util/api.js";
+import { isControlFrame, LogEntry, parseLogFrame } from "./logLines.js";
+
+/**
+ * A client for the server's live log stream: the WebSocket of the `/admin` route's `logs` endpoint (`<origin>/api/admin/logs`).
+ * It follows the shape of `@rapidmx/react-shared`'s `PushClient`, and differs where the protocol does.
+ *
+ * - It authenticates from the `jwt` cookie the browser sends with the upgrade. The server closes the socket with code 1002 when
+ * the caller may not read the logs, or the stream is not set up on the server, with an error code as the close reason. That is
+ * final: retrying would be refused the same way, so the client stops with an error and does not reconnect.
+ * - The first frame is a control message, `{"id":0,"type":"SUBSCRIBED","success":true,"data":"<channel>"}`, which says the stream
+ * is live. It is not a log line. Every later frame is the JSON of one Winston `info` object (see `parseLogFrame()`).
+ * - Delivery is fire-and-forget: lines logged while the socket was down are not replayed.
+ * - Any other close is retried with exponential backoff and jitter until `stop()`.
+ */
+
+/** The subset of the browser's `WebSocket` this client uses - what a test's fake implements. */
+export interface LogSocket {
+    readyState: number;
+    close(code?: number, reason?: string): void;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: { data: unknown }) => void) | null;
+    onclose: ((event: { code?: number; reason?: string }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+}
+
+export type LogSocketFactory = (url: string) => LogSocket;
+
+/**
+ * `connecting`: opening the first connection. `live`: subscribed. `reconnecting`: the connection was lost, or a reconnect is
+ * being tried. `closed`: stopped (or never started). `error`: refused for good, with `error()` saying why.
+ */
+export type LogStreamStatus = "connecting" | "live" | "reconnecting" | "closed" | "error";
+
+/** The close code the server uses when it refuses the stream (a permission or configuration failure). */
+export const LOG_CLOSE_REFUSED = 1002;
+
+/** The first reconnect waits about this long, and each further failure doubles it ... */
+export const LOG_BACKOFF_BASE_MS = 1_000;
+/** ... up to this. */
+export const LOG_BACKOFF_MAX_MS = 30_000;
+
+/** The log stream's URL: `apiUrl("/admin/logs")` made absolute (a relative one takes this page's origin) on `ws:`/`wss:` to
+ * match. `undefined` where there is no origin to use (server-side rendering). */
+export function logsUrl(): string | undefined {
+    const url = apiUrl("/admin/logs");
+    let absolute: string | undefined = url;
+    if (!/^https?:\/\//i.test(url)) {
+        absolute = typeof window === "undefined" ? undefined : `${window.location.origin}${url}`;
+    }
+    return absolute?.replace(/^http/i, "ws");
+}
+
+function defaultSocketFactory(): LogSocketFactory | undefined {
+    return typeof WebSocket === "undefined" ? undefined : (url) => new WebSocket(url) as unknown as LogSocket;
+}
+
+/** What the error for a refused stream says: the server's reason is an error code, so it is shown as one. */
+export function refusedMessage(reason: string | undefined): string {
+    return reason
+        ? `The server refused the log stream (${reason}). Check that you are an administrator and that log streaming is enabled.`
+        : "The server refused the log stream. Check that you are an administrator and that log streaming is enabled.";
+}
+
+export interface LogClientOptions {
+    /** The URL to connect to. Defaults to `logsUrl()`. */
+    url?: () => string | undefined;
+    /** Creates the socket. Defaults to the browser's `WebSocket`, if there is one. */
+    createSocket?: LogSocketFactory;
+    /** A `Math.random()` stand-in, for the backoff's jitter. */
+    random?: () => number;
+    /** A clock, for the time lines are received at. */
+    now?: () => number;
+}
+
+export class LogClient {
+    private socket: LogSocket | undefined;
+    private running = false;
+    private attempt = 0;
+    private timer: ReturnType<typeof setTimeout> | undefined;
+    private nextId = 1;
+    private current: LogStreamStatus = "closed";
+    private failure: string | undefined;
+    private readonly entryListeners = new Set<(entry: LogEntry) => void>();
+    private readonly statusListeners = new Set<(status: LogStreamStatus, error: string | undefined) => void>();
+
+    constructor(private readonly options: LogClientOptions = {}) {}
+
+    get status(): LogStreamStatus {
+        return this.current;
+    }
+
+    /** Why the stream is in the `error` state. */
+    get error(): string | undefined {
+        return this.failure;
+    }
+
+    /** Connects, and keeps reconnecting until `stop()`, or until the server refuses the stream. A no-op while it already runs. */
+    start(): void {
+        if (this.running) {
+            return;
+        }
+        this.running = true;
+        this.attempt = 0;
+        this.connect();
+    }
+
+    /** Closes the socket and stops reconnecting. The client can be started again. */
+    stop(): void {
+        this.running = false;
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        this.detach();
+        this.setStatus("closed");
+    }
+
+    /** Calls `listener` with every log line; returns the function that stops it. */
+    onEntry(listener: (entry: LogEntry) => void): () => void {
+        this.entryListeners.add(listener);
+        return () => this.entryListeners.delete(listener);
+    }
+
+    /** Calls `listener` whenever the status changes; returns the function that stops it. */
+    onStatus(listener: (status: LogStreamStatus, error: string | undefined) => void): () => void {
+        this.statusListeners.add(listener);
+        return () => this.statusListeners.delete(listener);
+    }
+
+    private setStatus(status: LogStreamStatus, error?: string): void {
+        if (status === this.current && error === this.failure) {
+            return;
+        }
+        this.current = status;
+        this.failure = error;
+        for (const listener of [...this.statusListeners]) {
+            listener(status, error);
+        }
+    }
+
+    /** Lets go of the socket without hearing about it any more, and closes it. */
+    private detach(): void {
+        const socket = this.socket;
+        this.socket = undefined;
+        if (socket) {
+            socket.onopen = socket.onmessage = socket.onclose = socket.onerror = null;
+            try {
+                socket.close(1000, "closing");
+            } catch {
+                // Already gone.
+            }
+        }
+    }
+
+    private connect(): void {
+        const url = (this.options.url ?? logsUrl)();
+        const createSocket = this.options.createSocket ?? defaultSocketFactory();
+        if (!url || !createSocket) {
+            this.running = false;
+            this.setStatus("error", "This browser cannot open a WebSocket to the server.");
+            return;
+        }
+        let socket: LogSocket;
+        try {
+            socket = createSocket(url);
+        } catch {
+            this.scheduleReconnect();
+            return;
+        }
+        this.socket = socket;
+        this.setStatus(this.attempt === 0 ? "connecting" : "reconnecting");
+        socket.onmessage = (event) => this.handleFrame(event.data);
+        socket.onclose = (event) => {
+            if (this.socket !== socket) {
+                return;
+            }
+            this.socket = undefined;
+            if (event.code === LOG_CLOSE_REFUSED) {
+                this.running = false;
+                this.setStatus("error", refusedMessage(event.reason));
+                return;
+            }
+            this.scheduleReconnect();
+        };
+        // A failed connection is followed by a close, which is what triggers the retry.
+        socket.onerror = () => undefined;
+    }
+
+    /** Waits out an exponentially growing, jittered delay ("equal jitter": half fixed, half random), then reconnects. */
+    private scheduleReconnect(): void {
+        const ceiling = Math.min(LOG_BACKOFF_MAX_MS, LOG_BACKOFF_BASE_MS * 2 ** Math.min(this.attempt, 30));
+        const delay = ceiling / 2 + ((this.options.random ?? Math.random)() * ceiling) / 2;
+        this.attempt += 1;
+        this.setStatus("reconnecting");
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            this.connect();
+        }, delay);
+    }
+
+    private handleFrame(data: unknown): void {
+        if (typeof data !== "string") {
+            return;
+        }
+        const frame = parseLogFrame(data, this.nextId, (this.options.now ?? Date.now)());
+        if (isControlFrame(frame)) {
+            if (frame.success) {
+                this.attempt = 0;
+                this.setStatus("live");
+            } else {
+                // The server accepted the socket and refused the subscription: nothing will ever be sent.
+                this.running = false;
+                this.detach();
+                this.setStatus("error", refusedMessage(undefined));
+            }
+            return;
+        }
+        this.nextId += 1;
+        if (this.current !== "live") {
+            // A line before the greeting means the stream is flowing.
+            this.attempt = 0;
+            this.setStatus("live");
+        }
+        for (const listener of [...this.entryListeners]) {
+            listener(frame);
+        }
+    }
+}