hscontrol: structured config validation and typed listener errors

[kradalby]

listen_addr: 0.0.0.0:80 + tls_letsencrypt_hostname collide internally — main HTTP and autocert HTTP-01 both want port 80. Second bind loses with address already in use and the ACME goroutine log.Fatals. No hint that the conflict is internal.

Now rejected at config load:

Fatal config error: listen_addr and tls_letsencrypt_listen would bind the same TCP socket
  current: listen_addr: "0.0.0.0:80"
  conflicts with: tls_letsencrypt_listen: ":http"
  hint: give each listener a distinct port, or bind them to different non-wildcard hosts
  see: https://headscale.net/stable/ref/tls/

Real runtime bind failures get a typed *ListenerBindError plus a CLI hint:

binding main HTTP listener (listen_addr="0.0.0.0:443"): listen tcp 0.0.0.0:443: bind: address already in use

Hint: another process on this host is bound to the same address. Find it with: sudo ss -tlnp 'sport = :443'

errors.Is / As / Join work through the chain. Validation reports every violation in one pass. ACME listener moved into the main errgroup; orphan log.Fatal is gone.

Fixes #3227

Generated with the help of an AI assistant

[Copilot]

Pull request overview

This PR improves Headscale’s operator experience around configuration and listener binding by introducing structured, multi-error config validation and typed listener bind errors, including detection of internal listener collisions (notably listen_addr vs ACME HTTP-01).

Changes:

• Add structured config error reporting (ConfigError + configValidator) that aggregates multiple validation failures using errors.Join.
• Detect and reject TCP listener collisions at config load time (including ACME HTTP-01 listener conflicts) and document the common port-80 pitfall.
• Introduce *ListenerBindError for runtime bind failures and add CLI hints for EADDRINUSE / EACCES; move ACME HTTP-01 serving into the main errgroup and shutdown path.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
hscontrol/types/listener.go	Adds ListenerBindError, port parsing helpers, and listener-collision validation.
hscontrol/types/listener_test.go	Unit tests for port parsing, overlap logic, wildcard detection, and ListenerBindError.
hscontrol/types/config.go	Refactors validation into an aggregator, adds listener-collision validation, and converts several log.Fatal validations into ConfigErrors.
hscontrol/types/config_test.go	Updates expectations for new structured validation output and adds coverage for collision detection and multi-error aggregation.
hscontrol/types/config_errors.go	Introduces structured ConfigError, ErrConfig sentinel, validator aggregation, and tree-walking helpers.
hscontrol/types/config_errors_test.go	Tests rendering and errors.Is/As behavior for ConfigError and joined validation errors.
hscontrol/app.go	Uses typed bind errors, replaces ACME HTTP-01 goroutine+log.Fatal with errgroup-managed server + shutdown integration, and refactors TLS settings return type.
cmd/headscale/cli/serve.go	Adds serve-error classification to append actionable hints for bind failures.
cmd/headscale/cli/serve_test.go	Tests serve error classification and hint rendering.
docs/ref/tls.md	Documents the listen_addr vs ACME HTTP-01 port-80 collision and the new startup validation behavior.
config-example.yaml	Adds guidance around ACME HTTP-01 listener binding and collision avoidance.
CHANGELOG.md	Documents the new config validation behavior and typed listener bind errors.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[nblock]

Can we remove this section? The config file is already quite long and headscale checks and refuses to start if it detects that misconfiguration?

[nblock]

Same as above, I think it should be removed altogether.