Rewrite the README sentence by sentence (closes #157)

The old text failed the issue's prose rules: a 60-word sentence on the
content security policy, a markdown table of settings, comma-chained
lists of batch sizes and error codes, undefined jargon and an edge case
in the opening. The new text leads with what RouteWatch is, why it
exists and how to run it, then the pages, the API and the blocklists,
then the settings, memory and upaas, and last the design and the
development workflow. Every statement was checked against the code on
next. The PR body lists where the old text disagreed with the code.

Model: fable-5-1

TODO.md

@@ -35,13 +35,6 @@ tested.
 
 # Completed Steps
 
-- 2026-10-27: the tests of `internal/routewatch` no longer fail on a loaded
-  host. Five of them gave `HandleMessage` two seconds to apply a full prefix
-  batch, which under the race detector can take longer. A test now waits up to
-  30 seconds for each step it expects (closes #213)
-- 2026-10-27: the server works out the home page's cards every minute until it
-  stops. It used to work them out only once, at startup: the end of the context
-  that `Start` is given stopped the refreshes (closes #211)
 - 2026-10-27: README "Rationale" says why RouteWatch exists: to answer our other
   services' questions about IP addresses, from its own routing table and the
   WHOIS details it keeps. It still says what RIS Live does not give (closes

internal/routewatch/app_integration_internal_test.go

@@ -509,6 +509,8 @@ func announcementFeed(prefixes []string) string {
 func TestShutdownWritesTheUpdatesQueuedInTheStreamer(t *testing.T) {
 	t.Parallel()
 
+	const maxWait = 10 * time.Second
+
 	prefixes := []string{"192.0.2.0/24", "198.51.100.0/24", "203.0.113.0/24"}
 	feed := announcementFeed(prefixes)
 
@@ -554,9 +556,9 @@ func TestShutdownWritesTheUpdatesQueuedInTheStreamer(t *testing.T) {
 	for range cap(linesSeen) {
 		select {
 		case <-linesSeen:
-		case <-time.After(handleMessageTimeout):
+		case <-time.After(maxWait):
 			t.Fatalf("the streamer did not read %d lines within %s",
-				cap(linesSeen), handleMessageTimeout)
+				cap(linesSeen), maxWait)
 		}
 	}
 
@@ -569,8 +571,8 @@ func TestShutdownWritesTheUpdatesQueuedInTheStreamer(t *testing.T) {
 
 	select {
 	case <-shutDown:
-	case <-time.After(handleMessageTimeout):
-		t.Fatalf("Shutdown did not return within %s", handleMessageTimeout)
+	case <-time.After(maxWait):
+		t.Fatalf("Shutdown did not return within %s", maxWait)
 	}
 
 	store.mu.Lock()
@@ -609,14 +611,19 @@ func freePort(t *testing.T) int {
 
 // TestShutdownReturnsByItsDeadlineWhileAWriteIsBlocked starts the HTTP server
 // and has the AS handler start a write that the store holds until the test
-// ends, past Shutdown's deadline. Shutdown must return without waiting for the
-// write, with the HTTP server stopped, and must neither checkpoint nor close
-// the database: the real one would wait for the write.
+// ends, past Shutdown's deadline. Shutdown must return within its deadline
+// plus a small margin, with the HTTP server stopped, and must neither
+// checkpoint nor close the database: the real one would wait for the write.
 // Before the fix Shutdown waited for the write.
 func TestShutdownReturnsByItsDeadlineWhileAWriteIsBlocked(t *testing.T) {
 	t.Parallel()
 
-	const deadline = 100 * time.Millisecond
+	const (
+		deadline = 100 * time.Millisecond
+		// margin is how long Shutdown may take after its deadline, to stop
+		// the HTTP server.
+		margin = 2 * time.Second
+	)
 
 	blocking := newBlockingStore()
 	defer blocking.releaseWrites()
@@ -660,9 +667,9 @@ func TestShutdownReturnsByItsDeadlineWhileAWriteIsBlocked(t *testing.T) {
 
 	select {
 	case <-shutDown:
-	case <-time.After(deadline + handleMessageTimeout):
+	case <-time.After(deadline + margin):
 		t.Fatalf("Shutdown did not return within %s of its deadline while "+
-			"a write was blocked", handleMessageTimeout)
+			"a write was blocked", margin)
 	}
 
 	var dialer net.Dialer
@@ -737,6 +744,8 @@ func (s *closeOrderStore) record(call string) {
 func TestShutdownCheckpointsAndClosesTheDatabaseLast(t *testing.T) {
 	t.Parallel()
 
+	const deadline = 10 * time.Second
+
 	store := &closeOrderStore{Store: newMockStore()}
 	log := logger.New()
 	cfg := &config.Config{}
@@ -754,7 +763,7 @@ func TestShutdownCheckpointsAndClosesTheDatabaseLast(t *testing.T) {
 		Path: ristypes.ASPath{Sequence: []int{testASNA}},
 	})
 
-	ctx, cancel := context.WithTimeout(t.Context(), handleMessageTimeout)
+	ctx, cancel := context.WithTimeout(t.Context(), deadline)
 	defer cancel()
 
 	rw.Shutdown(ctx)

internal/routewatch/batchwrite_internal_test.go

@@ -19,13 +19,9 @@ import (
 )
 
 const (
-	// handleMessageTimeout is how long a test waits for a step it expects,
-	// such as HandleMessage returning or a write starting, before it fails.
-	// Only a step that never comes should reach it. On a loaded host, under
-	// the race detector, HandleMessage takes seconds to apply a full prefix
-	// batch. A test that hangs still fails with its own message before go
-	// test's 90-second timeout.
-	handleMessageTimeout = 30 * time.Second
+	// handleMessageTimeout is how long a test waits for HandleMessage to
+	// return, or for a write to start, before it fails.
+	handleMessageTimeout = 2 * time.Second
 
 	// stillWaitingAfter is how long a test watches a HandleMessage that must
 	// wait. One that does not wait returns well within it.

internal/routewatch/prefixhandler_table_internal_test.go

@@ -32,6 +32,10 @@ const (
 	firstManyPrefix = "10.0.0.0/32"
 )
 
+// tableWriteTimeout is how long a test waits for the flush timer to write the
+// routing table's changes: a few ticks of it.
+const tableWriteTimeout = 5 * prefixBatchTimeout
+
 // tableCase is one test of the routing table in memory: the messages handed to
 // the prefix handler, and for each prefix the peers that carry it with each
 // origin AS after them.
@@ -272,9 +276,9 @@ func TestPrefixHandlerWritesTheTableChangesEachSecond(t *testing.T) {
 				t.Fatalf("wrote %+v, want the pair of %s and AS%d with "+
 					"removed %t", changes, prefix, testASNB, step.wantRemoved)
 			}
-		case <-time.After(handleMessageTimeout):
+		case <-time.After(tableWriteTimeout):
 			t.Fatalf("the routing table's change was not written within %s",
-				handleMessageTimeout)
+				tableWriteTimeout)
 		}
 	}
 }

internal/server/home_internal_test.go

@@ -6,7 +6,6 @@ import (
 	"strconv"
 	"strings"
 	"testing"
-	"testing/synctest"
 	"time"
 
 	"git.eeqj.de/sneak/routewatch/internal/database"
@@ -342,66 +341,6 @@ func TestStartedServerWorksOutTheCards(t *testing.T) {
 	}
 }
 
-// TestStartedServerWorksOutTheCardsUntilStop starts a server with a context
-// that ends as soon as Start returns. It runs in a synctest bubble, whose clock
-// is fake: time.Sleep there moves the clock on and returns at once. The server
-// must work the cards out again a minute later, and no more after Stop. Each
-// time it works them out, it keeps a new copy. Before the fix the end of
-// Start's context stopped the goroutine that works them out.
-func TestStartedServerWorksOutTheCardsUntilStop(t *testing.T) {
-	t.Parallel()
-
-	// The server is made outside the bubble. The streamer's metrics start a
-	// goroutine that never returns, and a bubble waits for each of its
-	// goroutines to return.
-	s := newServerWithTable(t, newCardsTable())
-
-	synctest.Test(t, func(t *testing.T) {
-		ctx, cancel := context.WithCancel(t.Context())
-
-		err := s.Start(ctx)
-		if err != nil {
-			t.Fatalf("Start: %v", err)
-		}
-
-		cancel()
-
-		// The bubble's clock moves only while each of its goroutines waits
-		// on the bubble, and the goroutine that serves HTTP waits on the
-		// network. The test sends no request, so it closes the HTTP server.
-		_ = s.srv.Close()
-
-		synctest.Wait()
-
-		started := s.cards.Load()
-		if started == nil {
-			t.Fatal("the server did not work out the cards when it started")
-		}
-
-		time.Sleep(homeCardsRefreshInterval)
-		synctest.Wait()
-
-		if s.cards.Load() == started {
-			t.Error("the server did not work out the cards again a minute " +
-				"after its start context ended")
-		}
-
-		err = s.Stop(t.Context())
-		if err != nil {
-			t.Fatalf("Stop: %v", err)
-		}
-
-		stopped := s.cards.Load()
-
-		time.Sleep(homeCardsRefreshInterval)
-		synctest.Wait()
-
-		if s.cards.Load() != stopped {
-			t.Error("the server worked out the cards again after Stop")
-		}
-	})
-}
-
 // waitUntil fails the test unless done reports true within maxWait.
 func waitUntil(t *testing.T, maxWait time.Duration, done func() bool) {
 	t.Helper()

internal/server/server.go

@@ -82,12 +82,6 @@ type Server struct {
 	// cards is the copy of the home page's cards that the pages serve, nil
 	// until the server first works them out
 	cards atomic.Pointer[homeCards]
-
-	// stopCards ends the goroutine that works out the cards, and
-	// cardsStopped is closed once it has returned. Both are nil until Start
-	// starts the goroutine.
-	stopCards    context.CancelFunc
-	cardsStopped chan struct{}
 }
 
 // New creates a new HTTP server that reads routes from table, the routing
@@ -117,8 +111,7 @@ func New(
 // Start listens on the configured port and serves HTTP in the background.
 // It returns an error if it cannot listen, for example because the port is
 // already in use. ctx bounds opening the port, not serving. Once listening,
-// the server works out the home page's cards every minute until Stop: the end
-// of ctx does not stop it.
+// the server works out the home page's cards every minute until ctx ends.
 func (s *Server) Start(ctx context.Context) error {
 	const (
 		network           = "tcp"
@@ -155,22 +148,16 @@ func (s *Server) Start(ctx context.Context) error {
 		}
 	}()
 
-	ctx, s.stopCards = context.WithCancel(context.WithoutCancel(ctx))
-	s.cardsStopped = make(chan struct{})
-
 	go func() {
-		defer close(s.cardsStopped)
-
 		s.keepHomeCardsFresh(ctx, homeCardsRefreshInterval)
 	}()
 
 	return nil
 }
 
-// Stop stops the goroutine that works out the home page's cards, and waits
-// until it has returned or ctx ends. It then stops the HTTP server. It waits,
-// until ctx ends, for the requests in progress to finish, and then closes the
-// connections of those still running and returns ctx's error.
+// Stop stops the HTTP server. It waits, until ctx ends, for the requests in
+// progress to finish, and then closes the connections of those still running
+// and returns ctx's error.
 func (s *Server) Stop(ctx context.Context) error {
 	if s.srv == nil {
 		return nil
@@ -178,16 +165,6 @@ func (s *Server) Stop(ctx context.Context) error {
 
 	s.logger.Info("Stopping HTTP server")
 
-	// Start returns before it starts the goroutine when it cannot listen.
-	if s.stopCards != nil {
-		s.stopCards()
-
-		select {
-		case <-s.cardsStopped:
-		case <-ctx.Done():
-		}
-	}
-
 	err := s.srv.Shutdown(ctx)
 	if err != nil {
 		return errors.Join(err, s.srv.Close())