diff --git a/hscontrol/config/generate.go b/hscontrol/config/generate.go index adb6c2280..1bb4b3713 100644 --- a/hscontrol/config/generate.go +++ b/hscontrol/config/generate.go @@ -40,6 +40,13 @@ func exampleYAML(cfg *types.Config, opts ExampleOptions, root string) ([]byte, e return nil, err } + return exampleOf(keys, cfg, opts, root) +} + +// exampleOf is [exampleYAML] from keys, the result of schema. +func exampleOf(keys []keyInfo, cfg *types.Config, opts ExampleOptions, root string) ([]byte, error) { + var err error + values := plainFields(cfg, opts.Redact) top := &yaml.Node{Kind: yaml.MappingNode} mappings := map[string]*yaml.Node{"": top} diff --git a/hscontrol/config/reference.go b/hscontrol/config/reference.go new file mode 100644 index 000000000..830e59111 --- /dev/null +++ b/hscontrol/config/reference.go @@ -0,0 +1,542 @@ +package config + +import ( + "fmt" + "maps" + "regexp" + "slices" + "strings" + "unicode/utf8" + + hsdns "github.com/juanfont/headscale/hscontrol/dns" + "github.com/juanfont/headscale/hscontrol/types" + "go.yaml.in/yaml/v3" +) + +// The page's prose, around what the schema generates. +const ( + referenceHead = "# Configuration options\n\n" + + "!!! note \"Generated page\"\n\n" + + " This page is generated from the doc comments in `hscontrol/types/config.go` by\n" + + " `go generate ./hscontrol/types/`. Edit the comments there, not this page.\n\n" + + "Every key headscale reads, in the order `headscale generate config` prints them, with its type, default,\n" + + "environment variable and an example for a configuration file, the environment and NixOS. Keys that no longer\n" + + "work are listed under [Removed keys](#removed-keys). [Configuration](configuration.md) explains where headscale\n" + + "finds its configuration, how to check it, and shows the full example.\n\n" + + "## Conventions { #conventions }\n\n" + + "### Value types { #types }\n\n" + + referenceEnv = "### Environment variables { #env }\n\n" + + "Every key can also be set with an environment variable: `HEADSCALE_` and the key's path in capitals, with `_` for\n" + + "`.`, e.g. `HEADSCALE_LOG_LEVEL` for `log.level`. Each key below names its variable. A variable wins over the\n" + + "configuration file, which wins over the default; an empty variable counts as unset.\n\n" + + "A list is a JSON array or, unless its values are objects, its values separated by spaces. A map is a JSON object,\n" + + "which replaces the map in the configuration file instead of merging into it. The examples below write every list\n" + + "and map as JSON.\n\n" + + "A `HEADSCALE_` variable that names no key logs a warning, and one for a removed key also says what to do instead.\n" + + "Other software uses the same prefix, so neither stops headscale.\n\n" + + "A DNS provider setting that takes text can also be set on its own as `HEADSCALE_DNS_CHALLENGE_PROVIDER_`,\n" + + "e.g. `HEADSCALE_DNS_CHALLENGE_PROVIDER_API_TOKEN`; see [`dns.challenge.provider`](#dns.challenge.provider).\n\n" + + referenceSecrets = "### Secrets { #secrets }\n\n" + + "A secret takes the value itself or `file:`, which reads it from that file. Environment variables in the path\n" + + "are expanded, as in `file:${CREDENTIALS_DIRECTORY}/oidc_client_secret`, and whitespace around the file's contents\n" + + "is trimmed; an empty file is an error. Headscale reads the file only where the secret is used, and\n" + + "`headscale check config` and `headscale check all` never read it. `headscale generate config --running` and\n" + + "`/debug/config` show a literal secret as `` and a `file:` reference as written.\n\n" + + referenceNixSecret = "On NixOS, keep a secret out of the Nix store: load it as a systemd credential and point the key at it.\n\n" + + "```nix\n" + + "services.headscale.settings.oidc.client_secret = \"file:\\${CREDENTIALS_DIRECTORY}/oidc_client_secret\";\n" + + "systemd.services.headscale.serviceConfig.LoadCredential = [ \"oidc_client_secret:/run/secrets/oidc_client_secret\" ];\n" + + "```\n\n" + + referenceRemoved = "## Removed keys { #removed-keys }\n\n" + + "Keys headscale no longer reads. One in the configuration file stops headscale with an error and a variable for\n" + + "one logs a warning, each saying what to do instead, as the table does.\n\n" + + secretsDir = "file:/run/secrets/" +) + +var ( + backtickedKey = regexp.MustCompile("`[a-z0-9_.]+`") + dottedName = regexp.MustCompile(`\b[a-z][a-z0-9_]*(\.([a-z0-9_]+|\*))+`) + shellWord = regexp.MustCompile(`^[A-Za-z0-9@%+=:,./_-]+$`) +) + +// reference is the page being written. +type reference struct { + strings.Builder + + keys []keyInfo + paths map[string]bool +} + +// GenerateReference is the configuration reference page, +// docs/ref/configuration-options.md: the conventions, every node of +// [types.ConfigTree] with its type, default, variable and examples, and +// the removed keys. +func GenerateReference() ([]byte, error) { + keys, err := schema() + if err != nil { + return nil, err + } + + r := &reference{keys: keys, paths: map[string]bool{}} + for _, k := range keys { + r.paths[k.Path] = true + } + + r.WriteString(referenceHead) + r.types() + r.WriteString(referenceEnv) + r.secrets(keys) + + for _, k := range keys { + err := r.key(k) + if err != nil { + return nil, fmt.Errorf("%s: %w", k.Path, err) + } + } + + r.removed() + + return []byte(strings.TrimSuffix(r.String(), "\n")), nil +} + +// types writes the value-type legend; a row a Type line links carries +// the anchor. +func (r *reference) types() { + linked := map[string]bool{} + for _, k := range r.keys { + linked[k.Type.Anchor] = true + } + + rows := make([][]string, 0, len(leafTypes)) + + for _, t := range leafTypes { + label := t.Label + if id := "type-" + strings.ReplaceAll(t.Label, " ", "-"); linked["#"+id] { + label = `` + label + } + + rows = append(rows, []string{label, t.Format, t.Sample}) + } + + r.table([]string{"Type", "Format", "Example"}, rows) +} + +func (r *reference) secrets(keys []keyInfo) { + var names []string + + for _, k := range keys { + if k.Field.Type == secretType { + names = append(names, r.link(k.Path)) + } + } + + r.WriteString(referenceSecrets) + fmt.Fprintf(r, "The secrets are %s and every string setting of %s.\n\n", strings.Join(names, ", "), r.link(providerKey)) + r.WriteString(referenceNixSecret) +} + +// key writes k's heading and block. +func (r *reference) key(k keyInfo) error { + name := k.Path[strings.LastIndex(k.Path, ".")+1:] + fmt.Fprintf(r, "%s `%s` { #%s data-toc-label=\"%s\" }\n\n", strings.Repeat("#", 2+strings.Count(k.Path, ".")), k.Path, k.Path, name) + + if k.Section { + r.paragraph(r.prose(k.Doc, k.Path)) + r.replaces(k) + + example, err := exampleOf(r.keys, new(Default()), ExampleOptions{}, k.Path) + if err != nil { + return err + } + + fmt.Fprintf(r, "??? example \"All `%s` keys and defaults\"\n\n", k.Path) + r.code("yaml", string(example)) + + return nil + } + + err := r.facts(k) + if err != nil { + return err + } + + r.paragraph(r.prose(k.Doc, k.Path)) + r.details(k) + + return r.examples(k) +} + +// facts writes k's Type, Default and Env lines. +func (r *reference) facts(k keyInfo) error { + typ := "[" + k.Type.Label + "](" + k.Type.Anchor + ")" + if len(k.Type.Enum) > 0 { + typ += ": `" + strings.Join(k.Type.Enum, "`, `") + "`" + } + + def := "- **Required**" + + if !k.Required || k.RequiredWhen != "" { + v, err := flowYAML(k.Default) + if err != nil { + return err + } + + def = "- **Default:** `" + v + "`" + if k.DefaultText != "" { + def += " (" + k.DefaultText + ")" + } + + if k.RequiredWhen != "" { + def += "; required when " + r.prose(k.RequiredWhen, k.Path) + } + } + + env := "`" + k.Env + "`" + if k.Type.Env != "" { + env += " ([" + k.Type.Env + "](#env))" + } + + fmt.Fprintf(r, "- **Type:** %s\n%s\n- **Env:** %s\n\n", typ, def, env) + + return nil +} + +// details writes what k's type adds to its doc: the meaning of each enum +// value, the fields of a DNS record and the DNS providers. An open map's +// key case is its doc's to state. +func (r *reference) details(k keyInfo) { + values := make([][]string, 0, len(k.Type.Enum)) + + for _, v := range k.Type.Enum { + values = append(values, []string{"`" + v + "`", r.prose(types.ConfigValueDoc(k.Field.Type, v), k.Path)}) + } + + if slices.ContainsFunc(values, func(row []string) bool { return row[1] != "" }) { + r.table([]string{"Value", "Meaning"}, values) + } + + if k.Field.Type == recordsType { + fields := make([][]string, 0, len(dnsRecordFields)) + for _, f := range dnsRecordFields { + fields = append(fields, []string{"`" + f.Name + "`", "[string](#type-string)", r.prose(f.Doc, k.Path)}) + } + + r.table([]string{"Field", "Type", "Description"}, fields) + } + + if k.Path == providerKey { + names := hsdns.ProviderNames() + providers := make([][]string, 0, len(names)) + + for _, p := range names { + providers = append(providers, []string{"`" + p + "`", "`" + strings.Join(hsdns.SettingNames(p), "`, `") + "`"}) + } + + r.table([]string{"Provider", "Settings"}, providers) + // The variable holds text, so an object setting cannot have one. + r.paragraph("Each text setting can also be set on its own as `HEADSCALE_DNS_CHALLENGE_PROVIDER_`, e.g. " + + "`HEADSCALE_DNS_CHALLENGE_PROVIDER_API_TOKEN`, which wins over the same setting in `" + k.Env + "` and in the configuration file. " + + "An object setting, such as the `config` of `acmedns`, goes inside the JSON object of `" + k.Env + "`; " + + "see [Environment variables](dns.md#environment-variables).") + } +} + +// examples writes k's example as a file, a variable and, for a key the +// server reads, NixOS settings, then the removed keys it replaces. +func (r *reference) examples(k keyInfo) error { + file, err := yamlText(nest(k.Path, k.Example)) + if err != nil { + return err + } + + r.WriteString("=== \"YAML\"\n\n") + r.code("yaml", file) + r.WriteString("=== \"Environment\"\n\n") + r.code("shell", envLine(k.Env, k.Example)) + + if !clientOnly(k.Path) { + var creds []string + + nix := "services.headscale.settings." + k.Path + " = " + nixLiteral(credentials(k.Path, k.Example, &creds), 0) + ";\n" + if len(creds) > 0 { + nix += "systemd.services.headscale.serviceConfig.LoadCredential = [ \"" + strings.Join(creds, "\" \"") + "\" ];\n" + } + + r.WriteString("=== \"NixOS\"\n\n") + r.code("nix", nix) + } + + r.replaces(k) + + return nil +} + +// credentials is v, the example of the key at path, with each +// file:/run/secrets/ reference, at any map depth, read from the systemd +// credential named for its key instead; it appends each LoadCredential +// entry to creds, in key order. +func credentials(path string, v any, creds *[]string) any { + switch x := v.(type) { + case string: + if !strings.HasPrefix(x, secretsDir) { + return x + } + + name := credentialName(path) + *creds = append(*creds, name+":"+strings.TrimPrefix(x, "file:")) + + return "file:${CREDENTIALS_DIRECTORY}/" + name + case map[string]any: + out := make(map[string]any, len(x)) + for _, key := range slices.Sorted(maps.Keys(x)) { + out[key] = credentials(path+"."+key, x[key], creds) + } + + return out + } + + return v +} + +func (r *reference) replaces(k keyInfo) { + lines := make([]string, 0, len(k.Replaces)) + for _, old := range k.Replaces { + lines = append(lines, "Replaces `"+old.Old+"` ([removed](#"+old.Old+")).") + } + + r.paragraph(strings.Join(lines, "\n")) +} + +// removed writes the removed-keys table: each row's first cell the +// anchor of its key, its last the hint the load error gives. +func (r *reference) removed() { + type row struct { + old string + cells []string + } + + rows := make([]row, 0, len(removedKeys)+1) + + // The provider's _path form is matched by name, not listed. + provider, _ := removedProviderPath(providerKey + "._path") + + for _, k := range append(slices.Clone(removedKeys), provider) { + k.Hint = r.hint(k.Hint) + id := strings.NewReplacer("<", "", ">", "").Replace(k.Old) + rows = append(rows, row{k.Old, []string{`` + "`" + k.Old + "`", k.Since, k.hintAs(r.keyRef, "%s: `%s`")}}) + } + + slices.SortFunc(rows, func(a, b row) int { return strings.Compare(a.old, b.old) }) + + table := make([][]string, 0, len(rows)) + for _, row := range rows { + table = append(table, row.cells) + } + + r.WriteString(referenceRemoved) + r.table([]string{"Key", "Removed in", "What to do"}, table) +} + +// topicPrefix starts the docs links in field comments. YAML and Nix need +// them absolute; the page links its own version instead (Decision 17). +const topicPrefix = "https://headscale.net/stable/ref/" + +// relativeTopicLinks rewrites each topicPrefix + "/[#frag]" in doc +// to ".md[#frag]". +func relativeTopicLinks(doc string) string { + var b strings.Builder + + for { + before, after, found := strings.Cut(doc, topicPrefix) + b.WriteString(before) + + if !found { + return b.String() + } + + path := after[:runEnd(after, isPathRune)] + + slash := strings.LastIndexByte(path, '/') + if slash <= 0 { + b.WriteString(topicPrefix) + + doc = after + + continue + } + + b.WriteString(path[:slash] + ".md") + + doc = after[slash+1:] + if frag, ok := strings.CutPrefix(doc, "#"); ok { + if n := runEnd(frag, isFragRune); n > 0 { + b.WriteString("#" + frag[:n]) + + doc = frag[n:] + } + } + } +} + +// runEnd is the length of s's leading run of runes that keep returns true for. +func runEnd(s string, keep func(rune) bool) int { + if n := strings.IndexFunc(s, func(c rune) bool { return !keep(c) }); n >= 0 { + return n + } + + return len(s) +} + +func isFragRune(c rune) bool { + return c >= 'a' && c <= 'z' || c >= '0' && c <= '9' || c == '_' || c == '-' +} + +func isPathRune(c rune) bool { + return isFragRune(c) || c == '/' +} + +// prose is a doc as the page prints it: each backticked key but self +// linked to its heading, each docs link relative. +func (r *reference) prose(doc, self string) string { + doc = relativeTopicLinks(doc) + + return backtickedKey.ReplaceAllStringFunc(doc, func(span string) string { + key := strings.Trim(span, "`") + if !r.paths[key] || key == self { + return span + } + + return "[" + span + "](#" + key + ")" + }) +} + +// hint is a removed key's free-text hint as Markdown: each key linked, +// each key pattern such as dns_config.* as code. +func (r *reference) hint(text string) string { + return dottedName.ReplaceAllStringFunc(text, func(name string) string { + switch { + case r.paths[name]: + return r.link(name) + case strings.HasSuffix(name, ".*"): + return "`" + name + "`" + } + + return name + }) +} + +func (r *reference) link(key string) string { + return "[`" + key + "`](#" + key + ")" +} + +// keyRef is key as code, linked to its heading or, for a placeholder +// such as dns.challenge.provider., to its map's. +func (r *reference) keyRef(key string) string { + target, _, _ := strings.Cut(key, ".<") + if !r.paths[target] { + return "`" + key + "`" + } + + return "[`" + key + "`](#" + target + ")" +} + +func (r *reference) paragraph(text string) { + if text != "" { + r.WriteString(text + "\n\n") + } +} + +// code writes body, which ends in a newline, as a fenced block indented +// into the admonition or tab above it. +func (r *reference) code(lang, body string) { + const indent = " " + + r.WriteString(indent + "```" + lang + "\n") + + for l := range strings.Lines(body) { + if l != "\n" { + r.WriteString(indent) + } + + r.WriteString(l) + } + + r.WriteString(indent + "```\n\n") +} + +// table writes a table as mdformat does: each cell padded to its +// column's width in runes, | escaped. +func (r *reference) table(header []string, body [][]string) { + rows := append([][]string{header}, body...) + widths := make([]int, len(header)) + cells := make([][]string, len(rows)) + + for i, row := range rows { + for j, c := range row { + c = strings.ReplaceAll(c, "|", `\|`) + cells[i] = append(cells[i], c) + widths[j] = max(widths[j], 3, utf8.RuneCountInString(c)) + } + } + + line := func(cells []string) { + for j, c := range cells { + r.WriteString("| " + c + strings.Repeat(" ", widths[j]-utf8.RuneCountInString(c)) + " ") + } + + r.WriteString("|\n") + } + + line(cells[0]) + + delimiter := make([]string, len(widths)) + for j, w := range widths { + delimiter[j] = strings.Repeat("-", w) + } + + line(delimiter) + + for _, row := range cells[1:] { + line(row) + } + + r.WriteString("\n") +} + +// yamlText is v as a YAML file indented as GenerateExample indents. +func yamlText(v any) (string, error) { + var b strings.Builder + + enc := yaml.NewEncoder(&b) + enc.SetIndent(2) + + err := enc.Encode(v) + if err != nil { + return "", err + } + + err = enc.Close() + + return b.String(), err +} + +// envLine is the shell line setting the variable env to v, exported so +// the headscale started next reads it. +func envLine(env string, v any) string { + return "export " + env + "=" + shellQuote(envValue(v)) + "\n" +} + +// shellQuote is s as one POSIX shell word: as is when no character is +// special, else single-quoted. +func shellQuote(s string) string { + if shellWord.MatchString(s) { + return s + } + + return "'" + strings.ReplaceAll(s, "'", `'\''`) + "'" +} diff --git a/hscontrol/config/reference_test.go b/hscontrol/config/reference_test.go new file mode 100644 index 000000000..196925622 --- /dev/null +++ b/hscontrol/config/reference_test.go @@ -0,0 +1,368 @@ +package config + +import ( + "os" + "os/exec" + "regexp" + "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" +) + +var ( + refHeading = regexp.MustCompile("(?m)^(#+) `([^`]+)` \\{ #(\\S+) data-toc-label=\"([^\"]+)\" \\}$") + refAnchor = regexp.MustCompile(`\{ #([^ }]+)|`) + refLink = regexp.MustCompile(`\]\(#([^)]+)\)`) + refFence = regexp.MustCompile("(?ms)^ *```.*?^ *```$") + refCode = regexp.MustCompile("`[^`]*`") + refBareTag = regexp.MustCompile(`<[A-Za-z/][^>]*>`) +) + +func referencePage(t *testing.T) string { + t.Helper() + + page, err := GenerateReference() + require.NoError(t, err) + + return string(page) +} + +// keyBlocks are page's blocks by key path, each from its heading to the +// next heading. +func keyBlocks(page string) map[string]string { + blocks := map[string]string{} + + for _, m := range refHeading.FindAllStringSubmatchIndex(page, -1) { + block := page[m[1]:] + if i := strings.Index(block, "\n#"); i >= 0 { + block = block[:i] + } + + blocks[page[m[4]:m[5]]] = block + } + + return blocks +} + +func TestReference(t *testing.T) { + page := referencePage(t) + d := Default() + tree := types.ConfigTree(&d) + + t.Run("headings", func(t *testing.T) { + want := make([]string, 0, len(tree)) + + for _, f := range tree { + leaf := f.Path[strings.LastIndex(f.Path, ".")+1:] + want = append(want, strings.Repeat("#", 2+strings.Count(f.Path, "."))+" "+f.Path+" #"+f.Path+" "+leaf) + } + + headings := refHeading.FindAllStringSubmatch(page, -1) + got := make([]string, 0, len(headings)) + + for _, m := range headings { + got = append(got, m[1]+" "+m[2]+" #"+m[3]+" "+m[4]) + } + + if diff := gocmp.Diff(want, got); diff != "" { + t.Errorf("headings (-want +got):\n%s", diff) + } + + require.Contains(t, page, "#### `dns.nameservers.split` { #dns.nameservers.split data-toc-label=\"split\" }\n") + }) + + blocks := keyBlocks(page) + + for _, f := range tree { + if f.Section { + continue + } + + t.Run(f.Path, func(t *testing.T) { + block := blocks[f.Path] + require.Contains(t, block, "\n- **Type:** [") + require.Regexp(t, `\n- \*\*(Default:\*\* |Required\*\*\n)`, block) + require.Contains(t, block, "\n- **Env:** `"+configEnvName(f.Path)+"`") + }) + } + + t.Run("removed rows", func(t *testing.T) { + _, removed, ok := strings.Cut(page, "\n## Removed keys { #removed-keys }\n") + require.True(t, ok) + + for _, r := range removedKeys { + require.Contains(t, removed, "| `"+r.Old+"` ") + } + + require.Contains(t, removed, "| `dns.challenge.provider._path` ") + require.Equal(t, len(removedKeys)+1, strings.Count(removed, "`](#dns.challenge.provider): `file:` ", + "| move every `dns_config.*` key to dns (nameservers to [`dns.nameservers.global`](#dns.nameservers.global), ", + } { + require.Contains(t, removed, row) + } + }) + + t.Run("anchors", func(t *testing.T) { + matches := refAnchor.FindAllStringSubmatch(page, -1) + ids := make([]string, 0, len(matches)) + + for _, m := range matches { + ids = append(ids, m[1]+m[2]) + } + + for _, id := range []string{"conventions", "types", "env", "secrets", "removed-keys", "type-file-mode", "type-URL", "type-list", "type-map"} { + require.Contains(t, ids, id) + } + + seen := map[string]bool{} + for _, id := range ids { + require.False(t, seen[id], "duplicate anchor %s", id) + seen[id] = true + } + + linked := map[string]bool{} + + for _, m := range refLink.FindAllStringSubmatch(page, -1) { + assert.True(t, seen[m[1]], "link to missing anchor #%s", m[1]) + linked[m[1]] = true + } + + for _, id := range ids { + if strings.HasPrefix(id, "type-") { + assert.True(t, linked[id], "legend id %s has no link", id) + } + } + }) + + t.Run("links", func(t *testing.T) { + require.NotContains(t, page, "https://headscale.net/stable/ref/") + require.Contains(t, page, "(dns.md#dns-01-challenge-provider)") + require.Contains(t, page, "(api.md#remote-control)") + // A key's doc links other keys, not itself. + require.Contains(t, blocks["tls.key_path"], "[`tls.cert_path`](#tls.cert_path)") + require.NotContains(t, blocks["oidc.issuer"], "](#oidc.issuer)") + }) +} + +func TestRelativeTopicLinks(t *testing.T) { + tests := []struct { + name, doc, want string + }{ + {"page", "See https://headscale.net/stable/ref/dns/.", "See dns.md."}, + {"fragment", "(https://headscale.net/stable/ref/oidc/#enable-pkce-recommended)", "(oidc.md#enable-pkce-recommended)"}, + {"nested page", "https://headscale.net/stable/ref/integration/reverse-proxy/", "integration/reverse-proxy.md"}, + {"two links", "https://headscale.net/stable/ref/dns/ and https://headscale.net/stable/ref/api/#remote-control", "dns.md and api.md#remote-control"}, + {"empty fragment", "https://headscale.net/stable/ref/dns/#", "dns.md#"}, + {"other host", "https://example.com/stable/ref/dns/", "https://example.com/stable/ref/dns/"}, + {"prefix only", "https://headscale.net/stable/ref/", "https://headscale.net/stable/ref/"}, + {"no link", "plain text", "plain text"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + require.Equal(t, tt.want, relativeTopicLinks(tt.doc)) + }) + } +} + +// TestReferenceKeys pins the parts of a key's block the schema decides. +func TestReferenceKeys(t *testing.T) { + blocks := keyBlocks(referencePage(t)) + + tests := []struct { + path string + want, hide []string + }{ + {path: "server_url", want: []string{"\n- **Required**\n", "\n export HEADSCALE_SERVER_URL=https://headscale.example.com\n"}}, + {path: "database.type", want: []string{ + "- **Type:** [enum](#type-enum): `sqlite`, `sqlite3`, `postgres`\n", + "- **Required**\n", + "| `postgres` | PostgreSQL, at [`database.postgres.host`](#database.postgres.host). ", + }}, + {path: "dns.base_domain", want: []string{"- **Default:** `\"\"`; required when [`dns.magic_dns`](#dns.magic_dns) is true\n"}}, + {path: "tuning.batcher_workers", want: []string{"- **Default:** `0` (three quarters of the CPU cores, at least one)\n"}}, + {path: "unix_socket_permission", want: []string{"- **Type:** [file mode](#type-file-mode)\n", "- **Default:** `\"0770\"`\n"}}, + {path: "dns.nameservers.split", want: []string{ + "- **Type:** [map of `` → list of strings](#type-map)\n", + "- **Env:** `HEADSCALE_DNS_NAMESERVERS_SPLIT` ([JSON object](#env))\n", + " export HEADSCALE_DNS_NAMESERVERS_SPLIT='{\"corp.example.com\":[\"192.0.2.53\"],", + " services.headscale.settings.dns.nameservers.split = {\n \"corp.example.com\" = [\n", + }, hide: []string{"Each `` key"}}, + {path: "database.postgres.pass", want: []string{ + "- **Type:** [secret](#secrets)\n", + " services.headscale.settings.database.postgres.pass = \"file:\\${CREDENTIALS_DIRECTORY}/database_postgres_pass\";\n", + " systemd.services.headscale.serviceConfig.LoadCredential = [ \"database_postgres_pass:/run/secrets/postgres_password\" ];\n", + "Replaces `database.postgres.password_file` ([removed](#database.postgres.password_file)).", + }}, + {path: "dns.challenge.provider", want: []string{ + "| Provider ", + "| `cloudflare` ", + "Each text setting can also be set on its own as `HEADSCALE_DNS_CHALLENGE_PROVIDER_`", + "An object setting, such as the `config` of `acmedns`, goes inside the JSON object of `HEADSCALE_DNS_CHALLENGE_PROVIDER`", + "(dns.md#environment-variables)", + "api_token = \"file:\\${CREDENTIALS_DIRECTORY}/dns_challenge_provider_api_token\";", + "LoadCredential = [ \"dns_challenge_provider_api_token:/run/secrets/cloudflare\" ];", + }}, + {path: "cli", want: []string{"`services.headscale.settings`"}}, + {path: "cli.api_key", want: []string{"=== \"Environment\"", "export HEADSCALE_CLI_API_KEY=file:/run/secrets/"}, hide: []string{"=== \"NixOS\"", "CREDENTIALS_DIRECTORY"}}, + {path: "dns.extra_records", want: []string{ + "- **Env:** `HEADSCALE_DNS_EXTRA_RECORDS` ([JSON array](#env))\n", + "| Field ", + "| `value` | [string](#type-string) | The IP address the name resolves to. ", + }}, + {path: "dns", want: []string{ + "??? example \"All `dns` keys and defaults\"\n\n ```yaml\n dns:\n magic_dns: true\n", + "Replaces `dns_config` ([removed](#dns_config)).", + }}, + {path: "noise.private_key_path", want: []string{ + "Replaces `private_key_path` ([removed](#private_key_path)).\nReplaces `noise_private_key_path` ([removed](#noise_private_key_path)).", + }}, + {path: "tls.acme.hostname", want: []string{" tls:\n acme:\n hostname: "}}, + } + for _, tt := range tests { + t.Run(tt.path, func(t *testing.T) { + for _, w := range tt.want { + require.Contains(t, blocks[tt.path], w) + } + + for _, h := range tt.hide { + require.NotContains(t, blocks[tt.path], h) + } + }) + } +} + +// TestOpenMapDocs: the page prints an open map's key case only through its +// doc, so the doc must state the rule the loader applies. +func TestOpenMapDocs(t *testing.T) { + keys, err := schema() + require.NoError(t, err) + + for _, k := range keys { + if !k.Open { + continue + } + + t.Run(k.Path, func(t *testing.T) { + if slices.Contains(caseSensitiveMaps, k.Path) { + require.Contains(t, k.Doc, "keep their case") + + return + } + + require.Contains(t, k.Doc, "lowercased on load") + require.Contains(t, k.Doc, "two that differ only in case are an error") + }) + } +} + +func TestReferenceEscapes(t *testing.T) { + page := referencePage(t) + + d := Default() + example, err := GenerateExample(&d, ExampleOptions{Docs: true}) + require.NoError(t, err) + + // The macros plugin renders the page and the included example as Jinja. + for name, text := range map[string]string{"page": page, "example": string(example)} { + for _, jinja := range []string{"{{", "{%", "{#"} { + require.NotContains(t, text, jinja, name) + } + } + + prose := refCode.ReplaceAllString(refFence.ReplaceAllString(page, ""), "") + prose = regexp.MustCompile(``).ReplaceAllString(prose, "") + require.Empty(t, refBareTag.FindAllString(prose, -1)) + + tables := 0 + + var width []int + + for line := range strings.Lines(page + "\n") { + if !strings.HasPrefix(line, "|") { + if len(width) > 0 { + tables++ + require.Len(t, slices.Compact(width), 1, "rows of table %d differ in width", tables) + } + + width = nil + + continue + } + + width = append(width, utf8.RuneCountInString(line)) + } + + require.GreaterOrEqual(t, tables, 3) +} + +// exported runs line in a clean shell and returns what a child it starts +// reads from env. +func exported(t *testing.T, line, env string) string { + t.Helper() + + sh, err := exec.LookPath("sh") + if err != nil { + t.Skip("no sh") + } + + cmd := exec.CommandContext(t.Context(), sh, "-c", line+`sh -c 'printf %s "$`+env+`"'`) + cmd.Env = []string{"PATH=" + os.Getenv("PATH")} + + out, err := cmd.Output() + require.NoError(t, err, line) + + return string(out) +} + +// TestReferenceEnvTabs: an Environment tab pasted into a shell reaches +// the headscale it starts. +func TestReferenceEnvTabs(t *testing.T) { + blocks := keyBlocks(referencePage(t)) + byPath := schemaByPath(t) + + for _, path := range []string{"dns.nameservers.global", "dns.nameservers.split", "database.postgres.pass", "dns.challenge.provider"} { + t.Run(path, func(t *testing.T) { + _, tab, ok := strings.Cut(blocks[path], "=== \"Environment\"\n\n ```shell\n ") + require.True(t, ok) + + line, _, _ := strings.Cut(tab, "\n") + k := byPath[path] + require.Equal(t, envValue(k.Example), exported(t, line+"\n", k.Env)) + }) + } + + t.Run("quotes", func(t *testing.T) { + v := `it's "q" $HOME` + require.Equal(t, v, exported(t, envLine("HEADSCALE_X", v), "HEADSCALE_X")) + }) +} + +func TestShellQuote(t *testing.T) { + tests := []struct{ in, want string }{ + {in: "abc", want: "abc"}, + {in: "file:/run/secrets/x", want: "file:/run/secrets/x"}, + {in: "a b", want: "'a b'"}, + {in: "file:${X}/y", want: "'file:${X}/y'"}, + {in: "it's", want: `'it'\''s'`}, + {in: "", want: "''"}, + {in: `["a","b"]`, want: `'["a","b"]'`}, + } + for _, tt := range tests { + t.Run(tt.in, func(t *testing.T) { + require.Equal(t, tt.want, shellQuote(tt.in)) + }) + } +} diff --git a/tools/configgen/files/main.go b/tools/configgen/files/main.go index 5dcf0deec..474006891 100644 --- a/tools/configgen/files/main.go +++ b/tools/configgen/files/main.go @@ -1,8 +1,9 @@ // Command files writes the files generated from the configuration schema -// of hscontrol/config: `files ` writes nix/options.generated.nix -// below the repository root. It is not part of configgen, which stays -// standard library only so its table regenerates when the committed one -// does not compile. +// of hscontrol/config: `files ` writes nix/options.generated.nix, +// docs/ref/configuration-options.md and docs/ref/config-example.yaml below +// the repository root. It is not part of configgen, which stays standard +// library only so its table regenerates when the committed one does not +// compile. // // `files -load ` prints the file as config.Load reads it, for the // NixOS options check to compare with the values it was written from. @@ -17,6 +18,10 @@ import ( "github.com/juanfont/headscale/hscontrol/config" ) +// exampleHeader marks the committed example; generate config output is +// the user's to edit, so it carries none. +const exampleHeader = "# Generated from hscontrol/types/config.go by go generate; do not edit.\n" + func main() { var err error @@ -63,5 +68,28 @@ func write(root string) error { return err } - return os.WriteFile(filepath.Join(root, "nix", "options.generated.nix"), nix, 0o600) + page, err := config.GenerateReference() + if err != nil { + return err + } + + d := config.Default() + + example, err := config.GenerateExample(&d, config.ExampleOptions{Docs: true}) + if err != nil { + return err + } + + for path, b := range map[string][]byte{ + "nix/options.generated.nix": nix, + "docs/ref/configuration-options.md": page, + "docs/ref/config-example.yaml": append([]byte(exampleHeader), example...), + } { + err := os.WriteFile(filepath.Join(root, path), b, 0o600) + if err != nil { + return err + } + } + + return nil } diff --git a/tools/configgen/files/main_test.go b/tools/configgen/files/main_test.go index 73cfd6063..a5d280be3 100644 --- a/tools/configgen/files/main_test.go +++ b/tools/configgen/files/main_test.go @@ -5,6 +5,7 @@ import ( "io" "os" "path/filepath" + "regexp" "testing" "github.com/google/go-cmp/cmp" @@ -14,19 +15,43 @@ import ( "go.yaml.in/yaml/v3" ) -func TestWrite(t *testing.T) { +// generatedFiles are the files write writes, below the repository root. +var generatedFiles = []string{"nix/options.generated.nix", "docs/ref/configuration-options.md", "docs/ref/config-example.yaml"} + +// writeTree runs write into a new repository root. +func writeTree(t *testing.T) string { + t.Helper() + root := t.TempDir() - require.NoError(t, os.Mkdir(filepath.Join(root, "nix"), 0o755)) + for _, dir := range []string{"nix", "docs/ref"} { + require.NoError(t, os.MkdirAll(filepath.Join(root, dir), 0o755)) + } + require.NoError(t, write(root)) - want, err := config.GenerateNixOptions(nil) + return root +} + +func TestWrite(t *testing.T) { + root := writeTree(t) + + nix, err := config.GenerateNixOptions(nil) + require.NoError(t, err) + + page, err := config.GenerateReference() + require.NoError(t, err) + + d := config.Default() + example, err := config.GenerateExample(&d, config.ExampleOptions{Docs: true}) require.NoError(t, err) tests := []struct { path string want []byte }{ - {path: "nix/options.generated.nix", want: want}, + {path: "nix/options.generated.nix", want: nix}, + {path: "docs/ref/configuration-options.md", want: page}, + {path: "docs/ref/config-example.yaml", want: append([]byte("# Generated from hscontrol/types/config.go by go generate; do not edit.\n"), example...)}, } for _, tt := range tests { @@ -41,6 +66,28 @@ func TestWrite(t *testing.T) { } } +// TestGeneratedFiles: each file is the same on every run, ends in one +// newline and has no trailing whitespace, so the repository's hooks leave +// it alone. +func TestGeneratedFiles(t *testing.T) { + first, second := writeTree(t), writeTree(t) + trailing := regexp.MustCompile(`(?m)[ \t]$`) + + for _, path := range generatedFiles { + t.Run(path, func(t *testing.T) { + a, err := os.ReadFile(filepath.Join(first, path)) + require.NoError(t, err) + + b, err := os.ReadFile(filepath.Join(second, path)) + require.NoError(t, err) + + require.Equal(t, a, b) + require.True(t, bytes.HasSuffix(a, []byte("\n")) && !bytes.HasSuffix(a, []byte("\n\n")), "must end in one newline") + require.Empty(t, trailing.FindAll(a, -1), "trailing whitespace") + }) + } +} + // TestLoad: load prints a file as config.Load reads it, in canonical form // and without the cli section; it fails on what Load rejects. func TestLoad(t *testing.T) {