fancy-dns/internal/app/contract_test.go

package app

import (
	"encoding/json"
	"net/http"
	"sort"
	"strconv"
	"strings"
	"testing"
)

// The contract tests in this file exist because the console's TypeScript types
// are hand-written and `apiFetch` ends in `JSON.parse(text) as T`, so nothing
// in the toolchain compared them with the Go structs. A field that lost its
// json tag, or a response a struct never had, showed up as an empty table in a
// browser and nowhere else: the Go suite was green and the console was wrong.
//
// Each assertion is the EXACT top-level key set of one endpoint, driven
// through the real router with the real hook implementations (harness_test.go
// wires a whole App). Renaming a field on either side now fails here with a
// readable diff instead of in a browser.
//
// The sets below are the Go side's truth. Where the console disagrees, the
// console is what has to move: these are the endpoints a deployed binary
// answers, and a contract that follows the UI would drag the API backwards
// every time the UI got nicer. TestConsoleWritePayloadsAreAccepted pins the
// other direction, because there the console is the client and its payload is
// fixed.

// keysOf returns the sorted top-level keys of a JSON object body.
func keysOf(t *testing.T, body []byte) []string {
	t.Helper()
	var m map[string]json.RawMessage
	if err := json.Unmarshal(body, &m); err != nil {
		t.Fatalf("body is not a JSON object: %v\n%s", err, body)
	}
	out := make([]string, 0, len(m))
	for k := range m {
		out = append(out, k)
	}
	sort.Strings(out)
	return out
}

// keysOfField returns the sorted keys of a nested object addressed by path,
// where a numeric path element indexes an array.
func keysOfField(t *testing.T, body []byte, path ...string) []string {
	t.Helper()
	var cur any
	if err := json.Unmarshal(body, &cur); err != nil {
		t.Fatalf("body is not JSON: %v\n%s", err, body)
	}
	for i, p := range path {
		switch node := cur.(type) {
		case map[string]any:
			next, ok := node[p]
			if !ok {
				t.Fatalf("%s: no such key %q at depth %d\n%s", strings.Join(path, "."), p, i, body)
			}
			cur = next
		case []any:
			idx, err := strconv.Atoi(p)
			if err != nil || idx >= len(node) {
				t.Fatalf("%s: %q is not a valid index (len %d)", strings.Join(path, "."), p, len(node))
			}
			cur = node[idx]
		default:
			t.Fatalf("%s: %q is not addressable at depth %d", strings.Join(path, "."), p, i)
		}
	}
	obj, ok := cur.(map[string]any)
	if !ok {
		t.Fatalf("%s: is not an object", strings.Join(path, "."))
	}
	out := make([]string, 0, len(obj))
	for k := range obj {
		out = append(out, k)
	}
	sort.Strings(out)
	return out
}

func wantKeys(want ...string) []string {
	out := append([]string(nil), want...)
	sort.Strings(out)
	return out
}

func requireKeys(t *testing.T, what string, got, want []string) {
	t.Helper()
	if strings.Join(got, ",") == strings.Join(want, ",") {
		return
	}
	t.Errorf("%s JSON keys drifted.\n got: %s\nwant: %s", what,
		strings.Join(got, ", "), strings.Join(want, ", "))
	t.Log("A key the console does not read is harmless but means the Go side grew " +
		"a field nobody agreed on: put it in web/src/lib/types.ts or take it off " +
		"the wire. A key the console reads and this test does not list is a field " +
		"that works today and will break the console the moment the struct changes.")
}

// TestAdminEndpointKeySets is the table: one entry per admin read endpoint the
// console calls, with its exact key set.
func TestAdminEndpointKeySets(t *testing.T) {
	h := newHarness(t, nil)
	// One query, so the log and the cache-top tables have a row to shape.
	// Asserting a key set against an empty list proves only the envelope.
	h.query("hot.test.", 1)
	h.query("hot.test.", 1)

	t.Run("status", func(t *testing.T) {
		code, body := h.get("/api/status")
		if code != http.StatusOK {
			t.Fatalf("GET /api/status = %d: %s", code, body)
		}
		requireKeys(t, "GET /api/status", keysOf(t, body),
			wantKeys("components", "config", "started", "uptime_s", "version"))
	})

	t.Run("dashboard", func(t *testing.T) {
		code, body := h.get("/api/dashboard?range=1h")
		if code != http.StatusOK {
			t.Fatalf("GET /api/dashboard = %d: %s", code, body)
		}
		requireKeys(t, "GET /api/dashboard", keysOf(t, body), wantKeys(
			"blocked_pct", "blocked_total", "blocklist_rules", "cache_entries",
			"cache_hit_rate", "config_version", "degraded_reason", "errors_total",
			"generation", "health", "inflight", "listeners", "node_id",
			"queries_per_sec", "queries_total", "recent", "series", "top_blocked",
			"top_queried", "transports", "upstreams", "uptime_seconds", "version",
		))
		requireKeys(t, "GET /api/dashboard recent[0]", keysOfField(t, body, "recent", "0"), wantKeys(
			"action", "blocked", "client", "client_group", "duration_ms", "id",
			"list", "name", "protocol", "qtype", "qtype_name", "rcode", "rcode_name",
			"response", "ts", "upstream",
		))
	})

	t.Run("blocklists", func(t *testing.T) {
		code, body := h.get("/api/blocklists")
		if code != http.StatusOK {
			t.Fatalf("GET /api/blocklists = %d: %s", code, body)
		}
		requireKeys(t, "GET /api/blocklists", keysOf(t, body),
			wantKeys("digest", "errors", "items", "stats"))
		// items[0] is where drift item 1 bit: blocklist.Source had no json
		// tags at all, so the Sources table rendered blank rows and its
		// per-row toggle posted `name: undefined`.
		requireKeys(t, "GET /api/blocklists items[0]", keysOfField(t, body, "items", "0"),
			wantKeys("digest", "format", "meta", "name", "stats"))
		requireKeys(t, "GET /api/blocklists items[0].meta", keysOfField(t, body, "items", "0", "meta"),
			wantKeys("bytes", "duration", "enabled", "err", "etag", "format",
				"http_status", "last_mod", "name", "path", "rules", "stale",
				"updated_at", "url"))
	})

	// The rules the console's table reads all come from /api/domains, which
	// serves both block and allow rules.
	t.Run("domains", func(t *testing.T) {
		code, body := h.get("/api/domains?per_page=5")
		if code != http.StatusOK {
			t.Fatalf("GET /api/domains = %d: %s", code, body)
		}
		requireKeys(t, "GET /api/domains", keysOf(t, body),
			wantKeys("items", "page", "per_page", "total", "truncated"))
		requireKeys(t, "GET /api/domains items[0]", keysOfField(t, body, "items", "0"),
			wantKeys("action", "categories", "hits", "name", "rule", "source"))
	})

	t.Run("clients", func(t *testing.T) {
		code, body := h.get("/api/clients")
		if code != http.StatusOK {
			t.Fatalf("GET /api/clients = %d: %s", code, body)
		}
		requireKeys(t, "GET /api/clients", keysOf(t, body),
			wantKeys("default_policy", "default_rate_limit", "groups"))
		// Drift item 2: the summary was flat where the console reads `match`,
		// so every group card read "matches nothing" and the editor sent a
		// shape the server refused. `comment` stays omitempty: a group without
		// one must not carry a key the console would have to special-case.
		requireKeys(t, "GET /api/clients groups[0]", keysOfField(t, body, "groups", "0"),
			wantKeys("allow_domains", "blocked_count", "client_count",
				"deny_domains", "log_queries", "match", "max_concurrent", "matched",
				"name", "policy", "query_count", "rate_limit", "skip_blocklist",
				"skip_cache", "upstreams"))
		requireKeys(t, "GET /api/clients groups[0].match", keysOfField(t, body, "groups", "0", "match"),
			wantKeys("any", "cidrs", "ptr_suffixes", "tags"))
	})

	t.Run("upstreams", func(t *testing.T) {
		code, body := h.get("/api/upstreams")
		if code != http.StatusOK {
			t.Fatalf("GET /api/upstreams = %d: %s", code, body)
		}
		requireKeys(t, "GET /api/upstreams", keysOf(t, body), wantKeys(
			"bootstraps", "breaker_cooldown", "breaker_threshold",
			"healthcheck_interval", "max_attempts", "policy", "servers",
		))
		requireKeys(t, "GET /api/upstreams servers[0]", keysOfField(t, body, "servers", "0"),
			wantKeys("addr", "avg_ms", "breaker_open", "fail_rate", "failures",
				"health", "latency_ms", "p95_ms", "proto", "queries", "server_name",
				"weight"))
	})

	t.Run("logs", func(t *testing.T) {
		code, body := h.get("/api/logs?limit=10")
		if code != http.StatusOK {
			t.Fatalf("GET /api/logs = %d: %s", code, body)
		}
		requireKeys(t, "GET /api/logs", keysOf(t, body),
			wantKeys("has_more", "items", "limit", "offset", "total"))
		// Every key on every row. These were omitempty, so a row without an
		// ACL group or a blocklist arrived without the key and the console
		// rendered "undefined" instead of an empty cell.
		requireKeys(t, "GET /api/logs items[0]", keysOfField(t, body, "items", "0"), wantKeys(
			"action", "blocked", "client", "client_group", "duration_ms", "id",
			"list", "name", "protocol", "qtype", "qtype_name", "rcode", "rcode_name",
			"response", "ts", "upstream",
		))
	})

	t.Run("cache", func(t *testing.T) {
		code, body := h.get("/api/cache")
		if code != http.StatusOK {
			t.Fatalf("GET /api/cache = %d: %s", code, body)
		}
		requireKeys(t, "GET /api/cache", keysOf(t, body), wantKeys(
			"bytes", "bytes_human", "enabled", "entries", "evictions", "hit_rate",
			"hits", "max_ttl_ms", "min_ttl_ms", "misses", "negative_ttl_ms",
			"persisted", "serve_stale_ms", "shards", "size", "stale_hits",
		))
		requireKeys(t, "GET /api/cache persisted", keysOfField(t, body, "persisted"), wantKeys(
			"bytes", "enabled", "entries", "errors", "last_snapshot", "loaded",
			"path", "writes",
		))
	})

	t.Run("cache top", func(t *testing.T) {
		code, body := h.get("/api/cache/top?limit=5")
		if code != http.StatusOK {
			t.Fatalf("GET /api/cache/top = %d: %s", code, body)
		}
		requireKeys(t, "GET /api/cache/top", keysOf(t, body), wantKeys("items"))
		// There is no `count` and no `last_seen`: the cache tracks a hit
		// counter and a byte count per name, and the console's "Lookups" and
		// "Last seen" columns were reading fields that never existed.
		requireKeys(t, "GET /api/cache/top items[0]", keysOfField(t, body, "items", "0"),
			wantKeys("bytes", "hits", "name", "qtype", "qtype_name"))
	})

	t.Run("settings", func(t *testing.T) {
		code, body := h.get("/api/settings")
		if code != http.StatusOK {
			t.Fatalf("GET /api/settings = %d: %s", code, body)
		}
		requireKeys(t, "GET /api/settings", keysOf(t, body), wantKeys(
			"config_yaml", "defaults_yaml", "effective_yaml", "last_error",
			"path", "reload_available", "version", "writable",
		))
	})

	t.Run("whoami", func(t *testing.T) {
		code, body := h.get("/api/whoami")
		if code != http.StatusOK {
			t.Fatalf("GET /api/whoami = %d: %s", code, body)
		}
		requireKeys(t, "GET /api/whoami", keysOf(t, body),
			wantKeys("auth_mode", "base_path", "can_write", "mode", "name", "read_only"))
	})
}

// TestWriteEndpointKeySets pins the small write responses.
func TestWriteEndpointKeySets(t *testing.T) {
	h := newHarness(t, nil)

	t.Run("blocklist refresh", func(t *testing.T) {
		code, body := h.do(http.MethodPost, "/api/blocklists/refresh", `{"names":[]}`)
		if code != http.StatusOK {
			t.Fatalf("POST /api/blocklists/refresh = %d: %s", code, body)
		}
		requireKeys(t, "POST /api/blocklists/refresh", keysOf(t, body), wantKeys("names", "started"))
		// The toast used to say "0 sources queued": names is a slice, and a
		// nil slice marshals to null, which the console counted as zero.
		var got struct {
			Names []string `json:"names"`
		}
		if err := json.Unmarshal(body, &got); err != nil {
			t.Fatal(err)
		}
		if got.Names == nil {
			t.Errorf("names is null, so the console's source count is a lie: %s", body)
		}
	})

	t.Run("cache flush", func(t *testing.T) {
		code, body := h.do(http.MethodPost, "/api/cache/flush", "")
		if code != http.StatusOK {
			t.Fatalf("POST /api/cache/flush = %d: %s", code, body)
		}
		requireKeys(t, "POST /api/cache/flush", keysOf(t, body), wantKeys("entries", "ok"))
	})

	t.Run("acl save", func(t *testing.T) {
		code, body := h.do(http.MethodPut, "/api/clients", `{"groups":[],"default_policy":"allow"}`)
		if code != http.StatusOK {
			t.Fatalf("PUT /api/clients = %d: %s", code, body)
		}
		requireKeys(t, "PUT /api/clients", keysOf(t, body), wantKeys("ok", "version"))
	})

	t.Run("upstream save", func(t *testing.T) {
		code, body := h.do(http.MethodPut, "/api/upstreams",
			`{"policy":"parallel","servers":[{"addr":"127.0.0.1:5300","proto":"udp","weight":1}],`+
				`"bootstraps":[],"max_attempts":1,"breaker_threshold":5,"healthcheck_interval":"30s"}`)
		if code != http.StatusOK {
			t.Fatalf("PUT /api/upstreams = %d: %s", code, body)
		}
		requireKeys(t, "PUT /api/upstreams", keysOf(t, body), wantKeys("ok", "version"))
	})
}

// TestConsoleWritePayloadsAreAccepted drives the two write endpoints with the
// exact payload web/src builds. Both answered 400 with `json: unknown field
// ...`, and no hand-written Go test found it: the suite never sent what the
// console actually sends.
func TestConsoleWritePayloadsAreAccepted(t *testing.T) {
	h := newHarness(t, nil)

	t.Run("clients", func(t *testing.T) {
		// web/src/pages/Clients.tsx toGroup(): match is nested, and the
		// console sends the ClientGroup shape without the server-owned
		// counters (client_count, query_count, blocked_count, matched).
		const body = `{"groups":[{
			"name":"console",
			"comment":"from the console",
			"policy":"allow",
			"match":{"cidrs":["10.0.0.0/8"],"ptr_suffixes":["lan.example."],"tags":["laptop"],"any":false},
			"allow_domains":["*.example.net"],
			"deny_domains":["*.ads.example.net"],
			"skip_blocklist":false,
			"skip_cache":false,
			"rate_limit":10,
			"max_concurrent":0,
			"log_queries":true,
			"upstreams":[]
		}],"default_policy":"allow"}`
		code, res := h.do(http.MethodPut, "/api/clients", body)
		if code != http.StatusOK {
			t.Fatalf("PUT /api/clients with the console payload = %d: %s", code, res)
		}
		// And it must round-trip: what the console sent comes back in the
		// shape it sent, or the editor empties itself on refetch.
		_, list := h.get("/api/clients")
		var got struct {
			Groups []struct {
				Name  string `json:"name"`
				Match struct {
					CIDRs []string `json:"cidrs"`
					Tags  []string `json:"tags"`
				} `json:"match"`
			} `json:"groups"`
		}
		if err := json.Unmarshal(list, &got); err != nil {
			t.Fatal(err)
		}
		if len(got.Groups) != 1 {
			t.Fatalf("the saved group did not come back: %s", list)
		}
		if got.Groups[0].Name != "console" {
			t.Errorf("group name = %q, want console", got.Groups[0].Name)
		}
		if len(got.Groups[0].Match.CIDRs) != 1 || got.Groups[0].Match.CIDRs[0] != "10.0.0.0/8" {
			t.Errorf("match.cidrs = %v, want [10.0.0.0/8]; the nested shape must survive", got.Groups[0].Match.CIDRs)
		}
		if len(got.Groups[0].Match.Tags) != 1 {
			t.Errorf("match.tags = %v, want [laptop]", got.Groups[0].Match.Tags)
		}
	})

	t.Run("upstreams", func(t *testing.T) {
		// web/src/pages/Upstreams.tsx save(): the console sends the whole
		// server object it read, including the runtime health fields, with a
		// comment saying the server ignores them. Refusing them is drift
		// item 4 — every save in the console answered 400.
		const body = `{"policy":"failover","max_attempts":2,"breaker_threshold":5,
			"healthcheck_interval_s":30,
			"servers":[{"addr":"127.0.0.1:5300","proto":"udp","server_name":"",
				"insecure_skip_verify":false,"weight":1,"comment":"",
				"health":"down","latency_ms":0,"fail_rate":0,"breaker_open":false,
				"queries":0,"avg_ms":0,"p95_ms":0}],
			"bootstraps":[{"name":"quad9","addresses":["9.9.9.9"],"refresh":"24h"}]}`
		code, res := h.do(http.MethodPut, "/api/upstreams", body)
		if code != http.StatusOK {
			t.Fatalf("PUT /api/upstreams with the console payload = %d: %s", code, res)
		}
		// The duration string form must survive the round trip too, or the
		// console's duration inputs show a nanosecond count.
		_, list := h.get("/api/upstreams")
		var got struct {
			HealthCheck json.RawMessage `json:"healthcheck_interval"`
			Cooldown    json.RawMessage `json:"breaker_cooldown"`
			Servers     []struct {
				Addr string `json:"addr"`
			} `json:"servers"`
			Bootstraps []struct {
				Name    string          `json:"name"`
				Refresh json.RawMessage `json:"refresh"`
			} `json:"bootstraps"`
		}
		if err := json.Unmarshal(list, &got); err != nil {
			t.Fatal(err)
		}
		if string(got.HealthCheck) != `"30s"` {
			t.Errorf("healthcheck_interval = %s, want \"30s\"", got.HealthCheck)
		}
		if string(got.Cooldown) == "" {
			t.Error("breaker_cooldown disappeared from the response")
		}
		if len(got.Servers) != 1 || got.Servers[0].Addr != "127.0.0.1:5300" {
			t.Fatalf("servers = %+v, want the saved 127.0.0.1:5300", got.Servers)
		}
		if len(got.Bootstraps) != 1 || got.Bootstraps[0].Name != "quad9" {
			t.Fatalf("bootstraps = %+v, want the saved quad9", got.Bootstraps)
		}
		// Go's canonical spelling of 24h, which is what Duration.MarshalJSON
		// writes and what the console's duration parser accepts.
		if string(got.Bootstraps[0].Refresh) != `"24h0m0s"` {
			t.Errorf("bootstraps[0].refresh = %s, want a duration string", got.Bootstraps[0].Refresh)
		}
	})
}