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,6 +35,17 @@ tested.
 
 # Completed Steps
 
+- 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
+  #204)
+- 2026-10-27: every JSON answer carries `@meta`. A panic on a JSON route answers
+  500 with the JSON error body. `/status.json` and the health check answer 405
+  with the JSON error body to any method they do not take. The 500 and the 405
+  used to have an empty body. The home page's IP lookup shows the whole JSON
+  answer, `@meta` included. It used to show only the answer's `data`, or only
+  the message of an error answer. A test checks `@meta` on every JSON route, in
+  its successes and its errors (closes #201)
 - 2026-10-27: every value in a JSON answer that has a unit is a number, with the
   unit at the end of its field name. `@meta.execution_time` is now
   `execution_time_ms`. The stats' `uptime`, `connection_duration` and

internal/server/handlers_internal_test.go

@@ -75,7 +75,6 @@ const (
 	asPagePath           = "/as/64500"
 	asJSONPath           = "/api/v1/as/64500"
 	prefixLengthPagePath = "/prefixlength/24"
-	statusJSONPath       = "/status.json"
 	statsPath            = "/api/v1/stats"
 )
 
@@ -1109,7 +1108,7 @@ func TestJSONRoutesDoNotSendErrorDetails(t *testing.T) {
 		path     string
 		wantCode int
 	}{
-		{"/.well-known/healthcheck.json", http.StatusServiceUnavailable},
+		{healthCheckPath, http.StatusServiceUnavailable},
 		{statusJSONPath, http.StatusInternalServerError},
 		{statsPath, http.StatusInternalServerError},
 		{asJSONPath, http.StatusInternalServerError},

internal/server/middleware.go

@@ -16,6 +16,7 @@ import (
 	"time"
 
 	"github.com/go-chi/chi/v5"
+	"github.com/go-chi/chi/v5/middleware"
 )
 
 // responseWriter wraps http.ResponseWriter to capture the response
@@ -154,7 +155,8 @@ func deadlinePassed(ctx context.Context) bool {
 // has passed, it answers 504 with the error message "Request timeout". A 4xx
 // keeps its status, with the status's standard text as the message. For other
 // errors, it returns "Internal server error", with status 500 if the original
-// status was 200.
+// status was 200. A panic in the handler answers 500 with "Internal server
+// error" too.
 //
 // Non-JSON responses are passed through unchanged.
 func JSONValidationMiddleware(next http.Handler) http.Handler {
@@ -166,8 +168,9 @@ func JSONValidationMiddleware(next http.Handler) http.Handler {
 			statusCode:     http.StatusOK,
 		}
 
-		// Serve the request
-		next.ServeHTTP(rw, r)
+		// Serve the request. Recoverer logs a panic in the handler and turns it
+		// into a 500 without a body, which gets the JSON error body below.
+		middleware.Recoverer(next).ServeHTTP(rw, r)
 
 		// Check if it's meant to be a JSON response
 		contentType := rw.Header().Get("Content-Type")

internal/server/middleware_internal_test.go

@@ -2,6 +2,7 @@ package server
 
 import (
 	"bytes"
+	"context"
 	"encoding/json"
 	"io"
 	"log/slog"
@@ -119,7 +120,7 @@ func TestJSONAnswersPutNoUnitInAString(t *testing.T) {
 	paths := []string{
 		statusJSONPath,
 		statsPath,
-		"/.well-known/healthcheck.json",
+		healthCheckPath,
 		"/api/v1/ip/" + untrustedPeerAddr,
 		"/ip/" + untrustedPeerAddr,
 		asJSONPath,
@@ -156,6 +157,144 @@ func TestJSONAnswersPutNoUnitInAString(t *testing.T) {
 	}
 }
 
+// TestJSONAnswersCarryMeta sends requests to every JSON route through the
+// server's router, and checks that each answer carries @meta with its three
+// fields. The answers include successes, and errors that the handlers, the
+// router and the middleware write. Before the fix a panic in a handler, and a
+// method /status.json or the health check does not take, answered with an
+// empty body (https://git.eeqj.de/sneak/routewatch/issues/201).
+func TestJSONAnswersCarryMeta(t *testing.T) {
+	t.Parallel()
+
+	// JSON routes whose handlers write nothing or panic, so that the JSON
+	// check on the route writes the error answer itself.
+	const (
+		writesNothingPath = "/writes-nothing.json"
+		panicsPath        = "/panics.json"
+	)
+
+	s := newServerWithTestRoutes(t)
+	s.resolver = &fakeResolver{}
+	s.streamer.GetMetricsTracker().SetConnected(true)
+	s.router.Get(writesNothingPath, JSONValidationMiddleware(http.HandlerFunc(
+		func(http.ResponseWriter, *http.Request) {})).ServeHTTP)
+	s.router.Get(panicsPath, JSONValidationMiddleware(http.HandlerFunc(
+		func(http.ResponseWriter, *http.Request) { panic(errDiskIO) })).ServeHTTP)
+
+	tests := []struct {
+		method   string
+		path     string
+		wantCode int
+	}{
+		// Answers that succeed
+		{http.MethodGet, statusJSONPath, http.StatusOK},
+		{http.MethodGet, healthCheckPath, http.StatusOK},
+		{http.MethodGet, "/ip", http.StatusOK},
+		{http.MethodGet, ownAddressPath, http.StatusOK},
+		{http.MethodGet, "/ip/" + addrInTestPrefixV4, http.StatusOK},
+		{http.MethodGet, statsPath, http.StatusOK},
+		{http.MethodGet, "/api/v1/ip/" + addrInTestPrefixV4, http.StatusOK},
+		{http.MethodGet, asJSONPath, http.StatusOK},
+		{http.MethodGet, "/api/v1/prefix/" + testPrefixV4, http.StatusOK},
+		{http.MethodGet, "/api/v1/search/as?q=google", http.StatusOK},
+		// Errors the handlers write
+		{http.MethodGet, "/ip/no-such-host.example", http.StatusBadRequest},
+		{http.MethodGet, "/api/v1/ip/no-such-host.example", http.StatusBadRequest},
+		{http.MethodGet, "/api/v1/as/foo", http.StatusBadRequest},
+		{http.MethodGet, "/api/v1/as/0", http.StatusNotFound},
+		{http.MethodGet, "/api/v1/prefix/192.0.2.0/33", http.StatusBadRequest},
+		{http.MethodGet, "/api/v1/prefix/198.51.100.0/24", http.StatusNotFound},
+		{http.MethodGet, "/api/v1/search/as", http.StatusBadRequest},
+		// Errors the router and the middleware write
+		{http.MethodGet, "/api/v1/no-such-route", http.StatusNotFound},
+		{http.MethodGet, "/ip/192.0.2.1/nothing", http.StatusNotFound},
+		{http.MethodPost, statsPath, http.StatusMethodNotAllowed},
+		{http.MethodPost, ownAddressPath, http.StatusMethodNotAllowed},
+		{http.MethodPost, statusJSONPath, http.StatusMethodNotAllowed},
+		{http.MethodPut, healthCheckPath, http.StatusMethodNotAllowed},
+		{http.MethodGet, writesNothingPath, http.StatusInternalServerError},
+		{http.MethodGet, panicsPath, http.StatusInternalServerError},
+	}
+
+	for _, tt := range tests {
+		checkAnswerCarriesMeta(t, s, httptest.NewRequestWithContext(
+			t.Context(), tt.method, tt.path, nil), tt.wantCode)
+	}
+
+	// A request whose time limit has already passed answers 504. The handlers
+	// write the answers of the first five routes, and the JSON check on the
+	// route writes the last.
+	pastTimeLimit, cancel := context.WithDeadline(t.Context(), time.Now())
+	defer cancel()
+
+	for _, path := range []string{
+		statusJSONPath, statsPath, "/ip/" + addrInTestPrefixV4,
+		"/api/v1/ip/" + addrInTestPrefixV4, asJSONPath, writesNothingPath,
+	} {
+		checkAnswerCarriesMeta(t, s, httptest.NewRequestWithContext(
+			pastTimeLimit, http.MethodGet, path, nil), http.StatusGatewayTimeout)
+	}
+
+	// With a store whose reads fail, the health check answers 503, and the
+	// handlers of the other routes 500.
+	failing := New(failingDB{}, newTestTable(),
+		streamer.New(logger.New(), metrics.New()), logger.New(), &config.Config{})
+	failing.resolver = &fakeResolver{}
+
+	checkAnswerCarriesMeta(t, failing, httptest.NewRequestWithContext(
+		t.Context(), http.MethodGet, healthCheckPath, nil),
+		http.StatusServiceUnavailable)
+
+	for _, path := range []string{
+		statusJSONPath, statsPath, asJSONPath,
+		"/api/v1/ip/" + addrInTestPrefixV4, "/ip/" + addrInTestPrefixV4,
+	} {
+		checkAnswerCarriesMeta(t, failing, httptest.NewRequestWithContext(
+			t.Context(), http.MethodGet, path, nil), http.StatusInternalServerError)
+	}
+}
+
+// checkAnswerCarriesMeta serves req through the server's router, and checks
+// that it answers wantCode with @meta and its three fields.
+func checkAnswerCarriesMeta(
+	t *testing.T, s *Server, req *http.Request, wantCode int,
+) {
+	t.Helper()
+
+	// The values README "API v1" gives the two fields that never change.
+	const (
+		wantTimeZone   = "UTC"
+		wantAPIVersion = 1
+	)
+
+	name := req.Method + " " + req.URL.String()
+
+	rec := httptest.NewRecorder()
+	s.router.ServeHTTP(rec, req)
+
+	if rec.Code != wantCode {
+		t.Errorf("%s: status %d, want %d; body %s", name, rec.Code, wantCode, rec.Body)
+	}
+
+	var answer map[string]any
+
+	err := json.Unmarshal(rec.Body.Bytes(), &answer)
+	if err != nil {
+		t.Errorf("%s: decoding the answer %q: %v", name, rec.Body, err)
+
+		return
+	}
+
+	meta, _ := answer[jsonKeyMeta].(map[string]any)
+	_, timeIsNumber := meta[metaKeyExecutionTimeMs].(float64)
+
+	if meta[metaKeyTimeZone] != wantTimeZone ||
+		meta[metaKeyAPIVersion] != float64(wantAPIVersion) || !timeIsNumber {
+		t.Errorf("%s: @meta %v, want time_zone %q, api_version %d and a "+
+			"number in execution_time_ms", name, meta, wantTimeZone, wantAPIVersion)
+	}
+}
+
 // stringsIn returns every string in a decoded JSON value, at any depth.
 func stringsIn(value any) []string {
 	var found []string

internal/server/routes.go

@@ -8,8 +8,8 @@ import (
 	"github.com/go-chi/chi/v5/middleware"
 )
 
-// The error messages the JSON routes under /api/v1 and /ip answer with when no
-// route matches the path, and when none takes the method.
+// The error messages the JSON routes answer with when no route matches the
+// path, and when the route does not take the method.
 const (
 	notFoundMessage         = "Not found"
 	methodNotAllowedMessage = "Method not allowed"
@@ -19,6 +19,13 @@ const (
 	jsonRoutesAllow = "GET, HEAD"
 )
 
+// The paths of the status figures and the health check, the two JSON routes
+// outside /api/v1 and /ip.
+const (
+	statusJSONPath  = "/status.json"
+	healthCheckPath = "/.well-known/healthcheck.json"
+)
+
 // setupRoutes configures the HTTP routes
 func (s *Server) setupRoutes() {
 	r := chi.NewRouter()
@@ -32,6 +39,8 @@ func (s *Server) setupRoutes() {
 	r.Use(middleware.RequestID)
 	r.Use(RealIPMiddleware(s.trustedProxies))
 	r.Use(RequestLoggerMiddleware(s.logger.Logger)) // Structured request logging
+	// Recoverer answers a panic on a page. JSONValidationMiddleware recovers a
+	// panic on a JSON route itself, so that the answer is JSON with @meta.
 	r.Use(middleware.Recoverer)
 	r.Use(JSONResponseMiddleware)
 	// Timeout must come after JSONResponseMiddleware, which sends its answer
@@ -43,11 +52,6 @@ func (s *Server) setupRoutes() {
 	// Routes
 	r.Get("/", s.handleIndex())
 	r.Get("/status", s.handleStatusHTML())
-	r.Get("/status.json", JSONValidationMiddleware(s.handleStatusJSON()).ServeHTTP)
-	r.Get(
-		"/.well-known/healthcheck.json",
-		JSONValidationMiddleware(s.handleHealthCheck()).ServeHTTP,
-	)
 
 	// AS and prefix detail pages
 	r.Get("/as/{asn}", s.handleASDetail())
@@ -70,6 +74,21 @@ func (s *Server) setupRoutes() {
 		s.writeJSONError(w, http.StatusMethodNotAllowed, methodNotAllowedMessage)
 	}
 
+	// The status figures and the health check. chi sets one 405 answer for a
+	// whole router. These two routes are on the pages' router, whose 405 stays
+	// chi's own. So each method they do not take is routed to the JSON 405
+	// here.
+	r.Get(statusJSONPath, JSONValidationMiddleware(s.handleStatusJSON()).ServeHTTP)
+	r.Get(healthCheckPath, JSONValidationMiddleware(s.handleHealthCheck()).ServeHTTP)
+
+	for _, method := range []string{
+		http.MethodPost, http.MethodPut, http.MethodPatch, http.MethodDelete,
+		http.MethodOptions, http.MethodTrace, http.MethodConnect,
+	} {
+		r.MethodFunc(method, statusJSONPath, jsonMethodNotAllowed)
+		r.MethodFunc(method, healthCheckPath, jsonMethodNotAllowed)
+	}
+
 	// IP info JSON endpoints (replaces old /ip redirect)
 	r.Route("/ip", func(r chi.Router) {
 		r.Use(JSONValidationMiddleware)

internal/server/routes_internal_test.go

@@ -17,7 +17,7 @@ func TestRoutesAnswerHEAD(t *testing.T) {
 
 	s := newServerWithTestRoutes(t)
 
-	for _, path := range []string{"/", statsPath, "/ip", "/ip/"} {
+	for _, path := range []string{"/", statusJSONPath, statsPath, "/ip", "/ip/"} {
 		rec := httptest.NewRecorder()
 		s.router.ServeHTTP(rec, httptest.NewRequestWithContext(
 			t.Context(), http.MethodHead, path, nil))
@@ -31,10 +31,13 @@ func TestRoutesAnswerHEAD(t *testing.T) {
 
 // TestJSONRoutesAnswerUnmatchedRequestsWithJSONErrors sends a method the JSON
 // routes do not take, and a path none of them matches, to each group of JSON
-// routes through the server's router. Each must answer with the JSON error
+// routes through the server's router. It also sends a method they do not take
+// to /status.json and the health check. Each must answer with the JSON error
 // body, and a 405 must name the methods the routes take in its Allow header.
 // Before the fix a 405 said "Internal server error" and a 404 was chi's plain
 // text answer (https://git.eeqj.de/sneak/routewatch/issues/111).
+// /status.json and the health check gave chi's empty 405
+// (https://git.eeqj.de/sneak/routewatch/issues/201).
 func TestJSONRoutesAnswerUnmatchedRequestsWithJSONErrors(t *testing.T) {
 	t.Parallel()
 
@@ -48,6 +51,14 @@ func TestJSONRoutesAnswerUnmatchedRequestsWithJSONErrors(t *testing.T) {
 	}{
 		{http.MethodPost, statsPath, http.StatusMethodNotAllowed, methodNotAllowedMessage},
 		{http.MethodPost, "/ip/", http.StatusMethodNotAllowed, methodNotAllowedMessage},
+		{
+			http.MethodDelete, statusJSONPath,
+			http.StatusMethodNotAllowed, methodNotAllowedMessage,
+		},
+		{
+			http.MethodOptions, healthCheckPath,
+			http.StatusMethodNotAllowed, methodNotAllowedMessage,
+		},
 		{http.MethodGet, "/api/v1/nothing", http.StatusNotFound, notFoundMessage},
 		{http.MethodGet, "/ip/192.0.2.1/nothing", http.StatusNotFound, notFoundMessage},
 	}

internal/templates/index.html

@@ -714,7 +714,8 @@
                 });
         });
 
-        // IP lookup
+        // IP lookup: show the whole JSON answer, its @meta and an error answer
+        // included, as the IP information API card does.
         document.getElementById('ip-form').addEventListener('submit', function(e) {
             e.preventDefault();
             const ip = document.getElementById('ip-input').value.trim();
@@ -730,18 +731,11 @@
 
             fetch('/ip/' + encodeURIComponent(ip))
                 .then(response => response.json())
-                .then(response => {
-                    contentEl.classList.remove('loading');
-                    if (response.status === 'error') {
-                        contentEl.className = 'error';
-                        contentEl.textContent = 'Error: ' + response.error.msg;
-                    } else {
-                        contentEl.className = '';
-                        contentEl.textContent = JSON.stringify(response.data, null, 2);
-                    }
+                .then(answer => {
+                    contentEl.className = '';
+                    contentEl.textContent = JSON.stringify(answer, null, 2);
                 })
                 .catch(error => {
-                    contentEl.classList.remove('loading');
                     contentEl.className = 'error';
                     contentEl.textContent = 'Error: ' + error.message;
                 });