nxdns/admin/src/features/configuration/settingsSections.ts

import type { Settings } from "@/lib/types";

/**
 * The settings registry. One list drives both renderings: the editable form
 * builds a control per field, the file-mode page builds a definition per
 * field, and neither can drift from the other or from `Settings`.
 */

export interface FieldDef<S extends keyof Settings> {
	key: keyof Settings[S] & string;
	kind: "number" | "text" | "boolean" | readonly string[];
}

export interface SectionDef<S extends keyof Settings> {
	section: S;
	title: string;
	/** The card head's one line: what the section governs, in the reader's words. */
	description: string;
	fields: readonly FieldDef<S>[];
}

/** Binds each section's field keys to that section's Settings type at definition. */
function defineSection<S extends keyof Settings>(def: SectionDef<S>): SectionDef<S> {
	return def;
}

/** The registry read back as a heterogeneous list, once the per-section binding has been proven. */
export type AnyFieldDef = { [S in keyof Settings]: FieldDef<S> }[keyof Settings];
export type AnySectionDef = { [S in keyof Settings]: SectionDef<S> }[keyof Settings];

/**
 * A section's values as a string-keyed view. The keys are proven against
 * `Settings[S]` where each section is defined; iterating the heterogeneous
 * registry loses that correlation, so consumption widens here in one place.
 */
export function sectionValues(settings: Settings, section: keyof Settings): Record<string, unknown> {
	return settings[section] as Record<string, unknown>;
}

const TLS_FIELDS: readonly FieldDef<"doh_server" | "dot_server">[] = [
	{ key: "enabled", kind: "boolean" },
	{ key: "bind", kind: "text" },
	{ key: "port", kind: "number" },
	{ key: "cert_path", kind: "text" },
	{ key: "key_path", kind: "text" },
];

export const SECTIONS: readonly AnySectionDef[] = [
	defineSection({
		section: "upstream",
		title: "Upstream",
		description:
			"How long nxdns waits on the upstream pool, per attempt and in total, and on a forward zone's resolver per read.",
		fields: [
			{ key: "attempt_timeout_ms", kind: "number" },
			{ key: "read_timeout_ms", kind: "number" },
			{ key: "total_timeout_ms", kind: "number" },
		],
	}),
	defineSection({
		section: "dns",
		title: "DNS",
		description:
			"The addresses and port the resolver listens on, and how many queries one client may send within the rate window.",
		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" },
		],
	}),
	defineSection({
		section: "blocking",
		title: "Blocking",
		description: "What a blocked query is answered with, and for how long clients may keep that answer.",
		fields: [
			{ key: "response", kind: ["zero", "nxdomain"] },
			{ key: "ttl", kind: "number" },
		],
	}),
	defineSection({
		section: "cache",
		title: "Cache",
		description: "How many answers are kept, and how long a negative answer stays valid.",
		fields: [
			{ key: "size", kind: "number" },
			{ key: "negative_ttl_max", kind: "number" },
		],
	}),
	defineSection({
		section: "web",
		title: "Web",
		description: "Where this admin interface listens, how long a login lasts, and its request limits.",
		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" },
			{ key: "trusted_proxies", kind: "text" },
		],
	}),
	defineSection({
		section: "doh_server",
		title: "DoH Server",
		description: "DNS over HTTPS for clients that speak it: the listener and its certificate.",
		fields: TLS_FIELDS,
	}),
	defineSection({
		section: "dot_server",
		title: "DoT Server",
		description: "DNS over TLS for clients that speak it: the listener and its certificate.",
		fields: TLS_FIELDS,
	}),
	defineSection({
		section: "edns",
		title: "EDNS",
		description: "Whether the client's subnet is passed on to upstreams or stripped from the query.",
		fields: [{ key: "ecs_mode", kind: ["strip", "forward"] }],
	}),
	defineSection({
		section: "logging",
		title: "Logging",
		description:
			"What the process log records and where it goes; how query history is buffered, flushed and kept, and which of its fields are hidden.",
		fields: [
			{ key: "level", kind: ["error", "warn", "info", "debug"] },
			{ key: "retention_days", kind: "number" },
			{ key: "query_log_buffer_max", kind: "number" },
			{ key: "query_log_flush_interval_s", 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" },
		],
	}),
	defineSection({
		section: "disk",
		title: "Disk",
		description: "The free space below which nxdns warns, and below which it stops writing history.",
		fields: [
			{ key: "min_free_mb", kind: "number" },
			{ key: "warn_free_mb", kind: "number" },
		],
	}),
	defineSection({
		section: "blocklist_update",
		title: "Blocklist Update",
		description: "Whether the blocklists are fetched again on their own, and how often.",
		fields: [
			{ key: "enabled", kind: "boolean" },
			{ key: "interval_hours", kind: "number" },
		],
	}),
];