milestone 9: react spa admin ui, frontend ci and embedded dist

This commit is contained in:
2026-08-02 13:04:09 +02:00
parent 5253c47303
commit 617cc966a2
82 changed files with 11833 additions and 17 deletions
@@ -0,0 +1,28 @@
import { act, fireEvent, render, screen } from "@testing-library/react";
import RestartBanner from "@/features/settings/RestartBanner";
import { dismissRestartBanner, raiseRestartBanner } from "@/features/settings/restartBanner";
beforeEach(() => {
act(() => dismissRestartBanner());
});
test("hidden until raised, dismissible, and a new raise shows it again", () => {
render(<RestartBanner />);
expect(screen.queryByRole("status")).toBeNull();
act(() => raiseRestartBanner());
expect(screen.getByRole("status").textContent).toContain("Restart nxdns to apply");
fireEvent.click(screen.getByRole("button", { name: "Dismiss" }));
expect(screen.queryByRole("status")).toBeNull();
act(() => raiseRestartBanner());
expect(screen.getByRole("status")).toBeTruthy();
});
test("raising while already raised keeps the banner up", () => {
render(<RestartBanner />);
act(() => raiseRestartBanner());
act(() => raiseRestartBanner());
expect(screen.getByRole("status")).toBeTruthy();
});
@@ -0,0 +1,21 @@
import { dismissRestartBanner, useRestartBanner } from "./restartBanner";
export default function RestartBanner() {
const raised = useRestartBanner();
if (!raised) return null;
return (
<div
role="status"
className="flex items-center gap-3 border-b border-amber-300 bg-amber-50 px-4 py-2 text-sm text-amber-900 dark:border-amber-800 dark:bg-amber-950 dark:text-amber-100"
>
<span className="flex-1">Settings saved. Restart nxdns to apply.</span>
<button
type="button"
onClick={dismissRestartBanner}
className="rounded border border-amber-400 px-2 py-1 text-xs focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-600 dark:border-amber-700"
>
Dismiss
</button>
</div>
);
}
@@ -0,0 +1,234 @@
import { Suspense } from "react";
import { QueryClientProvider } from "@tanstack/react-query";
import { fireEvent, render, screen, waitFor, within } from "@testing-library/react";
import { act } from "react";
import SettingsPage, { patchRequiresRestart } from "@/features/settings/SettingsPage";
import RestartBanner from "@/features/settings/RestartBanner";
import { dismissRestartBanner } from "@/features/settings/restartBanner";
import { createQueryClient } from "@/lib/queryClient";
import type { Settings, SettingsPatch } from "@/lib/types";
function baseSettings(): Settings {
return {
runtime: { io_backend: "threaded" },
upstream: { connect_timeout_ms: 2000, read_timeout_ms: 3000, total_timeout_ms: 5000 },
dns: { bind_ipv4: "0.0.0.0", bind_ipv6: "::", port: 53, rate_limit: 100, rate_window_seconds: 60 },
blocking: { response: "zero", ttl: 300 },
cache: { size: 10000, negative_ttl_max: 300 },
web: {
enabled: true,
bind: "127.0.0.1",
port: 8080,
session_ttl_hours: 24,
api_rate_limit_per_min: 60,
api_localhost_exempt: true,
sse_max_connections_per_ip: 2,
auth_enabled: true,
},
doh_server: { enabled: false, bind: "0.0.0.0", port: 443, cert_path: "", key_path: "" },
dot_server: { enabled: false, bind: "0.0.0.0", port: 853, cert_path: "", key_path: "" },
edns: { ecs_mode: "strip" },
logging: {
level: "info",
retention_days: 30,
query_log_buffer_max: 10000,
hide_domains: false,
hide_client_ips: false,
output: "stderr",
file_path: "",
max_size_mb: 50,
max_files: 3,
},
disk: { min_free_mb: 100, warn_free_mb: 500 },
blocklist_update: { enabled: true, interval_hours: 24 },
};
}
let putBodies: SettingsPatch[];
let putResponse: () => Response | Promise<Response>;
let storedSettings: Settings;
function jsonResponse(payload: unknown, status = 200): Response {
return new Response(JSON.stringify(payload), { status, headers: { "content-type": "application/json" } });
}
function applyPatch(patch: SettingsPatch): void {
const settings = storedSettings as unknown as Record<string, Record<string, unknown>>;
for (const [section, fields] of Object.entries(patch)) {
for (const [key, value] of Object.entries(fields as Record<string, unknown>)) {
if (section === "web" && key === "password") continue;
settings[section]![key] = value;
}
}
}
beforeEach(() => {
act(() => dismissRestartBanner());
putBodies = [];
storedSettings = baseSettings();
putResponse = () => {
applyPatch(putBodies[putBodies.length - 1]!);
return jsonResponse({ settings: storedSettings, restart_required: ["dns.port"] });
};
vi.stubGlobal(
"fetch",
vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
const url = String(input);
if (url !== "/api/settings") return jsonResponse({ error: "not stubbed" }, 404);
if (init?.method === "PUT") {
putBodies.push(JSON.parse(String(init.body)) as SettingsPatch);
return putResponse();
}
return jsonResponse({ settings: storedSettings, restart_required: ["dns.port"] });
}),
);
});
afterEach(() => {
vi.unstubAllGlobals();
});
async function renderPage() {
render(
<QueryClientProvider client={createQueryClient()}>
<RestartBanner />
<Suspense fallback={<p>loading</p>}>
<SettingsPage />
</Suspense>
</QueryClientProvider>,
);
await screen.findByRole("heading", { name: "Settings" });
}
function saveButton(): HTMLButtonElement {
return screen.getByRole("button", { name: "Save" }) as HTMLButtonElement;
}
test("no changes means Save is disabled and auth_enabled shows read-only", async () => {
await renderPage();
expect(saveButton().disabled).toBe(true);
expect(screen.getByText(/auth_enabled: true/).textContent).toContain("read-only");
});
test("a changed field enables Save and the PUT body is exactly the diff", async () => {
await renderPage();
const dns = screen.getByRole("group", { name: "DNS" });
fireEvent.change(within(dns).getByLabelText("port"), { target: { value: "5353" } });
expect(saveButton().disabled).toBe(false);
fireEvent.click(saveButton());
await waitFor(() => expect(putBodies).toHaveLength(1));
expect(putBodies[0]).toEqual({ dns: { port: 5353 } });
expect((await screen.findByRole("status")).textContent).toContain("Restart nxdns to apply");
await waitFor(() => expect(saveButton().disabled).toBe(true));
});
test("enum and boolean fields diff as their own types", async () => {
await renderPage();
const logging = screen.getByRole("group", { name: "Logging" });
fireEvent.change(within(logging).getByLabelText("level"), { target: { value: "debug" } });
fireEvent.click(within(logging).getByLabelText("hide_domains"));
fireEvent.click(saveButton());
await waitFor(() => expect(putBodies).toHaveLength(1));
expect(putBodies[0]).toEqual({ logging: { level: "debug", hide_domains: true } });
});
test("clearing a number field disables Save instead of sending NaN", async () => {
await renderPage();
const cache = screen.getByRole("group", { name: "Cache" });
fireEvent.change(within(cache).getByLabelText("size"), { target: { value: "" } });
expect(saveButton().disabled).toBe(true);
});
test("password flow: note shown, confirm required, PUT sends web.password, no banner", async () => {
await renderPage();
const web = screen.getByRole("group", { name: "Web" });
const passwordInput = within(web).getByLabelText("password") as HTMLInputElement;
const confirmInput = within(web).getByLabelText("confirm password") as HTMLInputElement;
expect(passwordInput.value).toBe("");
fireEvent.change(passwordInput, { target: { value: "hunter2" } });
expect(screen.getByText(/signs out every session/)).toBeTruthy();
expect(screen.getByText("Passwords do not match.")).toBeTruthy();
expect(saveButton().disabled).toBe(true);
fireEvent.change(confirmInput, { target: { value: "hunter2" } });
expect(screen.queryByText("Passwords do not match.")).toBeNull();
expect(saveButton().disabled).toBe(false);
fireEvent.click(saveButton());
await waitFor(() => expect(putBodies).toHaveLength(1));
expect(putBodies[0]).toEqual({ web: { password: "hunter2" } });
await waitFor(() => expect(passwordInput.value).toBe(""));
expect(confirmInput.value).toBe("");
expect(screen.queryByRole("status")).toBeNull();
});
test("a mixed patch with a password still raises the banner", async () => {
await renderPage();
const web = screen.getByRole("group", { name: "Web" });
fireEvent.change(within(web).getByLabelText("session_ttl_hours"), { target: { value: "48" } });
fireEvent.change(within(web).getByLabelText("password"), { target: { value: "hunter2" } });
fireEvent.change(within(web).getByLabelText("confirm password"), { target: { value: "hunter2" } });
fireEvent.click(saveButton());
await waitFor(() => expect(putBodies).toHaveLength(1));
expect(putBodies[0]).toEqual({ web: { session_ttl_hours: 48, password: "hunter2" } });
expect(await screen.findByRole("status")).toBeTruthy();
});
test("the form is disabled while the PUT is pending and re-enabled after success", async () => {
await renderPage();
let resolvePut!: (response: Response) => void;
putResponse = () => new Promise<Response>((resolve) => (resolvePut = resolve));
const dns = screen.getByRole("group", { name: "DNS" });
const port = within(dns).getByLabelText("port") as HTMLInputElement;
fireEvent.change(port, { target: { value: "5353" } });
fireEvent.click(saveButton());
await screen.findByRole("button", { name: "Saving…" });
expect(port.matches(":disabled")).toBe(true);
const web = screen.getByRole("group", { name: "Web" });
expect(within(web).getByLabelText("password").matches(":disabled")).toBe(true);
applyPatch(putBodies[putBodies.length - 1]!);
resolvePut(jsonResponse({ settings: storedSettings, restart_required: ["dns.port"] }));
await waitFor(() => expect(port.matches(":disabled")).toBe(false));
expect(saveButton().textContent).toBe("Save");
});
test("a 429 shows the rate-limit countdown from Retry-After", async () => {
await renderPage();
putResponse = () =>
new Response(JSON.stringify({ error: "too many requests" }), {
status: 429,
headers: { "content-type": "application/json", "Retry-After": "30" },
});
const dns = screen.getByRole("group", { name: "DNS" });
fireEvent.change(within(dns).getByLabelText("port"), { target: { value: "5353" } });
fireEvent.click(saveButton());
expect((await screen.findByRole("alert")).textContent).toBe("Rate limited. Try again in 30s.");
expect(screen.queryByRole("status")).toBeNull();
});
test("a 400 validation error surfaces inline and raises no banner", async () => {
await renderPage();
putResponse = () => jsonResponse({ error: "dns.port out of range" }, 400);
const dns = screen.getByRole("group", { name: "DNS" });
fireEvent.change(within(dns).getByLabelText("port"), { target: { value: "70000" } });
fireEvent.click(saveButton());
expect((await screen.findByRole("alert")).textContent).toBe("dns.port out of range");
expect(screen.queryByRole("status")).toBeNull();
expect(saveButton().disabled).toBe(false);
});
test("patchRequiresRestart ignores only a bare web.password", () => {
expect(patchRequiresRestart({ web: { password: "x" } })).toBe(false);
expect(patchRequiresRestart({ web: { password: "x", port: 9090 } })).toBe(true);
expect(patchRequiresRestart({ dns: { port: 5353 } })).toBe(true);
expect(patchRequiresRestart({ web: { password: "x" }, cache: { size: 1 } })).toBe(true);
});
+329
View File
@@ -0,0 +1,329 @@
import { useState, type FormEvent } from "react";
import { useMutation, useQueryClient, useSuspenseQuery } from "@tanstack/react-query";
import InlineError from "@/lib/InlineError";
import { settingsPutMutation, settingsQuery } from "@/lib/queries";
import { buildSettingsPatch } from "@/lib/settingsDiff";
import type { Settings, SettingsPatch } from "@/lib/types";
import { raiseRestartBanner } from "./restartBanner";
/** True when the patch touches anything besides the write-only `web.password` (ruling 11). */
export function patchRequiresRestart(patch: SettingsPatch): boolean {
return Object.entries(patch).some(([section, fields]) =>
Object.keys(fields as Record<string, unknown>).some((key) => !(section === "web" && key === "password")),
);
}
interface FieldDef {
key: string;
kind: "number" | "text" | "boolean" | readonly string[];
}
interface SectionDef {
section: keyof Settings;
title: string;
fields: readonly FieldDef[];
}
const TLS_FIELDS: readonly FieldDef[] = [
{ key: "enabled", kind: "boolean" },
{ key: "bind", kind: "text" },
{ key: "port", kind: "number" },
{ key: "cert_path", kind: "text" },
{ key: "key_path", kind: "text" },
];
const SECTIONS: readonly SectionDef[] = [
{ section: "runtime", title: "Runtime", fields: [{ key: "io_backend", kind: ["threaded", "evented"] }] },
{
section: "upstream",
title: "Upstream",
fields: [
{ key: "connect_timeout_ms", kind: "number" },
{ key: "read_timeout_ms", kind: "number" },
{ key: "total_timeout_ms", kind: "number" },
],
},
{
section: "dns",
title: "DNS",
fields: [
{ key: "bind_ipv4", kind: "text" },
{ key: "bind_ipv6", kind: "text" },
{ key: "port", kind: "number" },
{ key: "rate_limit", kind: "number" },
{ key: "rate_window_seconds", kind: "number" },
],
},
{
section: "blocking",
title: "Blocking",
fields: [
{ key: "response", kind: ["zero", "nxdomain"] },
{ key: "ttl", kind: "number" },
],
},
{
section: "cache",
title: "Cache",
fields: [
{ key: "size", kind: "number" },
{ key: "negative_ttl_max", kind: "number" },
],
},
{
section: "web",
title: "Web",
fields: [
{ key: "enabled", kind: "boolean" },
{ key: "bind", kind: "text" },
{ key: "port", kind: "number" },
{ key: "session_ttl_hours", kind: "number" },
{ key: "api_rate_limit_per_min", kind: "number" },
{ key: "api_localhost_exempt", kind: "boolean" },
{ key: "sse_max_connections_per_ip", kind: "number" },
],
},
{ section: "doh_server", title: "DoH Server", fields: TLS_FIELDS },
{ section: "dot_server", title: "DoT Server", fields: TLS_FIELDS },
{ section: "edns", title: "EDNS", fields: [{ key: "ecs_mode", kind: ["strip", "forward"] }] },
{
section: "logging",
title: "Logging",
fields: [
{ key: "level", kind: ["error", "warn", "info", "debug"] },
{ key: "retention_days", kind: "number" },
{ key: "query_log_buffer_max", kind: "number" },
{ key: "hide_domains", kind: "boolean" },
{ key: "hide_client_ips", kind: "boolean" },
{ key: "output", kind: ["stderr", "syslog", "file"] },
{ key: "file_path", kind: "text" },
{ key: "max_size_mb", kind: "number" },
{ key: "max_files", kind: "number" },
],
},
{
section: "disk",
title: "Disk",
fields: [
{ key: "min_free_mb", kind: "number" },
{ key: "warn_free_mb", kind: "number" },
],
},
{
section: "blocklist_update",
title: "Blocklist Update",
fields: [
{ key: "enabled", kind: "boolean" },
{ key: "interval_hours", kind: "number" },
],
},
];
const LABEL_CLASS = "text-sm text-zinc-700 dark:text-zinc-300";
const INPUT_CLASS =
"rounded border border-zinc-300 bg-white px-2 py-1 text-sm focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-600 dark:border-zinc-700 dark:bg-zinc-900";
function FieldRow({
section,
def,
value,
onChange,
}: {
section: string;
def: FieldDef;
value: unknown;
onChange: (value: unknown) => void;
}) {
const id = `${section}.${def.key}`;
if (def.kind === "boolean") {
return (
<div className="flex items-center gap-2">
<input
id={id}
type="checkbox"
checked={value as boolean}
onChange={(e) => onChange(e.target.checked)}
className="focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-600"
/>
<label htmlFor={id} className={LABEL_CLASS}>
{def.key}
</label>
</div>
);
}
if (Array.isArray(def.kind)) {
return (
<div className="flex flex-col gap-1">
<label htmlFor={id} className={LABEL_CLASS}>
{def.key}
</label>
<select
id={id}
value={value as string}
onChange={(e) => onChange(e.target.value)}
className={INPUT_CLASS}
>
{def.kind.map((option) => (
<option key={option} value={option}>
{option}
</option>
))}
</select>
</div>
);
}
if (def.kind === "number") {
const numeric = value as number;
return (
<div className="flex flex-col gap-1">
<label htmlFor={id} className={LABEL_CLASS}>
{def.key}
</label>
<input
id={id}
type="number"
value={Number.isNaN(numeric) ? "" : numeric}
onChange={(e) => onChange(e.target.valueAsNumber)}
className={INPUT_CLASS}
/>
</div>
);
}
return (
<div className="flex flex-col gap-1">
<label htmlFor={id} className={LABEL_CLASS}>
{def.key}
</label>
<input
id={id}
type="text"
value={value as string}
onChange={(e) => onChange(e.target.value)}
className={INPUT_CLASS}
/>
</div>
);
}
export default function SettingsPage() {
const { data } = useSuspenseQuery(settingsQuery());
const queryClient = useQueryClient();
const mutation = useMutation(settingsPutMutation(queryClient));
const [edited, setEdited] = useState<Settings>(() => structuredClone(data.settings));
const [password, setPassword] = useState("");
const [confirm, setConfirm] = useState("");
const passwordsMismatch = (password !== "" || confirm !== "") && password !== confirm;
const hasInvalidNumber = SECTIONS.some(({ section, fields }) =>
fields.some(
(field) => field.kind === "number" && Number.isNaN((edited[section] as Record<string, unknown>)[field.key]),
),
);
const patch = buildSettingsPatch(data.settings, edited, password === "" ? undefined : password);
const saveDisabled = patch === null || passwordsMismatch || hasInvalidNumber || mutation.isPending;
function setField(section: keyof Settings, key: string, value: unknown): void {
setEdited((prev) => ({
...prev,
[section]: { ...(prev[section] as Record<string, unknown>), [key]: value },
}));
}
function handleSubmit(event: FormEvent): void {
event.preventDefault();
if (patch === null || passwordsMismatch || hasInvalidNumber) return;
const restartNeeded = patchRequiresRestart(patch);
mutation.mutate(patch, {
onSuccess: (envelope) => {
setEdited(structuredClone(envelope.settings));
setPassword("");
setConfirm("");
if (restartNeeded) raiseRestartBanner();
},
});
}
return (
<section>
<h1 className="text-2xl font-semibold">Settings</h1>
<p className="mt-1 text-sm text-zinc-500">
Changes are validated as a whole; every setting requires a restart to take effect.
</p>
<form onSubmit={handleSubmit} className="mt-4 max-w-3xl">
<fieldset disabled={mutation.isPending} className="space-y-6">
{SECTIONS.map(({ section, title, fields }) => (
<fieldset key={section} className="rounded border border-zinc-200 p-4 dark:border-zinc-800">
<legend className="px-1 text-sm font-semibold">{title}</legend>
<div className="grid gap-3 sm:grid-cols-2">
{fields.map((def) => (
<FieldRow
key={def.key}
section={section}
def={def}
value={(edited[section] as Record<string, unknown>)[def.key]}
onChange={(value) => setField(section, def.key, value)}
/>
))}
{section === "web" && (
<>
<p className={LABEL_CLASS}>
auth_enabled: {data.settings.web.auth_enabled ? "true" : "false"}{" "}
<span className="text-zinc-500">(derived, read-only)</span>
</p>
<div className="flex flex-col gap-1">
<label htmlFor="web.password" className={LABEL_CLASS}>
password
</label>
<input
id="web.password"
type="password"
autoComplete="new-password"
value={password}
onChange={(e) => setPassword(e.target.value)}
className={INPUT_CLASS}
/>
</div>
<div className="flex flex-col gap-1">
<label htmlFor="web.password_confirm" className={LABEL_CLASS}>
confirm password
</label>
<input
id="web.password_confirm"
type="password"
autoComplete="new-password"
value={confirm}
onChange={(e) => setConfirm(e.target.value)}
className={INPUT_CLASS}
/>
</div>
{password !== "" && (
<p className="text-sm text-amber-700 sm:col-span-2 dark:text-amber-400">
Changing the password signs out every session; you will be asked to log
in again.
</p>
)}
{passwordsMismatch && (
<p className="text-sm text-red-700 sm:col-span-2 dark:text-red-400">
Passwords do not match.
</p>
)}
</>
)}
</div>
</fieldset>
))}
<div className="flex items-center gap-3">
<button
type="submit"
disabled={saveDisabled}
className="rounded bg-blue-600 px-4 py-1.5 text-sm font-medium text-white focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-600 disabled:bg-zinc-300 disabled:text-zinc-500 dark:disabled:bg-zinc-800"
>
{mutation.isPending ? "Saving…" : "Save"}
</button>
{mutation.isError && <InlineError error={mutation.error} />}
</div>
</fieldset>
</form>
</section>
);
}
@@ -0,0 +1,27 @@
import { useSyncExternalStore } from "react";
let raised = false;
const listeners = new Set<() => void>();
function subscribe(listener: () => void): () => void {
listeners.add(listener);
return () => listeners.delete(listener);
}
function getSnapshot(): boolean {
return raised;
}
export function raiseRestartBanner(): void {
raised = true;
for (const listener of listeners) listener();
}
export function dismissRestartBanner(): void {
raised = false;
for (const listener of listeners) listener();
}
export function useRestartBanner(): boolean {
return useSyncExternalStore(subscribe, getSnapshot);
}