mokhtar/nxdns
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

milestone 11: systemd and docker packaging, operator and architecture docs, config and api reference, docs drift guards

Browse Source
This commit is contained in:
mokhtar
2026-08-02 15:24:10 +02:00
parent a589df7515
commit bdb6ffab7a
29 changed files with 1936 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/config/model.zig
+2 -37
View File
@@ -18,7 +18,6 @@ const std = @import("std");
const Allocator = std.mem.Allocator;
pub const Config = struct {
runtime: Runtime = .{},
upstream: Upstream = .{},
dns: Dns = .{},
blocking: Blocking = .{},
@@ -42,28 +41,7 @@ pub const Config = struct {
forward_zones: []const ForwardZone = &.{},
};
pub const IoBackend = enum {
threaded,
evented,
pub fn toDb(self: IoBackend) []const u8 {
return switch (self) {
.threaded => "threaded",
.evented => "evented",
};
}
pub fn fromDb(text: []const u8) ?IoBackend {
if (std.mem.eql(u8, text, "threaded")) return .threaded;
if (std.mem.eql(u8, text, "evented")) return .evented;
return null;
}
};
pub const Runtime = struct { io_backend: IoBackend = .threaded };
pub const Upstream = struct {
connect_timeout_ms: u32 = 2000,
read_timeout_ms: u32 = 3000,
total_timeout_ms: u32 = 5000,
};
@@ -318,10 +296,6 @@ comptime {
assertFits(u32, 1024 * 1024, u64); // MiB conversions
}
pub fn connectTimeout(u: Upstream) std.Io.Duration {
return .{ .nanoseconds = @as(i96, u.connect_timeout_ms) * std.time.ns_per_ms };
}
pub fn readTimeout(u: Upstream) std.Io.Duration {
return .{ .nanoseconds = @as(i96, u.read_timeout_ms) * std.time.ns_per_ms };
}
@@ -506,8 +480,6 @@ const expected_keys = [_][]const u8{
"logging.output",
"logging.query_log_buffer_max",
"logging.retention_days",
"runtime.io_backend",
"upstream.connect_timeout_ms",
"upstream.read_timeout_ms",
"upstream.total_timeout_ms",
"web.api_localhost_exempt",
@@ -558,8 +530,7 @@ test "toSettings never emits web.password" {
test "toSettings and fromSettings round-trip a non-default config" {
const gpa = testing.allocator;
const original: Config = .{
.runtime = .{ .io_backend = .evented },
.upstream = .{ .connect_timeout_ms = 111, .read_timeout_ms = 222, .total_timeout_ms = 333 },
.upstream = .{ .read_timeout_ms = 222, .total_timeout_ms = 333 },
.dns = .{
.bind_ipv4 = "127.0.0.1",
.bind_ipv6 = "::1",
@@ -697,7 +668,6 @@ fn expectEnumRoundTrip(comptime E: type) !void {
}
test "every toDb and fromDb enum pair round-trips over all tags" {
try expectEnumRoundTrip(IoBackend);
try expectEnumRoundTrip(BlockResponse);
try expectEnumRoundTrip(EcsMode);
try expectEnumRoundTrip(LogLevel);
@@ -715,10 +685,6 @@ test "RecordType stores the uppercase DDL spelling" {
}
test "unit conversions" {
try testing.expectEqual(
@as(i96, 2000) * std.time.ns_per_ms,
connectTimeout(.{}).nanoseconds,
);
try testing.expectEqual(
@as(i96, 3000) * std.time.ns_per_ms,
readTimeout(.{}).nanoseconds,
@@ -737,13 +703,12 @@ test "unit conversions" {
test "unit conversions at the field maximum do not overflow" {
const max_upstream: Upstream = .{
.connect_timeout_ms = std.math.maxInt(u32),
.read_timeout_ms = std.math.maxInt(u32),
.total_timeout_ms = std.math.maxInt(u32),
};
try testing.expectEqual(
@as(i96, std.math.maxInt(u32)) * std.time.ns_per_ms,
connectTimeout(max_upstream).nanoseconds,
readTimeout(max_upstream).nanoseconds,
);
try testing.expectEqual(
@as(i64, std.math.maxInt(u16)) * 3600,
src/config/validate.zig
+31 -14
View File
@@ -199,21 +199,20 @@ const max_rate_window_seconds = 3_600;
fn checkScalars(cfg: Config, diags: *Diagnostics) error{OutOfMemory}!void {
const up = cfg.upstream;
try checkTimeout(diags, up.connect_timeout_ms, "upstream.connect_timeout_ms");
try checkTimeout(diags, up.read_timeout_ms, "upstream.read_timeout_ms");
try checkTimeout(diags, up.total_timeout_ms, "upstream.total_timeout_ms");
if (up.total_timeout_ms < up.connect_timeout_ms or up.total_timeout_ms < up.read_timeout_ms) {
if (up.total_timeout_ms < up.read_timeout_ms) {
try diags.add(
error.BadTimeout,
"upstream.total_timeout_ms",
.{},
"total budget {d}ms is below connect {d}ms or read {d}ms",
.{ up.total_timeout_ms, up.connect_timeout_ms, up.read_timeout_ms },
"total budget {d}ms is below read {d}ms",
.{ up.total_timeout_ms, up.read_timeout_ms },
);
}
try checkBind(diags, cfg.dns.bind_ipv4, "dns.bind_ipv4", true);
try checkBind(diags, cfg.dns.bind_ipv6, "dns.bind_ipv6", false);
try checkBind(diags, cfg.dns.bind_ipv4, "dns.bind_ipv4", .ip4);
try checkBind(diags, cfg.dns.bind_ipv6, "dns.bind_ipv6", .ip6);
try checkPort(diags, cfg.dns.port, "dns.port");
if (cfg.dns.rate_limit < 1) {
try diags.add(error.BadRateLimit, "dns.rate_limit", .{}, "must be at least 1", .{});
@@ -248,7 +247,7 @@ fn checkScalars(cfg: Config, diags: *Diagnostics) error{OutOfMemory}!void {
);
}
try checkBind(diags, cfg.web.bind, "web.bind", false);
try checkBind(diags, cfg.web.bind, "web.bind", .any);
try checkPort(diags, cfg.web.port, "web.port");
if (cfg.web.password.len != 0 and cfg.web.password_hash.len != 0) {
try diags.add(
@@ -339,18 +338,30 @@ fn checkTimeout(diags: *Diagnostics, value: u32, comptime path: []const u8) erro
}
}
const BindFamily = enum { ip4, ip6, any };
/// `dns.bind_ipv4` and `dns.bind_ipv6` each name one socket of the dual-stack
/// pair, so each must be a literal of its own family: an IPv4 wildcard in
/// `bind_ipv6` would bind IPv4 as the "v6" socket and make the real IPv4 bind
/// fail with AddressInUse — the IPv6 service silently disappears.
fn checkBind(
diags: *Diagnostics,
text: []const u8,
comptime path: []const u8,
comptime require_ip4: bool,
comptime family: BindFamily,
) error{OutOfMemory}!void {
const addr = NetAddress.parse(text) catch {
try diags.add(error.BadBindAddress, path, .{}, "'{s}' is not an IP address", .{text});
return;
};
if (require_ip4 and std.meta.activeTag(addr) != NetAddress.ip4) {
try diags.add(error.BadBindAddress, path, .{}, "'{s}' is not an IPv4 address", .{text});
switch (family) {
.ip4 => if (std.meta.activeTag(addr) != NetAddress.ip4) {
try diags.add(error.BadBindAddress, path, .{}, "'{s}' is not an IPv4 address", .{text});
},
.ip6 => if (std.meta.activeTag(addr) != NetAddress.ip6) {
try diags.add(error.BadBindAddress, path, .{}, "'{s}' is not an IPv6 address", .{text});
},
.any => {},
}
}
@@ -359,7 +370,7 @@ fn checkTlsEndpoint(
endpoint: model.TlsEndpoint,
comptime section: []const u8,
) error{OutOfMemory}!void {
try checkBind(diags, endpoint.bind, section ++ ".bind", false);
try checkBind(diags, endpoint.bind, section ++ ".bind", .any);
try checkPort(diags, endpoint.port, section ++ ".port");
if (!endpoint.enabled) return;
// Readability of the files is `nxdns check`'s job, not the pure validator's.
@@ -1162,11 +1173,11 @@ test "error.BadPort" {
test "error.BadTimeout" {
var cfg = baseConfig();
cfg.upstream.connect_timeout_ms = 10;
try expectProblem(cfg, error.BadTimeout, "upstream.connect_timeout_ms");
cfg.upstream.read_timeout_ms = 10;
try expectProblem(cfg, error.BadTimeout, "upstream.read_timeout_ms");
var budget = baseConfig();
budget.upstream = .{ .connect_timeout_ms = 4000, .read_timeout_ms = 4000, .total_timeout_ms = 1000 };
budget.upstream = .{ .read_timeout_ms = 4000, .total_timeout_ms = 1000 };
try expectProblem(budget, error.BadTimeout, "upstream.total_timeout_ms");
}
@@ -1214,6 +1225,12 @@ test "error.BadBindAddress" {
try expectProblem(web, error.BadBindAddress, "web.bind");
}
test "error.BadBindAddress on an IPv4 literal in dns.bind_ipv6" {
var cfg = baseConfig();
cfg.dns.bind_ipv6 = "0.0.0.0";
try expectProblem(cfg, error.BadBindAddress, "dns.bind_ipv6");
}
test "error.MissingCertPath" {
var cfg = baseConfig();
cfg.doh_server = .{ .enabled = true, .cert_path = "" };