Render admin page errors in the normal layout (closes #382)

Every 400, 403, 404 and 500 on an admin page now answers with an error page in the normal layout: the status, one fixed line explaining it, and a link back to the webhook list, or to sign-in when nobody is signed in. Unknown paths reach it through the router's not-found handler, a refused form token through the CSRF middleware, and a panic through a recoverer each admin page route group installs first. Status codes are unchanged, and the page always sends Cache-Control: no-store.

If the error page fails to render, the answer is the same status in plain text; if it panics, the answer is a 500. The receiver, the healthcheck and /metrics keep their plain answers.

Model: opus-5-5

internal/handlers/handlers.go

@@ -142,6 +142,7 @@ func New(
 		"source_edit.html":   parsePageTemplate("source_edit.html"),
 		"source_logs.html":   parsePageTemplate("source_logs.html"),
 		"target_edit.html":   parsePageTemplate("target_edit.html"),
+		"error.html":         parsePageTemplate("error.html"),
 	}
 
 	lc.Append(fx.Hook{
@@ -153,6 +154,16 @@ func New(
 	return s, nil
 }
 
+// HandleErrorPage returns a handler that answers every request with
+// the error page for status. The router uses it for unknown paths, the
+// CSRF middleware for a refused form, and each admin page route
+// group's recoverer for a panic.
+func (s *Handlers) HandleErrorPage(status int) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		s.renderError(w, r, status)
+	}
+}
+
 func (s *Handlers) respondJSON(
 	w http.ResponseWriter,
 	_ *http.Request,
@@ -170,15 +181,76 @@ func (s *Handlers) respondJSON(
 	}
 }
 
-// serverError logs an error and sends a 500 response.
+// serverError logs an error and answers with the 500 error page.
 func (s *Handlers) serverError(
-	w http.ResponseWriter, msg string, err error,
+	w http.ResponseWriter, r *http.Request, msg string, err error,
 ) {
 	s.log.Error(msg, "error", err)
-	http.Error(
-		w, "Internal server error",
-		http.StatusInternalServerError,
-	)
+	s.renderError(w, r, http.StatusInternalServerError)
+}
+
+// renderError answers with status and the error page: the normal
+// layout, one fixed line explaining the status, and a link back to the
+// webhook list, or to sign-in when nobody is signed in.
+//
+// It renders the page itself rather than through renderTemplate,
+// whose own failure comes here. If the error page cannot render
+// either, the answer is the same status in plain text: never a second
+// attempt, and never a different status.
+func (s *Handlers) renderError(
+	w http.ResponseWriter,
+	r *http.Request,
+	status int,
+) {
+	// The page names the signed-in user, and some error pages are
+	// served outside the routes where NoCache runs.
+	w.Header().Set("Cache-Control", "no-store")
+
+	data := s.pageData(r, map[string]any{
+		"Status":     status,
+		"StatusText": http.StatusText(status),
+		"Message":    errorPageText(status),
+	})
+
+	var buf bytes.Buffer
+
+	err := s.templates["error.html"].Execute(&buf, data)
+	if err != nil {
+		s.log.Error("failed to render error page", "error", err)
+		http.Error(w, http.StatusText(status), status)
+
+		return
+	}
+
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	w.WriteHeader(status)
+
+	_, err = buf.WriteTo(w)
+	if err != nil {
+		s.log.Error("failed to write error page", "error", err)
+	}
+}
+
+// errorPageText is the line the error page shows for status. It is
+// fixed per status, so the page tells the reader no more than the
+// plain-text answers it replaced did.
+func errorPageText(status int) string {
+	switch status {
+	case http.StatusBadRequest:
+		return "The request could not be read."
+	case http.StatusForbidden:
+		return "The request was refused. If it came from a form " +
+			"left open for a long time, reload the page and try " +
+			"again."
+	case http.StatusNotFound:
+		return "There is nothing here. It may have been deleted, " +
+			"or the address may be wrong."
+	case http.StatusServiceUnavailable:
+		return "The server is busy. Please try again in a moment."
+	default: // http.StatusInternalServerError
+		return "Something went wrong on the server. Please try " +
+			"again."
+	}
 }
 
 // UserInfo represents user information for templates
@@ -231,14 +303,17 @@ func (s *Handlers) renderTemplate(
 			"template not found",
 			"template", pageTemplate,
 		)
-		http.Error(
-			w, "Internal server error",
-			http.StatusInternalServerError,
-		)
+		s.renderError(w, r, http.StatusInternalServerError)
 
 		return
 	}
 
+	s.executeTemplate(w, r, tmpl, s.pageData(r, data))
+}
+
+// pageData adds the fields the shared layout renders to a page's own
+// data.
+func (s *Handlers) pageData(r *http.Request, data any) any {
 	userInfo := s.getUserInfo(r)
 	csrfToken := middleware.CSRFToken(r)
 
@@ -252,19 +327,16 @@ func (s *Handlers) renderTemplate(
 		m["User"] = userInfo
 		m["CSRFToken"] = csrfToken
 		m["Version"] = version
-		s.executeTemplate(w, tmpl, m)
 
-		return
+		return m
 	}
 
-	wrapper := templateDataWrapper{
+	return templateDataWrapper{
 		User:      userInfo,
 		CSRFToken: csrfToken,
 		Version:   version,
 		Data:      data,
 	}
-
-	s.executeTemplate(w, tmpl, wrapper)
 }
 
 // executeTemplate renders the template into a buffer and writes to
@@ -277,6 +349,7 @@ func (s *Handlers) renderTemplate(
 // this reason.
 func (s *Handlers) executeTemplate(
 	w http.ResponseWriter,
+	r *http.Request,
 	tmpl *template.Template,
 	data any,
 ) {
@@ -287,10 +360,7 @@ func (s *Handlers) executeTemplate(
 		s.log.Error(
 			"failed to execute template", "error", err,
 		)
-		http.Error(
-			w, "Internal server error",
-			http.StatusInternalServerError,
-		)
+		s.renderError(w, r, http.StatusInternalServerError)
 
 		return
 	}