From 76a6c24777bd1e1c07964ed2739b08e84fb0208b Mon Sep 17 00:00:00 2001 From: Kristoffer Dalby Date: Sun, 8 Nov 2026 20:18:56 +0000 Subject: [PATCH] config: render the example configuration Updates #1926 --- hscontrol/config/generate.go | 207 ++++++++++++++++++ hscontrol/config/generate_test.go | 347 ++++++++++++++++++++++++++++++ hscontrol/config/load_test.go | 5 - hscontrol/config/marshal_test.go | 182 +++++++++------- hscontrol/config/schema.go | 22 +- 5 files changed, 670 insertions(+), 93 deletions(-) create mode 100644 hscontrol/config/generate.go create mode 100644 hscontrol/config/generate_test.go diff --git a/hscontrol/config/generate.go b/hscontrol/config/generate.go new file mode 100644 index 000000000..adb6c2280 --- /dev/null +++ b/hscontrol/config/generate.go @@ -0,0 +1,207 @@ +package config + +import ( + "bytes" + "slices" + "strings" + "unicode/utf8" + + "github.com/juanfont/headscale/hscontrol/types" + "go.yaml.in/yaml/v3" +) + +// ExampleOptions select what [GenerateExample] prints. +type ExampleOptions struct { + // Docs puts each key's documentation above it, as comments. + Docs bool + // Redact hides secrets as [Marshal] does. + Redact bool + // OmitClientOnly leaves out the keys only the CLI reads, which a + // server's configuration has no use for. + OmitClientOnly bool +} + +const ( + exampleHeader = "# Every key: https://headscale.net/stable/ref/configuration-options/\n" + commentWidth = 80 +) + +// GenerateExample is cfg as a YAML configuration file: every key, nested +// in [types.ConfigTree] order, a nil list as [] and a nil map as {}. +func GenerateExample(cfg *types.Config, opts ExampleOptions) ([]byte, error) { + return exampleYAML(cfg, opts, "") +} + +// exampleYAML is the part of [GenerateExample]'s output at the dotted +// root, under its sections; "" is all of it. +func exampleYAML(cfg *types.Config, opts ExampleOptions, root string) ([]byte, error) { + keys, err := schema() + if err != nil { + return nil, err + } + + values := plainFields(cfg, opts.Redact) + top := &yaml.Node{Kind: yaml.MappingNode} + mappings := map[string]*yaml.Node{"": top} + + for _, k := range keys { + if root != "" && k.Path != root && !strings.HasPrefix(k.Path, root+".") && !strings.HasPrefix(root, k.Path+".") { + continue + } + + if opts.OmitClientOnly && clientOnly(k.Path) { + continue + } + + parent, name := "", k.Path + if i := strings.LastIndex(k.Path, "."); i >= 0 { + parent, name = k.Path[:i], k.Path[i+1:] + } + + key := &yaml.Node{Kind: yaml.ScalarNode, Value: name} + if opts.Docs { + key.HeadComment, err = keyComment(k, commentWidth-2*strings.Count(k.Path, ".")-len("# ")) + if err != nil { + return nil, err + } + } + + value := &yaml.Node{Kind: yaml.MappingNode} + if k.Section { + mappings[k.Path] = value + } else { + err = value.Encode(orEmpty(values[k.Path], k.Field.Type)) + if err != nil { + return nil, err + } + } + + mappings[parent].Content = append(mappings[parent].Content, key, value) + } + + var b bytes.Buffer + + if opts.Docs && root == "" { + b.WriteString(exampleHeader) + } + + // One document per top-level key, so blank lines can separate them. + for i := 0; i < len(top.Content); i += 2 { + if opts.Docs && b.Len() > 0 { + b.WriteString("\n") + } + + enc := yaml.NewEncoder(&b) + enc.SetIndent(2) + + err = enc.Encode(&yaml.Node{Kind: yaml.MappingNode, Content: top.Content[i : i+2]}) + if err != nil { + return nil, err + } + + err = enc.Close() + if err != nil { + return nil, err + } + } + + return b.Bytes(), nil +} + +// clientOnly reports whether path is read only by the headscale CLI, from +// its own configuration, so a server's configuration has no use for it. +func clientOnly(path string) bool { + return path == "cli" || strings.HasPrefix(path, "cli.") +} + +// keyComment is k's documentation as "# " lines: its doc, its enum +// values, whether it is required, and its default in words. Prose is +// wrapped to width runes; a list or code paragraph, which has an indented +// line, keeps its lines. A bare "#" separates paragraphs. +func keyComment(k keyInfo, width int) (string, error) { + var lines []string + + add := func(text string) { + for i, p := range strings.Split(text, "\n\n") { + if i > 0 { + lines = append(lines, "#") + } + + para := strings.Split(p, "\n") + if !slices.ContainsFunc(para, func(l string) bool { return strings.HasPrefix(l, " ") || strings.HasPrefix(l, "\t") }) { + para = wrap(p, width) + } + + for _, l := range para { + lines = append(lines, "# "+l) + } + } + } + + add(k.Doc) + + if len(k.Type.Enum) > 0 { + add("One of: `" + strings.Join(k.Type.Enum, "`, `") + "`.") + } + + switch { + case k.Required && k.RequiredWhen == "": + example, err := flowYAML(k.Example) + if err != nil { + return "", err + } + + add("Required. Example: " + example) + case k.Required: + add("Required when " + k.RequiredWhen + ".") + } + + if k.DefaultText != "" { + add("Default: " + k.DefaultText + ".") + } + + return strings.Join(lines, "\n"), nil +} + +// wrap breaks text at spaces into lines of at most width runes; a longer +// word has a line of its own. +func wrap(text string, width int) []string { + var lines []string + + line := "" + + for _, w := range strings.Fields(text) { + if line != "" && utf8.RuneCountInString(line)+1+utf8.RuneCountInString(w) > width { + lines = append(lines, line) + line = "" + } + + if line != "" { + line += " " + } + + line += w + } + + if line != "" { + lines = append(lines, line) + } + + return lines +} + +// flowYAML is v in YAML flow style, on one line. +func flowYAML(v any) (string, error) { + var n yaml.Node + + err := n.Encode(v) + if err != nil { + return "", err + } + + n.Style = yaml.FlowStyle + + out, err := yaml.Marshal(&n) + + return strings.TrimSpace(string(out)), err +} diff --git a/hscontrol/config/generate_test.go b/hscontrol/config/generate_test.go new file mode 100644 index 000000000..274cc146b --- /dev/null +++ b/hscontrol/config/generate_test.go @@ -0,0 +1,347 @@ +package config + +import ( + "bytes" + "os" + "path/filepath" + "slices" + "strings" + "testing" + "unicode/utf8" + + gocmp "github.com/google/go-cmp/cmp" + "github.com/juanfont/headscale/hscontrol/types" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "go.yaml.in/yaml/v3" +) + +// loadGenerated loads out as a config.yaml without environment. +func loadGenerated(t *testing.T, out []byte) *types.Config { + t.Helper() + + path := filepath.Join(t.TempDir(), "config.yaml") + require.NoError(t, os.WriteFile(path, out, 0o600)) + + l, err := Load(path, true, nil) + require.NoError(t, err, string(out)) + + return l.Config +} + +// exampleKeys are the top-level keys of out and the dotted paths of its +// leaves, in order; a section of ConfigTree is walked, any other key is a +// leaf. +func exampleKeys(t *testing.T, out []byte) ([]string, []string) { + t.Helper() + + var doc yaml.Node + require.NoError(t, yaml.Unmarshal(out, &doc)) + + d := Default() + sections := map[string]bool{} + + for _, f := range types.ConfigTree(&d) { + sections[f.Path] = f.Section + } + + var top, leaves []string + + var walk func(prefix string, n *yaml.Node) + walk = func(prefix string, n *yaml.Node) { + for i := 0; i < len(n.Content); i += 2 { + p := joinConfigPath(prefix, n.Content[i].Value) + if prefix == "" { + top = append(top, p) + } + + if sections[p] { + walk(p, n.Content[i+1]) + } else { + leaves = append(leaves, p) + } + } + } + walk("", doc.Content[0]) + + return top, leaves +} + +// commentAbove is the text of the comment lines directly above the line +// line, "# " stripped and joined by spaces. +func commentAbove(out, line string) string { + lines := strings.Split(out, "\n") + i := slices.Index(lines, line) + + var text []string + + for i--; i >= 0 && strings.HasPrefix(strings.TrimSpace(lines[i]), "#"); i-- { + text = append([]string{strings.TrimPrefix(strings.TrimSpace(lines[i]), "# ")}, text...) + } + + return strings.Join(text, " ") +} + +// TestGenerateExample: the example of Default() loads back to it, has every +// key in ConfigTree order and is the same on every run; with docs, each +// key's documentation is above it in lines of at most 80 columns. +func TestGenerateExample(t *testing.T) { + d := Default() + + var wantTop, wantLeaves []string + + for _, f := range types.ConfigTree(&d) { + if !strings.Contains(f.Path, ".") { + wantTop = append(wantTop, f.Path) + } + + if !f.Section { + wantLeaves = append(wantLeaves, f.Path) + } + } + + serverURL := slices.IndexFunc(types.ConfigFields(&d), func(f types.ConfigField) bool { return f.Path == "server_url" }) + require.GreaterOrEqual(t, serverURL, 0) + + for _, docs := range []bool{true, false} { + t.Run(map[bool]string{true: "docs", false: "no docs"}[docs], func(t *testing.T) { + cfg := Default() + + out, err := GenerateExample(&cfg, ExampleOptions{Docs: docs}) + require.NoError(t, err) + + again, err := GenerateExample(&cfg, ExampleOptions{Docs: docs}) + require.NoError(t, err) + assert.True(t, bytes.Equal(out, again), "two runs differ") + + if diff := gocmp.Diff(&d, loadGenerated(t, out), roundTripOpts); diff != "" { + t.Errorf("loads as (-default +loaded):\n%s", diff) + } + + top, leaves := exampleKeys(t, out) + assert.Equal(t, wantTop, top) + assert.Equal(t, wantLeaves, leaves) + + text := string(out) + assert.True(t, strings.HasSuffix(text, "\n") && !strings.HasSuffix(text, "\n\n"), "must end in one newline") + + for l := range strings.SplitSeq(strings.TrimSuffix(text, "\n"), "\n") { + assert.Equal(t, strings.TrimRight(l, " \t"), l, "trailing whitespace") + + if utf8.RuneCountInString(l) > 80 { + assert.Len(t, strings.Fields(strings.TrimPrefix(strings.TrimSpace(l), "#")), 1, "longer than 80 columns: %q", l) + } + } + + if !docs { + assert.NotContains(t, text, "#") + assert.NotContains(t, text, "\n\n") + + return + } + + assert.True(t, strings.HasPrefix(text, "# Every key: https://headscale.net/stable/ref/configuration-options/\n\n"), text) + + above := commentAbove(text, `server_url: ""`) + assert.Contains(t, above, types.ConfigFields(&d)[serverURL].Doc) + assert.Contains(t, above, "Required. Example: https://headscale.example.com") + assert.Contains(t, commentAbove(text, ` level: info`), "One of: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`, `disabled`.") + assert.Contains(t, commentAbove(text, ` base_domain: ""`), "Required when `dns.magic_dns` is true.") + assert.Contains(t, commentAbove(text, ` batcher_workers: 0`), "Default: three quarters of the CPU cores, at least one.") + assert.Equal(t, len(wantTop), strings.Count(text, "\n\n"), "one blank line before each top-level key") + }) + } +} + +// TestKeyComment: prose paragraphs are wrapped to the width, a list or +// code paragraph keeps its lines, and a bare "#" separates paragraphs. +func TestKeyComment(t *testing.T) { + tests := []struct { + name string + key keyInfo + want []string + }{ + { + name: "paragraphs and a list", + key: keyInfo{ConfigField: types.ConfigField{Doc: "The first paragraph is prose, long enough to be wrapped across more than one line.\n\n" + + "The second.\n\n - one item, which is long enough to pass the width but is kept as written\n - two"}}, + want: []string{ + "# The first paragraph is prose, long enough to be", + "# wrapped across more than one line.", + "#", + "# The second.", + "#", + "# - one item, which is long enough to pass the width but is kept as written", + "# - two", + }, + }, + { + name: "code and the generated lines", + key: keyInfo{ + ConfigField: types.ConfigField{Doc: "Run:\n\n\tfirst command\n\t indented more"}, + Type: typeInfo{Enum: []string{"a", "b"}}, + DefaultText: "chosen at start", + }, + want: []string{"# Run:", "#", "# \tfirst command", "# \t indented more", "# One of: `a`, `b`.", "# Default: chosen at start."}, + }, + { + name: "required", + key: keyInfo{ConfigField: types.ConfigField{Doc: "A key."}, Required: true, Example: "https://headscale.example.com"}, + want: []string{"# A key.", "# Required. Example: https://headscale.example.com"}, + }, + { + name: "required when", + key: keyInfo{ConfigField: types.ConfigField{Doc: "A key."}, Required: true, RequiredWhen: "`a` is true"}, + want: []string{"# A key.", "# Required when `a` is true."}, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got, err := keyComment(tt.key, 50) + require.NoError(t, err) + + if diff := gocmp.Diff(tt.want, strings.Split(got, "\n")); diff != "" { + t.Errorf("keyComment (-want +got):\n%s", diff) + } + }) + } +} + +// TestGenerateExampleValues: values YAML would read as another type, or +// as syntax, load back as written. +func TestGenerateExampleValues(t *testing.T) { + for _, s := range []string{"yes", "null", "~", "0x1F", "a: b", "# x", "*x", `""`, ""} { + t.Run(s, func(t *testing.T) { + cfg := Default() + cfg.ServerURL = s + cfg.Database.Postgres.Host = s + cfg.DNSConfig.Nameservers.Global = []string{s} + cfg.OIDC.ExtraParams = map[string]string{"prompt": s} + + for _, docs := range []bool{true, false} { + out, err := GenerateExample(&cfg, ExampleOptions{Docs: docs}) + require.NoError(t, err) + + if diff := gocmp.Diff(&cfg, loadGenerated(t, out), roundTripOpts); diff != "" { + t.Errorf("loads as (-written +loaded):\n%s", diff) + } + } + }) + } + + t.Run("typed", func(t *testing.T) { + cfg := Default() + cfg.UnixSocketPermission = 0o770 + cfg.TLS.ACME.HTTPListen = ":http" + cfg.DNSConfig.Nameservers.Split = map[string][]string{ + "corp.example.com": {"192.0.2.53"}, + "a.example.net": {"198.51.100.53", "2001:db8::53"}, + "z.example.org": {}, + } + + out, err := GenerateExample(&cfg, ExampleOptions{}) + require.NoError(t, err) + + if diff := gocmp.Diff(&cfg, loadGenerated(t, out), roundTripOpts); diff != "" { + t.Errorf("loads as (-written +loaded):\n%s", diff) + } + + assert.Contains(t, string(out), `unix_socket_permission: "0770"`) + assert.Less(t, strings.Index(string(out), "a.example.net"), strings.Index(string(out), "corp.example.com")) + assert.Less(t, strings.Index(string(out), "corp.example.com"), strings.Index(string(out), "z.example.org")) + }) +} + +// TestGenerateExampleRedacts: redacted, the example holds no credential, +// with docs too, and keeps file: references; unredacted, it holds them. +func TestGenerateExampleRedacts(t *testing.T) { + for _, tt := range redactTests { + t.Run(tt.name, func(t *testing.T) { + cfg := redactConfig(tt.provider) + + out, err := GenerateExample(&cfg, ExampleOptions{Docs: true, Redact: true}) + require.NoError(t, err) + + for _, h := range append(slices.Clone(redactHidden), tt.hidden...) { + assert.NotContains(t, string(out), h) + } + + for _, s := range append(slices.Clone(redactShown), tt.shown...) { + assert.Contains(t, string(out), s) + } + + raw, err := GenerateExample(&cfg, ExampleOptions{Docs: true}) + require.NoError(t, err) + + for _, s := range append([]string{"marker-oidc-secret", "marker-pg-pass", "marker-server-pass", "marker-issuer-pass"}, tt.hidden...) { + assert.Contains(t, string(raw), s) + } + }) + } + + for _, tt := range serverURLRedactTests { + t.Run(tt.serverURL, func(t *testing.T) { + cfg := Default() + cfg.ServerURL = tt.serverURL + + out, err := GenerateExample(&cfg, ExampleOptions{Docs: true, Redact: true}) + require.NoError(t, err) + assert.NotContains(t, string(out), "marker") + assert.Contains(t, string(out), tt.shown) + + raw, err := GenerateExample(&cfg, ExampleOptions{Docs: true}) + require.NoError(t, err) + assert.Contains(t, string(raw), tt.serverURL) + }) + } +} + +// TestGenerateExampleOmitClientOnly: a server's configuration leaves out +// the cli section and still loads; the example keeps it. +func TestGenerateExampleOmitClientOnly(t *testing.T) { + for _, tt := range []struct { + name string + omit bool + wantCLI bool + }{ + {name: "example", wantCLI: true}, + {name: "server", omit: true}, + } { + t.Run(tt.name, func(t *testing.T) { + cfg := Default() + + out, err := GenerateExample(&cfg, ExampleOptions{Docs: true, OmitClientOnly: tt.omit}) + require.NoError(t, err) + + top, leaves := exampleKeys(t, out) + assert.Equal(t, tt.wantCLI, slices.Contains(top, "cli")) + assert.Equal(t, tt.wantCLI, slices.ContainsFunc(leaves, clientOnly)) + + if diff := gocmp.Diff(&cfg, loadGenerated(t, out), roundTripOpts); diff != "" { + t.Errorf("loads as (-want +loaded):\n%s", diff) + } + }) + } +} + +// TestGenerateExampleSubtree: a subtree holds its own keys under its +// sections, nothing else. +func TestGenerateExampleSubtree(t *testing.T) { + cfg := Default() + + for _, tt := range []struct { + root string + want string + }{ + {root: "dns.nameservers", want: "dns:\n nameservers:\n global: []\n split: {}\n"}, + {root: "server_url", want: "server_url: \"\"\n"}, + {root: "log", want: "log:\n level: info\n format: text\n"}, + } { + t.Run(tt.root, func(t *testing.T) { + out, err := exampleYAML(&cfg, ExampleOptions{}, tt.root) + require.NoError(t, err) + assert.Equal(t, tt.want, string(out)) + }) + } +} diff --git a/hscontrol/config/load_test.go b/hscontrol/config/load_test.go index 05db8953c..20f620b79 100644 --- a/hscontrol/config/load_test.go +++ b/hscontrol/config/load_test.go @@ -2923,11 +2923,6 @@ disable_check_updates: %t } } -func TestExampleConfigBooleanSettings(t *testing.T) { - _, err := loadServer("../../config-example.yaml", true) - require.NoError(t, err) -} - func TestLoadRejectsNonBoolean(t *testing.T) { for _, key := range []string{"cli.insecure", "disable_check_updates"} { t.Run(key, func(t *testing.T) { diff --git a/hscontrol/config/marshal_test.go b/hscontrol/config/marshal_test.go index fd35800f1..8be727451 100644 --- a/hscontrol/config/marshal_test.go +++ b/hscontrol/config/marshal_test.go @@ -7,6 +7,7 @@ import ( "net/netip" "os" "path/filepath" + "slices" "testing" gocmp "github.com/google/go-cmp/cmp" @@ -259,87 +260,104 @@ func (fakeProvider) DeleteRecords(context.Context, string, []libdns.Record) ([]l return nil, nil } +// redactTests hold a credential in every key that can: dns.challenge.provider +// in each shape, the rest as redactConfig sets them. A redacted rendering +// hides redactHidden and hidden, and shows redactShown and shown. +var redactTests = []struct { + name string + provider map[string]any + hidden []string + shown []string +}{ + { + name: "string token", + provider: map[string]any{"name": "cloudflare", "api_token": "marker-api-token"}, + hidden: []string{"marker-api-token"}, + shown: []string{"cloudflare"}, + }, + { + name: "numeric token", + provider: map[string]any{"name": "cloudflare", "api_token": 123456}, + hidden: []string{"123456"}, + shown: []string{"cloudflare"}, + }, + { + name: "nested registration", + provider: map[string]any{"name": "acmedns", "config": map[string]any{ + "laptop.example.com": map[string]any{ + "username": "marker-user", + "password": "marker-registration-password", + "subdomain": "marker-subdomain", + "server_url": "https://auth.acme-dns.io", + }, + }}, + hidden: []string{"marker-user", "marker-registration-password", "marker-subdomain"}, + shown: []string{"acmedns"}, + }, + { + name: "file reference", + provider: map[string]any{"name": "cloudflare", "api_token": "file:/run/credentials/cloudflare"}, //nolint:gosec // a file reference, not a credential + shown: []string{"cloudflare", "file:/run/credentials/cloudflare"}, + }, +} + +// redactHidden are the credentials redactConfig sets outside the provider. +var redactHidden = []string{ + "marker-oidc-secret", "marker-issuer-user", "marker-issuer-pass", "marker-pg-pass", + "marker-acme-user", "marker-derp-user", "marker-derp-pass", + "marker-derpmap", "marker-go-provider", + "marker-server-user", "marker-server-pass", "marker-cli-user", + "marker-dns-user", "marker-dns-pass", "marker-split-user", +} + +// redactShown is what of redactConfig's values a redacted rendering keeps. +var redactShown = []string{ + "file:/run/credentials/cli_key", "idp.example.com", "derp.example.com", + "https://headscale.example.com", "https://cli.example.com", "1.1.1.1", + "https://dns.example.com/dns-query", "https://dns.example.com/q", +} + +// redactConfig is Default() with a credential in every key that can hold +// one, provider as dns.challenge.provider, and some set only from Go. +func redactConfig(provider map[string]any) types.Config { + cfg := Default() + cfg.ServerURL = "https://marker-server-user:marker-server-pass@headscale.example.com" //nolint:gosec // test markers, not credentials + cfg.CLI.Address = "https://marker-cli-user@cli.example.com" + cfg.DNSConfig.Nameservers.Global = []string{"1.1.1.1", "https://marker-dns-user:marker-dns-pass@dns.example.com/dns-query"} + cfg.DNSConfig.Nameservers.Split = map[string][]string{"corp.example.com": {"https://marker-split-user@dns.example.com/q"}} + cfg.OIDC.ClientSecret = "marker-oidc-secret" + cfg.OIDC.Issuer = "https://marker-issuer-user:marker-issuer-pass@idp.example.com" + cfg.Database.Postgres.Pass = "marker-pg-pass" + cfg.CLI.APIKey = "file:/run/credentials/cli_key" + cfg.TLS.ACME.URL = "https://marker-acme-user@acme.example.com/dir" + cfg.DERP.URLs = []types.HTTPURL{"https://marker-derp-user:marker-derp-pass@derp.example.com/map"} + cfg.DERP.DERPMap = &tailcfg.DERPMap{Regions: map[tailcfg.DERPRegionID]*tailcfg.DERPRegion{ + 900: {RegionID: 900, RegionName: "marker-derpmap"}, + }} + cfg.DNSConfig.Challenge.ProviderSettings = maps.Clone(provider) + cfg.DNSConfig.Challenge.Provider = fakeProvider{Token: "marker-go-provider"} //nolint:gosec // a test marker, not a credential + + return cfg +} + // TestMarshalRedacts: what Marshal prints holds no credential, in any // format: a literal secret, a DNS provider setting of any shape, URL // userinfo, in URL and plain string keys alike, and nothing set only from // Go. The running values keep theirs. func TestMarshalRedacts(t *testing.T) { - tests := []struct { - name string - provider map[string]any - hidden []string - shown []string - }{ - { - name: "string token", - provider: map[string]any{"name": "cloudflare", "api_token": "marker-api-token"}, - hidden: []string{"marker-api-token"}, - shown: []string{"cloudflare"}, - }, - { - name: "numeric token", - provider: map[string]any{"name": "cloudflare", "api_token": 123456}, - hidden: []string{"123456"}, - shown: []string{"cloudflare"}, - }, - { - name: "nested registration", - provider: map[string]any{"name": "acmedns", "config": map[string]any{ - "laptop.example.com": map[string]any{ - "username": "marker-user", - "password": "marker-registration-password", - "subdomain": "marker-subdomain", - "server_url": "https://auth.acme-dns.io", - }, - }}, - hidden: []string{"marker-user", "marker-registration-password", "marker-subdomain"}, - shown: []string{"acmedns"}, - }, - { - name: "file reference", - provider: map[string]any{"name": "cloudflare", "api_token": "file:/run/credentials/cloudflare"}, //nolint:gosec // a file reference, not a credential - shown: []string{"cloudflare", "file:/run/credentials/cloudflare"}, - }, - } - - for _, tt := range tests { + for _, tt := range redactTests { for _, ext := range fileFormats { t.Run(tt.name+ext, func(t *testing.T) { - cfg := Default() - cfg.ServerURL = "https://marker-server-user:marker-server-pass@headscale.example.com" //nolint:gosec // test markers, not credentials - cfg.CLI.Address = "https://marker-cli-user@cli.example.com" - cfg.DNSConfig.Nameservers.Global = []string{"1.1.1.1", "https://marker-dns-user:marker-dns-pass@dns.example.com/dns-query"} - cfg.DNSConfig.Nameservers.Split = map[string][]string{"corp.example.com": {"https://marker-split-user@dns.example.com/q"}} - cfg.OIDC.ClientSecret = "marker-oidc-secret" - cfg.OIDC.Issuer = "https://marker-issuer-user:marker-issuer-pass@idp.example.com" - cfg.Database.Postgres.Pass = "marker-pg-pass" - cfg.CLI.APIKey = "file:/run/credentials/cli_key" - cfg.TLS.ACME.URL = "https://marker-acme-user@acme.example.com/dir" - cfg.DERP.URLs = []types.HTTPURL{"https://marker-derp-user:marker-derp-pass@derp.example.com/map"} - cfg.DERP.DERPMap = &tailcfg.DERPMap{Regions: map[tailcfg.DERPRegionID]*tailcfg.DERPRegion{ - 900: {RegionID: 900, RegionName: "marker-derpmap"}, - }} - cfg.DNSConfig.Challenge.ProviderSettings = maps.Clone(tt.provider) - cfg.DNSConfig.Challenge.Provider = fakeProvider{Token: "marker-go-provider"} //nolint:gosec // a test marker, not a credential + cfg := redactConfig(tt.provider) out, err := Marshal(&cfg, ext) require.NoError(t, err) - for _, h := range append([]string{ - "marker-oidc-secret", "marker-issuer-user", "marker-issuer-pass", "marker-pg-pass", - "marker-acme-user", "marker-derp-user", "marker-derp-pass", - "marker-derpmap", "marker-go-provider", - "marker-server-user", "marker-server-pass", "marker-cli-user", - "marker-dns-user", "marker-dns-pass", "marker-split-user", - }, tt.hidden...) { + for _, h := range append(slices.Clone(redactHidden), tt.hidden...) { assert.NotContains(t, string(out), h) } - for _, s := range append([]string{ - "file:/run/credentials/cli_key", "idp.example.com", "derp.example.com", - "https://headscale.example.com", "https://cli.example.com", "1.1.1.1", - "https://dns.example.com/dns-query", "https://dns.example.com/q", - }, tt.shown...) { + for _, s := range append(slices.Clone(redactShown), tt.shown...) { assert.Contains(t, string(out), s) } @@ -352,24 +370,28 @@ func TestMarshalRedacts(t *testing.T) { } } +// serverURLRedactTests are server_url values with userinfo, each with what +// a redacted rendering shows: "" when the value is withheld whole. +var serverURLRedactTests = []struct { + serverURL string + shown string +}{ + {serverURL: "https://headscale.example.com", shown: "https://headscale.example.com"}, + {serverURL: "https://marker-user:marker-pass@headscale.example.com", shown: "https://headscale.example.com"}, //nolint:gosec // test markers, not credentials + {serverURL: "https://marker-user@headscale.example.com", shown: "https://headscale.example.com"}, + {serverURL: "https://marker-user:marker-pass@headscale.example.com/%zz"}, //nolint:gosec // test markers, not credentials + {serverURL: "https://alice:marker-pass?@headscale.example.com"}, + {serverURL: "https://alice:marker-pass#@headscale.example.com"}, + {serverURL: "https://alice:marker-pass@headscale.example.com:port"}, + {serverURL: "https:/alice:marker-pass@headscale.example.com"}, +} + // TestMarshalRedactsServerURL: server_url is a string, not an HTTPURL, but // its userinfo is as secret; a value whose userinfo cannot be told from the // rest is withheld whole. The raw map, as the round trip writes it, keeps // the value. func TestMarshalRedactsServerURL(t *testing.T) { - for _, tt := range []struct { - serverURL string - shown string // "" when withheld - }{ - {serverURL: "https://headscale.example.com", shown: "https://headscale.example.com"}, - {serverURL: "https://marker-user:marker-pass@headscale.example.com", shown: "https://headscale.example.com"}, //nolint:gosec // test markers, not credentials - {serverURL: "https://marker-user@headscale.example.com", shown: "https://headscale.example.com"}, - {serverURL: "https://marker-user:marker-pass@headscale.example.com/%zz"}, //nolint:gosec // test markers, not credentials - {serverURL: "https://alice:marker-pass?@headscale.example.com"}, - {serverURL: "https://alice:marker-pass#@headscale.example.com"}, - {serverURL: "https://alice:marker-pass@headscale.example.com:port"}, - {serverURL: "https:/alice:marker-pass@headscale.example.com"}, - } { + for _, tt := range serverURLRedactTests { for _, ext := range fileFormats { t.Run(tt.serverURL+ext, func(t *testing.T) { cfg := Default() diff --git a/hscontrol/config/schema.go b/hscontrol/config/schema.go index 217a11909..e88dd2ae0 100644 --- a/hscontrol/config/schema.go +++ b/hscontrol/config/schema.go @@ -221,20 +221,26 @@ func (k *keyInfo) describeLeaf(def any, required map[string]string) error { k.Type.Label = strings.Replace(k.Type.Label, "", "<"+k.MapKey+">", 1) } - switch { - case def != nil: - k.Default = def - case k.Value.Kind() == reflect.Slice: - k.Default = []any{} - default: - k.Default = map[string]any{} - } + k.Default = orEmpty(def, k.Field.Type) k.Example, err = loadExample(k.ConfigField, k.Default) return err } +// orEmpty is v, or for nil, which plainFields gives a nil list or map, an +// empty one of t's kind. +func orEmpty(v any, t reflect.Type) any { + switch { + case v != nil: + return v + case t.Kind() == reflect.Slice: + return []any{} + default: + return map[string]any{} + } +} + // loadExample is f's example tag as plainFields prints it once the // loader has read it, which must be the tag's own JSON; for a bool, !def. func loadExample(f types.ConfigField, def any) (any, error) {