mirror of
https://github.com/juanfont/headscale.git
synced 2026-11-19 11:57:07 +09:00
1 parent
caecddd249
commit
0578c2a571
11 files changed
+1260
-187
No files matched your search
@@ -13,13 +13,14 @@ import (
|
||||
// outside it means a generator reached further than expected, and the area is
|
||||
// dropped rather than committed.
|
||||
var generatedPaths = map[string]bool{
|
||||
"hscontrol/types/types_clone.go": true,
|
||||
"hscontrol/types/types_view.go": true,
|
||||
"hscontrol/capver/capver_generated.go": true,
|
||||
"hscontrol/capver/capver_test_data.go": true,
|
||||
"gen/client/v1/client.gen.go": true,
|
||||
"gen/client/v2/client.gen.go": true,
|
||||
".github/workflows/test-integration.yaml": true,
|
||||
"hscontrol/types/types_clone.go": true,
|
||||
"hscontrol/types/types_view.go": true,
|
||||
"hscontrol/types/config_docs_generated.go": true,
|
||||
"hscontrol/capver/capver_generated.go": true,
|
||||
"hscontrol/capver/capver_test_data.go": true,
|
||||
"gen/client/v1/client.gen.go": true,
|
||||
"gen/client/v2/client.gen.go": true,
|
||||
".github/workflows/test-integration.yaml": true,
|
||||
}
|
||||
|
||||
// oapiPin finds the oapi-codegen version the Makefile pins, so the clients are
|
||||
|
||||
@@ -0,0 +1,277 @@
|
||||
// Command configgen writes files generated from the configuration's Go
|
||||
// source. `configgen table <pkgdir> <out.go>` writes the doc comments of
|
||||
// the configuration fields and enum values as Go maps, so the binary can
|
||||
// print them; out.go is not read.
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"errors"
|
||||
"fmt"
|
||||
"go/ast"
|
||||
"go/format"
|
||||
"go/parser"
|
||||
"go/token"
|
||||
"log"
|
||||
"maps"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"reflect"
|
||||
"slices"
|
||||
"strconv"
|
||||
"strings"
|
||||
"unicode"
|
||||
"unicode/utf8"
|
||||
)
|
||||
|
||||
var (
|
||||
errUsage = errors.New("usage: configgen table <pkgdir> <out.go>")
|
||||
errEnumValue = errors.New("value must be a string literal with an explicit type")
|
||||
errNameOnly = errors.New("doc comment says nothing after the Go name")
|
||||
)
|
||||
|
||||
func main() {
|
||||
if len(os.Args) != 4 || os.Args[1] != "table" {
|
||||
log.Fatal(errUsage)
|
||||
}
|
||||
|
||||
err := generate(os.Args[2], os.Args[3])
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
||||
// generate writes the table of the package in dir to out.
|
||||
func generate(dir, out string) error {
|
||||
src, err := table(dir, out)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
return os.WriteFile(out, src, 0o600)
|
||||
}
|
||||
|
||||
// table is the generated Go file holding the docs of the package in dir,
|
||||
// whose sources other than out it reads.
|
||||
func table(dir, out string) ([]byte, error) {
|
||||
paths, err := filepath.Glob(filepath.Join(dir, "*.go"))
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
outAbs, err := filepath.Abs(out)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
// The previous output is no input: a conflicted or stale one must not
|
||||
// stop its own regeneration.
|
||||
paths = slices.DeleteFunc(paths, func(p string) bool {
|
||||
abs, _ := filepath.Abs(p)
|
||||
|
||||
return strings.HasSuffix(p, "_test.go") || abs == outAbs
|
||||
})
|
||||
|
||||
fields, values, err := extractDocs(paths...)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
var b bytes.Buffer
|
||||
|
||||
b.WriteString("// Code generated by tools/configgen from hscontrol/types/config.go; DO NOT EDIT.\n\npackage types\n")
|
||||
writeMap(&b, "configFieldDocs", fields)
|
||||
writeMap(&b, "configValueDocs", values)
|
||||
|
||||
return format.Source(b.Bytes())
|
||||
}
|
||||
|
||||
func writeMap(b *bytes.Buffer, name string, m map[string]string) {
|
||||
fmt.Fprintf(b, "\nvar %s = map[string]string{\n", name)
|
||||
|
||||
for _, k := range slices.Sorted(maps.Keys(m)) {
|
||||
fmt.Fprintf(b, "%q: %q,\n", k, m[k])
|
||||
}
|
||||
|
||||
b.WriteString("}\n")
|
||||
}
|
||||
|
||||
// extractDocs reads the docs of every struct field with a koanf tag other
|
||||
// than "-", keyed "<Type>.<Field>", and of every documented constant of a
|
||||
// type with an Allowed method, keyed "<Type>=<value>".
|
||||
func extractDocs(paths ...string) (map[string]string, map[string]string, error) {
|
||||
fset := token.NewFileSet()
|
||||
|
||||
var decls []*ast.GenDecl
|
||||
|
||||
enums := map[string]bool{}
|
||||
|
||||
for _, p := range paths {
|
||||
f, err := parser.ParseFile(fset, p, nil, parser.ParseComments)
|
||||
if err != nil {
|
||||
return nil, nil, err
|
||||
}
|
||||
|
||||
for _, d := range f.Decls {
|
||||
switch d := d.(type) {
|
||||
case *ast.GenDecl:
|
||||
decls = append(decls, d)
|
||||
case *ast.FuncDecl:
|
||||
if d.Name.Name == "Allowed" && d.Recv != nil {
|
||||
enums[typeName(d.Recv.List[0].Type)] = true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fields := map[string]string{}
|
||||
values := map[string]string{}
|
||||
|
||||
for _, d := range decls {
|
||||
for _, s := range d.Specs {
|
||||
switch s := s.(type) {
|
||||
case *ast.TypeSpec:
|
||||
st, ok := s.Type.(*ast.StructType)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
|
||||
for _, f := range st.Fields.List {
|
||||
if !hasKoanfKey(f) {
|
||||
continue
|
||||
}
|
||||
|
||||
for _, n := range f.Names {
|
||||
key := s.Name.Name + "." + n.Name
|
||||
|
||||
text, err := docText(f.Doc, n.Name)
|
||||
if err != nil {
|
||||
return nil, nil, fmt.Errorf("%s: %s: %w", fset.Position(n.Pos()), key, err)
|
||||
}
|
||||
|
||||
fields[key] = text
|
||||
}
|
||||
}
|
||||
case *ast.ValueSpec:
|
||||
doc := s.Doc
|
||||
if doc == nil && !d.Lparen.IsValid() {
|
||||
doc = d.Doc
|
||||
}
|
||||
|
||||
if d.Tok != token.CONST || doc == nil {
|
||||
continue
|
||||
}
|
||||
|
||||
for i, n := range s.Names {
|
||||
typ := typeName(s.Type)
|
||||
|
||||
var val ast.Expr
|
||||
if i < len(s.Values) {
|
||||
val = ast.Unparen(s.Values[i])
|
||||
}
|
||||
|
||||
if call, ok := val.(*ast.CallExpr); ok && typ == "" {
|
||||
typ = typeName(call.Fun)
|
||||
}
|
||||
|
||||
if !enums[typ] {
|
||||
continue
|
||||
}
|
||||
|
||||
// Only a typed literal is read; any other form fails
|
||||
// rather than drop the value's doc.
|
||||
lit, ok := val.(*ast.BasicLit)
|
||||
if s.Type == nil || !ok || lit.Kind != token.STRING {
|
||||
return nil, nil, fmt.Errorf("%s: constant %s: %w", fset.Position(n.Pos()), n.Name, errEnumValue)
|
||||
}
|
||||
|
||||
v, err := strconv.Unquote(lit.Value)
|
||||
if err != nil {
|
||||
return nil, nil, err
|
||||
}
|
||||
|
||||
text, err := docText(doc, n.Name)
|
||||
if err != nil {
|
||||
return nil, nil, fmt.Errorf("%s: constant %s: %w", fset.Position(n.Pos()), n.Name, err)
|
||||
}
|
||||
|
||||
values[typ+"="+v] = text
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return fields, values, nil
|
||||
}
|
||||
|
||||
// typeName is the name of a type expression T or *T, or "".
|
||||
func typeName(e ast.Expr) string {
|
||||
if s, ok := ast.Unparen(e).(*ast.StarExpr); ok {
|
||||
e = s.X
|
||||
}
|
||||
|
||||
if id, ok := ast.Unparen(e).(*ast.Ident); ok {
|
||||
return id.Name
|
||||
}
|
||||
|
||||
return ""
|
||||
}
|
||||
|
||||
func hasKoanfKey(f *ast.Field) bool {
|
||||
if f.Tag == nil {
|
||||
return false
|
||||
}
|
||||
|
||||
tag, err := strconv.Unquote(f.Tag.Value)
|
||||
if err != nil {
|
||||
return false
|
||||
}
|
||||
|
||||
key := reflect.StructTag(tag).Get("koanf")
|
||||
|
||||
return key != "" && key != "-"
|
||||
}
|
||||
|
||||
// docText is a doc comment as paragraphs joined by a blank line, without
|
||||
// a leading Go name and its "is" or "are": "Addr is the host:port" becomes
|
||||
// "The host:port". A prose paragraph is put on one line; one with an
|
||||
// indented line, a list or code, keeps its lines.
|
||||
func docText(doc *ast.CommentGroup, name string) (string, error) {
|
||||
paras := strings.Split(strings.TrimSuffix(doc.Text(), "\n"), "\n\n")
|
||||
for i, p := range paras {
|
||||
lines := strings.Split(p, "\n")
|
||||
if !slices.ContainsFunc(lines, func(l string) bool { return strings.HasPrefix(l, " ") || strings.HasPrefix(l, "\t") }) {
|
||||
paras[i] = strings.Join(lines, " ")
|
||||
}
|
||||
}
|
||||
|
||||
// Only the opening prose paragraph can start with the name; the strip
|
||||
// never crosses into a list or code block below it.
|
||||
rest, ok := cutWord(paras[0], name)
|
||||
if ok {
|
||||
if r, ok := cutWord(rest, "is"); ok {
|
||||
rest = r
|
||||
} else if r, ok := cutWord(rest, "are"); ok {
|
||||
rest = r
|
||||
}
|
||||
|
||||
if rest == "" {
|
||||
return "", errNameOnly
|
||||
}
|
||||
|
||||
r, size := utf8.DecodeRuneInString(rest)
|
||||
paras[0] = string(unicode.ToUpper(r)) + rest[size:]
|
||||
}
|
||||
|
||||
return strings.Join(paras, "\n\n"), nil
|
||||
}
|
||||
|
||||
// cutWord cuts the word w and the spaces after it from the start of s.
|
||||
func cutWord(s, w string) (string, bool) {
|
||||
rest, ok := strings.CutPrefix(s, w)
|
||||
if !ok || rest != "" && rest[0] != ' ' {
|
||||
return s, false
|
||||
}
|
||||
|
||||
return strings.TrimLeft(rest, " "), true
|
||||
}
|
||||
@@ -0,0 +1,163 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
|
||||
"github.com/google/go-cmp/cmp"
|
||||
"github.com/stretchr/testify/require"
|
||||
)
|
||||
|
||||
func TestExtractDocs(t *testing.T) {
|
||||
fields, values, err := extractDocs("testdata/fixture.go.txt")
|
||||
require.NoError(t, err)
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
got map[string]string
|
||||
want map[string]string
|
||||
}{
|
||||
{
|
||||
name: "fields",
|
||||
got: fields,
|
||||
want: map[string]string{
|
||||
"Server.Addr": "The host:port the server listens on.",
|
||||
"Server.Commands": "Run in order:\n\n\tfirst command\n\tsecond command",
|
||||
"Server.Enabled": "Lets nodes connect.",
|
||||
"Server.Notes": "Two paragraphs, still the first.\n\nThe second paragraph.",
|
||||
"Server.Choices": "Listed:\n\n - first choice\n - second choice\n\nRun:\n\n\tfirst command\n\t indented more",
|
||||
"Server.Retries": "How often to retry; Retries is not the first word.",
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "values",
|
||||
got: values,
|
||||
want: map[string]string{
|
||||
"Mode=fast": "The quick path.",
|
||||
"Mode=slow": "Takes its time.",
|
||||
"Mode=paren": "Has its type in parentheses.",
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
if diff := cmp.Diff(tt.want, tt.got); diff != "" {
|
||||
t.Errorf("(-want +got):\n%s", diff)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestExtractDocsErrors(t *testing.T) {
|
||||
const enum = "package fixture\n\ntype Mode string\n\nfunc (Mode) Allowed() []string { return nil }\n\n"
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
src string
|
||||
wantErr string
|
||||
}{
|
||||
{
|
||||
name: "enum value is an expression",
|
||||
src: enum + "const (\n\t// ModeSlow is slow.\n\tModeSlow Mode = \"sl\" + \"ow\"\n)\n",
|
||||
wantErr: "constant ModeSlow: value must be a string literal with an explicit type",
|
||||
},
|
||||
{
|
||||
name: "enum type is inferred",
|
||||
src: enum + "const (\n\t// ModeAlias is an alias.\n\tModeAlias = Mode(\"alias\")\n)\n",
|
||||
wantErr: "constant ModeAlias: value must be a string literal with an explicit type",
|
||||
},
|
||||
{
|
||||
name: "enum conversion in parentheses",
|
||||
src: enum + "const (\n\t// ModeParen is in parentheses.\n\tModeParen = (Mode(\"paren\"))\n)\n",
|
||||
wantErr: "constant ModeParen: value must be a string literal with an explicit type",
|
||||
},
|
||||
{
|
||||
name: "opening paragraph is only the Go name",
|
||||
src: "package fixture\n\ntype Server struct {\n\t// Choices are\n\t//\n\t//\tfirst command\n\t//\tsecond command\n\tChoices string `koanf:\"choices\"`\n}\n",
|
||||
wantErr: "Server.Choices: doc comment says nothing after the Go name",
|
||||
},
|
||||
{
|
||||
name: "doc is only the Go name",
|
||||
src: "package fixture\n\ntype Server struct {\n\t// Addr is\n\tAddr string `koanf:\"addr\"`\n}\n",
|
||||
wantErr: "Server.Addr: doc comment says nothing after the Go name",
|
||||
},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
path := filepath.Join(t.TempDir(), "fixture.go")
|
||||
require.NoError(t, os.WriteFile(path, []byte(tt.src), 0o600))
|
||||
|
||||
_, _, err := extractDocs(path)
|
||||
require.ErrorContains(t, err, tt.wantErr)
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// TestGenerate: the output file is not an input, so a conflicted or
|
||||
// deleted table regenerates; a broken source file still fails.
|
||||
func TestGenerate(t *testing.T) {
|
||||
fixture, err := os.ReadFile("testdata/fixture.go.txt")
|
||||
require.NoError(t, err)
|
||||
|
||||
clean := t.TempDir()
|
||||
require.NoError(t, os.WriteFile(filepath.Join(clean, "fixture.go"), fixture, 0o600))
|
||||
|
||||
want, err := table(clean, filepath.Join(clean, "docs_generated.go"))
|
||||
require.NoError(t, err)
|
||||
|
||||
const conflicted = "<<<<<<< HEAD\npackage types\n=======\n>>>>>>> other\n"
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
files map[string]string // besides fixture.go
|
||||
wantErr string
|
||||
}{
|
||||
{name: "deleted output"},
|
||||
{name: "conflicted output", files: map[string]string{"docs_generated.go": conflicted}},
|
||||
{name: "conflicted source", files: map[string]string{"other.go": conflicted}, wantErr: "other.go"},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
require.NoError(t, os.WriteFile(filepath.Join(dir, "fixture.go"), fixture, 0o600))
|
||||
|
||||
for name, src := range tt.files {
|
||||
require.NoError(t, os.WriteFile(filepath.Join(dir, name), []byte(src), 0o600))
|
||||
}
|
||||
|
||||
out := filepath.Join(dir, "docs_generated.go")
|
||||
|
||||
err := generate(dir, out)
|
||||
if tt.wantErr != "" {
|
||||
require.ErrorContains(t, err, tt.wantErr)
|
||||
|
||||
return
|
||||
}
|
||||
|
||||
require.NoError(t, err)
|
||||
|
||||
got, err := os.ReadFile(out)
|
||||
require.NoError(t, err)
|
||||
|
||||
if diff := cmp.Diff(string(want), string(got)); diff != "" {
|
||||
t.Errorf("(-want +got):\n%s", diff)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestTableFresh(t *testing.T) {
|
||||
got, err := table("../../hscontrol/types", "../../hscontrol/types/config_docs_generated.go")
|
||||
require.NoError(t, err)
|
||||
|
||||
want, err := os.ReadFile("../../hscontrol/types/config_docs_generated.go")
|
||||
require.NoError(t, err)
|
||||
|
||||
if diff := cmp.Diff(string(want), string(got)); diff != "" {
|
||||
t.Errorf("hscontrol/types/config_docs_generated.go is stale, run go generate ./hscontrol/types/ (-committed +extracted):\n%s", diff)
|
||||
}
|
||||
}
|
||||
+70
@@ -0,0 +1,70 @@
|
||||
package fixture
|
||||
|
||||
// Mode has an Allowed method, so its documented constants are values.
|
||||
type Mode string
|
||||
|
||||
func (Mode) Allowed() []string { return []string{string(ModeFast), string(ModeSlow)} }
|
||||
|
||||
const (
|
||||
// ModeFast is the quick path.
|
||||
ModeFast Mode = "fast"
|
||||
|
||||
// ModeSlow takes its time.
|
||||
ModeSlow Mode = "slow"
|
||||
|
||||
ModeOff Mode = "off"
|
||||
|
||||
// ModeParen has its type in parentheses.
|
||||
ModeParen (Mode) = ("paren")
|
||||
)
|
||||
|
||||
// Other has no Allowed method.
|
||||
type Other string
|
||||
|
||||
const (
|
||||
// OtherValue is not a value of an enum.
|
||||
OtherValue Other = "value"
|
||||
|
||||
// OtherConverted is not a value of an enum either.
|
||||
OtherConverted = Other("converted")
|
||||
)
|
||||
|
||||
type Server struct {
|
||||
// Addr is the host:port the server listens on.
|
||||
Addr string `koanf:"addr"`
|
||||
|
||||
// Enabled lets nodes connect.
|
||||
Enabled bool `koanf:"enabled"`
|
||||
|
||||
// Notes are two paragraphs,
|
||||
// still the first.
|
||||
//
|
||||
// The second paragraph.
|
||||
Notes []string `koanf:"notes"`
|
||||
|
||||
// Choices are listed:
|
||||
//
|
||||
// - first choice
|
||||
// - second choice
|
||||
//
|
||||
// Run:
|
||||
//
|
||||
// first command
|
||||
// indented more
|
||||
Choices string `koanf:"choices"`
|
||||
|
||||
// Commands are run in order:
|
||||
//
|
||||
// first command
|
||||
// second command
|
||||
Commands []string `koanf:"commands"`
|
||||
|
||||
// How often to retry; Retries is not the first word.
|
||||
Retries int `koanf:"retries"`
|
||||
|
||||
// Untagged has no koanf tag.
|
||||
Untagged string
|
||||
|
||||
// Skipped is tagged out.
|
||||
Skipped string `koanf:"-"`
|
||||
}
|
||||
Reference in new issue
Block a user