feat: mail notifications for watched nodes (user management part E)

.github/workflows/deploy.yml

@@ -529,7 +529,8 @@ jobs:
               "adminEmails": ["admin@e2e.test"],
               "publicBaseUrl": "http://localhost:13582",
               "mail": { "provider": "fake", "fromEmail": "noreply@e2e.test" },
-              "channelProposals": { "enabled": true }
+              "channelProposals": { "enabled": true },
+              "notifications": { "enabled": true }
             }
           }
           JSON

cmd/server/admin_stats_handlers.go

@@ -30,6 +30,15 @@ type guessedAccountJSON struct {
 	Failed      int    `json:"failed"`
 }
 
+// adminNotifyJSON: notification figures, counts only (watch lists are
+// private). Present only with notifications on.
+type adminNotifyJSON struct {
+	MailsLast24h   int `json:"mailsLast24h"`
+	MaxMailsPerDay int `json:"maxMailsPerDay"`
+	Watches        int `json:"watches"`
+	WatchingUsers  int `json:"watchingUsers"`
+}
+
 type adminStatsJSON struct {
 	Total           int                  `json:"total"`
 	Active          int                  `json:"active"`
@@ -47,6 +56,7 @@ type adminStatsJSON struct {
 	FailedLogins24h int                  `json:"failedLogins24h"`
 	Mail7d          mailCountsJSON       `json:"mail7d"`
 	Guessing        []guessedAccountJSON `json:"guessing"`
+	Notify          *adminNotifyJSON     `json:"notify,omitempty"`
 }
 
 func adminStatsFrom(st users.Stats) adminStatsJSON {
@@ -72,5 +82,21 @@ func (s *Server) handleAdminStats(w http.ResponseWriter, _ *http.Request, _ *use
 		writeError(w, http.StatusInternalServerError, "internal error")
 		return
 	}
-	writeJSON(w, adminStatsFrom(st))
+	out := adminStatsFrom(st)
+	if s.auth.notify != nil {
+		total, _, err := s.auth.st.NotifyMailCounts(s.auth.notify.now().Add(-24 * time.Hour))
+		if err != nil {
+			log.Printf("[users] admin stats notification mails: %v", err)
+			writeError(w, http.StatusInternalServerError, "internal error")
+			return
+		}
+		watches, watching, err := s.auth.st.NotifyWatchStats()
+		if err != nil {
+			log.Printf("[users] admin stats watches: %v", err)
+			writeError(w, http.StatusInternalServerError, "internal error")
+			return
+		}
+		out.Notify = &adminNotifyJSON{MailsLast24h: total, MaxMailsPerDay: s.auth.set.notify.maxMailsPerDay, Watches: watches, WatchingUsers: watching}
+	}
+	writeJSON(w, out)
 }

cmd/server/auth_e2e.go

@@ -4,7 +4,9 @@ package main
 
 // E2E-only hooks, compiled only with -tags e2etest (CI's corescope-server-e2e):
 // the "fake" mail provider and GET /__e2e/last-mail, which returns the newest
-// fake mail so Playwright can follow its link. Never part of a release build.
+// fake mail so Playwright can follow its link, and GET /__e2e/unsubscribe-link,
+// which returns a user's notification unsubscribe link. Never part of a
+// release build.
 
 import (
 	"net/http"
@@ -19,6 +21,10 @@ type e2eMail struct {
 	Text    string `json:"text"`
 }
 
+type e2eLink struct {
+	Link string `json:"link"`
+}
+
 func init() {
 	fakeMailerAllowed = true
 	e2eRoutes = func(s *Server, r *mux.Router) {
@@ -35,5 +41,20 @@ func init() {
 			}
 			writeJSON(w, e2eMail{To: m.To, Subject: m.Subject, Text: m.Text})
 		}).Methods("GET")
+		// The unsubscribe link a notification mail would carry, so the E2E
+		// can follow it without waiting for a real state change.
+		r.HandleFunc("/__e2e/unsubscribe-link", func(w http.ResponseWriter, req *http.Request) {
+			u, err := s.auth.st.GetByEmail(req.URL.Query().Get("email"))
+			if err != nil {
+				writeError(w, http.StatusNotFound, "no such user")
+				return
+			}
+			p, err := s.auth.st.NotifyPrefsFor(u.ID)
+			if err != nil {
+				writeError(w, http.StatusInternalServerError, "internal error")
+				return
+			}
+			writeJSON(w, e2eLink{Link: s.auth.link("unsubscribe", p.UnsubToken)})
+		}).Methods("GET")
 	}
 }

cmd/server/auth_e2e_on_test.go

@@ -15,3 +15,18 @@ func TestE2ELastMailReturnsNewestFakeMail(t *testing.T) {
 		t.Fatalf("unexpected mail: %+v", m)
 	}
 }
+
+func TestE2EUnsubscribeLink(t *testing.T) {
+	f := newAuthFixture(t)
+	expectStatus(t, f.do("GET", "/__e2e/unsubscribe-link?email=nobody@example.test", nil), 404)
+	c := f.registerAndActivate(t, "e2e@example.test", "E2E", "correct horse battery")
+	w := f.do("GET", "/__e2e/unsubscribe-link?email=e2e@example.test", nil)
+	expectStatus(t, w, 200)
+	p, err := f.st.NotifyPrefsFor(c.me.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if l := decode[e2eLink](t, w); l.Link != testBase+"/#/account/unsubscribe?token="+p.UnsubToken {
+		t.Fatalf("link = %q", l.Link)
+	}
+}

cmd/server/auth_mail.go

@@ -8,17 +8,24 @@ import (
 	"regexp"
 	"strings"
 	"time"
+	"unicode"
 
 	"github.com/meshcore-analyzer/mailer"
 	"github.com/meshcore-analyzer/users"
 )
 
+// mailLine is one linked line of a mail: a list item in HTML, the text and
+// the URL on their own lines in plain text.
+type mailLine struct{ text, url string }
+
 type mailContent struct {
 	subject     string
 	greeting    string
 	paragraphs  []string
+	lines       []mailLine // after the paragraphs
 	actionLabel string
 	actionURL   string
+	footer      *mailLine // replaces the default footer when set
 }
 
 // link builds {publicBaseUrl}/#/account/{page}?token=… (never from the
@@ -27,22 +34,52 @@ func (a *authService) link(page, token string) string {
 	return a.set.baseURL.String() + "/#/account/" + page + "?token=" + url.QueryEscape(token)
 }
 
+// mailSafeText makes a name chosen by someone else safe for one line of a
+// mail: control characters (line breaks and tabs included) and bidi
+// overrides and isolates (U+202A-U+202E, U+2066-U+2069) become a space,
+// runs of spaces collapse and the ends are trimmed. The HTML part escapes
+// the result as usual.
+func mailSafeText(s string) string {
+	return strings.Join(strings.Fields(strings.Map(func(r rune) rune {
+		if unicode.IsControl(r) || (r >= 0x202A && r <= 0x202E) || (r >= 0x2066 && r <= 0x2069) {
+			return ' '
+		}
+		return r
+	}, s)), " ")
+}
+
 func (a *authService) render(to, toName, tag string, c mailContent) mailer.Message {
-	footer := "You received this because this address was used on " + a.set.baseURL.Host +
-		". If that was not you, you can ignore this mail."
 	var text, h strings.Builder
 	text.WriteString(c.greeting + "\n\n")
 	h.WriteString("<p>" + html.EscapeString(c.greeting) + "</p>")
 	for _, p := range c.paragraphs {
 		text.WriteString(p + "\n\n")
 		h.WriteString("<p>" + html.EscapeString(p) + "</p>")
 	}
+	if len(c.lines) > 0 {
+		h.WriteString("<ul>")
+		for _, l := range c.lines {
+			l.text = mailSafeText(l.text)
+			text.WriteString("- " + l.text + "\n  " + l.url + "\n")
+			h.WriteString(`<li><a href="` + html.EscapeString(l.url) + `">` + html.EscapeString(l.text) + `</a></li>`)
+		}
+		h.WriteString("</ul>")
+		text.WriteString("\n")
+	}
 	if c.actionURL != "" {
 		text.WriteString(c.actionLabel + ":\n" + c.actionURL + "\n\n")
 		h.WriteString(`<p><a href="` + html.EscapeString(c.actionURL) + `">` + html.EscapeString(c.actionLabel) + `</a></p>`)
 	}
-	text.WriteString(footer + "\n")
-	h.WriteString(`<p style="color:#666;font-size:12px">` + html.EscapeString(footer) + `</p>`)
+	if c.footer != nil {
+		text.WriteString(c.footer.text + "\n" + c.footer.url + "\n")
+		h.WriteString(`<p style="color:#666;font-size:12px">` + html.EscapeString(c.footer.text) + ` <a href="` +
+			html.EscapeString(c.footer.url) + `">` + html.EscapeString(c.footer.url) + `</a></p>`)
+	} else {
+		footer := "You received this because this address was used on " + a.set.baseURL.Host +
+			". If that was not you, you can ignore this mail."
+		text.WriteString(footer + "\n")
+		h.WriteString(`<p style="color:#666;font-size:12px">` + html.EscapeString(footer) + `</p>`)
+	}
 	return mailer.Message{To: to, ToName: toName, Subject: "[" + a.set.fromName + "] " + c.subject,
 		HTML: h.String(), Text: text.String(), Tag: tag}
 }

cmd/server/auth_mail_test.go

@@ -78,3 +78,17 @@ func TestLogStartupShowsAbsoluteUsersDBPath(t *testing.T) {
 		t.Fatalf("log line = %q, want the absolute path %q", buf.String(), want)
 	}
 }
+
+func TestRenderLinesAndFooter(t *testing.T) {
+	a, _ := newTestAuthService(t)
+	m := a.render("x@example.org", "X", "notify", mailContent{subject: "S", greeting: "Hi",
+		lines:  []mailLine{{text: "<b>n</b>: offline", url: "https://e.org/#/nodes/ab"}},
+		footer: &mailLine{text: "Stop these mails:", url: "https://e.org/#/account/unsubscribe?token=t"}})
+	if !strings.Contains(m.HTML, `<ul><li><a href="https://e.org/#/nodes/ab">&lt;b&gt;n&lt;/b&gt;: offline</a></li></ul>`) ||
+		!strings.Contains(m.Text, "- <b>n</b>: offline\n  https://e.org/#/nodes/ab\n") ||
+		!strings.Contains(m.HTML, `Stop these mails: <a href="https://e.org/#/account/unsubscribe?token=t">`) ||
+		!strings.Contains(m.Text, "Stop these mails:\nhttps://e.org/#/account/unsubscribe?token=t\n") ||
+		strings.Contains(m.Text, "If that was not you") {
+		t.Fatalf("rendered = %q / %q", m.HTML, m.Text)
+	}
+}

cmd/server/auth_routes.go

@@ -41,6 +41,9 @@ func (s *Server) registerAuthRoutes(r *mux.Router) {
 	if s.auth.set.proposals.enabled {
 		s.registerProposalRoutes(r)
 	}
+	if s.auth.notify != nil {
+		s.registerNotifyRoutes(r)
+	}
 	// The webhook exists only when a secret is configured.
 	if s.auth.set.webhookSecret != "" {
 		r.HandleFunc("/api/mail/brevo/webhook", s.handleBrevoWebhook).Methods("POST")

cmd/server/auth_service.go

@@ -32,10 +32,14 @@ type authService struct {
 	approvedMu sync.Mutex
 	approved   atomic.Pointer[[]string]
 
+	// notify evaluates node notifications; nil unless
+	// userManagement.notifications.enabled.
+	notify *notifier
+
 	warnIndistinct sync.Once
 	stop           chan struct{}
 	stopOnce       sync.Once
-	wg             sync.WaitGroup // the janitor
+	wg             sync.WaitGroup // the janitor and the notifier
 	auditWG        sync.WaitGroup // in-flight auditAsync writes
 }
 
@@ -81,6 +85,16 @@ func (s *Server) initUserManagement(measurementDBPath string) error {
 		defer s.auth.wg.Done()
 		s.auth.janitor(time.Hour)
 	}()
+	if set.notify.enabled {
+		s.auth.notify = newNotifier(s.auth, serverNotifySource{s: s}, time.Now)
+		s.auth.wg.Add(1)
+		go func() {
+			defer s.auth.wg.Done()
+			s.auth.notify.loop(s.auth.stop, set.notify.interval)
+		}()
+		log.Printf("[notify] node notifications enabled: every %s, at most %d mails per user and %d in total per 24 hours",
+			set.notify.interval, set.notify.perUserPerDay, set.notify.maxMailsPerDay)
+	}
 	return nil
 }