mirror of
https://github.com/juanfont/headscale.git
synced 2026-11-19 11:57:07 +09:00
1 parent
63fdd50505
commit
b92d27b7db
5 files changed
+1001
-9
No files matched your search
@@ -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}
|
||||
|
||||
@@ -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_<SETTING>`,\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:<path>`, 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 `<redacted>` 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 = `<span id="` + id + `"></span>` + 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_<SETTING>`, 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 <setting>_path form is matched by name, not listed.
|
||||
provider, _ := removedProviderPath(providerKey + ".<setting>_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{`<span id="` + id + `"></span>` + "`" + 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 + "<page>/[#frag]" in doc
|
||||
// to "<page>.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.<setting>, 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, "'", `'\''`) + "'"
|
||||
}
|
||||
@@ -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(`\{ #([^ }]+)|<span id="([^"]+)"></span>`)
|
||||
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, "| <span id=\""+r.Old+"\"></span>`"+r.Old+"` ")
|
||||
}
|
||||
|
||||
require.Contains(t, removed, "| <span id=\"dns.challenge.provider.setting_path\"></span>`dns.challenge.provider.<setting>_path` ")
|
||||
require.Equal(t, len(removedKeys)+1, strings.Count(removed, "<span id="))
|
||||
|
||||
// The last cell is the hint the load error gives, keys linked.
|
||||
for _, row := range []string{
|
||||
"| use [`log.format`](#log.format): `json` ",
|
||||
"| use [`prefixes.v4`](#prefixes.v4) and [`prefixes.v6`](#prefixes.v6) ",
|
||||
"| remove `oidc.user`; see the CHANGELOG for context ",
|
||||
"| use [`dns.challenge.provider.<setting>`](#dns.challenge.provider): `file:<path>` ",
|
||||
"| 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 `<domain>` → 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 `<domain>` 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_<SETTING>`",
|
||||
"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(`<span id="[^"]+"></span>`).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))
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -1,8 +1,9 @@
|
||||
// Command files writes the files generated from the configuration schema
|
||||
// of hscontrol/config: `files <root>` 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 <root>` 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 <file>` 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
|
||||
}
|
||||
@@ -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) {
|
||||
|
||||
Reference in new issue
Block a user