control/controlknobs: clean up documentation and updater function (#22349)

In controlknobs.Knobs, each atomic field represents a knob controlled
by the existence of a capability in the node’s CapMap. This patch adds
a doc comment for each field referencing which nodecap.Cap sets it.

This patch also cleans up UpdateFromNodeAttributes to unify the
CapMap lookup with the setting of the appropriate Knobs field.
Previously, it was easier to accidentally mismatch them because they
were split in two places.

Updates #cleanup

Change-Id: I329b0c5732f1c13f2e0d8609c35f42ad645b6bd7

Signed-off-by: Simon Law <sfllaw@tailscale.com>
This commit is contained in:
Simon Law authored and GitHub committed 2026-11-19 10:34:29 -08:00
1 parent f6483cc55a
commit d843b72e35
2 files changed
+166 -74

No files matched your search

+94 -2
View File
@@ -4,21 +4,113 @@
package controlknobs
import (
"go/ast"
"go/constant"
"go/types"
"maps"
"reflect"
"regexp"
"slices"
"testing"
gcmp "github.com/google/go-cmp/cmp"
"golang.org/x/tools/go/packages"
"tailscale.com/tailcfg"
"tailscale.com/tailcfg/nodecap"
"tailscale.com/types/logger"
)
func TestKnobContainsNodeCapDocComment(t *testing.T) {
cfg := &packages.Config{Mode: packages.NeedSyntax | packages.NeedTypes}
pkgs, err := packages.Load(cfg, ".")
if err != nil {
t.Fatal(err)
}
if len(pkgs) != 1 {
t.Fatalf("loaded too many packages: %v", pkgs)
}
pkg := pkgs[0]
if len(pkg.Errors) != 0 {
t.Fatalf("loading package: %v", pkg.Errors)
}
var nodecaps *types.Scope
for _, imp := range pkg.Types.Imports() {
if imp.Path() == reflect.TypeFor[nodecap.Cap]().PkgPath() {
nodecaps = imp.Scope()
break
}
}
if nodecaps == nil {
t.Fatal("nodecap package not imported")
}
var fields []*ast.Field
Fields:
for _, f := range pkg.Syntax {
for n := range ast.Preorder(f) {
if ts, ok := n.(*ast.TypeSpec); ok && ts.Name.Name == "Knobs" {
fields = ts.Type.(*ast.StructType).Fields.List
break Fields
}
}
}
if fields == nil {
t.Fatal("Knobs fields not found")
}
base := new(Knobs)
base.UpdateFromNodeAttributes(nil)
baseJSON := base.AsDebugJSON()
docRef := regexp.MustCompile(`\[nodecap\.(\w+)\]`)
for _, f := range fields {
for _, id := range f.Names {
refs := docRef.FindAllStringSubmatch(f.Doc.Text(), -1)
if len(refs) == 0 {
t.Errorf("%s: doc comment missing link to [nodecap.Cap] for this knob", id.Name)
break
}
for _, ref := range refs {
nc, ok := nodecaps.Lookup(ref[1]).(*types.Const)
if !ok {
t.Errorf("%s: doc comment names unknown nodecap.%s", id.Name, ref[1])
continue
}
k := new(Knobs)
k.UpdateFromNodeAttributes(tailcfg.NodeCapMap{
nodecap.Cap(constant.StringVal(nc.Val())): nil,
})
if got := k.AsDebugJSON()[id.Name]; got == baseJSON[id.Name] {
t.Errorf("%s: nodecap.%s did not affect this knob; still %v", id.Name, ref[1], got)
}
}
}
}
}
func TestAsDebugJSON(t *testing.T) {
var nilPtr *Knobs
if got := nilPtr.AsDebugJSON(); got != nil {
t.Errorf("AsDebugJSON(nil) = %v; want nil", got)
}
var wantKeys []string
for f := range reflect.TypeFor[Knobs]().Fields() {
wantKeys = append(wantKeys, f.Name)
}
slices.Sort(wantKeys)
k := new(Knobs)
got := k.AsDebugJSON()
if want := reflect.TypeFor[Knobs]().NumField(); len(got) != want {
t.Errorf("AsDebugJSON map has %d fields; want %v", len(got), want)
gotKeys := slices.Sorted(maps.Keys(got))
if diff := gcmp.Diff(wantKeys, gotKeys); diff != "" {
t.Errorf("AsDebugJSON keys (-want +got)\n%s", diff)
}
t.Logf("Got: %v", logger.AsJSON(got))
}