From 2aab876be845907a95c1eebd27057bef41039381 Mon Sep 17 00:00:00 2001 From: Kristoffer Dalby Date: Sun, 8 Nov 2026 12:46:46 +0000 Subject: [PATCH] types: generate a table of config field docs Updates #1926 --- hscontrol/types/common.go | 11 +- hscontrol/types/config.go | 381 ++++++++++++++--------- hscontrol/types/config_docs_generated.go | 150 +++++++++ hscontrol/types/config_fields.go | 52 +++- hscontrol/types/config_fields_test.go | 305 ++++++++++++++++++ hscontrol/types/config_values.go | 2 +- hscontrol/types/const.go | 21 +- tools/bump/generate.go | 15 +- tools/configgen/main.go | 277 ++++++++++++++++ tools/configgen/main_test.go | 163 ++++++++++ tools/configgen/testdata/fixture.go.txt | 70 +++++ 11 files changed, 1260 insertions(+), 187 deletions(-) create mode 100644 hscontrol/types/config_docs_generated.go create mode 100644 tools/configgen/main.go create mode 100644 tools/configgen/main_test.go create mode 100644 tools/configgen/testdata/fixture.go.txt diff --git a/hscontrol/types/common.go b/hscontrol/types/common.go index cb28294ef..585829da8 100644 --- a/hscontrol/types/common.go +++ b/hscontrol/types/common.go @@ -16,9 +16,14 @@ import ( ) const ( - SelfUpdateIdentifier = "self-update" - DatabasePostgres DatabaseType = "postgres" - DatabaseSqlite DatabaseType = "sqlite3" + SelfUpdateIdentifier = "self-update" + + // DatabasePostgres is PostgreSQL, at `database.postgres.host`. + DatabasePostgres DatabaseType = "postgres" + // DatabaseSqlite is the same as `sqlite`. + DatabaseSqlite DatabaseType = "sqlite3" + // DatabaseSqliteShort is SQLite, in the file `database.sqlite.path`. + DatabaseSqliteShort DatabaseType = "sqlite" ) // Common errors. diff --git a/hscontrol/types/config.go b/hscontrol/types/config.go index 9a8c89c72..d8a558be3 100644 --- a/hscontrol/types/config.go +++ b/hscontrol/types/config.go @@ -1,5 +1,7 @@ package types +//go:generate go run ../../tools/configgen table . config_docs_generated.go + import ( "cmp" "encoding/json" @@ -25,8 +27,12 @@ import ( ) const ( + // PKCEMethodPlain sends the verifier itself as the challenge. Use it + // only with a provider that does not support `S256`. PKCEMethodPlain PKCEMethod = "plain" - PKCEMethodS256 PKCEMethod = "S256" + // PKCEMethodS256 sends the base64url SHA-256 of the verifier as the + // challenge. Recommended. + PKCEMethodS256 PKCEMethod = "S256" providerKey = "dns.challenge.provider" ) @@ -51,8 +57,11 @@ func DefaultChallengeResolvers() []string { type IPAllocationStrategy string //nolint:recvcheck // UnmarshalText needs a pointer; the rest read the value const ( + // IPAllocationStrategySequential takes the next free address after + // the last one handed out, and wraps around to reuse freed addresses. IPAllocationStrategySequential IPAllocationStrategy = "sequential" - IPAllocationStrategyRandom IPAllocationStrategy = "random" + // IPAllocationStrategyRandom picks a free address at random. + IPAllocationStrategyRandom IPAllocationStrategy = "random" ) // PolicyMode is where the policy is stored. "" decodes without error to the @@ -60,7 +69,11 @@ const ( type PolicyMode string //nolint:recvcheck // UnmarshalText needs a pointer; the rest read the value const ( - PolicyModeDB PolicyMode = "database" + // PolicyModeDB keeps the policy in the database, set with `headscale + // policy set` or the API. `policy.path` is not read. + PolicyModeDB PolicyMode = "database" + // PolicyModeFile reads the policy from `policy.path`. Send headscale + // `SIGHUP` to reload it after an edit. PolicyModeFile PolicyMode = "file" ) @@ -80,18 +93,21 @@ type EphemeralConfig struct { type HARouteConfig struct { // ProbeInterval is how often HA subnet routers are probed; a positive // interval must be at least 2s. Zero or negative disables probing, - // and with it the [HARouteConfig.ProbeTimeout] rules. + // and with it the `node.routes.ha.probe_timeout` rules. ProbeInterval time.Duration `koanf:"probe_interval"` // ProbeTimeout is the maximum time to wait for a probe response // before declaring a node unhealthy; at least 1s and less than - // [HARouteConfig.ProbeInterval]. + // `node.routes.ha.probe_interval`. ProbeTimeout time.Duration `koanf:"probe_timeout"` } // RouteConfig contains configuration for route behaviour. type RouteConfig struct { - // HA configures health probing of HA subnet routers. + // HA is health probing of HA subnet routers. When two or more nodes + // advertise the same route, headscale pings each over Noise and moves + // the route away from one that does not answer in time. See + // [High availability](https://headscale.net/stable/ref/routes/#high-availability). HA HARouteConfig `koanf:"ha"` } @@ -108,15 +124,18 @@ type PreAuthKeysConfig struct { type NodeConfig struct { // Expiry is the key expiry given to a non-tagged node that registers // without one, whatever the method (auth key, CLI, web, OIDC). An - // expiry the client asks for, oidc.use_expiry_from_token and an + // expiry the client asks for, `oidc.use_expiry_from_token` and an // admin's `headscale nodes expire` still apply. Tagged nodes never get // this default. Zero or negative disables the default. Expiry time.Duration `koanf:"expiry"` - // Ephemeral contains configuration for ephemeral node lifecycle. + // Ephemeral covers ephemeral nodes, which register with an ephemeral + // auth key and are deleted once they have been offline for + // `node.ephemeral.inactivity_timeout`. Ephemeral EphemeralConfig `koanf:"ephemeral"` - // Routes contains configuration for route behaviour. + // Routes covers the routes nodes advertise. See + // [Routes](https://headscale.net/stable/ref/routes/). Routes RouteConfig `koanf:"routes"` } @@ -124,86 +143,111 @@ type NodeConfig struct { // file; koanf tags name the keys. A duration needs a unit (30s, 3h, 90d), // except 0. type Config struct { //nolint:recvcheck // MarshalJSON reads a value, so a Config value is redacted too - // ServerURL is the URL clients connect to, with its http:// or https:// - // scheme, e.g. https://headscale.example.com:443. A trailing slash is - // trimmed on load. Its host must not be dns.base_domain or a name - // below it. + // ServerURL is the URL clients connect to, with its `http://` or + // `https://` scheme, e.g. `https://headscale.example.com:443`. A + // trailing slash is trimmed on load. Its host must not be + // `dns.base_domain` or a name below it. ServerURL string `koanf:"server_url"` // Addr is the host:port the server listens on for clients, the API and - // the web pages, with TLS when [Config.TLS] sets it up. + // the web pages. It serves HTTPS when `tls.cert_path` or + // `tls.acme.hostname` is set, plain HTTP otherwise. Addr ListenAddr `koanf:"listen_addr"` - // MetricsAddr is the host:port serving /metrics and /debug; keep it - // private. Empty disables this listener. + // MetricsAddr is the host:port serving `/metrics` and `/debug`; keep + // it private. Empty disables this listener. MetricsAddr ListenAddr `koanf:"metrics_listen_addr"` // UnixSocket is where the server serves the API without - // authentication, for the CLI on the same host; the CLI connects to it - // when cli.address is empty. + // authentication, for the CLI on the same host. The CLI connects to it + // when `cli.address` is empty. UnixSocket string `koanf:"unix_socket"` - // UnixSocketPermission is the file mode of [Config.UnixSocket], in - // quoted octal ("0770"): unquoted, YAML reads 0770 as the number 504. + // UnixSocketPermission is the file mode of `unix_socket`, in quoted + // octal (`"0770"`): unquoted, YAML reads `0770` as the number 504. UnixSocketPermission FileMode `koanf:"unix_socket_permission"` // TrustedProxies are the CIDRs of reverse proxies whose - // True-Client-IP, X-Real-IP and X-Forwarded-For headers are honoured. - // Empty ignores those headers. Set without a proxy in front, clients - // can spoof their source IP in logs and the v2 API. + // `True-Client-IP`, `X-Real-IP` and `X-Forwarded-For` headers are + // honoured. Empty ignores those headers. Set without a proxy in front, + // clients can spoof their source IP in logs and the v2 API. TrustedProxies []netip.Prefix `koanf:"trusted_proxies"` // DisableUpdateCheck skips the check for a newer headscale release // that commands make at start. DisableUpdateCheck bool `koanf:"disable_check_updates"` - // Noise configures the Noise (TS2021) protocol clients connect over. + // Noise is the Noise protocol (TS2021) clients connect over. Noise NoiseConfig `koanf:"noise"` - // Prefixes are the ranges node IPs are allocated from. + // Prefixes are the IP ranges node addresses are allocated from. Set at + // least one of `prefixes.v4` and `prefixes.v6`. Use the Tailscale + // ranges, `100.64.0.0/10` and `fd7a:115c:a1e0::/48`, or ranges inside + // them: the client assumes them, and other ranges are unsupported. Prefixes PrefixesConfig `koanf:"prefixes"` - // Policy is where the access control policy is stored. + // Policy is where the access control policy is kept: in a file + // headscale reads, or in the database. See + // [Policy](https://headscale.net/stable/ref/policy/). Policy PolicyConfig `koanf:"policy"` - // Log configures headscale's own log output. + // Log is headscale's own log output. See + // [Debugging](https://headscale.net/stable/ref/debug/#application-logging). Log LogConfig `koanf:"log"` - // Node configures node expiry, ephemeral nodes and HA routes. + // Node covers node key expiry, ephemeral nodes and subnet routes. Node NodeConfig `koanf:"node"` - // PreAuthKeys configures the cleanup of revoked pre-auth keys. + // PreAuthKeys covers the cleanup of revoked pre-auth keys. See + // [Pre authenticated key](https://headscale.net/stable/ref/registration/#pre-authenticated-key). PreAuthKeys PreAuthKeysConfig `koanf:"preauth_keys"` - // DERP configures the relay servers clients are given, and the - // embedded one. + // DERP is the DERP map: the relay servers clients use when they cannot + // connect directly, from `derp.urls`, `derp.paths` and the embedded + // server in `derp.server`. A region replaces an earlier one with the + // same ID. See [DERP](https://headscale.net/stable/ref/derp/). DERP DERPConfig `koanf:"derp"` - // Database selects and configures the database. + // Database is where headscale stores nodes, users and keys. SQLite is + // recommended; PostgreSQL is supported for legacy deployments only. + // `database.sqlite` is read only for SQLite, `database.postgres` only + // for PostgreSQL. Database DatabaseConfig `koanf:"database"` - // DNSConfig is the DNS configuration sent to clients, and node - // certificates. Clients apply it only with --accept-dns, their default. + // DNSConfig is the DNS configuration sent to clients, MagicDNS + // included, and TLS certificates for nodes. Clients apply it only with + // `--accept-dns`, their default. See + // [DNS](https://headscale.net/stable/ref/dns/). DNSConfig DNSConfig `koanf:"dns"` - // TLS configures HTTPS on [Config.Addr]: a certificate from files or - // from ACME. Unset, the server speaks plain HTTP. + // TLS is headscale's own HTTPS certificate on `listen_addr`: from the + // files `tls.cert_path` and `tls.key_path`, or from ACME in + // `tls.acme`, not both. Without either, the server speaks plain HTTP. + // See [TLS](https://headscale.net/stable/ref/tls/). TLS TLSConfig `koanf:"tls"` - // OIDC configures login through an OpenID Connect provider. It is on - // when oidc.issuer is set. + // OIDC is login through an OpenID Connect provider. Setting + // `oidc.issuer` turns it on and requires `oidc.client_id` and + // `oidc.client_secret`. See + // [OpenID Connect](https://headscale.net/stable/ref/oidc/). OIDC OIDCConfig `koanf:"oidc"` - // LogTail controls whether nodes send their logs to Tailscale. + // LogTail is whether nodes send their logs to Tailscale. LogTail LogTailConfig `koanf:"logtail"` - // Taildrop controls file sharing between nodes. + // Taildrop is Taildrop, Tailscale's file sharing between nodes. Taildrop TaildropConfig `koanf:"taildrop"` - // AutoUpdate sets the tailnet-wide default for client auto-updates. + // AutoUpdate is the tailnet-wide default for client auto-updates. AutoUpdate AutoUpdateConfig `koanf:"auto_update"` - // CLI configures how the headscale CLI reaches the server. + // CLI is how the headscale CLI reaches the server: the local + // `unix_socket` without authentication, or a remote `cli.address` + // with `cli.api_key`. The CLI reads these keys from its own + // configuration, such as `~/.config/headscale/config.yaml`, or from + // `HEADSCALE_CLI_*` variables; the server does not read them, so on + // NixOS they do not belong in `services.headscale.settings`. See + // [Remote control](https://headscale.net/stable/ref/api/#remote-control). CLI CLIConfig `koanf:"cli"` // Tuning holds performance settings that rarely need changing. @@ -221,8 +265,8 @@ type Config struct { //nolint:recvcheck // MarshalJSON reads a value, so a Confi // NoiseConfig is the key of the Noise protocol clients connect over. type NoiseConfig struct { // PrivateKeyPath is the file holding the Noise private key, which - // encrypts traffic between headscale and clients. A missing file is - // created with a new key. Relative to the configuration file. + // encrypts traffic between headscale and clients, relative to the + // configuration file. A missing file is created with a new key. PrivateKeyPath string `koanf:"private_key_path"` } @@ -231,17 +275,15 @@ type NoiseConfig struct { // or subsets of them: the client assumes them, and breaks in subtle ways // outside them. type PrefixesConfig struct { - // V4 is the IPv4 range, e.g. 100.64.0.0/10. Unset gives nodes no IPv4 - // address. + // V4 is the IPv4 range, e.g. `100.64.0.0/10`. Empty gives nodes no + // IPv4 address. V4 *netip.Prefix `koanf:"v4"` - // V6 is the IPv6 range, e.g. fd7a:115c:a1e0::/48. Unset gives nodes no - // IPv6 address. + // V6 is the IPv6 range, e.g. `fd7a:115c:a1e0::/48`. Empty gives nodes + // no IPv6 address. V6 *netip.Prefix `koanf:"v6"` - // Allocation is how a new node's IPs are picked: sequential takes the - // next free address after the last one handed out, random picks a free - // one at random. + // Allocation is how a new node's addresses are picked. Allocation IPAllocationStrategy `koanf:"allocation"` } @@ -257,42 +299,49 @@ type liveDNS struct { // DNSConfig is the DNS configuration clients get. To keep headscale out of // clients' DNS, set every field to its empty value. type DNSConfig struct { - // MagicDNS gives each node the name hostname.base_domain, resolved by - // the client. It requires [DNSConfig.BaseDomain]. + // MagicDNS gives each node a name below `dns.base_domain`, e.g. + // `laptop.example.com`, resolved by the client. It requires + // `dns.base_domain`. MagicDNS bool `koanf:"magic_dns"` // BaseDomain is the domain MagicDNS names live under, without a - // trailing dot, e.g. example.com. server_url's host must not be this - // domain or a name below it: clients take the domain over. + // trailing dot, e.g. `example.com`. The host of `server_url` must not + // be this domain or a name below it: clients take the domain over. BaseDomain string `koanf:"base_domain"` - // OverrideLocalDNS makes clients use [Nameservers.Global] instead of - // their local DNS settings, which then requires at least one global + // OverrideLocalDNS makes clients use `dns.nameservers.global` instead + // of their local DNS settings, which then requires at least one global // nameserver. False sends them only as fallback resolvers. OverrideLocalDNS bool `koanf:"override_local_dns"` - // Nameservers are the upstream DNS servers sent to clients. + // Nameservers are the upstream DNS servers sent to clients. An entry + // that is neither an IP address nor a URL is skipped with a warning. Nameservers Nameservers `koanf:"nameservers"` // SearchDomains are DNS search domains sent to clients. With MagicDNS, - // base_domain comes first. + // `dns.base_domain` comes first. SearchDomains []string `koanf:"search_domains"` - // ExtraRecords are DNS records served to clients, each with a name, - // type and value. Clients support A and AAAA. Mutually exclusive with - // [DNSConfig.ExtraRecordsPath]. + // ExtraRecords are DNS records served to clients, each with a `name`, + // `type` and `value`. Clients support `A` and `AAAA`. Mutually + // exclusive with `dns.extra_records_path`. See + // [Setting extra DNS records](https://headscale.net/stable/ref/dns/#setting-extra-dns-records). ExtraRecords []tailcfg.DNSRecord `koanf:"extra_records"` // ExtraRecordsPath is a file of extra records, reloaded when it - // changes. The extension picks the format: .json, .hujson, .yaml or - // .yml. Mutually exclusive with [DNSConfig.ExtraRecords]. + // changes. The extension picks the format: `.json`, `.hujson`, `.yaml` + // or `.yml`. Mutually exclusive with `dns.extra_records`. ExtraRecordsPath string `koanf:"extra_records_path"` // Certificates lets nodes get TLS certificates for their MagicDNS - // names. + // names with `tailscale cert`. The node runs ACME itself; headscale + // publishes its DNS-01 challenge through `dns.challenge.provider`. Certificates CertificatesConfig `koanf:"certificates"` - // Challenge is the DNS provider answering ACME DNS-01 challenges. + // Challenge is the DNS provider answering ACME DNS-01 challenges, for + // node certificates and for headscale's own certificate when + // `tls.acme.challenge_type` is `DNS-01`. See + // [DNS-01 challenge provider](https://headscale.net/stable/ref/dns/#dns-01-challenge-provider). Challenge DNSChallengeConfig `koanf:"challenge"` } @@ -300,13 +349,14 @@ type DNSConfig struct { // name with `tailscale cert`. The node runs ACME itself; headscale // publishes its DNS-01 challenge through [DNSChallengeConfig]. type CertificatesConfig struct { - // Enabled lets nodes run `tailscale cert`. It requires MagicDNS, a - // lowercase base_domain and dns.challenge.provider. + // Enabled lets nodes run `tailscale cert`. It requires + // `dns.magic_dns`, a lowercase `dns.base_domain` and + // `dns.challenge.provider`. Enabled bool `koanf:"enabled"` // Zone is the public DNS zone challenge records are written to, when - // base_domain sits below the zone apex. Empty uses base_domain. See - // [DNSConfig.CertificateZone]. + // `dns.base_domain` sits below the zone apex. It must contain + // `dns.base_domain`. Empty uses `dns.base_domain`. Zone string `koanf:"zone"` } @@ -323,15 +373,22 @@ type DNSChallengeConfig struct { // show up on every authoritative nameserver. Zero skips the check. PropagationTimeout time.Duration `koanf:"propagation_timeout"` - // Resolvers find the zone's nameservers, each an IP or host with an - // optional port (53 if omitted). Empty uses public resolvers, not the - // system's. + // Resolvers are the servers asked for the zone's nameservers, each an + // IP or host with an optional port (53 if omitted). Empty uses the + // default public resolvers. The system resolver is never used: on a + // host running MagicDNS it answers for `dns.base_domain` itself. Resolvers []string `koanf:"resolvers"` - // ProviderSettings is dns.challenge.provider: name selects the - // provider, the other keys are its settings, lowercased on load at - // every depth. A string setting may be "file:" to read it from - // a file. Never serialised: its settings are credentials. + // ProviderSettings is the DNS provider that writes challenge records: + // `name` selects it, the other keys are its settings. Keys are + // lowercased on load, at every depth; two that differ only in case + // are an error. A string setting may be `file:` to read it from + // a file. `headscale generate config --running` and `/debug/config` + // show `name` and `file:` references; every other setting is + // ``, as any may be a credential. See + // [DNS-01 challenge provider](https://headscale.net/stable/ref/dns/#dns-01-challenge-provider) + // to set a provider up, acme-dns included, and to set it from + // environment variables. ProviderSettings map[string]any `json:"-" koanf:"provider"` // Provider is a DNS provider set from Go, by an embedder or a test; it @@ -399,30 +456,32 @@ func (c DNSChallengeConfig) ResolverAddrs() []string { // Nameservers are the upstream DNS servers sent to clients. An entry that // is neither an IP address nor a URL is skipped with a warning. type Nameservers struct { - // Global are the nameservers for names Split does not cover: IP - // addresses, or DNS-over-HTTPS URLs such as - // https://dns.nextdns.io/. + // Global are the nameservers for names `dns.nameservers.split` does not + // cover: IP addresses, or DNS-over-HTTPS URLs such as + // `https://dns.nextdns.io/`. Global []string `koanf:"global"` // Split maps a domain to the nameservers that answer for it (split - // DNS). Domains are lowercased on load. + // DNS). Domains are lowercased on load; two that differ only in case + // are an error. Split map[string][]string `koanf:"split"` } // SqliteConfig configures the SQLite database. type SqliteConfig struct { // Path is the database file, relative to the configuration file; - // ":memory:" keeps the database in memory. + // `:memory:` keeps the database in memory. Path string `koanf:"path"` - // WriteAheadLog applies [SqliteConfig.WALAutoCheckPoint] and compacts - // the database (VACUUM) on shutdown. SQLite runs in WAL mode either - // way; false keeps the default checkpoint of 1000 frames. + // WriteAheadLog applies `database.sqlite.wal_autocheckpoint` and + // compacts the database (`VACUUM`) on shutdown. SQLite runs in WAL + // mode either way; false keeps SQLite's default checkpoint of 1000 + // frames. WriteAheadLog bool `koanf:"write_ahead_log"` // WALAutoCheckPoint is the number of WAL frames after which the WAL // is checkpointed automatically; zero disables automatic checkpoints. - // Applied only when write_ahead_log is true. + // Applied only when `database.sqlite.write_ahead_log` is true. WALAutoCheckPoint int `koanf:"wal_autocheckpoint"` } @@ -430,11 +489,12 @@ type SqliteConfig struct { // deployments only. type PostgresConfig struct { // Host is the server's host name or IP, or the directory of its Unix - // socket (a path starting with /). + // socket (a path starting with `/`). Host string `koanf:"host"` - // Port is the server's port, or with a Unix socket directory as Host, - // the port in the socket's file name. Zero uses the driver's default. + // Port is the server's port or, with a Unix socket directory in + // `database.postgres.host`, the port in the socket's file name. Zero + // uses the driver's default. Port int `koanf:"port"` // Name is the database name. @@ -443,13 +503,15 @@ type PostgresConfig struct { // User is the user to connect as. User string `koanf:"user"` - // Pass is the password, or "file:" to read it from a file. Read - // only for PostgreSQL. Never serialised. + // Pass is the password, or `file:` to read it from a file, read + // only when `database.type` is `postgres`. `headscale generate config + // --running` and `/debug/config` show a literal password as + // `` and a `file:` reference as written. Pass Secret `json:"-" koanf:"pass"` - // Ssl is the TLS mode: "true" keeps the driver's default sslmode, - // "false" disables TLS, any other value is passed as sslmode - // (require, verify-full, ...). + // Ssl is the TLS mode: `true` keeps the driver's default `sslmode`, + // `false` disables TLS, any other value is passed as `sslmode` + // (`require`, `verify-full`, ...). Ssl string `koanf:"ssl"` // MaxOpenConnections caps open connections to the database. @@ -525,8 +587,8 @@ type GormConfig struct { // query is logged as a warning. Zero disables the warning. SlowThreshold int `koanf:"slow_threshold"` - // SkipErrRecordNotFound leaves "record not found" errors out of the - // log. + // SkipErrRecordNotFound logs a query that finds no record as an + // ordinary query, not as an error. SkipErrRecordNotFound bool `koanf:"skip_err_record_not_found"` // ParameterizedQueries logs queries without their parameter values. @@ -539,23 +601,28 @@ type DatabaseConfig struct { // supported for legacy deployments only. Type DatabaseType `koanf:"type"` - // Debug logs database queries at log level debug, as - // [DatabaseConfig.Gorm] configures. + // Debug turns on query logging: ordinary queries at log level debug, + // shown only when `log.level` is `debug` or `trace`, slow ones at warn + // and failed ones at error. Off, no query is logged. `database.gorm` + // shapes the query log. See + // [Database logging](https://headscale.net/stable/ref/debug/#database-logging). Debug bool `koanf:"debug"` - // Gorm configures query logging. + // Gorm is query logging, applied only when `database.debug` is true. Gorm GormConfig `koanf:"gorm"` - // Sqlite configures SQLite, used when Type names it. + // Sqlite is SQLite, read only when `database.type` is `sqlite` or + // `sqlite3`. Sqlite SqliteConfig `koanf:"sqlite"` - // Postgres configures PostgreSQL, used when Type is postgres. + // Postgres is PostgreSQL, read only when `database.type` is + // `postgres`. Postgres PostgresConfig `koanf:"postgres"` } // IsSQLite reports whether Type names SQLite, in either spelling. func (d DatabaseConfig) IsSQLite() bool { - return d.Type == DatabaseSqlite || d.Type == "sqlite" + return d.Type == DatabaseSqlite || d.Type == DatabaseSqliteShort } // TLSConfig is headscale's own certificate: from files, or from ACME. The @@ -565,11 +632,12 @@ type TLSConfig struct { // file. Setting it turns TLS on. CertPath string `koanf:"cert_path"` - // KeyPath is the PEM private key file of [TLSConfig.CertPath], - // relative to the configuration file. + // KeyPath is the PEM private key file of `tls.cert_path`, relative to + // the configuration file. KeyPath string `koanf:"key_path"` - // ACME gets the certificate from an ACME CA such as Let's Encrypt. + // ACME gets the certificate from an ACME CA such as Let's Encrypt, + // and renews it. Setting `tls.acme.hostname` turns it on. ACME ACMEConfig `koanf:"acme"` } @@ -579,12 +647,13 @@ type ACMEConfig struct { // turns ACME on. Hostname string `koanf:"hostname"` - // ChallengeType is how the CA verifies the domain. DNS-01 publishes - // the challenge through dns.challenge. + // ChallengeType is how the CA verifies that headscale controls + // `tls.acme.hostname`. ChallengeType ACMEChallenge `koanf:"challenge_type"` // HTTPListen is the host:port serving HTTP-01 challenges; the port - // may be a name, as in ":http" for port 80. + // may be a name, as in `:http` for port 80. Other requests to it are + // redirected to `server_url`. HTTPListen ListenAddr `koanf:"http_listen"` // URL is the CA's ACME directory. Empty uses Let's Encrypt. @@ -604,8 +673,7 @@ type PKCEConfig struct { // Enabled sends a PKCE challenge with each login. Enabled bool `koanf:"enabled"` - // Method is how the code challenge is derived from the verifier: S256 - // (base64url SHA-256, recommended) or plain (the verifier itself). The + // Method is how the code challenge is derived from the verifier. The // verifier is sent as is in the token exchange. Method PKCEMethod `koanf:"method"` } @@ -619,19 +687,21 @@ type OIDCConfig struct { // Issuer is the provider's issuer URL. Setting it turns OIDC on. Issuer HTTPURL `koanf:"issuer"` - // ClientID is the client ID from the provider; required with Issuer. + // ClientID is the client ID from the provider; required when + // `oidc.issuer` is set. ClientID string `koanf:"client_id"` // ClientSecret is the client secret from the provider, or - // "file:" to read it from a file; required with Issuer. Never - // serialised. + // `file:` to read it from a file; required when `oidc.issuer` is + // set. `headscale generate config --running` and `/debug/config` show a + // literal secret as `` and a `file:` reference as written. ClientSecret Secret `json:"-" koanf:"client_secret"` - // Scope are the scopes requested; include "openid". + // Scope are the scopes requested; include `openid`. Scope []string `koanf:"scope"` // ExtraParams are sent as is to the provider's authorization endpoint, - // e.g. domain_hint; names keep their case. + // e.g. `domain_hint`; names keep their case. ExtraParams map[string]string `koanf:"extra_params"` // AllowedDomains admits only users whose email domain is listed. @@ -643,22 +713,24 @@ type OIDCConfig struct { AllowedUsers []string `koanf:"allowed_users"` // AllowedGroups admits only members of at least one listed group, - // from the provider's groups claim: UserInfo first, the ID token as + // from the provider's `groups` claim: UserInfo first, the ID token as // fallback. Empty admits any group. AllowedGroups []string `koanf:"allowed_groups"` // EmailVerifiedRequired trusts an email only when the provider marks - // it verified: an unverified one fails allowed_domains and - // allowed_users and is not copied to the user. Turn it off for a - // provider that does not send email_verified. + // it verified: an unverified one fails `oidc.allowed_domains` and + // `oidc.allowed_users` and is not copied to the user. Turn it off for a + // provider that does not send `email_verified`. EmailVerifiedRequired bool `koanf:"email_verified_required"` // UseExpiryFromToken expires an OIDC-registered node with its token, - // instead of node.expiry. Tokens are often short-lived, forcing + // instead of `node.expiry`. Tokens are often short-lived, forcing // frequent logins. UseExpiryFromToken bool `koanf:"use_expiry_from_token"` - // PKCE configures Proof Key for Code Exchange. + // PKCE is Proof Key for Code Exchange (RFC 7636), which protects the + // authorization code from interception. See + // [Enable PKCE](https://headscale.net/stable/ref/oidc/#enable-pkce-recommended). PKCE PKCEConfig `koanf:"pkce"` } @@ -666,24 +738,26 @@ type OIDCConfig struct { // connection fails. Sources merge in order (DERPMap, URLs, Paths, then the // embedded server); a region replaces an earlier one with the same ID. type DERPConfig struct { - // Server is the embedded DERP server. + // Server is the embedded DERP server, a relay and STUN server run by + // headscale itself. See + // [Enable embedded DERP](https://headscale.net/stable/ref/derp/#enable-embedded-derp). Server DERPServerConfig `koanf:"server"` // URLs are DERP maps in JSON to fetch. One that fails to load is // logged and skipped; startup fails only when no region remains. URLs []HTTPURL `koanf:"urls"` - // Paths are DERP map files. The extension picks the format: .yaml or - // .yml, or Tailscale JSON as .json or .hujson, both accepting comments - // and trailing commas. + // Paths are DERP map files. The extension picks the format: `.yaml` or + // `.yml`, or Tailscale JSON as `.json` or `.hujson`, both accepting + // comments and trailing commas. Paths []string `koanf:"paths"` - // AutoUpdate reloads URLs and Paths every - // [DERPConfig.UpdateFrequency]. + // AutoUpdate reloads `derp.urls` and `derp.paths` every + // `derp.update_frequency`. AutoUpdate bool `koanf:"auto_update_enabled"` - // UpdateFrequency is how often AutoUpdate reloads the DERP map. Zero - // disables reloading. + // UpdateFrequency is how often `derp.auto_update_enabled` reloads the + // DERP map. Zero disables reloading. UpdateFrequency time.Duration `koanf:"update_frequency"` // DERPMap is a DERP map set from Go, by an embedder or a test; it @@ -694,7 +768,7 @@ type DERPConfig struct { // DERPServerConfig is the embedded DERP server. type DERPServerConfig struct { // Enabled runs the embedded DERP server. DERP needs TLS, so - // server_url must be https://. + // `server_url` must be `https://`. Enabled bool `koanf:"enabled"` // RegionID is the embedded server's region ID. It replaces a region @@ -711,13 +785,14 @@ type DERPServerConfig struct { VerifyClients bool `koanf:"verify_clients"` // STUNAddr is the UDP host:port of the STUN server, which helps - // clients with NAT traversal; required with Enabled. + // clients with NAT traversal; required when `derp.server.enabled` is + // true. STUNAddr ListenAddr `koanf:"stun_listen_addr"` // PrivateKeyPath is the file holding the DERP server's private key, - // relative to the configuration file; required with Enabled. A missing - // file is created with a new key. It must differ from - // noise.private_key_path. + // relative to the configuration file; required when + // `derp.server.enabled` is true. A missing file is created with a new + // key. It must differ from `noise.private_key_path`. PrivateKeyPath string `koanf:"private_key_path"` // IPv4 is the server's public IPv4 address, published in the DERP map @@ -729,8 +804,8 @@ type DERPServerConfig struct { IPv6 string `koanf:"ipv6"` // AutomaticallyAddEmbeddedDerpRegion adds the embedded server's region - // to the DERP map. False requires derp.paths, where you write the - // region yourself. + // to the DERP map. When it is false and `derp.server.enabled` is true, + // `derp.paths` is required: write the region there yourself. AutomaticallyAddEmbeddedDerpRegion bool `koanf:"automatically_add_embedded_derp_region"` } @@ -745,7 +820,7 @@ type LogTailConfig struct { // nodes. type TaildropConfig struct { // Enabled gives every node the file-sharing capability. False omits - // it from the baseline; a policy nodeAttrs grant can still give it. + // it from the baseline; a policy `nodeAttrs` grant can still give it. Enabled bool `koanf:"enabled"` } @@ -764,32 +839,31 @@ type AutoUpdateConfig struct { // CLIConfig is how the headscale CLI reaches the server: the local // unix_socket without authentication, or a remote address with an API key. type CLIConfig struct { - // Address is the remote server's host:port or URL; https:// is - // assumed without a scheme. Empty uses unix_socket. + // Address is the remote server's host:port or URL; `https://` is + // assumed without a scheme. Empty uses `unix_socket`. Address string `koanf:"address"` - // APIKey is the API key the CLI sends to a remote Address, or - // "file:" to read it from a file. Read only by the CLI. Never - // serialised. + // APIKey is the API key the CLI sends to `cli.address`, or + // `file:` to read it from a file. Read only by the CLI. APIKey Secret `json:"-" koanf:"api_key"` // Timeout bounds each CLI command's requests to the server. Timeout time.Duration `koanf:"timeout"` - // Insecure skips TLS certificate verification of a remote Address. + // Insecure skips TLS certificate verification of `cli.address`. Insecure bool `koanf:"insecure"` } // PolicyConfig is where the access control policy (ACLs and grants) is // stored. type PolicyConfig struct { - // Path is the HuJSON policy file read in file mode, relative to the - // configuration file. Empty starts without a policy, which allows all - // traffic. + // Path is the HuJSON policy file read when `policy.mode` is `file`, + // relative to the configuration file. Empty starts without a policy, + // which allows all traffic. Path string `koanf:"path"` - // Mode is where the policy is kept: a file headscale reads, or the - // database, edited through the CLI or API. + // Mode is where the policy is kept: in the file `policy.path`, or in + // the database, edited through the CLI or API. Mode PolicyMode `koanf:"mode"` } @@ -821,24 +895,23 @@ type Tuning struct { NodeMapSessionBufferedChanSize int `koanf:"node_mapsession_buffered_chan_size"` // BatcherWorkers is the number of workers building map updates for - // connected clients. Zero uses three quarters of the CPU cores, at - // least one. See [Tuning.BatcherWorkerCount]. + // connected clients. Zero picks the number from the CPU count. BatcherWorkers int `koanf:"batcher_workers"` // RegisterCacheExpiration is how long a pending registration waits - // to be completed. Zero uses the built-in default. + // to be completed. Zero uses the default. RegisterCacheExpiration time.Duration `koanf:"register_cache_expiration"` // RegisterCacheMaxEntries bounds pending registrations. At capacity, // new registrations are refused without evicting pending ones; SSH - // checks have a small reserve beyond it. Zero uses the built-in - // default. + // checks have a small reserve beyond it. Zero uses the default. See + // [Pending authentication limits](https://headscale.net/stable/ref/registration/#pending-authentication-limits). RegisterCacheMaxEntries int `koanf:"register_cache_max_entries"` // NodeStoreBatchSize is how many node changes are batched before the // in-memory node state, peer relationships included, is rebuilt; must // be positive. Higher values save CPU on bulk changes but delay each - // change until its batch is full or [Tuning.NodeStoreBatchTimeout] + // change until its batch is full or `tuning.node_store_batch_timeout` // passes. NodeStoreBatchSize int `koanf:"node_store_batch_size"` diff --git a/hscontrol/types/config_docs_generated.go b/hscontrol/types/config_docs_generated.go new file mode 100644 index 000000000..f9db7df41 --- /dev/null +++ b/hscontrol/types/config_docs_generated.go @@ -0,0 +1,150 @@ +// Code generated by tools/configgen from hscontrol/types/config.go; DO NOT EDIT. + +package types + +var configFieldDocs = map[string]string{ + "ACMEConfig.CacheDir": "Where certificates and ACME account data are stored, relative to the configuration file.", + "ACMEConfig.ChallengeType": "How the CA verifies that headscale controls `tls.acme.hostname`.", + "ACMEConfig.Email": "The contact address registered with the CA.", + "ACMEConfig.HTTPListen": "The host:port serving HTTP-01 challenges; the port may be a name, as in `:http` for port 80. Other requests to it are redirected to `server_url`.", + "ACMEConfig.Hostname": "The domain to request a certificate for. Setting it turns ACME on.", + "ACMEConfig.URL": "The CA's ACME directory. Empty uses Let's Encrypt.", + "AutoUpdateConfig.Enabled": "Makes auto-update the default for clients that have not chosen locally. Clients store the default they first see, so a later change reaches only new clients.", + "CLIConfig.APIKey": "The API key the CLI sends to `cli.address`, or `file:` to read it from a file. Read only by the CLI.", + "CLIConfig.Address": "The remote server's host:port or URL; `https://` is assumed without a scheme. Empty uses `unix_socket`.", + "CLIConfig.Insecure": "Skips TLS certificate verification of `cli.address`.", + "CLIConfig.Timeout": "Bounds each CLI command's requests to the server.", + "CertificatesConfig.Enabled": "Lets nodes run `tailscale cert`. It requires `dns.magic_dns`, a lowercase `dns.base_domain` and `dns.challenge.provider`.", + "CertificatesConfig.Zone": "The public DNS zone challenge records are written to, when `dns.base_domain` sits below the zone apex. It must contain `dns.base_domain`. Empty uses `dns.base_domain`.", + "Config.Addr": "The host:port the server listens on for clients, the API and the web pages. It serves HTTPS when `tls.cert_path` or `tls.acme.hostname` is set, plain HTTP otherwise.", + "Config.AutoUpdate": "The tailnet-wide default for client auto-updates.", + "Config.CLI": "How the headscale CLI reaches the server: the local `unix_socket` without authentication, or a remote `cli.address` with `cli.api_key`. The CLI reads these keys from its own configuration, such as `~/.config/headscale/config.yaml`, or from `HEADSCALE_CLI_*` variables; the server does not read them, so on NixOS they do not belong in `services.headscale.settings`. See [Remote control](https://headscale.net/stable/ref/api/#remote-control).", + "Config.DERP": "The DERP map: the relay servers clients use when they cannot connect directly, from `derp.urls`, `derp.paths` and the embedded server in `derp.server`. A region replaces an earlier one with the same ID. See [DERP](https://headscale.net/stable/ref/derp/).", + "Config.DNSConfig": "The DNS configuration sent to clients, MagicDNS included, and TLS certificates for nodes. Clients apply it only with `--accept-dns`, their default. See [DNS](https://headscale.net/stable/ref/dns/).", + "Config.Database": "Where headscale stores nodes, users and keys. SQLite is recommended; PostgreSQL is supported for legacy deployments only. `database.sqlite` is read only for SQLite, `database.postgres` only for PostgreSQL.", + "Config.DisableUpdateCheck": "Skips the check for a newer headscale release that commands make at start.", + "Config.Log": "Headscale's own log output. See [Debugging](https://headscale.net/stable/ref/debug/#application-logging).", + "Config.LogTail": "Whether nodes send their logs to Tailscale.", + "Config.MetricsAddr": "The host:port serving `/metrics` and `/debug`; keep it private. Empty disables this listener.", + "Config.Node": "Covers node key expiry, ephemeral nodes and subnet routes.", + "Config.Noise": "The Noise protocol (TS2021) clients connect over.", + "Config.OIDC": "Login through an OpenID Connect provider. Setting `oidc.issuer` turns it on and requires `oidc.client_id` and `oidc.client_secret`. See [OpenID Connect](https://headscale.net/stable/ref/oidc/).", + "Config.Policy": "Where the access control policy is kept: in a file headscale reads, or in the database. See [Policy](https://headscale.net/stable/ref/policy/).", + "Config.PreAuthKeys": "Covers the cleanup of revoked pre-auth keys. See [Pre authenticated key](https://headscale.net/stable/ref/registration/#pre-authenticated-key).", + "Config.Prefixes": "The IP ranges node addresses are allocated from. Set at least one of `prefixes.v4` and `prefixes.v6`. Use the Tailscale ranges, `100.64.0.0/10` and `fd7a:115c:a1e0::/48`, or ranges inside them: the client assumes them, and other ranges are unsupported.", + "Config.ServerURL": "The URL clients connect to, with its `http://` or `https://` scheme, e.g. `https://headscale.example.com:443`. A trailing slash is trimmed on load. Its host must not be `dns.base_domain` or a name below it.", + "Config.TLS": "Headscale's own HTTPS certificate on `listen_addr`: from the files `tls.cert_path` and `tls.key_path`, or from ACME in `tls.acme`, not both. Without either, the server speaks plain HTTP. See [TLS](https://headscale.net/stable/ref/tls/).", + "Config.Taildrop": "Taildrop, Tailscale's file sharing between nodes.", + "Config.TrustedProxies": "The CIDRs of reverse proxies whose `True-Client-IP`, `X-Real-IP` and `X-Forwarded-For` headers are honoured. Empty ignores those headers. Set without a proxy in front, clients can spoof their source IP in logs and the v2 API.", + "Config.Tuning": "Holds performance settings that rarely need changing.", + "Config.UnixSocket": "Where the server serves the API without authentication, for the CLI on the same host. The CLI connects to it when `cli.address` is empty.", + "Config.UnixSocketPermission": "The file mode of `unix_socket`, in quoted octal (`\"0770\"`): unquoted, YAML reads `0770` as the number 504.", + "DERPConfig.AutoUpdate": "Reloads `derp.urls` and `derp.paths` every `derp.update_frequency`.", + "DERPConfig.Paths": "DERP map files. The extension picks the format: `.yaml` or `.yml`, or Tailscale JSON as `.json` or `.hujson`, both accepting comments and trailing commas.", + "DERPConfig.Server": "The embedded DERP server, a relay and STUN server run by headscale itself. See [Enable embedded DERP](https://headscale.net/stable/ref/derp/#enable-embedded-derp).", + "DERPConfig.URLs": "DERP maps in JSON to fetch. One that fails to load is logged and skipped; startup fails only when no region remains.", + "DERPConfig.UpdateFrequency": "How often `derp.auto_update_enabled` reloads the DERP map. Zero disables reloading.", + "DERPServerConfig.AutomaticallyAddEmbeddedDerpRegion": "Adds the embedded server's region to the DERP map. When it is false and `derp.server.enabled` is true, `derp.paths` is required: write the region there yourself.", + "DERPServerConfig.Enabled": "Runs the embedded DERP server. DERP needs TLS, so `server_url` must be `https://`.", + "DERPServerConfig.IPv4": "The server's public IPv4 address, published in the DERP map so clients reach it without DNS. Empty publishes none.", + "DERPServerConfig.IPv6": "The server's public IPv6 address, published in the DERP map so clients reach it without DNS. Empty publishes none.", + "DERPServerConfig.PrivateKeyPath": "The file holding the DERP server's private key, relative to the configuration file; required when `derp.server.enabled` is true. A missing file is created with a new key. It must differ from `noise.private_key_path`.", + "DERPServerConfig.RegionCode": "The region's short code, shown by Tailscale clients.", + "DERPServerConfig.RegionID": "The embedded server's region ID. It replaces a region with the same ID from the other sources.", + "DERPServerConfig.RegionName": "The region's name, shown by Tailscale clients.", + "DERPServerConfig.STUNAddr": "The UDP host:port of the STUN server, which helps clients with NAT traversal; required when `derp.server.enabled` is true.", + "DERPServerConfig.VerifyClients": "Admits only nodes registered with this server.", + "DNSChallengeConfig.PropagationTimeout": "How long to wait for a challenge record to show up on every authoritative nameserver. Zero skips the check.", + "DNSChallengeConfig.ProviderSettings": "The DNS provider that writes challenge records: `name` selects it, the other keys are its settings. Keys are lowercased on load, at every depth; two that differ only in case are an error. A string setting may be `file:` to read it from a file. `headscale generate config --running` and `/debug/config` show `name` and `file:` references; every other setting is ``, as any may be a credential. See [DNS-01 challenge provider](https://headscale.net/stable/ref/dns/#dns-01-challenge-provider) to set a provider up, acme-dns included, and to set it from environment variables.", + "DNSChallengeConfig.Resolvers": "The servers asked for the zone's nameservers, each an IP or host with an optional port (53 if omitted). Empty uses the default public resolvers. The system resolver is never used: on a host running MagicDNS it answers for `dns.base_domain` itself.", + "DNSConfig.BaseDomain": "The domain MagicDNS names live under, without a trailing dot, e.g. `example.com`. The host of `server_url` must not be this domain or a name below it: clients take the domain over.", + "DNSConfig.Certificates": "Lets nodes get TLS certificates for their MagicDNS names with `tailscale cert`. The node runs ACME itself; headscale publishes its DNS-01 challenge through `dns.challenge.provider`.", + "DNSConfig.Challenge": "The DNS provider answering ACME DNS-01 challenges, for node certificates and for headscale's own certificate when `tls.acme.challenge_type` is `DNS-01`. See [DNS-01 challenge provider](https://headscale.net/stable/ref/dns/#dns-01-challenge-provider).", + "DNSConfig.ExtraRecords": "DNS records served to clients, each with a `name`, `type` and `value`. Clients support `A` and `AAAA`. Mutually exclusive with `dns.extra_records_path`. See [Setting extra DNS records](https://headscale.net/stable/ref/dns/#setting-extra-dns-records).", + "DNSConfig.ExtraRecordsPath": "A file of extra records, reloaded when it changes. The extension picks the format: `.json`, `.hujson`, `.yaml` or `.yml`. Mutually exclusive with `dns.extra_records`.", + "DNSConfig.MagicDNS": "Gives each node a name below `dns.base_domain`, e.g. `laptop.example.com`, resolved by the client. It requires `dns.base_domain`.", + "DNSConfig.Nameservers": "The upstream DNS servers sent to clients. An entry that is neither an IP address nor a URL is skipped with a warning.", + "DNSConfig.OverrideLocalDNS": "Makes clients use `dns.nameservers.global` instead of their local DNS settings, which then requires at least one global nameserver. False sends them only as fallback resolvers.", + "DNSConfig.SearchDomains": "DNS search domains sent to clients. With MagicDNS, `dns.base_domain` comes first.", + "DatabaseConfig.Debug": "Turns on query logging: ordinary queries at log level debug, shown only when `log.level` is `debug` or `trace`, slow ones at warn and failed ones at error. Off, no query is logged. `database.gorm` shapes the query log. See [Database logging](https://headscale.net/stable/ref/debug/#database-logging).", + "DatabaseConfig.Gorm": "Query logging, applied only when `database.debug` is true.", + "DatabaseConfig.Postgres": "PostgreSQL, read only when `database.type` is `postgres`.", + "DatabaseConfig.Sqlite": "SQLite, read only when `database.type` is `sqlite` or `sqlite3`.", + "DatabaseConfig.Type": "The database backend. SQLite is recommended; PostgreSQL is supported for legacy deployments only.", + "EphemeralConfig.InactivityTimeout": "How long an ephemeral node can be offline before it is automatically deleted. It must exceed 65s, the client keepalive plus a margin.", + "GormConfig.ParameterizedQueries": "Logs queries without their parameter values.", + "GormConfig.SkipErrRecordNotFound": "Logs a query that finds no record as an ordinary query, not as an error.", + "GormConfig.SlowThreshold": "The query time, in milliseconds, above which a query is logged as a warning. Zero disables the warning.", + "HARouteConfig.ProbeInterval": "How often HA subnet routers are probed; a positive interval must be at least 2s. Zero or negative disables probing, and with it the `node.routes.ha.probe_timeout` rules.", + "HARouteConfig.ProbeTimeout": "The maximum time to wait for a probe response before declaring a node unhealthy; at least 1s and less than `node.routes.ha.probe_interval`.", + "LogConfig.Format": "How log lines are written.", + "LogConfig.Level": "The lowest level logged.", + "LogTailConfig.Enabled": "Lets nodes send their logs to Tailscale Inc.; headscale cannot point them at another log server. False tells nodes not to.", + "Nameservers.Global": "The nameservers for names `dns.nameservers.split` does not cover: IP addresses, or DNS-over-HTTPS URLs such as `https://dns.nextdns.io/`.", + "Nameservers.Split": "Maps a domain to the nameservers that answer for it (split DNS). Domains are lowercased on load; two that differ only in case are an error.", + "NodeConfig.Ephemeral": "Covers ephemeral nodes, which register with an ephemeral auth key and are deleted once they have been offline for `node.ephemeral.inactivity_timeout`.", + "NodeConfig.Expiry": "The key expiry given to a non-tagged node that registers without one, whatever the method (auth key, CLI, web, OIDC). An expiry the client asks for, `oidc.use_expiry_from_token` and an admin's `headscale nodes expire` still apply. Tagged nodes never get this default. Zero or negative disables the default.", + "NodeConfig.Routes": "Covers the routes nodes advertise. See [Routes](https://headscale.net/stable/ref/routes/).", + "NoiseConfig.PrivateKeyPath": "The file holding the Noise private key, which encrypts traffic between headscale and clients, relative to the configuration file. A missing file is created with a new key.", + "OIDCConfig.AllowedDomains": "Admits only users whose email domain is listed. Empty admits any domain.", + "OIDCConfig.AllowedGroups": "Admits only members of at least one listed group, from the provider's `groups` claim: UserInfo first, the ID token as fallback. Empty admits any group.", + "OIDCConfig.AllowedUsers": "Admits only users whose email address is listed. Empty admits any user.", + "OIDCConfig.ClientID": "The client ID from the provider; required when `oidc.issuer` is set.", + "OIDCConfig.ClientSecret": "The client secret from the provider, or `file:` to read it from a file; required when `oidc.issuer` is set. `headscale generate config --running` and `/debug/config` show a literal secret as `` and a `file:` reference as written.", + "OIDCConfig.EmailVerifiedRequired": "Trusts an email only when the provider marks it verified: an unverified one fails `oidc.allowed_domains` and `oidc.allowed_users` and is not copied to the user. Turn it off for a provider that does not send `email_verified`.", + "OIDCConfig.ExtraParams": "Sent as is to the provider's authorization endpoint, e.g. `domain_hint`; names keep their case.", + "OIDCConfig.Issuer": "The provider's issuer URL. Setting it turns OIDC on.", + "OIDCConfig.OnlyStartIfOIDCIsAvailable": "Stops startup when the provider cannot be reached. False starts without OIDC, with CLI-based registration.", + "OIDCConfig.PKCE": "Proof Key for Code Exchange (RFC 7636), which protects the authorization code from interception. See [Enable PKCE](https://headscale.net/stable/ref/oidc/#enable-pkce-recommended).", + "OIDCConfig.Scope": "The scopes requested; include `openid`.", + "OIDCConfig.UseExpiryFromToken": "Expires an OIDC-registered node with its token, instead of `node.expiry`. Tokens are often short-lived, forcing frequent logins.", + "PKCEConfig.Enabled": "Sends a PKCE challenge with each login.", + "PKCEConfig.Method": "How the code challenge is derived from the verifier. The verifier is sent as is in the token exchange.", + "PolicyConfig.Mode": "Where the policy is kept: in the file `policy.path`, or in the database, edited through the CLI or API.", + "PolicyConfig.Path": "The HuJSON policy file read when `policy.mode` is `file`, relative to the configuration file. Empty starts without a policy, which allows all traffic.", + "PostgresConfig.ConnMaxIdleTimeSecs": "How long, in seconds, a connection may stay idle before it is closed.", + "PostgresConfig.Host": "The server's host name or IP, or the directory of its Unix socket (a path starting with `/`).", + "PostgresConfig.MaxIdleConnections": "Caps idle connections kept in the pool.", + "PostgresConfig.MaxOpenConnections": "Caps open connections to the database.", + "PostgresConfig.Name": "The database name.", + "PostgresConfig.Pass": "The password, or `file:` to read it from a file, read only when `database.type` is `postgres`. `headscale generate config --running` and `/debug/config` show a literal password as `` and a `file:` reference as written.", + "PostgresConfig.Port": "The server's port or, with a Unix socket directory in `database.postgres.host`, the port in the socket's file name. Zero uses the driver's default.", + "PostgresConfig.Ssl": "The TLS mode: `true` keeps the driver's default `sslmode`, `false` disables TLS, any other value is passed as `sslmode` (`require`, `verify-full`, ...).", + "PostgresConfig.User": "The user to connect as.", + "PreAuthKeysConfig.RevokedRetention": "How long a soft-revoked pre-auth key (revoked via the v2 API's DELETE) is kept retrievable before the background collector hard-deletes it. Keys still backing a node are kept until the node is deleted. A zero or negative duration disables the collector.", + "PrefixesConfig.Allocation": "How a new node's addresses are picked.", + "PrefixesConfig.V4": "The IPv4 range, e.g. `100.64.0.0/10`. Empty gives nodes no IPv4 address.", + "PrefixesConfig.V6": "The IPv6 range, e.g. `fd7a:115c:a1e0::/48`. Empty gives nodes no IPv6 address.", + "RouteConfig.HA": "Health probing of HA subnet routers. When two or more nodes advertise the same route, headscale pings each over Noise and moves the route away from one that does not answer in time. See [High availability](https://headscale.net/stable/ref/routes/#high-availability).", + "SqliteConfig.Path": "The database file, relative to the configuration file; `:memory:` keeps the database in memory.", + "SqliteConfig.WALAutoCheckPoint": "The number of WAL frames after which the WAL is checkpointed automatically; zero disables automatic checkpoints. Applied only when `database.sqlite.write_ahead_log` is true.", + "SqliteConfig.WriteAheadLog": "Applies `database.sqlite.wal_autocheckpoint` and compacts the database (`VACUUM`) on shutdown. SQLite runs in WAL mode either way; false keeps SQLite's default checkpoint of 1000 frames.", + "TLSConfig.ACME": "Gets the certificate from an ACME CA such as Let's Encrypt, and renews it. Setting `tls.acme.hostname` turns it on.", + "TLSConfig.CertPath": "The PEM certificate file, relative to the configuration file. Setting it turns TLS on.", + "TLSConfig.KeyPath": "The PEM private key file of `tls.cert_path`, relative to the configuration file.", + "TaildropConfig.Enabled": "Gives every node the file-sharing capability. False omits it from the baseline; a policy `nodeAttrs` grant can still give it.", + "Tuning.BatchChangeDelay": "How often queued changes are sent to clients as one update; must be positive.", + "Tuning.BatcherWorkers": "The number of workers building map updates for connected clients. Zero picks the number from the CPU count.", + "Tuning.NodeMapSessionBufferedChanSize": "How many map updates are queued per connected client.", + "Tuning.NodeStoreBatchSize": "How many node changes are batched before the in-memory node state, peer relationships included, is rebuilt; must be positive. Higher values save CPU on bulk changes but delay each change until its batch is full or `tuning.node_store_batch_timeout` passes.", + "Tuning.NodeStoreBatchTimeout": "The longest a partial batch of node changes waits before the rebuild; must be positive. Lower values answer single changes faster at the cost of more rebuilds.", + "Tuning.RegisterCacheExpiration": "How long a pending registration waits to be completed. Zero uses the default.", + "Tuning.RegisterCacheMaxEntries": "Bounds pending registrations. At capacity, new registrations are refused without evicting pending ones; SSH checks have a small reserve beyond it. Zero uses the default. See [Pending authentication limits](https://headscale.net/stable/ref/registration/#pending-authentication-limits).", +} + +var configValueDocs = map[string]string{ + "ACMEChallenge=DNS-01": "Has the CA look up a TXT record, which headscale writes through `dns.challenge.provider`. It needs no open port.", + "ACMEChallenge=HTTP-01": "Has the CA fetch a token over HTTP on port 80, answered on `tls.acme.http_listen`. TLS-ALPN-01 on `listen_addr` stays enabled too.", + "ACMEChallenge=TLS-ALPN-01": "Has the CA check a special certificate on port 443, answered on `listen_addr`, which must be reachable there.", + "DatabaseType=postgres": "PostgreSQL, at `database.postgres.host`.", + "DatabaseType=sqlite": "SQLite, in the file `database.sqlite.path`.", + "DatabaseType=sqlite3": "The same as `sqlite`.", + "IPAllocationStrategy=random": "Picks a free address at random.", + "IPAllocationStrategy=sequential": "Takes the next free address after the last one handed out, and wraps around to reuse freed addresses.", + "LogFormat=json": "Writes one JSON object per line, for log collectors.", + "LogFormat=text": "Writes human-readable lines, coloured when stderr is a terminal and `NO_COLOR` is unset.", + "PKCEMethod=S256": "Sends the base64url SHA-256 of the verifier as the challenge. Recommended.", + "PKCEMethod=plain": "Sends the verifier itself as the challenge. Use it only with a provider that does not support `S256`.", + "PolicyMode=database": "Keeps the policy in the database, set with `headscale policy set` or the API. `policy.path` is not read.", + "PolicyMode=file": "Reads the policy from `policy.path`. Send headscale `SIGHUP` to reload it after an edit.", +} diff --git a/hscontrol/types/config_fields.go b/hscontrol/types/config_fields.go index f7be84062..06125bd7f 100644 --- a/hscontrol/types/config_fields.go +++ b/hscontrol/types/config_fields.go @@ -3,9 +3,11 @@ package types import ( "encoding" "reflect" + "slices" ) -// ConfigField is one key of the configuration: a leaf value or an open map. +// ConfigField is one key of the configuration: a section, a leaf value or +// an open map. type ConfigField struct { // Path is the dotted key, e.g. "dns.nameservers.global". Path string @@ -14,18 +16,33 @@ type ConfigField struct { Value reflect.Value // Open marks a map, whose keys the user chooses. Open bool + // Section marks a struct whose fields are the keys below Path. + Section bool + // Doc is the field's doc comment, from config_docs_generated.go. + Doc string } var textUnmarshalerType = reflect.TypeFor[encoding.TextUnmarshaler]() -// ConfigFields lists every leaf and open map of cfg reachable through koanf -// tags, in declaration order. A struct is a leaf when *T unmarshals text; -// otherwise it is descended into. Fields tagged koanf:"-" are skipped. -func ConfigFields(cfg *Config) []ConfigField { - return appendConfigFields(nil, "", reflect.ValueOf(cfg).Elem()) +// ConfigTree lists every section, leaf and open map of cfg reachable +// through koanf tags, in declaration order, each section before its keys. +// A struct is a leaf when *T unmarshals text; otherwise it is a section. +// Fields tagged koanf:"-" are skipped. +func ConfigTree(cfg *Config) []ConfigField { + return appendConfigTree(nil, "", reflect.ValueOf(cfg).Elem()) } -func appendConfigFields(fields []ConfigField, prefix string, v reflect.Value) []ConfigField { +// ConfigFields is [ConfigTree] without its sections. +func ConfigFields(cfg *Config) []ConfigField { + return slices.DeleteFunc(ConfigTree(cfg), func(f ConfigField) bool { return f.Section }) +} + +// ConfigValueDoc is the doc comment of enum's constant holding value, or "". +func ConfigValueDoc(enum reflect.Type, value string) string { + return configValueDocs[enum.Name()+"="+value] +} + +func appendConfigTree(fields []ConfigField, prefix string, v reflect.Value) []ConfigField { for f, fv := range v.Fields() { name := f.Tag.Get("koanf") if !f.IsExported() || name == "" || name == "-" { @@ -33,19 +50,20 @@ func appendConfigFields(fields []ConfigField, prefix string, v reflect.Value) [] } path := prefix + name - - if f.Type.Kind() == reflect.Struct && !reflect.PointerTo(f.Type).Implements(textUnmarshalerType) { - fields = appendConfigFields(fields, path+".", fv) - - continue - } + section := f.Type.Kind() == reflect.Struct && !reflect.PointerTo(f.Type).Implements(textUnmarshalerType) fields = append(fields, ConfigField{ - Path: path, - Field: f, - Value: fv, - Open: f.Type.Kind() == reflect.Map, + Path: path, + Field: f, + Value: fv, + Open: f.Type.Kind() == reflect.Map, + Section: section, + Doc: configFieldDocs[v.Type().Name()+"."+f.Name], }) + + if section { + fields = appendConfigTree(fields, path+".", fv) + } } return fields diff --git a/hscontrol/types/config_fields_test.go b/hscontrol/types/config_fields_test.go index 3b131935a..2cd60224c 100644 --- a/hscontrol/types/config_fields_test.go +++ b/hscontrol/types/config_fields_test.go @@ -1,7 +1,10 @@ package types import ( + "maps" "reflect" + "regexp" + "slices" "strings" "testing" @@ -199,3 +202,305 @@ func TestConfigFields(t *testing.T) { check(reflect.TypeFor[Config](), "Config") }) } + +func TestConfigTree(t *testing.T) { + wantSections := []string{ + "noise", + "prefixes", + "policy", + "log", + "node", + "node.ephemeral", + "node.routes", + "node.routes.ha", + "preauth_keys", + "derp", + "derp.server", + "database", + "database.gorm", + "database.sqlite", + "database.postgres", + "dns", + "dns.nameservers", + "dns.certificates", + "dns.challenge", + "tls", + "tls.acme", + "oidc", + "oidc.pkce", + "logtail", + "taildrop", + "auto_update", + "cli", + "tuning", + } + + var cfg Config + + tree := ConfigTree(&cfg) + + var gotSections []string + + for i, f := range tree { + if f.Doc == "" { + t.Errorf("%s has no doc", f.Path) + } + + if !f.Section { + continue + } + + gotSections = append(gotSections, f.Path) + + if i+1 == len(tree) || !strings.HasPrefix(tree[i+1].Path, f.Path+".") { + t.Errorf("section %s is not directly before its first key", f.Path) + } + } + + if diff := cmp.Diff(wantSections, gotSections); diff != "" { + t.Errorf("ConfigTree sections (-want +got):\n%s", diff) + } +} + +var ( + goDocLink = regexp.MustCompile(`\[[A-Za-z][\w.]*\](\(?)`) + codeSpan = regexp.MustCompile("`([^`]*)`") + linkTarget = regexp.MustCompile(`\]\([^)]*\)`) + docWord = regexp.MustCompile(`[A-Za-z0-9_.]+`) + keyLike = regexp.MustCompile(`^[a-z0-9_]+(\.[a-z0-9_<>]+)+$`) + placeholder = regexp.MustCompile(`^<[a-z_]+>$`) + angleWord = regexp.MustCompile(`<[A-Za-z][\w-]*>`) + snakeCase = regexp.MustCompile(`^[a-z0-9]+(_[a-z0-9]+)+$`) + camelCase = regexp.MustCompile(`[a-z][A-Z]`) +) + +// docSchema is what the doc style rules check a doc against. +type docSchema struct { + paths, open, top, lastSegments, goNames map[string]bool +} + +func newDocSchema(tree []ConfigField) docSchema { + s := docSchema{ + paths: map[string]bool{}, open: map[string]bool{}, top: map[string]bool{}, + lastSegments: map[string]bool{}, goNames: map[string]bool{}, + } + structs := []reflect.Type{reflect.TypeFor[Config]()} + + for _, f := range tree { + s.paths[f.Path] = true + s.open[f.Path] = f.Open + + first, _, nested := strings.Cut(f.Path, ".") + s.top[first] = true + + if last := f.Path[strings.LastIndex(f.Path, ".")+1:]; nested && snakeCase.MatchString(last) { + s.lastSegments[last] = true + } + + if f.Section { + structs = append(structs, f.Field.Type) + } + } + + for _, typ := range structs { + for f := range typ.Fields() { + if f.IsExported() && camelCase.MatchString(f.Name) && f.Name != "MagicDNS" { + s.goNames[f.Name] = true + } + } + } + + return s +} + +// bare is text outside code spans and link targets. +func bare(text string) string { + return linkTarget.ReplaceAllString(codeSpan.ReplaceAllString(text, " "), "]") +} + +func bareWords(text string) []string { + words := docWord.FindAllString(bare(text), -1) + for i, w := range words { + words[i] = strings.TrimRight(w, ".") + } + + return words +} + +// goDocLinks are [Name] links a Markdown renderer leaves as text. +func (docSchema) goDocLinks(text string) []string { + var bad []string + + for _, m := range goDocLink.FindAllStringSubmatch(text, -1) { + if m[1] == "" { + bad = append(bad, m[0]) + } + } + + return bad +} + +// bareKeys are keys written outside backticks: a dotted or snake_case +// path, or the snake_case leaf of a nested one. +func (s docSchema) bareKeys(text string) []string { + var bad []string + + for _, w := range bareWords(text) { + if (strings.ContainsAny(w, "._") && s.paths[w]) || s.lastSegments[w] { + bad = append(bad, w) + } + } + + return bad +} + +// unknownKeys are backticked keys under a top-level key that name no key, +// nor an open map's entry placeholder. +func (s docSchema) unknownKeys(text string) []string { + var bad []string + + for _, m := range codeSpan.FindAllStringSubmatch(text, -1) { + key := m[1] + first, _, _ := strings.Cut(key, ".") + + if !keyLike.MatchString(key) || !s.top[first] || s.paths[key] { + continue + } + + i := strings.LastIndex(key, ".") + if !s.open[key[:i]] || !placeholder.MatchString(key[i+1:]) { + bad = append(bad, key) + } + } + + return bad +} + +func (s docSchema) goFieldNames(text string) []string { + return slices.DeleteFunc(bareWords(text), func(w string) bool { return !s.goNames[w] }) +} + +// markup is what Markdown swallows as HTML, or a template engine runs. +func (docSchema) markup(text string) []string { + bad := angleWord.FindAllString(bare(text), -1) + + for _, s := range []string{"{{", "{%", "{#"} { + if strings.Contains(text, s) { + bad = append(bad, s) + } + } + + return bad +} + +// undocumentedValues lists the values of each enum in tree that has a +// documented value but not all of them. +func undocumentedValues(tree []ConfigField) []string { + type enum interface{ Allowed() []string } + + var bad []string + + for _, f := range tree { + e, ok := reflect.TypeAssert[enum](f.Value) + prefix := f.Field.Type.Name() + "=" + + if !ok || !slices.ContainsFunc(slices.Collect(maps.Keys(configValueDocs)), func(k string) bool { + return strings.HasPrefix(k, prefix) + }) { + continue + } + + for _, v := range e.Allowed() { + if ConfigValueDoc(f.Field.Type, v) == "" { + bad = append(bad, f.Path+": "+v) + } + } + } + + return bad +} + +// TestConfigDocsStyle keeps the field and value docs readable where they +// are printed: YAML comments, the reference page and NixOS descriptions. +func TestConfigDocsStyle(t *testing.T) { + tree := ConfigTree(new(Config)) + schema := newDocSchema(tree) + + type doc struct{ at, text string } + + docs := make([]doc, 0, len(tree)+len(configValueDocs)) + for _, f := range tree { + docs = append(docs, doc{f.Path, f.Doc}) + } + + for _, k := range slices.Sorted(maps.Keys(configValueDocs)) { + docs = append(docs, doc{k, configValueDocs[k]}) + } + + // Each rule has docs it must reject, one per clause, so it cannot pass + // vacuously, and docs it must accept, so it does not flag good prose. + rules := []struct { + name string + check func(text string) []string + rejects []string + accepts []string + }{ + { + name: "no Go doc links", + check: schema.goDocLinks, + rejects: []string{"With TLS as [Config.TLS] sets it up."}, + accepts: []string{"See [DNS](https://headscale.net/stable/ref/dns/)."}, + }, + { + name: "keys in backticks", + check: schema.bareKeys, + rejects: []string{"Requires dns.base_domain.", "Applied only when write_ahead_log is true."}, + accepts: []string{"Each node below `dns.base_domain`, as the policy allows; see [DNS](https://headscale.net/stable/ref/dns/)."}, + }, + { + name: "backticked keys exist", + check: schema.unknownKeys, + rejects: []string{"Set `dns.challenge.provider.name`."}, + accepts: []string{"Set `dns.challenge.provider.` or `dns.base_domain`, e.g. `1.1.1.1:53` in `config.yaml`."}, + }, + { + name: "no Go field names", + check: schema.goFieldNames, + rejects: []string{"Reloads every UpdateFrequency."}, + accepts: []string{"Requires MagicDNS and an IPv4 address."}, + }, + { + name: "no markup Markdown or templates eat", + check: schema.markup, + rejects: []string{"Reads file:.", "Shows {{ .Name }}.", "Shows {% raw %}.", "Shows {# note #}."}, + accepts: []string{"Reads `file:`; shows ``."}, + }, + } + + for _, rule := range rules { + t.Run(rule.name, func(t *testing.T) { + for _, text := range rule.rejects { + assert.NotEmpty(t, rule.check(text), "rejects %q", text) + } + + for _, text := range rule.accepts { + assert.Empty(t, rule.check(text), "accepts %q", text) + } + + var offenders []string + + for _, d := range docs { + for _, bad := range rule.check(d.text) { + offenders = append(offenders, d.at+": "+bad) + } + } + + assert.Empty(t, offenders) + }) + } + + t.Run("enums document every value", func(t *testing.T) { + assert.Empty(t, undocumentedValues(tree)) + assert.NotEmpty(t, ConfigValueDoc(reflect.TypeFor[PolicyMode](), "database")) + }) +} diff --git a/hscontrol/types/config_values.go b/hscontrol/types/config_values.go index 3db3bdb33..3d7070678 100644 --- a/hscontrol/types/config_values.go +++ b/hscontrol/types/config_values.go @@ -221,7 +221,7 @@ func (f *LogFormat) UnmarshalText(text []byte) error { type DatabaseType string //nolint:recvcheck // UnmarshalText needs a pointer; the rest read the value func (DatabaseType) Allowed() []string { - return []string{"sqlite", string(DatabaseSqlite), string(DatabasePostgres)} + return []string{string(DatabaseSqliteShort), string(DatabaseSqlite), string(DatabasePostgres)} } func (d *DatabaseType) UnmarshalText(text []byte) error { diff --git a/hscontrol/types/const.go b/hscontrol/types/const.go index 788831e8f..7b7f71aa4 100644 --- a/hscontrol/types/const.go +++ b/hscontrol/types/const.go @@ -3,13 +3,24 @@ package types import "time" const ( - HTTPTimeout = 30 * time.Second - HTTPShutdownTimeout = 3 * time.Second - TLSALPN01ChallengeType ACMEChallenge = "TLS-ALPN-01" - HTTP01ChallengeType ACMEChallenge = "HTTP-01" - DNS01ChallengeType ACMEChallenge = "DNS-01" + HTTPTimeout = 30 * time.Second + HTTPShutdownTimeout = 3 * time.Second + // TLSALPN01ChallengeType has the CA check a special certificate on + // port 443, answered on `listen_addr`, which must be reachable there. + TLSALPN01ChallengeType ACMEChallenge = "TLS-ALPN-01" + // HTTP01ChallengeType has the CA fetch a token over HTTP on port 80, + // answered on `tls.acme.http_listen`. TLS-ALPN-01 on `listen_addr` + // stays enabled too. + HTTP01ChallengeType ACMEChallenge = "HTTP-01" + // DNS01ChallengeType has the CA look up a TXT record, which headscale + // writes through `dns.challenge.provider`. It needs no open port. + DNS01ChallengeType ACMEChallenge = "DNS-01" + + // JSONLogFormat writes one JSON object per line, for log collectors. JSONLogFormat LogFormat = "json" + // TextLogFormat writes human-readable lines, coloured when stderr is a + // terminal and `NO_COLOR` is unset. TextLogFormat LogFormat = "text" MaxHostnameLength = 255 diff --git a/tools/bump/generate.go b/tools/bump/generate.go index 55217a464..f54007cac 100644 --- a/tools/bump/generate.go +++ b/tools/bump/generate.go @@ -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 diff --git a/tools/configgen/main.go b/tools/configgen/main.go new file mode 100644 index 000000000..f3d667f9b --- /dev/null +++ b/tools/configgen/main.go @@ -0,0 +1,277 @@ +// Command configgen writes files generated from the configuration's Go +// source. `configgen table ` 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 ") + 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 ".", and of every documented constant of a +// type with an Allowed method, keyed "=". +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 +} diff --git a/tools/configgen/main_test.go b/tools/configgen/main_test.go new file mode 100644 index 000000000..60b8b42b6 --- /dev/null +++ b/tools/configgen/main_test.go @@ -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) + } +} diff --git a/tools/configgen/testdata/fixture.go.txt b/tools/configgen/testdata/fixture.go.txt new file mode 100644 index 000000000..46d61553d --- /dev/null +++ b/tools/configgen/testdata/fixture.go.txt @@ -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:"-"` +}