server: a port that cannot be bound stops startup (closes #266)

The start hook now binds the listen port itself and serves on it in a
goroutine. A bind failure, such as a port already in use or a
privileged port without root, is returned to fx, which stops startup
and exits 1 with an error like "starting http server: listen tcp
:8080: bind: address already in use". Before, the bind happened inside
the goroutine and its error was only logged while the watcher kept
running without the dashboard, API or health check.

The http.Server is now built before that goroutine starts, so Shutdown
no longer reads a field another goroutine may still be writing.

TestPortInUseStopsStartup holds a port and checks that starting the
server on it fails with an error naming it.

Model: opus-5-5

README.md

@@ -423,7 +423,7 @@ following precedence (highest to lowest):
 
 | Variable                               | Description                                                                                                                           | Default               |
 | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
-| `PORT`                                 | HTTP listen port                                                                                                                      | `8080`                |
+| `PORT`                                 | HTTP listen port; a port that cannot be bound, such as one already in use, stops startup                                              | `8080`                |
 | `DNSWATCHER_DEBUG`                     | Enable debug logging                                                                                                                  | `false`               |
 | `DNSWATCHER_DATA_DIR`                  | Directory for state file                                                                                                              | `/var/lib/dnswatcher` |
 | `DNSWATCHER_TARGETS`                   | Comma-separated DNS names (auto-classified via PSL)                                                                                   | `""`                  |

TODO.md

@@ -19,6 +19,10 @@ trial run of the finished image: https://git.eeqj.de/sneak/dnswatcher/issues/149
 
 # Completed Steps
 
+- 2026-10-13: a `PORT` that cannot be bound stops startup with an error naming
+  the address, instead of running without the HTTP server (closes #266).
+- 2026-10-13: a check saving the state while the dashboard or `/api/v1/status`
+  is read cannot crash the process (closes #261).
 - 2026-10-06: canonical files re-fetched from `sneak/prompts` at `dd4027b`; lint
   and test are phases of the `Dockerfile`, every scripted build uncached (closes
   #257).

internal/server/export_test.go

@@ -13,8 +13,8 @@ import (
 const RequestTimeout time.Duration = requestTimeout
 
 // SetListenPort overrides the port Run binds. A test uses it to hand
-// Run an unbindable port so ListenAndServe fails immediately and Run
-// returns after storing its http.Server.
+// Run an unbindable port, so that Run stores its http.Server and then
+// returns an error without listening.
 func SetListenPort(s *Server, port int) {
 	s.port = port
 }

internal/server/server.go

@@ -6,6 +6,7 @@ import (
 	"errors"
 	"fmt"
 	"log/slog"
+	"net"
 	"net/http"
 	"time"
 
@@ -112,7 +113,7 @@ func New(
 	}
 
 	lifecycle.Append(fx.Hook{
-		OnStart: func(_ context.Context) error {
+		OnStart: func(ctx context.Context) error {
 			srv.startupTime = time.Now()
 
 			err := srv.enableSentry()
@@ -120,9 +121,7 @@ func New(
 				return err
 			}
 
-			go srv.Run()
-
-			return nil
+			return srv.Run(ctx)
 		},
 		OnStop: func(ctx context.Context) error {
 			return srv.Shutdown(ctx)
@@ -149,8 +148,10 @@ func newHTTPServer(
 	}
 }
 
-// Run starts the HTTP server.
-func (s *Server) Run() {
+// Run binds the listen port, then serves HTTP on it in a new goroutine
+// and returns. A port that cannot be bound is returned as an error, so
+// that startup stops instead of running without the HTTP server.
+func (s *Server) Run(ctx context.Context) error {
 	s.SetupRoutes()
 
 	listenAddr := fmt.Sprintf(":%d", s.port)
@@ -158,10 +159,21 @@ func (s *Server) Run() {
 
 	s.log.Info("http server starting", "addr", listenAddr)
 
-	err := s.httpServer.ListenAndServe()
-	if err != nil && !errors.Is(err, http.ErrServerClosed) {
-		s.log.Error("http server error", "error", err)
+	lc := &net.ListenConfig{}
+
+	listener, err := lc.Listen(ctx, "tcp", listenAddr)
+	if err != nil {
+		return fmt.Errorf("starting http server: %w", err)
 	}
+
+	go func() {
+		err := s.httpServer.Serve(listener)
+		if err != nil && !errors.Is(err, http.ErrServerClosed) {
+			s.log.Error("http server error", "error", err)
+		}
+	}()
+
+	return nil
 }
 
 // Shutdown gracefully shuts down the server, then sends the error

internal/server/server_test.go

@@ -1,6 +1,8 @@
 package server_test
 
 import (
+	"net"
+	"strings"
 	"testing"
 
 	"github.com/spf13/viper"
@@ -58,15 +60,13 @@ func buildServer(t *testing.T) *server.Server {
 }
 
 // TestRunWiresSocketTimeouts pins that the http.Server the running
-// server actually serves — the one Run builds and hands to
-// ListenAndServe — carries every socket-level timeout, plus the two
+// server actually serves — the one Run builds and serves on the port
+// it binds — carries every socket-level timeout, plus the two
 // relationships the values must satisfy.
 //
-// Run is driven to completion with an unbindable port: it builds and
-// stores s.httpServer, then ListenAndServe fails at once and Run
-// returns without ever listening. The assertions run in the same
-// goroutine after Run returns, so reading s.httpServer is free of any
-// data race. Nothing here measures elapsed time.
+// Run is given an unbindable port: it builds and stores s.httpServer,
+// then the bind fails and Run returns the error without ever
+// listening. Nothing here measures elapsed time.
 //
 // ReadTimeout must be at least ReadHeaderTimeout. net/http reads the
 // headers under ReadHeaderTimeout, then sets the read deadline for the
@@ -84,7 +84,10 @@ func TestRunWiresSocketTimeouts(t *testing.T) {
 	srv := buildServer(t)
 	server.SetListenPort(srv, -1)
 
-	srv.Run()
+	err := srv.Run(t.Context())
+	if err == nil {
+		t.Fatal("Run bound port -1")
+	}
 
 	hs := server.HTTPServerOf(srv)
 	if hs == nil {
@@ -133,3 +136,38 @@ func TestRunWiresSocketTimeouts(t *testing.T) {
 		)
 	}
 }
+
+func TestPortInUseStopsStartup(t *testing.T) {
+	// Bound on every address, as Run binds, so that Run's bind fails.
+	lc := &net.ListenConfig{}
+
+	taken, err := lc.Listen(t.Context(), "tcp", ":0")
+	if err != nil {
+		t.Fatalf("binding a port for the test: %v", err)
+	}
+
+	defer func() { _ = taken.Close() }()
+
+	_, port, err := net.SplitHostPort(taken.Addr().String())
+	if err != nil {
+		t.Fatalf("reading the bound port: %v", err)
+	}
+
+	viper.Reset()
+	t.Setenv("DNSWATCHER_TARGETS", "example.com")
+	t.Setenv("DNSWATCHER_DATA_DIR", t.TempDir())
+	t.Setenv("PORT", port)
+
+	app := newServerApp(fx.Invoke(func(*server.Server) {}))
+
+	err = app.Start(t.Context())
+	if err == nil {
+		_ = app.Stop(t.Context())
+
+		t.Fatal("startup succeeded on a port that is already bound")
+	}
+
+	if !strings.Contains(err.Error(), ":"+port) {
+		t.Errorf("startup error does not name port %s: %v", port, err)
+	}
+}

internal/state/state.go

@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"log/slog"
+	"maps"
 	"os"
 	"path/filepath"
 	"slices"
@@ -270,12 +271,21 @@ func (s *State) Save() error {
 	return nil
 }
 
-// GetSnapshot returns a copy of the current snapshot.
+// GetSnapshot returns a copy of the current snapshot, with copies of
+// its maps, so that a caller can range over them while the state is
+// written. The entries in the maps are not copied: an entry saved in the
+// state must be replaced, never changed in place.
 func (s *State) GetSnapshot() Snapshot {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
 
-	return *s.snapshot
+	snap := *s.snapshot
+	snap.Domains = maps.Clone(snap.Domains)
+	snap.Hostnames = maps.Clone(snap.Hostnames)
+	snap.Ports = maps.Clone(snap.Ports)
+	snap.Certificates = maps.Clone(snap.Certificates)
+
+	return snap
 }
 
 // SetDomainState updates the state for a domain.

internal/state/state_test.go

@@ -995,7 +995,8 @@ func TestPortStateUnmarshalJSON_BothFormats(t *testing.T) {
 	}
 }
 
-// TestGetSnapshot_ReturnsCopy verifies that GetSnapshot returns a value copy.
+// TestGetSnapshot_ReturnsCopy verifies that the maps in the snapshot
+// GetSnapshot returns are not the state's own.
 func TestGetSnapshot_ReturnsCopy(t *testing.T) {
 	t.Parallel()
 
@@ -1005,15 +1006,67 @@ func TestGetSnapshot_ReturnsCopy(t *testing.T) {
 
 	snap := s.GetSnapshot()
 
-	// Mutate the returned snapshot's map.
-	snap.Domains["mutated.example.com"] = &state.DomainState{
-		Nameservers: []string{"ns1.mutated.com."},
+	const added = "added.example.com"
+
+	snap.Domains[added] = &state.DomainState{}
+	snap.Hostnames[added] = &state.HostnameState{}
+	snap.Ports[added] = &state.PortState{}
+	snap.Certificates[added] = &state.CertificateState{}
+
+	if _, ok := s.GetDomainState(added); ok {
+		t.Error("the snapshot's Domains map is the state's own")
 	}
 
-	// The original domain data should still be accessible.
-	_, ok := s.GetDomainState("example.com")
-	if !ok {
-		t.Error("original domain should still exist")
+	if _, ok := s.GetHostnameState(added); ok {
+		t.Error("the snapshot's Hostnames map is the state's own")
+	}
+
+	if _, ok := s.GetPortState(added); ok {
+		t.Error("the snapshot's Ports map is the state's own")
+	}
+
+	if _, ok := s.GetCertificateState(added); ok {
+		t.Error("the snapshot's Certificates map is the state's own")
+	}
+}
+
+// TestGetSnapshot_WhileWritten ranges over snapshots while another
+// goroutine writes the state, as the dashboard does while a check runs.
+// Under -race it fails when a snapshot's maps are the state's own.
+func TestGetSnapshot_WhileWritten(t *testing.T) {
+	t.Parallel()
+
+	s := state.NewForTestWithDataDir(t.TempDir())
+
+	const writes = 1000
+
+	written := make(chan struct{})
+
+	go func() {
+		defer close(written)
+
+		for range writes {
+			s.SetDomainState("example.com", &state.DomainState{})
+			s.SetHostnameState(testHostname, &state.HostnameState{})
+			s.SetPortState(testIPv4+":443", &state.PortState{})
+			s.SetCertificateState(
+				testIPv4+":443:"+testHostname, &state.CertificateState{},
+			)
+		}
+	}()
+
+	for {
+		select {
+		case <-written:
+			return
+		default:
+		}
+
+		// json.Marshal ranges over each of the snapshot's maps.
+		_, err := json.Marshal(s.GetSnapshot())
+		if err != nil {
+			t.Fatal(err)
+		}
 	}
 }