@rapidmx/web-client 0.17.2 → 0.19.0

package/dist/apps/shared/components/admin/diagnostics/useLogStream.d.ts

@@ -0,0 +1,37 @@
+import { LogClientOptions, LogStreamStatus } from "./logClient.js";
+import type { LogEntry } from "./logLines.js";
+/** Lines arrive in bursts; the view is redrawn at most this often, however many came. */
+export declare const LOG_FLUSH_MS = 100;
+/** What a capture has recorded, without the lines (which can be tens of thousands: `LogStream.captureEntries()` has them). */
+export interface CaptureSummary {
+    active: boolean;
+    startedAt: number;
+    stoppedAt: number | undefined;
+    count: number;
+    missed: number;
+}
+export interface LogStream {
+    status: LogStreamStatus;
+    /** Why the stream is in the `error` state. */
+    error: string | undefined;
+    /** Whether the stream is on (connecting, live or trying again), as opposed to stopped or refused. */
+    running: boolean;
+    /** The display buffer: the most recent lines, oldest first. */
+    entries: LogEntry[];
+    /** How many older lines the display buffer has dropped. */
+    dropped: number;
+    capture: CaptureSummary | undefined;
+    start: () => void;
+    stop: () => void;
+    /** Empties the display buffer (not a capture). */
+    clear: () => void;
+    startCapture: () => void;
+    stopCapture: () => void;
+    /** Every line of the capture, for a download. */
+    captureEntries: () => LogEntry[];
+}
+/**
+ * The live log stream of the server for the log view: a `LogClient`, and a `LogStore` holding the lines and any capture. Nothing
+ * connects until `start()`. The stream is closed, and the redraw timer cleared, when the component unmounts.
+ */
+export declare function useLogStream(options?: LogClientOptions): LogStream;

package/dist/apps/shared/components/admin/diagnostics/useLogStream.js

@@ -0,0 +1,79 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useCallback, useEffect, useRef, useState } from "react";
+import { LogClient } from "./logClient.js";
+import { LogStore } from "./LogStore.js";
+/** Lines arrive in bursts; the view is redrawn at most this often, however many came. */
+export const LOG_FLUSH_MS = 100;
+function snapshotOf(store) {
+    const capture = store.capture;
+    return {
+        entries: store.entries.slice(),
+        dropped: store.dropped,
+        capture: capture && {
+            active: capture.active,
+            startedAt: capture.startedAt,
+            stoppedAt: capture.stoppedAt,
+            count: capture.entries.length,
+            missed: capture.missed,
+        },
+    };
+}
+/**
+ * The live log stream of the server for the log view: a `LogClient`, and a `LogStore` holding the lines and any capture. Nothing
+ * connects until `start()`. The stream is closed, and the redraw timer cleared, when the component unmounts.
+ */
+export function useLogStream(options = {}) {
+    const [client] = useState(() => new LogClient(options));
+    const [store] = useState(() => new LogStore());
+    const [connection, setConnection] = useState({
+        status: client.status,
+        error: undefined,
+    });
+    const [snapshot, setSnapshot] = useState(() => snapshotOf(store));
+    const timer = useRef(undefined);
+    const flush = useCallback(() => {
+        clearTimeout(timer.current);
+        timer.current = undefined;
+        setSnapshot(snapshotOf(store));
+    }, [store]);
+    useEffect(() => {
+        const stopEntries = client.onEntry((entry) => {
+            store.add(entry);
+            timer.current ?? (timer.current = setTimeout(flush, LOG_FLUSH_MS));
+        });
+        const stopStatus = client.onStatus((status, error) => setConnection({ status, error }));
+        return () => {
+            stopEntries();
+            stopStatus();
+            client.stop();
+            clearTimeout(timer.current);
+            timer.current = undefined;
+        };
+    }, [client, store, flush]);
+    return {
+        status: connection.status,
+        error: connection.error,
+        running: connection.status === "connecting" || connection.status === "live" || connection.status === "reconnecting",
+        entries: snapshot.entries,
+        dropped: snapshot.dropped,
+        capture: snapshot.capture,
+        start: () => client.start(),
+        stop: () => client.stop(),
+        clear: () => {
+            store.clear();
+            flush();
+        },
+        startCapture: () => {
+            store.startCapture(Date.now());
+            flush();
+        },
+        stopCapture: () => {
+            store.stopCapture(Date.now());
+            flush();
+        },
+        captureEntries: () => store.capture?.entries ?? [],
+    };
+}

package/dist/apps/shared/components/admin/diagnostics/useMetricsPolling.d.ts

@@ -0,0 +1,20 @@
+import { DiagnosticsMetrics } from "./diagnosticsApi.js";
+export interface MetricsPolling {
+    /** The last `METRICS_HISTORY_SIZE` samples, oldest first. */
+    history: DiagnosticsMetrics[];
+    /** Why the last request failed, until one succeeds. */
+    error: string | undefined;
+    /** Whether nothing has been answered yet. */
+    loading: boolean;
+    /** Whether polling is stopped by the viewer (Pause), or because the server refused the viewer. */
+    paused: boolean;
+    setPaused: (paused: boolean) => void;
+}
+/**
+ * Samples `getDiagnosticsMetrics()` every `METRICS_POLL_INTERVAL_MS` while `enabled` and not paused, keeping the last
+ * `METRICS_HISTORY_SIZE`. A request is only ever made when the previous one has answered, none is made while the page is
+ * hidden (one is made at once when it is shown again), and polling stops when the component unmounts. A refusal (401/403)
+ * pauses polling, since asking again would only be refused again; Resume tries once more. Any other failure is shown
+ * and polling carries on, so a blip on the server does not need the viewer to do anything.
+ */
+export declare function useMetricsPolling(enabled: boolean): MetricsPolling;

package/dist/apps/shared/components/admin/diagnostics/useMetricsPolling.js

@@ -0,0 +1,69 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import { getDiagnosticsMetrics } from "./diagnosticsApi.js";
+import { describeError, isPermissionError } from "./format.js";
+import { appendSample, METRICS_POLL_INTERVAL_MS } from "./metricsHistory.js";
+/**
+ * Samples `getDiagnosticsMetrics()` every `METRICS_POLL_INTERVAL_MS` while `enabled` and not paused, keeping the last
+ * `METRICS_HISTORY_SIZE`. A request is only ever made when the previous one has answered, none is made while the page is
+ * hidden (one is made at once when it is shown again), and polling stops when the component unmounts. A refusal (401/403)
+ * pauses polling, since asking again would only be refused again; Resume tries once more. Any other failure is shown
+ * and polling carries on, so a blip on the server does not need the viewer to do anything.
+ */
+export function useMetricsPolling(enabled) {
+    const [history, setHistory] = useState([]);
+    const [error, setError] = useState();
+    const [loading, setLoading] = useState(true);
+    const [paused, setPaused] = useState(false);
+    useEffect(() => {
+        if (!enabled || paused) {
+            return;
+        }
+        let cancelled = false;
+        let inFlight = false;
+        async function sample() {
+            if (inFlight || document.hidden) {
+                return;
+            }
+            inFlight = true;
+            try {
+                const next = await getDiagnosticsMetrics();
+                if (!cancelled) {
+                    setHistory((previous) => appendSample(previous, next));
+                    setError(undefined);
+                }
+            }
+            catch (err) {
+                if (!cancelled) {
+                    setError(describeError(err, "Could not read the server's metrics."));
+                    if (isPermissionError(err)) {
+                        setPaused(true);
+                    }
+                }
+            }
+            finally {
+                inFlight = false;
+                if (!cancelled) {
+                    setLoading(false);
+                }
+            }
+        }
+        void sample();
+        const timer = setInterval(() => void sample(), METRICS_POLL_INTERVAL_MS);
+        const onVisibilityChange = () => {
+            if (!document.hidden) {
+                void sample();
+            }
+        };
+        document.addEventListener("visibilitychange", onVisibilityChange);
+        return () => {
+            cancelled = true;
+            clearInterval(timer);
+            document.removeEventListener("visibilitychange", onVisibilityChange);
+        };
+    }, [enabled, paused]);
+    return { history, error, loading, paused, setPaused };
+}

package/dist/apps/shared/components/admin/layout/AdminShell.d.ts

@@ -2,7 +2,7 @@ import "../../../styles/app.css";
 import React, { PropsWithChildren } from "react";
 import type { NavItem } from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
 import { PluginNav, PluginNavProps } from "../../../plugins/pluginNav.js";
-export type AdminSection = "mailboxes" | "quarantine" | "ingestQueue" | "domains" | "auditLog" | "distributionLists" | "transportRules" | "escrowScopes" | "retentionPolicy" | "encryptionPolicy" | "mailboxPolicy" | "setup" | "dataRequests" | "plugins" | "branding" | "signingCertificates";
+export type AdminSection = "mailboxes" | "quarantine" | "ingestQueue" | "domains" | "auditLog" | "distributionLists" | "transportRules" | "escrowScopes" | "retentionPolicy" | "encryptionPolicy" | "mailboxPolicy" | "setup" | "dataRequests" | "plugins" | "diagnostics" | "branding" | "signingCertificates";
 /** A core `AdminSection`, or a plugin's `adminNav` item id (see `PluginNav`). */
 export type AdminShellActive = AdminSection | (string & {});
 export interface AdminShellProps extends PluginNavProps {

package/dist/apps/shared/components/admin/layout/AdminShell.js

@@ -6,7 +6,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import "../../../styles/app.css";
 import { useEffect, useState } from "react";
 import { useRouter } from "@rapidrest/react/client";
-import { HiOutlineClipboardDocumentList, HiOutlineClock, HiOutlineDocumentArrowDown, HiOutlineDocumentCheck, HiOutlineGlobeAlt, HiOutlineInboxStack, HiOutlineKey, HiOutlineLockClosed, HiOutlinePaintBrush, HiOutlinePuzzlePiece, HiOutlineQueueList, HiOutlineRocketLaunch, HiOutlineShieldCheck, HiOutlineShieldExclamation, HiOutlineUserGroup, HiOutlineWrenchScrewdriver, HiOutlineBars3, } from "react-icons/hi2";
+import { HiOutlineClipboardDocumentList, HiOutlineClock, HiOutlineCpuChip, HiOutlineDocumentArrowDown, HiOutlineDocumentCheck, HiOutlineGlobeAlt, HiOutlineInboxStack, HiOutlineKey, HiOutlineLockClosed, HiOutlinePaintBrush, HiOutlinePuzzlePiece, HiOutlineQueueList, HiOutlineRocketLaunch, HiOutlineShieldCheck, HiOutlineShieldExclamation, HiOutlineUserGroup, HiOutlineWrenchScrewdriver, HiOutlineBars3, } from "react-icons/hi2";
 import { apiFetch, ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { getSetupStatus } from "@rapidmx/react-shared/admin/setupApi.js";
 import { useRedirectIfUnauthenticated } from "@rapidmx/react-shared/auth/session.js";
@@ -78,6 +78,7 @@ const NAV_ITEMS = [
         icon: HiOutlineDocumentCheck,
     },
     { id: "plugins", href: "/admin/plugins", label: "Plugins", icon: HiOutlinePuzzlePiece },
+    { id: "diagnostics", href: "/admin/diagnostics", label: "Diagnostics", icon: HiOutlineCpuChip },
     { id: "branding", href: "/admin/branding", label: "Branding", icon: HiOutlinePaintBrush },
 ];
 /** Mailbox-scoped sections — not part of the global nav rail/tab bar (see `NAV_ITEMS` above), but

package/dist/apps/shared/components/admin/settings/PluginsManager.js

@@ -616,13 +616,32 @@ function suggestedHost(definition, saved) {
     const unset = saved === undefined || saved === "" || (typeof saved === "string" && saved.includes(HOST_PLACEHOLDER));
     return unset ? definition.default.split(HOST_PLACEHOLDER).join(window.location.host) : undefined;
 }
-/** A setting's current form value: its saved value, else its default - or, for a required select with neither, its
- * first option. Kept as a string for text inputs. */
-function initialValue(definition, saved) {
+/** What the deployment configures for a setting, as a form value: nothing for a secret, whose value the server keeps to itself. */
+function configuredValue(definition, configured) {
+    if (definition.type === "boolean") {
+        return configured.value === true;
+    }
+    return configured.value === undefined ? "" : String(configured.value);
+}
+/** Whether a saved value is absent - nothing, or the empty value a plugin's own "" default is saved as. */
+function isUnsaved(saved) {
+    return saved === undefined || saved === "";
+}
+/** The suggestion for the host, unless the deployment configures the setting, which is offered instead. */
+function hostSuggestion(definition, saved, configured) {
+    return configured ? undefined : suggestedHost(definition, saved);
+}
+/** A setting's current form value: its saved value (which wins over the deployment's configuration); else what the
+ * deployment configures; else the setting's own default - or, for a required select with none of those, its first
+ * option. Kept as a string for text inputs. */
+function initialValue(definition, saved, configured) {
+    if (configured && isUnsaved(saved)) {
+        return configuredValue(definition, configured);
+    }
     if (needsSelection(definition, saved)) {
         return definition.options[0].value;
     }
-    const suggestion = suggestedHost(definition, saved);
+    const suggestion = hostSuggestion(definition, saved, configured);
     if (suggestion !== undefined) {
         return suggestion;
     }
@@ -635,28 +654,51 @@ function initialValue(definition, saved) {
 function SettingsModal({ plugin, onClose, onSaved }) {
     // Only opened from the Settings button, which is only shown for a plugin that declares settings.
     const definitions = plugin.manifest.settings;
-    const initial = useRef(Object.fromEntries(definitions.map((d) => [d.key, initialValue(d, plugin.settings[d.key])])));
+    const initial = useRef(Object.fromEntries(definitions.map((d) => [d.key, initialValue(d, plugin.settings[d.key], plugin.configured?.[d.key])])));
     const [values, setValues] = useState(initial.current);
+    // Set by Reset: saving then drops every saved value, so the deployment's configuration (or the default) applies again.
+    const [resetting, setResetting] = useState(false);
     const [error, setError] = useState(null);
     const [busy, setBusy] = useState(false);
+    /** Puts every field back to what it shows with nothing saved. Nothing is stored until the form is saved. */
+    function reset() {
+        setValues(Object.fromEntries(definitions.map((d) => [d.key, initialValue(d, undefined, plugin.configured?.[d.key])])));
+        setResetting(true);
+        setError(null);
+    }
     async function save(e) {
         e.preventDefault();
         // The server replaces the whole settings object, so every setting is sent. One left alone is sent as it's saved
         // - `null` when nothing is, so it keeps following the plugin's default rather than pinning the default shown.
         // A required select with nothing to fall back on, and a setting offering this console's host, are sent as the
-        // form shows them.
+        // form shows them. What the deployment configures is never saved as a copy, which would outrank it when it changes
+        // - a field that shows it is sent as nothing.
         const settings = {};
         let changed = false;
         for (const definition of definitions) {
             const key = definition.key;
+            const configured = plugin.configured?.[key];
+            const saved = plugin.settings[key];
             const value = values[key];
-            if (value === initial.current[key] && !needsSelection(definition, plugin.settings[key]) && suggestedHost(definition, plugin.settings[key]) === undefined) {
-                settings[key] = plugin.settings[key] ?? null;
+            if (resetting && value === initialValue(definition, undefined, configured)) {
+                // What a fresh install saves: only a default naming this console's host has to be, for the plugin to work.
+                // A saved value that already is the default shown stays, since dropping it changes nothing.
+                settings[key] = !configured && saved !== undefined && String(saved) === String(value) ? saved : (hostSuggestion(definition, undefined, configured) ?? null);
+                changed || (changed = settings[key] !== (saved ?? null));
+                continue;
+            }
+            if (!resetting && value === initial.current[key] && !needsSelection(definition, saved) && hostSuggestion(definition, saved, configured) === undefined) {
+                settings[key] = saved ?? null;
                 continue;
             }
             changed = true;
             // A number input only ever reports a valid number or an empty string.
-            settings[key] = value === "" ? null : definition.type === "number" ? Number(value) : value;
+            settings[key] =
+                value === "" || (configured && !configured.secret && String(value) === String(configured.value))
+                    ? null
+                    : definition.type === "number"
+                        ? Number(value)
+                        : value;
         }
         if (!changed) {
             onClose();
@@ -674,15 +716,21 @@ function SettingsModal({ plugin, onClose, onSaved }) {
             setBusy(false);
         }
     }
-    return (_jsxs(Modal, { open: true, onClose: onClose, title: `${plugin.manifest.displayName} settings`, children: [error && _jsx(Alert, { children: error }), _jsxs("form", { onSubmit: save, className: "flex flex-col gap-5", children: [definitions.map((definition) => (_jsx(SettingField, { definition: definition, value: values[definition.key], onChange: (value) => setValues((prev) => ({ ...prev, [definition.key]: value })) }, definition.key))), _jsxs("div", { className: "sticky -bottom-7 -mx-7 -mb-7 px-7 py-4 bg-surface border-t border-border flex flex-col gap-3", children: [_jsx("p", { className: "text-xs text-text-muted", children: "Saving restarts the servers one at a time to apply the new settings." }), _jsxs("div", { className: "flex gap-2 justify-end", children: [_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: onClose, children: "Cancel" }), _jsx(Button, { type: "submit", className: "!w-auto", loading: busy, disabled: busy, children: "Save" })] })] })] })] }));
+    return (_jsxs(Modal, { open: true, onClose: onClose, title: `${plugin.manifest.displayName} settings`, children: [error && _jsx(Alert, { children: error }), _jsxs("form", { onSubmit: save, className: "flex flex-col gap-5", children: [definitions.map((definition) => (_jsx(SettingField, { definition: definition, value: values[definition.key], configured: plugin.configured?.[definition.key], onChange: (value) => setValues((prev) => ({ ...prev, [definition.key]: value })) }, definition.key))), _jsxs("div", { className: "sticky -bottom-7 -mx-7 -mb-7 px-7 py-4 bg-surface border-t border-border flex flex-col gap-3", children: [_jsx("p", { className: "text-xs text-text-muted", children: resetting
+                                    ? "Every setting is back to what this deployment's configuration or the plugin's default gives. Save to apply that."
+                                    : "Saving restarts the servers one at a time to apply the new settings." }), _jsxs("div", { className: "flex gap-2 justify-end", children: [_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto mr-auto", onClick: reset, disabled: busy, children: "Reset" }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: onClose, children: "Cancel" }), _jsx(Button, { type: "submit", className: "!w-auto", loading: busy, disabled: busy, children: "Save" })] })] })] })] }));
 }
-function SettingField({ definition, value, onChange, }) {
-    const help = definition.help && _jsx("span", { className: "text-xs text-text-muted", children: definition.help });
+function SettingField({ definition, value, configured, onChange, }) {
+    // What applies without a saved value; one saved here replaces it, and Reset goes back to it.
+    const note = configured && (_jsxs("span", { className: "text-xs text-text-muted", children: ["This deployment's configuration provides ", configured.secret ? "a value" : "the value shown", " unless one is saved here."] }));
+    // A secret's value never reaches the browser, so the field only says that it is set.
+    const placeholder = configured?.secret ? "Set by this deployment" : undefined;
+    const help = (_jsxs(_Fragment, { children: [definition.help && _jsx("span", { className: "text-xs text-text-muted", children: definition.help }), note] }));
     if (definition.type === "boolean") {
         // Laid out like the admin policy forms' checkboxes: the help sits under the label, beside the box.
         return (_jsxs("label", { className: "flex items-start gap-2 text-sm", children: [_jsx("input", { type: "checkbox", className: "mt-1", checked: value === true, onChange: (e) => onChange(e.target.checked) }), _jsxs("span", { className: "flex flex-col gap-0.5", children: [_jsx("span", { className: "font-semibold", children: definition.label }), help] })] }));
     }
-    return (_jsxs("label", { className: "flex flex-col gap-1.5 text-sm", children: [_jsx("span", { className: "font-semibold", children: definition.label }), definition.type === "select" ? (_jsxs("select", { "aria-label": definition.label, className: INPUT_CLASS, value: String(value), onChange: (e) => onChange(e.target.value), children: [!definition.required && _jsx("option", { value: "", children: "Default" }), (definition.options ?? []).map((option) => (_jsx("option", { value: option.value, children: option.label }, option.value)))] })) : (_jsx("input", { "aria-label": definition.label, className: INPUT_CLASS, type: definition.type === "number" ? "number" : "text", min: definition.min, max: definition.max, required: definition.required, value: String(value), onChange: (e) => onChange(e.target.value) })), help] }));
+    return (_jsxs("label", { className: "flex flex-col gap-1.5 text-sm", children: [_jsx("span", { className: "font-semibold", children: definition.label }), definition.type === "select" ? (_jsxs("select", { "aria-label": definition.label, className: INPUT_CLASS, value: String(value), onChange: (e) => onChange(e.target.value), children: [!definition.required && _jsx("option", { value: "", children: "Default" }), (definition.options ?? []).map((option) => (_jsx("option", { value: option.value, children: option.label }, option.value)))] })) : (_jsx("input", { "aria-label": definition.label, className: INPUT_CLASS, type: definition.type === "number" ? "number" : "text", min: definition.min, max: definition.max, required: definition.required && !configured, placeholder: placeholder, value: String(value), onChange: (e) => onChange(e.target.value) })), help] }));
 }
 function RemoveModal({ plugin, onClose, onRemoved }) {
     const [error, setError] = useState(null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rapidmx/web-client",
-  "version": "0.17.2",
+  "version": "0.19.0",
   "description": "RapidMX's webmail and admin console React UI for web-based clients.",
   "type": "module",
   "repository": "https://github.com/rapidmx/web-client",
@@ -40,7 +40,7 @@
     "@dnd-kit/core": "^6.3.1",
     "@journeyapps/wa-sqlite": "^2.0.4",
     "@peculiar/x509": "^2.1.0",
-    "@rapidmx/react-shared": "^0.19.0",
+    "@rapidmx/react-shared": "^0.20.0",
     "@tiptap/core": "^3.31.3",
     "@tiptap/extension-highlight": "^3.31.3",
     "@tiptap/extension-image": "^3.31.3",