Merge branch 'main' into cluster2

Revert "add tzdata to docker arm build"

.github/workflows/build.yaml

@@ -8,13 +8,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Install Go
-        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
-          go-version: '1.26.x'
+          go-version-file: '.go-version'
       - name: Install node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: '24'
           cache: 'npm'

.github/workflows/docs.yaml

@@ -9,10 +9,10 @@ jobs:
     steps:
       -
         name: Checkout ntfy code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       -
         name: Checkout docs pages code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           repository: binwiederhier/ntfy-docs.github.io
           path: build/ntfy-docs.github.io

.github/workflows/release.yaml

@@ -25,19 +25,19 @@ jobs:
       NTFY_TEST_S3_URL: ${{ secrets.NTFY_TEST_S3_URL }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Install Go
-        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
-          go-version: '1.26.x'
+          go-version-file: '.go-version'
       - name: Install node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: '24'
           cache: 'npm'
           cache-dependency-path: './web/package-lock.json'
       - name: Docker login
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        uses: docker/login-action@371161bbe7024a29a25c5e19bfcbc0804fe9ad2c # v4.5.2
         with:
           username: ${{ github.repository_owner }}
           password: ${{ secrets.DOCKER_HUB_TOKEN }}

.github/workflows/test.yaml

@@ -25,13 +25,13 @@ jobs:
       NTFY_TEST_S3_URL: ${{ secrets.NTFY_TEST_S3_URL }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Install Go
-        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
-          go-version: '1.26.x'
+          go-version-file: '.go-version'
       - name: Install node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: '24'
           cache: 'npm'

.go-version

@@ -0,0 +1 @@
+1.26.5

CODE_OF_CONDUCT.md

@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement via Discord/Matrix (binwiederhier),
-or email (ntfy@heckel.io). All complaints will be reviewed and investigated promptly 
+or email (contact@mail.ntfy.sh). All complaints will be reviewed and investigated promptly 
 and fairly.
 
 All community leaders are obligated to respect the privacy and security of the

Dockerfile-build

@@ -48,6 +48,9 @@ ADD ./webpush ./webpush
 ADD ./attachment ./attachment
 ADD ./mail ./mail
 ADD ./s3 ./s3
+ADD ./action ./action
+ADD ./template/gotext ./template/gotext
+
 RUN --mount=type=cache,target=/go/pkg/mod --mount=type=cache,target=/root/.cache/go-build make VERSION=$VERSION COMMIT=$COMMIT cli-linux-server
 
 FROM alpine

Makefile

@@ -5,7 +5,9 @@ PIP := pip3
 VERSION := $(shell git describe --tag)
 COMMIT := $(shell git rev-parse --short HEAD)
 
-.PHONY:
+# FORCE is an always-out-of-date target with no recipe; listing it as a prerequisite
+# forces that target's recipe to run every time (the classic "FORCE target" idiom).
+FORCE:
 
 help:
 	@echo "Typical commands (more see below):"
@@ -43,6 +45,7 @@ help:
 	@echo "  make web-deps                   - Install web app dependencies (npm install the universe)"
 	@echo "  make web-build                  - Actually build the web app"
 	@echo "  make web-lint                   - Run eslint on the web app"
+	@echo "  make web-test                   - Run vitest unit tests for the web app"
 	@echo "  make web-fmt                    - Run prettier on the web app"
 	@echo "  make web-fmt-check              - Run prettier on the web app, but don't change anything"
 	@echo
@@ -52,7 +55,9 @@ help:
 	@echo "  make docs-build                 - Actually build the documentation"
 	@echo
 	@echo "Test/check:"
-	@echo "  make test                       - Run tests"
+	@echo "  make test                       - Run all tests (Go + web)"
+	@echo "  make cli-test                   - Run Go tests only"
+	@echo "  make web-test                   - Run web app tests only"
 	@echo "  make race                       - Run tests with -race flag"
 	@echo "  make coverage                   - Run tests and show coverage"
 	@echo "  make coverage-html              - Run tests and show coverage (as HTML)"
@@ -82,12 +87,12 @@ help:
 
 # Building everything
 
-clean: .PHONY
+clean: FORCE
 	rm -rf dist build server/docs server/site
 
 build: web docs cli
 
-update: web-deps-update cli-deps-update docs-deps-update
+update: web-deps-update cli-deps-update docs-deps-update go-check
 	docker pull alpine
 
 docker-dev:
@@ -119,7 +124,7 @@ build-deps-ubuntu:
 
 docs: docs-deps docs-build
 
-docs-venv: .PHONY
+docs-venv: FORCE
 	$(PYTHON) -m venv ./venv
 
 docs-build: docs-venv
@@ -128,7 +133,7 @@ docs-build: docs-venv
 docs-deps: docs-venv
 	(. venv/bin/activate && $(PIP) install -r requirements.txt)
 
-docs-deps-update: .PHONY
+docs-deps-update: FORCE
 	(. venv/bin/activate && $(PIP) install -r requirements.txt --upgrade)
 
 
@@ -163,6 +168,9 @@ web-fmt-check:
 web-lint:
 	cd web && $(NPM) run lint
 
+web-test:
+	cd web && $(NPM) run test
+
 # Main server/client build
 
 cli: cli-deps
@@ -265,17 +273,21 @@ cli-build-results:
 
 # Test/check targets
 
-check: test web-fmt-check fmt-check vet web-lint lint staticcheck
+check: test web-fmt-check fmt-check vet web-lint lint staticcheck template-check go-check
 
-checkv: testv web-fmt-check fmt-check vet web-lint lint staticcheck
+checkv: testv web-fmt-check fmt-check vet web-lint lint staticcheck template-check go-check
 
-test: .PHONY
+test: cli-test web-test
+
+testv: cli-testv web-test
+
+cli-test: FORCE
 	go test $(shell go list -f '{{if .TestGoFiles}}{{.ImportPath}}{{end}}' ./... | grep -vE 'ntfy/v2/(test|examples|tools)')
 
-testv: .PHONY
+cli-testv: FORCE
 	go test -v $(shell go list -f '{{if .TestGoFiles}}{{.ImportPath}}{{end}}' ./... | grep -vE 'ntfy/v2/(test|examples|tools)')
 
-race: .PHONY
+race: FORCE
 	go test -v -race $(shell go list -f '{{if .TestGoFiles}}{{.ImportPath}}{{end}}' ./... | grep -vE 'ntfy/v2/(test|examples|tools)')
 
 coverage:
@@ -305,17 +317,73 @@ vet:
 
 lint:
 	which golint || go install golang.org/x/lint/golint@latest
-	go list ./... | grep -v /vendor/ | xargs -L1 golint -set_exit_status
+	go list ./... | grep -v /vendor/ | grep -vE 'ntfy/v2/template/gotext' | xargs -L1 golint -set_exit_status
 
-staticcheck: .PHONY
+staticcheck: FORCE
 	rm -rf build/staticcheck
 	which staticcheck || go install honnef.co/go/tools/cmd/staticcheck@latest
 	mkdir -p build/staticcheck
 	ln -s "go" build/staticcheck/go
-	PATH="$(PWD)/build/staticcheck:$(PATH)" staticcheck ./...
+	PATH="$(PWD)/build/staticcheck:$(PATH)" staticcheck $$(go list ./... | grep -vE 'ntfy/v2/template/gotext')
 	rm -rf build/staticcheck
 
 
+# Vendored template targets (see template/README.md)
+
+TEMPLATE_GO_VERSION := go$(shell cat .go-version 2>/dev/null)
+
+update-template:
+	@if [ "$$(go env GOVERSION)" != "$(TEMPLATE_GO_VERSION)" ]; then \
+		echo "ERROR: local Go $$(go env GOVERSION) != $(TEMPLATE_GO_VERSION) pinned in .go-version."; \
+		echo "Bump .go-version and install that toolchain first: go install golang.org/dl/$(TEMPLATE_GO_VERSION)@latest && $(TEMPLATE_GO_VERSION) download"; \
+		exit 1; \
+	fi
+	src="$$(go env GOROOT)/src"; \
+	rm -f template/gotext/*.go template/gotext/fmtsort/*.go; \
+	for f in $$(go list -f '{{range .GoFiles}}{{.}} {{end}}' text/template); do cp "$$src/text/template/$$f" template/gotext/; done; \
+	for f in $$(go list -f '{{range .GoFiles}}{{.}} {{end}}' internal/fmtsort); do cp "$$src/internal/fmtsort/$$f" template/gotext/fmtsort/; done; \
+	sed -i 's/^package template$$/package gotext/' template/gotext/*.go; \
+	sed -i 's#"internal/fmtsort"#"heckel.io/ntfy/v2/template/gotext/fmtsort"#' template/gotext/*.go; \
+	( cd template/gotext && for p in patches/*.patch; do echo "Applying $$p"; git apply "$$p" || exit 1; done )
+	go env GOVERSION > template/gotext/GENERATED_FROM
+	@echo "Regenerated template/gotext/ from $(TEMPLATE_GO_VERSION) (files enumerated via 'go list'); review with 'git diff'."
+
+template-check: FORCE
+	@if [ "$$(cat template/gotext/GENERATED_FROM)" != "$(TEMPLATE_GO_VERSION)" ]; then \
+		echo "ERROR: template/gotext was generated from $$(cat template/gotext/GENERATED_FROM), but .go-version pins $(TEMPLATE_GO_VERSION). Run 'make update-template' on the pinned Go."; \
+		exit 1; \
+	fi
+	@if [ "$$(go env GOVERSION)" != "$(TEMPLATE_GO_VERSION)" ]; then \
+		echo "SKIP: local Go $$(go env GOVERSION) != pinned $(TEMPLATE_GO_VERSION); skipping vendored template content check (version marker already verified)."; \
+		exit 0; \
+	fi
+	@tmp=$$(mktemp -d); src="$$(go env GOROOT)/src"; \
+	mkdir -p "$$tmp/gotext/fmtsort"; \
+	for f in $$(go list -f '{{range .GoFiles}}{{.}} {{end}}' text/template); do cp "$$src/text/template/$$f" "$$tmp/gotext/"; done; \
+	for f in $$(go list -f '{{range .GoFiles}}{{.}} {{end}}' internal/fmtsort); do cp "$$src/internal/fmtsort/$$f" "$$tmp/gotext/fmtsort/"; done; \
+	sed -i 's/^package template$$/package gotext/' "$$tmp/gotext/"*.go; \
+	sed -i 's#"internal/fmtsort"#"heckel.io/ntfy/v2/template/gotext/fmtsort"#' "$$tmp/gotext/"*.go; \
+	cp template/gotext/patches/*.patch "$$tmp/"; \
+	( cd "$$tmp/gotext" && for p in "$$tmp"/*.patch; do git apply "$$p" || exit 1; done ); \
+	if diff -rq -x 'README.md' -x 'GENERATED_FROM' -x 'patches' "$$tmp/gotext" template/gotext >/dev/null 2>&1; then \
+		rm -rf "$$tmp"; \
+	else \
+		echo "ERROR: template/gotext/ drifted from GOROOT+patches (or its file set changed). Run 'make update-template' on Go $(TEMPLATE_GO_VERSION):"; \
+		diff -rq -x 'README.md' -x 'GENERATED_FROM' -x 'patches' "$$tmp/gotext" template/gotext; \
+		rm -rf "$$tmp"; exit 1; \
+	fi
+
+# go-check is advisory only (never fails): it warns when the pinned Go (.go-version) is behind the
+# latest upstream release, so template/gotext doesn't silently fall behind on text/template fixes.
+go-check: FORCE
+	@latest=$$(curl -s --max-time 10 'https://go.dev/VERSION?m=text' 2>/dev/null | head -1); \
+	if [ -n "$$latest" ] && [ "$$latest" != "$(TEMPLATE_GO_VERSION)" ]; then \
+		echo ""; \
+		echo "note: latest Go is $$latest, but template/gotext is pinned to $(TEMPLATE_GO_VERSION) (.go-version)."; \
+		echo "      to bump: install $$latest, set .go-version to $${latest#go}, then run 'make update-template'."; \
+	fi
+
+
 # Releasing targets
 
 release: clean cli-deps release-checks docs web check
@@ -326,6 +394,10 @@ release-snapshot: clean cli-deps docs web check
 
 release-checks:
 	$(eval LATEST_TAG := $(shell git describe --abbrev=0 --tags | cut -c2-))
+	if [ "$$(go env GOVERSION)" != "go$$(cat .go-version)" ]; then\
+		echo "ERROR: releases must use the pinned Go toolchain (go$$(cat .go-version) from .go-version), but this is $$(go env GOVERSION). This also ensures 'make check' enforces (not skips) the template/gotext drift check.";\
+		exit 1;\
+	fi
 	if ! grep -q $(LATEST_TAG) docs/install.md; then\
 	 	echo "ERROR: Must update docs/install.md with latest tag first.";\
 	 	exit 1;\

README.md

@@ -84,8 +84,6 @@ Thank you to our commercial sponsors, who help keep the service running and the
 
 <a href="https://m.do.co/c/442b929528db"><img src="https://opensource.nyc3.cdn.digitaloceanspaces.com/attribution/assets/SVG/DO_Logo_horizontal_blue.svg" width="201px"></a>
 
-<a href="https://www.magicbell.com/?utm_source=ntfy"><img src="assets/sponsors/magicbell.png" width="180px"></a>
-
 <a href="https://go.warp.dev/ntfy"><img src="https://raw.githubusercontent.com/warpdotdev/brand-assets/refs/heads/main/Logos/Warp-Wordmark-Black.png" width="160px"></a>
 
 And a big fat **Thank You** to the individuals who have sponsored ntfy in the past, or are still sponsoring ntfy:
@@ -268,6 +266,7 @@ Third-party libraries and resources:
 * [github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3) (MIT) is used to provide the persistent message cache
 * [Firebase Admin SDK](https://github.com/firebase/firebase-admin-go) (Apache 2.0) is used to send FCM messages
 * [github/gemoji](https://github.com/github/gemoji) (MIT) is used for emoji support (specifically the [emoji.json](https://raw.githubusercontent.com/github/gemoji/master/db/emoji.json) file)
+* Go's [text/template](https://pkg.go.dev/text/template) (BSD-3-Clause) is vendored under [template/gotext/](template/gotext/) with a small patch adding an execution deadline (see [template/gotext/README.md](template/gotext/README.md))
 * [Lightbox with vanilla JS](https://yossiabramov.com/blog/vanilla-js-lightbox) as a lightbox on the landing page 
 * [HTTP middleware for gzip compression](https://gist.github.com/CJEnright/bc2d8b8dc0c1389a9feeddb110f822d7) (MIT) is used for serving static files
 * [Regex for auto-linking](https://github.com/bryanwoods/autolink-js) (MIT) is used to highlight links (the library is not used)

action/action.go

@@ -1,4 +1,6 @@
-package server
+// Package action parses the "action buttons" that can be attached to a notification, in both the
+// JSON and the human-readable "simple" format described at https://ntfy.sh/docs/publish/#action-buttons.
+package action
 
 import (
 	"encoding/json"
@@ -37,10 +39,10 @@ type actionParser struct {
 	pos   int
 }
 
-// parseActions parses the actions string as described in https://ntfy.sh/docs/publish/#action-buttons.
+// Parse parses the actions string as described in https://ntfy.sh/docs/publish/#action-buttons.
 // It supports both a JSON representation (if the string begins with "[", see parseActionsFromJSON),
 // and the "simple" format, which is more human-readable, but harder to parse (see parseActionsFromSimple).
-func parseActions(s string) (actions []*model.Action, err error) {
+func Parse(s string) (actions []*model.Action, err error) {
 	// Parse JSON or simple format
 	s = strings.TrimSpace(s)
 	if strings.HasPrefix(s, "[") {

action/action_test.go

@@ -1,4 +1,4 @@
-package server
+package action
 
 import (
 	"testing"
@@ -7,12 +7,12 @@ import (
 )
 
 func TestParseActions(t *testing.T) {
-	actions, err := parseActions("[]")
+	actions, err := Parse("[]")
 	require.Nil(t, err)
 	require.Empty(t, actions)
 
 	// Basic test
-	actions, err = parseActions("action=http, label=Open door, url=https://door.lan/open; view, Show portal, https://door.lan")
+	actions, err = Parse("action=http, label=Open door, url=https://door.lan/open; view, Show portal, https://door.lan")
 	require.Nil(t, err)
 	require.Equal(t, 2, len(actions))
 	require.Equal(t, "http", actions[0].Action)
@@ -23,7 +23,7 @@ func TestParseActions(t *testing.T) {
 	require.Equal(t, "https://door.lan", actions[1].URL)
 
 	// JSON
-	actions, err = parseActions(`[{"action":"http","label":"Open door","url":"https://door.lan/open"}, {"action":"view","label":"Show portal","url":"https://door.lan"}]`)
+	actions, err = Parse(`[{"action":"http","label":"Open door","url":"https://door.lan/open"}, {"action":"view","label":"Show portal","url":"https://door.lan"}]`)
 	require.Nil(t, err)
 	require.Equal(t, 2, len(actions))
 	require.Equal(t, "http", actions[0].Action)
@@ -34,7 +34,7 @@ func TestParseActions(t *testing.T) {
 	require.Equal(t, "https://door.lan", actions[1].URL)
 
 	// Other params
-	actions, err = parseActions("action=http, label=Open door, url=https://door.lan/open, body=this is a body, method=PUT")
+	actions, err = Parse("action=http, label=Open door, url=https://door.lan/open, body=this is a body, method=PUT")
 	require.Nil(t, err)
 	require.Equal(t, 1, len(actions))
 	require.Equal(t, "http", actions[0].Action)
@@ -44,7 +44,7 @@ func TestParseActions(t *testing.T) {
 	require.Equal(t, "this is a body", actions[0].Body)
 
 	// Extras with underscores
-	actions, err = parseActions("action=broadcast, label=Do a thing, extras.command=some command, extras.some_param=a parameter")
+	actions, err = Parse("action=broadcast, label=Do a thing, extras.command=some command, extras.some_param=a parameter")
 	require.Nil(t, err)
 	require.Equal(t, 1, len(actions))
 	require.Equal(t, "broadcast", actions[0].Action)
@@ -54,7 +54,7 @@ func TestParseActions(t *testing.T) {
 	require.Equal(t, "a parameter", actions[0].Extras["some_param"])
 
 	// Broadcast action with intent
-	actions, err = parseActions("action=broadcast, label=Do a thing, intent=io.heckel.ntfy.TEST_INTENT")
+	actions, err = Parse("action=broadcast, label=Do a thing, intent=io.heckel.ntfy.TEST_INTENT")
 	require.Nil(t, err)
 	require.Equal(t, 1, len(actions))
 	require.Equal(t, "broadcast", actions[0].Action)
@@ -62,7 +62,7 @@ func TestParseActions(t *testing.T) {
 	require.Equal(t, "io.heckel.ntfy.TEST_INTENT", actions[0].Intent)
 
 	// Headers with dashes
-	actions, err = parseActions("action=http, label=Send request, url=http://example.com, method=GET, headers.Content-Type=application/json, headers.Authorization=Basic sdasffsf")
+	actions, err = Parse("action=http, label=Send request, url=http://example.com, method=GET, headers.Content-Type=application/json, headers.Authorization=Basic sdasffsf")
 	require.Nil(t, err)
 	require.Equal(t, 1, len(actions))
 	require.Equal(t, "http", actions[0].Action)
@@ -72,7 +72,7 @@ func TestParseActions(t *testing.T) {
 	require.Equal(t, "Basic sdasffsf", actions[0].Headers["Authorization"])
 
 	// Quotes
-	actions, err = parseActions(`action=http, "Look ma, \"quotes\"; and semicolons", url=http://example.com`)
+	actions, err = Parse(`action=http, "Look ma, \"quotes\"; and semicolons", url=http://example.com`)
 	require.Nil(t, err)
 	require.Equal(t, 1, len(actions))
 	require.Equal(t, "http", actions[0].Action)
@@ -80,7 +80,7 @@ func TestParseActions(t *testing.T) {
 	require.Equal(t, `http://example.com`, actions[0].URL)
 
 	// Single quotes
-	actions, err = parseActions(`action=http, '"quotes" and \'single quotes\'', url=http://example.com`)
+	actions, err = Parse(`action=http, '"quotes" and \'single quotes\'', url=http://example.com`)
 	require.Nil(t, err)
 	require.Equal(t, 1, len(actions))
 	require.Equal(t, "http", actions[0].Action)
@@ -88,7 +88,7 @@ func TestParseActions(t *testing.T) {
 	require.Equal(t, `http://example.com`, actions[0].URL)
 
 	// Single quotes (JSON)
-	actions, err = parseActions(`action=http, Post it, url=http://example.com, body='{"temperature": 65}'`)
+	actions, err = Parse(`action=http, Post it, url=http://example.com, body='{"temperature": 65}'`)
 	require.Nil(t, err)
 	require.Equal(t, 1, len(actions))
 	require.Equal(t, "http", actions[0].Action)
@@ -97,7 +97,7 @@ func TestParseActions(t *testing.T) {
 	require.Equal(t, `{"temperature": 65}`, actions[0].Body)
 
 	// Out of order
-	actions, err = parseActions(`label="Out of order!" , action="http", url=http://example.com`)
+	actions, err = Parse(`label="Out of order!" , action="http", url=http://example.com`)
 	require.Nil(t, err)
 	require.Equal(t, 1, len(actions))
 	require.Equal(t, "http", actions[0].Action)
@@ -105,7 +105,7 @@ func TestParseActions(t *testing.T) {
 	require.Equal(t, `http://example.com`, actions[0].URL)
 
 	// Spaces
-	actions, err = parseActions(`action = http, label = 'this is a label', url = "http://google.com"`)
+	actions, err = Parse(`action = http, label = 'this is a label', url = "http://google.com"`)
 	require.Nil(t, err)
 	require.Equal(t, 1, len(actions))
 	require.Equal(t, "http", actions[0].Action)
@@ -113,7 +113,7 @@ func TestParseActions(t *testing.T) {
 	require.Equal(t, `http://google.com`, actions[0].URL)
 
 	// Non-ASCII
-	actions, err = parseActions(`action = http, 'Кохайтеся а не воюйте, 💙🫤', url = "http://google.com"`)
+	actions, err = Parse(`action = http, 'Кохайтеся а не воюйте, 💙🫤', url = "http://google.com"`)
 	require.Nil(t, err)
 	require.Equal(t, 1, len(actions))
 	require.Equal(t, "http", actions[0].Action)
@@ -121,7 +121,7 @@ func TestParseActions(t *testing.T) {
 	require.Equal(t, `http://google.com`, actions[0].URL)
 
 	// Multiple actions, awkward spacing
-	actions, err = parseActions(`http , 'Make love, not war 💙🫤' , https://ntfy.sh ; view, " yo ", https://x.org, clear=true`)
+	actions, err = Parse(`http , 'Make love, not war 💙🫤' , https://ntfy.sh ; view, " yo ", https://x.org, clear=true`)
 	require.Nil(t, err)
 	require.Equal(t, 2, len(actions))
 	require.Equal(t, "http", actions[0].Action)
@@ -134,7 +134,7 @@ func TestParseActions(t *testing.T) {
 	require.Equal(t, true, actions[1].Clear)
 
 	// Copy action (simple format)
-	actions, err = parseActions("copy, Copy code, 1234")
+	actions, err = Parse("copy, Copy code, 1234")
 	require.Nil(t, err)
 	require.Equal(t, 1, len(actions))
 	require.Equal(t, "copy", actions[0].Action)
@@ -142,7 +142,7 @@ func TestParseActions(t *testing.T) {
 	require.Equal(t, "1234", actions[0].Value)
 
 	// Copy action (JSON)
-	actions, err = parseActions(`[{"action":"copy","label":"Copy OTP","value":"567890"}]`)
+	actions, err = Parse(`[{"action":"copy","label":"Copy OTP","value":"567890"}]`)
 	require.Nil(t, err)
 	require.Equal(t, 1, len(actions))
 	require.Equal(t, "copy", actions[0].Action)
@@ -150,7 +150,7 @@ func TestParseActions(t *testing.T) {
 	require.Equal(t, "567890", actions[0].Value)
 
 	// Copy action with clear
-	actions, err = parseActions("copy, Copy code, 1234, clear=true")
+	actions, err = Parse("copy, Copy code, 1234, clear=true")
 	require.Nil(t, err)
 	require.Equal(t, 1, len(actions))
 	require.Equal(t, "copy", actions[0].Action)
@@ -159,7 +159,7 @@ func TestParseActions(t *testing.T) {
 	require.Equal(t, true, actions[0].Clear)
 
 	// Copy action with explicit value key
-	actions, err = parseActions("action=copy, label=Copy token, clear=true, value=abc-123-def")
+	actions, err = Parse("action=copy, label=Copy token, clear=true, value=abc-123-def")
 	require.Nil(t, err)
 	require.Equal(t, 1, len(actions))
 	require.Equal(t, "copy", actions[0].Action)
@@ -168,56 +168,56 @@ func TestParseActions(t *testing.T) {
 	require.True(t, actions[0].Clear)
 
 	// Copy action without value (error)
-	_, err = parseActions("copy, Copy code")
+	_, err = Parse("copy, Copy code")
 	require.EqualError(t, err, "parameter 'value' is required for action 'copy'")
 
 	// Invalid syntax
-	_, err = parseActions(`label="Out of order!" x, action="http", url=http://example.com`)
+	_, err = Parse(`label="Out of order!" x, action="http", url=http://example.com`)
 	require.EqualError(t, err, "unexpected character 'x' at position 22")
 
-	_, err = parseActions(`label="", action="http", url=http://example.com`)
+	_, err = Parse(`label="", action="http", url=http://example.com`)
 	require.EqualError(t, err, "parameter 'label' is required")
 
-	_, err = parseActions(`label=, action="http", url=http://example.com`)
+	_, err = Parse(`label=, action="http", url=http://example.com`)
 	require.EqualError(t, err, "parameter 'label' is required")
 
-	_, err = parseActions(`label="xx", action="http", url=http://example.com, what is this anyway`)
+	_, err = Parse(`label="xx", action="http", url=http://example.com, what is this anyway`)
 	require.EqualError(t, err, "term 'what is this anyway' unknown")
 
-	_, err = parseActions(`fdsfdsf`)
+	_, err = Parse(`fdsfdsf`)
 	require.EqualError(t, err, "parameter 'action' cannot be 'fdsfdsf', valid values are 'view', 'broadcast', 'http' and 'copy'")
 
-	_, err = parseActions(`aaa=a, "bbb, 'ccc, ddd, eee "`)
+	_, err = Parse(`aaa=a, "bbb, 'ccc, ddd, eee "`)
 	require.EqualError(t, err, "key 'aaa' unknown")
 
-	_, err = parseActions(`action=http, label="omg the end quote is missing`)
+	_, err = Parse(`action=http, label="omg the end quote is missing`)
 	require.EqualError(t, err, "unexpected end of input, quote started at position 20")
 
-	_, err = parseActions(`;;;;`)
+	_, err = Parse(`;;;;`)
 	require.EqualError(t, err, "only 3 actions allowed")
 
-	_, err = parseActions(`,,,,,,;;`)
+	_, err = Parse(`,,,,,,;;`)
 	require.EqualError(t, err, "term '' unknown")
 
-	_, err = parseActions(`''";,;"`)
+	_, err = Parse(`''";,;"`)
 	require.EqualError(t, err, "unexpected character '\"' at position 2")
 
-	_, err = parseActions(`action=http, label=a label, body=somebody`)
+	_, err = Parse(`action=http, label=a label, body=somebody`)
 	require.EqualError(t, err, "parameter 'url' is required for action 'http'")
 
-	_, err = parseActions(`action=http, label=a label, url=http://ntfy.sh, method=HEAD, body=somebody`)
+	_, err = Parse(`action=http, label=a label, url=http://ntfy.sh, method=HEAD, body=somebody`)
 	require.EqualError(t, err, "parameter 'body' cannot be set if method is HEAD")
 
-	_, err = parseActions(`[ invalid json ]`)
+	_, err = Parse(`[ invalid json ]`)
 	require.EqualError(t, err, "JSON error: invalid character 'i' looking for beginning of value")
 
-	_, err = parseActions(`[ { "some": "object" } ]`)
+	_, err = Parse(`[ { "some": "object" } ]`)
 	require.EqualError(t, err, "parameter 'action' cannot be '', valid values are 'view', 'broadcast', 'http' and 'copy'")
 
-	_, err = parseActions("\x00\x01\xFFx\xFE")
+	_, err = Parse("\x00\x01\xFFx\xFE")
 	require.EqualError(t, err, "invalid utf-8 string")
 
-	_, err = parseActions(`http, label, http://x.org, clear=x`)
+	_, err = Parse(`http, label, http://x.org, clear=x`)
 	require.EqualError(t, err, "parameter 'clear' cannot be 'x', only boolean values are allowed (true/yes/1/false/no/0)")
 
 }

ban/service.go

@@ -0,0 +1,185 @@
+// Package ban implements the abuse ban-feed: it tracks per-prefix weighted "strikes" from rejected
+// requests and appends breaching prefixes to a ban file that fail2ban tails. Keying by prefix (not
+// by visitor) makes the accounting match the unit fail2ban bans, even for shared account visitors.
+package ban
+
+import (
+	"fmt"
+	"net/netip"
+	"os"
+	"sync"
+	"time"
+
+	"golang.org/x/time/rate"
+	"heckel.io/ntfy/v2/log"
+)
+
+const (
+	tag           = "ban"
+	pruneInterval = 10 * time.Minute
+	writeInterval = 3 * time.Second
+)
+
+// Config is the Service's config, kept separate from server.Config to avoid an import cycle.
+type Config struct {
+	File           string        // Ban file that fail2ban tails (must be non-empty; the caller decides whether the feature is enabled)
+	Window         time.Duration // Rolling window over which weighted strikes are counted
+	Threshold      int           // Weighted strikes per Window before a prefix is banned
+	Weights        Weights       // Code matcher -> strike weight (0 = exempt)
+	PrefixBitsIPv4 int           // Mask width for the ban unit, e.g. 32 (matches rate-limiting granularity)
+	PrefixBitsIPv6 int           // Mask width for the ban unit, e.g. 64
+}
+
+// tracker is the per-prefix strike state: a weighted breach detector plus timestamps for pruning and throttling.
+type tracker struct {
+	limiter *rate.Limiter
+	seen    time.Time // Last strike, for pruning idle prefixes
+	emitted time.Time // Last ban-line write for this prefix, throttles re-emits to once per Window
+}
+
+// Service owns the ban-feed: per-prefix strike accounting, buffered file writes, and idle-prefix
+// pruning. The caller owns the enable/disable decision -- only construct a Service when the feature
+// is on (see server.New, which builds one only when a ban file is configured).
+type Service struct {
+	conf      *Config
+	mu        sync.Mutex // Guards trackers and pending
+	trackers  map[netip.Prefix]*tracker
+	pending   []string      // Formatted ban lines buffered by Record, flushed to the ban file by runWriteLoop
+	writeDone chan struct{} // Closed when runWriteLoop exits after its final flush
+	closeChan chan struct{}
+	closeOnce sync.Once
+}
+
+// NewService builds a Service and starts its background loops. The caller must only call it when the
+// feature is enabled (conf non-nil, File non-empty); the Service does not model a disabled state.
+func NewService(conf *Config) *Service {
+	s := &Service{
+		conf:      conf,
+		trackers:  make(map[netip.Prefix]*tracker),
+		closeChan: make(chan struct{}),
+		writeDone: make(chan struct{}),
+	}
+	go s.runPruneLoop()
+	go s.runWriteLoop()
+	return s
+}
+
+// Record counts one rejection against the IP's prefix bucket and, on breach, buffers a ban line
+// (throttled to once per Window per prefix). No-ops for a non-4xx/5xx status or a zero-weight code.
+func (s *Service) Record(ip netip.Addr, httpCode, errorCode int) {
+	if httpCode < 400 {
+		return
+	}
+	weight := s.conf.Weights.WeightFor(errorCode)
+	if weight == 0 {
+		return // Weight 0: exempt, no strike
+	}
+	prefix := s.prefix(ip)
+	now := time.Now()
+
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	t := s.trackers[prefix]
+	if t == nil {
+		t = &tracker{limiter: rate.NewLimiter(rate.Limit(float64(s.conf.Threshold)/s.conf.Window.Seconds()), s.conf.Threshold)}
+		s.trackers[prefix] = t
+	}
+	t.seen = now
+	if t.limiter.AllowN(now, weight) {
+		return // Within the strike budget, no breach
+	}
+	if !t.emitted.IsZero() && now.Sub(t.emitted) < s.conf.Window {
+		return // Already emitted this prefix within the window (one ban line per prefix per window)
+	}
+	t.emitted = now
+	s.pending = append(s.pending, formatBanLine(now, ip, prefix, httpCode, errorCode))
+}
+
+// prefix masks ip to the ban unit (PrefixBitsIPv4/IPv6) -- what fail2ban bans, e.g. a whole /64.
+func (s *Service) prefix(ip netip.Addr) netip.Prefix {
+	if ip.Is4() {
+		return netip.PrefixFrom(ip, s.conf.PrefixBitsIPv4).Masked()
+	}
+	return netip.PrefixFrom(ip, s.conf.PrefixBitsIPv6).Masked()
+}
+
+// formatBanLine builds the "<RFC3339-UTC> <ip> <prefix> <http> <ntfy>" line the fail2ban filter
+// parses. The timestamp is captured at breach time, not flush time.
+func formatBanLine(t time.Time, ip netip.Addr, prefix netip.Prefix, httpCode, errorCode int) string {
+	return fmt.Sprintf("%s %s %s %d %d\n", t.UTC().Format(time.RFC3339), ip.String(), prefix.String(), httpCode, errorCode)
+}
+
+// runPruneLoop prunes idle prefixes until Close.
+func (s *Service) runPruneLoop() {
+	ticker := time.NewTicker(pruneInterval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ticker.C:
+			s.prune()
+		case <-s.closeChan:
+			return
+		}
+	}
+}
+
+// runWriteLoop flushes buffered ban lines every writeInterval, plus a final flush on Close.
+func (s *Service) runWriteLoop() {
+	defer close(s.writeDone)
+	ticker := time.NewTicker(writeInterval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ticker.C:
+			s.flush()
+		case <-s.closeChan:
+			s.flush()
+			return
+		}
+	}
+}
+
+// flush appends the buffered lines to the file in one open/write. Best-effort: a batch is dropped on
+// error. Concurrent calls are safe -- pending is drained under mu, so only one flush writes a batch.
+func (s *Service) flush() {
+	s.mu.Lock()
+	lines := s.pending
+	s.pending = nil
+	s.mu.Unlock()
+	if len(lines) == 0 {
+		return
+	}
+	f, err := os.OpenFile(s.conf.File, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
+	if err != nil {
+		log.Tag(tag).Err(err).Warn("Cannot open ban file %s, dropped %d ban(s)", s.conf.File, len(lines))
+		return
+	}
+	defer f.Close()
+	for i, line := range lines {
+		if _, err := f.WriteString(line); err != nil {
+			log.Tag(tag).Err(err).Warn("Cannot write to ban file %s, dropped %d ban(s)", s.conf.File, len(lines)-i)
+			return
+		}
+	}
+}
+
+// prune drops prefixes idle for a full Window -- their bucket has refilled, so forgetting them is a
+// no-op that bounds memory under a flood of distinct IPs.
+func (s *Service) prune() {
+	now := time.Now()
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	for prefix, t := range s.trackers {
+		if now.Sub(t.seen) >= s.conf.Window {
+			delete(s.trackers, prefix)
+		}
+	}
+}
+
+// Close stops the loops and blocks until the final flush completes. Idempotent.
+func (s *Service) Close() {
+	s.closeOnce.Do(func() {
+		close(s.closeChan)
+		<-s.writeDone
+	})
+}

ban/service_test.go

@@ -0,0 +1,253 @@
+package ban
+
+import (
+	"net/netip"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+var testIP = netip.MustParseAddr("1.2.3.4")
+
+// newTestService creates a Service wired for testing, with the given ban file, weighted-bucket
+// threshold, and weights, plus a 1-minute window (so the emit throttle only fires once per test).
+func newTestService(t *testing.T, banFile string, threshold int, weights map[string]int) *Service {
+	t.Helper()
+	s := NewService(&Config{
+		File:           banFile,
+		Window:         time.Minute,
+		Threshold:      threshold,
+		Weights:        weights,
+		PrefixBitsIPv4: 32,
+		PrefixBitsIPv6: 64,
+	})
+	t.Cleanup(s.Close)
+	return s
+}
+
+// flushAndRead forces a synchronous flush of the buffered bans (writes are otherwise async, on the
+// runWriteLoop ticker) and returns the ban file's lines.
+func flushAndRead(t *testing.T, s *Service, path string) []string {
+	t.Helper()
+	s.flush()
+	data, err := os.ReadFile(path)
+	require.NoError(t, err)
+	return strings.Split(strings.TrimRight(string(data), "\n"), "\n")
+}
+
+func TestService_Record_Weight2BansAtHalfThreshold(t *testing.T) {
+	banFile := filepath.Join(t.TempDir(), "ban.log")
+	// Threshold 10, code weight 2 -> the budget covers exactly 5 hits, so the 6th breaches.
+	s := newTestService(t, banFile, 10, map[string]int{"*": 2})
+	for i := 0; i < 5; i++ {
+		s.Record(testIP, 400, 40001)
+	}
+	s.flush()
+	require.NoFileExists(t, banFile) // 5 hits * weight 2 = 10 == budget, exactly at the limit, not over
+	s.Record(testIP, 400, 40001)     // 6th hit cannot be covered -> breach
+	lines := flushAndRead(t, s, banFile)
+	require.Len(t, lines, 1)
+	require.True(t, strings.HasSuffix(lines[0], " 1.2.3.4 1.2.3.4/32 400 40001")) // <ip> <prefix> <http> <ntfy-code>
+}
+
+func TestService_Record_Weight10BansFast(t *testing.T) {
+	banFile := filepath.Join(t.TempDir(), "ban.log")
+	// Threshold 10, code weight 10 -> a single hit drains the whole budget, so the 2nd breaches.
+	s := newTestService(t, banFile, 10, map[string]int{"42909": 10, "*": 1})
+	s.Record(testIP, 429, 42909)
+	s.flush()
+	require.NoFileExists(t, banFile)
+	s.Record(testIP, 429, 42909) // 2nd hit cannot be covered -> breach
+	lines := flushAndRead(t, s, banFile)
+	require.Len(t, lines, 1)
+	require.True(t, strings.HasSuffix(lines[0], " 1.2.3.4 1.2.3.4/32 429 42909"))
+}
+
+func TestService_Record_Weight0NeverBans(t *testing.T) {
+	banFile := filepath.Join(t.TempDir(), "ban.log")
+	// The legit-quota code is exempt (weight 0), so no number of hits ever bans.
+	s := newTestService(t, banFile, 10, map[string]int{"42908": 0, "*": 1})
+	for i := 0; i < 100; i++ {
+		s.Record(testIP, 429, 42908)
+	}
+	s.flush()
+	require.NoFileExists(t, banFile)
+}
+
+func TestService_Record_SingleBucketNoRelaxation(t *testing.T) {
+	banFile := filepath.Join(t.TempDir(), "ban.log")
+	// One shared bucket per prefix: different codes draw down the SAME budget, so mixing them creates
+	// no extra headroom (unlike per-code buckets, which would relax the effective limit for a mixed
+	// offender).
+	s := newTestService(t, banFile, 10, map[string]int{"403*": 2, "*": 1})
+	s.Record(testIP, 403, 40301) // weight 2 -> 8 left
+	s.Record(testIP, 403, 40301) // weight 2 -> 6 left
+	s.Record(testIP, 403, 40301) // weight 2 -> 4 left
+	s.flush()
+	require.NoFileExists(t, banFile)
+	for i := 0; i < 4; i++ {
+		s.Record(testIP, 400, 40001) // weight 1 each -> drains the remaining 4 -> 0 left
+	}
+	s.flush()
+	require.NoFileExists(t, banFile) // 6 + 4 = 10 == budget exactly, still not over
+	s.Record(testIP, 400, 40001)     // one more cannot be covered -> breach
+	lines := flushAndRead(t, s, banFile)
+	require.Len(t, lines, 1)
+}
+
+func TestService_Record_ExactLineFormat(t *testing.T) {
+	banFile := filepath.Join(t.TempDir(), "ban.log")
+	s := newTestService(t, banFile, 1, map[string]int{"*": 1})
+	before := time.Now().UTC().Truncate(time.Second)
+	for i := 0; i < 3; i++ {
+		s.Record(testIP, 429, 42901)
+	}
+	after := time.Now().UTC()
+	lines := flushAndRead(t, s, banFile)
+	require.Len(t, lines, 1)
+	parts := strings.Split(lines[0], " ")
+	require.Len(t, parts, 5) // "<timestamp> <ip> <prefix> <http-code> <ntfy-code>"
+	ts, err := time.Parse(time.RFC3339, parts[0])
+	require.NoError(t, err)
+	require.Equal(t, time.UTC, ts.Location())
+	require.False(t, ts.Before(before))
+	require.False(t, ts.After(after.Add(time.Second)))
+	require.Equal(t, "1.2.3.4", parts[1])    // full IP
+	require.Equal(t, "1.2.3.4/32", parts[2]) // masked to the default IPv4 prefix (/32)
+	require.Equal(t, "429", parts[3])        // HTTP status
+	require.Equal(t, "42901", parts[4])      // ntfy code
+}
+
+func TestService_Record_IPv6MaskedToPrefix(t *testing.T) {
+	banFile := filepath.Join(t.TempDir(), "ban.log")
+	s := newTestService(t, banFile, 1, map[string]int{"*": 1})
+	ip := netip.MustParseAddr("2001:db8::abcd")
+	for i := 0; i < 3; i++ {
+		s.Record(ip, 429, 42901)
+	}
+	parts := strings.Split(flushAndRead(t, s, banFile)[0], " ")
+	require.Len(t, parts, 5)
+	require.Equal(t, "2001:db8::abcd", parts[1]) // full IPv6 address
+	require.Equal(t, "2001:db8::/64", parts[2])  // masked to the default IPv6 prefix (/64)
+}
+
+func TestService_Record_PerPrefixIsolation(t *testing.T) {
+	// Each source prefix gets its own bucket: one IP hammering to a breach must not push a different,
+	// quiet IP over the edge. This is the whole point of keying by prefix instead of by visitor.
+	banFile := filepath.Join(t.TempDir(), "ban.log")
+	s := newTestService(t, banFile, 2, map[string]int{"*": 1})
+	noisy := netip.MustParseAddr("1.1.1.1")
+	quiet := netip.MustParseAddr("2.2.2.2")
+	for i := 0; i < 5; i++ {
+		s.Record(noisy, 429, 42901) // breaches its own bucket
+	}
+	s.Record(quiet, 429, 42901) // single hit, well under threshold
+	lines := flushAndRead(t, s, banFile)
+	require.Len(t, lines, 1) // only the noisy prefix is written
+	require.True(t, strings.HasSuffix(lines[0], " 1.1.1.1 1.1.1.1/32 429 42901"))
+}
+
+func TestService_Record_OncePerWindowThrottle(t *testing.T) {
+	// Once a prefix has been written, further breaches within the window must not re-append it, so a
+	// persistent offender produces exactly one line per window (mirrors the old per-visitor banEmit).
+	banFile := filepath.Join(t.TempDir(), "ban.log")
+	s := newTestService(t, banFile, 1, map[string]int{"*": 1})
+	for i := 0; i < 50; i++ {
+		s.Record(testIP, 429, 42901)
+	}
+	lines := flushAndRead(t, s, banFile)
+	require.Len(t, lines, 1)
+}
+
+func TestService_Record_BansPassedIP(t *testing.T) {
+	// The Service bans the exact IP passed to Record -- the caller passes the offending request's IP,
+	// which for an account-keyed visitor is not the visitor's stored IP.
+	banFile := filepath.Join(t.TempDir(), "ban.log")
+	s := newTestService(t, banFile, 1, map[string]int{"*": 1})
+	offender := netip.MustParseAddr("5.6.7.8")
+	for i := 0; i < 3; i++ {
+		s.Record(offender, 429, 42901)
+	}
+	parts := strings.Split(flushAndRead(t, s, banFile)[0], " ")
+	require.Equal(t, "5.6.7.8", parts[1])    // the IP passed to Record
+	require.Equal(t, "5.6.7.8/32", parts[2]) // its prefix
+}
+
+func TestService_Record_Ignores2xx3xx(t *testing.T) {
+	banFile := filepath.Join(t.TempDir(), "ban.log")
+	s := newTestService(t, banFile, 3, map[string]int{"*": 1})
+	// Success and redirects must never count toward a ban, even over the threshold -- otherwise a
+	// legit high-volume publisher (lots of 200s) would get banned.
+	for i := 0; i < 20; i++ {
+		s.Record(testIP, 200, 20000)
+		s.Record(testIP, 302, 30000)
+	}
+	s.flush()
+	require.NoFileExists(t, banFile)
+	// A 4xx over the same budget still gets written.
+	for i := 0; i < 5; i++ {
+		s.Record(testIP, 400, 40001)
+	}
+	lines := flushAndRead(t, s, banFile)
+	require.Len(t, lines, 1)
+	require.True(t, strings.HasSuffix(lines[0], " 1.2.3.4 1.2.3.4/32 400 40001"))
+}
+
+func TestService_Record_BuffersUntilFlush(t *testing.T) {
+	// Writes are async: a breach buffers the ban line rather than writing it synchronously on the
+	// request path. The line only reaches the file when runWriteLoop (or an explicit flush) runs.
+	banFile := filepath.Join(t.TempDir(), "ban.log")
+	s := newTestService(t, banFile, 1, map[string]int{"*": 1})
+	for i := 0; i < 3; i++ {
+		s.Record(testIP, 429, 42901)
+	}
+	require.NoFileExists(t, banFile) // not written synchronously
+	s.mu.Lock()
+	require.Len(t, s.pending, 1) // one line buffered (throttled to once per window)
+	s.mu.Unlock()
+	lines := flushAndRead(t, s, banFile)
+	require.Len(t, lines, 1)
+	require.True(t, strings.HasSuffix(lines[0], " 1.2.3.4 1.2.3.4/32 429 42901"))
+}
+
+func TestService_Close_FlushesPending(t *testing.T) {
+	// Close must flush buffered bans so nothing is lost on shutdown, and must block until it has.
+	banFile := filepath.Join(t.TempDir(), "ban.log")
+	s := NewService(&Config{File: banFile, Window: time.Minute, Threshold: 1, Weights: Weights{"*": 1}, PrefixBitsIPv4: 32, PrefixBitsIPv6: 64})
+	for i := 0; i < 3; i++ {
+		s.Record(testIP, 429, 42901)
+	}
+	require.NoFileExists(t, banFile) // still buffered
+	s.Close()                        // blocks until the final flush completes
+	data, err := os.ReadFile(banFile)
+	require.NoError(t, err)
+	require.Len(t, strings.Split(strings.TrimRight(string(data), "\n"), "\n"), 1)
+}
+
+func TestService_Prune_DropsIdlePrefixes(t *testing.T) {
+	// A prefix idle for a full window has a refilled bucket, so prune drops it to bound memory. An
+	// active prefix (seen within the window) is kept.
+	banFile := filepath.Join(t.TempDir(), "ban.log")
+	s := newTestService(t, banFile, 10, map[string]int{"*": 1})
+	idle := netip.MustParseAddr("9.9.9.9")
+	s.Record(idle, 400, 40001)
+	s.Record(testIP, 400, 40001)
+	require.Len(t, s.trackers, 2)
+
+	// Backdate the idle prefix past the window, then prune.
+	idlePrefix := s.prefix(idle)
+	s.mu.Lock()
+	s.trackers[idlePrefix].seen = time.Now().Add(-2 * time.Minute)
+	s.mu.Unlock()
+	s.prune()
+
+	require.Len(t, s.trackers, 1)
+	_, ok := s.trackers[idlePrefix]
+	require.False(t, ok) // idle prefix dropped
+	_, ok = s.trackers[s.prefix(testIP)]
+	require.True(t, ok) // active prefix kept
+}

ban/weights.go

@@ -0,0 +1,83 @@
+package ban
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+)
+
+// Weights maps a matcher key to a strike weight for the abuse ban-feed (see ParseWeights, WeightFor).
+type Weights map[string]int
+
+// ParseWeights normalizes a list like ["42909:10","403:2","*:1"] into a Weights map. A key is an
+// exact ntfy code, a family ("429*"), a bare HTTP status ("403" -> "403*"), or "*"; weights are ints
+// >= 0 (0 = exempt). Malformed entries are rejected so misconfiguration fails at startup.
+func ParseWeights(entries []string) (Weights, error) {
+	out := make(Weights, len(entries))
+	for _, entry := range entries {
+		key, weightStr, ok := strings.Cut(entry, ":")
+		if !ok {
+			return nil, fmt.Errorf("invalid ban-weight %q, want KEY:WEIGHT", entry)
+		}
+		weight, err := strconv.Atoi(strings.TrimSpace(weightStr))
+		if err != nil || weight < 0 {
+			return nil, fmt.Errorf("invalid ban-weight value in %q, want a non-negative integer", entry)
+		}
+		key = strings.TrimSpace(key)
+		if !validWeightKey(key) {
+			return nil, fmt.Errorf("invalid ban-weight key in %q, want %q, an ntfy code, an HTTP status, or a PREFIX*", entry, "*")
+		}
+		// A bare 3-digit HTTP status is shorthand for the whole family (e.g. "403" -> "403*").
+		if len(key) == 3 && isAllDigits(key) {
+			key += "*"
+		}
+		out[key] = weight
+	}
+	return out, nil
+}
+
+// WeightFor returns the strike weight for an ntfy error code, longest-match-wins (exact > family > "*").
+// If nothing matches (no "*" catch-all) it returns the implied default 1, so a forgotten "*" still
+// bans; use "*:0" to exempt everything not explicitly weighted.
+func (w Weights) WeightFor(errorCode int) int {
+	code := strconv.Itoa(errorCode)
+	weight, bestLen, matched := 0, -1, false
+	for key, wt := range w {
+		matchLen := -1
+		switch {
+		case key == "*":
+			matchLen = 0
+		case strings.HasSuffix(key, "*"):
+			if prefix := strings.TrimSuffix(key, "*"); strings.HasPrefix(code, prefix) {
+				matchLen = len(prefix)
+			}
+		case key == code:
+			matchLen = len(code)
+		}
+		if matchLen > bestLen {
+			weight, bestLen, matched = wt, matchLen, true
+		}
+	}
+	if !matched {
+		return 1
+	}
+	return weight
+}
+
+// validWeightKey reports whether key is a legal matcher: "*", an all-digits code, or DIGITS*.
+func validWeightKey(key string) bool {
+	if key == "*" {
+		return true
+	}
+	digits := strings.TrimSuffix(key, "*")
+	return digits != "" && isAllDigits(digits)
+}
+
+func isAllDigits(s string) bool {
+	for _, r := range s {
+		if r < '0' || r > '9' {
+			return false
+		}
+	}
+	return s != ""
+}

ban/weights_test.go

@@ -0,0 +1,73 @@
+package ban
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestParseWeights(t *testing.T) {
+	// Exact codes, a bare 3-digit HTTP status (normalized to a family), an exempt code, and "*".
+	weights, err := ParseWeights([]string{"42909:10", "403:2", "42908:0", "*:1"})
+	require.NoError(t, err)
+	require.Equal(t, Weights{"42909": 10, "403*": 2, "42908": 0, "*": 1}, weights)
+
+	// A bare 3-digit HTTP status normalizes to its family.
+	weights, err = ParseWeights([]string{"429:5"})
+	require.NoError(t, err)
+	require.Equal(t, Weights{"429*": 5}, weights)
+
+	// An explicit family key stays as-is.
+	weights, err = ParseWeights([]string{"429*:5"})
+	require.NoError(t, err)
+	require.Equal(t, Weights{"429*": 5}, weights)
+
+	// Weight 0 is valid and means exempt.
+	weights, err = ParseWeights([]string{"42908:0"})
+	require.NoError(t, err)
+	require.Equal(t, Weights{"42908": 0}, weights)
+
+	_, err = ParseWeights([]string{"401"}) // Missing weight
+	require.Error(t, err)
+	_, err = ParseWeights([]string{"401:-1"}) // Negative weight
+	require.Error(t, err)
+	_, err = ParseWeights([]string{"401:abc"}) // Non-integer weight
+	require.Error(t, err)
+	_, err = ParseWeights([]string{"abc:10"}) // Non-numeric key
+	require.Error(t, err)
+	_, err = ParseWeights([]string{"4*3:10"}) // Star not at the end
+	require.Error(t, err)
+}
+
+func TestWeights_WeightFor(t *testing.T) {
+	weights, err := ParseWeights([]string{"42908:0", "42903:0", "42905:0", "42910:0", "42909:10", "429*:1", "403*:2", "4*:1", "5*:1"})
+	require.NoError(t, err)
+	// Longest-match-wins: exact 5-digit beats "429*" beats "4*" beats "*".
+	require.Equal(t, 0, weights.WeightFor(42908))
+	require.Equal(t, 10, weights.WeightFor(42909))
+	require.Equal(t, 1, weights.WeightFor(42901))
+	require.Equal(t, 2, weights.WeightFor(40311))
+	require.Equal(t, 1, weights.WeightFor(40011))
+	require.Equal(t, 1, weights.WeightFor(50312))
+	// No rule matches (this config has 4*/5* but no "*"), so the implied default weight 1 applies.
+	require.Equal(t, 1, weights.WeightFor(30012))
+}
+
+func TestWeights_WeightFor_NoStarRuleImpliesWeight1(t *testing.T) {
+	// With no "*" rule, a code that matches nothing defaults to weight 1 (can be banned), so the
+	// feature can't be silently turned into a no-op by forgetting "*". Explicit codes still win.
+	weights, err := ParseWeights([]string{"42908:0", "42909:10"})
+	require.NoError(t, err)
+	require.Equal(t, 0, weights.WeightFor(42908))  // explicitly exempt
+	require.Equal(t, 10, weights.WeightFor(42909)) // explicit
+	require.Equal(t, 1, weights.WeightFor(42901))  // unmatched -> implied 1
+	require.Equal(t, 1, weights.WeightFor(40001))  // unmatched -> implied 1
+}
+
+func TestWeights_WeightFor_ExplicitStarZeroExemptsAll(t *testing.T) {
+	// An explicit "*:0" is the opt-out: exempt everything not otherwise weighted.
+	weights, err := ParseWeights([]string{"42909:10", "*:0"})
+	require.NoError(t, err)
+	require.Equal(t, 10, weights.WeightFor(42909)) // explicit
+	require.Equal(t, 0, weights.WeightFor(42901))  // *:0 -> exempt everything else
+}

cluster/cluster.go

@@ -0,0 +1,113 @@
+// Package cluster implements cross-node message delivery for a multi-node ntfy cluster. Nodes
+// register themselves in a PostgreSQL node registry (control plane) and fan published messages
+// out to each other directly over HTTP (data plane); PostgreSQL is never on the message path.
+// The single-node default is the nop cluster, which does nothing.
+package cluster
+
+import (
+	"errors"
+	"net/http"
+	"time"
+
+	"heckel.io/ntfy/v2/db"
+	"heckel.io/ntfy/v2/model"
+)
+
+// The internal peer API: every kind of node-to-node communication is a path under
+// /v1/internal/, served only on the dedicated cluster listener. Future concerns (rate limit
+// counters, stats) become new paths or new sections of the state envelope.
+const (
+	// MessagePath receives batches of published messages (NDJSON, one apiMessage per line).
+	MessagePath = "/v1/internal/message"
+	// StatePath receives peer state (JSON apiState): full subscription snapshots and
+	// incremental updates.
+	StatePath = "/v1/internal/state"
+)
+
+// NodeID identifies a cluster node; it keys the registry, the per-peer queues, and the peer
+// state table.
+//
+// Naming convention: a "node" is any cluster member in the absolute sense (identity, registry,
+// config); a "peer" is another node as seen from this one (Peers, peerQueue, peerState). A peer
+// IS a node, which is why peer values carry a NodeID.
+type NodeID string
+
+const (
+	// secretHeader carries the shared secret authenticating node-to-node fan-out requests.
+	secretHeader = "X-Cluster-Secret"
+
+	// originHeader carries the sending node's ID on fan-out requests, so a node can skip
+	// requests that carry its own broadcasts (loop prevention).
+	originHeader = "X-Cluster-Origin"
+)
+
+// Content types of the peer API: message bodies are NDJSON (one JSON message per line, matching
+// the framing of ntfy's own /topic/json subscribe stream), state bodies are plain JSON. Future
+// node-to-node request types get their own paths on the cluster listener; an old node answering
+// 404 on an unknown path keeps mixed-version clusters working during rolling deploys.
+const (
+	contentTypeNDJSON = "application/x-ndjson"
+	contentTypeJSON   = "application/json"
+)
+
+const (
+	defaultHeartbeatInterval = 3 * time.Second  // How often a node refreshes its registry heartbeat
+	defaultNodeTTL           = 30 * time.Second // A node counts as live if its heartbeat is newer than this; generous to avoid false-dead flapping (see plans)
+	defaultStateInterval     = 15 * time.Second // How often the full subscription state is pushed to peers
+
+	// DefaultBatchLinger is how long a fan-out message may wait in a peer's queue for more
+	// messages to arrive, so they are delivered as one batch. It trades up to this much
+	// cross-node latency for a bounded request rate per peer.
+	DefaultBatchLinger = 500 * time.Millisecond
+)
+
+// Cluster fans published messages out to peer cluster nodes and receives their fan-out requests.
+// Local delivery to a node's own subscribers still happens inline in the server; the cluster
+// only covers the cross-node hop.
+type Cluster interface {
+	http.Handler
+	// ForwardMessage sends a locally published message on to the peer nodes that may have subscribers
+	// for its topic (all of them, when subscription knowledge is missing or stale). It is
+	// fire-and-forget and must not block the caller's request path.
+	ForwardMessage(m *model.Message) error
+	// BroadcastState pushes a subscription-state delta to ALL peers (unlike ForwardMessage,
+	// which routes), closing the routing-knowledge window to ~one round trip. Nop single-node.
+	BroadcastState(state *State)
+	// IsLeader reports whether this node holds the cluster leader lock. Singleton background
+	// jobs (e.g. the Firebase keepaliver) are gated on the leader.
+	IsLeader() bool
+	// Healthy reports whether this node is fit to serve: its registry heartbeat is fresh
+	// enough (within NodeTTL) that peers still forward messages to it. Health checkers must
+	// fail open (never pull ALL nodes): during a full database outage every node reports
+	// unhealthy while the mesh keeps delivering on stale peer caches.
+	Healthy() bool
+	// Close stops the cluster and releases its resources.
+	Close() error
+}
+
+// New creates the cluster for the given config: the nop cluster when clustering is disabled (the
+// single-node default), or the peer-mesh cluster otherwise.
+func New(conf *Config, pool *db.DB, deliver DeliverFunc, topics TopicsFunc) (Cluster, error) {
+	if !conf.Enabled {
+		return &nopCluster{}, nil
+	}
+	if pool == nil {
+		return nil, errors.New("cluster mode requires a PostgreSQL database (set database-url)")
+	}
+	if conf.AdvertiseURL == "" {
+		return nil, errors.New("cluster mode requires an advertise URL (set cluster-advertise-url)")
+	}
+	if conf.NodeID == "" {
+		return nil, errors.New("cluster mode requires a stable node ID (set cluster-node-id)")
+	}
+	if conf.HeartbeatInterval == 0 {
+		conf.HeartbeatInterval = defaultHeartbeatInterval
+	}
+	if conf.NodeTTL == 0 {
+		conf.NodeTTL = defaultNodeTTL
+	}
+	if conf.StateInterval == 0 {
+		conf.StateInterval = defaultStateInterval
+	}
+	return newMeshCluster(conf, pool, deliver, topics)
+}

cluster/cluster_load_test.go

@@ -0,0 +1,133 @@
+package cluster
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	dbtest "heckel.io/ntfy/v2/db/test"
+	"heckel.io/ntfy/v2/model"
+)
+
+// TestMesh_Soak floods the mesh with concurrent publishers and asserts exact delivery: every
+// message reaches the peer exactly once, nothing is dropped, and batching keeps the request
+// count far below the message count. Skipped unless NTFY_TEST_SOAK is set (it takes a few
+// seconds and is meant for pre-deploy verification, not the regular suite).
+func TestMesh_Soak(t *testing.T) {
+	if os.Getenv("NTFY_TEST_SOAK") == "" {
+		t.Skip("NTFY_TEST_SOAK not set")
+	}
+	// ~1000 msg/s aggregate (10x the ntfy.sh peak of ~88 msg/s): each publisher paces itself to
+	// 100 msg/s. Unthrottled publishing intentionally overruns the bounded per-peer queue (load
+	// shedding by design), so a zero-drop assertion only holds below the drain ceiling.
+	const (
+		publishers           = 10
+		messagesPerPublisher = 300
+		publishInterval      = 10 * time.Millisecond
+		total                = publishers * messagesPerPublisher
+	)
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	var mu sync.Mutex
+	received := make(map[string]int, total) // message body -> count, to catch duplicates
+	requests := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, err := io.ReadAll(r.Body)
+		require.Nil(t, err)
+		messages, err := unmarshalMessageBody(body, 1<<20)
+		require.Nil(t, err)
+		mu.Lock()
+		requests++
+		for _, m := range messages {
+			received[m.Message]++
+		}
+		mu.Unlock()
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+	conf := newTestMeshConfig("node-a", "http://127.0.0.1:1")
+	conf.BatchLinger = 50 * time.Millisecond
+	conf.NodeTTL = time.Minute // The fake peer never heartbeats; liveness is not under test here
+	registerFakePeer(t, pool, "node-peer", srv.URL)
+	mesh, err := newMeshCluster(conf, pool, nil, nil)
+	require.Nil(t, err)
+	defer mesh.Close()
+	start := time.Now()
+	var wg sync.WaitGroup
+	for p := 0; p < publishers; p++ {
+		wg.Add(1)
+		go func(p int) {
+			defer wg.Done()
+			ticker := time.NewTicker(publishInterval)
+			defer ticker.Stop()
+			for i := 0; i < messagesPerPublisher; i++ {
+				require.Nil(t, mesh.ForwardMessage(model.NewDefaultMessage("mytopic", fmt.Sprintf("p%d-m%d", p, i))))
+				<-ticker.C
+			}
+		}(p)
+	}
+	wg.Wait()
+	waitFor(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+		return len(received) == total
+	})
+	elapsed := time.Since(start)
+	mu.Lock()
+	defer mu.Unlock()
+	for body, count := range received {
+		require.Equalf(t, 1, count, "message %s delivered %d times", body, count)
+	}
+	require.Less(t, requests, total/10, "expected strong batching under load")
+	t.Logf("soak: %d messages, %d requests (%.1f msgs/request), %.0f msgs/s",
+		total, requests, float64(total)/float64(requests), float64(total)/elapsed.Seconds())
+}
+
+// BenchmarkForwardMessage measures the publish-path cost of ForwardMessage: marshal + peer lookup (cached)
+// + enqueue. The peer never drains, so enqueued fragments are dropped once the queue fills;
+// the benchmark measures the hot path, not HTTP delivery.
+func BenchmarkForwardMessage(b *testing.B) {
+	if os.Getenv("NTFY_TEST_DATABASE_URL") == "" {
+		b.Skip("NTFY_TEST_DATABASE_URL not set")
+	}
+	schemaDSN := dbtest.CreateTestPostgresSchema(b)
+	pool := openTestPool(b, schemaDSN)
+	conf := newTestMeshConfig("node-a", "http://127.0.0.1:1")
+	conf.BatchLinger = time.Minute // Never flush; we measure enqueue only
+	mesh, err := newMeshCluster(conf, pool, nil, nil)
+	require.Nil(b, err)
+	defer mesh.Close()
+	registerFakePeer(b, pool, "node-peer", "http://127.0.0.1:1")
+	m := model.NewDefaultMessage("mytopic", "benchmark message body of typical size for a push")
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		if err := mesh.ForwardMessage(m); err != nil {
+			b.Fatal(err)
+		}
+	}
+}
+
+// BenchmarkDecodeFanout measures the receive-path cost of decoding a 100-message NDJSON body.
+func BenchmarkDecodeFanout(b *testing.B) {
+	frags := make([][]byte, 100)
+	for i := range frags {
+		frag, err := marshalMessage(model.NewDefaultMessage("mytopic", fmt.Sprintf("benchmark message %d", i)))
+		require.Nil(b, err)
+		frags[i] = frag
+	}
+	body := assembleMessageBody(frags)
+	b.SetBytes(int64(len(body)))
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		messages, err := unmarshalMessageBody(body, 1<<20)
+		if err != nil || len(messages) != 100 {
+			b.Fatal("decode failed")
+		}
+	}
+}

cluster/cluster_mesh.go

@@ -0,0 +1,498 @@
+package cluster
+
+import (
+	"bytes"
+	"context"
+	"crypto/subtle"
+	"encoding/json"
+	"io"
+	"net/http"
+	"sync"
+	"time"
+
+	"heckel.io/ntfy/v2/cluster/registry"
+	"heckel.io/ntfy/v2/db"
+	"heckel.io/ntfy/v2/db/pg"
+	"heckel.io/ntfy/v2/log"
+	"heckel.io/ntfy/v2/metrics"
+	"heckel.io/ntfy/v2/model"
+	"heckel.io/ntfy/v2/util"
+)
+
+const (
+	meshHTTPTimeout   = 5 * time.Second
+	peerQueueSize     = 1024            // Bounded per-peer fan-out queue (drop on overflow)
+	batchMaxMessages  = 100             // Flush a batch early when it reaches this many messages
+	batchMaxBytes     = 256 * 1024      // Flush a batch early when it reaches this size
+	stateMaxBytes     = 4 * 1024 * 1024 // Upper bound for inbound state bodies (filter over ~1M topics)
+	stateFilterFPRate = 0.01            // Bloom false-positive rate; a false positive is one wasted send
+	tag               = "cluster"
+)
+
+// meshCluster fans messages out directly to peer nodes over HTTP (the data plane), using
+// PostgreSQL only as a control plane: the node_registry table for membership/discovery, and a
+// Postgres advisory lock for singleton-job leader election. Fan-out never touches the database on
+// the message path (only the cached peer list does). See plans/260715-scale-out-mesh.md.
+//
+// Each peer has its own bounded send queue and delivery worker, so a slow or wedged peer only
+// backs up (and eventually drops) its own queue and never delays delivery to healthy peers.
+type meshCluster struct {
+	conf           *Config
+	deliver        DeliverFunc
+	topics         TopicsFunc
+	registry       *registry.Registry
+	leader         *pg.Leader
+	httpClient     *http.Client
+	mux            *http.ServeMux        // The internal peer API; Cluster is an http.Handler
+	queues         map[NodeID]*peerQueue // per-peer send queues; reconciled against the registry
+	closed         bool                  // Guards against ForwardMessage spawning new workers after Close
+	states         map[NodeID]*peerState // what each peer last told us (subscription knowledge)
+	lastStatePush  time.Time             // Only touched by the heartbeat goroutine
+	knownPeers     map[NodeID]string     // Peers seen in the last reconcile, for join/leave logging
+	lastRegistered time.Time             // Last successful registry heartbeat, for Healthy
+	ctx            context.Context
+	cancel         context.CancelFunc
+	wg             sync.WaitGroup
+	mu             sync.Mutex // Protects queues, closed, knownPeers and lastRegistered
+	statesMu       sync.Mutex // Protects states
+}
+
+// newMeshCluster creates the mesh cluster: it sets up the registry schema, registers this node
+// (synchronously, so it is discoverable before New returns), and starts the heartbeat loop.
+// Peer delivery workers are started lazily as peers appear in the registry.
+func newMeshCluster(conf *Config, pool *db.DB, deliver DeliverFunc, topics TopicsFunc) (*meshCluster, error) {
+	if topics == nil {
+		topics = func() []string { return nil } // No known topics; peers will broadcast to us
+	}
+	reg, err := registry.New(pool, string(conf.NodeID), conf.AdvertiseURL, conf.NodeTTL)
+	if err != nil {
+		return nil, err
+	}
+	// Register synchronously so the node is discoverable before the constructor returns; the
+	// heartbeat loop refreshes the registration from here on
+	if err := reg.Register(); err != nil {
+		return nil, err
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	c := &meshCluster{
+		conf:     conf,
+		deliver:  deliver,
+		topics:   topics,
+		registry: reg,
+		// Renews its lease on its own fixed cadence; see pg.Leader for the semantics
+		leader:         pg.NewLeader(pool.Primary(), pg.LeaderLockKey, conf.LeaderRenewInterval),
+		httpClient:     &http.Client{Timeout: meshHTTPTimeout},
+		queues:         make(map[NodeID]*peerQueue),
+		lastRegistered: time.Now(), // The synchronous Register above just succeeded
+		states:         make(map[NodeID]*peerState),
+		knownPeers:     make(map[NodeID]string),
+		ctx:            ctx,
+		cancel:         cancel,
+	}
+	c.mux = http.NewServeMux()
+	c.mux.HandleFunc("POST "+MessagePath, c.authenticated(c.handleMessage))
+	c.mux.HandleFunc("POST "+StatePath, c.authenticated(c.handleState))
+	c.wg.Add(1)
+	go c.heartbeatLoop()
+	return c, nil
+}
+
+// ServeHTTP serves the internal peer API. Auth lives in the authenticated middleware, so every
+// endpoint gets the same shared-secret and origin handling.
+func (c *meshCluster) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	c.mux.ServeHTTP(w, r)
+}
+
+// authenticated wraps a peer API handler with the checks every endpoint needs: the shared
+// secret (constant-time compare, rejected before any body is read), a present origin, and the
+// origin self-skip (a request carrying this node's own traffic is acknowledged but ignored).
+func (c *meshCluster) authenticated(h func(origin NodeID, w http.ResponseWriter, r *http.Request)) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		if c.conf.Secret == "" || subtle.ConstantTimeCompare([]byte(r.Header.Get(secretHeader)), []byte(c.conf.Secret)) != 1 {
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+		origin := NodeID(r.Header.Get(originHeader))
+		if origin == "" {
+			w.WriteHeader(http.StatusBadRequest)
+			return
+		}
+		if origin == c.conf.NodeID {
+			w.WriteHeader(http.StatusOK) // Our own traffic; nothing to do
+			return
+		}
+		h(origin, w, r)
+	}
+}
+
+// heartbeatLoop runs one heartbeat immediately (the ticker first fires a full interval after
+// startup, and a fresh node should be leader-capable and state-visible right away), then one per
+// interval until shutdown.
+func (c *meshCluster) heartbeatLoop() {
+	defer c.wg.Done()
+	ticker := time.NewTicker(c.conf.HeartbeatInterval)
+	defer ticker.Stop()
+	if err := c.heartbeat(); err != nil {
+		log.Tag(tag).Err(err).Warn("Cluster heartbeat failed")
+	}
+	for {
+		select {
+		case <-c.ctx.Done():
+			return
+		case <-ticker.C:
+			if err := c.heartbeat(); err != nil {
+				log.Tag(tag).Err(err).Warn("Cluster heartbeat failed")
+			}
+		}
+	}
+}
+
+// heartbeat is one control-plane tick: refresh this node's registry row, retry/confirm the
+// leader lock, prune long-dead registry rows (as leader), reconcile the per-peer queues, and
+// periodically push our subscription state to peers.
+//
+// A node that cannot even register itself aborts the tick: the remaining database work would
+// fail against the same database, and everything downstream degrades safely without it -- ForwardMessage
+// serves the stale peer cache on its own, and peers fall back to broadcasting to us once our
+// last pushed state expires.
+func (c *meshCluster) heartbeat() error {
+	if err := c.registry.Register(); err != nil {
+		return err
+	}
+	c.mu.Lock()
+	c.lastRegistered = time.Now()
+	c.mu.Unlock()
+	// Effective leadership: pg.Leader's lease semantics guarantee a no-leader gap on
+	// failover, never two leaders
+	if c.leader.IsLeader() {
+		metrics.ClusterLeader.Set(1)
+		if err := c.registry.Prune(); err != nil {
+			log.Tag(tag).Err(err).Warn("Failed to prune stale nodes") // Housekeeping only; not fatal for the tick
+		}
+	} else {
+		metrics.ClusterLeader.Set(0)
+	}
+	peers, err := c.registry.Peers()
+	if err != nil {
+		return err
+	}
+	c.reconcilePeers(peers)
+	if time.Since(c.lastStatePush) >= c.conf.StateInterval {
+		c.pushState(peers)
+		c.lastStatePush = time.Now()
+	}
+	return nil
+}
+
+// reconcilePeers aligns this node's per-peer attachments with the live peer set: it retires the
+// queues (and workers) of peers that have left the registry or re-registered under a new
+// advertise URL (the retired queue's remainder was headed for a dead address anyway), and prunes
+// the stale state of departed peers. New and replacement queues are created lazily by ForwardMessage, not
+// here, so a freshly joined peer is reachable immediately.
+func (c *meshCluster) reconcilePeers(peers []*registry.Peer) {
+	metrics.ClusterPeers.Set(float64(len(peers)))
+	alive := make(map[NodeID]string, len(peers)) // node ID -> advertise URL
+	for _, p := range peers {
+		alive[NodeID(p.NodeID)] = p.AdvertiseURL
+	}
+	c.mu.Lock()
+	// Log joins and leaves (as seen through the up-to-NodeTTL-stale registry view)
+	for nodeID, url := range alive {
+		if _, ok := c.knownPeers[nodeID]; !ok {
+			log.Tag(tag).Info("Peer %s (%s) joined the cluster", nodeID, url)
+		}
+	}
+	for nodeID := range c.knownPeers {
+		if _, ok := alive[nodeID]; !ok {
+			log.Tag(tag).Info("Peer %s left the cluster", nodeID)
+		}
+	}
+	c.knownPeers = alive
+	for nodeID, q := range c.queues {
+		if url, ok := alive[nodeID]; !ok || q.advertiseURL != url {
+			q.queue.Close() // Flushes the remainder; the worker exits when the queue is drained
+			delete(c.queues, nodeID)
+		}
+	}
+	c.mu.Unlock()
+	// Prune the state of departed peers, but only once stale: state is push-driven and can
+	// arrive before a new peer is visible in the (up to NodeTTL stale) registry view, so fresh
+	// state must survive even when its peer is not in the live set. Without this, the states of
+	// long-gone nodes would accumulate forever.
+	c.statesMu.Lock()
+	for nodeID, state := range c.states {
+		if _, ok := alive[nodeID]; !ok && time.Since(state.updatedAt) > 3*c.conf.StateInterval {
+			delete(c.states, nodeID)
+		}
+	}
+	c.statesMu.Unlock()
+}
+
+// queueFor returns the send queue for the given peer, creating it (and its delivery worker) if it
+// does not exist yet. The caller must hold c.mu.
+func (c *meshCluster) queueFor(p *registry.Peer) *peerQueue {
+	nodeID := NodeID(p.NodeID)
+	q, ok := c.queues[nodeID]
+	if ok {
+		return q
+	}
+	q = &peerQueue{
+		advertiseURL: p.AdvertiseURL,
+		queue: util.NewLingerQueue(peerQueueSize, batchMaxMessages, batchMaxBytes,
+			func(frag []byte) int { return len(frag) }, c.conf.BatchLinger),
+	}
+	c.queues[nodeID] = q
+	c.wg.Add(1)
+	go c.peerWorker(nodeID, q)
+	return q
+}
+
+// ForwardMessage enqueues the message for delivery to every live peer node that may have subscribers for
+// its topic (all of them, absent fresh knowledge). Delivery is fire-and-forget via each peer's
+// bounded batching queue; if a peer's queue is full the message is dropped for that peer
+// (subscribers reconnect and re-poll history from the database).
+func (c *meshCluster) ForwardMessage(msg *model.Message) error {
+	peers, err := c.registry.Peers()
+	if err != nil {
+		return err
+	}
+	if len(peers) == 0 {
+		return nil // Cluster of one; skip the marshal
+	}
+	frag, err := marshalMessage(msg)
+	if err != nil {
+		return err
+	}
+	metrics.ClusterMessagesForwarded.Inc()
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.closed {
+		return nil // Shutting down; the message is dropped like any other in-flight fan-out
+	}
+	for _, p := range peers {
+		// Route around peers whose fresh state provably excludes this topic; anything less
+		// certain (no state, stale state) falls back to broadcasting
+		if !c.mayNeed(NodeID(p.NodeID), msg.Topic) {
+			metrics.ClusterRouteSkipped.Inc()
+			if ev := log.Tag(tag); ev.IsTrace() {
+				ev.Trace("Skipping peer %s for message %s: no subscribers for topic %s", p.NodeID, msg.ID, msg.Topic)
+			}
+			continue
+		}
+		if !c.queueFor(p).queue.TryEnqueue(frag) {
+			metrics.ClusterQueueDropped.Inc()
+			log.Tag(tag).Warn("Fan-out queue for peer %s full, dropping message %s", p.NodeID, msg.ID)
+		} else if ev := log.Tag(tag); ev.IsTrace() {
+			ev.Trace("Enqueued message %s (topic %s) for peer %s", msg.ID, msg.Topic, p.NodeID)
+		}
+	}
+	return nil
+}
+
+// mayNeed reports whether the peer may have a subscriber for the topic. Conservative by
+// construction: it returns false only when a fresh state snapshot provably excludes the topic.
+// A false positive costs one wasted send; a false negative would lose a message and cannot
+// happen for topics a peer has reported (Bloom filters have no false negatives).
+func (c *meshCluster) mayNeed(peer NodeID, topic string) bool {
+	c.statesMu.Lock()
+	defer c.statesMu.Unlock()
+	state, ok := c.states[peer]
+	if !ok || time.Since(state.updatedAt) > 3*c.conf.StateInterval {
+		return true // No knowledge, or too old to trust for skipping
+	}
+	return state.topics.Contains(topic)
+}
+
+// peerWorker delivers batches of queued fan-out messages to a single peer. Batches form in the
+// peer's LingerQueue (up to BatchLinger delay, flushed early on size/count caps); the worker
+// exits when the queue is closed (peer left the registry, or mesh shutdown) and drained.
+func (c *meshCluster) peerWorker(nodeID NodeID, q *peerQueue) {
+	defer c.wg.Done()
+	for frags := range q.queue.Dequeue() {
+		body := assembleMessageBody(frags)
+		log.Tag(tag).Debug("Sending batch of %d message(s) (%d bytes) to peer %s", len(frags), len(body), nodeID)
+		c.postToPeer(nodeID, messageURL(q.advertiseURL), contentTypeNDJSON, body)
+		metrics.ClusterBatchesSent.Inc()
+	}
+}
+
+// postToPeer POSTs a peer API payload, authenticated with the shared cluster secret. Failures
+// are logged and counted, never retried: peer traffic is best-effort by design (messages are
+// recovered via since= replay, state via the next periodic push).
+func (c *meshCluster) postToPeer(nodeID NodeID, url, contentType string, payload []byte) {
+	req, err := http.NewRequestWithContext(c.ctx, http.MethodPost, url, bytes.NewReader(payload))
+	if err != nil {
+		metrics.ClusterSendErrors.Inc()
+		log.Tag(tag).Err(err).Warn("Failed to build request for peer %s", nodeID)
+		return
+	}
+	req.Header.Set("Content-Type", contentType)
+	req.Header.Set(secretHeader, c.conf.Secret)
+	req.Header.Set(originHeader, string(c.conf.NodeID))
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		if c.ctx.Err() == nil {
+			metrics.ClusterSendErrors.Inc()
+			log.Tag(tag).Err(err).Warn("Failed to send to peer %s (%s)", nodeID, url)
+		}
+		return
+	}
+	resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		metrics.ClusterSendErrors.Inc()
+		log.Tag(tag).Warn("Peer %s (%s) rejected request with HTTP %d", nodeID, url, resp.StatusCode)
+	}
+}
+
+// handleMessage receives a batch of peer messages (NDJSON) and streams them to local
+// subscribers line by line, delivering each message as it is decoded.
+func (c *meshCluster) handleMessage(origin NodeID, w http.ResponseWriter, r *http.Request) {
+	// A batch can exceed its byte cap by one message, plus framing overhead
+	maxBodyBytes := int64(batchMaxBytes) + c.conf.MaxMessageBytes + 1024
+	received := 0
+	deliver := func(m *model.Message) {
+		received++
+		if ev := log.Tag(tag); ev.IsTrace() {
+			ev.Trace("Delivering message %s (topic %s) from peer %s", m.ID, m.Topic, origin)
+		}
+		c.deliver(m)
+	}
+	if err := decodeMessageBody(io.LimitReader(r.Body, maxBodyBytes), int(c.conf.MaxMessageBytes), deliver); err != nil {
+		w.WriteHeader(http.StatusBadRequest)
+		return
+	}
+	log.Tag(tag).Debug("Received batch of %d message(s) from peer %s", received, origin)
+	w.WriteHeader(http.StatusOK)
+}
+
+// handleState receives a peer's state envelope and applies each section it carries.
+func (c *meshCluster) handleState(origin NodeID, w http.ResponseWriter, r *http.Request) {
+	body, err := io.ReadAll(io.LimitReader(r.Body, stateMaxBytes))
+	if err != nil {
+		w.WriteHeader(http.StatusBadRequest)
+		return
+	}
+	var state apiState
+	if err := json.Unmarshal(body, &state); err != nil {
+		w.WriteHeader(http.StatusBadRequest)
+		return
+	}
+	if state.Topics != nil {
+		if err := c.applyTopicState(origin, state.Topics); err != nil {
+			w.WriteHeader(http.StatusBadRequest)
+			return
+		}
+	}
+	w.WriteHeader(http.StatusOK)
+}
+
+// applyTopicState updates what we know about a peer's subscriptions: a full snapshot replaces
+// all prior knowledge, an incremental add merges into it. Increments without a baseline are
+// ignored on purpose -- without a snapshot the peer is broadcast to anyway.
+func (c *meshCluster) applyTopicState(origin NodeID, topics *apiStateTopics) error {
+	c.statesMu.Lock()
+	defer c.statesMu.Unlock()
+	if len(topics.Filter) > 0 {
+		filter, err := util.UnmarshalBloomFilter(topics.Filter)
+		if err != nil {
+			return err
+		}
+		c.states[origin] = &peerState{topics: filter, updatedAt: time.Now()}
+		log.Tag(tag).Debug("Received subscription state from peer %s (%d filter bytes)", origin, len(topics.Filter))
+		return nil
+	}
+	if state, ok := c.states[origin]; ok {
+		for _, topic := range topics.Added {
+			state.topics.Add(topic)
+		}
+		state.updatedAt = time.Now()
+		log.Tag(tag).Debug("Received %d announced topic(s) from peer %s", len(topics.Added), origin)
+	}
+	return nil
+}
+
+// pushState sends a full state snapshot to every live peer: a Bloom filter over the topics that
+// currently have local subscribers. Sent directly (not via the linger queues -- state must not
+// wait behind message batches); a lost push self-heals at the next interval. Topics without
+// subscribers disappear simply by not being in the next snapshot.
+func (c *meshCluster) pushState(peers []*registry.Peer) {
+	if len(peers) == 0 {
+		return
+	}
+	topics := c.topics()
+	filter := util.NewBloomFilter(len(topics), stateFilterFPRate)
+	for _, topic := range topics {
+		filter.Add(topic)
+	}
+	data, err := filter.MarshalBinary()
+	if err != nil {
+		return
+	}
+	body, err := json.Marshal(&apiState{Topics: &apiStateTopics{Filter: data}})
+	if err != nil {
+		return
+	}
+	log.Tag(tag).Debug("Pushing subscription state (%d topics, %d bytes) to %d peer(s)", len(topics), len(body), len(peers))
+	for _, p := range peers {
+		go c.postToPeer(NodeID(p.NodeID), stateURL(p.AdvertiseURL), contentTypeJSON, body)
+	}
+	metrics.ClusterStatePushes.Inc()
+}
+
+// BroadcastState immediately tells all live peers that these topics gained their first local
+// subscriber, shrinking the window in which a publisher could wrongly skip this node from a
+// full state interval down to about one round trip.
+func (c *meshCluster) BroadcastState(state *State) {
+	if len(state.AddedTopics) == 0 {
+		return
+	}
+	peers, err := c.registry.Peers()
+	if err != nil || len(peers) == 0 {
+		return
+	}
+	body, err := json.Marshal(&apiState{Topics: &apiStateTopics{Added: state.AddedTopics}})
+	if err != nil {
+		return
+	}
+	log.Tag(tag).Debug("Broadcasting state (%d new topics) to %d peer(s)", len(state.AddedTopics), len(peers))
+	for _, p := range peers {
+		go c.postToPeer(NodeID(p.NodeID), stateURL(p.AdvertiseURL), contentTypeJSON, body)
+	}
+}
+
+// IsLeader reports whether this node currently holds singleton-job leadership.
+func (c *meshCluster) IsLeader() bool {
+	return c.leader.IsLeader()
+}
+
+// Healthy reports whether this node's registry heartbeat is fresh enough that peers still
+// forward messages to it (see the Cluster interface for the checker's fail-open duty).
+func (c *meshCluster) Healthy() bool {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return time.Since(c.lastRegistered) < c.conf.NodeTTL
+}
+
+// Close stops the mesh: it deregisters this node, releases leadership, stops all peer workers,
+// and waits for them to exit.
+func (c *meshCluster) Close() error {
+	c.cancel() // Stops the heartbeat loop and aborts in-flight peer deliveries
+	// Close the peer queues so their workers flush and exit; final sends are best-effort since
+	// the context is already canceled (parity with fire-and-forget delivery)
+	c.mu.Lock()
+	c.closed = true
+	for nodeID, q := range c.queues {
+		q.queue.Close()
+		delete(c.queues, nodeID)
+	}
+	c.mu.Unlock()
+	// Wait for the loops BEFORE deregistering: an in-flight heartbeat's Register would otherwise
+	// re-insert our row right after Deregister deleted it
+	c.wg.Wait()
+	if err := c.registry.Deregister(); err != nil {
+		log.Tag(tag).Err(err).Warn("Failed to deregister node")
+	}
+	c.leader.Close()
+	metrics.ClusterLeader.Set(0)
+	return nil
+}

cluster/cluster_mesh_test.go

@@ -0,0 +1,590 @@
+package cluster
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"heckel.io/ntfy/v2/cluster/registry"
+	"heckel.io/ntfy/v2/db"
+	"heckel.io/ntfy/v2/db/pg"
+	dbtest "heckel.io/ntfy/v2/db/test"
+	"heckel.io/ntfy/v2/model"
+	"heckel.io/ntfy/v2/util"
+)
+
+const (
+	testSecret = "s3cret"
+)
+
+// openTestPool opens a dedicated connection pool to the given test schema, so that each simulated
+// node has its own pool like real nodes would.
+func openTestPool(t testing.TB, dsn string) *db.DB {
+	host, err := pg.Open(dsn)
+	require.Nil(t, err)
+	d := db.New(host, nil)
+	t.Cleanup(func() { d.Close() })
+	return d
+}
+
+func newTestMeshConfig(nodeID, advertiseURL string) *Config {
+	return &Config{
+		Enabled:             true,
+		NodeID:              NodeID(nodeID),
+		AdvertiseURL:        advertiseURL,
+		Secret:              testSecret,
+		HeartbeatInterval:   100 * time.Millisecond,
+		LeaderRenewInterval: 20 * time.Millisecond, // Lease duration 60ms, hold-off 120ms; keeps leadership tests fast
+		NodeTTL:             time.Second,           // Also the peer cache bound; short so fake peers registered mid-test are seen quickly
+		MaxMessageBytes:     1 << 20,
+		StateInterval:       time.Minute, // Individual tests lower this to exercise state pushes
+	}
+}
+
+// registerFakePeer registers a fake peer via the registry (creating the table if the mesh has
+// not been constructed yet): tests register fakes before the mesh boots, since its first
+// heartbeat caches the peer list. The fake never refreshes its heartbeat.
+func registerFakePeer(t testing.TB, pool *db.DB, nodeID NodeID, url string) {
+	t.Helper()
+	reg, err := registry.New(pool, string(nodeID), url, time.Minute)
+	require.Nil(t, err)
+	require.Nil(t, reg.Register())
+}
+
+func waitFor(t *testing.T, f func() bool) {
+	t.Helper()
+	for i := 0; i < 100; i++ {
+		if f() {
+			return
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+	t.Fatal("timed out waiting for condition")
+}
+
+func TestMesh_CrossNodeDelivery(t *testing.T) {
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	poolA, poolB := openTestPool(t, schemaDSN), openTestPool(t, schemaDSN)
+	var mu sync.Mutex
+	var received []*model.Message
+	var meshB *meshCluster
+	srvB := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		meshB.ServeHTTP(w, r)
+	}))
+	defer srvB.Close()
+	meshB, err := newMeshCluster(newTestMeshConfig("node-b", srvB.URL), poolB, func(m *model.Message) {
+		mu.Lock()
+		defer mu.Unlock()
+		received = append(received, m)
+	}, nil)
+	require.Nil(t, err)
+	defer meshB.Close()
+	meshA, err := newMeshCluster(newTestMeshConfig("node-a", "http://127.0.0.1:1"), poolA, func(m *model.Message) {
+		t.Error("node A must not receive its own relayed message")
+	}, nil)
+	require.Nil(t, err)
+	defer meshA.Close()
+	msg := model.NewDefaultMessage("mytopic", "hello cross-node")
+	require.Nil(t, meshA.ForwardMessage(msg))
+	waitFor(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+		return len(received) == 1
+	})
+	mu.Lock()
+	defer mu.Unlock()
+	require.Equal(t, "mytopic", received[0].Topic)
+	require.Equal(t, "hello cross-node", received[0].Message)
+}
+
+func TestMesh_PeerAPI_Auth(t *testing.T) {
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	var delivered int
+	mesh, err := newMeshCluster(newTestMeshConfig("node-a", "http://127.0.0.1:1"), pool, func(m *model.Message) {
+		delivered++
+	}, nil)
+	require.Nil(t, err)
+	defer mesh.Close()
+	frag, err := marshalMessage(model.NewDefaultMessage("mytopic", "hi"))
+	require.Nil(t, err)
+	payload := assembleMessageBody([][]byte{frag})
+
+	// Wrong secret -> 401, not delivered
+	rr := httptest.NewRecorder()
+	req := httptest.NewRequest("POST", MessagePath, strings.NewReader(string(payload)))
+	req.Header.Set(secretHeader, "wrong")
+	req.Header.Set(originHeader, "node-b")
+	mesh.ServeHTTP(rr, req)
+	require.Equal(t, 401, rr.Code)
+
+	// Missing secret -> 401, not delivered
+	rr = httptest.NewRecorder()
+	mesh.ServeHTTP(rr, httptest.NewRequest("POST", MessagePath, strings.NewReader(string(payload))))
+	require.Equal(t, 401, rr.Code)
+	require.Equal(t, 0, delivered)
+
+	// Missing origin -> 400, not delivered
+	rr = httptest.NewRecorder()
+	req = httptest.NewRequest("POST", MessagePath, strings.NewReader(string(payload)))
+	req.Header.Set(secretHeader, testSecret)
+	mesh.ServeHTTP(rr, req)
+	require.Equal(t, 400, rr.Code)
+	require.Equal(t, 0, delivered)
+
+	// Correct secret and origin -> 200, delivered
+	rr = httptest.NewRecorder()
+	req = httptest.NewRequest("POST", MessagePath, strings.NewReader(string(payload)))
+	req.Header.Set(secretHeader, testSecret)
+	req.Header.Set(originHeader, "node-b")
+	mesh.ServeHTTP(rr, req)
+	require.Equal(t, 200, rr.Code)
+	require.Equal(t, 1, delivered)
+}
+
+func TestMesh_PeerAPI_SelfOrigin(t *testing.T) {
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	var delivered int
+	mesh, err := newMeshCluster(newTestMeshConfig("node-a", "http://127.0.0.1:1"), pool, func(m *model.Message) {
+		delivered++
+	}, nil)
+	require.Nil(t, err)
+	defer mesh.Close()
+
+	// A request that carries this node's own broadcasts must not be re-delivered (loop prevention)
+	frag, err := marshalMessage(model.NewDefaultMessage("mytopic", "loop"))
+	require.Nil(t, err)
+	payload := assembleMessageBody([][]byte{frag})
+	rr := httptest.NewRecorder()
+	req := httptest.NewRequest("POST", MessagePath, strings.NewReader(string(payload)))
+	req.Header.Set(secretHeader, testSecret)
+	req.Header.Set(originHeader, "node-a") // Same as the receiving node's ID
+	mesh.ServeHTTP(rr, req)
+	require.Equal(t, 200, rr.Code)
+	require.Equal(t, 0, delivered)
+}
+
+func TestMesh_SlowPeerIsolation(t *testing.T) {
+	// A wedged peer must not delay delivery to healthy peers: each peer has its own queue and
+	// delivery worker. With a shared send queue (the design this replaces), the slow peer's
+	// requests would occupy all delivery workers and starve the fast peer.
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	var mu sync.Mutex
+	fastReceived := 0 // Messages, not requests: with batching, one request can carry many
+	srvFast := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, err := io.ReadAll(r.Body)
+		require.Nil(t, err)
+		messages, err := unmarshalMessageBody(body, 1<<20)
+		require.Nil(t, err)
+		mu.Lock()
+		fastReceived += len(messages)
+		mu.Unlock()
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srvFast.Close()
+	release := make(chan struct{})
+	srvSlow := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		<-release // Wedged until the end of the test
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srvSlow.Close()
+	defer close(release)
+	// Register the fake peers before the mesh boots; its first heartbeat caches the peer list
+	for i, url := range []string{srvFast.URL, srvSlow.URL} {
+		registerFakePeer(t, pool, NodeID(fmt.Sprintf("node-fake-%d", i)), url)
+	}
+	mesh, err := newMeshCluster(newTestMeshConfig("node-a", "http://127.0.0.1:1"), pool, nil, nil)
+	require.Nil(t, err)
+	defer mesh.Close()
+	const n = 20
+	for i := 0; i < n; i++ {
+		require.Nil(t, mesh.ForwardMessage(model.NewDefaultMessage("mytopic", fmt.Sprintf("message %d", i))))
+	}
+	waitFor(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+		return fastReceived == n
+	})
+}
+
+func TestMesh_BatchCoalescing(t *testing.T) {
+	// Messages published within the linger window arrive as batches: fewer HTTP requests than
+	// messages, with nothing lost. Fails against a one-request-per-message sender.
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	var mu sync.Mutex
+	requests, messages := 0, 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, err := io.ReadAll(r.Body)
+		require.Nil(t, err)
+		decoded, err := unmarshalMessageBody(body, 1<<20)
+		require.Nil(t, err)
+		mu.Lock()
+		requests++
+		messages += len(decoded)
+		mu.Unlock()
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+	registerFakePeer(t, pool, "node-fake", srv.URL)
+	conf := newTestMeshConfig("node-a", "http://127.0.0.1:1")
+	conf.BatchLinger = 150 * time.Millisecond
+	mesh, err := newMeshCluster(conf, pool, nil, nil)
+	require.Nil(t, err)
+	defer mesh.Close()
+	const n = 20
+	for i := 0; i < n; i++ {
+		require.Nil(t, mesh.ForwardMessage(model.NewDefaultMessage("mytopic", fmt.Sprintf("message %d", i))))
+	}
+	waitFor(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+		return messages == n
+	})
+	mu.Lock()
+	defer mu.Unlock()
+	require.Less(t, requests, 5, "expected %d messages coalesced into few requests, got %d", n, requests)
+}
+
+func TestMesh_DeadPeerRemovedAndRejoin(t *testing.T) {
+	// A peer that dies ungracefully (no Deregister) stops refreshing its heartbeat: after the
+	// TTL it no longer counts as live (no more sends), its queue/worker are reconciled away, the
+	// leader prunes its registry row, and a re-registered peer starts receiving again.
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	var mu sync.Mutex
+	received := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, err := io.ReadAll(r.Body)
+		require.Nil(t, err)
+		messages, err := unmarshalMessageBody(body, 1<<20)
+		require.Nil(t, err)
+		mu.Lock()
+		received += len(messages)
+		mu.Unlock()
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+	conf := newTestMeshConfig("node-a", "http://127.0.0.1:1")
+	conf.NodeTTL = 300 * time.Millisecond // Fast expiry so the test observes TTL-based removal
+	mesh, err := newMeshCluster(conf, pool, nil, nil)
+	require.Nil(t, err)
+	defer mesh.Close()
+	// The fake peer registers once and then "dies": its heartbeat is never refreshed
+	registerFakePeer(t, pool, "node-dead", srv.URL)
+	require.Nil(t, mesh.ForwardMessage(model.NewDefaultMessage("mytopic", "while alive")))
+	waitFor(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+		return received == 1
+	})
+	// After the TTL, the peer is no longer live: its queue is reconciled away and its registry
+	// row is pruned by the leader (this mesh is the only real node, so it holds the lock)
+	waitFor(t, func() bool {
+		mesh.mu.Lock()
+		defer mesh.mu.Unlock()
+		return len(mesh.queues) == 0
+	})
+	waitFor(t, func() bool {
+		var count int
+		require.Nil(t, pool.QueryRow(`SELECT COUNT(*) FROM node_registry WHERE node_id = 'node-dead'`).Scan(&count))
+		return count == 0
+	})
+	require.Nil(t, mesh.ForwardMessage(model.NewDefaultMessage("mytopic", "while dead")))
+	time.Sleep(250 * time.Millisecond) // Give a wrong implementation time to deliver anyway
+	mu.Lock()
+	require.Equal(t, 1, received) // Only the first message arrived
+	mu.Unlock()
+	// The peer comes back (same node ID, fresh heartbeat) and receives messages again; the
+	// relay retries because the peer list is cached for up to the node TTL
+	registerFakePeer(t, pool, "node-dead", srv.URL)
+	waitFor(t, func() bool {
+		require.Nil(t, mesh.ForwardMessage(model.NewDefaultMessage("mytopic", "after rejoin")))
+		mu.Lock()
+		defer mu.Unlock()
+		return received > 1
+	})
+}
+
+func TestMesh_ForwardAfterClose(t *testing.T) {
+	// A ForwardMessage racing shutdown (e.g. an in-flight publish during server Stop) must not spawn
+	// a new peer queue and worker after Close: the worker would never exit (its queue is never
+	// closed) and nothing waits for it.
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	mesh, err := newMeshCluster(newTestMeshConfig("node-a", "http://127.0.0.1:1"), pool, nil, nil)
+	require.Nil(t, err)
+	registerFakePeer(t, pool, "node-peer", "http://127.0.0.1:1")
+	require.Nil(t, mesh.Close())
+	require.Nil(t, mesh.ForwardMessage(model.NewDefaultMessage("mytopic", "too late"))) // Dropped silently
+	mesh.mu.Lock()
+	defer mesh.mu.Unlock()
+	require.Empty(t, mesh.queues)
+}
+
+func TestMesh_LeaderFailover(t *testing.T) {
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	poolA, poolB := openTestPool(t, schemaDSN), openTestPool(t, schemaDSN)
+	meshA, err := newMeshCluster(newTestMeshConfig("node-a", "http://127.0.0.1:1"), poolA, nil, nil)
+	require.Nil(t, err)
+	defer meshA.Close()
+	meshB, err := newMeshCluster(newTestMeshConfig("node-b", "http://127.0.0.1:1"), poolB, nil, nil)
+	require.Nil(t, err)
+	defer meshB.Close()
+	// Exactly one node becomes leader
+	waitFor(t, func() bool {
+		return meshA.IsLeader() != meshB.IsLeader() // Exactly one
+	})
+	// The leader steps down; the follower takes over
+	leader, follower := meshA, meshB
+	if meshB.IsLeader() {
+		leader, follower = meshB, meshA
+	}
+	require.Nil(t, leader.Close())
+	waitFor(t, follower.IsLeader)
+}
+
+func TestMesh_CloseDeregisters(t *testing.T) {
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	mesh, err := newMeshCluster(newTestMeshConfig("node-a", "http://127.0.0.1:1"), pool, nil, nil)
+	require.Nil(t, err)
+	var count int
+	require.Nil(t, pool.QueryRow(`SELECT COUNT(*) FROM node_registry WHERE node_id = 'node-a'`).Scan(&count))
+	require.Equal(t, 1, count)
+	require.Nil(t, mesh.Close())
+	require.Nil(t, pool.QueryRow(`SELECT COUNT(*) FROM node_registry WHERE node_id = 'node-a'`).Scan(&count))
+	require.Equal(t, 0, count)
+}
+
+// postState delivers a state envelope to a mesh's peer API, as a peer would.
+func postState(c *meshCluster, origin NodeID, state *apiState) *httptest.ResponseRecorder {
+	body, err := json.Marshal(state)
+	if err != nil {
+		panic(err)
+	}
+	rr := httptest.NewRecorder()
+	req := httptest.NewRequest("POST", StatePath, bytes.NewReader(body))
+	req.Header.Set(secretHeader, testSecret)
+	req.Header.Set(originHeader, string(origin))
+	c.ServeHTTP(rr, req)
+	return rr
+}
+
+// topicFilter builds a marshaled Bloom filter over the given topics.
+func topicFilter(t *testing.T, topics ...string) []byte {
+	t.Helper()
+	filter := util.NewBloomFilter(len(topics), 0.01)
+	for _, topic := range topics {
+		filter.Add(topic)
+	}
+	data, err := filter.MarshalBinary()
+	require.Nil(t, err)
+	return data
+}
+
+func TestMesh_RouteSkipsUnsubscribedPeer(t *testing.T) {
+	// A peer whose fresh state provably excludes a topic is not contacted for it; a topic in its
+	// state is delivered as usual.
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	var mu sync.Mutex
+	received := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, err := io.ReadAll(r.Body)
+		require.Nil(t, err)
+		messages, err := unmarshalMessageBody(body, 1<<20)
+		require.Nil(t, err)
+		mu.Lock()
+		received += len(messages)
+		mu.Unlock()
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+	registerFakePeer(t, pool, "node-b", srv.URL)
+	mesh, err := newMeshCluster(newTestMeshConfig("node-a", "http://127.0.0.1:1"), pool, nil, nil)
+	require.Nil(t, err)
+	defer mesh.Close()
+	// node-b reports subscribers only for "subscribed-topic"
+	rr := postState(mesh, "node-b", &apiState{Topics: &apiStateTopics{Filter: topicFilter(t, "subscribed-topic")}})
+	require.Equal(t, 200, rr.Code)
+	// A topic outside the peer's state is skipped
+	require.Nil(t, mesh.ForwardMessage(model.NewDefaultMessage("other-topic", "skipped")))
+	time.Sleep(300 * time.Millisecond) // Give a wrong implementation time to deliver anyway
+	mu.Lock()
+	require.Equal(t, 0, received)
+	mu.Unlock()
+	// A topic inside the peer's state is delivered
+	require.Nil(t, mesh.ForwardMessage(model.NewDefaultMessage("subscribed-topic", "delivered")))
+	waitFor(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+		return received == 1
+	})
+}
+
+func TestMesh_RouteBroadcastsOnStaleState(t *testing.T) {
+	// State too old to trust cannot justify skipping: the peer is broadcast to as if unknown.
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	var mu sync.Mutex
+	received := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == MessagePath { // The mesh also pushes state here; count only messages
+			mu.Lock()
+			received++
+			mu.Unlock()
+		}
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+	registerFakePeer(t, pool, "node-b", srv.URL)
+	mesh, err := newMeshCluster(newTestMeshConfig("node-a", "http://127.0.0.1:1"), pool, nil, nil)
+	require.Nil(t, err)
+	defer mesh.Close()
+	rr := postState(mesh, "node-b", &apiState{Topics: &apiStateTopics{Filter: topicFilter(t, "subscribed-topic")}})
+	require.Equal(t, 200, rr.Code)
+	// Age the state beyond the trust window
+	mesh.statesMu.Lock()
+	mesh.states["node-b"].updatedAt = time.Now().Add(-time.Hour)
+	mesh.statesMu.Unlock()
+	require.Nil(t, mesh.ForwardMessage(model.NewDefaultMessage("other-topic", "broadcast anyway")))
+	waitFor(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+		return received == 1
+	})
+}
+
+func TestMesh_StatePushReplacesAndRemoves(t *testing.T) {
+	// Node A periodically pushes a full snapshot of its live topics to node B; each snapshot
+	// REPLACES B's knowledge, so topics that lost their subscribers disappear without any
+	// explicit removal protocol.
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	poolA, poolB := openTestPool(t, schemaDSN), openTestPool(t, schemaDSN)
+	var topicsMu sync.Mutex
+	topicsA := []string{"topic-1"}
+	source := func() []string {
+		topicsMu.Lock()
+		defer topicsMu.Unlock()
+		return append([]string{}, topicsA...)
+	}
+	var meshB *meshCluster
+	srvB := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		meshB.ServeHTTP(w, r)
+	}))
+	defer srvB.Close()
+	meshB, err := newMeshCluster(newTestMeshConfig("node-b", srvB.URL), poolB, nil, nil)
+	require.Nil(t, err)
+	defer meshB.Close()
+	confA := newTestMeshConfig("node-a", "http://127.0.0.1:1")
+	confA.StateInterval = 200 * time.Millisecond
+	meshA, err := newMeshCluster(confA, poolA, nil, source)
+	require.Nil(t, err)
+	defer meshA.Close()
+	// B learns A's topics via the periodic push
+	knows := func(topic string) func() bool {
+		return func() bool {
+			meshB.statesMu.Lock()
+			defer meshB.statesMu.Unlock()
+			state, ok := meshB.states["node-a"]
+			return ok && state.topics.Contains(topic)
+		}
+	}
+	waitFor(t, knows("topic-1"))
+	// A's subscribers change; the next snapshot replaces the old knowledge entirely
+	topicsMu.Lock()
+	topicsA = []string{"topic-2"}
+	topicsMu.Unlock()
+	waitFor(t, knows("topic-2"))
+	waitFor(t, func() bool { return !knows("topic-1")() })
+}
+
+func TestMesh_AnnounceClosesWindow(t *testing.T) {
+	// A topic gaining its first subscriber is announced immediately, so peers learn about it
+	// without waiting for the next full state push.
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	poolA, poolB := openTestPool(t, schemaDSN), openTestPool(t, schemaDSN)
+	var meshB *meshCluster
+	srvB := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		meshB.ServeHTTP(w, r)
+	}))
+	defer srvB.Close()
+	meshB, err := newMeshCluster(newTestMeshConfig("node-b", srvB.URL), poolB, nil, nil)
+	require.Nil(t, err)
+	defer meshB.Close()
+	confA := newTestMeshConfig("node-a", "http://127.0.0.1:1")
+	confA.StateInterval = 200 * time.Millisecond // One full push establishes the baseline
+	meshA, err := newMeshCluster(confA, poolA, nil, func() []string { return []string{"existing"} })
+	require.Nil(t, err)
+	defer meshA.Close()
+	waitFor(t, func() bool {
+		meshB.statesMu.Lock()
+		defer meshB.statesMu.Unlock()
+		_, ok := meshB.states["node-a"]
+		return ok
+	})
+	// Announcements merge into the baseline right away
+	meshA.BroadcastState(&State{AddedTopics: []string{"fresh-topic"}})
+	waitFor(t, func() bool {
+		meshB.statesMu.Lock()
+		defer meshB.statesMu.Unlock()
+		state, ok := meshB.states["node-a"]
+		return ok && state.topics.Contains("fresh-topic")
+	})
+}
+
+func TestMesh_StateOfDepartedPeerPruned(t *testing.T) {
+	// peerState is push-driven and can arrive before the peer is visible in the registry, so it
+	// must survive reconcile while fresh -- but a departed peer's state must not leak forever:
+	// once it is both absent from the registry and stale past the trust window, it is pruned.
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	mesh, err := newMeshCluster(newTestMeshConfig("node-a", "http://127.0.0.1:1"), pool, nil, nil)
+	require.Nil(t, err)
+	defer mesh.Close()
+	rr := postState(mesh, "node-gone", &apiState{Topics: &apiStateTopics{Filter: topicFilter(t, "some-topic")}})
+	require.Equal(t, 200, rr.Code)
+	// Fresh state of an unknown peer survives reconcile (the new-node visibility window)
+	mesh.reconcilePeers(nil)
+	mesh.statesMu.Lock()
+	_, ok := mesh.states["node-gone"]
+	mesh.statesMu.Unlock()
+	require.True(t, ok)
+	// Stale state of an absent peer is pruned
+	mesh.statesMu.Lock()
+	mesh.states["node-gone"].updatedAt = time.Now().Add(-time.Hour)
+	mesh.statesMu.Unlock()
+	mesh.reconcilePeers(nil)
+	mesh.statesMu.Lock()
+	_, ok = mesh.states["node-gone"]
+	mesh.statesMu.Unlock()
+	require.False(t, ok)
+}
+
+func TestMesh_HealthyReflectsRegistration(t *testing.T) {
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	mesh, err := newMeshCluster(newTestMeshConfig("node-a", "http://127.0.0.1:1"), pool, nil, nil)
+	require.Nil(t, err)
+	defer mesh.Close()
+	require.True(t, mesh.Healthy()) // Registered synchronously at construction
+	// Stale heartbeat: peers stop forwarding to this node, so it must report unhealthy
+	mesh.mu.Lock()
+	mesh.lastRegistered = time.Now().Add(-2 * mesh.conf.NodeTTL)
+	mesh.mu.Unlock()
+	require.False(t, mesh.Healthy())
+	// A successful heartbeat restores health
+	require.Nil(t, mesh.heartbeat())
+	require.True(t, mesh.Healthy())
+}

cluster/cluster_nop.go

@@ -0,0 +1,26 @@
+package cluster
+
+import (
+	"net/http"
+
+	"heckel.io/ntfy/v2/model"
+)
+
+// nopCluster is the single-node default: it drops all relayed messages, rejects peer API requests, and
+// reports this node as leader (a single node is trivially the leader, so leader-gated jobs need
+// no special-casing in single-node mode).
+type nopCluster struct{}
+
+func (c *nopCluster) ForwardMessage(_ *model.Message) error { return nil }
+
+func (c *nopCluster) ServeHTTP(w http.ResponseWriter, _ *http.Request) {
+	w.WriteHeader(http.StatusNotFound)
+}
+
+func (c *nopCluster) BroadcastState(_ *State) {}
+
+func (c *nopCluster) IsLeader() bool { return true }
+
+func (c *nopCluster) Healthy() bool { return true }
+
+func (c *nopCluster) Close() error { return nil }

cluster/cluster_test.go

@@ -0,0 +1,84 @@
+package cluster
+
+import (
+	"bytes"
+	"net/http/httptest"
+	"net/netip"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"heckel.io/ntfy/v2/model"
+)
+
+func TestDeliver_RoundTrip(t *testing.T) {
+	// The fan-out body is NDJSON: one apiDeliverMessage per line, joined from pre-marshaled
+	// fragments; the origin travels in a header, not the body
+	m1 := model.NewDefaultMessage("mytopic", "my message")
+	m1.Sender = netip.MustParseAddr("1.2.3.4")
+	m1.User = "u_abc"
+	m2 := model.NewDefaultMessage("othertopic", "other message")
+	frag1, err := marshalMessage(m1)
+	require.Nil(t, err)
+	frag2, err := marshalMessage(m2)
+	require.Nil(t, err)
+	messages, err := unmarshalMessageBody(assembleMessageBody([][]byte{frag1, frag2}), 1<<20)
+	require.Nil(t, err)
+	require.Len(t, messages, 2)
+	require.Equal(t, "mytopic", messages[0].Topic)
+	require.Equal(t, "my message", messages[0].Message)
+	// Sender and User are json:"-" on model.Message; the lines must carry and reattach them
+	require.Equal(t, netip.MustParseAddr("1.2.3.4"), messages[0].Sender)
+	require.Equal(t, "u_abc", messages[0].User)
+	require.Equal(t, "othertopic", messages[1].Topic)
+	require.False(t, messages[1].Sender.IsValid())
+}
+
+func TestDeliver_SingleMessage(t *testing.T) {
+	// A single message is just a one-line body; there is no separate single-message format
+	frag, err := marshalMessage(model.NewDefaultMessage("mytopic", "hi"))
+	require.Nil(t, err)
+	messages, err := unmarshalMessageBody(assembleMessageBody([][]byte{frag}), 1<<20)
+	require.Nil(t, err)
+	require.Len(t, messages, 1)
+}
+
+func TestDeliver_MalformedLinesSkipped(t *testing.T) {
+	// Fan-out is fire-and-forget: a malformed or message-less line is skipped (and logged), the
+	// remaining lines are still delivered
+	frag, err := marshalMessage(model.NewDefaultMessage("mytopic", "good"))
+	require.Nil(t, err)
+	body := []byte("this is not json\n{\"sender\":\"1.2.3.4\"}\n" + string(frag) + "\n\n")
+	messages, err := unmarshalMessageBody(body, 1<<20)
+	require.Nil(t, err)
+	require.Len(t, messages, 1)
+	require.Equal(t, "good", messages[0].Message)
+}
+
+// unmarshalMessageBody is a test helper collecting the messages of an NDJSON message body.
+func unmarshalMessageBody(body []byte, maxLineBytes int) ([]*model.Message, error) {
+	var messages []*model.Message
+	err := decodeMessageBody(bytes.NewReader(body), maxLineBytes, func(m *model.Message) {
+		messages = append(messages, m)
+	})
+	return messages, err
+}
+
+func TestNop(t *testing.T) {
+	b, err := New(&Config{}, nil, nil, nil) // not enabled -> nop cluster, no database required
+	require.Nil(t, err)
+	require.IsType(t, &nopCluster{}, b)
+	require.Nil(t, b.ForwardMessage(model.NewDefaultMessage("mytopic", "hi")))
+	// A single node is trivially the leader, so leader-gated jobs run without special-casing
+	require.True(t, b.IsLeader())
+	require.True(t, b.Healthy())
+	rr := httptest.NewRecorder()
+	b.ServeHTTP(rr, httptest.NewRequest("POST", MessagePath, nil))
+	require.Equal(t, 404, rr.Code)
+	require.Nil(t, b.Close())
+}
+
+func TestNew_EnabledRequiresDatabase(t *testing.T) {
+	_, err := New(&Config{Enabled: true, Secret: "secret"}, nil, nil, nil)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "database")
+}

cluster/registry/registry.go

@@ -0,0 +1,149 @@
+// Package registry implements cluster membership: each node upserts its own row into the
+// node_registry table with a fresh heartbeat, and discovers its peers by reading the other
+// fresh rows. Node IDs are plain strings here; the cluster package layers its NodeID type on
+// top.
+package registry
+
+import (
+	"sync"
+	"time"
+
+	"heckel.io/ntfy/v2/db"
+	"heckel.io/ntfy/v2/db/schema"
+)
+
+// Registry queries
+const (
+	upsertNodeQuery = `
+		INSERT INTO node_registry (node_id, advertise_url, last_heartbeat)
+		VALUES ($1, $2, $3)
+		ON CONFLICT (node_id) DO UPDATE SET advertise_url = EXCLUDED.advertise_url, last_heartbeat = EXCLUDED.last_heartbeat
+	`
+	selectPeersQuery     = `SELECT node_id, advertise_url FROM node_registry WHERE last_heartbeat >= $1 AND node_id != $2`
+	pruneStaleNodesQuery = `DELETE FROM node_registry WHERE last_heartbeat < $1`
+	deleteNodeQuery      = `DELETE FROM node_registry WHERE node_id = $1`
+)
+
+// Schema version and queries
+
+const (
+	schemaVersion  = 1
+	schemaStoreKey = "node_registry"
+)
+
+var (
+	createTable = schema.AsMigrateFunc(`
+		CREATE TABLE IF NOT EXISTS node_registry (
+			node_id        TEXT PRIMARY KEY,
+			advertise_url  TEXT NOT NULL,
+			last_heartbeat BIGINT NOT NULL
+		)
+	`)
+)
+
+// Peer is a live remote node as read from the registry.
+type Peer struct {
+	NodeID       string
+	AdvertiseURL string
+}
+
+// Registry is the node membership table (control plane): each node upserts its own row with a
+// fresh heartbeat every few seconds, and peers are the other rows with a heartbeat newer than
+// the TTL. Stale rows are pruned by the leader. The TTL bounds membership staleness in BOTH
+// directions: how long a silent node still counts as live, and how long the cached peer list is
+// served before a re-read -- so a new node may take up to a TTL to become visible.
+type Registry struct {
+	pool         *db.DB
+	nodeID       string
+	advertiseURL string
+	ttl          time.Duration
+	peers        []*Peer // cached peer list
+	peersFetched time.Time
+	mu           sync.Mutex // Protects peers and peersFetched
+}
+
+// New creates or migrates the registry schema and returns this node's membership handle. It
+// does NOT register the node: joining the cluster is an explicit Register call, owned by the
+// caller, so read-only uses of the registry stay side-effect free.
+func New(pool *db.DB, nodeID, advertiseURL string, ttl time.Duration) (*Registry, error) {
+	if err := schema.Migrate(pool.Primary(), schema.Postgres, schemaStoreKey, schemaVersion, createTable, nil); err != nil {
+		return nil, err
+	}
+	return &Registry{
+		pool:         pool,
+		nodeID:       nodeID,
+		advertiseURL: advertiseURL,
+		ttl:          ttl,
+	}, nil
+}
+
+// Register upserts this node into the registry with a fresh heartbeat. It is a pure write: it
+// does not touch the peer cache, because our own row is excluded from Peers() anyway.
+func (r *Registry) Register() error {
+	_, err := r.pool.Exec(upsertNodeQuery, r.nodeID, r.advertiseURL, time.Now().Unix())
+	return err
+}
+
+// Peers returns the current set of live peer nodes (all registry rows with a fresh heartbeat,
+// excluding this node), cached for the TTL.
+func (r *Registry) Peers() ([]*Peer, error) {
+	r.mu.Lock()
+	if r.peers != nil && time.Since(r.peersFetched) < r.ttl {
+		peers := r.peers
+		r.mu.Unlock()
+		return peers, nil
+	}
+	r.mu.Unlock()
+	peers, err := r.queryPeers()
+	if err != nil {
+		// Serve the last-known peer list during database hiccups: fan-out keeps flowing to
+		// known peers instead of erroring (and logging) once per published message for the
+		// duration of the outage. Dead peers in the stale list only cost failed sends.
+		r.mu.Lock()
+		defer r.mu.Unlock()
+		if r.peers != nil {
+			return r.peers, nil
+		}
+		return nil, err
+	}
+	r.mu.Lock()
+	r.peers = peers
+	r.peersFetched = time.Now()
+	r.mu.Unlock()
+	return peers, nil
+}
+
+// Prune deletes registry rows whose heartbeat is long expired. Only the leader calls this; the
+// grace period of 3x the TTL avoids deleting rows of nodes that are merely slow to heartbeat.
+func (r *Registry) Prune() error {
+	_, err := r.pool.Exec(pruneStaleNodesQuery, time.Now().Add(-3*r.ttl).Unix())
+	return err
+}
+
+// Deregister deletes this node's registry row; called on shutdown.
+func (r *Registry) Deregister() error {
+	_, err := r.pool.Exec(deleteNodeQuery, r.nodeID)
+	return err
+}
+
+// queryPeers reads the current live peer set from the registry table.
+func (r *Registry) queryPeers() ([]*Peer, error) {
+	cutoff := time.Now().Add(-r.ttl).Unix()
+	rows, err := r.pool.Query(selectPeersQuery, cutoff, r.nodeID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	peers := make([]*Peer, 0)
+	for rows.Next() {
+		p := &Peer{}
+		if err := rows.Scan(&p.NodeID, &p.AdvertiseURL); err != nil {
+			return nil, err
+		}
+		peers = append(peers, p)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return peers, nil
+}

cluster/registry/registry_test.go

@@ -0,0 +1,222 @@
+package registry
+
+import (
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"heckel.io/ntfy/v2/db"
+	"heckel.io/ntfy/v2/db/pg"
+	dbtest "heckel.io/ntfy/v2/db/test"
+)
+
+func openTestPool(t *testing.T, dsn string) *db.DB {
+	t.Helper()
+	host, err := pg.Open(dsn)
+	require.Nil(t, err)
+	d := db.New(host, nil)
+	t.Cleanup(func() { d.Close() })
+	return d
+}
+
+func TestRegistry_NewDoesNotRegister(t *testing.T) {
+	// New only sets up the schema and the identity handle; joining the cluster is an explicit
+	// Register call, owned by the caller (the mesh registers synchronously at construction).
+	// This keeps read-only uses (ops tooling, future admin endpoints) side-effect free.
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	r1, err := New(pool, "node-1", "http://10.0.0.1:2587", time.Minute)
+	require.Nil(t, err)
+	require.Equal(t, 0, countRows(t, pool, "node-1"))
+	require.Nil(t, r1.Register())
+	require.Equal(t, 1, countRows(t, pool, "node-1"))
+}
+
+func TestRegistry_RegisterAndPeers(t *testing.T) {
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	r1, err := New(pool, "node-1", "http://10.0.0.1:2587", time.Minute)
+	require.Nil(t, err)
+	require.Nil(t, r1.Register())
+	r2, err := New(pool, "node-2", "http://10.0.0.2:2587", time.Minute)
+	require.Nil(t, err)
+	require.Nil(t, r2.Register())
+	// Each node sees the other, never itself
+	peers, err := r1.Peers()
+	require.Nil(t, err)
+	require.Len(t, peers, 1)
+	require.Equal(t, "node-2", peers[0].NodeID)
+	require.Equal(t, "http://10.0.0.2:2587", peers[0].AdvertiseURL)
+	peers, err = r2.Peers()
+	require.Nil(t, err)
+	require.Len(t, peers, 1)
+	require.Equal(t, "node-1", peers[0].NodeID)
+}
+
+func TestRegistry_ReRegisterUpdatesAdvertiseURL(t *testing.T) {
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	r1, err := New(pool, "node-1", "http://10.0.0.1:2587", time.Minute)
+	require.Nil(t, err)
+	// The same node comes back under a new address; the upsert replaces the row
+	old, err := New(pool, "node-2", "http://old:2587", time.Minute)
+	require.Nil(t, err)
+	require.Nil(t, old.Register())
+	renewed, err := New(pool, "node-2", "http://new:2587", time.Minute)
+	require.Nil(t, err)
+	require.Nil(t, renewed.Register())
+	expireCache(r1)
+	peers, err := r1.Peers()
+	require.Nil(t, err)
+	require.Len(t, peers, 1)
+	require.Equal(t, "http://new:2587", peers[0].AdvertiseURL)
+}
+
+func TestRegistry_PeersCachedForTTL(t *testing.T) {
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	r1, err := New(pool, "node-1", "http://10.0.0.1:2587", time.Minute)
+	require.Nil(t, err)
+	peers, err := r1.Peers()
+	require.Nil(t, err)
+	require.Empty(t, peers)
+	// A node joining after the cache was populated is invisible until the cache expires
+	r2, err := New(pool, "node-2", "http://10.0.0.2:2587", time.Minute)
+	require.Nil(t, err)
+	require.Nil(t, r2.Register())
+	peers, err = r1.Peers()
+	require.Nil(t, err)
+	require.Empty(t, peers)
+	expireCache(r1)
+	peers, err = r1.Peers()
+	require.Nil(t, err)
+	require.Len(t, peers, 1)
+}
+
+func TestRegistry_TTLExcludesSilentNodes(t *testing.T) {
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	r1, err := New(pool, "node-1", "http://10.0.0.1:2587", time.Minute)
+	require.Nil(t, err)
+	// A node whose heartbeat is older than the TTL does not count as live
+	_, err = pool.Exec(upsertNodeQuery, "node-silent", "http://10.0.0.9:2587", time.Now().Add(-2*time.Minute).Unix())
+	require.Nil(t, err)
+	peers, err := r1.Peers()
+	require.Nil(t, err)
+	require.Empty(t, peers)
+}
+
+func TestRegistry_PruneDeletesLongDeadOnly(t *testing.T) {
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	r1, err := New(pool, "node-1", "http://10.0.0.1:2587", time.Minute)
+	require.Nil(t, err)
+	// One node beyond the 3x TTL grace period, one merely stale
+	_, err = pool.Exec(upsertNodeQuery, "node-long-dead", "http://10.0.0.8:2587", time.Now().Add(-4*time.Minute).Unix())
+	require.Nil(t, err)
+	_, err = pool.Exec(upsertNodeQuery, "node-slow", "http://10.0.0.9:2587", time.Now().Add(-2*time.Minute).Unix())
+	require.Nil(t, err)
+	require.Nil(t, r1.Prune())
+	require.Equal(t, 0, countRows(t, pool, "node-long-dead"))
+	require.Equal(t, 1, countRows(t, pool, "node-slow")) // Slow, not dead: kept
+}
+
+func TestRegistry_Deregister(t *testing.T) {
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	r1, err := New(pool, "node-1", "http://10.0.0.1:2587", time.Minute)
+	require.Nil(t, err)
+	require.Nil(t, r1.Register())
+	require.Equal(t, 1, countRows(t, pool, "node-1"))
+	require.Nil(t, r1.Deregister())
+	require.Equal(t, 0, countRows(t, pool, "node-1"))
+}
+
+func TestRegistry_PeersStaleCacheOnError(t *testing.T) {
+	// During a database hiccup, Peers serves the last-known peer list instead of erroring:
+	// fan-out keeps flowing to known peers, and the publish path does not log a warning per
+	// message for the duration of the outage.
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	r1, err := New(pool, "node-1", "http://10.0.0.1:2587", time.Minute)
+	require.Nil(t, err)
+	r2, err := New(pool, "node-2", "http://10.0.0.2:2587", time.Minute)
+	require.Nil(t, err)
+	require.Nil(t, r2.Register())
+	peers, err := r1.Peers()
+	require.Nil(t, err)
+	require.Len(t, peers, 1)
+	// Expire the cache and break the database; the stale list must still be served
+	expireCache(r1)
+	require.Nil(t, pool.Close())
+	peers, err = r1.Peers()
+	require.Nil(t, err)
+	require.Len(t, peers, 1)
+	require.Equal(t, "node-2", peers[0].NodeID)
+}
+
+func TestRegistry_ConcurrentCreate(t *testing.T) {
+	// Multiple nodes cold-booting on a fresh database must not race on table creation: CREATE
+	// TABLE IF NOT EXISTS is not atomic in PostgreSQL, so creation is serialized via an advisory
+	// lock. Without it, this test fails sporadically with a duplicate-key error on pg_class.
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	const n = 8
+	errs := make(chan error, n)
+	for i := 0; i < n; i++ {
+		go func(i int) {
+			pool, err := pg.Open(schemaDSN)
+			if err != nil {
+				errs <- err
+				return
+			}
+			defer pool.DB.Close()
+			_, err = New(db.New(pool, nil), fmt.Sprintf("node-%d", i), "http://127.0.0.1:1", time.Second)
+			errs <- err
+		}(i)
+	}
+	for i := 0; i < n; i++ {
+		require.Nil(t, <-errs)
+	}
+}
+
+func TestRegistry_SchemaVersionWritten(t *testing.T) {
+	// The registry participates in the shared schema_version framework like every other store,
+	// so future table changes can be applied as migrations.
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	_, err := New(pool, "node-1", "http://10.0.0.1:2587", time.Minute)
+	require.Nil(t, err)
+	var version int
+	require.Nil(t, pool.QueryRow(`SELECT version FROM schema_version WHERE store = $1`, schemaStoreKey).Scan(&version))
+	require.Equal(t, schemaVersion, version)
+	// Setup is idempotent: a second node boots against the migrated schema
+	_, err = New(pool, "node-2", "http://10.0.0.2:2587", time.Minute)
+	require.Nil(t, err)
+}
+
+func TestRegistry_SchemaVersionFromTheFuture(t *testing.T) {
+	// A node running older code must refuse to touch a schema migrated by newer code
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	pool := openTestPool(t, schemaDSN)
+	_, err := New(pool, "node-1", "http://10.0.0.1:2587", time.Minute)
+	require.Nil(t, err)
+	_, err = pool.Exec(`UPDATE schema_version SET version = 99 WHERE store = $1`, schemaStoreKey)
+	require.Nil(t, err)
+	_, err = New(pool, "node-2", "http://10.0.0.2:2587", time.Minute)
+	require.Error(t, err)
+}
+
+// expireCache forces the next Peers() call to re-read the registry table.
+func expireCache(r *Registry) {
+	r.mu.Lock()
+	r.peersFetched = time.Time{}
+	r.mu.Unlock()
+}
+
+func countRows(t *testing.T, pool *db.DB, nodeID string) int {
+	t.Helper()
+	var count int
+	require.Nil(t, pool.QueryRow(`SELECT COUNT(*) FROM node_registry WHERE node_id = $1`, nodeID).Scan(&count))
+	return count
+}

cluster/types.go

@@ -0,0 +1,76 @@
+package cluster
+
+import (
+	"time"
+
+	"heckel.io/ntfy/v2/model"
+	"heckel.io/ntfy/v2/util"
+)
+
+// Config configures the cluster. It is assembled by the server from its own config, which keeps
+// this package free of server types.
+type Config struct {
+	Enabled             bool          // Master switch; when false, New returns the nop cluster
+	NodeID              NodeID        // Stable per-node identifier; required
+	AdvertiseURL        string        // Base URL peers use to reach this node's fan-out endpoint
+	Secret              string        // Shared secret authenticating node-to-node fan-out requests
+	HeartbeatInterval   time.Duration // How often the node registry heartbeat is refreshed
+	NodeTTL             time.Duration // Registry rows older than this do not count as live peers
+	BatchLinger         time.Duration // How long messages wait in a peer queue to form a batch; 0 = send immediately
+	StateInterval       time.Duration // How often the full subscription state is pushed to peers
+	MaxMessageBytes     int64         // Upper bound for a single message on the wire (batch limits derive from this)
+	LeaderRenewInterval time.Duration // Overrides the leader lease renewal cadence; tests only, 0 = default
+}
+
+// DeliverFunc hands a message received from a peer node to this node's local subscribers. The
+// server supplies it, which inverts the dependency: this package never imports the server.
+type DeliverFunc func(m *model.Message)
+
+// State is a subscription-state delta for Cluster.BroadcastState.
+type State struct {
+	AddedTopics []string // Topics that just gained their first local subscriber on this node
+}
+
+// TopicsFunc returns the topics that currently have at least one live subscriber, computed
+// fresh on every call: membership is never tracked as a list, so topics "leave" simply by not
+// appearing in the next snapshot. The server supplies it (same inversion as DeliverFunc).
+type TopicsFunc func() []string
+
+// apiMessage is one line of a message request body (NDJSON: one message per line; a single
+// message is just a one-line body). It carries the two fields that model.Message does not
+// serialize to JSON (Sender and User), which are needed to reconstruct the visitor on the
+// receiving node. The origin node travels in a request header, not in the body.
+type apiMessage struct {
+	Sender  string         `json:"sender,omitempty"`
+	User    string         `json:"user,omitempty"`
+	Message *model.Message `json:"message"`
+}
+
+// apiState is the peer state-exchange envelope. Each concern is an optional section; future
+// concerns (rate limit counters, stats) become siblings of Topics.
+type apiState struct {
+	Topics *apiStateTopics `json:"topics,omitempty"`
+}
+
+// apiStateTopics carries a peer's subscription knowledge: either a full snapshot (Filter, a
+// marshaled Bloom filter over the topics with live subscribers) replacing all prior knowledge,
+// or an incremental update (Added) merged into it.
+type apiStateTopics struct {
+	Filter []byte   `json:"filter,omitempty"`
+	Added  []string `json:"added,omitempty"`
+}
+
+// peerState is what a peer last told us about itself; ForwardMessage routes around peers whose
+// fresh state provably excludes a topic.
+type peerState struct {
+	topics    *util.BloomFilter
+	updatedAt time.Time
+}
+
+// peerQueue is the bounded, batching send queue for a single peer, pinned to the advertise URL
+// the peer was created with: a peer re-registering under a different advertise URL is treated
+// as a replacement (reconcile retires the old queue; ForwardMessage creates a fresh one on demand).
+type peerQueue struct {
+	advertiseURL string
+	queue        *util.LingerQueue[[]byte] // pre-marshaled apiMessage fragments
+}

cluster/util.go

@@ -0,0 +1,69 @@
+package cluster
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/json"
+	"io"
+	"net/netip"
+	"strings"
+
+	"heckel.io/ntfy/v2/log"
+	"heckel.io/ntfy/v2/model"
+)
+
+// messageURL derives the peer's message endpoint URL from its advertise URL.
+func messageURL(advertiseURL string) string {
+	return strings.TrimRight(advertiseURL, "/") + MessagePath
+}
+
+// stateURL derives the peer's state endpoint URL from its advertise URL.
+func stateURL(advertiseURL string) string {
+	return strings.TrimRight(advertiseURL, "/") + StatePath
+}
+
+// marshalMessage serializes one message and its non-JSON fields (Sender, User) as an
+// apiMessage line. Lines are marshaled once per publish and shared across all per-peer
+// queues; assembleMessageBody joins them without re-marshaling.
+func marshalMessage(m *model.Message) ([]byte, error) {
+	apiMsg := &apiMessage{User: m.User, Message: m}
+	if m.Sender.IsValid() {
+		apiMsg.Sender = m.Sender.String()
+	}
+	return json.Marshal(apiMsg)
+}
+
+// assembleMessageBody builds an NDJSON fan-out request body from pre-marshaled apiMessage
+// lines, avoiding a second JSON marshal of the messages.
+func assembleMessageBody(frags [][]byte) []byte {
+	return append(bytes.Join(frags, []byte("\n")), '\n')
+}
+
+// decodeMessageBody reads NDJSON apiMessage lines from r, reattaches the non-JSON fields
+// (Sender, User) onto each message, and hands them to deliver. Malformed or message-less lines
+// are skipped and logged, not fatal: fan-out is fire-and-forget, so the valid remainder of a
+// request is still delivered. It returns an error only for stream-level failures (e.g. a line
+// exceeding maxLineBytes).
+func decodeMessageBody(r io.Reader, maxLineBytes int, deliver DeliverFunc) error {
+	scanner := bufio.NewScanner(r)
+	scanner.Buffer(make([]byte, 64*1024), maxLineBytes)
+	for scanner.Scan() {
+		line := bytes.TrimSpace(scanner.Bytes())
+		if len(line) == 0 {
+			continue
+		}
+		var apiMsg apiMessage
+		if err := json.Unmarshal(line, &apiMsg); err != nil || apiMsg.Message == nil {
+			log.Tag(tag).Warn("Skipping malformed fan-out line")
+			continue
+		}
+		apiMsg.Message.User = apiMsg.User
+		if apiMsg.Sender != "" {
+			if addr, err := netip.ParseAddr(apiMsg.Sender); err == nil {
+				apiMsg.Message.Sender = addr
+			}
+		}
+		deliver(apiMsg.Message)
+	}
+	return scanner.Err()
+}

cmd/serve.go

@@ -10,6 +10,7 @@ import (
 	"net"
 	"net/netip"
 	"net/url"
+	"path/filepath"
 	"runtime"
 	"strings"
 	"text/template"
@@ -17,6 +18,8 @@ import (
 
 	"github.com/urfave/cli/v2"
 	"github.com/urfave/cli/v2/altsrc"
+	"heckel.io/ntfy/v2/ban"
+	"heckel.io/ntfy/v2/cluster"
 	"heckel.io/ntfy/v2/log"
 	"heckel.io/ntfy/v2/payments"
 	"heckel.io/ntfy/v2/server"
@@ -41,6 +44,11 @@ var flagsServe = append(
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "firebase-key-file", Aliases: []string{"firebase_key_file", "F"}, EnvVars: []string{"NTFY_FIREBASE_KEY_FILE"}, Usage: "Firebase credentials file; if set additionally publish to FCM topic"}),
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "database-url", Aliases: []string{"database_url"}, EnvVars: []string{"NTFY_DATABASE_URL"}, Usage: "PostgreSQL connection string for database-backed stores (e.g. postgres://user:pass@host:5432/ntfy)"}),
 	altsrc.NewStringSliceFlag(&cli.StringSliceFlag{Name: "database-replica-urls", Aliases: []string{"database_replica_urls"}, EnvVars: []string{"NTFY_DATABASE_REPLICA_URLS"}, Usage: "PostgreSQL read replica connection strings for offloading read queries"}),
+	altsrc.NewStringFlag(&cli.StringFlag{Name: "cluster-node-id", Aliases: []string{"cluster_node_id"}, EnvVars: []string{"NTFY_CLUSTER_NODE_ID"}, Usage: "stable per-node identifier for the cluster node registry (required in cluster mode)"}),
+	altsrc.NewStringFlag(&cli.StringFlag{Name: "cluster-listen", Aliases: []string{"cluster_listen"}, EnvVars: []string{"NTFY_CLUSTER_LISTEN"}, Usage: "ip:port for the dedicated cluster fan-out listener; bind it to the private network (e.g. 10.0.0.5:2587)"}),
+	altsrc.NewStringFlag(&cli.StringFlag{Name: "cluster-advertise-url", Aliases: []string{"cluster_advertise_url"}, EnvVars: []string{"NTFY_CLUSTER_ADVERTISE_URL"}, Usage: "base URL peer nodes use to reach this node's fan-out listener (defaults to http://<cluster-listen>)"}),
+	altsrc.NewStringFlag(&cli.StringFlag{Name: "cluster-secret", Aliases: []string{"cluster_secret"}, EnvVars: []string{"NTFY_CLUSTER_SECRET"}, Usage: "shared secret authenticating node-to-node fan-out requests"}),
+	altsrc.NewStringFlag(&cli.StringFlag{Name: "cluster-batch-linger", Aliases: []string{"cluster_batch_linger"}, EnvVars: []string{"NTFY_CLUSTER_BATCH_LINGER"}, Value: util.FormatDuration(cluster.DefaultBatchLinger), Usage: "how long fan-out messages wait to form a batch per peer node (0 = send immediately)"}),
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "cache-file", Aliases: []string{"cache_file", "C"}, EnvVars: []string{"NTFY_CACHE_FILE"}, Usage: "cache file used for message caching"}),
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "cache-duration", Aliases: []string{"cache_duration", "b"}, EnvVars: []string{"NTFY_CACHE_DURATION"}, Value: util.FormatDuration(server.DefaultCacheDuration), Usage: "buffer messages for this time to allow `since` requests"}),
 	altsrc.NewIntFlag(&cli.IntFlag{Name: "cache-batch-size", Aliases: []string{"cache_batch_size"}, EnvVars: []string{"NTFY_BATCH_SIZE"}, Usage: "max size of messages to batch together when writing to message cache (if zero, writes are synchronous)"}),
@@ -98,6 +106,10 @@ var flagsServe = append(
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "visitor-topic-creation-limit-replenish", Aliases: []string{"visitor_topic_creation_limit_replenish"}, EnvVars: []string{"NTFY_VISITOR_TOPIC_CREATION_LIMIT_REPLENISH"}, Value: util.FormatDuration(server.DefaultVisitorTopicCreationLimitReplenish), Usage: "interval at which topic-creation tokens are refilled (one per x)"}),
 	altsrc.NewIntFlag(&cli.IntFlag{Name: "visitor-prefix-bits-ipv4", Aliases: []string{"visitor_prefix_bits_ipv4"}, EnvVars: []string{"NTFY_VISITOR_PREFIX_BITS_IPV4"}, Value: server.DefaultVisitorPrefixBitsIPv4, Usage: "number of bits of the IPv4 address to use for rate limiting (default: 32, full address)"}),
 	altsrc.NewIntFlag(&cli.IntFlag{Name: "visitor-prefix-bits-ipv6", Aliases: []string{"visitor_prefix_bits_ipv6"}, EnvVars: []string{"NTFY_VISITOR_PREFIX_BITS_IPV6"}, Value: server.DefaultVisitorPrefixBitsIPv6, Usage: "number of bits of the IPv6 address to use for rate limiting (default: 64, /64 subnet)"}),
+	altsrc.NewStringFlag(&cli.StringFlag{Name: "ban-file", Aliases: []string{"ban_file"}, EnvVars: []string{"NTFY_BAN_FILE"}, Value: "", Usage: "if set, append IPs of abusive visitors to this file for fail2ban to tail (empty disables)"}),
+	altsrc.NewStringFlag(&cli.StringFlag{Name: "ban-window", Aliases: []string{"ban_window"}, EnvVars: []string{"NTFY_BAN_WINDOW"}, Value: util.FormatDuration(server.DefaultBanWindow), Usage: "rolling window over which weighted strikes are counted for the ban file"}),
+	altsrc.NewIntFlag(&cli.IntFlag{Name: "ban-threshold", Aliases: []string{"ban_threshold"}, EnvVars: []string{"NTFY_BAN_THRESHOLD"}, Value: server.DefaultBanThreshold, Usage: "weighted strikes per window before an offender is banned"}),
+	altsrc.NewStringSliceFlag(&cli.StringSliceFlag{Name: "ban-weights", Aliases: []string{"ban_weights"}, EnvVars: []string{"NTFY_BAN_WEIGHTS"}, Value: cli.NewStringSlice(server.DefaultBanWeights...), Usage: "per-code strike weights as KEY:WEIGHT, where KEY is an ntfy code, an HTTP status, a PREFIX*, or '*' (weight 0 exempts)"}),
 	altsrc.NewBoolFlag(&cli.BoolFlag{Name: "behind-proxy", Aliases: []string{"behind_proxy", "P"}, EnvVars: []string{"NTFY_BEHIND_PROXY"}, Value: false, Usage: "if set, use forwarded header (e.g. X-Forwarded-For, X-Client-IP) to determine visitor IP address (for rate limiting)"}),
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "proxy-forwarded-header", Aliases: []string{"proxy_forwarded_header"}, EnvVars: []string{"NTFY_PROXY_FORWARDED_HEADER"}, Value: "X-Forwarded-For", Usage: "use specified header to determine visitor IP address (for rate limiting)"}),
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "proxy-trusted-hosts", Aliases: []string{"proxy_trusted_hosts"}, EnvVars: []string{"NTFY_PROXY_TRUSTED_HOSTS"}, Value: "", Usage: "comma-separated list of trusted IP addresses, hosts, or CIDRs to remove from forwarded header"}),
@@ -151,6 +163,11 @@ func execServe(c *cli.Context) error {
 	firebaseKeyFile := c.String("firebase-key-file")
 	databaseURL := c.String("database-url")
 	databaseReplicaURLs := c.StringSlice("database-replica-urls")
+	clusterNodeID := c.String("cluster-node-id")
+	clusterListen := c.String("cluster-listen")
+	clusterAdvertiseURL := c.String("cluster-advertise-url")
+	clusterSecret := c.String("cluster-secret")
+	clusterBatchLingerStr := c.String("cluster-batch-linger")
 	webPushPrivateKey := c.String("web-push-private-key")
 	webPushPublicKey := c.String("web-push-public-key")
 	webPushFile := c.String("web-push-file")
@@ -215,6 +232,10 @@ func execServe(c *cli.Context) error {
 	visitorTopicCreationLimitReplenishStr := c.String("visitor-topic-creation-limit-replenish")
 	visitorPrefixBitsIPv4 := c.Int("visitor-prefix-bits-ipv4")
 	visitorPrefixBitsIPv6 := c.Int("visitor-prefix-bits-ipv6")
+	banFile := c.String("ban-file")
+	banWindowStr := c.String("ban-window")
+	banThreshold := c.Int("ban-threshold")
+	banWeightsRaw := c.StringSlice("ban-weights")
 	behindProxy := c.Bool("behind-proxy")
 	proxyForwardedHeader := c.String("proxy-forwarded-header")
 	proxyTrustedHosts := util.SplitNoEmpty(c.String("proxy-trusted-hosts"), ",")
@@ -242,6 +263,10 @@ func execServe(c *cli.Context) error {
 	if err != nil {
 		return fmt.Errorf("invalid keepalive interval: %s", keepaliveIntervalStr)
 	}
+	clusterBatchLinger, err := util.ParseDuration(clusterBatchLingerStr)
+	if err != nil || clusterBatchLinger < 0 {
+		return fmt.Errorf("invalid cluster batch linger: %s", clusterBatchLingerStr)
+	}
 	managerInterval, err := util.ParseDuration(managerIntervalStr)
 	if err != nil {
 		return fmt.Errorf("invalid manager interval: %s", managerIntervalStr)
@@ -270,6 +295,16 @@ func execServe(c *cli.Context) error {
 	if err != nil {
 		return fmt.Errorf("invalid web push expiry warning duration: %s", webPushExpiryWarningDurationStr)
 	}
+	banWindow, err := util.ParseDuration(banWindowStr)
+	if err != nil {
+		return fmt.Errorf("invalid ban window: %s", banWindowStr)
+	}
+
+	// Parse abuse ban-feed weights ("KEY:WEIGHT" list, "*" fallback)
+	banWeights, err := ban.ParseWeights(banWeightsRaw)
+	if err != nil {
+		return err
+	}
 
 	// Convert sizes to bytes
 	messageSizeLimit, err := util.ParseSize(messageSizeLimitStr)
@@ -302,6 +337,16 @@ func execServe(c *cli.Context) error {
 		return errors.New("if database-url is set, auth-file, cache-file, and web-push-file must not be set")
 	} else if len(databaseReplicaURLs) > 0 && databaseURL == "" {
 		return errors.New("database-replica-urls can only be used if database-url is also set")
+	} else if clusterListen != "" && databaseURL == "" {
+		return errors.New("cluster-listen requires database-url to be set")
+	} else if clusterListen != "" && clusterSecret == "" {
+		return errors.New("cluster-listen requires cluster-secret to be set")
+	} else if clusterListen != "" && clusterNodeID == "" {
+		return errors.New("cluster-listen requires cluster-node-id to be set")
+	} else if clusterListen == "" && clusterSecret != "" {
+		return errors.New("cluster-secret can only be used if cluster-listen is set")
+	} else if clusterListen != "" && clusterAdvertiseURL == "" && wildcardAddr(clusterListen) {
+		return errors.New("cluster-advertise-url must be set if cluster-listen binds a wildcard address")
 	} else if firebaseKeyFile != "" && !util.FileExists(firebaseKeyFile) {
 		return errors.New("if set, FCM key file must exist")
 	} else if firebaseKeyFile != "" && !server.FirebaseAvailable {
@@ -372,6 +417,14 @@ func execServe(c *cli.Context) error {
 		return errors.New("visitor-prefix-bits-ipv4 must be between 1 and 32")
 	} else if visitorPrefixBitsIPv6 < 1 || visitorPrefixBitsIPv6 > 128 {
 		return errors.New("visitor-prefix-bits-ipv6 must be between 1 and 128")
+	} else if banFile != "" && banWindow <= 0 {
+		return errors.New("if ban-file is set, ban-window must be greater than zero")
+	} else if banFile != "" && banThreshold <= 0 {
+		return errors.New("if ban-file is set, ban-threshold must be greater than zero")
+	} else if banFile != "" && len(banWeights) == 0 {
+		return errors.New("if ban-file is set, ban-weights must not be empty")
+	} else if banFile != "" && !util.FileExists(filepath.Dir(banFile)) {
+		return fmt.Errorf("if ban-file is set, its directory (%s) must exist", filepath.Dir(banFile))
 	} else if runtime.GOOS == "windows" && listenUnix != "" {
 		return errors.New("listen-unix is not supported on Windows")
 	}
@@ -512,6 +565,10 @@ func execServe(c *cli.Context) error {
 	conf.VisitorTopicCreationLimitReplenish = visitorTopicCreationLimitReplenish
 	conf.VisitorPrefixBitsIPv4 = visitorPrefixBitsIPv4
 	conf.VisitorPrefixBitsIPv6 = visitorPrefixBitsIPv6
+	conf.BanFile = banFile
+	conf.BanWindow = banWindow
+	conf.BanThreshold = banThreshold
+	conf.BanWeights = banWeights
 	conf.BehindProxy = behindProxy
 	conf.ProxyForwardedHeader = proxyForwardedHeader
 	conf.ProxyTrustedPrefixes = trustedProxyPrefixes
@@ -527,6 +584,11 @@ func execServe(c *cli.Context) error {
 	conf.ProfileListenHTTP = profileListenHTTP
 	conf.DatabaseURL = databaseURL
 	conf.DatabaseReplicaURLs = databaseReplicaURLs
+	conf.ClusterNodeID = clusterNodeID
+	conf.ClusterListen = clusterListen
+	conf.ClusterAdvertiseURL = clusterAdvertiseURL
+	conf.ClusterSecret = clusterSecret
+	conf.ClusterBatchLinger = clusterBatchLinger
 	conf.WebPushPrivateKey = webPushPrivateKey
 	conf.WebPushPublicKey = webPushPublicKey
 	conf.WebPushFile = webPushFile
@@ -705,3 +767,13 @@ func maybeFromMetadata(m map[string]any, key string) string {
 	}
 	return s
 }
+
+// wildcardAddr reports whether the given listen address binds all interfaces (e.g. ":2587",
+// "0.0.0.0:2587", "[::]:2587"), in which case peers cannot derive a reachable URL from it.
+func wildcardAddr(addr string) bool {
+	host, _, err := net.SplitHostPort(addr)
+	if err != nil {
+		return true // Unparseable -> cannot derive a URL either
+	}
+	return host == "" || host == "0.0.0.0" || host == "::"
+}

cmd/serve_test.go

@@ -536,6 +536,41 @@ func TestIP_Host_Parsing(t *testing.T) {
 	}
 }
 
+func TestCLI_Serve_ClusterValidation(t *testing.T) {
+	configFile := newEmptyFile(t) // Avoid issues with existing server.yml file on system
+	// Setting cluster-listen implicitly enables clustering, which requires database-url; all
+	// validation must fail before any database connection is attempted
+	app, _, _, _ := newTestApp()
+	err := app.Run([]string{"ntfy", "serve", "--config=" + configFile, "--cluster-listen=127.0.0.1:2587"})
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "database-url")
+	// cluster-listen requires cluster-secret
+	app, _, _, _ = newTestApp()
+	err = app.Run([]string{"ntfy", "serve", "--config=" + configFile, "--cluster-listen=127.0.0.1:2587", "--database-url=postgres://user:pass@localhost:1/na"})
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "cluster-secret")
+	// cluster-listen requires an explicit stable node ID
+	app, _, _, _ = newTestApp()
+	err = app.Run([]string{"ntfy", "serve", "--config=" + configFile, "--cluster-listen=127.0.0.1:2587", "--database-url=postgres://user:pass@localhost:1/na", "--cluster-secret=s3cret"})
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "cluster-node-id")
+	// cluster-secret without cluster-listen is a config error (clustering would silently be off)
+	app, _, _, _ = newTestApp()
+	err = app.Run([]string{"ntfy", "serve", "--config=" + configFile, "--cluster-secret=s3cret"})
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "cluster-listen")
+	// A wildcard cluster-listen bind cannot derive an advertise URL
+	app, _, _, _ = newTestApp()
+	err = app.Run([]string{"ntfy", "serve", "--config=" + configFile, "--cluster-listen=:2587", "--database-url=postgres://user:pass@localhost:1/na", "--cluster-secret=s3cret", "--cluster-node-id=node-a"})
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "cluster-advertise-url")
+	// cluster-batch-linger must not be negative
+	app, _, _, _ = newTestApp()
+	err = app.Run([]string{"ntfy", "serve", "--config=" + configFile, "--cluster-batch-linger=-1s"})
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "cluster batch linger")
+}
+
 func newEmptyFile(t *testing.T) string {
 	filename := filepath.Join(t.TempDir(), "empty")
 	require.Nil(t, os.WriteFile(filename, []byte{}, 0600))

db/db.go

@@ -90,6 +90,15 @@ func (d *DB) ReadOnly() *sql.DB {
 	return d.primary.DB
 }
 
+// MarkReplicasHealthyForTest immediately marks all configured replicas as healthy, bypassing the
+// async health-check loop's initial delay. It exists so tests can deterministically route
+// ReadOnly() to a replica without waiting; it is not used in production code.
+func (d *DB) MarkReplicasHealthyForTest() {
+	for _, r := range d.replicas {
+		r.healthy.Store(true)
+	}
+}
+
 // Close closes the primary database and all replicas, and stops the health-check goroutine.
 func (d *DB) Close() error {
 	d.cancel()

db/pg/leader.go

@@ -0,0 +1,163 @@
+package pg
+
+import (
+	"context"
+	"database/sql"
+	"sync"
+	"time"
+
+	"heckel.io/ntfy/v2/log"
+)
+
+const (
+	tagLeader = "leader"
+
+	tryAdvisoryLockQuery = `SELECT pg_try_advisory_lock($1)`
+	advisoryUnlockQuery  = `SELECT pg_advisory_unlock($1)`
+
+	defaultRenewInterval = 5 * time.Second
+	leaderMissedRenewals = 3
+	leaderHoldoffFactor  = 2
+)
+
+// Leader implements singleton-job leader election via a Postgres advisory lock held on a
+// pinned connection. The lock auto-releases when the holding connection dies, so a crashed
+// leader is replaced without manual fencing; distinct keys elect independently. The Leader
+// renews its lease on its own loop; callers only ask IsLeader and eventually Close.
+//
+// Holding the lock is not the same as believing to be the leader: IsLeader also requires a
+// recent renewal (lease duration) and a completed hold-off after winning the lock. The
+// hold-off outlasts the lease duration by construction, so on failover the old belief always
+// expires before the new one begins: a short no-leader gap, never two leaders. Defaults:
+// renew every 5s, lease duration 15s, hold-off 30s -> up to ~35s without a leader.
+type Leader struct {
+	db            *sql.DB
+	key           int64
+	renewInterval time.Duration
+	conn          *sql.Conn          // holds the advisory lock while this process is leader
+	acquiredAt    time.Time          // When the lock was won (this tenure), for the hold-off
+	renewedAt     time.Time          // Last successful renewal, for the lease duration; zero = lock not held
+	cancel        context.CancelFunc // Stops the renew loop and aborts its in-flight query on Close
+	closeOnce     sync.Once
+	wg            sync.WaitGroup
+	mu            sync.Mutex // Protects conn, acquiredAt and renewedAt
+}
+
+// NewLeader creates a Leader competing for the lock identified by key and starts its renew
+// loop. renewInterval is for tests; pass 0 for the default.
+func NewLeader(db *sql.DB, key int64, renewInterval time.Duration) *Leader {
+	if renewInterval <= 0 {
+		renewInterval = defaultRenewInterval
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	l := &Leader{
+		db:            db,
+		key:           key,
+		renewInterval: renewInterval,
+		cancel:        cancel,
+	}
+	l.wg.Add(1)
+	go l.runAcquireOrRenewLoop(ctx)
+	return l
+}
+
+// IsLeader reports whether this process should act as the leader: lock held, lease renewed
+// recently, hold-off elapsed (see the Leader doc comment).
+func (l *Leader) IsLeader() bool {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	leaseDuration := leaderMissedRenewals * l.renewInterval
+	holdoff := leaderHoldoffFactor * leaseDuration
+	return time.Since(l.renewedAt) < leaseDuration && time.Since(l.acquiredAt) >= holdoff
+}
+
+// Close stops competing for leadership and releases the lock. Idempotent.
+func (l *Leader) Close() {
+	l.closeOnce.Do(func() {
+		l.cancel() // Also aborts an in-flight renewal query
+		l.wg.Wait()
+		if l.IsLeader() {
+			log.Tag(tagLeader).Info("Lost leadership: closed (lock key %d)", l.key)
+		}
+		l.release()
+	})
+}
+
+// runAcquireOrRenewLoop acquires or renews the lock every renewInterval until ctx is canceled
+func (l *Leader) runAcquireOrRenewLoop(ctx context.Context) {
+	defer l.wg.Done()
+	ticker := time.NewTicker(l.renewInterval)
+	defer ticker.Stop()
+	wasLeader := false
+	for {
+		attemptCtx, cancel := context.WithTimeout(ctx, l.renewInterval)
+		l.tryAcquireOrRenew(attemptCtx)
+		cancel()
+		if isLeader := l.IsLeader(); isLeader != wasLeader {
+			wasLeader = isLeader
+			if isLeader {
+				log.Tag(tagLeader).Info("Became leader (lock key %d)", l.key)
+			} else {
+				log.Tag(tagLeader).Info("Lost leadership (lock key %d)", l.key)
+			}
+		}
+		select {
+		case <-ticker.C:
+		case <-ctx.Done():
+			return
+		}
+	}
+}
+
+// tryAcquireOrRenew renews the lock on a healthy leader (a cheap ping) or retries acquiring
+// it on a follower, on a pinned connection.
+func (l *Leader) tryAcquireOrRenew(ctx context.Context) {
+	l.mu.Lock()
+	conn := l.conn
+	l.mu.Unlock()
+	if conn != nil {
+		if conn.PingContext(ctx) == nil {
+			// Still holding the lock, connection healthy: renew the lease
+			l.mu.Lock()
+			l.renewedAt = time.Now()
+			l.mu.Unlock()
+			log.Tag(tagLeader).Trace("Renewed leader lease (lock key %d)", l.key)
+			return
+		}
+		log.Tag(tagLeader).Debug("Leader lock connection died, lock lost (lock key %d)", l.key)
+		l.release() // Connection died; the lock is already gone, re-acquire below
+	}
+	newConn, err := l.db.Conn(ctx)
+	if err != nil {
+		log.Tag(tagLeader).Debug("Cannot get connection to compete for leader lock (lock key %d): %s", l.key, err.Error())
+		return
+	}
+	var acquired bool
+	if err := newConn.QueryRowContext(ctx, tryAdvisoryLockQuery, l.key).Scan(&acquired); err != nil || !acquired {
+		newConn.Close()
+		log.Tag(tagLeader).Trace("Leader lock held elsewhere (lock key %d)", l.key)
+		return
+	}
+	log.Tag(tagLeader).Debug("Acquired leader lock (lock key %d); leadership after the hold-off", l.key)
+	l.mu.Lock()
+	l.conn = newConn
+	l.acquiredAt = time.Now()
+	l.renewedAt = l.acquiredAt
+	l.mu.Unlock()
+}
+
+// release unlocks the advisory lock and returns the pinned connection to the pool
+func (l *Leader) release() {
+	l.mu.Lock()
+	conn := l.conn
+	l.conn = nil
+	l.renewedAt = time.Time{} // Zero revokes belief; without it, IsLeader would linger a lease duration
+	l.mu.Unlock()
+	if conn != nil {
+		// Unlock explicitly: sql.Conn.Close() returns the connection to the pool, so the
+		// session-scoped lock would otherwise stay held
+		conn.ExecContext(context.Background(), advisoryUnlockQuery, l.key)
+		conn.Close()
+		log.Tag(tagLeader).Debug("Released leader lock (lock key %d)", l.key)
+	}
+}

db/pg/leader_internal_test.go

@@ -0,0 +1,41 @@
+package pg
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+// The lease logic is pure time arithmetic, so it is unit-tested here without a database; the
+// external leader tests cover the loop end to end.
+
+func TestLeader_Lease_HoldoffMeansNoLeaderRatherThanTwo(t *testing.T) {
+	// Freshly acquired lock: belief must wait out the hold-off
+	l := &Leader{renewInterval: 20 * time.Second} // Lease duration 1m, hold-off 2m
+	l.acquiredAt = time.Now()
+	l.renewedAt = l.acquiredAt
+	require.False(t, l.IsLeader())
+	// Once the hold-off has passed (and verification is fresh), belief begins
+	l.acquiredAt = time.Now().Add(-3 * time.Minute)
+	l.renewedAt = time.Now()
+	require.True(t, l.IsLeader())
+}
+
+func TestLeader_Lease_ExpiredLeaseRevokesLeadership(t *testing.T) {
+	// A leader that cannot renew its lease (wedged process, long GC pause) must stop
+	// believing once the lease expires, even though the lock may still be held
+	l := &Leader{renewInterval: 20 * time.Second} // Lease duration 1m, hold-off 2m
+	l.acquiredAt = time.Now().Add(-time.Hour)
+	l.renewedAt = time.Now().Add(-2 * time.Minute) // Lease expired
+	require.False(t, l.IsLeader())
+	l.renewedAt = time.Now() // Fresh renewal restores belief
+	require.True(t, l.IsLeader())
+}
+
+func TestLeader_Lease_ReleasedIsNeverLeader(t *testing.T) {
+	// release() zeroes renewedAt, which fails the lease check no matter how old the tenure
+	l := &Leader{renewInterval: 20 * time.Second} // Lease duration 1m, hold-off 2m
+	l.acquiredAt = time.Now().Add(-time.Hour)
+	require.False(t, l.IsLeader())
+}

db/pg/leader_test.go

@@ -0,0 +1,90 @@
+package pg_test
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"heckel.io/ntfy/v2/db/pg"
+	dbtest "heckel.io/ntfy/v2/db/test"
+)
+
+const testRenewInterval = 20 * time.Millisecond // Lease duration 60ms, hold-off 120ms
+
+func TestLeader_AcquireAndFailover(t *testing.T) {
+	testDB := dbtest.CreateTestPostgres(t) // skips if NTFY_TEST_DATABASE_URL is unset
+	const key = int64(42)
+	l1 := pg.NewLeader(testDB.Primary(), key, testRenewInterval)
+	defer l1.Close()
+	// Belief follows the hold-off, it is never instant
+	require.False(t, l1.IsLeader())
+	waitForLeader(t, l1)
+	// A competitor never becomes leader while the leader lives
+	l2 := pg.NewLeader(testDB.Primary(), key, testRenewInterval)
+	defer l2.Close()
+	time.Sleep(300 * time.Millisecond) // Several verification rounds
+	require.False(t, l2.IsLeader())
+	require.True(t, l1.IsLeader())
+	// Close -> the follower takes over
+	l1.Close()
+	require.False(t, l1.IsLeader())
+	waitForLeader(t, l2)
+	require.False(t, l1.IsLeader())
+}
+
+func TestLeader_ConnectionLossFailover(t *testing.T) {
+	// A crashed leader must not wedge the cluster: Postgres releases the session-scoped lock
+	// when the pinned connection dies (simulated by terminating the backend), and someone
+	// re-acquires. Either node may win; the invariant is one leader eventually, never two.
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	hostA, err := pg.Open(schemaDSN)
+	require.Nil(t, err)
+	defer hostA.DB.Close()
+	hostB, err := pg.Open(schemaDSN)
+	require.Nil(t, err)
+	defer hostB.DB.Close()
+	const key = int64(43)
+	l1 := pg.NewLeader(hostA.DB, key, testRenewInterval)
+	defer l1.Close()
+	waitForLeader(t, l1)
+	l2 := pg.NewLeader(hostB.DB, key, testRenewInterval)
+	defer l2.Close()
+	// Kill the backend holding the lock (advisory lock keys map to classid/objid)
+	_, err = hostB.DB.Exec(`SELECT pg_terminate_backend(pid) FROM pg_locks WHERE locktype = 'advisory' AND objid = $1 AND granted`, key)
+	require.Nil(t, err)
+	// Eventually exactly one leader again, and never two along the way
+	deadline := time.Now().Add(5 * time.Second)
+	for time.Now().Before(deadline) {
+		leader1, leader2 := l1.IsLeader(), l2.IsLeader()
+		require.False(t, leader1 && leader2, "two leaders at once")
+		if leader1 != leader2 {
+			return
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	t.Fatal("no leader re-emerged after connection loss")
+}
+
+func TestLeader_DistinctKeysAreIndependent(t *testing.T) {
+	testDB := dbtest.CreateTestPostgres(t)
+	l1 := pg.NewLeader(testDB.Primary(), 1, testRenewInterval)
+	defer l1.Close()
+	l2 := pg.NewLeader(testDB.Primary(), 2, testRenewInterval)
+	defer l2.Close()
+	// Different keys do not compete: both become effective leaders
+	waitForLeader(t, l1)
+	waitForLeader(t, l2)
+}
+
+// waitForLeader waits until the node believes it is the leader, or fails the test
+func waitForLeader(t *testing.T, l *pg.Leader) {
+	t.Helper()
+	deadline := time.Now().Add(5 * time.Second)
+	for time.Now().Before(deadline) {
+		if l.IsLeader() {
+			return
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	t.Fatal("node never became effective leader")
+}

db/pg/pg.go

@@ -13,6 +13,13 @@ import (
 	"heckel.io/ntfy/v2/db"
 )
 
+// Advisory lock keys. PostgreSQL advisory locks share one database-wide key space, so every
+// ntfy key is defined here, following the "ntfy"+2586+letter scheme
+const (
+	SchemaLockKey = int64(0x6e7466792586a) // Schema setup serialization (transaction-scoped, see db/schema)
+	LeaderLockKey = int64(0x6e7466792586b) // Cluster singleton-job leader (session-scoped, held for process lifetime)
+)
+
 // Open opens a PostgreSQL connection pool for a primary database. It pings the database
 // to verify connectivity before returning.
 func Open(dsn string) (*db.Host, error) {

db/schema/schema.go

@@ -0,0 +1,111 @@
+// Package schema tracks and migrates database schemas, and Migrate creates or upgrades a
+// store's schema inside a single transaction. On PostgreSQL, all stores share one database, so
+// versions live in a shared schema_version table keyed by store name. On SQLite, every store is
+// its own database file, so the version lives in the schemaVersion table keyed by id = 1.
+package schema
+
+import (
+	"database/sql"
+	"errors"
+	"fmt"
+
+	"heckel.io/ntfy/v2/db/pg"
+	"heckel.io/ntfy/v2/log"
+)
+
+const (
+	tag = "schema"
+)
+
+const (
+	sqliteCreateVersionTableQuery = `CREATE TABLE IF NOT EXISTS schemaVersion (id INT PRIMARY KEY, version INT NOT NULL)`
+	sqliteSelectVersionQuery      = `SELECT version FROM schemaVersion WHERE id = 1`
+	sqliteUpsertVersionQuery      = `INSERT INTO schemaVersion (id, version) VALUES (1, ?) ON CONFLICT (id) DO UPDATE SET version = excluded.version`
+
+	postgresCreateVersionTableQuery = `CREATE TABLE IF NOT EXISTS schema_version (store TEXT PRIMARY KEY, version INT NOT NULL)`
+	postgresSelectVersionQuery      = `SELECT version FROM schema_version WHERE store = $1`
+	postgresUpsertVersionQuery      = `INSERT INTO schema_version (store, version) VALUES ($1, $2) ON CONFLICT (store) DO UPDATE SET version = EXCLUDED.version`
+	postgresAdvisoryLockQuery       = `SELECT pg_advisory_xact_lock($1)` // Transaction-scoped lock to avoid migration races
+)
+
+// Migrate creates or upgrades the named store's schema to targetVersion in one transaction, or
+// creates a new database using the "create" function.
+func Migrate(db *sql.DB, dialect Dialect, store string, targetVersion int, create MigrateFunc, migrations map[int]MigrateFunc) error {
+	if dialect != Postgres && dialect != SQLite {
+		return fmt.Errorf("unsupported schema dialect %d", dialect)
+	}
+	tx, err := db.Begin()
+	if err != nil {
+		return fmt.Errorf("cannot begin %s schema transaction: %w", store, err)
+	}
+	defer tx.Rollback()
+	if dialect == Postgres {
+		// Serialize setup across nodes: CREATE TABLE IF NOT EXISTS is not atomic, and
+		// concurrently cold-booting nodes would otherwise race on DDL and crash
+		if _, err := tx.Exec(postgresAdvisoryLockQuery, pg.SchemaLockKey); err != nil {
+			return fmt.Errorf("cannot acquire %s schema advisory lock: %w", store, err)
+		}
+	}
+	if _, err := tx.Exec(createVersionTableQuery(dialect)); err != nil {
+		return fmt.Errorf("cannot create schema version table: %w", err)
+	}
+	version, err := readVersion(tx, dialect, store)
+	if errors.Is(err, sql.ErrNoRows) {
+		// Fresh database: create the store's tables at the target version
+		if err := create(tx); err != nil {
+			return fmt.Errorf("cannot create %s schema: %w", store, err)
+		}
+		if err := writeVersion(tx, dialect, store, targetVersion); err != nil {
+			return fmt.Errorf("cannot write %s schema version: %w", store, err)
+		}
+		return tx.Commit()
+	} else if err != nil {
+		return fmt.Errorf("cannot read %s schema version: %w", store, err)
+	}
+	if version == targetVersion {
+		return tx.Commit()
+	}
+	if version > targetVersion {
+		return fmt.Errorf("unexpected %s schema version %d, this version of ntfy supports up to %d", store, version, targetVersion)
+	}
+	for v := version; v < targetVersion; v++ {
+		migrate, ok := migrations[v]
+		if !ok {
+			return fmt.Errorf("cannot find %s migration step from version %d to %d", store, v, v+1)
+		}
+		log.Tag(tag).Info("Migrating %s database schema: from %d to %d", store, v, v+1)
+		if err := migrate(tx); err != nil {
+			return fmt.Errorf("%s migration step from version %d to %d failed: %w", store, v, v+1, err)
+		}
+	}
+	if err := writeVersion(tx, dialect, store, targetVersion); err != nil {
+		return fmt.Errorf("cannot write %s schema version: %w", store, err)
+	}
+	return tx.Commit()
+}
+
+func createVersionTableQuery(dialect Dialect) string {
+	if dialect == Postgres {
+		return postgresCreateVersionTableQuery
+	}
+	return sqliteCreateVersionTableQuery
+}
+
+func readVersion(tx *sql.Tx, dialect Dialect, store string) (version int, err error) {
+	if dialect == Postgres {
+		err = tx.QueryRow(postgresSelectVersionQuery, store).Scan(&version)
+	} else {
+		err = tx.QueryRow(sqliteSelectVersionQuery).Scan(&version)
+	}
+	return
+}
+
+func writeVersion(tx *sql.Tx, dialect Dialect, store string, version int) error {
+	var err error
+	if dialect == Postgres {
+		_, err = tx.Exec(postgresUpsertVersionQuery, store, version)
+	} else {
+		_, err = tx.Exec(sqliteUpsertVersionQuery, version)
+	}
+	return err
+}

db/schema/schema_test.go

@@ -0,0 +1,192 @@
+package schema_test
+
+import (
+	"database/sql"
+	"fmt"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"heckel.io/ntfy/v2/db/pg"
+	"heckel.io/ntfy/v2/db/schema"
+	dbtest "heckel.io/ntfy/v2/db/test"
+
+	_ "github.com/mattn/go-sqlite3"
+)
+
+const (
+	testCreateQuery = `CREATE TABLE IF NOT EXISTS things (id TEXT PRIMARY KEY, name TEXT NOT NULL)`
+)
+
+func testCreate(tx *sql.Tx) error {
+	_, err := tx.Exec(testCreateQuery)
+	return err
+}
+
+func openTestPostgres(t *testing.T) *sql.DB {
+	t.Helper()
+	host, err := pg.Open(dbtest.CreateTestPostgresSchema(t))
+	require.Nil(t, err)
+	t.Cleanup(func() { host.DB.Close() })
+	return host.DB
+}
+
+func openTestSQLite(t *testing.T) *sql.DB {
+	t.Helper()
+	d, err := sql.Open("sqlite3", filepath.Join(t.TempDir(), "test.db"))
+	require.Nil(t, err)
+	t.Cleanup(func() { d.Close() })
+	return d
+}
+
+func forEachDialect(t *testing.T, f func(t *testing.T, d *sql.DB, dialect schema.Dialect)) {
+	t.Run("postgres", func(t *testing.T) {
+		f(t, openTestPostgres(t), schema.Postgres)
+	})
+	t.Run("sqlite", func(t *testing.T) {
+		f(t, openTestSQLite(t), schema.SQLite)
+	})
+}
+
+func TestMigrate_FreshCreate(t *testing.T) {
+	forEachDialect(t, func(t *testing.T, d *sql.DB, dialect schema.Dialect) {
+		// A fresh database jumps straight to the target version; migration steps are not consulted
+		require.Nil(t, schema.Migrate(d, dialect, "things", 3, testCreate, nil))
+		_, err := d.Exec(`INSERT INTO things (id, name) VALUES ('a', 'thing a')`)
+		require.Nil(t, err)
+		require.Equal(t, 3, storeVersion(t, d, dialect, "things"))
+		// Idempotent: a second node boots against the migrated schema
+		require.Nil(t, schema.Migrate(d, dialect, "things", 3, testCreate, nil))
+	})
+}
+
+func TestMigrate_AppliesMigrationSteps(t *testing.T) {
+	forEachDialect(t, func(t *testing.T, d *sql.DB, dialect schema.Dialect) {
+		require.Nil(t, schema.Migrate(d, dialect, "things", 1, testCreate, nil))
+		// A newer version of the code migrates 1 -> 3 step by step, in order
+		migrations := map[int]schema.MigrateFunc{
+			1: func(tx *sql.Tx) error {
+				_, err := tx.Exec(`ALTER TABLE things ADD COLUMN color TEXT NOT NULL DEFAULT ''`)
+				return err
+			},
+			2: func(tx *sql.Tx) error {
+				_, err := tx.Exec(`ALTER TABLE things ADD COLUMN size INT NOT NULL DEFAULT 0`)
+				return err
+			},
+		}
+		require.Nil(t, schema.Migrate(d, dialect, "things", 3, testCreate, migrations))
+		_, err := d.Exec(`INSERT INTO things (id, name, color, size) VALUES ('b', 'thing b', 'red', 2)`)
+		require.Nil(t, err)
+		require.Equal(t, 3, storeVersion(t, d, dialect, "things"))
+	})
+}
+
+func TestMigrate_ClosureCarriesConfig(t *testing.T) {
+	// Migrations needing config take it via closure at map-construction time; there is no
+	// params plumbing in the framework itself
+	migrationsFor := func(defaultName string) map[int]schema.MigrateFunc {
+		return map[int]schema.MigrateFunc{
+			1: schema.AsMigrateFunc(fmt.Sprintf(`ALTER TABLE things ADD COLUMN nick TEXT NOT NULL DEFAULT '%s'`, defaultName)),
+		}
+	}
+	forEachDialect(t, func(t *testing.T, d *sql.DB, dialect schema.Dialect) {
+		require.Nil(t, schema.Migrate(d, dialect, "things", 1, testCreate, nil))
+		_, err := d.Exec(`INSERT INTO things (id, name) VALUES ('a', 'thing a')`)
+		require.Nil(t, err)
+		require.Nil(t, schema.Migrate(d, dialect, "things", 2, testCreate, migrationsFor("configured-default")))
+		var nick string
+		require.Nil(t, d.QueryRow(`SELECT nick FROM things WHERE id = 'a'`).Scan(&nick))
+		require.Equal(t, "configured-default", nick)
+	})
+}
+
+func TestMigrate_InvalidDialect(t *testing.T) {
+	d := openTestSQLite(t)
+	err := schema.Migrate(d, schema.Dialect(99), "things", 1, testCreate, nil)
+	require.Error(t, err)
+}
+
+func TestMigrate_RefusesFutureVersion(t *testing.T) {
+	forEachDialect(t, func(t *testing.T, d *sql.DB, dialect schema.Dialect) {
+		require.Nil(t, schema.Migrate(d, dialect, "things", 2, testCreate, map[int]schema.MigrateFunc{}))
+		err := schema.Migrate(d, dialect, "things", 1, testCreate, nil)
+		require.Error(t, err)
+	})
+}
+
+func TestMigrate_MissingStepFails(t *testing.T) {
+	forEachDialect(t, func(t *testing.T, d *sql.DB, dialect schema.Dialect) {
+		require.Nil(t, schema.Migrate(d, dialect, "things", 1, testCreate, nil))
+		err := schema.Migrate(d, dialect, "things", 3, testCreate, nil) // No step 1 -> 2 registered
+		require.Error(t, err)
+	})
+}
+
+func TestMigrate_StoresAreIndependent(t *testing.T) {
+	// Postgres only: stores share one database, tracked as rows in schema_version. On SQLite
+	// every store has its own database file, so independence is by file.
+	d := openTestPostgres(t)
+	require.Nil(t, schema.Migrate(d, schema.Postgres, "things", 1, testCreate, nil))
+	require.Nil(t, schema.Migrate(d, schema.Postgres, "gadgets", 4, func(tx *sql.Tx) error {
+		_, err := tx.Exec(`CREATE TABLE IF NOT EXISTS gadgets (id TEXT PRIMARY KEY)`)
+		return err
+	}, nil))
+	require.Equal(t, 1, storeVersion(t, d, schema.Postgres, "things"))
+	require.Equal(t, 4, storeVersion(t, d, schema.Postgres, "gadgets"))
+}
+
+func TestMigrate_SQLiteReadsExistingSchemaVersionTable(t *testing.T) {
+	// Existing ntfy SQLite databases (message, user, webpush) track their version in a
+	// schemaVersion (id, version) table keyed by id = 1; the framework uses that table as-is
+	// on SQLite, so existing databases migrate without any adoption step
+	d := openTestSQLite(t)
+	_, err := d.Exec(testCreateQuery)
+	require.Nil(t, err)
+	_, err = d.Exec(`CREATE TABLE schemaVersion (id INT PRIMARY KEY, version INT NOT NULL)`)
+	require.Nil(t, err)
+	_, err = d.Exec(`INSERT INTO schemaVersion VALUES (1, 1)`)
+	require.Nil(t, err)
+	migrations := map[int]schema.MigrateFunc{
+		1: func(tx *sql.Tx) error {
+			_, err := tx.Exec(`ALTER TABLE things ADD COLUMN color TEXT NOT NULL DEFAULT ''`)
+			return err
+		},
+	}
+	require.Nil(t, schema.Migrate(d, schema.SQLite, "things", 2, testCreate, migrations))
+	_, err = d.Exec(`INSERT INTO things (id, name, color) VALUES ('a', 'thing a', 'red')`)
+	require.Nil(t, err)
+	require.Equal(t, 2, storeVersion(t, d, schema.SQLite, "things"))
+}
+
+func TestMigrate_ConcurrentFreshCreate(t *testing.T) {
+	// Postgres only: concurrent cold-boots must not race on DDL (CREATE TABLE IF NOT EXISTS is
+	// not atomic); Migrate serializes via an advisory lock. SQLite has a single writer.
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	const n = 8
+	errs := make(chan error, n)
+	for i := 0; i < n; i++ {
+		go func() {
+			host, err := pg.Open(schemaDSN)
+			if err != nil {
+				errs <- err
+				return
+			}
+			defer host.DB.Close()
+			errs <- schema.Migrate(host.DB, schema.Postgres, "things", 1, testCreate, nil)
+		}()
+	}
+	for i := 0; i < n; i++ {
+		require.Nil(t, <-errs)
+	}
+}
+
+func storeVersion(t *testing.T, d *sql.DB, dialect schema.Dialect, store string) int {
+	t.Helper()
+	var version int
+	if dialect == schema.Postgres {
+		require.Nil(t, d.QueryRow(`SELECT version FROM schema_version WHERE store = $1`, store).Scan(&version), fmt.Sprintf("store %s", store))
+	} else {
+		require.Nil(t, d.QueryRow(`SELECT version FROM schemaVersion WHERE id = 1`).Scan(&version), fmt.Sprintf("store %s", store))
+	}
+	return version
+}

db/schema/types.go

@@ -0,0 +1,31 @@
+package schema
+
+import "database/sql"
+
+// Dialect selects the SQL flavor Migrate speaks to the version table.
+type Dialect int
+
+// Supported dialects; SQLite is the zero value
+const (
+	SQLite Dialect = iota
+	Postgres
+)
+
+// MigrateFunc applies one schema change inside the setup transaction: the initial creation of
+// a store's tables, or one step upgrading a store from version N to N+1. Migrations needing
+// config capture it via closure, e.g. func migrations(cacheDuration time.Duration) map[int]MigrateFunc.
+type MigrateFunc func(tx *sql.Tx) error
+
+// AsMigrateFunc converts a simple query to a migration function
+func AsMigrateFunc(query string) MigrateFunc {
+	return func(tx *sql.Tx) error {
+		_, err := tx.Exec(query)
+		return err
+	}
+}
+
+// NopMigrateFunc is a migration step that does nothing, for versions where a dialect has no
+// work to do (e.g. when only the other dialect's schema changed).
+func NopMigrateFunc(_ *sql.Tx) error {
+	return nil
+}

db/test/schema.go

@@ -0,0 +1,185 @@
+package dbtest
+
+import (
+	"database/sql"
+	"fmt"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// Querier is the subset of *sql.DB / *db.DB needed to introspect a schema.
+type Querier interface {
+	Query(query string, args ...any) (*sql.Rows, error)
+}
+
+// SQLiteSchema returns a normalized, comparable description of the database schema: tables
+// with their columns, named indexes, and foreign keys. Column order, declared type spelling
+// (INT vs INTEGER) and default values are not part of the description, so the schema produced
+// by a migration chain can be compared to a freshly created one.
+func SQLiteSchema(t testing.TB, d Querier) string {
+	t.Helper()
+	lines := make([]string, 0)
+	for _, table := range sqliteTables(t, d) {
+		lines = append(lines, "table "+table)
+		lines = append(lines, sqliteColumns(t, d, table)...)
+		lines = append(lines, sqliteForeignKeys(t, d, table)...)
+		lines = append(lines, sqliteIndexes(t, d, table)...)
+	}
+	return strings.Join(lines, "\n")
+}
+
+// PostgresSchema is SQLiteSchema's PostgreSQL counterpart, describing the current schema's
+// tables, columns, constraints and indexes in a normalized, comparable way.
+func PostgresSchema(t testing.TB, d Querier) string {
+	t.Helper()
+	lines := make([]string, 0)
+	for _, table := range postgresTables(t, d) {
+		lines = append(lines, "table "+table)
+		lines = append(lines, postgresColumns(t, d, table)...)
+	}
+	lines = append(lines, postgresConstraints(t, d)...)
+	lines = append(lines, postgresIndexes(t, d)...)
+	return strings.Join(lines, "\n")
+}
+
+func sqliteTables(t testing.TB, d Querier) []string {
+	t.Helper()
+	return queryStrings(t, d, `SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name`)
+}
+
+func sqliteColumns(t testing.TB, d Querier, table string) []string {
+	t.Helper()
+	rows, err := d.Query(fmt.Sprintf(`PRAGMA table_info(%q)`, table))
+	require.Nil(t, err)
+	defer rows.Close()
+	lines := make([]string, 0)
+	for rows.Next() {
+		var cid, notNull, pk int
+		var name, typ string
+		var dflt sql.NullString
+		require.Nil(t, rows.Scan(&cid, &name, &typ, &notNull, &dflt, &pk))
+		typ = strings.ToUpper(typ)
+		if typ == "INT" { // INT and INTEGER are the same affinity; migrations spell them inconsistently
+			typ = "INTEGER"
+		}
+		lines = append(lines, fmt.Sprintf("  col %s %s notnull=%d pk=%d", name, typ, notNull, pk))
+	}
+	require.Nil(t, rows.Err())
+	sort.Strings(lines)
+	return lines
+}
+
+func sqliteForeignKeys(t testing.TB, d Querier, table string) []string {
+	t.Helper()
+	rows, err := d.Query(fmt.Sprintf(`PRAGMA foreign_key_list(%q)`, table))
+	require.Nil(t, err)
+	defer rows.Close()
+	lines := make([]string, 0)
+	for rows.Next() {
+		var id, seq int
+		var refTable, from, onUpdate, onDelete, match string
+		var to sql.NullString // NULL when referencing the parent's primary key implicitly
+		require.Nil(t, rows.Scan(&id, &seq, &refTable, &from, &to, &onUpdate, &onDelete, &match))
+		lines = append(lines, fmt.Sprintf("  fk %s -> %s(%s) on_delete=%s", from, refTable, to.String, onDelete))
+	}
+	require.Nil(t, rows.Err())
+	sort.Strings(lines)
+	return lines
+}
+
+func sqliteIndexes(t testing.TB, d Querier, table string) []string {
+	t.Helper()
+	rows, err := d.Query(fmt.Sprintf(`PRAGMA index_list(%q)`, table))
+	require.Nil(t, err)
+	type index struct {
+		name            string
+		unique, partial int
+	}
+	indexes := make([]index, 0)
+	for rows.Next() {
+		var seq, unique, partial int
+		var name, origin string
+		require.Nil(t, rows.Scan(&seq, &name, &unique, &origin, &partial))
+		// Skip auto-indexes backing PRIMARY KEY/UNIQUE table constraints; those are described
+		// by the column and constraint listings already
+		if strings.HasPrefix(name, "sqlite_autoindex_") {
+			continue
+		}
+		indexes = append(indexes, index{name, unique, partial})
+	}
+	require.Nil(t, rows.Err())
+	require.Nil(t, rows.Close())
+	lines := make([]string, 0, len(indexes))
+	for _, idx := range indexes {
+		cols := queryStrings(t, d, fmt.Sprintf(`SELECT name FROM pragma_index_info(%q) ORDER BY seqno`, idx.name))
+		lines = append(lines, fmt.Sprintf("  index %s unique=%d partial=%d cols=(%s)", idx.name, idx.unique, idx.partial, strings.Join(cols, ",")))
+	}
+	sort.Strings(lines)
+	return lines
+}
+
+func postgresTables(t testing.TB, d Querier) []string {
+	t.Helper()
+	return queryStrings(t, d, `SELECT table_name FROM information_schema.tables WHERE table_schema = current_schema() AND table_type = 'BASE TABLE' ORDER BY table_name`)
+}
+
+func postgresColumns(t testing.TB, d Querier, table string) []string {
+	t.Helper()
+	rows, err := d.Query(`SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_schema = current_schema() AND table_name = $1 ORDER BY column_name`, table)
+	require.Nil(t, err)
+	defer rows.Close()
+	lines := make([]string, 0)
+	for rows.Next() {
+		var name, typ, nullable string
+		require.Nil(t, rows.Scan(&name, &typ, &nullable))
+		lines = append(lines, fmt.Sprintf("  col %s %s nullable=%s", name, typ, nullable))
+	}
+	require.Nil(t, rows.Err())
+	return lines
+}
+
+func postgresConstraints(t testing.TB, d Querier) []string {
+	t.Helper()
+	return queryStrings(t, d, `
+		SELECT 'constraint ' || conrelid::regclass::text || ': ' || pg_get_constraintdef(oid)
+		FROM pg_constraint
+		WHERE connamespace = current_schema()::regnamespace
+		ORDER BY 1
+	`)
+}
+
+func postgresIndexes(t testing.TB, d Querier) []string {
+	t.Helper()
+	rows, err := d.Query(`SELECT indexname, indexdef, schemaname FROM pg_indexes WHERE schemaname = current_schema() ORDER BY indexname`)
+	require.Nil(t, err)
+	defer rows.Close()
+	lines := make([]string, 0)
+	for rows.Next() {
+		var name, def, schema string
+		require.Nil(t, rows.Scan(&name, &def, &schema))
+		// The index definition qualifies the table with the (test-specific) schema name; strip
+		// it so snapshots from different test schemas compare equal
+		def = strings.ReplaceAll(def, schema+".", "")
+		lines = append(lines, "index "+def)
+	}
+	require.Nil(t, rows.Err())
+	return lines
+}
+
+func queryStrings(t testing.TB, d Querier, query string) []string {
+	t.Helper()
+	rows, err := d.Query(query)
+	require.Nil(t, err)
+	defer rows.Close()
+	values := make([]string, 0)
+	for rows.Next() {
+		var value string
+		require.Nil(t, rows.Scan(&value))
+		values = append(values, value)
+	}
+	require.Nil(t, rows.Err())
+	return values
+}

db/test/test.go

@@ -17,7 +17,7 @@ const testPoolMaxConns = "2"
 // CreateTestPostgresSchema creates a temporary PostgreSQL schema and returns the DSN pointing to it.
 // It registers a cleanup function to drop the schema when the test finishes.
 // If NTFY_TEST_DATABASE_URL is not set, the test is skipped.
-func CreateTestPostgresSchema(t *testing.T) string {
+func CreateTestPostgresSchema(t testing.TB) string {
 	t.Helper()
 	dsn := os.Getenv("NTFY_TEST_DATABASE_URL")
 	if dsn == "" {
@@ -51,7 +51,7 @@ func CreateTestPostgresSchema(t *testing.T) string {
 // CreateTestPostgres creates a temporary PostgreSQL schema and returns an open *db.DB connection to it.
 // It registers cleanup functions to close the DB and drop the schema when the test finishes.
 // If NTFY_TEST_DATABASE_URL is not set, the test is skipped.
-func CreateTestPostgres(t *testing.T) *db.DB {
+func CreateTestPostgres(t testing.TB) *db.DB {
 	t.Helper()
 	schemaDSN := CreateTestPostgresSchema(t)
 	testHost, err := pg.Open(schemaDSN)

docs/config.md

@@ -379,7 +379,7 @@ This generator helps you configure your self-hosted ntfy instance. It's not full
 </div>
 </div>
 <div class="cg-panel" id="cg-panel-database">
-<div class="cg-panel-desc">Configure the PostgreSQL connection. See <a href="/config/#postgresql-experimental" target="_blank">PostgreSQL</a> for details.</div>
+<div class="cg-panel-desc">Configure the PostgreSQL connection. See <a href="/config/#postgresql" target="_blank">PostgreSQL</a> for details.</div>
 <div class="cg-field">
 <label>Database URL</label>
 <input type="text" data-key="database-url" placeholder="postgres://user:pass@host:5432/ntfy">
@@ -417,7 +417,7 @@ no external dependencies:
 * `auth-file`: Database file for authentication and [access control](#access-control). If set, enables auth.
 * `web-push-file`: Database file for [web push](#web-push) subscriptions.
 
-### PostgreSQL (EXPERIMENTAL)
+### PostgreSQL
 As an alternative, you can configure ntfy to use PostgreSQL for **all** database-backed stores by setting the
 `database-url` option to a PostgreSQL connection string.
 
@@ -1656,7 +1656,7 @@ a database to keep track of the browser's subscriptions, and an admin email addr
 - `web-push-expiry-duration` defines the duration after which unused subscriptions will expire (default is `60d`)
 
 Alternatively, you can use PostgreSQL instead of SQLite by setting `database-url`
-(see [PostgreSQL database](#postgresql-experimental)).
+(see [PostgreSQL database](#postgresql)).
 
 Limitations:
 
@@ -2129,6 +2129,72 @@ chain.
 The official ntfy.sh server uses fail2ban to ban IPs. Check out ntfy.sh's [Ansible fail2ban role](https://github.com/binwiederhier/ntfy-ansible/tree/main/roles/fail2ban) for details. Ban actors are banned for 1 hour initially, and up to
 4 hours at a time for repeated offenses. IPv4 addresses are banned individually, while IPv6 addresses are banned by their `/56` prefix.
 
+### Ban-feed
+In addition to the fail2ban setup above, ntfy can detect abusive visitors itself and write their IP
+addresses to a file for fail2ban to ban from. ntfy keeps a per-prefix weighted "strike" budget, and
+each rejected request costs strikes based on its response code -- the ntfy error code, or its HTTP
+status (see `ban-weights`) -- so different kinds of rejection can be weighted differently or exempted
+entirely. When a prefix exceeds the budget, ntfy appends the offending IP address to `ban-file`. Since
+every line is already a confirmed offender, the fail2ban jail can ban on first sight (`maxretry = 1`).
+
+- `ban-file` is the file offenders are appended to. If it is not set, the ban-feed is disabled. Its
+  parent directory must exist and be writable by ntfy. Be sure to rotate it (e.g. with logrotate and
+  `copytruncate`) so it does not grow unbounded.
+- `ban-window` is the rolling window over which weighted strikes are counted, per IP prefix.
+- `ban-threshold` is the number of weighted strikes per `ban-window` before a prefix is written to
+  `ban-file`. Each prefix has one shared budget, so it cannot be gamed by mixing error codes.
+- `ban-weights` assigns a strike weight per matcher key, formatted as `KEY:WEIGHT`. A key is an exact
+  ntfy error code (`42909`), a code family (`429*`, `403*`, `4*`), a bare HTTP status (`403`, short for
+  `403*`), or `*`. The longest matching key wins. A weight of `0` exempts a code entirely (it never
+  counts toward a ban), useful to spare a specific code from a `*` catch-all. Heavier weights ban faster. If you do not
+  include a `*` rule, any code that matches nothing defaults to weight `1` (i.e. it can be banned);
+  set `*:0` to exempt everything that is not explicitly weighted.
+
+Only rejections (4xx/5xx) count towards a ban; successful requests never do. Because the budget
+refills over `ban-window`, the trigger is a sustained rate: a prefix is only written out once it
+exceeds `ban-threshold / ban-window` rejections per second (with the defaults, `100 / 10m` = ~0.17/s).
+
+Each line in `ban-file` has the format `<RFC3339-timestamp> <ip> <prefix> <http-code> <ntfy-code>`, for example:
+
+```
+2026-01-15T20:56:32Z 1.2.3.4 1.2.3.4/32 429 42901
+2026-01-15T20:56:32Z 2001:db8::abcd 2001:db8::/64 429 42909
+```
+
+`<prefix>` is `<ip>` masked to the rate-limiting prefix (`visitor-prefix-bits-ipv4`/`-ipv6`) -- the
+same unit ntfy rate-limits by. Have the fail2ban filter capture the bare `<ip>` (the action then
+applies the prefix):
+
+=== "server.yml"
+    ```yaml
+    ban-file: "/var/log/ntfy/ban.log"
+    ban-window: "10m"
+    ban-threshold: 100
+    ban-weights:
+      - "42909:10"   # too many auth failures -> brute force, ban fast
+      # everything else 4xx/5xx defaults to weight 1
+    ```
+
+=== "/etc/fail2ban/filter.d/ntfy-ban.conf"
+    ```
+    [Definition]
+    failregex = ^\S+ <HOST> \S+ \d+ \d+$
+    datepattern = ^%%Y-%%m-%%dT%%H:%%M:%%S
+    ignoreregex =
+    ```
+
+=== "/etc/fail2ban/jail.d/ntfy-ban.local"
+    ```
+    [ntfy-ban]
+    enabled = true
+    filter = ntfy-ban
+    action = iptables-multiport[name=ntfy-ban, port="http,https", protocol=tcp]
+    logpath = /var/log/ntfy/ban.log
+    maxretry = 1
+    findtime = 1m
+    bantime = 1h
+    ```
+
 ## IPv6 support
 ntfy fully supports IPv6, though there are a few things to keep in mind.
 
@@ -2159,13 +2225,14 @@ See [Installation for Docker](install.md#docker) for an example of how this coul
 If configured, ntfy can expose a `/metrics` endpoint for [Prometheus](https://prometheus.io/), which can then be used to
 create dashboards and alerts (e.g. via [Grafana](https://grafana.com/)).
 
-To configure the metrics endpoint, either set `enable-metrics` and/or set the `metrics-listen-http` option to a dedicated
+To configure the metrics endpoint, either set `enable-metrics`, or set the `metrics-listen-http` option to a dedicated
 listen address. Metrics may be considered sensitive information, so before you enable them, be sure you know what you are
 doing, and/or secure access to the endpoint in your reverse proxy.
 
 - `enable-metrics` enables the /metrics endpoint for the default ntfy server (i.e. HTTP, HTTPS and/or Unix socket)
-- `metrics-listen-http` exposes the metrics endpoint via a dedicated `[IP]:port`. If set, this option implicitly
-  enables metrics as well, e.g. "10.0.1.1:9090" or ":9090"
+- `metrics-listen-http` moves the metrics endpoint to a dedicated `[IP]:port`, e.g. "10.0.1.1:9090" or ":9090". It
+  implicitly enables metrics. If set, the metrics are served only on that dedicated port, and the default ntfy server
+  does not serve /metrics, even if `enable-metrics` is also set.
 
 === "server.yml (Using default port)"
     ```yaml
@@ -2328,6 +2395,10 @@ variable before running the `ntfy` command (e.g. `export NTFY_LISTEN_HTTP=:80`).
 | `visitor-topic-creation-limit-replenish`   | `NTFY_VISITOR_TOPIC_CREATION_LIMIT_REPLENISH`   | *duration*                                          | 1m                | Rate limiting: Rate at which the per-visitor topic-creation bucket is refilled (one new topic per x).                                                                                                                                   |
 | `visitor-prefix-bits-ipv4`                 | `NTFY_VISITOR_PREFIX_BITS_IPV4`                 | *number*                                            | 32                | Rate limiting: Number of bits to use for IPv4 visitor prefix, e.g. 24 for /24                                                                                                                                                           |
 | `visitor-prefix-bits-ipv6`                 | `NTFY_VISITOR_PREFIX_BITS_IPV6`                 | *number*                                            | 64                | Rate limiting: Number of bits to use for IPv6 visitor prefix, e.g. 48 for /48                                                                                                                                                           |
+| `ban-file`                                 | `NTFY_BAN_FILE`                                 | *filename*                                          | -                 | Abuse ban-feed: file confirmed abusive visitor IPs are appended to, for fail2ban to tail. Empty disables the feature. See [Banning bad actors](#banning-bad-actors-fail2ban)                                                             |
+| `ban-window`                               | `NTFY_BAN_WINDOW`                               | *duration*                                          | 10m               | Abuse ban-feed: rolling window over which weighted strikes are counted, per IP prefix                                                                                                                                                     |
+| `ban-threshold`                            | `NTFY_BAN_THRESHOLD`                            | *number*                                            | 100               | Abuse ban-feed: weighted strikes per `ban-window` before a prefix is written to `ban-file`                                                                                                                                             |
+| `ban-weights`                              | `NTFY_BAN_WEIGHTS`                              | *list of KEY:WEIGHT*                                | `42909:10`| Abuse ban-feed: per-code strike weights (exact code, family `429*`, or `*`; longest match wins; `0` exempts). See [Banning bad actors](#banning-bad-actors-fail2ban)                                                                     |
 | `web-root`                                 | `NTFY_WEB_ROOT`                                 | *path*, e.g. `/` or `/app`, or `disable`            | `/`               | Sets root of the web app (e.g. /, or /app), or disables it entirely (disable)                                                                                                                                                           |
 | `enable-signup`                            | `NTFY_ENABLE_SIGNUP`                            | *boolean* (`true` or `false`)                       | `false`           | Allows users to sign up via the web app, or API                                                                                                                                                                                         |
 | `enable-login`                             | `NTFY_ENABLE_LOGIN`                             | *boolean* (`true` or `false`)                       | `false`           | Allows users to log in via the web app, or API                                                                                                                                                                                          |

docs/contact.md

@@ -28,7 +28,7 @@ via the following channels:
 | Channel               | Contact                                             | Description                              |
 |-----------------------|-----------------------------------------------------|------------------------------------------|
 | **General Support**   | [support@mail.ntfy.sh](mailto:support@mail.ntfy.sh) | Direct email support for Pro subscribers |
-| **Billing Inquiries** | [billing@mail.ntfy.sh](mailto:support@mail.ntfy.sh) | Inquire about billing issues             |
+| **Billing Inquiries** | [billing@mail.ntfy.sh](mailto:billing@mail.ntfy.sh) | Inquire about billing issues             |
 | **Discord/Matrix**    | Mention your Pro status                             | Priority responses in community channels |
 
 Please include your ntfy.sh username when contacting support so we can verify your subscription status.
@@ -37,6 +37,11 @@ Please include your ntfy.sh username when contacting support so we can verify yo
 
 If you discover a security vulnerability, please report it responsibly via [security@mail.ntfy.sh](mailto:security@mail.ntfy.sh). See also: [SECURITY.md](https://github.com/binwiederhier/ntfy/blob/main/SECURITY.md).
 
+## Abuse reports
+
+To report spam, phishing, or other abuse of ntfy.sh, please email [abuse@mail.ntfy.sh](mailto:abuse@mail.ntfy.sh).
+Please include the topic name and any relevant message details so we can investigate.
+
 ## Other inquiries
 
 For questions about our [privacy policy](privacy.md), data handling, or to exercise your data rights 

docs/develop.md

@@ -65,8 +65,8 @@ These steps **assume Ubuntu**. Steps may vary on different Linux distributions.
 
 First, install [Go](https://go.dev/) (see [official instructions](https://go.dev/doc/install)):
 ``` shell
-wget https://go.dev/dl/go1.19.1.linux-amd64.tar.gz
-sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.19.1.linux-amd64.tar.gz
+wget https://go.dev/dl/go1.25.8.linux-amd64.tar.gz
+sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.25.8.linux-amd64.tar.gz
 export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin
 go version   # verifies that it worked
 ```
@@ -77,9 +77,11 @@ go install github.com/goreleaser/goreleaser@latest
 goreleaser -v   # verifies that it worked
 ```
 
-Install [nodejs](https://nodejs.org/en/) (see [official instructions](https://nodejs.org/en/download/package-manager/)):
+Install [nodejs](https://nodejs.org/en/) (see [official instructions](https://nodejs.org/en/download/package-manager/)).
+Use a current LTS release (Node 24 is what CI builds with; anything older than Node 20 will not work
+with the current Vite-based web build):
 ``` shell
-curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
 sudo apt-get install -y nodejs
 npm -v   # verifies that it worked
 ```

docs/examples.md

@@ -641,6 +641,32 @@ or by simply providing traccar with a valid username/password combination.
         <entry key='sms.http.password'>mypass</entry>
 ```
 
+## Flowtriq DDoS detection
+[Flowtriq](https://flowtriq.com) is a real-time DDoS detection and mitigation platform. Its Linux agent, ftagent,
+supports webhook alerts that can POST directly to an ntfy topic, so you get push notifications on your phone
+whenever an attack is detected.
+
+Configure the webhook URL in your ftagent configuration to point to your ntfy topic:
+
+```yaml
+# /etc/ftagent/ftagent.yml
+alerts:
+  webhooks:
+    - url: https://ntfy.sh/flowtriq-attacks
+      method: POST
+```
+
+You can also use curl to test the integration manually with a sample attack alert:
+
+```bash
+curl \
+  -H "Title: DDoS Attack Detected" \
+  -H "Priority: urgent" \
+  -H "Tags: rotating_light" \
+  -d "Attack detected on 203.0.113.5: 14.2 Gbps UDP flood from 3,482 sources" \
+  ntfy.sh/flowtriq-attacks
+```
+
 ## Terminal Notifications for Long-Running Commands
 
 This example provides a simple way to send notifications using [ntfy.sh](https://ntfy.sh) when a terminal command completes. It includes success or failure indicators based on the command's exit status.

docs/install.md

@@ -34,37 +34,37 @@ as a service starting at boot time.
 
 === "x86_64/amd64"
     ```bash
-    wget https://github.com/binwiederhier/ntfy/releases/download/v2.24.0/ntfy_2.24.0_linux_amd64.tar.gz
-    tar zxvf ntfy_2.24.0_linux_amd64.tar.gz
-    sudo cp -a ntfy_2.24.0_linux_amd64/ntfy /usr/local/bin/ntfy
-    sudo mkdir /etc/ntfy && sudo cp ntfy_2.24.0_linux_amd64/{client,server}/*.yml /etc/ntfy
+    wget https://github.com/binwiederhier/ntfy/releases/download/v2.27.0/ntfy_2.27.0_linux_amd64.tar.gz
+    tar zxvf ntfy_2.27.0_linux_amd64.tar.gz
+    sudo cp -a ntfy_2.27.0_linux_amd64/ntfy /usr/local/bin/ntfy
+    sudo mkdir /etc/ntfy && sudo cp ntfy_2.27.0_linux_amd64/{client,server}/*.yml /etc/ntfy
     sudo ntfy serve
     ```
 
 === "armv6"
     ```bash
-    wget https://github.com/binwiederhier/ntfy/releases/download/v2.24.0/ntfy_2.24.0_linux_armv6.tar.gz
-    tar zxvf ntfy_2.24.0_linux_armv6.tar.gz
-    sudo cp -a ntfy_2.24.0_linux_armv6/ntfy /usr/bin/ntfy
-    sudo mkdir /etc/ntfy && sudo cp ntfy_2.24.0_linux_armv6/{client,server}/*.yml /etc/ntfy
+    wget https://github.com/binwiederhier/ntfy/releases/download/v2.27.0/ntfy_2.27.0_linux_armv6.tar.gz
+    tar zxvf ntfy_2.27.0_linux_armv6.tar.gz
+    sudo cp -a ntfy_2.27.0_linux_armv6/ntfy /usr/bin/ntfy
+    sudo mkdir /etc/ntfy && sudo cp ntfy_2.27.0_linux_armv6/{client,server}/*.yml /etc/ntfy
     sudo ntfy serve
     ```
 
 === "armv7/armhf"
     ```bash
-    wget https://github.com/binwiederhier/ntfy/releases/download/v2.24.0/ntfy_2.24.0_linux_armv7.tar.gz
-    tar zxvf ntfy_2.24.0_linux_armv7.tar.gz
-    sudo cp -a ntfy_2.24.0_linux_armv7/ntfy /usr/bin/ntfy
-    sudo mkdir /etc/ntfy && sudo cp ntfy_2.24.0_linux_armv7/{client,server}/*.yml /etc/ntfy
+    wget https://github.com/binwiederhier/ntfy/releases/download/v2.27.0/ntfy_2.27.0_linux_armv7.tar.gz
+    tar zxvf ntfy_2.27.0_linux_armv7.tar.gz
+    sudo cp -a ntfy_2.27.0_linux_armv7/ntfy /usr/bin/ntfy
+    sudo mkdir /etc/ntfy && sudo cp ntfy_2.27.0_linux_armv7/{client,server}/*.yml /etc/ntfy
     sudo ntfy serve
     ```
 
 === "arm64"
     ```bash
-    wget https://github.com/binwiederhier/ntfy/releases/download/v2.24.0/ntfy_2.24.0_linux_arm64.tar.gz
-    tar zxvf ntfy_2.24.0_linux_arm64.tar.gz
-    sudo cp -a ntfy_2.24.0_linux_arm64/ntfy /usr/bin/ntfy
-    sudo mkdir /etc/ntfy && sudo cp ntfy_2.24.0_linux_arm64/{client,server}/*.yml /etc/ntfy
+    wget https://github.com/binwiederhier/ntfy/releases/download/v2.27.0/ntfy_2.27.0_linux_arm64.tar.gz
+    tar zxvf ntfy_2.27.0_linux_arm64.tar.gz
+    sudo cp -a ntfy_2.27.0_linux_arm64/ntfy /usr/bin/ntfy
+    sudo mkdir /etc/ntfy && sudo cp ntfy_2.27.0_linux_arm64/{client,server}/*.yml /etc/ntfy
     sudo ntfy serve
     ```
 
@@ -84,25 +84,25 @@ Install the ntfy server unit file (which contains parameters to start the servic
 
 === "x86_64/amd64"
     ```bash
-    sudo mv ntfy_2.24.0_linux_amd64/server/ntfy.service /etc/systemd/system/
+    sudo mv ntfy_2.27.0_linux_amd64/server/ntfy.service /etc/systemd/system/
     sudo chmod 644 /etc/systemd/system/ntfy.service
     ```
 
 === "armv6"
     ```bash
-    sudo mv ntfy_2.24.0_linux_armv6/server/ntfy.service /etc/systemd/system/
+    sudo mv ntfy_2.27.0_linux_armv6/server/ntfy.service /etc/systemd/system/
     sudo chmod 644 /etc/systemd/system/ntfy.service
     ```
 
 === "armv7/armhf"
     ```bash
-    sudo mv ntfy_2.24.0_linux_armv7/server/ntfy.service /etc/systemd/system/
+    sudo mv ntfy_2.27.0_linux_armv7/server/ntfy.service /etc/systemd/system/
     sudo chmod 644 /etc/systemd/system/ntfy.service
     ```
 
 === "arm64"
     ```bash
-    sudo mv ntfy_2.24.0_linux_arm64/server/ntfy.service /etc/systemd/system/
+    sudo mv ntfy_2.27.0_linux_arm64/server/ntfy.service /etc/systemd/system/
     sudo chmod 644 /etc/systemd/system/ntfy.service
     ```
 
@@ -118,25 +118,25 @@ Install the ntfy server service script:
 
 === "x86_64/amd64"
     ```bash
-    sudo mv ntfy_2.24.0_linux_amd64/server/ntfy.openrc /etc/init.d/ntfy
+    sudo mv ntfy_2.27.0_linux_amd64/server/ntfy.openrc /etc/init.d/ntfy
     sudo chmod 755 /etc/init.d/ntfy
     ```
 
 === "armv6"
     ```bash
-    sudo mv ntfy_2.24.0_linux_armv6/server/ntfy.openrc /etc/init.d/ntfy
+    sudo mv ntfy_2.27.0_linux_armv6/server/ntfy.openrc /etc/init.d/ntfy
     sudo chmod 755 /etc/init.d/ntfy
     ```
 
 === "armv7/armhf"
     ```bash
-    sudo mv ntfy_2.24.0_linux_armv7/server/ntfy.openrc /etc/init.d/ntfy
+    sudo mv ntfy_2.27.0_linux_armv7/server/ntfy.openrc /etc/init.d/ntfy
     sudo chmod 755 /etc/init.d/ntfy
     ```
 
 === "arm64"
     ```bash
-    sudo mv ntfy_2.24.0_linux_arm64/server/ntfy.openrc /etc/init.d/ntfy
+    sudo mv ntfy_2.27.0_linux_arm64/server/ntfy.openrc /etc/init.d/ntfy
     sudo chmod 755 /etc/init.d/ntfy
     ```
 
@@ -204,7 +204,7 @@ Manually installing the .deb file:
 
 === "x86_64/amd64"
     ```bash
-    wget https://github.com/binwiederhier/ntfy/releases/download/v2.24.0/ntfy_2.24.0_linux_amd64.deb
+    wget https://github.com/binwiederhier/ntfy/releases/download/v2.27.0/ntfy_2.27.0_linux_amd64.deb
     sudo dpkg -i ntfy_*.deb
     sudo systemctl enable ntfy
     sudo systemctl start ntfy
@@ -212,7 +212,7 @@ Manually installing the .deb file:
 
 === "armv6"
     ```bash
-    wget https://github.com/binwiederhier/ntfy/releases/download/v2.24.0/ntfy_2.24.0_linux_armv6.deb
+    wget https://github.com/binwiederhier/ntfy/releases/download/v2.27.0/ntfy_2.27.0_linux_armv6.deb
     sudo dpkg -i ntfy_*.deb
     sudo systemctl enable ntfy
     sudo systemctl start ntfy
@@ -220,7 +220,7 @@ Manually installing the .deb file:
 
 === "armv7/armhf"
     ```bash
-    wget https://github.com/binwiederhier/ntfy/releases/download/v2.24.0/ntfy_2.24.0_linux_armv7.deb
+    wget https://github.com/binwiederhier/ntfy/releases/download/v2.27.0/ntfy_2.27.0_linux_armv7.deb
     sudo dpkg -i ntfy_*.deb
     sudo systemctl enable ntfy
     sudo systemctl start ntfy
@@ -228,7 +228,7 @@ Manually installing the .deb file:
 
 === "arm64"
     ```bash
-    wget https://github.com/binwiederhier/ntfy/releases/download/v2.24.0/ntfy_2.24.0_linux_arm64.deb
+    wget https://github.com/binwiederhier/ntfy/releases/download/v2.27.0/ntfy_2.27.0_linux_arm64.deb
     sudo dpkg -i ntfy_*.deb
     sudo systemctl enable ntfy
     sudo systemctl start ntfy
@@ -238,28 +238,28 @@ Manually installing the .deb file:
 
 === "x86_64/amd64"
     ```bash
-    sudo rpm -ivh https://github.com/binwiederhier/ntfy/releases/download/v2.24.0/ntfy_2.24.0_linux_amd64.rpm
+    sudo rpm -ivh https://github.com/binwiederhier/ntfy/releases/download/v2.27.0/ntfy_2.27.0_linux_amd64.rpm
     sudo systemctl enable ntfy 
     sudo systemctl start ntfy
     ```
 
 === "armv6"
     ```bash
-    sudo rpm -ivh https://github.com/binwiederhier/ntfy/releases/download/v2.24.0/ntfy_2.24.0_linux_armv6.rpm
+    sudo rpm -ivh https://github.com/binwiederhier/ntfy/releases/download/v2.27.0/ntfy_2.27.0_linux_armv6.rpm
     sudo systemctl enable ntfy
     sudo systemctl start ntfy
     ```
 
 === "armv7/armhf"
     ```bash
-    sudo rpm -ivh https://github.com/binwiederhier/ntfy/releases/download/v2.24.0/ntfy_2.24.0_linux_armv7.rpm
+    sudo rpm -ivh https://github.com/binwiederhier/ntfy/releases/download/v2.27.0/ntfy_2.27.0_linux_armv7.rpm
     sudo systemctl enable ntfy 
     sudo systemctl start ntfy
     ```
 
 === "arm64"
     ```bash
-    sudo rpm -ivh https://github.com/binwiederhier/ntfy/releases/download/v2.24.0/ntfy_2.24.0_linux_arm64.rpm
+    sudo rpm -ivh https://github.com/binwiederhier/ntfy/releases/download/v2.27.0/ntfy_2.27.0_linux_arm64.rpm
     sudo systemctl enable ntfy 
     sudo systemctl start ntfy
     ```
@@ -301,18 +301,18 @@ pkg install go-ntfy
 
 ## macOS
 The [ntfy CLI](subscribe/cli.md) (`ntfy publish` and `ntfy subscribe` only) is supported on macOS as well. 
-To install, please [download the tarball](https://github.com/binwiederhier/ntfy/releases/download/v2.24.0/ntfy_2.24.0_darwin_all.tar.gz), 
+To install, please [download the tarball](https://github.com/binwiederhier/ntfy/releases/download/v2.27.0/ntfy_2.27.0_darwin_all.tar.gz), 
 extract it and place it somewhere in your `PATH` (e.g. `/usr/local/bin/ntfy`). 
 
 If run as `root`, ntfy will look for its config at `/etc/ntfy/client.yml`. For all other users, it'll look for it at 
 `~/Library/Application Support/ntfy/client.yml` (sample included in the tarball).
 
 ```bash
-curl -L https://github.com/binwiederhier/ntfy/releases/download/v2.24.0/ntfy_2.24.0_darwin_all.tar.gz > ntfy_2.24.0_darwin_all.tar.gz
-tar zxvf ntfy_2.24.0_darwin_all.tar.gz
-sudo cp -a ntfy_2.24.0_darwin_all/ntfy /usr/local/bin/ntfy
+curl -L https://github.com/binwiederhier/ntfy/releases/download/v2.27.0/ntfy_2.27.0_darwin_all.tar.gz > ntfy_2.27.0_darwin_all.tar.gz
+tar zxvf ntfy_2.27.0_darwin_all.tar.gz
+sudo cp -a ntfy_2.27.0_darwin_all/ntfy /usr/local/bin/ntfy
 mkdir ~/Library/Application\ Support/ntfy 
-cp ntfy_2.24.0_darwin_all/client/client.yml ~/Library/Application\ Support/ntfy/client.yml
+cp ntfy_2.27.0_darwin_all/client/client.yml ~/Library/Application\ Support/ntfy/client.yml
 ntfy --help
 ```
 
@@ -333,7 +333,7 @@ brew install ntfy
 The ntfy server and CLI are fully supported on Windows. You can run the ntfy server directly or as a Windows service.
 To install, you can either
 
-* [Download the latest ZIP](https://github.com/binwiederhier/ntfy/releases/download/v2.24.0/ntfy_2.24.0_windows_amd64.zip),
+* [Download the latest ZIP](https://github.com/binwiederhier/ntfy/releases/download/v2.27.0/ntfy_2.27.0_windows_amd64.zip),
 extract it and place the `ntfy.exe` binary somewhere in your `%Path%`. 
 * Or install ntfy from the [Scoop](https://scoop.sh) main repository via `scoop install ntfy`
 
@@ -726,3 +726,31 @@ kubectl apply -k /ntfy
     cache-file: "/var/cache/ntfy/cache.db"
     attachment-cache-dir: "/var/cache/ntfy/attachments"
     ```
+
+## Helm
+<span class="community-badge" title="This package is maintained by the community, not the ntfy developers"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M11 7h2v2h-2zm0 4h2v6h-2zm1-9C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8z"/></svg> Community maintained</span>
+
+If you prefer [Helm](https://helm.sh/), ntfy can be deployed using the third-party
+[HelmForge chart](https://helmforge.dev/docs/charts/ntfy), which packages the official
+`binwiederhier/ntfy` image with persistent storage, Service, Ingress, optional Prometheus metrics, and more.
+This chart is **not** maintained by the ntfy developers.
+
+!!! warning
+    The HelmForge project is young and maintained by a small community. Review the chart before deploying it,
+    and use it at your own risk.
+
+```bash
+helm repo add helmforge https://repo.helmforge.dev
+helm repo update
+helm install ntfy helmforge/ntfy
+```
+
+Alternatively, install it directly from the OCI registry:
+
+```bash
+helm install ntfy oci://ghcr.io/helmforgedev/helm/ntfy
+```
+
+Because ntfy's default SQLite storage is single-writer, run the chart as a single instance rather than
+treating it as a horizontally scalable deployment. See the [chart documentation](https://helmforge.dev/docs/charts/ntfy)
+for the full list of configurable values.

docs/integrations.md

@@ -43,6 +43,7 @@ I've added a ⭐ to projects or posts that have a significant following, or had
 - [Miniflux](https://miniflux.app/docs/ntfy.html) - Minimalist and opinionated feed reader
 - [Beszel](https://beszel.dev/guide/notifications/ntfy) - Server monitoring platform
 - [Simple Observability](https://simpleobservability.com/docs/alerts/ntfy) - Server monitoring and observability platform
+- [Sifio](https://sifio.net) - Aggregate updates from RSS, social media, and other sources, then deliver them to ntfy, Slack, Notion and more
 
 ## Integration via HTTP/SMTP/etc.
 
@@ -54,6 +55,7 @@ I've added a ⭐ to projects or posts that have a significant following, or had
 - [Proxmox-Ntfy](https://github.com/qtsone/proxmox-ntfy) - Python script that monitors Proxmox tasks and sends notifications using the Ntfy service.
 - [Scrutiny](https://github.com/AnalogJ/scrutiny) - WebUI for smartd S.M.A.R.T monitoring. Scrutiny includes shoutrrr/ntfy integration ([see integration README](https://github.com/AnalogJ/scrutiny?tab=readme-ov-file#notifications))
 - [UptimeObserver](https://uptimeobserver.com) - Uptime Monitoring tool for Websites, APIs, SSL Certificates, DNS, Domain Names and Ports. [Integration Guide](https://support.uptimeobserver.com/integrations/ntfy/)
+- [Flowtriq](https://flowtriq.com) - Real-time DDoS detection and mitigation platform (integration via [webhook alerts](https://flowtriq.com))
 
 ## [UnifiedPush](https://unifiedpush.org/users/apps/) integrations
 
@@ -82,13 +84,13 @@ I've added a ⭐ to projects or posts that have a significant following, or had
 - [symfony/ntfy-notifier](https://symfony.com/components/NtfyNotifier) ⭐ - Symfony Notifier integration for ntfy (PHP)
 - [ntfy-java](https://github.com/MaheshBabu11/ntfy-java/) - A Java package to interact with a ntfy server (Java)
 - [aiontfy](https://github.com/tr4nt0r/aiontfy) - Asynchronous client library for publishing and subscribing to ntfy (Python)
+- [ex_ntfy](https://github.com/houllette/ex_ntfy) - Elixir SDK covering publishing, polling, and streaming subscriptions for ntfy servers (Elixir)
 
 ## CLIs + GUIs
 
 - [ntfy.sh.sh](https://github.com/mininmobile/ntfy.sh.sh) - Run scripts on ntfy.sh events
 - [ntfy-desktop](https://codeberg.org/zvava/ntfy-desktop) - Cross-platform desktop application for ntfy
 - [ntfy-desktop](https://github.com/Aetherinox/ntfy-desktop) - Desktop client for Windows, Linux, and MacOS with push notifications
-- [ntfy svelte front-end](https://github.com/novatorem/Ntfy) - Front-end built with svelte
 - [ntfy Desktop (Windows)](https://github.com/simoneferrari/ntfy-desktop) - Native Windows desktop client with multi-server support, toast notifications and message history, built with WPF and .NET (C#)
 - [wio-ntfy-ticker](https://github.com/nachotp/wio-ntfy-ticker) - Ticker display for a ntfy.sh topic
 - [ntfysh-windows](https://github.com/mshafer1/ntfysh-windows) - A ntfy client for Windows Desktop
@@ -189,6 +191,7 @@ I've added a ⭐ to projects or posts that have a significant following, or had
 - [send_to_ntfy_extension](https://github.com/TheDuffman85/send_to_ntfy_extension/) ⭐ - A browser extension to send the notifications to ntfy (JS)
 - [SIA-Server](https://github.com/ZebMcKayhan/SIA-Server) - A light weight, self-hosted notification Server for Honywell Galaxy Flex alarm systems (Python)
 - [zabbix-ntfy](https://github.com/torgrimt/zabbix-ntfy) - Zabbix server Mediatype to add support for ntfy.sh services
+- [Rubix Notify](https://wordpress.org/plugins/rubix-notify) - WordPress Integration with ntfy (PHP + React).
 
 ## Blog + forum posts
 

docs/publish.md

@@ -2815,16 +2815,20 @@ Here's an example of a dead man's switch that sends an alert if the script stops
 ### Canceling scheduled notifications
 
 You can cancel a scheduled message before it is delivered by sending a DELETE request to the 
-`/<topic>/<sequence_id>` endpoint, just like [deleting notifications](#deleting-notifications). This will remove the 
-scheduled message from the server so it will never be delivered, and emit a `message_delete` event to any subscribers.
+`/<topic>/<sequence_id>` endpoint, just like [deleting notifications](#deleting-notifications). Alternatively, you can send a `GET`
+request to `/<topic>/<sequence_id>/delete`. This will remove the scheduled message from the server so it will never be delivered,
+and emit a `message_delete` event to any subscribers.
 
 === "Command line (curl)"
     ```bash
     # Schedule a reminder for 2 hours from now
     curl -H "In: 2h" -d "Take a break!" ntfy.sh/mytopic/break-reminder
 
-    # Changed your mind? Cancel the scheduled message
+    # Changed your mind? Cancel the scheduled message via DELETE
     curl -X DELETE ntfy.sh/mytopic/break-reminder
+
+    # Or cancel it via GET
+    curl ntfy.sh/mytopic/break-reminder/delete
     ```
 
 === "ntfy CLI"
@@ -3220,6 +3224,14 @@ You can use the following features in your templates:
 A good way to experiment with Go templates is the **[Go Template Playground](https://repeatit.io)**. It is _highly recommended_ to test
 your templates there first ([example for Grafana alert](https://repeatit.io/#/share/eyJ0ZW1wbGF0ZSI6InRpdGxlPUdyYWZhbmErYWxlcnQ6K3t7LnRpdGxlfX0mbWVzc2FnZT17ey5tZXNzYWdlfX0iLCJpbnB1dCI6IntcbiAgXCJyZWNlaXZlclwiOiBcIm50ZnlcXFxcLmV4YW1wbGVcXFxcLmNvbS9hbGVydHNcIixcbiAgXCJzdGF0dXNcIjogXCJyZXNvbHZlZFwiLFxuICBcImFsZXJ0c1wiOiBbXG4gICAge1xuICAgICAgXCJzdGF0dXNcIjogXCJyZXNvbHZlZFwiLFxuICAgICAgXCJsYWJlbHNcIjoge1xuICAgICAgICBcImFsZXJ0bmFtZVwiOiBcIkxvYWQgYXZnIDE1bSB0b28gaGlnaFwiLFxuICAgICAgICBcImdyYWZhbmFfZm9sZGVyXCI6IFwiTm9kZSBhbGVydHNcIixcbiAgICAgICAgXCJpbnN0YW5jZVwiOiBcIjEwLjEwOC4wLjI6OTEwMFwiLFxuICAgICAgICBcImpvYlwiOiBcIm5vZGUtZXhwb3J0ZXJcIlxuICAgICAgfSxcbiAgICAgIFwiYW5ub3RhdGlvbnNcIjoge1xuICAgICAgICBcInN1bW1hcnlcIjogXCIxNW0gbG9hZCBhdmVyYWdlIHRvbyBoaWdoXCJcbiAgICAgIH0sXG4gICAgICBcInN0YXJ0c0F0XCI6IFwiMjAyNC0wMy0xNVQwMjoyODowMFpcIixcbiAgICAgIFwiZW5kc0F0XCI6IFwiMjAyNC0wMy0xNVQwMjo0MjowMFpcIixcbiAgICAgIFwiZ2VuZXJhdG9yVVJMXCI6IFwibG9jYWxob3N0OjMwMDAvYWxlcnRpbmcvZ3JhZmFuYS9OVzlvRHctNHovdmlld1wiLFxuICAgICAgXCJmaW5nZXJwcmludFwiOiBcImJlY2JmYjk0YmQ4MWVmNDhcIixcbiAgICAgIFwic2lsZW5jZVVSTFwiOiBcImxvY2FsaG9zdDozMDAwL2FsZXJ0aW5nL3NpbGVuY2UvbmV3P2FsZXJ0bWFuYWdlcj1ncmFmYW5hJm1hdGNoZXI9YWxlcnRuYW1lJTNETG9hZCthdmcrMTVtK3RvbytoaWdoJm1hdGNoZXI9Z3JhZmFuYV9mb2xkZXIlM0ROb2RlK2FsZXJ0cyZtYXRjaGVyPWluc3RhbmNlJTNEMTAuMTA4LjAuMiUzQTkxMDAmbWF0Y2hlcj1qb2IlM0Rub2RlLWV4cG9ydGVyXCIsXG4gICAgICBcImRhc2hib2FyZFVSTFwiOiBcIlwiLFxuICAgICAgXCJwYW5lbFVSTFwiOiBcIlwiLFxuICAgICAgXCJ2YWx1ZXNcIjoge1xuICAgICAgICBcIkJcIjogMTguOTgyMTEzMTQ0NzU4NzYsXG4gICAgICAgIFwiQ1wiOiAwXG4gICAgICB9LFxuICAgICAgXCJ2YWx1ZVN0cmluZ1wiOiBcIlsgdmFyPSdCJyBsYWJlbHM9e19fbmFtZV9fPW5vZGVfbG9hZDE1LCBpbnN0YW5jZT0xMC4xMDguMC4yOjkxMDAsIGpvYj1ub2RlLWV4cG9ydGVyfSB2YWx1ZT0xOC45ODIxMTMxNDQ3NTg3NiBdLCBbIHZhcj0nQycgbGFiZWxzPXtfX25hbWVfXz1ub2RlX2xvYWQxNSwgaW5zdGFuY2U9MTAuMTA4LjAuMjo5MTAwLCBqb2I9bm9kZS1leHBvcnRlcn0gdmFsdWU9MCBdXCJcbiAgICB9XG4gIF0sXG4gIFwiZ3JvdXBMYWJlbHNcIjoge1xuICAgIFwiYWxlcnRuYW1lXCI6IFwiTG9hZCBhdmcgMTVtIHRvbyBoaWdoXCIsXG4gICAgXCJncmFmYW5hX2ZvbGRlclwiOiBcIk5vZGUgYWxlcnRzXCJcbiAgfSxcbiAgXCJjb21tb25MYWJlbHNcIjoge1xuICAgIFwiYWxlcnRuYW1lXCI6IFwiTG9hZCBhdmcgMTVtIHRvbyBoaWdoXCIsXG4gICAgXCJncmFmYW5hX2ZvbGRlclwiOiBcIk5vZGUgYWxlcnRzXCIsXG4gICAgXCJpbnN0YW5jZVwiOiBcIjEwLjEwOC4wLjI6OTEwMFwiLFxuICAgIFwiam9iXCI6IFwibm9kZS1leHBvcnRlclwiXG4gIH0sXG4gIFwiY29tbW9uQW5ub3RhdGlvbnNcIjoge1xuICAgIFwic3VtbWFyeVwiOiBcIjE1bSBsb2FkIGF2ZXJhZ2UgdG9vIGhpZ2hcIlxuICB9LFxuICBcImV4dGVybmFsVVJMXCI6IFwibG9jYWxob3N0OjMwMDAvXCIsXG4gIFwidmVyc2lvblwiOiBcIjFcIixcbiAgXCJncm91cEtleVwiOiBcInt9OnthbGVydG5hbWU9XFxcIkxvYWQgYXZnIDE1bSB0b28gaGlnaFxcXCIsIGdyYWZhbmFfZm9sZGVyPVxcXCJOb2RlIGFsZXJ0c1xcXCJ9XCIsXG4gIFwidHJ1bmNhdGVkQWxlcnRzXCI6IDAsXG4gIFwib3JnSWRcIjogMSxcbiAgXCJ0aXRsZVwiOiBcIltSRVNPTFZFRF0gTG9hZCBhdmcgMTVtIHRvbyBoaWdoIE5vZGUgYWxlcnRzICgxMC4xMDguMC4yOjkxMDAgbm9kZS1leHBvcnRlcilcIixcbiAgXCJzdGF0ZVwiOiBcIm9rXCIsXG4gIFwibWVzc2FnZVwiOiBcIioqUmVzb2x2ZWQqKlxcblxcblZhbHVlOiBCPTE4Ljk4MjExMzE0NDc1ODc2LCBDPTBcXG5MYWJlbHM6XFxuIC0gYWxlcnRuYW1lID0gTG9hZCBhdmcgMTVtIHRvbyBoaWdoXFxuIC0gZ3JhZmFuYV9mb2xkZXIgPSBOb2RlIGFsZXJ0c1xcbiAtIGluc3RhbmNlID0gMTAuMTA4LjAuMjo5MTAwXFxuIC0gam9iID0gbm9kZS1leHBvcnRlclxcbkFubm90YXRpb25zOlxcbiAtIHN1bW1hcnkgPSAxNW0gbG9hZCBhdmVyYWdlIHRvbyBoaWdoXFxuU291cmNlOiBsb2NhbGhvc3Q6MzAwMC9hbGVydGluZy9ncmFmYW5hL05XOW9Edy00ei92aWV3XFxuU2lsZW5jZTogbG9jYWxob3N0OjMwMDAvYWxlcnRpbmcvc2lsZW5jZS9uZXc/YWxlcnRtYW5hZ2VyPWdyYWZhbmEmbWF0Y2hlcj1hbGVydG5hbWUlM0RMb2FkK2F2ZysxNW0rdG9vK2hpZ2gmbWF0Y2hlcj1ncmFmYW5hX2ZvbGRlciUzRE5vZGUrYWxlcnRzJm1hdGNoZXI9aW5zdGFuY2UlM0QxMC4xMDguMC4yJTNBOTEwMCZtYXRjaGVyPWpvYiUzRG5vZGUtZXhwb3J0ZXJcXG5cIlxufVxuIiwiY29uZmlnIjp7InRlbXBsYXRlIjoidGV4dCIsImZ1bGxTY3JlZW5IVE1MIjpmYWxzZSwiZnVuY3Rpb25zIjpbInNwcmlnIl0sIm9wdGlvbnMiOlsibGl2ZSJdLCJpbnB1dFR5cGUiOiJ5YW1sIn19)).
 
+!!! info
+    A few Go template features are disabled for user-supplied templates: `{{define}}`, `{{template}}`,
+    `{{block}}`, and `{{call}}` are not allowed. Templates also run with a short execution time limit --
+    a template that loops too long is stopped and rejected with an HTTP 400 error. Templates are
+    limited to 32 KB in size, `printf` widths and precisions must be below 1000 (`%999d` is
+    allowed, `%1000d` is not), including the `%*d` form that takes the width from an argument, and
+    `indent`/`nindent` are limited to 100 spaces.
+
 ### Template functions
 ntfy supports a subset of the **[Sprig template functions](publish/template-functions.md)** (originally copied from [Sprig](https://github.com/Masterminds/sprig),
 thank you to the Sprig developers 🙏). This is useful for advanced message templating and for transforming the data provided through the JSON payload.
@@ -4143,26 +4155,41 @@ field the response. A sequence of updates may look like this (first example from
 ### Clearing notifications
 Clearing a notification means **marking it as read and dismissing it from the notification drawer**. 
 
-To do this, send a PUT request to the `/<topic>/<sequence_id>/clear` endpoint (or `/<topic>/<sequence_id>/read` as an alias). 
+To do this, send a `PUT` request to the `/<topic>/<sequence_id>/clear` endpoint (or `/<topic>/<sequence_id>/read` as an alias).
 This will then emit a `message_clear` event that is used by the clients (web app and Android app) to update the read status
 and dismiss the notification.
 
+Alternatively, if your client has limited HTTP support, you can send a `GET` request to the same endpoints:
+`GET /<topic>/<sequence_id>/clear` or `GET /<topic>/<sequence_id>/read`.
+
 === "Command line (curl)"
     ```bash
+    # Via PUT method
     curl -X PUT ntfy.sh/mytopic/my-download-123/clear
+
+    # Via GET method
+    curl ntfy.sh/mytopic/my-download-123/clear
     ```
 
 === "HTTP"
     ``` http
     PUT /mytopic/my-download-123/clear HTTP/1.1
     Host: ntfy.sh
+
+    # Or using GET
+    GET /mytopic/my-download-123/clear HTTP/1.1
+    Host: ntfy.sh
     ```
 
 === "JavaScript"
     ``` javascript
+    // Via PUT method
     await fetch('https://ntfy.sh/mytopic/my-download-123/clear', {
       method: 'PUT'
     });
+
+    // Via GET method
+    await fetch('https://ntfy.sh/mytopic/my-download-123/clear');
     ```
 
 === "Go"
@@ -4197,25 +4224,40 @@ An example response from the server with the `message_clear` event may look like
 ### Deleting notifications
 Deleting a notification means **removing it from the notification drawer and from the client's database**.
 
-To do this, send a DELETE request to the `/<topic>/<sequence_id>` endpoint. This will emit a `message_delete` event
+To do this, send a `DELETE` request to the `/<topic>/<sequence_id>` endpoint. This will emit a `message_delete` event
 that is used by the clients (web app and Android app) to remove the notification entirely.
 
+Alternatively, if your client has limited HTTP support (e.g. webhooks or IoT devices), you can also delete a message by sending
+a `GET` request to `/<topic>/<sequence_id>/delete`.
+
 === "Command line (curl)"
     ```bash
+    # Via DELETE method
     curl -X DELETE ntfy.sh/mytopic/my-download-123
+
+    # Via GET method
+    curl ntfy.sh/mytopic/my-download-123/delete
     ```
 
 === "HTTP"
     ``` http
     DELETE /mytopic/my-download-123 HTTP/1.1
     Host: ntfy.sh
+
+    # Or using GET
+    GET /mytopic/my-download-123/delete HTTP/1.1
+    Host: ntfy.sh
     ```
 
 === "JavaScript"
     ``` javascript
+    // Via DELETE method
     await fetch('https://ntfy.sh/mytopic/my-download-123', {
       method: 'DELETE'
     });
+
+    // Via GET method
+    await fetch('https://ntfy.sh/mytopic/my-download-123/delete');
     ```
 
 === "Go"

docs/releases.md

@@ -4,15 +4,145 @@ and the [ntfy Android app](https://github.com/binwiederhier/ntfy-android/release
 
 ## Current stable releases
 
-| Component        | Version | Release date |
-|------------------|---------|--------------|
-| ntfy server      | v2.24.0 | June 4, 2026 |
-| ntfy Android app | v1.24.0 | Mar 5, 2026  |
-| ntfy iOS app     | v1.7.0  | May 30, 2026 |
+| Component        | Version | Release date  |
+|------------------|---------|---------------|
+| ntfy server      | v2.27.0 | Aug 4, 2026   |
+| ntfy Android app | v1.25.2 | July 23, 2026 |
+| ntfy iOS app     | v1.7.0  | May 30, 2026  |
 
 Please check out the release notes for [upcoming releases](#not-released-yet) below.
 
-### ntfy server v2.24.0
+### ntfy server v2.27.0
+Released August 4, 2026
+
+This release lets you sign in with your verified email address instead of your username, which should help if you ever
+signed up with an email and then forgot which username you picked. It also hardens the message templating engine against
+a few ways a small template could eat a lot of memory, and it drops the "experimental" label from
+[PostgreSQL support](config.md#postgresql), which has been running ntfy.sh for a while now.
+
+I also did a bunch of refactoring in, mostly in preparation for being able to cluster ntfy nodes and scale the service
+horizontally. It'll be a while until then, ... baby steps.
+
+**Security:**
+
+* Limit message templates (`Template: yes`) to 32 KB, limit `printf` widths and precisions to below 1000, and limit `indent`/`nindent` to 100 spaces, preventing excessive memory use from a single small template
+* Exclude secrets from the config hash served to the web app, preventing a rather theoretical information leak
+
+**Features:**
+
+* Allow logging in with your verified primary email address (in addition to your username), so a password reset no longer leaves you unable to sign in when you only remember the email you signed up with
+
+**Bug fixes + maintenance:**
+
+* Fix Twilio phone calls and phone number verifications failing silently when Twilio rejected the request, and move the Twilio integration into its own `twilio` package
+* Move the Prometheus metrics into a dedicated `metrics` package
+* Message cache databases from ntfy older than v1.10.0 (November 2021) can no longer be migrated; upgrade via an older ntfy version first, or delete the cache database
+* Fix `user_phone` table in the SQLite user database referencing a dropped table after the v2.14 schema migration; repaired automatically by a new migration
+
+## ntfy Android v1.25.2
+Released July 23, 2026
+
+This release makes the "connection lost" alert configurable and turns it off by default. Folks did not like it and many reached out
+or even gave ntfy bad reviews. I heard you! You can re-enable the alert in the advanced settings.
+
+The release also tries to be smarter about not retrying the connection at all if the app is in flight mode, or has no network. If there
+is no network, ntfy now keeps the foreground service alive and shows a "Waiting for network" notification, then resumes automatically
+once connectivity returns.
+
+Another change related to the networking is that we now force-reconnect when the connection is changed, e.g. during transitions
+from Wi-Fi to cellular network, or vice versa. That should allow for faster transitions during hand-overs.
+
+We also increase the client-side WebSocket ping interval from 1 minute to 3 minutes, which should slightly improve battery life,
+especially when paired with increaseing the server-side `keepalive-interval` in your self-hosted server.
+
+**Features:**
+
+* Add configurable "Alert when connection is lost" setting, turned off by default ([#1665](https://github.com/binwiederhier/ntfy/issues/1665), [#1662](https://github.com/binwiederhier/ntfy/issues/1662), [#1652](https://github.com/binwiederhier/ntfy/issues/1652), [#1655](https://github.com/binwiederhier/ntfy/issues/1655), thanks to [@tintamarre](https://github.com/tintamarre), [@sjozs](https://github.com/sjozs), [@TheRealOne78](https://github.com/TheRealOne78), and [@DAE51D](https://github.com/DAE51D) for reporting)
+* Handle "no network" gracefully: when the device is offline or in airplane mode, ntfy now stops retrying, suppresses the connection-lost alert, and keeps the foreground service alive with a "Waiting for network" notification, resuming instant delivery automatically when connectivity returns ([ntfy-android#165](https://github.com/binwiederhier/ntfy-android/pull/165), thanks to [@tintamarre](https://github.com/tintamarre) for the contribution, and [#1709](https://github.com/binwiederhier/ntfy/issues/1709), thanks to [@isaitgirl](https://github.com/isaitgirl) for reporting)
+* Improve battery life by increasing WebSocket client ping interval from 1 min to 3 min, and reconnect instantly on Wi-Fi/cellular/VPN transitions ([ntfy-android#113](https://github.com/binwiederhier/ntfy-android/pull/113), thanks to [@ftilde](https://github.com/ftilde) for the investigation)
+* Disable UnifiedPush components when UnifiedPush is disabled in settings ([ntfy-android#168](https://github.com/binwiederhier/ntfy-android/pull/168), thanks to [@p1gp1g](https://github.com/p1gp1g) for the contribution)
+
+**Bug fixes + maintenance:**
+
+* Fix the "connection lost" alert briefly disappearing and re-firing when roaming between networks (e.g. Wi-Fi to cellular), by no longer cancelling it during the transient no-network gap of a handover
+* Fix the "connection lost" alert repeatedly waking the screen while a server stayed unreachable, by no longer re-posting the alert once it is already showing
+* Fix the "connection lost" alert firing late, erratically, or not at all when a connection kept dropping (e.g. a flaky server) rather than being refused outright, by tracking how long the connection has been down independently of whether the drop warrants a UI error
+* Undo automatic phone number linking for numbers in message body ([ntfy-android#170](https://github.com/binwiederhier/ntfy-android/pull/170), thanks to [@acortelyou](https://github.com/acortelyou) for the contribution)
+* Fix subscription icons disappearing after a few days due to Android clearing cache ([#1322](https://github.com/binwiederhier/ntfy/issues/1322), thanks to [@mcanning](https://github.com/mcanning) for reporting)
+* Fix UnifiedPush `failed_reason` being sent as an enum instead of a string, which caused an exception in receiving apps that read it as a string extra ([ntfy-android#182](https://github.com/binwiederhier/ntfy-android/pull/182), thanks to [@p1gp1g](https://github.com/p1gp1g) for the contribution)
+
+### ntfy server v2.26.3
+Released July 20, 2026
+
+This is a hotfix release, useful pretty much only for ntfy.sh. It was adds the ability to track abusive IPs more
+efficiently, reducing the load on the IP banning services and preventing them from falling behind and leaving abusers
+unbanned for too long. It works by tracking HTTP errors, and writing out a ban file that fail2ban can read and ban
+offenders instantly. See [ban-feed](config.md#ban-feed) for details.
+
+**Features:**
+
+* Add an abuse ban-feed: when enabled via `ban-file`, ntfy tracks a weighted strike budget per visitor and appends abusive IPs to a file that fail2ban can tail and ban on sight (`ban-file`, `ban-window`, `ban-threshold`, `ban-weights`; see [ban-feed docs](config.md#ban-feed))
+
+### ntfy server v2.26.0
+Released July 9, 2026
+
+This release hardens **message templates**, which are now executed with a hard-capped execution timeout. This closes
+a denial-of-service hole.
+
+On the web app side, it adds configurable **date and time formats**, a smoother loading and page-transition experience,
+and a fix that strips unsafe URL protocols from rendered Markdown.
+
+**Security:**
+
+* Prevent a CPU denial of service via message templates (`Template: yes`) ([#1826](https://github.com/binwiederhier/ntfy/pull/1826), thanks to [@alanturing881](https://github.com/alanturing881), [@5ud0er](https://github.com/5ud0er) and [@jvoisin](https://github.com/jvoisin) for reporting)
+
+**Features:**
+
+* Web app: Add "Date format" and "Time format" settings (Settings -> Appearance), with ISO 8601, day/month/year (slash or dot) and month/day/year date options and a 12-/24-hour clock option, and base the default format on your browser/system locale rather than the selected display language. When logged in, both settings sync across devices via your account ([#1647](https://github.com/binwiederhier/ntfy/issues/1647), thanks to [@wsw70](https://github.com/wsw70) for reporting)
+
+**Bug fixes + maintenance:**
+
+* Web app: Smooth transitions and loading animation, remove flickering
+* Web app: `GET /account` now reads from the primary database instead of a read replica, so the account view no longer shows stale data right after a change when replicas lag behind
+* Docs: Document the third-party HelmForge Helm chart as a Kubernetes installation option ([#1727](https://github.com/binwiederhier/ntfy/issues/1727), thanks to [@mberlofa](https://github.com/mberlofa))
+* Web app: Strip unsafe URL protocols (`javascript:`, `data:`, ...) from links and images in Markdown-rendered messages, so they no longer trigger an uncaught "React has blocked a javascript: URL" error (thanks to [@jvoisin](https://github.com/jvoisin) for reporting)
+
+## ntfy server v2.25.0
+Released June 24, 2026
+
+This release adds **password reset** via email, and reworks email verification to use durable,
+link-based magic links (replacing the old in-memory 6-digit codes). Email stays optional at
+signup; a user can reset their password only once they have a verified "primary" (recovery)
+email.
+
+All of this work is probably not useful for self-hosters, but it hopefully will be useful for me,
+since I do have to reset accounts on a regular basis.
+
+**Security issues:**
+
+* Generate access tokens, IDs, and magic-link tokens with a cryptographically secure RNG (`crypto/rand`) instead of a clock-seeded PRNG
+
+**Features:**
+
+* Add password reset via emailed magic link, with a "Forgot password" link on the login page and a `ntfy user reset-pass` CLI command for admins
+* Rework email verification to use durable, single-use, expiring magic links instead of in-memory 6-digit codes, and add a "primary" email (used for account recovery and as the `X-Email: yes` target) with verified/unverified state in the account UI
+* You can now clear/read messages and delete messages with a GET request ([#1771](https://github.com/binwiederhier/ntfy/issues/1771), thanks to [@lemmi](https://github.com/lemmi) for reporting and to [@wunter8](https://github.com/wunter8) for implementing)
+* Add a reload button to the web app's action bar when running as an installed PWA, which clears the service worker caches and hard-refreshes the app ([#1281](https://github.com/binwiederhier/ntfy/issues/1281), thanks to [@leanza](https://github.com/leanza) for reporting)
+* Add a "Back to app" link to the web app's login, signup, and password-reset pages (alongside the existing links), which previously had no way back to the app
+
+**Bug fixes + maintenance:**
+
+* `X-Email: yes` (also `true`/`1`) now sends to your primary verified email regardless of the `smtp-sender-verify` setting (previously it was rejected unless verification was enabled); it requires being logged in with a verified address
+* Grant users full access to their own sync topic (`st_...`) so cross-device subscription sync works under `auth-default-access: deny-all` ([#733](https://github.com/binwiederhier/ntfy/issues/733), [#1795](https://github.com/binwiederhier/ntfy/pull/1795), thanks to [@lmorchard](https://github.com/lmorchard) for the contribution)
+* Support HTTP (non-TLS) S3-compatible endpoints by preserving the endpoint scheme, e.g. for a local MinIO instance ([#1794](https://github.com/binwiederhier/ntfy/pull/1794), [#1734](https://github.com/binwiederhier/ntfy/issues/1734), thanks to [@sskender](https://github.com/sskender) for the contribution, and [@Kernald](https://github.com/Kernald) for reporting)
+* Stop silently stripping spaces from passwords while typing in the web app's login, signup, and password-reset forms ([#1246](https://github.com/binwiederhier/ntfy/issues/1246), thanks to [@aldem](https://github.com/aldem) for reporting)
+* Update web app dependencies, including major-version upgrades to Vite (6 -> 8, now Rolldown-based), Material UI (5 -> 9), and Dexie (3 -> 4) ([#1800](https://github.com/binwiederhier/ntfy/pull/1800), [#1764](https://github.com/binwiederhier/ntfy/pull/1764), [#1767](https://github.com/binwiederhier/ntfy/pull/1767), [#1762](https://github.com/binwiederhier/ntfy/pull/1762), [#1766](https://github.com/binwiederhier/ntfy/pull/1766), [#1765](https://github.com/binwiederhier/ntfy/pull/1765), thanks Dependabot)
+* Play notification sounds in the web app even when the Notification API is unavailable, e.g. over plain HTTP or in browsers without notification support ([#1772](https://github.com/binwiederhier/ntfy/pull/1772), thanks to [@mitya12342](https://github.com/mitya12342) for the contribution)
+* Stop escaping `<`, `>`, and `&` as `\u003c`/`\u003e`/`\u0026` in JSON responses ([#1511](https://github.com/binwiederhier/ntfy/issues/1511), [#1512](https://github.com/binwiederhier/ntfy/pull/1512), thanks to [@wunter8](https://github.com/wunter8) for the contribution)
+* Fix the web app navbar not reflecting a topic reservation (lock icon, and "Reserve topic" -> "Change reservation"/"Remove reservation" menu) until a page reload, by persisting reservation and display-name changes onto already-subscribed topics during account sync
+* Reduce the web app's initial bundle size by ~300 KB (~50 KB gzipped) by lazy-loading the emoji picker dataset and the Markdown renderer, and by importing Material UI icons individually
+
+## ntfy server v2.24.0
 Released June 4, 2026
 
 The main feature for this release is an in-memory ACL cache (`auth-access-cache`) that can help bring down the read load
@@ -197,7 +327,7 @@ to the primary until the replica recovers.
 
 **Features:**
 
-* Support [PostgreSQL read replicas](config.md#postgresql-experimental) for offloading non-critical read queries via `database-replica-urls` config option ([#1648](https://github.com/binwiederhier/ntfy/pull/1648))
+* Support [PostgreSQL read replicas](config.md#postgresql) for offloading non-critical read queries via `database-replica-urls` config option ([#1648](https://github.com/binwiederhier/ntfy/pull/1648))
 * Add interactive [config generator](config.md#config-generator) to the documentation to help create server configuration files ([#1654](https://github.com/binwiederhier/ntfy/pull/1654))
 
 **Bug fixes + maintenance:**
@@ -209,7 +339,7 @@ to the primary until the replica recovers.
 Released March 7, 2026
 
 This is the biggest release I've ever done on the server. It's 14,997 added lines of code, and 10,202 lines removed, all from
-one [pull request](https://github.com/binwiederhier/ntfy/pull/1619) that adds [PostgreSQL support](config.md#postgresql-experimental).
+one [pull request](https://github.com/binwiederhier/ntfy/pull/1619) that adds [PostgreSQL support](config.md#postgresql).
 
 The code was written by Cursor and Claude, but reviewed and heavily tested over 2-3 weeks by me. I created comparison documents,
 went through all queries multiple times and reviewed the logic over and over again. I also did load tests and manual regression tests,
@@ -220,7 +350,7 @@ if things are working (or not working). There is a [one-off migration tool](http
 
 **Features:**
 
-* Add experimental [PostgreSQL support](config.md#postgresql-experimental) as an alternative database backend (message cache, user manager, web push subscriptions) via `database-url` config option ([#1114](https://github.com/binwiederhier/ntfy/issues/1114)/[#1619](https://github.com/binwiederhier/ntfy/pull/1619), thanks to [@brettinternet](https://github.com/brettinternet) for reporting)
+* Add experimental [PostgreSQL support](config.md#postgresql) as an alternative database backend (message cache, user manager, web push subscriptions) via `database-url` config option ([#1114](https://github.com/binwiederhier/ntfy/issues/1114)/[#1619](https://github.com/binwiederhier/ntfy/pull/1619), thanks to [@brettinternet](https://github.com/brettinternet) for reporting)
 
 **Bug fixes + maintenance:**
 
@@ -1948,53 +2078,6 @@ and the [ntfy Android app](https://github.com/binwiederhier/ntfy-android/release
 
 ## Not released yet
 
-### ntfy server v2.25.0 (UNRELEASED)
-
-This release adds **password reset** via email, and reworks email verification to use durable,
-link-based magic links (replacing the old in-memory 6-digit codes). Email stays optional at
-signup; a user can reset their password only once they have a verified "primary" (recovery)
-email.
-
-All of this work is probably not useful for self-hosters, but it hopefully will be useful for me,
-since I do have to reset emails on a regular basis.
-
-**Features:**
-
-* Add password reset via emailed magic link, with a "Forgot password" link on the login page and a `ntfy user reset-pass` CLI command for admins
-* Rework email verification to use durable, single-use, expiring magic links instead of in-memory 6-digit codes, and add a "primary" email (used for account recovery and as the `X-Email: yes` target) with verified/unverified state in the account UI
-
-**Bug fixes + maintenance:**
-
-* Generate access tokens, IDs, and magic-link tokens with a cryptographically secure RNG (`crypto/rand`) instead of a clock-seeded PRNG
-* `X-Email: yes` (also `true`/`1`) now sends to your primary verified email regardless of the `smtp-sender-verify` setting (previously it was rejected unless verification was enabled); it requires being logged in with a verified address
-
-### ntfy Android v1.25.x (UNRELEASED)
-
-This release makes the "connection lost" alert configurable and turns it off by default. Folks did not like it and many reached out
-or even gave ntfy bad reviews. I heard you! You can re-enable the alert in the advanced settings.
-
-The release also tries to be smarter about not retrying the connection at all if the app is in flight mode, or has no network. If there
-is no network, ntfy will now stop the foreground service entirely.
-
-Another change related to the networking is that we now force-reconnect when the connection is changed, e.g. during transitions
-from Wi-Fi to cellular network, or vice versa. That should allow for faster transitions during hand-overs.
-
-We also increase the client-side WebSocket ping interval from 1 minute to 3 minutes, which should slightly improve battery life,
-especially when paired with increaseing the server-side `keepalive-interval` in your self-hosted server. 
-
-**Features:**
-
-* Add configurable "Alert when connection is lost" setting ([#1665](https://github.com/binwiederhier/ntfy/issues/1665), [#1662](https://github.com/binwiederhier/ntfy/issues/1662), [#1652](https://github.com/binwiederhier/ntfy/issues/1652), [#1655](https://github.com/binwiederhier/ntfy/issues/1655), thanks to [@tintamarre](https://github.com/tintamarre), [@sjozs](https://github.com/sjozs), [@TheRealOne78](https://github.com/TheRealOne78), and [@DAE51D](https://github.com/DAE51D) for reporting)
-* Suppress connection alerts and stop foreground service when there is no network ([ntfy-android#165](https://github.com/binwiederhier/ntfy-android/pull/165), thanks to [@tintamarre](https://github.com/tintamarre) for the contribution)
-* Restart the foreground service immediately when network returns, even if the app process was killed while offline
-* Improve battery life by increasing WebSocket client ping interval from 1 min to 3 min, and reconnect instantly on Wi-Fi/cellular/VPN transitions ([ntfy-android#113](https://github.com/binwiederhier/ntfy-android/pull/113), thanks to [@ftilde](https://github.com/ftilde) for the investigation)
-* Disable UnifiedPush components when UnifiedPush is disabled in settings ([ntfy-android#168](https://github.com/binwiederhier/ntfy-android/pull/168), thanks to [@p1gp1g](https://github.com/p1gp1g) for the contribution)
-
-**Bug fixes + maintenance:**
-
-* Undo automatic phone number linking for numbers in message body ([ntfy-android#170](https://github.com/binwiederhier/ntfy-android/pull/170), thanks to [@acortelyou](https://github.com/acortelyou) for the contribution)
-* Fix subscription icons disappearing after a few days due to Android clearing cache ([#1322](https://github.com/binwiederhier/ntfy/issues/1322), thanks to [@mcanning](https://github.com/mcanning) for reporting)
-
 ### ntfy iOS app v1.8.0 (UNRELEASED)
 
 **Features:**

go.mod

@@ -3,23 +3,23 @@ module heckel.io/ntfy/v2
 go 1.25.8
 
 require (
-	cloud.google.com/go/firestore v1.22.0 // indirect
-	cloud.google.com/go/storage v1.62.2 // indirect
+	cloud.google.com/go/firestore v1.24.0 // indirect
+	cloud.google.com/go/storage v1.64.0 // indirect
 	github.com/BurntSushi/toml v1.6.0 // indirect
 	github.com/cpuguy83/go-md2man/v2 v2.0.7 // indirect
 	github.com/emersion/go-smtp v0.24.0
-	github.com/gabriel-vasile/mimetype v1.4.13
+	github.com/gabriel-vasile/mimetype v1.4.15
 	github.com/gorilla/websocket v1.5.3
-	github.com/mattn/go-sqlite3 v1.14.44
+	github.com/mattn/go-sqlite3 v1.14.49
 	github.com/olebedev/when v1.1.0
 	github.com/stretchr/testify v1.11.1
 	github.com/urfave/cli/v2 v2.27.7
-	golang.org/x/crypto v0.52.0
+	golang.org/x/crypto v0.54.0
 	golang.org/x/oauth2 v0.36.0 // indirect
-	golang.org/x/sync v0.20.0
-	golang.org/x/term v0.43.0
+	golang.org/x/sync v0.22.0
+	golang.org/x/term v0.45.0
 	golang.org/x/time v0.15.0
-	google.golang.org/api v0.283.0
+	google.golang.org/api v0.291.0
 	gopkg.in/yaml.v2 v2.4.0
 )
 
@@ -28,29 +28,29 @@ replace github.com/emersion/go-smtp => github.com/emersion/go-smtp v0.17.0 // Pi
 require github.com/pkg/errors v0.9.1 // indirect
 
 require (
-	firebase.google.com/go/v4 v4.20.0
+	firebase.google.com/go/v4 v4.21.0
 	github.com/SherClockHolmes/webpush-go v1.4.0
 	github.com/jackc/pgx/v5 v5.10.0
 	github.com/microcosm-cc/bluemonday v1.0.27
-	github.com/prometheus/client_golang v1.23.2
+	github.com/prometheus/client_golang v1.24.1
 	github.com/stripe/stripe-go/v74 v74.30.0
-	golang.org/x/sys v0.45.0
-	golang.org/x/text v0.37.0
+	golang.org/x/sys v0.47.0
+	golang.org/x/text v0.40.0
 )
 
 require (
 	cel.dev/expr v0.25.2 // indirect
 	cloud.google.com/go v0.123.0 // indirect
-	cloud.google.com/go/auth v0.20.0 // indirect
+	cloud.google.com/go/auth v0.22.0 // indirect
 	cloud.google.com/go/auth/oauth2adapt v0.2.8 // indirect
 	cloud.google.com/go/compute/metadata v0.9.0 // indirect
-	cloud.google.com/go/iam v1.11.0 // indirect
-	cloud.google.com/go/longrunning v1.0.0 // indirect
-	cloud.google.com/go/monitoring v1.29.0 // indirect
+	cloud.google.com/go/iam v1.12.0 // indirect
+	cloud.google.com/go/longrunning v1.2.0 // indirect
+	cloud.google.com/go/monitoring v1.30.0 // indirect
 	github.com/AlekSi/pointer v1.2.0 // indirect
-	github.com/GoogleCloudPlatform/opentelemetry-operations-go/detectors/gcp v1.32.0 // indirect
-	github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/metric v0.56.0 // indirect
-	github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/resourcemapping v0.56.0 // indirect
+	github.com/GoogleCloudPlatform/opentelemetry-operations-go/detectors/gcp v1.35.0 // indirect
+	github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/metric v0.59.0 // indirect
+	github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/resourcemapping v0.59.0 // indirect
 	github.com/MicahParks/keyfunc v1.9.0 // indirect
 	github.com/aymerick/douceur v0.2.0 // indirect
 	github.com/beorn7/perks v1.0.1 // indirect
@@ -60,17 +60,17 @@ require (
 	github.com/emersion/go-sasl v0.0.0-20241020182733-b788ff22d5a6 // indirect
 	github.com/envoyproxy/go-control-plane/envoy v1.37.0 // indirect
 	github.com/envoyproxy/protoc-gen-validate v1.3.3 // indirect
-	github.com/felixge/httpsnoop v1.0.4 // indirect
+	github.com/felixge/httpsnoop v1.1.0 // indirect
 	github.com/go-jose/go-jose/v4 v4.1.4 // indirect
-	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/logr v1.4.4 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/golang-jwt/jwt/v4 v4.5.2 // indirect
 	github.com/golang-jwt/jwt/v5 v5.3.1 // indirect
 	github.com/golang/protobuf v1.5.4 // indirect
 	github.com/google/s2a-go v0.1.9 // indirect
 	github.com/google/uuid v1.6.0 // indirect
-	github.com/googleapis/enterprise-certificate-proxy v0.3.16 // indirect
-	github.com/googleapis/gax-go/v2 v2.22.0 // indirect
+	github.com/googleapis/enterprise-certificate-proxy v0.3.19 // indirect
+	github.com/googleapis/gax-go/v2 v2.23.0 // indirect
 	github.com/gorilla/css v1.0.1 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
@@ -79,10 +79,10 @@ require (
 	github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
 	github.com/prometheus/client_model v0.6.2 // indirect
-	github.com/prometheus/common v0.68.1 // indirect
-	github.com/prometheus/procfs v0.20.1 // indirect
+	github.com/prometheus/common v0.70.1 // indirect
+	github.com/prometheus/procfs v0.21.1 // indirect
 	github.com/russross/blackfriday/v2 v2.1.0 // indirect
-	github.com/spiffe/go-spiffe/v2 v2.7.0 // indirect
+	github.com/spiffe/go-spiffe/v2 v2.8.1 // indirect
 	github.com/stretchr/objx v0.5.2 // indirect
 	github.com/xrash/smetrics v0.0.0-20250705151800-55b8f293f342 // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
@@ -94,12 +94,12 @@ require (
 	go.opentelemetry.io/otel/sdk v1.44.0 // indirect
 	go.opentelemetry.io/otel/sdk/metric v1.44.0 // indirect
 	go.opentelemetry.io/otel/trace v1.44.0 // indirect
-	golang.org/x/net v0.55.0 // indirect
+	golang.org/x/net v0.57.0 // indirect
 	google.golang.org/appengine/v2 v2.0.6 // indirect
-	google.golang.org/genproto v0.0.0-20260526163538-3dc84a4a5aaa // indirect
-	google.golang.org/genproto/googleapis/api v0.0.0-20260526163538-3dc84a4a5aaa // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20260526163538-3dc84a4a5aaa // indirect
-	google.golang.org/grpc v1.81.1 // indirect
+	google.golang.org/genproto v0.0.0-20260803160001-6ac0973c030d // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20260803160001-6ac0973c030d // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260803160001-6ac0973c030d // indirect
+	google.golang.org/grpc v1.83.0 // indirect
 	google.golang.org/protobuf v1.36.11 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -2,40 +2,40 @@ cel.dev/expr v0.25.2 h1:K6j46C81hXtZQfuX60cVWQFBJahKSE2gfRbNuvr5bFs=
 cel.dev/expr v0.25.2/go.mod h1:hrXvqGP6G6gyx8UAHSHJ5RGk//1Oj5nXQ2NI02Nrsg4=
 cloud.google.com/go v0.123.0 h1:2NAUJwPR47q+E35uaJeYoNhuNEM9kM8SjgRgdeOJUSE=
 cloud.google.com/go v0.123.0/go.mod h1:xBoMV08QcqUGuPW65Qfm1o9Y4zKZBpGS+7bImXLTAZU=
-cloud.google.com/go/auth v0.20.0 h1:kXTssoVb4azsVDoUiF8KvxAqrsQcQtB53DcSgta74CA=
-cloud.google.com/go/auth v0.20.0/go.mod h1:942/yi/itH1SsmpyrbnTMDgGfdy2BUqIKyd0cyYLc5Q=
+cloud.google.com/go/auth v0.22.0 h1:Xp9wAKkLoeaYb5pYZZoQGz4E9sdPxIbzS3gywZE3ciQ=
+cloud.google.com/go/auth v0.22.0/go.mod h1:M9o2Oz+YI2jAfxewJgb1vyI3vceHF+eohmxyzmrl+9s=
 cloud.google.com/go/auth/oauth2adapt v0.2.8 h1:keo8NaayQZ6wimpNSmW5OPc283g65QNIiLpZnkHRbnc=
 cloud.google.com/go/auth/oauth2adapt v0.2.8/go.mod h1:XQ9y31RkqZCcwJWNSx2Xvric3RrU88hAYYbjDWYDL+c=
 cloud.google.com/go/compute/metadata v0.9.0 h1:pDUj4QMoPejqq20dK0Pg2N4yG9zIkYGdBtwLoEkH9Zs=
 cloud.google.com/go/compute/metadata v0.9.0/go.mod h1:E0bWwX5wTnLPedCKqk3pJmVgCBSM6qQI1yTBdEb3C10=
-cloud.google.com/go/firestore v1.22.0 h1:avooeboIq37vKXobrbPUFhFBxS/c3FqmWoX0xs8dO6E=
-cloud.google.com/go/firestore v1.22.0/go.mod h1:PaM4i7i7ruALSKmlpHXXZaPObcZw0W7ie5UOPr72iTU=
-cloud.google.com/go/iam v1.11.0 h1:KieQ9Pb+LLPak1O3Rv3GgCxhnmkYf7Xyh0P5HfF1jFM=
-cloud.google.com/go/iam v1.11.0/go.mod h1:KP+nKGugNJW4LcLx1uEZcq1ok5sQHFaQehQNl4QDgV4=
-cloud.google.com/go/logging v1.18.0 h1:KhzZq+1cSkPH9YUaKLLhLtQxIHitVayBmk0sGfoM9+k=
-cloud.google.com/go/logging v1.18.0/go.mod h1:ZGKnpBaURITh+g/uom2VhbiFoFWvejcrHPDhxFtU/gI=
-cloud.google.com/go/longrunning v1.0.0 h1:lwzWEYD8+NkYV7dhexOz6kmlvajZA70+bW/xMhRVVdY=
-cloud.google.com/go/longrunning v1.0.0/go.mod h1:8nqFBPOO1U/XkhWl0I19AMZEphrHi73VNABIpKYaTwM=
-cloud.google.com/go/monitoring v1.29.0 h1:AHhDsFaSax1/4k+qlIDX/SDGe6hggnfXJ9dkgD9qBPY=
-cloud.google.com/go/monitoring v1.29.0/go.mod h1:72NOVjJXHY/HBfoLT0+qlCZBT059+9VXLeAnL2PeeVM=
-cloud.google.com/go/storage v1.62.2 h1:WgR4U9n7bIzXkkVnwPKKE8bkaKUNsHG+0MAAlh9DGU4=
-cloud.google.com/go/storage v1.62.2/go.mod h1:cpYz/kRVZ+UQAF1uHeea10/9ewcRbxGoGNKsS9daSXA=
+cloud.google.com/go/firestore v1.24.0 h1:x0Z3hrgjYgo2wI9whuBRQcNc2hYwzZDQy/7pkUXbXcs=
+cloud.google.com/go/firestore v1.24.0/go.mod h1:5aojyjN4olKUnBZDCRWwM+NsdrrCX3t1qfyERZGOonM=
+cloud.google.com/go/iam v1.12.0 h1:Aki3bX9aHUDKPHfnRJfDcTdVedvy6quGBQcTqx3DRXk=
+cloud.google.com/go/iam v1.12.0/go.mod h1:FEZ4lXpADAC2AIpQY7LANNjjwyQ2jK439CI2VaD+sLY=
+cloud.google.com/go/logging v1.19.0 h1:NCqhdVUg3wQ8Cobdf16FDSuTGi3+6+hdSBHrY5TsR6Q=
+cloud.google.com/go/logging v1.19.0/go.mod h1:i40NZCHC9Gqvod4yE+yQfDWwlgwW/SrshkkGibCHxcA=
+cloud.google.com/go/longrunning v1.2.0 h1:WjYH3YHBGCxGJP9M4dWGHBfXr/cFIjMkNgWcJj7/iMM=
+cloud.google.com/go/longrunning v1.2.0/go.mod h1:5KMQALFGOCtFoi2xSOA1u3H7WKlhmckgiyFw7+LGQp0=
+cloud.google.com/go/monitoring v1.30.0 h1:r/d+JUbyKmJ8b07iznuKfzVzrIXTWxHQ3lBRm3x2LlY=
+cloud.google.com/go/monitoring v1.30.0/go.mod h1:htlUR0QWVMrjFzZmN4LGnMAve9xB/eduwjmINxVZ8RM=
+cloud.google.com/go/storage v1.64.0 h1:KLpxI/oX9LxeRsNqn877d2WyeT3ryiEwnGt8pwcSPZg=
+cloud.google.com/go/storage v1.64.0/go.mod h1:lWyAtwvDZHdL3k68WVKbESP6bmWaV23ZJJ/JEVw/ZaQ=
 cloud.google.com/go/trace v1.16.0 h1:GmQovzFc5F0CNfl0VLgL64aoTtu7xsM0YajW2GlG9+E=
 cloud.google.com/go/trace v1.16.0/go.mod h1:r+bdAn16dKLSV1G2D5v3e58IlQlizfxWrUfjx7kM7X0=
-firebase.google.com/go/v4 v4.20.0 h1:ighpjeAC45rY/95cUQ+ojIKlKcTnz2YC0ldam56z2YU=
-firebase.google.com/go/v4 v4.20.0/go.mod h1:hqhkQtZkThGH42TnaYi7A8EFR1E0FEuB5oHvJ1Q57t8=
+firebase.google.com/go/v4 v4.21.0 h1:HBZV4jrLtFYj8EwWyqEZOuRLfkfkV2bpnfyyXHOhPxY=
+firebase.google.com/go/v4 v4.21.0/go.mod h1:CDumIdA5oTiyDpLNVcQoW8ZrB5CTgyE2D45DuENIABg=
 github.com/AlekSi/pointer v1.2.0 h1:glcy/gc4h8HnG2Z3ZECSzZ1IX1x2JxRVuDzaJwQE0+w=
 github.com/AlekSi/pointer v1.2.0/go.mod h1:gZGfd3dpW4vEc/UlyfKKi1roIqcCgwOIvb0tSNSBle0=
 github.com/BurntSushi/toml v1.6.0 h1:dRaEfpa2VI55EwlIW72hMRHdWouJeRF7TPYhI+AUQjk=
 github.com/BurntSushi/toml v1.6.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
-github.com/GoogleCloudPlatform/opentelemetry-operations-go/detectors/gcp v1.32.0 h1:rIkQfkCOVKc1OiRCNcSDD8ml5RJlZbH/Xsq7lbpynwc=
-github.com/GoogleCloudPlatform/opentelemetry-operations-go/detectors/gcp v1.32.0/go.mod h1:RD2SsorTmYhF6HkTmDw7KmPYQk8OBYwTkuasChwv7R4=
-github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/metric v0.56.0 h1:O2sXMyJh8b7devAGdE+163xtRurt0RVpB6DIzX5vGfg=
-github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/metric v0.56.0/go.mod h1:hEpiGU18xf70qb3jbTcIggWAiEfX/cOIVc2OTe4OegA=
-github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/cloudmock v0.56.0 h1:ZIT85vKP7LBS84XJ0WdJ3dPOX3iz4j3c0+lpajGQMyo=
-github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/cloudmock v0.56.0/go.mod h1:rqP9UEhOXv9WhQ7Gjz+G5y/pf8+BJZW5/Ts0AhE0PwE=
-github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/resourcemapping v0.56.0 h1:0YP0+/ixwu+Uqeu/FGiBZNQ19huiUxxiPXIc9WsLKuQ=
-github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/resourcemapping v0.56.0/go.mod h1:6ZZMQhZKDvUvkJw2rc+oDP90tMMzuU/J+5HG1ZmPOmE=
+github.com/GoogleCloudPlatform/opentelemetry-operations-go/detectors/gcp v1.35.0 h1:bN1gA3of5bXtbnLsRPrwfmbbe7A5UWFlcTHseujLnpc=
+github.com/GoogleCloudPlatform/opentelemetry-operations-go/detectors/gcp v1.35.0/go.mod h1:Yj5vHEz/aAepZGliRJsA6uvHAVAQyEwajq9ORCHPxzM=
+github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/metric v0.59.0 h1:c/Ivw7FuawPLfrr+zB0LZKeCchO2cAHQpF2qZ6OV7rQ=
+github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/metric v0.59.0/go.mod h1:Zba7lknY/d78oxbKqFTmCsaGwfpzeJ3ktrrLXtnTV6g=
+github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/cloudmock v0.59.0 h1:xTXsqDOj5k9mK3VVWHYUryryJCIdYfXxdjKFwpzINUw=
+github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/cloudmock v0.59.0/go.mod h1:V9g30lTKzfUsEW+gpWssck6u9IhARajmipodImLLcwI=
+github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/resourcemapping v0.59.0 h1:18FRm6ZcN/x9+ZmhMr96hLcTtlLn2/gHPuDLVeg7XcY=
+github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/resourcemapping v0.59.0/go.mod h1:YqwkQPrWSC7+byyc1VlKbWLBF5JsW5IoL6xUkemYSXk=
 github.com/MicahParks/keyfunc v1.9.0 h1:lhKd5xrFHLNOWrDc4Tyb/Q1AJ4LCzQ48GVJyVIID3+o=
 github.com/MicahParks/keyfunc v1.9.0/go.mod h1:IdnCilugA0O/99dW+/MkvlyrsX8+L8+x95xuVNtM5jw=
 github.com/SherClockHolmes/webpush-go v1.4.0 h1:ocnzNKWN23T9nvHi6IfyrQjkIc0oJWv1B1pULsf9i3s=
@@ -66,15 +66,15 @@ github.com/envoyproxy/go-control-plane/ratelimit v0.1.0 h1:/G9QYbddjL25KvtKTv3an
 github.com/envoyproxy/go-control-plane/ratelimit v0.1.0/go.mod h1:Wk+tMFAFbCXaJPzVVHnPgRKdUdwW/KdbRt94AzgRee4=
 github.com/envoyproxy/protoc-gen-validate v1.3.3 h1:MVQghNeW+LZcmXe7SY1V36Z+WFMDjpqGAGacLe2T0ds=
 github.com/envoyproxy/protoc-gen-validate v1.3.3/go.mod h1:TsndJ/ngyIdQRhMcVVGDDHINPLWB7C82oDArY51KfB0=
-github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
-github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
-github.com/gabriel-vasile/mimetype v1.4.13 h1:46nXokslUBsAJE/wMsp5gtO500a4F3Nkz9Ufpk2AcUM=
-github.com/gabriel-vasile/mimetype v1.4.13/go.mod h1:d+9Oxyo1wTzWdyVUPMmXFvp4F9tea18J8ufA774AB3s=
+github.com/felixge/httpsnoop v1.1.0 h1:3YtUj32ZZkqZtt3sZZsClsymw/QDuVfpNhoA31zeORc=
+github.com/felixge/httpsnoop v1.1.0/go.mod h1:Zqxgdd+1Rkcz8euOqdr7lqgCRJztwr5hp9vDSi5UZCE=
+github.com/gabriel-vasile/mimetype v1.4.15 h1:05iP/CYtZ/w455R/KZM6rZ5ieAdh99UPtd+d3YzLmaI=
+github.com/gabriel-vasile/mimetype v1.4.15/go.mod h1:azpTcoLcDZRNgFou5j+APrqQx9HqVPWa6ijYQIIVswQ=
 github.com/go-jose/go-jose/v4 v4.1.4 h1:moDMcTHmvE6Groj34emNPLs/qtYXRVcd6S7NHbHz3kA=
 github.com/go-jose/go-jose/v4 v4.1.4/go.mod h1:x4oUasVrzR7071A4TnHLGSPpNOm2a21K9Kf04k1rs08=
 github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
-github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
-github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/logr v1.4.4 h1:tG4xh9yMsRCAiodLVTxyrkzSZ9+o0L1Kg/+cPVcbP/8=
+github.com/go-logr/logr v1.4.4/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
 github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
 github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
 github.com/golang-jwt/jwt/v4 v4.4.2/go.mod h1:m21LjoU+eqJr34lmDMbreY2eSTRJ1cv77w39/MY0Ch0=
@@ -96,10 +96,10 @@ github.com/google/s2a-go v0.1.9 h1:LGD7gtMgezd8a/Xak7mEWL0PjoTQFvpRudN895yqKW0=
 github.com/google/s2a-go v0.1.9/go.mod h1:YA0Ei2ZQL3acow2O62kdp9UlnvMmU7kA6Eutn0dXayM=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
-github.com/googleapis/enterprise-certificate-proxy v0.3.16 h1:F/VPrx0YPBdksZJQdCAp0WUsqnNmZpUZszzfYt0M5Dw=
-github.com/googleapis/enterprise-certificate-proxy v0.3.16/go.mod h1:9Yb0eAkH/Xqhvv3zbeKf/+wMJqCeocWc6KIhDvEAuYE=
-github.com/googleapis/gax-go/v2 v2.22.0 h1:PjIWBpgGIVKGoCXuiCoP64altEJCj3/Ei+kSU5vlZD4=
-github.com/googleapis/gax-go/v2 v2.22.0/go.mod h1:irWBbALSr0Sk3qlqb9SyJ1h68WjgeFuiOzI4Rqw5+aY=
+github.com/googleapis/enterprise-certificate-proxy v0.3.19 h1:mMOE7DN2+p76/EdIrmAy9B9bH+yC4563vmnJ34QR8i4=
+github.com/googleapis/enterprise-certificate-proxy v0.3.19/go.mod h1:rSEsBUemEBZEexP2y6jPp16LUmUbjmSbcPMQizR0o4k=
+github.com/googleapis/gax-go/v2 v2.23.0 h1:Tchl7qkvE7Ip3y+ztvNufYFvkfqTe7NfLTYGIdJRLuE=
+github.com/googleapis/gax-go/v2 v2.23.0/go.mod h1:rBQKOVJCdb8IFEzg+FCwlt1LP/xMDGuqUXhUG+XMXEg=
 github.com/gorilla/css v1.0.1 h1:ntNaBIghp6JmvWnxbZKANoLyuXTPZ4cAMlo6RyhlbO8=
 github.com/gorilla/css v1.0.1/go.mod h1:BvnYkspnSzMmwRK+b8/xgNPLiIuNZr6vbZBTPQ2A3b0=
 github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
@@ -112,16 +112,16 @@ github.com/jackc/pgx/v5 v5.10.0 h1:VhSvgU2jSli8o3AqIEOTJr7rZwAEUVo4E4XhR94Zfr0=
 github.com/jackc/pgx/v5 v5.10.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
 github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
 github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
-github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo=
-github.com/klauspost/compress v1.18.0/go.mod h1:2Pp+KzxcywXVXMr50+X0Q/Lsb43OQHYWRCY2AiWywWQ=
+github.com/klauspost/compress v1.19.1 h1:VsB4HPswih7mmZ8WleSFQ75c/Ui1M4trX5oAsJnhSlk=
+github.com/klauspost/compress v1.19.1/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
 github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
-github.com/mattn/go-sqlite3 v1.14.44 h1:3VSe+xafpbzsLbdr2AWlAZk9yRHiBhTBakioXaCKTF8=
-github.com/mattn/go-sqlite3 v1.14.44/go.mod h1:pjEuOr8IwzLJP2MfGeTb0A35jauH+C2kbHKBr7yXKVQ=
+github.com/mattn/go-sqlite3 v1.14.49 h1:B8jBHC3xhxZgxztrgruTuLucebnULQnx4W7cF7SAE9w=
+github.com/mattn/go-sqlite3 v1.14.49/go.mod h1:6JTjA44L93a0QCyJef5YvlPoKXntQPjzWv5gtm9sB6w=
 github.com/microcosm-cc/bluemonday v1.0.27 h1:MpEUotklkwCSLeH+Qdx1VJgNqLlpY2KXwXFM08ygZfk=
 github.com/microcosm-cc/bluemonday v1.0.27/go.mod h1:jFi9vgW+H7c3V0lb6nR74Ib/DIB5OBs92Dimizgw2cA=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
@@ -135,20 +135,20 @@ github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10/go.mod h1
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/prometheus/client_golang v1.23.2 h1:Je96obch5RDVy3FDMndoUsjAhG5Edi49h0RJWRi/o0o=
-github.com/prometheus/client_golang v1.23.2/go.mod h1:Tb1a6LWHB3/SPIzCoaDXI4I8UHKeFTEQ1YCr+0Gyqmg=
+github.com/prometheus/client_golang v1.24.1 h1:JnJkREXzWxUdCuPFpIWZiPispT9xVV59uiuyR2bPlnU=
+github.com/prometheus/client_golang v1.24.1/go.mod h1:F+oSRECHg4sse5ucfYpYDeIv/hu68Zo0uoHKetWnzcE=
 github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
 github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
-github.com/prometheus/common v0.68.1 h1:omjRRl4QP4komogpXuhfeOiisQg7xdy8VM1UY+pStaY=
-github.com/prometheus/common v0.68.1/go.mod h1:ZzL3f6u94qUxh9p+tJTrF+FvBS1XXbbRAZCQkytAL0Y=
-github.com/prometheus/procfs v0.20.1 h1:XwbrGOIplXW/AU3YhIhLODXMJYyC1isLFfYCsTEycfc=
-github.com/prometheus/procfs v0.20.1/go.mod h1:o9EMBZGRyvDrSPH1RqdxhojkuXstoe4UlK79eF5TGGo=
+github.com/prometheus/common v0.70.1 h1:1HvjP4D5oL3t8RsPlwxA9onvvStjtIHYE5XuuwOi/PY=
+github.com/prometheus/common v0.70.1/go.mod h1:VdFUQDMZK3VLkurFUVhia6uys/0suUp86TJz5qbJRhc=
+github.com/prometheus/procfs v0.21.1 h1:GljZCt+zSTS+NZq88cyQ1LjZ+RCHp3uVuabBWA5+OJI=
+github.com/prometheus/procfs v0.21.1/go.mod h1:aB55Cww9pdSJVHk0hUf0inxWyyjPogFIjmHKYgMKmtY=
 github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
 github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
 github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
-github.com/spiffe/go-spiffe/v2 v2.7.0 h1:uXe1MflJoHw58wAUvxVlcM7WpKtijWG7I1UidcGh6g4=
-github.com/spiffe/go-spiffe/v2 v2.7.0/go.mod h1:47Q0Q9/AqGha8QLHp+kxpH4Wca7X7EnOtlIJy3mxZ3U=
+github.com/spiffe/go-spiffe/v2 v2.8.1 h1:eXZMLsu+3MLEPJyGJkolqtVrteZfQdUpOWj6LTiDl/E=
+github.com/spiffe/go-spiffe/v2 v2.8.1/go.mod h1:47Q0Q9/AqGha8QLHp+kxpH4Wca7X7EnOtlIJy3mxZ3U=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
 github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
@@ -173,8 +173,8 @@ go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0 h1:8tvICD4
 go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0/go.mod h1:z9+yiacE0IHRqM4qFfkbt/JYlmYXgss8GY/jXoNuPJI=
 go.opentelemetry.io/otel v1.44.0 h1:JjwHmHpA4iZ3wBxluu2fbbE7j4kqlE8jXyAyPXH7HqU=
 go.opentelemetry.io/otel v1.44.0/go.mod h1:BMgjTHL9WPRlRjL2oZCBTL4whCGtXch2H4BhOPIAyYc=
-go.opentelemetry.io/otel/exporters/stdout/stdoutmetric v1.43.0 h1:TC+BewnDpeiAmcscXbGMfxkO+mwYUwE/VySwvw88PfA=
-go.opentelemetry.io/otel/exporters/stdout/stdoutmetric v1.43.0/go.mod h1:J/ZyF4vfPwsSr9xJSPyQ4LqtcTPULFR64KwTikGLe+A=
+go.opentelemetry.io/otel/exporters/stdout/stdoutmetric v1.44.0 h1:hqxVTu/GtBF+vJ8d1fzW7fRxZFvgoDjWcxwwCaFDYpU=
+go.opentelemetry.io/otel/exporters/stdout/stdoutmetric v1.44.0/go.mod h1:z5fVEF4X5v0ESvlJqBrrFlBVoj5EQuefZpzsu7R+x5Q=
 go.opentelemetry.io/otel/metric v1.44.0 h1:1w0gILTcHdr3YI+ixLyjemwrVnsMURbTZFrSYCdDdmc=
 go.opentelemetry.io/otel/metric v1.44.0/go.mod h1:8O7hanEPBNgEMmybD3s2VBKcgWOCsA6tzHBPODAiquo=
 go.opentelemetry.io/otel/metric/x v0.66.0 h1:YkCrx1zLOChi9ZcZ6euupOcsgzbVlec7D/xoEU1+cTA=
@@ -195,8 +195,8 @@ golang.org/x/crypto v0.13.0/go.mod h1:y6Z2r+Rw4iayiXXAIxJIDAJ1zMW4yaTpebo8fPOliY
 golang.org/x/crypto v0.19.0/go.mod h1:Iy9bg/ha4yyC70EfRS8jz+B6ybOBKMaSxLj6P6oBDfU=
 golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0v8=
 golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk=
-golang.org/x/crypto v0.52.0 h1:RMs7fP2rXdep0CftQlK8Uf+kibLm7qkCcradZWYz988=
-golang.org/x/crypto v0.52.0/go.mod h1:1QgfPxDqh0T2M/elOJtp9RvuR95kVjir0e6/BvEmGbc=
+golang.org/x/crypto v0.54.0 h1:YLIA59K4fiNzHzjnZt2tUJQjQtUWfWbeHBqKtk3eScw=
+golang.org/x/crypto v0.54.0/go.mod h1:KWL8ny2AZdGR2cWmzeHrp2azQPGogOv+HeQaVEXC2dk=
 golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
 golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
 golang.org/x/mod v0.12.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
@@ -211,8 +211,8 @@ golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg=
 golang.org/x/net v0.15.0/go.mod h1:idbUs1IY1+zTqbi8yxTbhexhEEk5ur9LInksu6HrEpk=
 golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44=
 golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM=
-golang.org/x/net v0.55.0 h1:bcvxaJn3e1U6InsFWt1JUq1aSjnRxLzT2rtD2KfkDF8=
-golang.org/x/net v0.55.0/go.mod h1:L5U2KuzuOe1lY7Z+aWVIKK6qEeJXnXV9yzGA+WCHJww=
+golang.org/x/net v0.57.0 h1:K5+3DljvIuDG9/Jv9rvyMywYNFCQ9RSUY6OOTTkT+tE=
+golang.org/x/net v0.57.0/go.mod h1:KpXc8iv+r3XplLAG/f7Jsf9RPszJzdR0f58q9vGOuEU=
 golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
 golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
@@ -222,8 +222,8 @@ golang.org/x/sync v0.3.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y=
 golang.org/x/sync v0.6.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sync v0.10.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
-golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
-golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
@@ -236,8 +236,8 @@ golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/sys v0.45.0 h1:dO4czNzziLiiXplLQgBCEpCvXQ3dnkn0SdaZSYdQ+FY=
-golang.org/x/sys v0.45.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/telemetry v0.0.0-20240228155512-f48c80bd79b2/go.mod h1:TeRTkGYfJXctD9OcfyVLyj2J3IxLnKwHJR8f4D8a3YE=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
@@ -247,8 +247,8 @@ golang.org/x/term v0.12.0/go.mod h1:owVbMEjm3cBLCHdkQu9b1opXd4ETQWc3BhuQGKgXgvU=
 golang.org/x/term v0.17.0/go.mod h1:lLRBjIVuehSbZlaOtGMbcMncT+aqLLLmKrsjNrUguwk=
 golang.org/x/term v0.20.0/go.mod h1:8UkIAJTvZgivsXaD6/pH6U9ecQzZ45awqEOzuCvwpFY=
 golang.org/x/term v0.27.0/go.mod h1:iMsnZpn0cago0GOrHO2+Y7u7JPn5AylBrcoWkElMTSM=
-golang.org/x/term v0.43.0 h1:S4RLU2sB31O/NCl+zFN9Aru9A/Cq2aqKpTZJ6B+DwT4=
-golang.org/x/term v0.43.0/go.mod h1:lrhlHNdQJHO+1qVYiHfFKVuVioJIheAc3fBSMFYEIsk=
+golang.org/x/term v0.45.0 h1:NwWyBmoJCbfTHpxrWoZ9C6/VxOf7ic219I8xZZFdrf0=
+golang.org/x/term v0.45.0/go.mod h1:9aqxs0blBcrm/n0L9QW0aRVD+ktan8ssZromtqJC43w=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
@@ -260,8 +260,8 @@ golang.org/x/text v0.13.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
 golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
 golang.org/x/text v0.15.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
 golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ=
-golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
-golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
+golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
+golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
 golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
@@ -274,18 +274,18 @@ golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8T
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
 gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
-google.golang.org/api v0.283.0 h1:0lkp8u0MPwJVHqRL+nJlMAoZVVzbmiXmFHXMOTmSPik=
-google.golang.org/api v0.283.0/go.mod h1:6Wssta4c5n9qHq5CBhmlai5h/PUa1djdDAIhYEHyvcM=
+google.golang.org/api v0.291.0 h1:wfPbbY+mr9c7wZLqqzrHJLft/q8iFKREd6IgTBUene0=
+google.golang.org/api v0.291.0/go.mod h1:at7kwWbuonglBFEBoeMDAV1bguHqL3qf0BHFsv3coa0=
 google.golang.org/appengine/v2 v2.0.6 h1:LvPZLGuchSBslPBp+LAhihBeGSiRh1myRoYK4NtuBIw=
 google.golang.org/appengine/v2 v2.0.6/go.mod h1:WoEXGoXNfa0mLvaH5sV3ZSGXwVmy8yf7Z1JKf3J3wLI=
-google.golang.org/genproto v0.0.0-20260526163538-3dc84a4a5aaa h1:mfj8IS4EA4VAR9a6QDVxTQkLY64iBybb5QI1B4pXrpE=
-google.golang.org/genproto v0.0.0-20260526163538-3dc84a4a5aaa/go.mod h1:fuT7yonGw1Iq2oa+YC0fyqPPQJkgo/54gPNC6VitOkI=
-google.golang.org/genproto/googleapis/api v0.0.0-20260526163538-3dc84a4a5aaa h1:Kjn0N0tCrDgiAFW+lGO4JZ3ck44CehvJQMAwj9QF0G8=
-google.golang.org/genproto/googleapis/api v0.0.0-20260526163538-3dc84a4a5aaa/go.mod h1:q4lMZS6kskjT5HvCPrnnypcDPVJqT/f4nfxmkE7gryY=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260526163538-3dc84a4a5aaa h1:mZHHdPZl0dbGHCflZgAq/Q468DWVFcU2whhB2KAo8fk=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260526163538-3dc84a4a5aaa/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
-google.golang.org/grpc v1.81.1 h1:VnnIIZ88UzOOKLukQi+ImGz8O1Wdp8nAGGnvOfEIWQQ=
-google.golang.org/grpc v1.81.1/go.mod h1:xGH9GfzOyMTGIOXBJmXt+BX/V0kcdQbdcuwQ/zNw42I=
+google.golang.org/genproto v0.0.0-20260803160001-6ac0973c030d h1:33JLrUF0lFT31667SAtJzZAjLewV0ew5Mizks4caz0A=
+google.golang.org/genproto v0.0.0-20260803160001-6ac0973c030d/go.mod h1:I7vGRdTamb7ukERkgP9I+0e4p21O4ak3cM7ICA3krg8=
+google.golang.org/genproto/googleapis/api v0.0.0-20260803160001-6ac0973c030d h1:FarXi840EJWSHYTN3ERkADbPWjl307+FGrA22KAVjjc=
+google.golang.org/genproto/googleapis/api v0.0.0-20260803160001-6ac0973c030d/go.mod h1:K/+WGbmBY7aNW1HDw1fJnKYo10i0DkAX6pows00dLig=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260803160001-6ac0973c030d h1:IL4hdHzcUv2l/gcg98/Rj3FbtE6axwqslOW8SW0C+S0=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260803160001-6ac0973c030d/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
+google.golang.org/grpc v1.83.0 h1:JeNZEKJFbQxArAMl+hiytHauacDNqJUllNfmIMmpqnQ=
+google.golang.org/grpc v1.83.0/go.mod h1:kDyl6SKsiHKt0uylY5gtn5cEjkrIOhQOGDgIc4JGwzQ=
 google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
 google.golang.org/protobuf v1.30.0/go.mod h1:HV8QOd/L58Z+nl8r43ehVNZIU/HEI6OcFqwMG9pJV4I=
 google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=

message/cache.go

@@ -17,6 +17,7 @@ import (
 
 const (
 	tagMessageCache = "message_cache"
+	schemaStore     = "message" // Store name in the schema_version table (see db/schema)
 )
 
 var errNoRows = errors.New("no rows found")
@@ -34,6 +35,7 @@ type queries struct {
 	selectMessagesSinceIDScheduled   string
 	selectMessagesLatest             string
 	selectMessagesDue                string
+	selectMessagesDueForUpdate       string // Postgres-only: claims due rows via FOR UPDATE SKIP LOCKED; empty for SQLite/mem
 	deleteExpiredMessages            string
 	updateMessagePublished           string
 	selectMessagesCount              string
@@ -237,6 +239,15 @@ func (c *Cache) messagesLatest(topic string) ([]*model.Message, error) {
 
 // MessagesDue returns all messages that are due for publishing
 func (c *Cache) MessagesDue() ([]*model.Message, error) {
+	// On Postgres (cluster mode), claim due rows atomically so that concurrent delayed senders
+	// on other nodes cannot pick up the same message. We SELECT ... FOR UPDATE SKIP LOCKED and
+	// mark the claimed rows published in the same transaction; each row is thus handed to exactly
+	// one node. We deliberately mark published at claim time (not after delivery) to keep the row
+	// lock short: holding a transaction open across Firebase/WebPush/email delivery would be far
+	// worse than the small at-most-once window if a node crashes between claim and delivery.
+	if c.queries.selectMessagesDueForUpdate != "" {
+		return c.claimMessagesDue()
+	}
 	rows, err := c.db.Query(c.queries.selectMessagesDue, time.Now().Unix())
 	if err != nil {
 		return nil, err
@@ -244,6 +255,32 @@ func (c *Cache) MessagesDue() ([]*model.Message, error) {
 	return readMessages(rows)
 }
 
+// claimMessagesDue is the Postgres claiming path for MessagesDue (see its comment).
+func (c *Cache) claimMessagesDue() ([]*model.Message, error) {
+	tx, err := c.db.Begin()
+	if err != nil {
+		return nil, err
+	}
+	defer tx.Rollback()
+	rows, err := tx.Query(c.queries.selectMessagesDueForUpdate, time.Now().Unix())
+	if err != nil {
+		return nil, err
+	}
+	messages, err := readMessages(rows) // reads all rows and closes them
+	if err != nil {
+		return nil, err
+	}
+	for _, m := range messages {
+		if _, err := tx.Exec(c.queries.updateMessagePublished, m.ID); err != nil {
+			return nil, err
+		}
+	}
+	if err := tx.Commit(); err != nil {
+		return nil, err
+	}
+	return messages, nil
+}
+
 // DeleteExpiredMessages deletes up to `limit` expired messages in a single query
 // and returns the number of deleted rows.
 func (c *Cache) DeleteExpiredMessages(limit int) (int64, error) {

message/cache_postgres.go

@@ -4,6 +4,7 @@ import (
 	"time"
 
 	"heckel.io/ntfy/v2/db"
+	"heckel.io/ntfy/v2/db/schema"
 )
 
 // PostgreSQL runtime query constants
@@ -60,6 +61,13 @@ const (
 		WHERE time <= $1 AND published = FALSE
 		ORDER BY time, id
 	`
+	postgresSelectMessagesDueForUpdateQuery = `
+		SELECT mid, sequence_id, time, event, expires, topic, message, title, priority, tags, click, icon, actions, attachment_name, attachment_type, attachment_size, attachment_expires, attachment_url, sender, user_id, content_type, encoding
+		FROM message
+		WHERE time <= $1 AND published = FALSE
+		ORDER BY time, id
+		FOR UPDATE SKIP LOCKED
+	`
 	postgresUpdateMessagePublishedQuery = `UPDATE message SET published = TRUE WHERE mid = $1`
 	postgresSelectMessagesCountQuery    = `SELECT COUNT(*) FROM message`
 	postgresSelectTopicsQuery           = `SELECT topic FROM message GROUP BY topic`
@@ -87,6 +95,7 @@ var postgresQueries = queries{
 	selectMessagesSinceIDScheduled:   postgresSelectMessagesSinceIDIncludeScheduledQuery,
 	selectMessagesLatest:             postgresSelectMessagesLatestQuery,
 	selectMessagesDue:                postgresSelectMessagesDueQuery,
+	selectMessagesDueForUpdate:       postgresSelectMessagesDueForUpdateQuery,
 	deleteExpiredMessages:            postgresDeleteExpiredMessagesQuery,
 	updateMessagePublished:           postgresUpdateMessagePublishedQuery,
 	selectMessagesCount:              postgresSelectMessagesCountQuery,
@@ -102,7 +111,7 @@ var postgresQueries = queries{
 
 // NewPostgresStore creates a new PostgreSQL-backed message cache store using an existing database connection pool.
 func NewPostgresStore(d *db.DB, batchSize int, batchTimeout time.Duration) (*Cache, error) {
-	if err := setupPostgres(d.Primary()); err != nil {
+	if err := schema.Migrate(d.Primary(), schema.Postgres, schemaStore, postgresCurrentSchemaVersion, postgresCreateTables, postgresMigrations); err != nil {
 		return nil, err
 	}
 	return newCache(d, postgresQueries, nil, batchSize, batchTimeout, false), nil

message/cache_postgres_schema.go

@@ -1,16 +1,13 @@
 package message
 
 import (
-	"database/sql"
-	"fmt"
-
-	"heckel.io/ntfy/v2/db"
-	"heckel.io/ntfy/v2/log"
+	"heckel.io/ntfy/v2/db/schema"
 )
 
 // Initial PostgreSQL schema
 const (
-	postgresCreateTablesQuery = `
+	postgresCurrentSchemaVersion = 15
+	postgresCreateTablesQuery    = `
 		CREATE TABLE IF NOT EXISTS message (
 			id BIGSERIAL PRIMARY KEY,
 			mid TEXT NOT NULL,
@@ -50,21 +47,9 @@ const (
 			value BIGINT
 		);
 		INSERT INTO message_stats (key, value) VALUES ('messages', 0);
-		CREATE TABLE IF NOT EXISTS schema_version (
-			store TEXT PRIMARY KEY,
-			version INT NOT NULL
-		);
 	`
 )
 
-// PostgreSQL schema management queries
-const (
-	postgresCurrentSchemaVersion     = 15
-	postgresInsertSchemaVersionQuery = `INSERT INTO schema_version (store, version) VALUES ('message', $1)`
-	postgresUpdateSchemaVersionQuery = `UPDATE schema_version SET version = $1 WHERE store = 'message'`
-	postgresSelectSchemaVersionQuery = `SELECT version FROM schema_version WHERE store = 'message'`
-)
-
 // PostgreSQL schema migrations
 const (
 	// 14 -> 15
@@ -73,51 +58,12 @@ const (
 	`
 )
 
-var postgresMigrations = map[int]func(d *sql.DB) error{
-	14: postgresMigrateFrom14,
-}
+var (
+	postgresCreateTables = schema.AsMigrateFunc(postgresCreateTablesQuery)
 
-func setupPostgres(d *sql.DB) error {
-	var schemaVersion int
-	if err := d.QueryRow(postgresSelectSchemaVersionQuery).Scan(&schemaVersion); err != nil {
-		return setupNewPostgresDB(d)
-	} else if schemaVersion == postgresCurrentSchemaVersion {
-		return nil
-	} else if schemaVersion > postgresCurrentSchemaVersion {
-		return fmt.Errorf("unexpected schema version: version %d is higher than current version %d", schemaVersion, postgresCurrentSchemaVersion)
+	// postgresMigrations maps a schema version to the migration upgrading it to the next
+	// version. Always append migrations at the end, never insert in the middle.
+	postgresMigrations = map[int]schema.MigrateFunc{
+		14: schema.AsMigrateFunc(postgresMigrate14To15CreateIndexQuery),
 	}
-	for i := schemaVersion; i < postgresCurrentSchemaVersion; i++ {
-		fn, ok := postgresMigrations[i]
-		if !ok {
-			return fmt.Errorf("cannot find migration step from schema version %d to %d", i, i+1)
-		} else if err := fn(d); err != nil {
-			return err
-		}
-	}
-	return nil
-}
-
-func postgresMigrateFrom14(d *sql.DB) error {
-	log.Tag(tagMessageCache).Info("Migrating message cache database schema: from 14 to 15")
-	return db.ExecTx(d, func(tx *sql.Tx) error {
-		if _, err := tx.Exec(postgresMigrate14To15CreateIndexQuery); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(postgresUpdateSchemaVersionQuery, 15); err != nil {
-			return err
-		}
-		return nil
-	})
-}
-
-func setupNewPostgresDB(sqlDB *sql.DB) error {
-	return db.ExecTx(sqlDB, func(tx *sql.Tx) error {
-		if _, err := tx.Exec(postgresCreateTablesQuery); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(postgresInsertSchemaVersionQuery, postgresCurrentSchemaVersion); err != nil {
-			return err
-		}
-		return nil
-	})
-}
+)

message/cache_postgres_test.go

@@ -0,0 +1,76 @@
+package message_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	dbtest "heckel.io/ntfy/v2/db/test"
+	"heckel.io/ntfy/v2/message"
+	"heckel.io/ntfy/v2/model"
+)
+
+func TestPostgresStore_Migration_From14(t *testing.T) {
+	// A pre-framework database at version 14: full v14 schema, version tracked in the
+	// hand-rolled schema_version table, and no idx_message_attachment_expires yet
+	testDB := dbtest.CreateTestPostgres(t)
+	_, err := testDB.Exec(`
+		CREATE TABLE message (
+			id BIGSERIAL PRIMARY KEY,
+			mid TEXT NOT NULL,
+			sequence_id TEXT NOT NULL,
+			time BIGINT NOT NULL,
+			event TEXT NOT NULL,
+			expires BIGINT NOT NULL,
+			topic TEXT NOT NULL,
+			message TEXT NOT NULL,
+			title TEXT NOT NULL,
+			priority INT NOT NULL,
+			tags TEXT NOT NULL,
+			click TEXT NOT NULL,
+			icon TEXT NOT NULL,
+			actions TEXT NOT NULL,
+			attachment_name TEXT NOT NULL,
+			attachment_type TEXT NOT NULL,
+			attachment_size BIGINT NOT NULL,
+			attachment_expires BIGINT NOT NULL,
+			attachment_url TEXT NOT NULL,
+			attachment_deleted BOOLEAN NOT NULL DEFAULT FALSE,
+			sender TEXT NOT NULL,
+			user_id TEXT NOT NULL,
+			content_type TEXT NOT NULL,
+			encoding TEXT NOT NULL,
+			published BOOLEAN NOT NULL DEFAULT FALSE
+		);
+		CREATE INDEX idx_message_mid ON message (mid);
+		CREATE INDEX idx_message_sequence_id ON message (sequence_id);
+		CREATE INDEX idx_message_topic_published_time ON message (topic, published, time, id);
+		CREATE INDEX idx_message_published_expires ON message (published, expires);
+		CREATE INDEX idx_message_sender_attachment_expires ON message (sender, attachment_expires) WHERE user_id = '';
+		CREATE INDEX idx_message_user_id_attachment_expires ON message (user_id, attachment_expires);
+		CREATE TABLE message_stats (key TEXT PRIMARY KEY, value BIGINT);
+		INSERT INTO message_stats (key, value) VALUES ('messages', 0);
+		CREATE TABLE schema_version (store TEXT PRIMARY KEY, version INT NOT NULL);
+		INSERT INTO schema_version (store, version) VALUES ('message', 14);
+	`)
+	require.Nil(t, err)
+	store, err := message.NewPostgresStore(testDB, 0, 0)
+	require.Nil(t, err)
+	// The 14 -> 15 step ran: version bumped, partial index created
+	var version int
+	require.Nil(t, testDB.QueryRow(`SELECT version FROM schema_version WHERE store = 'message'`).Scan(&version))
+	require.Equal(t, 15, version)
+	var indexCount int
+	require.Nil(t, testDB.QueryRow(`SELECT COUNT(*) FROM pg_indexes WHERE indexname = 'idx_message_attachment_expires' AND schemaname = current_schema()`).Scan(&indexCount))
+	require.Equal(t, 1, indexCount)
+	// And the store works
+	require.Nil(t, store.AddMessage(model.NewDefaultMessage("mytopic", "hi there")))
+	messages, err := store.Messages("mytopic", model.SinceAllMessages, false)
+	require.Nil(t, err)
+	require.Len(t, messages, 1)
+
+	// The migrated database must be structurally identical to a freshly created one
+	freshDB := dbtest.CreateTestPostgres(t)
+	_, err = message.NewPostgresStore(freshDB, 0, 0)
+	require.Nil(t, err)
+	require.Equal(t, dbtest.PostgresSchema(t, freshDB), dbtest.PostgresSchema(t, testDB))
+}

message/cache_sqlite.go

@@ -9,6 +9,7 @@ import (
 
 	_ "github.com/mattn/go-sqlite3" // SQLite driver
 	"heckel.io/ntfy/v2/db"
+	"heckel.io/ntfy/v2/db/schema"
 	"heckel.io/ntfy/v2/util"
 )
 
@@ -113,7 +114,10 @@ func NewSQLiteStore(filename, startupQueries string, cacheDuration time.Duration
 	if err != nil {
 		return nil, err
 	}
-	if err := setupSQLite(d, startupQueries, cacheDuration); err != nil {
+	if err := runSQLiteStartupQueries(d, startupQueries); err != nil {
+		return nil, err
+	}
+	if err := schema.Migrate(d, schema.SQLite, schemaStore, sqliteCurrentSchemaVersion, sqliteCreateTables, sqliteMigrations(cacheDuration)); err != nil {
 		return nil, err
 	}
 	return newCache(db.New(&db.Host{DB: d}, nil), sqliteQueries, &sync.Mutex{}, batchSize, batchTimeout, nop), nil

message/cache_sqlite_schema.go

@@ -2,16 +2,15 @@ package message
 
 import (
 	"database/sql"
-	"fmt"
 	"time"
 
-	"heckel.io/ntfy/v2/db"
-	"heckel.io/ntfy/v2/log"
+	"heckel.io/ntfy/v2/db/schema"
 )
 
 // Initial SQLite schema
 const (
-	sqliteCreateTablesQuery = `
+	sqliteCurrentSchemaVersion = 15
+	sqliteCreateTablesQuery    = `
 		CREATE TABLE IF NOT EXISTS messages (
 			id INTEGER PRIMARY KEY AUTOINCREMENT,
 			mid TEXT NOT NULL,
@@ -55,29 +54,9 @@ const (
 	`
 )
 
-// Schema version management for SQLite
+// Schema migrations for SQLite. Databases older than schema version 1 (ntfy < v1.10.0,
+// November 2021) can no longer be migrated.
 const (
-	sqliteCurrentSchemaVersion          = 15
-	sqliteCreateSchemaVersionTableQuery = `
-		CREATE TABLE IF NOT EXISTS schemaVersion (
-			id INT PRIMARY KEY,
-			version INT NOT NULL
-		);
-	`
-	sqliteInsertSchemaVersionQuery = `INSERT INTO schemaVersion VALUES (1, ?)`
-	sqliteUpdateSchemaVersionQuery = `UPDATE schemaVersion SET version = ? WHERE id = 1`
-	sqliteSelectSchemaVersionQuery = `SELECT version FROM schemaVersion WHERE id = 1`
-)
-
-// Schema migrations for SQLite
-const (
-	// 0 -> 1
-	sqliteMigrate0To1AlterMessagesTableQuery = `
-		ALTER TABLE messages ADD COLUMN title TEXT NOT NULL DEFAULT('');
-		ALTER TABLE messages ADD COLUMN priority INT NOT NULL DEFAULT(0);
-		ALTER TABLE messages ADD COLUMN tags TEXT NOT NULL DEFAULT('');
-	`
-
 	// 1 -> 2
 	sqliteMigrate1To2AlterMessagesTableQuery = `
 		ALTER TABLE messages ADD COLUMN published INT NOT NULL DEFAULT(1);
@@ -193,67 +172,35 @@ const (
 )
 
 var (
-	sqliteMigrations = map[int]func(db *sql.DB, cacheDuration time.Duration) error{
-		0:  sqliteMigrateFrom0,
-		1:  sqliteMigrateFrom1,
-		2:  sqliteMigrateFrom2,
-		3:  sqliteMigrateFrom3,
-		4:  sqliteMigrateFrom4,
-		5:  sqliteMigrateFrom5,
-		6:  sqliteMigrateFrom6,
-		7:  sqliteMigrateFrom7,
-		8:  sqliteMigrateFrom8,
-		9:  sqliteMigrateFrom9,
-		10: sqliteMigrateFrom10,
-		11: sqliteMigrateFrom11,
-		12: sqliteMigrateFrom12,
-		13: sqliteMigrateFrom13,
-		14: sqliteMigrateFrom14,
-	}
+	sqliteCreateTables = schema.AsMigrateFunc(sqliteCreateTablesQuery)
 )
 
-func setupSQLite(db *sql.DB, startupQueries string, cacheDuration time.Duration) error {
-	if err := runSQLiteStartupQueries(db, startupQueries); err != nil {
-		return err
-	}
-	// If 'messages' table does not exist, this must be a new database
-	var messagesCount int
-	if err := db.QueryRow(sqliteSelectMessagesCountQuery).Scan(&messagesCount); err != nil {
-		return setupNewSQLite(db)
-	}
-	// If 'messages' table exists (schema >= 0), check 'schemaVersion' table
-	var schemaVersion int
-	db.QueryRow(sqliteSelectSchemaVersionQuery).Scan(&schemaVersion) // Error means schema version is zero!
-	// Do migrations
-	if schemaVersion == sqliteCurrentSchemaVersion {
-		return nil
-	} else if schemaVersion > sqliteCurrentSchemaVersion {
-		return fmt.Errorf("unexpected schema version: version %d is higher than current version %d", schemaVersion, sqliteCurrentSchemaVersion)
-	}
-	for i := schemaVersion; i < sqliteCurrentSchemaVersion; i++ {
-		fn, ok := sqliteMigrations[i]
-		if !ok {
-			return fmt.Errorf("cannot find migration step from schema version %d to %d", i, i+1)
-		} else if err := fn(db, cacheDuration); err != nil {
+// sqliteMigrations returns the migration steps, keyed by the version they upgrade FROM. The
+// cache duration is carried into the 9 -> 10 step via closure (it backfills "expires" from it).
+// Always append migrations at the end, never insert in the middle.
+func sqliteMigrations(cacheDuration time.Duration) map[int]schema.MigrateFunc {
+	return map[int]schema.MigrateFunc{
+		1: schema.AsMigrateFunc(sqliteMigrate1To2AlterMessagesTableQuery),
+		2: schema.AsMigrateFunc(sqliteMigrate2To3AlterMessagesTableQuery),
+		3: schema.AsMigrateFunc(sqliteMigrate3To4AlterMessagesTableQuery),
+		4: schema.AsMigrateFunc(sqliteMigrate4To5AlterMessagesTableQuery),
+		5: schema.AsMigrateFunc(sqliteMigrate5To6AlterMessagesTableQuery),
+		6: schema.AsMigrateFunc(sqliteMigrate6To7AlterMessagesTableQuery),
+		7: schema.AsMigrateFunc(sqliteMigrate7To8AlterMessagesTableQuery),
+		8: schema.AsMigrateFunc(sqliteMigrate8To9AlterMessagesTableQuery),
+		9: func(tx *sql.Tx) error {
+			if _, err := tx.Exec(sqliteMigrate9To10AlterMessagesTableQuery); err != nil {
+				return err
+			}
+			_, err := tx.Exec(sqliteMigrate9To10UpdateMessageExpiryQuery, int64(cacheDuration.Seconds()))
 			return err
-		}
+		},
+		10: schema.AsMigrateFunc(sqliteMigrate10To11AlterMessagesTableQuery),
+		11: schema.AsMigrateFunc(sqliteMigrate11To12AlterMessagesTableQuery),
+		12: schema.AsMigrateFunc(sqliteMigrate12To13AlterMessagesTableQuery),
+		13: schema.AsMigrateFunc(sqliteMigrate13To14AlterMessagesTableQuery),
+		14: schema.NopMigrateFunc, // Corresponds to Postgres migration
 	}
-	return nil
-}
-
-func setupNewSQLite(sqlDB *sql.DB) error {
-	return db.ExecTx(sqlDB, func(tx *sql.Tx) error {
-		if _, err := tx.Exec(sqliteCreateTablesQuery); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(sqliteCreateSchemaVersionTableQuery); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(sqliteInsertSchemaVersionQuery, sqliteCurrentSchemaVersion); err != nil {
-			return err
-		}
-		return nil
-	})
 }
 
 func runSQLiteStartupQueries(db *sql.DB, startupQueries string) error {
@@ -264,203 +211,3 @@ func runSQLiteStartupQueries(db *sql.DB, startupQueries string) error {
 	}
 	return nil
 }
-
-func sqliteMigrateFrom0(sqlDB *sql.DB, _ time.Duration) error {
-	log.Tag(tagMessageCache).Info("Migrating cache database schema: from 0 to 1")
-	return db.ExecTx(sqlDB, func(tx *sql.Tx) error {
-		if _, err := tx.Exec(sqliteMigrate0To1AlterMessagesTableQuery); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(sqliteCreateSchemaVersionTableQuery); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(sqliteInsertSchemaVersionQuery, 1); err != nil {
-			return err
-		}
-		return nil
-	})
-}
-
-func sqliteMigrateFrom1(sqlDB *sql.DB, _ time.Duration) error {
-	log.Tag(tagMessageCache).Info("Migrating cache database schema: from 1 to 2")
-	return db.ExecTx(sqlDB, func(tx *sql.Tx) error {
-		if _, err := tx.Exec(sqliteMigrate1To2AlterMessagesTableQuery); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(sqliteUpdateSchemaVersionQuery, 2); err != nil {
-			return err
-		}
-		return nil
-	})
-}
-
-func sqliteMigrateFrom2(sqlDB *sql.DB, _ time.Duration) error {
-	log.Tag(tagMessageCache).Info("Migrating cache database schema: from 2 to 3")
-	return db.ExecTx(sqlDB, func(tx *sql.Tx) error {
-		if _, err := tx.Exec(sqliteMigrate2To3AlterMessagesTableQuery); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(sqliteUpdateSchemaVersionQuery, 3); err != nil {
-			return err
-		}
-		return nil
-	})
-}
-
-func sqliteMigrateFrom3(sqlDB *sql.DB, _ time.Duration) error {
-	log.Tag(tagMessageCache).Info("Migrating cache database schema: from 3 to 4")
-	return db.ExecTx(sqlDB, func(tx *sql.Tx) error {
-		if _, err := tx.Exec(sqliteMigrate3To4AlterMessagesTableQuery); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(sqliteUpdateSchemaVersionQuery, 4); err != nil {
-			return err
-		}
-		return nil
-	})
-}
-
-func sqliteMigrateFrom4(sqlDB *sql.DB, _ time.Duration) error {
-	log.Tag(tagMessageCache).Info("Migrating cache database schema: from 4 to 5")
-	return db.ExecTx(sqlDB, func(tx *sql.Tx) error {
-		if _, err := tx.Exec(sqliteMigrate4To5AlterMessagesTableQuery); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(sqliteUpdateSchemaVersionQuery, 5); err != nil {
-			return err
-		}
-		return nil
-	})
-}
-
-func sqliteMigrateFrom5(sqlDB *sql.DB, _ time.Duration) error {
-	log.Tag(tagMessageCache).Info("Migrating cache database schema: from 5 to 6")
-	return db.ExecTx(sqlDB, func(tx *sql.Tx) error {
-		if _, err := tx.Exec(sqliteMigrate5To6AlterMessagesTableQuery); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(sqliteUpdateSchemaVersionQuery, 6); err != nil {
-			return err
-		}
-		return nil
-	})
-}
-
-func sqliteMigrateFrom6(sqlDB *sql.DB, _ time.Duration) error {
-	log.Tag(tagMessageCache).Info("Migrating cache database schema: from 6 to 7")
-	return db.ExecTx(sqlDB, func(tx *sql.Tx) error {
-		if _, err := tx.Exec(sqliteMigrate6To7AlterMessagesTableQuery); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(sqliteUpdateSchemaVersionQuery, 7); err != nil {
-			return err
-		}
-		return nil
-	})
-}
-
-func sqliteMigrateFrom7(sqlDB *sql.DB, _ time.Duration) error {
-	log.Tag(tagMessageCache).Info("Migrating cache database schema: from 7 to 8")
-	return db.ExecTx(sqlDB, func(tx *sql.Tx) error {
-		if _, err := tx.Exec(sqliteMigrate7To8AlterMessagesTableQuery); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(sqliteUpdateSchemaVersionQuery, 8); err != nil {
-			return err
-		}
-		return nil
-	})
-}
-
-func sqliteMigrateFrom8(sqlDB *sql.DB, _ time.Duration) error {
-	log.Tag(tagMessageCache).Info("Migrating cache database schema: from 8 to 9")
-	return db.ExecTx(sqlDB, func(tx *sql.Tx) error {
-		if _, err := tx.Exec(sqliteMigrate8To9AlterMessagesTableQuery); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(sqliteUpdateSchemaVersionQuery, 9); err != nil {
-			return err
-		}
-		return nil
-	})
-}
-
-func sqliteMigrateFrom9(sqlDB *sql.DB, cacheDuration time.Duration) error {
-	log.Tag(tagMessageCache).Info("Migrating cache database schema: from 9 to 10")
-	return db.ExecTx(sqlDB, func(tx *sql.Tx) error {
-		if _, err := tx.Exec(sqliteMigrate9To10AlterMessagesTableQuery); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(sqliteMigrate9To10UpdateMessageExpiryQuery, int64(cacheDuration.Seconds())); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(sqliteUpdateSchemaVersionQuery, 10); err != nil {
-			return err
-		}
-		return nil
-	})
-}
-
-func sqliteMigrateFrom10(sqlDB *sql.DB, _ time.Duration) error {
-	log.Tag(tagMessageCache).Info("Migrating cache database schema: from 10 to 11")
-	return db.ExecTx(sqlDB, func(tx *sql.Tx) error {
-		if _, err := tx.Exec(sqliteMigrate10To11AlterMessagesTableQuery); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(sqliteUpdateSchemaVersionQuery, 11); err != nil {
-			return err
-		}
-		return nil
-	})
-}
-
-func sqliteMigrateFrom11(sqlDB *sql.DB, _ time.Duration) error {
-	log.Tag(tagMessageCache).Info("Migrating cache database schema: from 11 to 12")
-	return db.ExecTx(sqlDB, func(tx *sql.Tx) error {
-		if _, err := tx.Exec(sqliteMigrate11To12AlterMessagesTableQuery); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(sqliteUpdateSchemaVersionQuery, 12); err != nil {
-			return err
-		}
-		return nil
-	})
-}
-
-func sqliteMigrateFrom12(sqlDB *sql.DB, _ time.Duration) error {
-	log.Tag(tagMessageCache).Info("Migrating cache database schema: from 12 to 13")
-	return db.ExecTx(sqlDB, func(tx *sql.Tx) error {
-		if _, err := tx.Exec(sqliteMigrate12To13AlterMessagesTableQuery); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(sqliteUpdateSchemaVersionQuery, 13); err != nil {
-			return err
-		}
-		return nil
-	})
-}
-
-func sqliteMigrateFrom13(sqlDB *sql.DB, _ time.Duration) error {
-	log.Tag(tagMessageCache).Info("Migrating cache database schema: from 13 to 14")
-	return db.ExecTx(sqlDB, func(tx *sql.Tx) error {
-		if _, err := tx.Exec(sqliteMigrate13To14AlterMessagesTableQuery); err != nil {
-			return err
-		}
-		if _, err := tx.Exec(sqliteUpdateSchemaVersionQuery, 14); err != nil {
-			return err
-		}
-		return nil
-	})
-}
-
-// sqliteMigrateFrom14 is a no-op; the corresponding Postgres migration adds
-// idx_message_attachment_expires, which SQLite already has from the initial schema.
-func sqliteMigrateFrom14(sqlDB *sql.DB, _ time.Duration) error {
-	log.Tag(tagMessageCache).Info("Migrating cache database schema: from 14 to 15")
-	return db.ExecTx(sqlDB, func(tx *sql.Tx) error {
-		if _, err := tx.Exec(sqliteUpdateSchemaVersionQuery, 15); err != nil {
-			return err
-		}
-		return nil
-	})
-}

message/cache_sqlite_test.go

@@ -9,50 +9,11 @@ import (
 
 	_ "github.com/mattn/go-sqlite3" // SQLite driver
 	"github.com/stretchr/testify/require"
+	dbtest "heckel.io/ntfy/v2/db/test"
 	"heckel.io/ntfy/v2/message"
 	"heckel.io/ntfy/v2/model"
 )
 
-func TestSqliteStore_Migration_From0(t *testing.T) {
-	filename := newSqliteTestStoreFile(t)
-	db, err := sql.Open("sqlite3", filename)
-	require.Nil(t, err)
-
-	// Create "version 0" schema
-	_, err = db.Exec(`
-		BEGIN;
-		CREATE TABLE IF NOT EXISTS messages (
-			id VARCHAR(20) PRIMARY KEY,
-			time INT NOT NULL,
-			topic VARCHAR(64) NOT NULL,
-			message VARCHAR(1024) NOT NULL
-		);
-		CREATE INDEX IF NOT EXISTS idx_topic ON messages (topic);
-		COMMIT;
-	`)
-	require.Nil(t, err)
-
-	// Insert a bunch of messages
-	for i := 0; i < 10; i++ {
-		_, err = db.Exec(`INSERT INTO messages (id, time, topic, message) VALUES (?, ?, ?, ?)`,
-			fmt.Sprintf("abcd%d", i), time.Now().Unix(), "mytopic", fmt.Sprintf("some message %d", i))
-		require.Nil(t, err)
-	}
-	require.Nil(t, db.Close())
-
-	// Create store to trigger migration
-	s := newSqliteTestStoreFromFile(t, filename, "")
-	checkSqliteSchemaVersion(t, filename)
-
-	messages, err := s.Messages("mytopic", model.SinceAllMessages, false)
-	require.Nil(t, err)
-	require.Equal(t, 10, len(messages))
-	require.Equal(t, "some message 5", messages[5].Message)
-	require.Equal(t, "", messages[5].Title)
-	require.Nil(t, messages[5].Tags)
-	require.Equal(t, 0, messages[5].Priority)
-}
-
 func TestSqliteStore_Migration_From1(t *testing.T) {
 	filename := newSqliteTestStoreFile(t)
 	db, err := sql.Open("sqlite3", filename)
@@ -90,6 +51,19 @@ func TestSqliteStore_Migration_From1(t *testing.T) {
 	s := newSqliteTestStoreFromFile(t, filename, "")
 	checkSqliteSchemaVersion(t, filename)
 
+	// The migrated database must be structurally identical to a freshly created one
+	freshFile := newSqliteTestStoreFile(t)
+	fresh, err := message.NewSQLiteStore(freshFile, "", time.Hour, 0, 0, false)
+	require.Nil(t, err)
+	t.Cleanup(func() { fresh.Close() })
+	freshDB, err := sql.Open("sqlite3", freshFile)
+	require.Nil(t, err)
+	defer freshDB.Close()
+	migratedDB, err := sql.Open("sqlite3", filename)
+	require.Nil(t, err)
+	defer migratedDB.Close()
+	require.Equal(t, dbtest.SQLiteSchema(t, freshDB), dbtest.SQLiteSchema(t, migratedDB))
+
 	// Add delayed message
 	delayedMessage := model.NewDefaultMessage("mytopic", "some delayed message")
 	delayedMessage.Time = time.Now().Add(time.Minute).Unix()

message/cache_test.go

@@ -1,6 +1,7 @@
 package message_test
 
 import (
+	"fmt"
 	"net/netip"
 	"path/filepath"
 	"sync"
@@ -556,6 +557,43 @@ func TestStore_MarkPublished(t *testing.T) {
 	})
 }
 
+func TestStore_MessagesDue_ClaimExactlyOnce(t *testing.T) {
+	// Postgres-only: exercises "FOR UPDATE SKIP LOCKED" claiming so that concurrent delayed
+	// senders running on different cluster nodes never pick up (and deliver) the same due
+	// message twice. With the non-claiming implementation, every concurrent caller sees every
+	// due row, so this test fails; with claiming, each row is returned to exactly one caller.
+	s := newTestPostgresStore(t) // skips if NTFY_TEST_DATABASE_URL is unset
+	const n = 40
+	for i := 0; i < n; i++ {
+		m := model.NewDefaultMessage("mytopic", fmt.Sprintf("scheduled %d", i))
+		m.Time = time.Now().Add(time.Hour).Unix() // future -> stored as published=FALSE
+		require.Nil(t, s.AddMessage(m))
+		// Move the time into the past so the message is due now (but still unpublished)
+		require.Nil(t, s.UpdateMessageTime(m.ID, time.Now().Add(-time.Minute).Unix()))
+	}
+	var mu sync.Mutex
+	seen := make(map[string]int)
+	var wg sync.WaitGroup
+	for c := 0; c < 6; c++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			due, err := s.MessagesDue()
+			require.Nil(t, err)
+			mu.Lock()
+			defer mu.Unlock()
+			for _, m := range due {
+				seen[m.ID]++
+			}
+		}()
+	}
+	wg.Wait()
+	require.Len(t, seen, n) // every due message was claimed
+	for id, count := range seen {
+		require.Equalf(t, 1, count, "message %s was claimed %d times, want exactly 1", id, count)
+	}
+}
+
 func TestStore_ExpireMessages(t *testing.T) {
 	forEachBackend(t, func(t *testing.T, s *message.Cache) {
 		// Add messages to two topics

metrics/metrics.go

@@ -0,0 +1,143 @@
+// Package metrics defines the Prometheus metrics exposed by the ntfy server, and registers them
+// with the default Prometheus registry on import. It is decoupled from the ntfy server, so that
+// call sites can update metrics without depending on the server package.
+package metrics
+
+import (
+	"github.com/prometheus/client_golang/prometheus"
+)
+
+// Collectors for all metrics exposed by the server.
+//
+// These are never nil, so that call sites can update them unconditionally. If metrics are
+// disabled, the server never mounts the /metrics handler, and the values are simply never read.
+var (
+	MessagesPublishedSuccess = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_messages_published_success",
+	})
+	MessagesPublishedFailure = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_messages_published_failure",
+	})
+	MessagesCached = prometheus.NewGauge(prometheus.GaugeOpts{
+		Name: "ntfy_messages_cached_total",
+	})
+	MessagePublishDurationMillis = prometheus.NewGauge(prometheus.GaugeOpts{
+		Name: "ntfy_message_publish_duration_ms",
+	})
+	FirebasePublishedSuccess = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_firebase_published_success",
+	})
+	FirebasePublishedFailure = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_firebase_published_failure",
+	})
+	EmailsPublishedSuccess = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_emails_sent_success",
+	})
+	EmailsPublishedFailure = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_emails_sent_failure",
+	})
+	EmailsReceivedSuccess = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_emails_received_success",
+	})
+	EmailsReceivedFailure = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_emails_received_failure",
+	})
+	CallsMadeSuccess = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_calls_made_success",
+	})
+	CallsMadeFailure = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_calls_made_failure",
+	})
+	UnifiedPushPublishedSuccess = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_unifiedpush_published_success",
+	})
+	MatrixPublishedSuccess = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_matrix_published_success",
+	})
+	MatrixPublishedFailure = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_matrix_published_failure",
+	})
+	AttachmentsTotalSize = prometheus.NewGauge(prometheus.GaugeOpts{
+		Name: "ntfy_attachments_total_size",
+	})
+	Visitors = prometheus.NewGauge(prometheus.GaugeOpts{
+		Name: "ntfy_visitors_total",
+	})
+	Users = prometheus.NewGauge(prometheus.GaugeOpts{
+		Name: "ntfy_users_total",
+	})
+	Subscribers = prometheus.NewGauge(prometheus.GaugeOpts{
+		Name: "ntfy_subscribers_total",
+	})
+	Topics = prometheus.NewGauge(prometheus.GaugeOpts{
+		Name: "ntfy_topics_total",
+	})
+	HTTPRequests = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "ntfy_http_requests_total",
+	}, []string{"http_code", "ntfy_code", "http_method"})
+	ClusterPeers = prometheus.NewGauge(prometheus.GaugeOpts{
+		Name: "ntfy_cluster_peers",
+	})
+	ClusterMessagesForwarded = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_cluster_messages_forwarded_total",
+	})
+	ClusterSendErrors = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_cluster_send_errors_total",
+	})
+	ClusterQueueDropped = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_cluster_queue_dropped_total",
+	})
+	ClusterBatchesSent = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_cluster_batches_sent_total",
+	})
+	ClusterMessagesWasted = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_cluster_messages_wasted_total",
+	})
+	ClusterRouteSkipped = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_cluster_route_skipped_total",
+	})
+	ClusterStatePushes = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "ntfy_cluster_state_pushes_total",
+	})
+	ClusterLeader = prometheus.NewGauge(prometheus.GaugeOpts{
+		Name: "ntfy_cluster_leader",
+	})
+)
+
+// init registers all collectors with the default Prometheus registry. Registration is
+// unconditional: the collectors are only ever exposed if the server mounts the /metrics handler,
+// so there is nothing to be gained by tying registration to the config.
+func init() {
+	prometheus.MustRegister(
+		MessagesPublishedSuccess,
+		MessagesPublishedFailure,
+		MessagesCached,
+		MessagePublishDurationMillis,
+		FirebasePublishedSuccess,
+		FirebasePublishedFailure,
+		EmailsPublishedSuccess,
+		EmailsPublishedFailure,
+		EmailsReceivedSuccess,
+		EmailsReceivedFailure,
+		CallsMadeSuccess,
+		CallsMadeFailure,
+		UnifiedPushPublishedSuccess,
+		MatrixPublishedSuccess,
+		MatrixPublishedFailure,
+		AttachmentsTotalSize,
+		Visitors,
+		Users,
+		Subscribers,
+		Topics,
+		HTTPRequests,
+		ClusterPeers,
+		ClusterMessagesForwarded,
+		ClusterSendErrors,
+		ClusterQueueDropped,
+		ClusterBatchesSent,
+		ClusterMessagesWasted,
+		ClusterRouteSkipped,
+		ClusterStatePushes,
+		ClusterLeader,
+	)
+}

metrics/metrics_test.go

@@ -0,0 +1,67 @@
+package metrics
+
+import (
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/stretchr/testify/require"
+)
+
+// expectedMetricNames is the exact set of metrics the server exposes. These names are a public
+// contract: renaming or dropping one silently breaks existing dashboards and alerts.
+var expectedMetricNames = []string{
+	"ntfy_attachments_total_size",
+	"ntfy_calls_made_failure",
+	"ntfy_calls_made_success",
+	"ntfy_cluster_batches_sent_total",
+	"ntfy_cluster_leader",
+	"ntfy_cluster_messages_forwarded_total",
+	"ntfy_cluster_messages_wasted_total",
+	"ntfy_cluster_peers",
+	"ntfy_cluster_queue_dropped_total",
+	"ntfy_cluster_route_skipped_total",
+	"ntfy_cluster_send_errors_total",
+	"ntfy_cluster_state_pushes_total",
+	"ntfy_emails_received_failure",
+	"ntfy_emails_received_success",
+	"ntfy_emails_sent_failure",
+	"ntfy_emails_sent_success",
+	"ntfy_firebase_published_failure",
+	"ntfy_firebase_published_success",
+	"ntfy_http_requests_total",
+	"ntfy_matrix_published_failure",
+	"ntfy_matrix_published_success",
+	"ntfy_message_publish_duration_ms",
+	"ntfy_messages_cached_total",
+	"ntfy_messages_published_failure",
+	"ntfy_messages_published_success",
+	"ntfy_subscribers_total",
+	"ntfy_topics_total",
+	"ntfy_unifiedpush_published_success",
+	"ntfy_users_total",
+	"ntfy_visitors_total",
+}
+
+func TestRegisteredMetricNames(t *testing.T) {
+	HTTPRequests.WithLabelValues("200", "20000", "GET").Inc()
+	families, err := prometheus.DefaultGatherer.Gather()
+	require.Nil(t, err)
+	names := make([]string, 0)
+	for _, family := range families {
+		if strings.HasPrefix(family.GetName(), "ntfy_") {
+			names = append(names, family.GetName())
+		}
+	}
+	sort.Strings(names)
+	require.Equal(t, expectedMetricNames, names)
+}
+
+func TestCollectors_NeverNil(t *testing.T) {
+	// Call sites update metrics unconditionally, even when metrics are disabled, so no collector
+	// may ever be nil
+	MessagesPublishedSuccess.Inc()
+	MessagesCached.Set(1)
+	HTTPRequests.WithLabelValues("200", "20000", "PUT").Inc()
+}

s3/client_test.go

@@ -22,6 +22,7 @@ func TestParseURL_Success(t *testing.T) {
 	require.Equal(t, "us-east-1", cfg.Region)
 	require.Equal(t, "AKID", cfg.AccessKey)
 	require.Equal(t, "SECRET", cfg.SecretKey)
+	require.Equal(t, "https", cfg.Scheme)
 	require.Equal(t, "s3.us-east-1.amazonaws.com", cfg.Endpoint)
 	require.False(t, cfg.PathStyle)
 }
@@ -38,6 +39,7 @@ func TestParseURL_WithEndpoint(t *testing.T) {
 	require.Nil(t, err)
 	require.Equal(t, "my-bucket", cfg.Bucket)
 	require.Equal(t, "prefix", cfg.Prefix)
+	require.Equal(t, "https", cfg.Scheme)
 	require.Equal(t, "s3.example.com", cfg.Endpoint)
 	require.True(t, cfg.PathStyle)
 }
@@ -45,10 +47,32 @@ func TestParseURL_WithEndpoint(t *testing.T) {
 func TestParseURL_EndpointHTTP(t *testing.T) {
 	cfg, err := ParseURL("s3://AKID:SECRET@my-bucket?region=us-east-1&endpoint=http://localhost:9000")
 	require.Nil(t, err)
+	require.Equal(t, "http", cfg.Scheme)
 	require.Equal(t, "localhost:9000", cfg.Endpoint)
 	require.True(t, cfg.PathStyle)
 }
 
+func TestParseURL_EndpointNoScheme(t *testing.T) {
+	// A bare host:port endpoint (no scheme) must default to https for backward compatibility.
+	// Without this, url.Parse treats the host as the scheme ("localhost:9000" -> scheme "localhost").
+	cfg, err := ParseURL("s3://AKID:SECRET@my-bucket?region=us-east-1&endpoint=localhost:9000")
+	require.Nil(t, err)
+	require.Equal(t, "https", cfg.Scheme)
+	require.Equal(t, "localhost:9000", cfg.Endpoint)
+	require.True(t, cfg.PathStyle)
+	require.Equal(t, "https://localhost:9000/my-bucket", cfg.BucketURL())
+}
+
+func TestParseURL_EndpointNoSchemeHostname(t *testing.T) {
+	// A dotted hostname with a port and no scheme must also default to https
+	// ("minio.example.com:9000" must not become scheme "minio.example.com").
+	cfg, err := ParseURL("s3://AKID:SECRET@my-bucket?region=us-east-1&endpoint=minio.example.com:9000")
+	require.Nil(t, err)
+	require.Equal(t, "https", cfg.Scheme)
+	require.Equal(t, "minio.example.com:9000", cfg.Endpoint)
+	require.Equal(t, "https://minio.example.com:9000/my-bucket", cfg.BucketURL())
+}
+
 func TestParseURL_EndpointTrailingSlash(t *testing.T) {
 	cfg, err := ParseURL("s3://AKID:SECRET@my-bucket?region=us-east-1&endpoint=https://s3.example.com/")
 	require.Nil(t, err)
@@ -111,6 +135,11 @@ func TestConfig_BucketURL_PathStyle(t *testing.T) {
 	require.Equal(t, "https://s3.example.com/my-bucket", c.BucketURL())
 }
 
+func TestConfig_BucketURL_PathStyle_EndpointHTTP(t *testing.T) {
+	c := &Config{Scheme: "http", Endpoint: "localhost:9000", Bucket: "b", PathStyle: true}
+	require.Equal(t, "http://localhost:9000/b", c.BucketURL())
+}
+
 func TestConfig_BucketURL_VirtualHosted(t *testing.T) {
 	c := &Config{Endpoint: "s3.us-east-1.amazonaws.com", Bucket: "my-bucket", PathStyle: false}
 	require.Equal(t, "https://my-bucket.s3.us-east-1.amazonaws.com", c.BucketURL())

s3/types.go

@@ -11,6 +11,7 @@ import (
 
 // Config holds the parsed fields from an S3 URL. Use ParseURL to create one from a URL string.
 type Config struct {
+	Scheme       string // URL scheme, e.g. "https" or "http"
 	Endpoint     string // host[:port] only, e.g. "s3.us-east-1.amazonaws.com"
 	PathStyle    bool
 	Bucket       string
@@ -24,10 +25,14 @@ type Config struct {
 
 // BucketURL returns the base URL for bucket-level operations.
 func (c *Config) BucketURL() string {
-	if c.PathStyle {
-		return fmt.Sprintf("https://%s/%s", c.Endpoint, c.Bucket)
+	scheme := "https"
+	if c.Scheme != "" {
+		scheme = c.Scheme
 	}
-	return fmt.Sprintf("https://%s.%s", c.Bucket, c.Endpoint)
+	if c.PathStyle {
+		return fmt.Sprintf("%s://%s/%s", scheme, c.Endpoint, c.Bucket)
+	}
+	return fmt.Sprintf("%s://%s.%s", scheme, c.Bucket, c.Endpoint)
 }
 
 // HostHeader returns the value for the Host header.

s3/util.go

@@ -70,21 +70,30 @@ func ParseURL(s3URL string) (*Config, error) {
 		return nil, fmt.Errorf("s3: region query parameter is required")
 	}
 	endpointParam := u.Query().Get("endpoint")
+	var scheme string
 	var endpoint string
 	var pathStyle bool
 	if endpointParam != "" {
-		// Custom endpoint: strip scheme prefix to extract host[:port]
+		// Custom endpoint: derive the scheme from the prefix and strip it to extract host[:port].
+		// Default to https for backward compatibility, including bare "host:port" endpoints (no
+		// scheme) -- url.Parse would otherwise misread the host before the port colon as the scheme.
+		scheme = "https"
+		if strings.HasPrefix(endpointParam, "http://") {
+			scheme = "http"
+		}
 		ep := strings.TrimRight(endpointParam, "/")
 		ep = strings.TrimPrefix(ep, "https://")
 		ep = strings.TrimPrefix(ep, "http://")
 		endpoint = ep
 		pathStyle = true
 	} else {
+		scheme = "https"
 		endpoint = fmt.Sprintf("s3.%s.amazonaws.com", region)
 		pathStyle = false
 	}
 	disableHTTP2, _ := strconv.ParseBool(u.Query().Get("disable_http2"))
 	return &Config{
+		Scheme:       scheme,
 		Endpoint:     endpoint,
 		PathStyle:    pathStyle,
 		Bucket:       bucket,

scripts/emoji-convert.sh

@@ -11,11 +11,20 @@ if [ -z "$1" ]; then
     echo "Example:"
     echo "  $0 emoji-converted.json"
     echo "  $0 $ROOTDIR/web/src/app/emojis.js"
+    echo "  $0 $ROOTDIR/web/src/app/emojisMapped.js"
     echo "  $0 $ROOTDIR/docs/emojis.md"
     exit 1
 fi
 
-if [[ "$1" == *.js ]]; then
+if [[ "$1" == *emojisMapped.js ]]; then
+  # Small alias -> emoji lookup used to render tags as emojis. Precomputed so the full
+  # emoji dataset (emojis.js) stays out of the main web bundle.
+  echo -n "// This file is generated by scripts/emoji-convert.sh -- alias to emoji lookup
+// Original data source: https://github.com/github/gemoji/blob/master/db/emoji.json
+export default " > "$1"
+    cat "$SCRIPTDIR/emoji.json" | jq -jc '[.[] | .aliases[] as $a | {key: $a, value: .emoji}] | from_entries' >> "$1"
+    echo ";" >> "$1"
+elif [[ "$1" == *.js ]]; then
   echo -n "// This file is generated by scripts/emoji-convert.sh to reduce the size
 // Original data source: https://github.com/github/gemoji/blob/master/db/emoji.json
 export const rawEmojis = " > "$1"

server/ban_test.go

@@ -0,0 +1,55 @@
+package server
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"heckel.io/ntfy/v2/ban"
+)
+
+// TestServer_BanFeed_WritesOffenderToFile is the end-to-end wiring test: a rejected request flows
+// through s.handle -> the error responder -> s.ban.Record, and once the offender's prefix
+// breaches, its ban line lands in the ban file (flushed on Close).
+func TestServer_BanFeed_WritesOffenderToFile(t *testing.T) {
+	banFile := filepath.Join(t.TempDir(), "ban.log")
+	conf := newTestConfig(t, "")
+	conf.BanFile = banFile
+	conf.BanWindow = time.Minute
+	conf.BanThreshold = 1                 // capacity 1: the 2nd rejection breaches
+	conf.BanWeights = ban.Weights{"*": 1} // any 4xx counts one strike
+	s := newTestServer(t, conf)
+	require.NotNil(t, s.ban)
+
+	// A delayed message with caching disabled is a deterministic 400 (errHTTPBadRequestDelayNoCache).
+	// request() sends from RemoteAddr 9.9.9.9.
+	reject := map[string]string{"Cache": "no", "In": "30 min"}
+	for i := 0; i < 3; i++ {
+		response := request(t, s, "PUT", "/mytopic", "", reject)
+		require.Equal(t, 400, response.Code)
+	}
+
+	// Writes are async; Close flushes the buffer. The offender's prefix must be in the feed exactly
+	// once (throttled to one line per window).
+	s.ban.Close()
+	data, err := os.ReadFile(banFile)
+	require.NoError(t, err)
+	lines := strings.Split(strings.TrimRight(string(data), "\n"), "\n")
+	require.Len(t, lines, 1)
+	require.Contains(t, lines[0], " 9.9.9.9 9.9.9.9/32 400 ") // <ip> <prefix> <http-code> <ntfy-code>
+}
+
+// TestServer_BanFeed_DisabledByDefault verifies the feature is off with no ban file: s.ban is
+// nil and the error path skips it (guarded), so a rejected request must not panic.
+func TestServer_BanFeed_DisabledByDefault(t *testing.T) {
+	conf := newTestConfig(t, "") // no BanFile
+	s := newTestServer(t, conf)
+	require.Nil(t, s.ban)
+
+	reject := map[string]string{"Cache": "no", "In": "30 min"}
+	response := request(t, s, "PUT", "/mytopic", "", reject) // guarded callsite, no Record
+	require.Equal(t, 400, response.Code)
+}

server/config.go

@@ -10,6 +10,9 @@ import (
 	"text/template"
 	"time"
 
+	"heckel.io/ntfy/v2/cluster"
+
+	"heckel.io/ntfy/v2/ban"
 	"heckel.io/ntfy/v2/user"
 )
 
@@ -42,6 +45,24 @@ const (
 	DefaultWebPushExpiryDuration        = 60 * 24 * time.Hour
 )
 
+// Defines default abuse ban-feed settings (see BanFile, BanWindow, BanThreshold, BanWeights)
+const (
+	DefaultBanWindow    = 10 * time.Minute
+	DefaultBanThreshold = 100 // Weighted strikes per BanWindow before a prefix is banned
+)
+
+// DefaultBanWeights is the ban-feed's default per-code strike weights: the auth-failure flood bans fast,
+// and everything else defaults to weight 1 (no "*" rule needed; see BanWeights.WeightFor).
+var DefaultBanWeights = []string{
+	banWeight(errHTTPTooManyRequestsLimitAuthFailure, 10), // brute-force auth flood -> ban fast
+}
+
+// banWeight formats a "CODE:WEIGHT" ban-feed default from an ntfy error, so the codes stay in sync with
+// the errHTTP definitions instead of being duplicated as string literals.
+func banWeight(err *errHTTP, weight int) string {
+	return fmt.Sprintf("%d:%d", err.Code, weight)
+}
+
 // Defines all global and per-visitor limits
 // - message size limit: the max number of bytes for a message
 // - total topic limit: max number of topics overall
@@ -100,8 +121,13 @@ type Config struct {
 	ListenUnixMode                       fs.FileMode
 	KeyFile                              string
 	CertFile                             string
-	DatabaseURL                          string   // PostgreSQL connection string (e.g. "postgres://user:pass@host:5432/ntfy")
-	DatabaseReplicaURLs                  []string // PostgreSQL read replica connection strings
+	DatabaseURL                          string        // PostgreSQL connection string (e.g. "postgres://user:pass@host:5432/ntfy")
+	DatabaseReplicaURLs                  []string      // PostgreSQL read replica connection strings
+	ClusterNodeID                        string        // Stable per-node identifier used to skip a node's own fan-out; required in cluster mode
+	ClusterListen                        string        // ip:port the dedicated cluster fan-out listener binds to (private network, e.g. "10.0.0.5:2587")
+	ClusterAdvertiseURL                  string        // Base URL peers use to reach this node's fan-out listener (defaults to "http://<cluster-listen>")
+	ClusterSecret                        string        `hash:"-"` // Shared secret authenticating node-to-node fan-out requests
+	ClusterBatchLinger                   time.Duration // How long fan-out messages wait to form a batch per peer; 0 sends immediately
 	FirebaseKeyFile                      string
 	CacheFile                            string
 	CacheDuration                        time.Duration
@@ -111,9 +137,9 @@ type Config struct {
 	AuthFile                             string
 	AuthStartupQueries                   string
 	AuthDefault                          user.Permission
-	AuthUsers                            []*user.User
+	AuthUsers                            []*user.User `hash:"-"`
 	AuthAccess                           map[string][]*user.Grant
-	AuthTokens                           map[string][]*user.Token
+	AuthTokens                           map[string][]*user.Token `hash:"-"`
 	AuthBcryptCost                       int
 	AuthStatsQueueWriterInterval         time.Duration
 	AuthAccessCacheEnabled               bool          // Enables the in-memory ACL cache (high volume servers only)
@@ -134,23 +160,22 @@ type Config struct {
 	FirebasePollInterval                 time.Duration
 	FirebaseQuotaExceededPenaltyDuration time.Duration
 	UpstreamBaseURL                      string
-	UpstreamAccessToken                  string
+	UpstreamAccessToken                  string `hash:"-"`
 	SMTPSenderAddr                       string
 	SMTPSenderUser                       string
-	SMTPSenderPass                       string
+	SMTPSenderPass                       string `hash:"-"`
 	SMTPSenderFrom                       string
 	SMTPSenderVerify                     bool
 	SMTPServerListen                     string
 	SMTPServerDomain                     string
 	SMTPServerAddrPrefix                 string
 	TwilioAccount                        string
-	TwilioAuthToken                      string
+	TwilioAuthToken                      string `hash:"-"`
 	TwilioPhoneNumber                    string
 	TwilioCallsBaseURL                   string
 	TwilioVerifyBaseURL                  string
 	TwilioVerifyService                  string
 	TwilioCallFormat                     *template.Template
-	MetricsEnable                        bool
 	MetricsListenHTTP                    string
 	ProfileListenHTTP                    string
 	MessageDelayMin                      time.Duration
@@ -180,8 +205,8 @@ type Config struct {
 	BehindProxy                          bool           // If true, the server will trust the proxy client IP header to determine the client IP address (IPv4 and IPv6 supported)
 	ProxyForwardedHeader                 string         // The header field to read the real/client IP address from, if BehindProxy is true, defaults to "X-Forwarded-For" (IPv4 and IPv6 supported)
 	ProxyTrustedPrefixes                 []netip.Prefix // List of trusted proxy networks (IPv4 or IPv6) that will be stripped from the Forwarded header if BehindProxy is true
-	StripeSecretKey                      string
-	StripeWebhookKey                     string
+	StripeSecretKey                      string         `hash:"-"`
+	StripeWebhookKey                     string         `hash:"-"`
 	StripePriceCacheDuration             time.Duration
 	BillingContact                       string
 	EnableSignup                         bool // Enable creation of accounts via API and UI
@@ -190,16 +215,20 @@ type Config struct {
 	EnableReservations                   bool // Allow users with role "user" to own/reserve topics
 	EnableMetrics                        bool
 	AccessControlAllowOrigin             string // CORS header field to restrict access from web clients
-	WebPushPrivateKey                    string
+	WebPushPrivateKey                    string `hash:"-"`
 	WebPushPublicKey                     string
 	WebPushFile                          string
 	WebPushEmailAddress                  string
 	WebPushStartupQueries                string
 	WebPushExpiryDuration                time.Duration
 	WebPushExpiryWarningDuration         time.Duration
-	BuildVersion                         string // Injected by App
-	BuildDate                            string // Injected by App
-	BuildCommit                          string // Injected by App
+	BanFile                              string        // Abuse ban-feed: file that fail2ban tails; empty string disables the feature
+	BanWindow                            time.Duration // Abuse ban-feed: rolling window over which weighted strikes are counted
+	BanThreshold                         int           // Abuse ban-feed: weighted strikes per window before a prefix is banned
+	BanWeights                           ban.Weights   // Abuse ban-feed: code matcher -> strike weight (see ban.ParseWeights, ban.Weights.WeightFor)
+	BuildVersion                         string        // Injected by App
+	BuildDate                            string        // Injected by App
+	BuildCommit                          string        // Injected by App
 }
 
 // NewConfig instantiates a default new server config
@@ -214,6 +243,11 @@ func NewConfig() *Config {
 		KeyFile:                              "",
 		CertFile:                             "",
 		DatabaseURL:                          "",
+		ClusterNodeID:                        "",
+		ClusterListen:                        "",
+		ClusterAdvertiseURL:                  "",
+		ClusterSecret:                        "",
+		ClusterBatchLinger:                   cluster.DefaultBatchLinger,
 		FirebaseKeyFile:                      "",
 		CacheFile:                            "",
 		CacheDuration:                        DefaultCacheDuration,
@@ -300,6 +334,10 @@ func NewConfig() *Config {
 		WebPushEmailAddress:                  "",
 		WebPushExpiryDuration:                DefaultWebPushExpiryDuration,
 		WebPushExpiryWarningDuration:         DefaultWebPushExpiryWarningDuration,
+		BanFile:                              "",
+		BanWindow:                            DefaultBanWindow,
+		BanThreshold:                         DefaultBanThreshold,
+		BanWeights:                           nil,
 		BuildVersion:                         "",
 		BuildDate:                            "",
 		BuildCommit:                          "",
@@ -316,6 +354,10 @@ func (c *Config) Hash() string {
 	for i := 0; i < v.NumField(); i++ {
 		field := v.Field(i)
 		fieldName := t.Field(i).Name
+		// Secrets must not feed the hash
+		if t.Field(i).Tag.Get("hash") == "-" {
+			continue
+		}
 		// Try to marshal the field and skip if it fails (e.g. *template.Template, netip.Prefix)
 		if b, err := json.Marshal(field.Interface()); err == nil {
 			result += fmt.Sprintf("%s:%s|", fieldName, string(b))

server/config_test.go

@@ -3,6 +3,7 @@ package server_test
 import (
 	"github.com/stretchr/testify/assert"
 	"heckel.io/ntfy/v2/server"
+	"heckel.io/ntfy/v2/user"
 	"testing"
 )
 
@@ -11,3 +12,25 @@ func TestConfig_New(t *testing.T) {
 	assert.Equal(t, ":80", c.ListenHTTP)
 	assert.Equal(t, server.DefaultKeepaliveInterval, c.KeepaliveInterval)
 }
+
+func TestConfig_HashExcludesSecrets(t *testing.T) {
+	// The config hash is served to browsers (ConfigHash, for webapp change detection), so
+	// secret material must not feed it: a weak secret would otherwise be offline-brute-forceable
+	// against a publicly visible hash.
+	conf1 := server.NewConfig()
+	conf2 := server.NewConfig()
+	conf2.StripeSecretKey = "sk_live_topsecret"
+	conf2.StripeWebhookKey = "whsec_topsecret"
+	conf2.TwilioAuthToken = "twilio-auth-token"
+	conf2.UpstreamAccessToken = "tk_upstream"
+	conf2.WebPushPrivateKey = "web-push-private-key"
+	conf2.SMTPSenderPass = "hunter2"
+	conf2.ClusterSecret = "cluster-secret"
+	conf2.AuthUsers = []*user.User{{Name: "phil", Hash: "$2a$10$somebcrypthash"}}
+	conf2.AuthTokens = map[string][]*user.Token{"phil": {{Value: "tk_secrettoken"}}}
+	assert.Equal(t, conf1.Hash(), conf2.Hash())
+	// Non-secret fields must still change the hash
+	conf3 := server.NewConfig()
+	conf3.BaseURL = "https://ntfy.example.com"
+	assert.NotEqual(t, conf1.Hash(), conf3.Hash())
+}

server/errors.go

@@ -136,8 +136,9 @@ var (
 	errHTTPBadRequestTemplateMessageTooLarge         = &errHTTP{40041, http.StatusBadRequest, "invalid request: message or title is too large after replacing template", "https://ntfy.sh/docs/publish/#message-templating", nil}
 	errHTTPBadRequestTemplateMessageNotJSON          = &errHTTP{40042, http.StatusBadRequest, "invalid request: message body must be JSON if templating is enabled", "https://ntfy.sh/docs/publish/#message-templating", nil}
 	errHTTPBadRequestTemplateInvalid                 = &errHTTP{40043, http.StatusBadRequest, "invalid request: could not parse template", "https://ntfy.sh/docs/publish/#message-templating", nil}
-	errHTTPBadRequestTemplateDisallowedFunctionCalls = &errHTTP{40044, http.StatusBadRequest, "invalid request: template contains disallowed function calls, e.g. template, call, or define", "https://ntfy.sh/docs/publish/#message-templating", nil}
+	errHTTPBadRequestTemplateDisallowedFunctionCalls = &errHTTP{40044, http.StatusBadRequest, "invalid request: template contains disallowed function calls, e.g. template, call, define, or block", "https://ntfy.sh/docs/publish/#message-templating", nil}
 	errHTTPBadRequestTemplateExecuteFailed           = &errHTTP{40045, http.StatusBadRequest, "invalid request: template execution failed", "https://ntfy.sh/docs/publish/#message-templating", nil}
+	errHTTPBadRequestTemplateExecutionTimeout        = &errHTTP{40055, http.StatusBadRequest, "invalid request: template execution timed out", "https://ntfy.sh/docs/publish/#message-templating", nil}
 	errHTTPBadRequestInvalidUsername                 = &errHTTP{40046, http.StatusBadRequest, "invalid request: invalid username", "", nil}
 	errHTTPBadRequestTemplateFileNotFound            = &errHTTP{40047, http.StatusBadRequest, "invalid request: template file not found", "https://ntfy.sh/docs/publish/#message-templating", nil}
 	errHTTPBadRequestTemplateFileInvalid             = &errHTTP{40048, http.StatusBadRequest, "invalid request: template file invalid", "https://ntfy.sh/docs/publish/#message-templating", nil}
@@ -147,6 +148,7 @@ var (
 	errHTTPBadRequestEmailAddressNotVerified         = &errHTTP{40052, http.StatusBadRequest, "invalid request: email address not verified", "https://ntfy.sh/docs/publish/#e-mail-notifications", nil}
 	errHTTPBadRequestAnonymousEmailNotAllowed        = &errHTTP{40053, http.StatusBadRequest, "invalid request: anonymous email sending is not allowed", "https://ntfy.sh/docs/publish/#e-mail-notifications", nil}
 	errHTTPBadRequestResetLinkInvalid                = &errHTTP{40054, http.StatusBadRequest, "invalid request: password reset link invalid or expired", "", nil}
+	errHTTPBadRequestTemplateTooLarge                = &errHTTP{40056, http.StatusBadRequest, "invalid request: template too large", "https://ntfy.sh/docs/publish/#message-templating", nil}
 	errHTTPNotFound                                  = &errHTTP{40401, http.StatusNotFound, "page not found", "", nil}
 	errHTTPUnauthorized                              = &errHTTP{40101, http.StatusUnauthorized, "unauthorized", "https://ntfy.sh/docs/publish/#authentication", nil}
 	errHTTPForbidden                                 = &errHTTP{40301, http.StatusForbidden, "forbidden", "https://ntfy.sh/docs/publish/#authentication", nil}

server/log.go

@@ -16,22 +16,21 @@ import (
 
 // Log tags
 const (
-	tagStartup      = "startup"
-	tagHTTP         = "http"
-	tagPublish      = "publish"
-	tagSubscribe    = "subscribe"
-	tagFirebase     = "firebase"
-	tagSMTP         = "smtp"  // Receive email
-	tagEmail        = "email" // Send email
-	tagTwilio       = "twilio"
-	tagMessageCache = "message_cache"
-	tagStripe       = "stripe"
-	tagAccount      = "account"
-	tagManager      = "manager"
-	tagResetter     = "resetter"
-	tagWebsocket    = "websocket"
-	tagMatrix       = "matrix"
-	tagWebPush      = "webpush"
+	tagStartup   = "startup"
+	tagHTTP      = "http"
+	tagPublish   = "publish"
+	tagSubscribe = "subscribe"
+	tagFirebase  = "firebase"
+	tagSMTP      = "smtp"  // Receive email
+	tagEmail     = "email" // Send email
+	tagTwilio    = "twilio"
+	tagStripe    = "stripe"
+	tagAccount   = "account"
+	tagManager   = "manager"
+	tagResetter  = "resetter"
+	tagWebsocket = "websocket"
+	tagMatrix    = "matrix"
+	tagWebPush   = "webpush"
 )
 
 var (

server/server.go

@@ -17,13 +17,11 @@ import (
 	"net/url"
 	"os"
 	"path"
-	"path/filepath"
 	"regexp"
 	"sort"
 	"strconv"
 	"strings"
 	"sync"
-	"text/template"
 	"time"
 	"unicode/utf8"
 
@@ -31,18 +29,21 @@ import (
 	"github.com/gorilla/websocket"
 	"github.com/prometheus/client_golang/prometheus/promhttp"
 	"golang.org/x/sync/errgroup"
-	"gopkg.in/yaml.v2"
+	"heckel.io/ntfy/v2/action"
 	"heckel.io/ntfy/v2/attachment"
+	"heckel.io/ntfy/v2/ban"
+	"heckel.io/ntfy/v2/cluster"
 	"heckel.io/ntfy/v2/db"
 	"heckel.io/ntfy/v2/db/pg"
 	"heckel.io/ntfy/v2/log"
 	"heckel.io/ntfy/v2/mail"
 	"heckel.io/ntfy/v2/message"
+	"heckel.io/ntfy/v2/metrics"
 	"heckel.io/ntfy/v2/model"
 	"heckel.io/ntfy/v2/payments"
+	"heckel.io/ntfy/v2/twilio"
 	"heckel.io/ntfy/v2/user"
 	"heckel.io/ntfy/v2/util"
-	"heckel.io/ntfy/v2/util/sprig"
 	"heckel.io/ntfy/v2/webpush"
 )
 
@@ -60,7 +61,9 @@ type Server struct {
 	mailer            mail.Sender
 	topics            map[string]*topic
 	visitors          map[string]*visitor // ip:<ip> or user:<user>
+	ban               *ban.Service        // Abuse ban-feed; nil when the feature is disabled (no ban file)
 	firebaseClient    *firebaseClient
+	twilio            *twilio.Client
 	messages          int64                               // Total number of messages (persisted if messageCache enabled)
 	messagesHistory   []int64                             // Last n values of the messages counter, used to determine rate
 	userManager       *user.Manager                       // Might be nil!
@@ -70,6 +73,8 @@ type Server struct {
 	stripe            stripeAPI                           // Stripe API, can be replaced with a mock
 	priceCache        *util.LookupCache[map[string]int64] // Stripe price ID -> price as cents (USD implied!)
 	metricsHandler    http.Handler                        // Handles /metrics if enable-metrics set, and listen-metrics-http not set
+	cluster           cluster.Cluster                     // Fans messages out to peer cluster nodes (nop when not clustered)
+	httpClusterServer *http.Server                        // Dedicated private listener for node-to-node fan-out (cluster-listen)
 	closeChan         chan bool
 	mu                sync.RWMutex
 }
@@ -90,6 +95,7 @@ var (
 	publishPathRegex       = regexp.MustCompile(`^/[-_A-Za-z0-9]{1,64}/(publish|send|trigger)$`)
 	updatePathRegex        = regexp.MustCompile(`^/[-_A-Za-z0-9]{1,64}/[-_A-Za-z0-9]{1,64}$`)
 	clearPathRegex         = regexp.MustCompile(`^/[-_A-Za-z0-9]{1,64}/[-_A-Za-z0-9]{1,64}/(read|clear)$`)
+	deletePathRegex        = regexp.MustCompile(`^/[-_A-Za-z0-9]{1,64}/[-_A-Za-z0-9]{1,64}/delete$`)
 	sequenceIDRegex        = topicRegex
 
 	webAppConfigPath              = "/config.js"
@@ -111,6 +117,7 @@ var (
 	apiUsersPath                                         = "/v1/users"
 	apiUsersAccessPath                                   = "/v1/users/access"
 	apiAccountPath                                       = "/v1/account"
+	apiAccountLoginPath                                  = "/v1/account/login"
 	apiAccountTokenPath                                  = "/v1/account/token"
 	apiAccountPasswordPath                               = "/v1/account/password"
 	apiAccountSettingsPath                               = "/v1/account/settings"
@@ -146,15 +153,6 @@ var (
 	//go:embed docs
 	docsStaticFs     embed.FS
 	docsStaticCached = &util.CachingEmbedFS{ModTime: time.Now(), FS: docsStaticFs}
-
-	//go:embed templates
-	templatesFs  embed.FS // Contains template config files (e.g. grafana.yml, github.yml, ...)
-	templatesDir = "templates"
-
-	// templateDisallowedRegex tests a template for disallowed expressions. While not really dangerous, they
-	// are not useful, and seem potentially troublesome.
-	templateDisallowedRegex = regexp.MustCompile(`(?m)\{\{-?\s*(call|template|define)\b`)
-	templateNameRegex       = regexp.MustCompile(`^[-_A-Za-z0-9]+$`)
 )
 
 const (
@@ -168,9 +166,6 @@ const (
 	unifiedPushTopicPrefix   = "up"                      // Temporarily, we rate limit all "up*" topics based on the subscriber
 	unifiedPushTopicLength   = 14                        // Length of UnifiedPush topics, including the "up" part
 	messagesHistoryMax       = 10                        // Number of message count values to keep in memory
-	templateMaxExecutionTime = 100 * time.Millisecond    // Maximum time a template can take to execute, used to prevent DoS attacks
-	templateMaxOutputBytes   = 1024 * 1024               // Maximum number of bytes a template can output, used to prevent DoS attacks
-	templateFileExtension    = ".yml"                    // Template files must end with this extension
 )
 
 // WebSocket constants
@@ -251,6 +246,16 @@ func New(conf *Config) (*Server, error) {
 	if err != nil {
 		return nil, err
 	}
+	twilioClient := twilio.NewClient(&twilio.Config{
+		Account:       conf.TwilioAccount,
+		AuthToken:     conf.TwilioAuthToken,
+		PhoneNumber:   conf.TwilioPhoneNumber,
+		CallsBaseURL:  conf.TwilioCallsBaseURL,
+		VerifyBaseURL: conf.TwilioVerifyBaseURL,
+		VerifyService: conf.TwilioVerifyService,
+		CallFormat:    conf.TwilioCallFormat,
+		BuildVersion:  conf.BuildVersion,
+	})
 	var userManager *user.Manager
 	if conf.AuthFile != "" || pool != nil {
 		authConfig := &user.Config{
@@ -290,6 +295,17 @@ func New(conf *Config) (*Server, error) {
 		}
 		firebaseClient = newFirebaseClient(sender, auther)
 	}
+	var banner *ban.Service
+	if conf.BanFile != "" {
+		banner = ban.NewService(&ban.Config{
+			File:           conf.BanFile,
+			Window:         conf.BanWindow,
+			Threshold:      conf.BanThreshold,
+			Weights:        conf.BanWeights,
+			PrefixBitsIPv4: conf.VisitorPrefixBitsIPv4,
+			PrefixBitsIPv6: conf.VisitorPrefixBitsIPv6,
+		})
+	}
 	s := &Server{
 		config:          conf,
 		db:              pool,
@@ -297,7 +313,9 @@ func New(conf *Config) (*Server, error) {
 		webPush:         wp,
 		attachment:      attachmentStore,
 		firebaseClient:  firebaseClient,
+		twilio:          twilioClient,
 		mailer:          sender,
+		ban:             banner,
 		topics:          topics,
 		userManager:     userManager,
 		messages:        messages,
@@ -306,9 +324,93 @@ func New(conf *Config) (*Server, error) {
 		stripe:          stripe,
 	}
 	s.priceCache = util.NewLookupCache(s.fetchStripePrices, conf.StripePriceCacheDuration)
+	// Cross-node cluster; delivery of peer messages to local subscribers is injected
+	// as a callback, so the cluster package never depends on the server. Peers talk to each
+	// other only via the dedicated cluster listener, never via the public listeners.
+	advertiseURL := conf.ClusterAdvertiseURL
+	if advertiseURL == "" && conf.ClusterListen != "" {
+		advertiseURL = "http://" + conf.ClusterListen
+	}
+	s.cluster, err = cluster.New(&cluster.Config{
+		Enabled:         conf.ClusterListen != "", // Setting cluster-listen implicitly enables clustering
+		NodeID:          cluster.NodeID(conf.ClusterNodeID),
+		AdvertiseURL:    advertiseURL,
+		Secret:          conf.ClusterSecret,
+		BatchLinger:     conf.ClusterBatchLinger,
+		MaxMessageBytes: int64(conf.MessageSizeLimit)*4 + 1024, // Envelope overhead over the raw message
+	}, pool, s.deliverFromBus, s.liveTopics)
+	if err != nil {
+		return nil, err
+	}
+	// The cluster routes messages by subscription knowledge: peers learn this node's live topics
+	// via periodic state pushes (liveTopics) and immediate announcements on a topic's first
+	// subscriber (the hook below; also set in topicsFromIDs for topics created later)
+	for _, t := range s.topics {
+		t.onFirstSubscriber = s.topicAnnouncer(t.ID)
+	}
 	return s, nil
 }
 
+// clusterHandler returns the handler served on the dedicated cluster listener (cluster-listen).
+// It serves the internal peer API (owned and routed by the cluster itself, including auth) plus
+// a health endpoint; the public listeners never expose these paths, so internal traffic cannot
+// be reached from the outside even before any firewalling.
+func (s *Server) clusterHandler() http.Handler {
+	mux := http.NewServeMux()
+	mux.HandleFunc(apiHealthPath, func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		if s.cluster.Healthy() {
+			io.WriteString(w, `{"healthy":true}`+"\n")
+		} else {
+			w.WriteHeader(http.StatusServiceUnavailable)
+			io.WriteString(w, `{"healthy":false}`+"\n")
+		}
+	})
+	mux.Handle("/", s.cluster)
+	return mux
+}
+
+// liveTopics returns the topics that currently have at least one subscriber, computed fresh on
+// every call. Deliberately NOT the whole topics map: it also holds subscriber-less topics
+// rebuilt from the message cache, which would gut the routing filter's selectivity.
+func (s *Server) liveTopics() []string {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	topics := make([]string, 0, len(s.topics))
+	for _, t := range s.topics {
+		if subscribers, _ := t.Stats(); subscribers > 0 {
+			topics = append(topics, t.ID)
+		}
+	}
+	return topics
+}
+
+// topicAnnouncer returns the first-subscriber hook for a topic: it tells peer nodes right away
+// that this node now wants messages for it (see Cluster.BroadcastState).
+func (s *Server) topicAnnouncer(id string) func() {
+	return func() {
+		s.cluster.BroadcastState(&cluster.State{AddedTopics: []string{id}})
+	}
+}
+
+// deliverFromBus delivers a message received from a peer node (via the cluster) to this
+// node's local subscribers. It is the receive-side counterpart to Cluster.ForwardMessage: local
+// delivery and all global side effects (Firebase, email, web push, upstream) already ran on the
+// origin node, so this only publishes to the local topic, and never re-relays.
+func (s *Server) deliverFromBus(m *model.Message) {
+	s.mu.RLock()
+	t, ok := s.topics[m.Topic]
+	s.mu.RUnlock()
+	if !ok {
+		metrics.ClusterMessagesWasted.Inc() // Relayed here needlessly: this node had no use for the message
+		return
+	}
+	v := s.visitor(m.Sender, nil)
+	if err := t.Publish(v, m); err != nil {
+		logvm(v, m).Err(err).Warn("Cluster: unable to deliver fan-out message to local subscribers")
+	}
+}
+
 func createMessageCache(conf *Config, pool *db.DB) (*message.Cache, error) {
 	if conf.CacheDuration == 0 {
 		return message.NewNopStore()
@@ -351,6 +453,9 @@ func (s *Server) Run() error {
 	if s.config.ProfileListenHTTP != "" {
 		listenStr += fmt.Sprintf(" %s[http/profile]", s.config.ProfileListenHTTP)
 	}
+	if s.config.ClusterListen != "" {
+		listenStr += fmt.Sprintf(" %s[http/cluster]", s.config.ClusterListen)
+	}
 	log.Tag(tagStartup).Info("Listening on%s, ntfy %s, log level is %s", listenStr, s.config.BuildVersion, log.CurrentLevel().String())
 	if log.IsFile() {
 		fmt.Fprintf(os.Stderr, "Listening on%s, ntfy %s\n", listenStr, s.config.BuildVersion)
@@ -398,15 +503,19 @@ func (s *Server) Run() error {
 		}()
 	}
 	if s.config.MetricsListenHTTP != "" {
-		initMetrics()
 		s.httpMetricsServer = &http.Server{Addr: s.config.MetricsListenHTTP, Handler: promhttp.Handler()}
 		go func() {
 			errChan <- s.httpMetricsServer.ListenAndServe()
 		}()
 	} else if s.config.EnableMetrics {
-		initMetrics()
 		s.metricsHandler = promhttp.Handler()
 	}
+	if s.config.ClusterListen != "" {
+		s.httpClusterServer = &http.Server{Addr: s.config.ClusterListen, Handler: s.clusterHandler()}
+		go func() {
+			errChan <- s.httpClusterServer.ListenAndServe()
+		}()
+	}
 	if s.config.ProfileListenHTTP != "" {
 		profileMux := http.NewServeMux()
 		profileMux.HandleFunc("/debug/pprof/", pprof.Index)
@@ -452,7 +561,16 @@ func (s *Server) Stop() {
 	if s.attachment != nil {
 		s.attachment.Close()
 	}
+	if s.httpClusterServer != nil {
+		s.httpClusterServer.Close()
+	}
+	if s.cluster != nil {
+		s.cluster.Close()
+	}
 	s.closeDatabases()
+	if s.ban != nil {
+		s.ban.Close()
+	}
 	if s.closeChan != nil {
 		close(s.closeChan)
 	}
@@ -475,7 +593,7 @@ func (s *Server) closeDatabases() {
 
 // handle is the main entry point for all HTTP requests
 func (s *Server) handle(w http.ResponseWriter, r *http.Request) {
-	v, err := s.maybeAuthenticate(r) // Note: Always returns v, even when error is returned
+	r, v, err := s.maybeAuthenticate(r) // Note: Always returns v (and r, with the client IP in its context), even on error
 	if err != nil {
 		s.handleError(w, r, v, err)
 		return
@@ -492,9 +610,7 @@ func (s *Server) handle(w http.ResponseWriter, r *http.Request) {
 				s.handleError(w, r, v, err)
 				return
 			}
-			if metricHTTPRequests != nil {
-				metricHTTPRequests.WithLabelValues("200", "20000", r.Method).Inc()
-			}
+			metrics.HTTPRequests.WithLabelValues("200", "20000", r.Method).Inc()
 		}).
 		Debug("HTTP request finished")
 }
@@ -504,9 +620,7 @@ func (s *Server) handleError(w http.ResponseWriter, r *http.Request, v *visitor,
 	if !ok {
 		httpErr = errHTTPInternalError
 	}
-	if metricHTTPRequests != nil {
-		metricHTTPRequests.WithLabelValues(fmt.Sprintf("%d", httpErr.HTTPCode), fmt.Sprintf("%d", httpErr.Code), r.Method).Inc()
-	}
+	metrics.HTTPRequests.WithLabelValues(strconv.Itoa(httpErr.HTTPCode), strconv.Itoa(httpErr.Code), r.Method).Inc()
 	isRateLimiting := util.Contains(rateLimitingErrorCodes, httpErr.HTTPCode)
 	isNormalError := strings.Contains(err.Error(), "i/o timeout") || util.Contains(normalErrorCodes, httpErr.HTTPCode)
 	ev := logvr(v, r).Err(err)
@@ -541,6 +655,11 @@ func (s *Server) handleError(w http.ResponseWriter, r *http.Request, v *visitor,
 	w.Header().Set("Access-Control-Allow-Origin", s.config.AccessControlAllowOrigin) // CORS, allow cross-origin requests
 	w.WriteHeader(httpErr.HTTPCode)
 	io.WriteString(w, httpErr.JSON()+"\n")
+	if s.ban != nil {
+		if ip, err := fromContext[netip.Addr](r, contextVisitorIP); err == nil {
+			s.ban.Record(ip, httpErr.HTTPCode, httpErr.Code)
+		}
+	}
 }
 
 func (s *Server) handleInternal(w http.ResponseWriter, r *http.Request, v *visitor) error {
@@ -578,6 +697,8 @@ func (s *Server) handleInternal(w http.ResponseWriter, r *http.Request, v *visit
 		return s.ensureUser(s.withAccountSync(s.handleAccountDelete))(w, r, v)
 	} else if r.Method == http.MethodPost && r.URL.Path == apiAccountPasswordPath {
 		return s.ensureUser(s.handleAccountPasswordChange)(w, r, v)
+	} else if r.Method == http.MethodPost && r.URL.Path == apiAccountLoginPath {
+		return s.ensureUser(s.withAccountSync(s.handleAccountLogin))(w, r, v)
 	} else if r.Method == http.MethodPost && r.URL.Path == apiAccountTokenPath {
 		return s.ensureUser(s.withAccountSync(s.handleAccountTokenCreate))(w, r, v)
 	} else if r.Method == http.MethodPatch && r.URL.Path == apiAccountTokenPath {
@@ -654,9 +775,9 @@ func (s *Server) handleInternal(w http.ResponseWriter, r *http.Request, v *visit
 		return s.transformMatrixJSON(s.limitRequestsWithTopic(s.authorizeTopicWrite(s.handlePublishMatrix)))(w, r, v)
 	} else if (r.Method == http.MethodPut || r.Method == http.MethodPost) && (topicPathRegex.MatchString(r.URL.Path) || updatePathRegex.MatchString(r.URL.Path)) {
 		return s.limitRequestsWithTopic(s.authorizeTopicWrite(s.handlePublish))(w, r, v)
-	} else if r.Method == http.MethodDelete && updatePathRegex.MatchString(r.URL.Path) {
+	} else if (r.Method == http.MethodDelete && updatePathRegex.MatchString(r.URL.Path)) || (r.Method == http.MethodGet && deletePathRegex.MatchString(r.URL.Path)) {
 		return s.limitRequestsWithTopic(s.authorizeTopicWrite(s.handleDelete))(w, r, v)
-	} else if r.Method == http.MethodPut && clearPathRegex.MatchString(r.URL.Path) {
+	} else if (r.Method == http.MethodGet || r.Method == http.MethodPut) && clearPathRegex.MatchString(r.URL.Path) {
 		return s.limitRequestsWithTopic(s.authorizeTopicWrite(s.handleClear))(w, r, v)
 	} else if r.Method == http.MethodGet && publishPathRegex.MatchString(r.URL.Path) {
 		return s.limitRequestsWithTopic(s.authorizeTopicWrite(s.handlePublish))(w, r, v)
@@ -678,22 +799,6 @@ func (s *Server) handleInternal(w http.ResponseWriter, r *http.Request, v *visit
 	return errHTTPNotFound
 }
 
-// handleWebApp serves the embedded web app's index for client-side (SPA) routes that the
-// browser router resolves, so the app shell loads and the client-side router takes over.
-func (s *Server) handleWebApp(w http.ResponseWriter, r *http.Request, v *visitor) error {
-	r.URL.Path = webAppIndex
-	return s.handleStatic(w, r, v)
-}
-
-// handleWebAppNoIndex serves the web app index for the magic-link landing pages, whose path
-// carries a one-time token. The response is marked no-referrer (so the token can't leak to third
-// parties via the Referer header) and noindex (so it never gets indexed).
-func (s *Server) handleWebAppNoIndex(w http.ResponseWriter, r *http.Request, v *visitor) error {
-	w.Header().Set("Referrer-Policy", "no-referrer")
-	w.Header().Set("X-Robots-Tag", "noindex")
-	return s.handleWebApp(w, r, v)
-}
-
 func (s *Server) handleTopic(w http.ResponseWriter, r *http.Request, v *visitor) error {
 	unifiedpush := readBoolParam(r, false, "x-unifiedpush", "unifiedpush", "up") // see PUT/POST too!
 	if unifiedpush {
@@ -714,65 +819,13 @@ func (s *Server) handleTopicAuth(w http.ResponseWriter, _ *http.Request, _ *visi
 }
 
 func (s *Server) handleHealth(w http.ResponseWriter, _ *http.Request, _ *visitor) error {
-	response := &apiHealthResponse{
-		Healthy: true,
+	// Unhealthy = the registry heartbeat went stale and peers stopped forwarding to this
+	// node; 503 lets status-code LB checks pull it (checkers must fail open, see cluster.Cluster)
+	healthy := s.cluster.Healthy()
+	if !healthy {
+		w.WriteHeader(http.StatusServiceUnavailable)
 	}
-	return s.writeJSON(w, response)
-}
-
-func (s *Server) handleConfig(w http.ResponseWriter, _ *http.Request, _ *visitor) error {
-	w.Header().Set("Cache-Control", "no-cache")
-	return s.writeJSON(w, s.configResponse())
-}
-
-func (s *Server) handleWebConfig(w http.ResponseWriter, _ *http.Request, _ *visitor) error {
-	b, err := json.MarshalIndent(s.configResponse(), "", "  ")
-	if err != nil {
-		return err
-	}
-	w.Header().Set("Content-Type", "text/javascript")
-	w.Header().Set("Cache-Control", "no-cache")
-	_, err = io.WriteString(w, fmt.Sprintf("// Generated server configuration\nvar config = %s;\n", string(b)))
-	return err
-}
-
-func (s *Server) configResponse() *apiConfigResponse {
-	return &apiConfigResponse{
-		BaseURL:             "", // Will translate to window.location.origin
-		AppRoot:             s.config.WebRoot,
-		EnableLogin:         s.config.EnableLogin,
-		RequireLogin:        s.config.RequireLogin,
-		EnableSignup:        s.config.EnableSignup,
-		EnablePayments:      s.config.StripeSecretKey != "",
-		EnableCalls:         s.config.TwilioAccount != "",
-		EnableEmails:        s.config.SMTPSenderFrom != "",
-		EnableResetPassword: s.config.SMTPSenderFrom != "" && s.config.BaseURL != "", // Reset links need SMTP + an absolute base-url
-		EnableReservations:  s.config.EnableReservations,
-		EnableWebPush:       s.config.WebPushPublicKey != "",
-		BillingContact:      s.config.BillingContact,
-		WebPushPublicKey:    s.config.WebPushPublicKey,
-		DisallowedTopics:    s.config.DisallowedTopics,
-		ConfigHash:          s.config.Hash(),
-	}
-}
-
-// handleWebManifest serves the web app manifest for the progressive web app (PWA)
-func (s *Server) handleWebManifest(w http.ResponseWriter, _ *http.Request, _ *visitor) error {
-	response := &webManifestResponse{
-		Name:            "ntfy",
-		Description:     "ntfy lets you send push notifications via scripts from any computer or phone",
-		ShortName:       "ntfy",
-		Scope:           "/",
-		StartURL:        s.config.WebRoot,
-		Display:         "standalone",
-		BackgroundColor: "#ffffff",
-		ThemeColor:      "#317f6f",
-		Icons: []*webManifestIcon{
-			{SRC: "/static/images/pwa-192x192.png", Sizes: "192x192", Type: "image/png"},
-			{SRC: "/static/images/pwa-512x512.png", Sizes: "512x512", Type: "image/png"},
-		},
-	}
-	return s.writeJSONWithContentType(w, response, "application/manifest+json")
+	return s.writeJSON(w, &apiHealthResponse{Healthy: healthy})
 }
 
 // handleMetrics returns Prometheus metrics. This endpoint is only called if enable-metrics is set,
@@ -782,19 +835,6 @@ func (s *Server) handleMetrics(w http.ResponseWriter, r *http.Request, _ *visito
 	return nil
 }
 
-// handleStatic returns all static resources (excluding the docs), including the web app
-func (s *Server) handleStatic(w http.ResponseWriter, r *http.Request, _ *visitor) error {
-	r.URL.Path = webSiteDir + r.URL.Path
-	util.Gzip(http.FileServer(http.FS(webFsCached))).ServeHTTP(w, r)
-	return nil
-}
-
-// handleDocs returns static resources related to the docs
-func (s *Server) handleDocs(w http.ResponseWriter, r *http.Request, _ *visitor) error {
-	util.Gzip(http.FileServer(http.FS(docsStaticCached))).ServeHTTP(w, r)
-	return nil
-}
-
 // handleStats returns the publicly available server stats
 func (s *Server) handleStats(w http.ResponseWriter, _ *http.Request, _ *visitor) error {
 	s.mu.RLock()
@@ -885,6 +925,49 @@ func (s *Server) handleMatrixDiscovery(w http.ResponseWriter) error {
 	return writeMatrixDiscoveryResponse(w)
 }
 
+// dispatch delivers m to local subscribers, forwards it to peer cluster nodes, and fires the
+// requested side-effect targets. It is the single choke point through which every published
+// message must pass; t may be nil when the topic has no local subscribers (delayed sender).
+//
+// The side-effect targets (Firebase, email, calls, upstream, web push) are global, not per-node:
+// they fire only here on the origin node, and never again when a peer node receives the message
+// via the cluster (see deliverFromBus).
+func (s *Server) dispatch(v *visitor, t *topic, m *model.Message, opts dispatchOpts) error {
+	// Deliver to local subscribers
+	if t != nil {
+		if opts.async {
+			go func() {
+				if err := t.Publish(v, m); err != nil {
+					logvm(v, m).Err(err).Warn("Unable to publish message")
+				}
+			}()
+		} else if err := t.Publish(v, m); err != nil {
+			return err
+		}
+	}
+	// Forward to peer cluster nodes, whose subscribers do not show up in this node's topics map
+	if err := s.cluster.ForwardMessage(m); err != nil {
+		logvm(v, m).Err(err).Warn("Cluster: unable to forward message to peer nodes")
+	}
+	// Fire the requested side-effect targets
+	if s.firebaseClient != nil && opts.firebase {
+		go s.sendToFirebase(v, m)
+	}
+	if s.mailer != nil && opts.email != "" {
+		go s.sendEmail(v, m, opts.email)
+	}
+	if s.config.TwilioAccount != "" && opts.call != "" {
+		go s.callPhone(v, m, opts.call)
+	}
+	if s.config.UpstreamBaseURL != "" && opts.upstream {
+		go s.forwardPollRequest(v, m)
+	}
+	if s.config.WebPushPublicKey != "" && opts.webPush {
+		go s.publishToWebPushEndpoints(v, m)
+	}
+	return nil
+}
+
 func (s *Server) handlePublishInternal(r *http.Request, v *visitor) (*model.Message, error) {
 	start := time.Now()
 	t, err := fromContext[*topic](r, contextTopic)
@@ -963,24 +1046,16 @@ func (s *Server) handlePublishInternal(r *http.Request, v *visitor) (*model.Mess
 		ev.Debug("Received message")
 	}
 	if !delayed {
-		if err := t.Publish(v, m); err != nil {
+		err := s.dispatch(v, t, m, dispatchOpts{
+			firebase: firebase,
+			email:    email,
+			call:     call,
+			upstream: !unifiedpush, // UP messages are not sent to upstream
+			webPush:  true,
+		})
+		if err != nil {
 			return nil, err
 		}
-		if s.firebaseClient != nil && firebase {
-			go s.sendToFirebase(v, m)
-		}
-		if s.mailer != nil && email != "" {
-			go s.sendEmail(v, m, email)
-		}
-		if s.config.TwilioAccount != "" && call != "" {
-			go s.callPhone(v, r, m, call)
-		}
-		if s.config.UpstreamBaseURL != "" && !unifiedpush { // UP messages are not sent to upstream
-			go s.forwardPollRequest(v, m)
-		}
-		if s.config.WebPushPublicKey != "" {
-			go s.publishToWebPushEndpoints(v, m)
-		}
 	} else {
 		logvrm(v, r, m).Tag(tagPublish).Debug("Message delayed, will process later")
 	}
@@ -1009,27 +1084,27 @@ func (s *Server) handlePublishInternal(r *http.Request, v *visitor) (*model.Mess
 	s.messages++
 	s.mu.Unlock()
 	if unifiedpush {
-		minc(metricUnifiedPushPublishedSuccess)
+		metrics.UnifiedPushPublishedSuccess.Inc()
 	}
-	mset(metricMessagePublishDurationMillis, time.Since(start).Milliseconds())
+	metrics.MessagePublishDurationMillis.Set(float64(time.Since(start).Milliseconds()))
 	return m, nil
 }
 
 func (s *Server) handlePublish(w http.ResponseWriter, r *http.Request, v *visitor) error {
 	m, err := s.handlePublishInternal(r, v)
 	if err != nil {
-		minc(metricMessagesPublishedFailure)
+		metrics.MessagesPublishedFailure.Inc()
 		return err
 	}
-	minc(metricMessagesPublishedSuccess)
+	metrics.MessagesPublishedSuccess.Inc()
 	return s.writeJSON(w, m.ForJSON())
 }
 
 func (s *Server) handlePublishMatrix(w http.ResponseWriter, r *http.Request, v *visitor) error {
 	_, err := s.handlePublishInternal(r, v)
 	if err != nil {
-		minc(metricMessagesPublishedFailure)
-		minc(metricMatrixPublishedFailure)
+		metrics.MessagesPublishedFailure.Inc()
+		metrics.MatrixPublishedFailure.Inc()
 		if e, ok := err.(*errHTTP); ok && e.HTTPCode == errHTTPInsufficientStorageUnifiedPush.HTTPCode {
 			topic, err := fromContext[*topic](r, contextTopic)
 			if err != nil {
@@ -1045,8 +1120,8 @@ func (s *Server) handlePublishMatrix(w http.ResponseWriter, r *http.Request, v *
 		}
 		return err
 	}
-	minc(metricMessagesPublishedSuccess)
-	minc(metricMatrixPublishedSuccess)
+	metrics.MessagesPublishedSuccess.Inc()
+	metrics.MatrixPublishedSuccess.Inc()
 	return writeMatrixSuccess(w)
 }
 
@@ -1079,18 +1154,10 @@ func (s *Server) handleActionMessage(w http.ResponseWriter, r *http.Request, v *
 	m.Sender = v.IP()
 	m.User = v.MaybeUserID()
 	m.Expires = time.Unix(m.Time, 0).Add(v.Limits().MessageExpiryDuration).Unix()
-	// Publish to subscribers
-	if err := t.Publish(v, m); err != nil {
+	// Publish to subscribers, peer nodes, Firebase (for Android clients), and web push endpoints
+	if err := s.dispatch(v, t, m, dispatchOpts{firebase: true, webPush: true}); err != nil {
 		return err
 	}
-	// Send to Firebase for Android clients
-	if s.firebaseClient != nil {
-		go s.sendToFirebase(v, m)
-	}
-	// Send to web push endpoints
-	if s.config.WebPushPublicKey != "" {
-		go s.publishToWebPushEndpoints(v, m)
-	}
 	if event == model.MessageDeleteEvent {
 		// Delete any existing scheduled message with the same sequence ID
 		deletedIDs, err := s.messageCache.DeleteScheduledBySequenceID(t.ID, sequenceID)
@@ -1118,7 +1185,7 @@ func (s *Server) handleActionMessage(w http.ResponseWriter, r *http.Request, v *
 func (s *Server) sendToFirebase(v *visitor, m *model.Message) {
 	logvm(v, m).Tag(tagFirebase).Debug("Publishing to Firebase")
 	if err := s.firebaseClient.Send(v, m); err != nil {
-		minc(metricFirebasePublishedFailure)
+		metrics.FirebasePublishedFailure.Inc()
 		if errors.Is(err, errFirebaseTemporarilyBanned) {
 			logvm(v, m).Tag(tagFirebase).Err(err).Debug("Unable to publish to Firebase: %v", err.Error())
 		} else {
@@ -1126,17 +1193,17 @@ func (s *Server) sendToFirebase(v *visitor, m *model.Message) {
 		}
 		return
 	}
-	minc(metricFirebasePublishedSuccess)
+	metrics.FirebasePublishedSuccess.Inc()
 }
 
 func (s *Server) sendEmail(v *visitor, m *model.Message, email string) {
 	logvm(v, m).Tag(tagEmail).Field("email", email).Info("Sending email to %s", email)
 	if err := s.mailer.SendNotification(email, m, v.ip.String()); err != nil {
 		logvm(v, m).Tag(tagEmail).Field("email", email).Err(err).Warn("Unable to send email to %s: %v", email, err.Error())
-		minc(metricEmailsPublishedFailure)
+		metrics.EmailsPublishedFailure.Inc()
 		return
 	}
-	minc(metricEmailsPublishedSuccess)
+	metrics.EmailsPublishedSuccess.Inc()
 }
 
 func (s *Server) forwardPollRequest(v *visitor, m *model.Message) {
@@ -1282,7 +1349,7 @@ func (s *Server) parsePublishParams(r *http.Request, m *model.Message) (cache bo
 	}
 	actionsStr := readParam(r, "x-actions", "actions", "action")
 	if actionsStr != "" {
-		m.Actions, e = parseActions(actionsStr)
+		m.Actions, e = action.Parse(actionsStr)
 		if e != nil {
 			return false, false, "", "", "", false, "", errHTTPBadRequestActionsInvalid.Wrap("%s", e.Error())
 		}
@@ -1332,7 +1399,7 @@ func (s *Server) handlePublishBody(r *http.Request, v *visitor, m *model.Message
 	} else if m.Attachment != nil && m.Attachment.Name != "" {
 		return s.handleBodyAsAttachment(r, v, m, body) // Case 4
 	} else if template.Enabled() {
-		return s.handleBodyAsTemplatedTextMessage(m, template, body, priorityStr) // Case 5
+		return s.handleBodyAsTemplatedTextMessage(r.Context(), m, template, body, priorityStr) // Case 5
 	} else if !body.LimitReached && utf8.Valid(body.PeekedBytes) {
 		return s.handleBodyAsTextMessage(m, body) // Case 6
 	}
@@ -1368,114 +1435,6 @@ func (s *Server) handleBodyAsTextMessage(m *model.Message, body *util.PeekedRead
 	return nil
 }
 
-func (s *Server) handleBodyAsTemplatedTextMessage(m *model.Message, template templateMode, body *util.PeekedReadCloser, priorityStr string) error {
-	body, err := util.Peek(body, max(s.config.MessageSizeLimit, jsonBodyBytesLimit))
-	if err != nil {
-		return err
-	} else if body.LimitReached {
-		return errHTTPEntityTooLargeJSONBody
-	}
-	peekedBody := strings.TrimSpace(string(body.PeekedBytes))
-	if template.FileMode() {
-		if err := s.renderTemplateFromFile(m, template.FileName(), peekedBody); err != nil {
-			return err
-		}
-	} else {
-		if err := s.renderTemplateFromParams(m, peekedBody, priorityStr); err != nil {
-			return err
-		}
-	}
-	if len(m.Title) > s.config.MessageSizeLimit || len(m.Message) > s.config.MessageSizeLimit {
-		return errHTTPBadRequestTemplateMessageTooLarge
-	}
-	return nil
-}
-
-// renderTemplateFromFile transforms the JSON message body according to a template from the filesystem.
-// The template file must be in the templates directory, or in the configured template directory.
-func (s *Server) renderTemplateFromFile(m *model.Message, templateName, peekedBody string) error {
-	if !templateNameRegex.MatchString(templateName) {
-		return errHTTPBadRequestTemplateFileNotFound
-	}
-	templateContent, _ := templatesFs.ReadFile(filepath.Join(templatesDir, templateName+templateFileExtension)) // Read from the embedded filesystem first
-	if s.config.TemplateDir != "" {
-		if b, _ := os.ReadFile(filepath.Join(s.config.TemplateDir, templateName+templateFileExtension)); len(b) > 0 {
-			templateContent = b
-		}
-	}
-	if len(templateContent) == 0 {
-		return errHTTPBadRequestTemplateFileNotFound
-	}
-	var tpl templateFile
-	if err := yaml.Unmarshal(templateContent, &tpl); err != nil {
-		return errHTTPBadRequestTemplateFileInvalid
-	}
-	var err error
-	if tpl.Message != nil {
-		if m.Message, err = s.renderTemplate(templateName+" (message)", *tpl.Message, peekedBody); err != nil {
-			return err
-		}
-	}
-	if tpl.Title != nil {
-		if m.Title, err = s.renderTemplate(templateName+" (title)", *tpl.Title, peekedBody); err != nil {
-			return err
-		}
-	}
-	if tpl.Priority != nil {
-		renderedPriority, err := s.renderTemplate(templateName+" (priority)", *tpl.Priority, peekedBody)
-		if err != nil {
-			return err
-		}
-		if m.Priority, err = util.ParsePriority(renderedPriority); err != nil {
-			return errHTTPBadRequestPriorityInvalid
-		}
-	}
-	return nil
-}
-
-// renderTemplateFromParams transforms the JSON message body according to the inline template in the
-// message, title, and priority parameters.
-func (s *Server) renderTemplateFromParams(m *model.Message, peekedBody string, priorityStr string) error {
-	var err error
-	if m.Message, err = s.renderTemplate("priority query parameter", m.Message, peekedBody); err != nil {
-		return err
-	}
-	if m.Title, err = s.renderTemplate("title query parameter", m.Title, peekedBody); err != nil {
-		return err
-	}
-	if priorityStr != "" {
-		renderedPriority, err := s.renderTemplate("priority query parameter", priorityStr, peekedBody)
-		if err != nil {
-			return err
-		}
-		if m.Priority, err = util.ParsePriority(renderedPriority); err != nil {
-			return errHTTPBadRequestPriorityInvalid
-		}
-	}
-	return nil
-}
-
-// renderTemplate renders a template with the given JSON source data.
-func (s *Server) renderTemplate(name, tpl, source string) (string, error) {
-	if templateDisallowedRegex.MatchString(tpl) {
-		return "", errHTTPBadRequestTemplateDisallowedFunctionCalls
-	}
-	var data any
-	if err := json.Unmarshal([]byte(source), &data); err != nil {
-		return "", errHTTPBadRequestTemplateMessageNotJSON
-	}
-	t, err := template.New("").Funcs(sprig.TxtFuncMap()).Parse(tpl)
-	if err != nil {
-		return "", errHTTPBadRequestTemplateInvalid.Wrap("%s", err.Error())
-	}
-	var buf bytes.Buffer
-	limitWriter := util.NewLimitWriter(util.NewTimeoutWriter(&buf, templateMaxExecutionTime), util.NewFixedLimiter(templateMaxOutputBytes))
-	if err := t.Execute(limitWriter, data); err != nil {
-		return "", errHTTPBadRequestTemplateExecuteFailed.Wrap("template %s: %s", name, err.Error())
-	}
-	return strings.TrimSpace(strings.ReplaceAll(buf.String(), "\\n", "\n")), nil // replace any remaining "\n" (those outside of template curly braces) with newlines
-}
-
 func (s *Server) handleBodyAsAttachment(r *http.Request, v *visitor, m *model.Message, body *util.PeekedReadCloser) error {
 	if s.attachment == nil || s.config.BaseURL == "" {
 		return errHTTPBadRequestAttachmentsDisallowed.With(m)
@@ -1529,7 +1488,7 @@ func (s *Server) handleBodyAsAttachment(r *http.Request, v *visitor, m *model.Me
 func (s *Server) handleSubscribeJSON(w http.ResponseWriter, r *http.Request, v *visitor) error {
 	encoder := func(msg *model.Message) (string, error) {
 		var buf bytes.Buffer
-		if err := json.NewEncoder(&buf).Encode(msg.ForJSON()); err != nil {
+		if err := util.EncodeJSON(&buf, msg.ForJSON()); err != nil {
 			return "", err
 		}
 		return buf.String(), nil
@@ -1540,7 +1499,7 @@ func (s *Server) handleSubscribeJSON(w http.ResponseWriter, r *http.Request, v *
 func (s *Server) handleSubscribeSSE(w http.ResponseWriter, r *http.Request, v *visitor) error {
 	encoder := func(msg *model.Message) (string, error) {
 		var buf bytes.Buffer
-		if err := json.NewEncoder(&buf).Encode(msg.ForJSON()); err != nil {
+		if err := util.EncodeJSON(&buf, msg.ForJSON()); err != nil {
 			return "", err
 		}
 		if msg.Event != model.MessageEvent && msg.Event != model.MessageDeleteEvent && msg.Event != model.MessageClearEvent {
@@ -1992,7 +1951,9 @@ func (s *Server) topicsFromIDs(v *visitor, ids ...string) ([]*topic, error) {
 			if v != nil && !v.TopicCreationAllowed() {
 				return nil, errHTTPTooManyRequestsLimitTopicCreation
 			}
-			s.topics[id] = newTopic(id)
+			t := newTopic(id)
+			t.onFirstSubscriber = s.topicAnnouncer(id)
+			s.topics[id] = t
 		}
 		topics = append(topics, s.topics[id])
 	}
@@ -2079,7 +2040,8 @@ func (s *Server) resetStats() {
 	for _, v := range s.visitors {
 		v.ResetStats()
 	}
-	if s.userManager != nil {
+	// The user database is shared; only the cluster leader resets it (always true single-node)
+	if s.userManager != nil && s.cluster.IsLeader() {
 		if err := s.userManager.ResetStats(); err != nil {
 			log.Tag(tagResetter).Warn("Failed to write to database: %s", err.Error())
 		}
@@ -2094,7 +2056,11 @@ func (s *Server) runFirebaseKeepaliver() {
 	for {
 		select {
 		case <-time.After(s.config.FirebaseKeepaliveInterval):
-			s.sendToFirebase(v, model.NewKeepaliveMessage(firebaseControlTopic))
+			// Leader only: every FCM keepalive wakes all subscribed phones, so a cluster must
+			// send it exactly once, not once per node (checked per tick to survive failover)
+			if s.cluster.IsLeader() {
+				s.sendToFirebase(v, model.NewKeepaliveMessage(firebaseControlTopic))
+			}
 		/*
 			FIXME: Disable iOS polling entirely for now due to thundering herd problem (see #677)
 			       To solve this, we'd have to shard the iOS poll topics to spread out the polling evenly.
@@ -2147,24 +2113,18 @@ func (s *Server) sendDelayedMessages() error {
 func (s *Server) sendDelayedMessage(v *visitor, m *model.Message) error {
 	logvm(v, m).Debug("Sending delayed message")
 	s.mu.RLock()
-	t, ok := s.topics[m.Topic] // If no subscribers, just mark message as published
+	t := s.topics[m.Topic] // May be nil if there are no local subscribers; dispatch handles that
 	s.mu.RUnlock()
-	if ok {
-		go func() {
-			// We do not rate-limit messages here, since we've rate limited them in the PUT/POST handler
-			if err := t.Publish(v, m); err != nil {
-				logvm(v, m).Err(err).Warn("Unable to publish message")
-			}
-		}()
-	}
-	if s.firebaseClient != nil { // Firebase subscribers may not show up in topics map
-		go s.sendToFirebase(v, m)
-	}
-	if s.config.UpstreamBaseURL != "" {
-		go s.forwardPollRequest(v, m)
-	}
-	if s.config.WebPushPublicKey != "" {
-		go s.publishToWebPushEndpoints(v, m)
+	// We do not rate-limit messages here, since we've rate limited them in the PUT/POST handler.
+	// Firebase subscribers may not show up in the topics map, so side effects fire regardless.
+	err := s.dispatch(v, t, m, dispatchOpts{
+		firebase: true,
+		upstream: true,
+		webPush:  true,
+		async:    true,
+	})
+	if err != nil {
+		return err
 	}
 	if err := s.messageCache.MarkPublished(m); err != nil {
 		return err
@@ -2259,130 +2219,6 @@ func (s *Server) transformMatrixJSON(next handleFunc) handleFunc {
 	}
 }
 
-func (s *Server) authorizeTopicWrite(next handleFunc) handleFunc {
-	return s.authorizeTopic(next, user.PermissionWrite)
-}
-
-func (s *Server) authorizeTopicRead(next handleFunc) handleFunc {
-	return s.authorizeTopic(next, user.PermissionRead)
-}
-
-func (s *Server) authorizeTopic(next handleFunc, perm user.Permission) handleFunc {
-	return func(w http.ResponseWriter, r *http.Request, v *visitor) error {
-		if s.userManager == nil {
-			return next(w, r, v)
-		}
-		topics, _, err := s.topicsFromPath(v, r.URL.Path)
-		if err != nil {
-			return err
-		}
-		u := v.User()
-		for _, t := range topics {
-			if err := s.userManager.Authorize(u, t.ID, perm); err != nil {
-				logvr(v, r).With(t).Err(err).Debug("Access to topic %s not authorized", t.ID)
-				return errHTTPForbidden.With(t)
-			}
-		}
-		return next(w, r, v)
-	}
-}
-
-// maybeAuthenticate reads the "Authorization" header and will try to authenticate the user
-// if it is set.
-//
-//   - If auth-file is not configured, immediately return an IP-based visitor
-//   - If the header is not set or not supported (anything non-Basic and non-Bearer),
-//     an IP-based visitor is returned
-//   - If the header is set, authenticate will be called to check the username/password (Basic auth),
-//     or the token (Bearer auth), and read the user from the database
-//
-// This function will ALWAYS return a visitor, even if an error occurs (e.g. unauthorized), so
-// that subsequent logging calls still have a visitor context.
-func (s *Server) maybeAuthenticate(r *http.Request) (*visitor, error) {
-	// Read the "Authorization" header value and exit out early if it's not set
-	ip := extractIPAddress(r, s.config.BehindProxy, s.config.ProxyForwardedHeader, s.config.ProxyTrustedPrefixes)
-	vip := s.visitor(ip, nil)
-	if s.userManager == nil {
-		return vip, nil
-	}
-	header, err := readAuthHeader(r)
-	if err != nil {
-		return vip, err
-	} else if !supportedAuthHeader(header) {
-		return vip, nil
-	}
-	// If we're trying to auth, check the rate limiter first
-	if !vip.AuthAllowed() {
-		return vip, errHTTPTooManyRequestsLimitAuthFailure // Always return visitor, even when error occurs!
-	}
-	u, err := s.authenticate(r, header)
-	if err != nil {
-		vip.AuthFailed()
-		logr(r).Err(err).Debug("Authentication failed")
-		return vip, errHTTPUnauthorized // Always return visitor, even when error occurs!
-	}
-	// Authentication with user was successful
-	return s.visitor(ip, u), nil
-}
-
-// authenticate a user based on basic auth username/password (Authorization: Basic ...), or token auth (Authorization: Bearer ...).
-// The Authorization header can be passed as a header or the ?auth=... query param. The latter is required only to
-// support the WebSocket JavaScript class, which does not support passing headers during the initial request. The auth
-// query param is effectively doubly base64 encoded. Its format is base64(Basic base64(user:pass)).
-func (s *Server) authenticate(r *http.Request, header string) (user *user.User, err error) {
-	if strings.HasPrefix(header, "Bearer") {
-		return s.authenticateBearerAuth(r, strings.TrimSpace(strings.TrimPrefix(header, "Bearer")))
-	}
-	return s.authenticateBasicAuth(r, header)
-}
-
-// readAuthHeader reads the raw value of the Authorization header, either from the actual HTTP header,
-// or from the ?auth... query parameter
-func readAuthHeader(r *http.Request) (string, error) {
-	value := strings.TrimSpace(r.Header.Get("Authorization"))
-	queryParam := readQueryParam(r, "authorization", "auth")
-	if queryParam != "" {
-		a, err := base64.RawURLEncoding.DecodeString(queryParam)
-		if err != nil {
-			return "", err
-		}
-		value = strings.TrimSpace(string(a))
-	}
-	return value, nil
-}
-
-// supportedAuthHeader returns true only if the Authorization header value starts
-// with "Basic" or "Bearer". In particular, an empty value is not supported, and neither
-// are things like "WebPush", or "vapid" (see #629).
-func supportedAuthHeader(value string) bool {
-	value = strings.ToLower(value)
-	return strings.HasPrefix(value, "basic ") || strings.HasPrefix(value, "bearer ")
-}
-
-func (s *Server) authenticateBasicAuth(r *http.Request, value string) (user *user.User, err error) {
-	r.Header.Set("Authorization", value)
-	username, password, ok := r.BasicAuth()
-	if !ok {
-		return nil, errors.New("invalid basic auth")
-	} else if username == "" {
-		return s.authenticateBearerAuth(r, password) // Treat password as token
-	}
-	return s.userManager.Authenticate(username, password)
-}
-
-func (s *Server) authenticateBearerAuth(r *http.Request, token string) (*user.User, error) {
-	u, err := s.userManager.AuthenticateToken(token)
-	if err != nil {
-		return nil, err
-	}
-	ip := extractIPAddress(r, s.config.BehindProxy, s.config.ProxyForwardedHeader, s.config.ProxyTrustedPrefixes)
-	go s.userManager.EnqueueTokenUpdate(token, &user.TokenUpdate{
-		LastAccess: time.Now(),
-		LastOrigin: ip,
-	})
-	return u, nil
-}
-
 func (s *Server) visitor(ip netip.Addr, user *user.User) *visitor {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -2404,10 +2240,7 @@ func (s *Server) writeJSON(w http.ResponseWriter, v any) error {
 func (s *Server) writeJSONWithContentType(w http.ResponseWriter, v any, contentType string) error {
 	w.Header().Set("Content-Type", contentType)
 	w.Header().Set("Access-Control-Allow-Origin", s.config.AccessControlAllowOrigin) // CORS, allow cross-origin requests
-	if err := json.NewEncoder(w).Encode(v); err != nil {
-		return err
-	}
-	return nil
+	return util.EncodeJSON(w, v)
 }
 
 func (s *Server) updateAndWriteStats(messagesCount int64) {

server/server.yml

@@ -61,6 +61,34 @@
 #
 # database-url: <connection-string>
 
+# If "cluster-listen" is set, clustering is implicitly enabled: this node registers itself in
+# the PostgreSQL node registry and fans published messages out to the other cluster nodes over
+# HTTP, so subscribers connected to any node receive messages published to any other node.
+# Requires "database-url" and "cluster-secret".
+#
+# - cluster-listen is the ip:port of the dedicated fan-out listener that peer nodes talk to.
+#   Bind it to a private network interface (e.g. "10.0.0.5:2587"); the public listeners never
+#   serve the fan-out endpoint.
+# - cluster-node-id is a stable per-node identifier (e.g. the hostname); required.
+# - cluster-advertise-url is the base URL peer nodes use to reach this node's fan-out listener;
+#   it defaults to "http://<cluster-listen>". It must be set explicitly if cluster-listen binds
+#   a wildcard address (e.g. ":2587").
+# - cluster-secret authenticates node-to-node fan-out requests; it must be identical on all
+#   nodes.
+# - cluster-batch-linger is how long fan-out messages may wait to form a batch per peer node,
+#   trading up to that much cross-node delivery latency for a bounded request rate between
+#   nodes. Set to 0 to send each message immediately.
+#
+# SECURITY: The fan-out endpoint injects messages into arbitrary topics. The shared secret
+# protects it, and it is only served on the dedicated cluster listener -- but you should still
+# make sure that listener is reachable only from the private network (firewall/VPC rules).
+#
+# cluster-listen: <ip:port>
+# cluster-node-id: <hostname>
+# cluster-advertise-url: "http://<cluster-listen>"
+# cluster-secret: <secret>
+# cluster-batch-linger: 500ms
+
 # If "cache-file" is set, messages are cached in a local SQLite database instead of only in-memory.
 # This allows for service restarts without losing messages in support of the since= parameter.
 # Not required if "database-url" is set (messages are stored in PostgreSQL instead).
@@ -370,6 +398,39 @@
 # visitor-topic-creation-limit-burst: 100
 # visitor-topic-creation-limit-replenish: "1m"
 
+# Abuse ban-feed: Count HTTP response statuses per visitor and append abusive IPs to a file that
+# fail2ban (or similar) can tail and ban on sight. This captures ntfy-layer rejections (e.g. ACL
+# 403s and ntfy's own 429s), so fail2ban does not have to regex-parse the full access log.
+# - ban-file is the file abusive IPs are appended to; leave empty to disable the feature. Its
+#   directory must exist and be writable by ntfy. Rotate it (e.g. logrotate, copytruncate) so it
+#   cannot grow unbounded.
+# - ban-window is the rolling window over which weighted strikes are counted, per visitor.
+# - ban-threshold is the number of weighted strikes per window before a visitor is banned. Each
+#   visitor has ONE strike budget; rejections draw it down, so there is no way to game it by mixing
+#   codes.
+# - ban-weights assigns a strike weight to a matcher KEY (KEY:WEIGHT). A KEY is an exact ntfy code
+#   ("42909"), a prefix family ("429*"), a bare HTTP status ("403", shorthand for "403*"), or "*".
+#   Longest match wins. A weight of 0 exempts a code (never contributes to a ban), so the legit quota
+#   429s can be carved out from a "*" catch-all. Heavier weights ban faster (auth-failure floods).
+#
+# Each appended line has the exact format
+#   "<RFC3339-UTC-timestamp> <ip> <prefix> <http-code> <ntfy-code>", for example:
+#   2026-07-17T20:56:32Z 1.2.3.4 1.2.3.4/32 429 42901
+#   2026-07-17T20:56:32Z 2001:db8::abcd 2001:db8::/64 429 42909
+# <prefix> is <ip> masked to the rate-limiting prefix (visitor-prefix-bits-ipv4/ipv6); that is the
+# unit a fail2ban jail should ban, so a whole IPv6 subnet is banned as one.
+#
+# ban-file: "/var/log/ntfy-ban.log"
+# ban-window: "1m"
+# ban-threshold: 100
+# ban-weights:
+#   - "42909:10"   # auth-failure flood: bans in ~10
+#   - "42908:0"    # daily message quota reached -> legit, never counts
+#   - "42903:0"    # subscription limit -> legit
+#   - "42905:0"    # daily bandwidth reached -> legit
+#   - "42910:0"    # daily phone call quota reached -> legit
+#   - "*:1"        # everything else 4xx/5xx
+
 # Rate limiting: IPv4/IPv6 address prefix bits used for rate limiting
 # - visitor-prefix-bits-ipv4: number of bits of the IPv4 address to use for rate limiting (default: 32, full address)
 # - visitor-prefix-bits-ipv6: number of bits of the IPv6 address to use for rate limiting (default: 64, /64 subnet)
@@ -423,8 +484,9 @@
 # doing, and/or secure access to the endpoint in your reverse proxy.
 #
 # - enable-metrics enables the /metrics endpoint for the default ntfy server (i.e. HTTP, HTTPS and/or Unix socket)
-# - metrics-listen-http exposes the metrics endpoint via a dedicated [IP]:port. If set, this option implicitly
-#   enables metrics as well, e.g. "10.0.1.1:9090" or ":9090"
+# - metrics-listen-http moves the metrics endpoint to a dedicated [IP]:port, e.g. "10.0.1.1:9090" or ":9090".
+#   It implicitly enables metrics. If set, the metrics are served only on that dedicated port, and the default
+#   ntfy server does not serve /metrics, even if enable-metrics is also set.
 #
 # enable-metrics: false
 # metrics-listen-http:

server/server_account.go

@@ -10,6 +10,7 @@ import (
 
 	"heckel.io/ntfy/v2/log"
 	"heckel.io/ntfy/v2/model"
+	"heckel.io/ntfy/v2/twilio"
 	"heckel.io/ntfy/v2/user"
 	"heckel.io/ntfy/v2/util"
 )
@@ -107,6 +108,12 @@ func (s *Server) handleAccountGet(w http.ResponseWriter, r *http.Request, v *vis
 			if u.Prefs.Language != nil {
 				response.Language = *u.Prefs.Language
 			}
+			if u.Prefs.DateFormat != nil {
+				response.DateFormat = *u.Prefs.DateFormat
+			}
+			if u.Prefs.TimeFormat != nil {
+				response.TimeFormat = *u.Prefs.TimeFormat
+			}
 			if u.Prefs.Notification != nil {
 				response.Notification = u.Prefs.Notification
 			}
@@ -180,10 +187,6 @@ func (s *Server) handleAccountGet(w http.ResponseWriter, r *http.Request, v *vis
 			if err != nil {
 				return err
 			}
-			primaryEmail, err := s.userManager.PrimaryEmail(u.ID)
-			if err != nil {
-				return err
-			}
 			pendingEmails, err := s.userManager.PendingEmails(u.ID)
 			if err != nil {
 				return err
@@ -191,7 +194,7 @@ func (s *Server) handleAccountGet(w http.ResponseWriter, r *http.Request, v *vis
 			// Combine verified (with primary flag) and pending (unverified) into one list
 			emailInfos := make([]*apiAccountEmailInfo, 0, len(emails)+len(pendingEmails))
 			for _, email := range emails {
-				emailInfos = append(emailInfos, &apiAccountEmailInfo{Address: email, Primary: email == primaryEmail})
+				emailInfos = append(emailInfos, &apiAccountEmailInfo{Address: email.Address, Primary: email.Primary})
 			}
 			for _, email := range pendingEmails {
 				emailInfos = append(emailInfos, &apiAccountEmailInfo{Address: email, Pending: true})
@@ -266,6 +269,24 @@ func (s *Server) handleAccountPasswordChange(w http.ResponseWriter, r *http.Requ
 	return s.writeJSON(w, newSuccessResponse())
 }
 
+// handleAccountLogin authenticates a username-or-email + password (via the ensureUser wrapper's
+// Basic Auth), mints a session token, and returns it together with the canonical username. Unlike
+// the token endpoint (which exists to mint arbitrary API tokens), this endpoint's job is to log a
+// user in, so it also reports who they are (the identifier they typed may be a primary email).
+func (s *Server) handleAccountLogin(w http.ResponseWriter, r *http.Request, v *visitor) error {
+	u := v.User()
+	logvr(v, r).Tag(tagAccount).Info("Logging in user %s", u.Name)
+	token, err := s.userManager.CreateToken(u.ID, "", time.Now().Add(tokenExpiryDuration), v.IP(), false)
+	if err != nil {
+		return err
+	}
+	response := &apiAccountLoginResponse{
+		Token:    token.Value,
+		Username: u.Name,
+	}
+	return s.writeJSON(w, response)
+}
+
 func (s *Server) handleAccountTokenCreate(w http.ResponseWriter, r *http.Request, v *visitor) error {
 	req, err := readJSONWithLimit[apiAccountTokenIssueRequest](r.Body, jsonBodyBytesLimit, true) // Allow empty body!
 	if err != nil {
@@ -377,6 +398,12 @@ func (s *Server) handleAccountSettingsChange(w http.ResponseWriter, r *http.Requ
 	if newPrefs.Language != nil {
 		prefs.Language = newPrefs.Language
 	}
+	if newPrefs.DateFormat != nil {
+		prefs.DateFormat = newPrefs.DateFormat
+	}
+	if newPrefs.TimeFormat != nil {
+		prefs.TimeFormat = newPrefs.TimeFormat
+	}
 	if newPrefs.Notification != nil {
 		if prefs.Notification == nil {
 			prefs.Notification = &user.NotificationPrefs{}
@@ -605,7 +632,7 @@ func (s *Server) handleAccountPhoneNumberVerify(w http.ResponseWriter, r *http.R
 	}
 	// Actually add the unverified number, and send verification
 	logvr(v, r).Tag(tagAccount).Field("phone_number", req.Number).Debug("Sending phone number verification")
-	if err := s.verifyPhoneNumber(v, r, req.Number, req.Channel); err != nil {
+	if err := s.twilio.Verify(req.Number, req.Channel); err != nil {
 		return err
 	}
 	return s.writeJSON(w, newSuccessResponse())
@@ -620,7 +647,10 @@ func (s *Server) handleAccountPhoneNumberAdd(w http.ResponseWriter, r *http.Requ
 	if !phoneNumberRegex.MatchString(req.Number) {
 		return errHTTPBadRequestPhoneNumberInvalid
 	}
-	if err := s.verifyPhoneNumberCheck(v, r, req.Number, req.Code); err != nil {
+	if err := s.twilio.CheckVerify(req.Number, req.Code); err != nil {
+		if errors.Is(err, twilio.ErrVerificationExpired) {
+			return errHTTPGonePhoneVerificationExpired
+		}
 		return err
 	}
 	logvr(v, r).Tag(tagAccount).Field("phone_number", req.Number).Debug("Adding phone number as verified")
@@ -667,7 +697,7 @@ func (s *Server) handleAccountEmailAdd(w http.ResponseWriter, r *http.Request, v
 	emails, err := s.userManager.Emails(u.ID)
 	if err != nil {
 		return err
-	} else if util.Contains(emails, req.Email) {
+	} else if emails.Contains(req.Email) {
 		return errHTTPConflictEmailExists
 	}
 	// Rate limit (counts against the user's email quota)
@@ -888,7 +918,7 @@ func (s *Server) convertEmailAddress(u *user.User, email string) (string, *errHT
 		if err != nil {
 			return "", errHTTPInternalError
 		} else if len(emails) > 0 {
-			return emails[0], nil
+			return emails[0].Address, nil
 		}
 		return "", errHTTPBadRequestEmailAddressNotVerified
 	}
@@ -903,7 +933,7 @@ func (s *Server) convertEmailAddress(u *user.User, email string) (string, *errHT
 	emails, err := s.userManager.Emails(u.ID)
 	if err != nil {
 		return "", errHTTPInternalError
-	} else if util.Contains(emails, email) {
+	} else if emails.Contains(email) {
 		return email, nil
 	}
 	return "", errHTTPBadRequestEmailAddressNotVerified
@@ -955,7 +985,8 @@ func (s *Server) publishSyncEventForUser(v *visitor, u *user.User) error {
 		return err
 	}
 	m := model.NewDefaultMessage(syncTopic.ID, string(messageBytes))
-	if err := syncTopic.Publish(v, m); err != nil {
+	// Dispatch so the sync event also reaches the user's devices connected to peer cluster nodes
+	if err := s.dispatch(v, syncTopic, m, dispatchOpts{}); err != nil {
 		return err
 	}
 	return nil

server/server_account_email_test.go

@@ -224,6 +224,22 @@ func canLogin(t *testing.T, s *Server, username, password string) bool {
 	return rr.Code == 200
 }
 
+func TestAccount_LoginByPrimaryEmail(t *testing.T) {
+	forEachBackend(t, func(t *testing.T, databaseURL string) {
+		s, mailer, auth := newEmailTestServer(t, databaseURL)
+		defer s.closeDatabases()
+		verifyEmailFor(t, s, mailer, auth, "ben@example.com")
+
+		// Basic Auth works with either the username or the verified primary email
+		require.True(t, canLogin(t, s, "ben", "ben"))
+		require.True(t, canLogin(t, s, "ben@example.com", "ben"))
+
+		// ...but not with the wrong password or an unknown email
+		require.False(t, canLogin(t, s, "ben@example.com", "wrong"))
+		require.False(t, canLogin(t, s, "nobody@example.com", "ben"))
+	})
+}
+
 func TestAccount_PasswordReset_ByUsername(t *testing.T) {
 	forEachBackend(t, func(t *testing.T, databaseURL string) {
 		s, mailer, auth := newEmailTestServer(t, databaseURL)

server/server_account_test.go

@@ -55,6 +55,58 @@ func TestAccount_Signup_Success(t *testing.T) {
 	})
 }
 
+func TestAccount_Login_Success(t *testing.T) {
+	forEachBackend(t, func(t *testing.T, databaseURL string) {
+		conf := newTestConfigWithAuthFile(t, databaseURL)
+		s := newTestServer(t, conf)
+		defer s.closeDatabases()
+
+		require.Nil(t, s.userManager.AddUser("phil", "mypass", user.RoleUser, false))
+		u, err := s.userManager.User("phil")
+		require.Nil(t, err)
+		require.Nil(t, s.userManager.AddEmail(u.ID, "phil@example.com"))
+		require.Nil(t, s.userManager.SetPrimaryEmail(u.ID, "phil@example.com"))
+
+		// Login by username returns a token and the canonical username
+		rr := request(t, s, "POST", "/v1/account/login", "", map[string]string{
+			"Authorization": util.BasicAuth("phil", "mypass"),
+		})
+		require.Equal(t, 200, rr.Code)
+		resp, _ := util.UnmarshalJSON[apiAccountLoginResponse](io.NopCloser(rr.Body))
+		require.True(t, strings.HasPrefix(resp.Token, "tk_"))
+		require.Equal(t, "phil", resp.Username)
+
+		// The returned token actually authenticates
+		rr = request(t, s, "GET", "/v1/account", "", map[string]string{
+			"Authorization": util.BearerAuth(resp.Token),
+		})
+		require.Equal(t, 200, rr.Code)
+
+		// Login by primary email returns the canonical username, not the email that was typed
+		rr = request(t, s, "POST", "/v1/account/login", "", map[string]string{
+			"Authorization": util.BasicAuth("phil@example.com", "mypass"),
+		})
+		require.Equal(t, 200, rr.Code)
+		resp, _ = util.UnmarshalJSON[apiAccountLoginResponse](io.NopCloser(rr.Body))
+		require.True(t, strings.HasPrefix(resp.Token, "tk_"))
+		require.Equal(t, "phil", resp.Username)
+	})
+}
+
+func TestAccount_Login_InvalidCredentials(t *testing.T) {
+	forEachBackend(t, func(t *testing.T, databaseURL string) {
+		conf := newTestConfigWithAuthFile(t, databaseURL)
+		s := newTestServer(t, conf)
+		defer s.closeDatabases()
+		require.Nil(t, s.userManager.AddUser("phil", "mypass", user.RoleUser, false))
+
+		rr := request(t, s, "POST", "/v1/account/login", "", map[string]string{
+			"Authorization": util.BasicAuth("phil", "wrongpass"),
+		})
+		require.Equal(t, 401, rr.Code)
+	})
+}
+
 func TestAccount_Signup_UserExists(t *testing.T) {
 	forEachBackend(t, func(t *testing.T, databaseURL string) {
 		conf := newTestConfigWithAuthFile(t, databaseURL)
@@ -207,12 +259,19 @@ func TestAccount_ChangeSettings(t *testing.T) {
 		})
 		require.Equal(t, 200, rr.Code)
 
+		rr = request(t, s, "PATCH", "/v1/account/settings", `{"date_format": "iso8601", "time_format": "24h"}`, map[string]string{
+			"Authorization": util.BearerAuth(token.Value),
+		})
+		require.Equal(t, 200, rr.Code)
+
 		rr = request(t, s, "GET", "/v1/account", `{"username":"marian", "password":"marian"}`, map[string]string{
 			"Authorization": util.BearerAuth(token.Value),
 		})
 		require.Equal(t, 200, rr.Code)
 		account, _ := util.UnmarshalJSON[apiAccountResponse](io.NopCloser(rr.Body))
 		require.Equal(t, "de", account.Language)
+		require.Equal(t, "iso8601", account.DateFormat) // Merged, not overwritten by previous PATCH
+		require.Equal(t, "24h", account.TimeFormat)
 		require.Equal(t, util.Int(86400), account.Notification.DeleteAfter)
 		require.Equal(t, util.String("juntos"), account.Notification.Sound)
 		require.Nil(t, account.Notification.MinPriority) // Not set

server/server_auth.go

@@ -0,0 +1,111 @@
+package server
+
+import (
+	"encoding/base64"
+	"errors"
+	"net/http"
+	"strings"
+	"time"
+
+	"heckel.io/ntfy/v2/user"
+)
+
+// maybeAuthenticate reads the "Authorization" header and will try to authenticate the user
+// if it is set.
+//
+//   - If auth-file is not configured, immediately return an IP-based visitor
+//   - If the header is not set or not supported (anything non-Basic and non-Bearer),
+//     an IP-based visitor is returned
+//   - If the header is set, authenticate will be called to check the username/password (Basic auth),
+//     or the token (Bearer auth), and read the user from the database
+//
+// This function will ALWAYS return a visitor, even if an error occurs (e.g. unauthorized), so
+// that subsequent logging calls still have a visitor context.
+func (s *Server) maybeAuthenticate(r *http.Request) (*http.Request, *visitor, error) {
+	// Read the "Authorization" header value and exit out early if it's not set
+	ip := extractIPAddress(r, s.config.BehindProxy, s.config.ProxyForwardedHeader, s.config.ProxyTrustedPrefixes)
+	// Stash the extracted client IP in the request context so downstream code (the abuse ban-feed in
+	// handleError) can reuse it without re-parsing headers, and so an account-keyed (tier'd) visitor --
+	// whose shared visitor object has a stale v.ip -- is still attributed to the actual request IP.
+	r = withContext(r, map[contextKey]any{contextVisitorIP: ip})
+	vip := s.visitor(ip, nil)
+	if s.userManager == nil {
+		return r, vip, nil
+	}
+	header, err := readAuthHeader(r)
+	if err != nil {
+		return r, vip, err
+	} else if !supportedAuthHeader(header) {
+		return r, vip, nil
+	}
+	// If we're trying to auth, check the rate limiter first
+	if !vip.AuthAllowed() {
+		return r, vip, errHTTPTooManyRequestsLimitAuthFailure // Always return visitor, even when error occurs!
+	}
+	u, err := s.authenticate(r, header)
+	if err != nil {
+		vip.AuthFailed()
+		logr(r).Err(err).Debug("Authentication failed")
+		return r, vip, errHTTPUnauthorized // Always return visitor, even when error occurs!
+	}
+	// Authentication with user was successful
+	return r, s.visitor(ip, u), nil
+}
+
+// authenticate a user based on basic auth username/password (Authorization: Basic ...), or token auth (Authorization: Bearer ...).
+// The Authorization header can be passed as a header or the ?auth=... query param. The latter is required only to
+// support the WebSocket JavaScript class, which does not support passing headers during the initial request. The auth
+// query param is effectively doubly base64 encoded. Its format is base64(Basic base64(user:pass)).
+func (s *Server) authenticate(r *http.Request, header string) (user *user.User, err error) {
+	if strings.HasPrefix(header, "Bearer") {
+		return s.authenticateBearerAuth(r, strings.TrimSpace(strings.TrimPrefix(header, "Bearer")))
+	}
+	return s.authenticateBasicAuth(r, header)
+}
+
+// readAuthHeader reads the raw value of the Authorization header, either from the actual HTTP header,
+// or from the ?auth... query parameter
+func readAuthHeader(r *http.Request) (string, error) {
+	value := strings.TrimSpace(r.Header.Get("Authorization"))
+	queryParam := readQueryParam(r, "authorization", "auth")
+	if queryParam != "" {
+		a, err := base64.RawURLEncoding.DecodeString(queryParam)
+		if err != nil {
+			return "", err
+		}
+		value = strings.TrimSpace(string(a))
+	}
+	return value, nil
+}
+
+// supportedAuthHeader returns true only if the Authorization header value starts
+// with "Basic" or "Bearer". In particular, an empty value is not supported, and neither
+// are things like "WebPush", or "vapid" (see #629).
+func supportedAuthHeader(value string) bool {
+	value = strings.ToLower(value)
+	return strings.HasPrefix(value, "basic ") || strings.HasPrefix(value, "bearer ")
+}
+
+func (s *Server) authenticateBasicAuth(r *http.Request, value string) (user *user.User, err error) {
+	r.Header.Set("Authorization", value)
+	username, password, ok := r.BasicAuth()
+	if !ok {
+		return nil, errors.New("invalid basic auth")
+	} else if username == "" {
+		return s.authenticateBearerAuth(r, password) // Treat password as token
+	}
+	return s.userManager.Authenticate(username, password)
+}
+
+func (s *Server) authenticateBearerAuth(r *http.Request, token string) (*user.User, error) {
+	u, err := s.userManager.AuthenticateToken(token)
+	if err != nil {
+		return nil, err
+	}
+	ip := extractIPAddress(r, s.config.BehindProxy, s.config.ProxyForwardedHeader, s.config.ProxyTrustedPrefixes)
+	go s.userManager.EnqueueTokenUpdate(token, &user.TokenUpdate{
+		LastAccess: time.Now(),
+		LastOrigin: ip,
+	})
+	return u, nil
+}

server/server_cluster_test.go

@@ -0,0 +1,353 @@
+package server
+
+import (
+	"database/sql"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"heckel.io/ntfy/v2/cluster"
+	dbtest "heckel.io/ntfy/v2/db/test"
+	"heckel.io/ntfy/v2/model"
+	"heckel.io/ntfy/v2/user"
+)
+
+// fakeCluster records relayed messages and topic announcements so tests can assert that every
+// publish path passes through the cluster exactly once, and that subscription hooks fire.
+type fakeCluster struct {
+	mu         sync.Mutex
+	messages   []*model.Message
+	announced  []string
+	notLeader  bool
+	notHealthy bool
+}
+
+func (b *fakeCluster) ForwardMessage(m *model.Message) error {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	b.messages = append(b.messages, m)
+	return nil
+}
+
+func (b *fakeCluster) ServeHTTP(_ http.ResponseWriter, _ *http.Request) {}
+
+func (b *fakeCluster) BroadcastState(state *cluster.State) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	b.announced = append(b.announced, state.AddedTopics...)
+}
+
+func (b *fakeCluster) Healthy() bool {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return !b.notHealthy
+}
+
+func (b *fakeCluster) setHealthy(healthy bool) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	b.notHealthy = !healthy
+}
+
+func (b *fakeCluster) IsLeader() bool {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return !b.notLeader
+}
+
+func (b *fakeCluster) setLeader(leader bool) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	b.notLeader = !leader
+}
+
+func (b *fakeCluster) Close() error { return nil }
+
+func (b *fakeCluster) Messages() []*model.Message {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return append([]*model.Message{}, b.messages...)
+}
+
+func (b *fakeCluster) Announced() []string {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return append([]string{}, b.announced...)
+}
+
+func TestServer_Cluster_PublishForwardsOnce(t *testing.T) {
+	s := newTestServer(t, newTestConfig(t, ""))
+	b := &fakeCluster{}
+	s.cluster = b
+	response := request(t, s, "PUT", "/mytopic", "hi there", nil)
+	require.Equal(t, 200, response.Code)
+	messages := b.Messages()
+	require.Len(t, messages, 1)
+	require.Equal(t, "mytopic", messages[0].Topic)
+	require.Equal(t, "hi there", messages[0].Message)
+}
+
+func TestServer_Cluster_SyncEventForwards(t *testing.T) {
+	// Account sync events are delivered via the user's st_... sync topic; without relaying
+	// them, cross-device account sync silently breaks when a user's devices land on different
+	// cluster nodes.
+	s := newTestServer(t, newTestConfig(t, ""))
+	b := &fakeCluster{}
+	s.cluster = b
+	u := &user.User{ID: "u_abc", Name: "phil", SyncTopic: "st_1234"}
+	v := s.visitor(netip.MustParseAddr("1.2.3.4"), nil)
+	require.Nil(t, s.publishSyncEventForUser(v, u))
+	messages := b.Messages()
+	require.Len(t, messages, 1)
+	require.Equal(t, "st_1234", messages[0].Topic)
+}
+
+func TestServer_Cluster_DeliverNotOnPublicHandler(t *testing.T) {
+	// The fan-out endpoint lives only on the dedicated cluster listener; the public handler must
+	// not serve it, even with cluster mode on and a valid secret.
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	conf := newTestConfig(t, schemaDSN)
+	conf.ClusterNodeID = "node-a"
+	conf.ClusterListen = "127.0.0.1:1" // Enables clustering; not bound since Run() is not called
+	conf.ClusterSecret = "s3cret"
+	conf.ClusterAdvertiseURL = "http://127.0.0.1:1"
+	s := newTestServer(t, conf)
+	topics, err := s.topicsFromIDs(nil, "mytopic")
+	require.Nil(t, err)
+	var mu sync.Mutex
+	var received []*model.Message
+	topics[0].Subscribe(func(_ *visitor, m *model.Message) error {
+		mu.Lock()
+		defer mu.Unlock()
+		received = append(received, m)
+		return nil
+	}, "", func() {})
+	// A valid fan-out request against the PUBLIC handler must not deliver
+	response := request(t, s, "POST", "/v1/internal/message",
+		`{"message":{"id":"x1","time":1,"event":"message","topic":"mytopic","message":"sneaky"}}`,
+		map[string]string{"X-Cluster-Secret": "s3cret", "X-Cluster-Origin": "node-b"})
+	require.Equal(t, 404, response.Code)
+	time.Sleep(250 * time.Millisecond) // Delivery is async; give a wrong implementation time to fail
+	mu.Lock()
+	require.Empty(t, received)
+	mu.Unlock()
+	// The same request against the cluster listener handler DOES deliver
+	rr := httptest.NewRecorder()
+	req, err := http.NewRequest("POST", "/v1/internal/message",
+		strings.NewReader(`{"message":{"id":"x2","time":1,"event":"message","topic":"mytopic","message":"legit"}}`))
+	require.Nil(t, err)
+	req.Header.Set("X-Cluster-Secret", "s3cret")
+	req.Header.Set("X-Cluster-Origin", "node-b")
+	s.clusterHandler().ServeHTTP(rr, req)
+	require.Equal(t, 200, rr.Code)
+	waitFor(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+		return len(received) == 1
+	})
+}
+
+func TestServer_Cluster_EndToEnd(t *testing.T) {
+	// Two full servers sharing one Postgres schema: a message published to node A over HTTP must
+	// reach a subscriber connected to node B, via the node registry and the fan-out endpoint.
+	schemaDSN := dbtest.CreateTestPostgresSchema(t)
+	// Node B: create the listener first so its advertise URL is known before the server exists
+	listenerB, err := net.Listen("tcp", "127.0.0.1:0")
+	require.Nil(t, err)
+	confB := newTestConfig(t, schemaDSN)
+	confB.ClusterNodeID = "node-b"
+	confB.ClusterListen = listenerB.Addr().String() // Enables clustering; the test serves it below
+	confB.ClusterSecret = "s3cret"
+	confB.ClusterAdvertiseURL = "http://" + listenerB.Addr().String()
+	sB := newTestServer(t, confB)
+	srvB := &http.Server{Handler: sB.clusterHandler()}
+	go srvB.Serve(listenerB)
+	defer srvB.Close()
+	// Node A: publish-only in this test, so its advertise URL is never called
+	confA := newTestConfig(t, schemaDSN)
+	confA.ClusterNodeID = "node-a"
+	confA.ClusterListen = "127.0.0.1:1" // Enables clustering; not bound since Run() is not called
+	confA.ClusterSecret = "s3cret"
+	confA.ClusterAdvertiseURL = "http://127.0.0.1:1"
+	sA := newTestServer(t, confA)
+	// Subscribe on node B
+	topics, err := sB.topicsFromIDs(nil, "mytopic")
+	require.Nil(t, err)
+	var mu sync.Mutex
+	var received []*model.Message
+	topics[0].Subscribe(func(_ *visitor, m *model.Message) error {
+		mu.Lock()
+		defer mu.Unlock()
+		received = append(received, m)
+		return nil
+	}, "", func() {})
+	// Publish on node A
+	response := request(t, sA, "PUT", "/mytopic", "hello cluster", nil)
+	require.Equal(t, 200, response.Code)
+	waitFor(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+		return len(received) == 1
+	})
+	mu.Lock()
+	defer mu.Unlock()
+	require.Equal(t, "hello cluster", received[0].Message)
+}
+
+func TestServer_Cluster_DeliverFromBus(t *testing.T) {
+	// deliverFromBus is the receive side of the broadcaster: a message that originated on a peer
+	// node must reach this node's local subscribers, but must NOT be re-broadcast (loop) nor
+	// re-trigger origin-only side effects.
+	s := newTestServer(t, newTestConfig(t, ""))
+	b := &fakeCluster{}
+	s.cluster = b
+	topics, err := s.topicsFromIDs(nil, "mytopic")
+	require.Nil(t, err)
+	var mu sync.Mutex
+	var received []*model.Message
+	topics[0].Subscribe(func(_ *visitor, m *model.Message) error {
+		mu.Lock()
+		defer mu.Unlock()
+		received = append(received, m)
+		return nil
+	}, "", func() {})
+	m := model.NewDefaultMessage("mytopic", "from peer")
+	m.Sender = netip.MustParseAddr("5.6.7.8")
+	s.deliverFromBus(m)
+	waitFor(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+		return len(received) == 1
+	})
+	require.Empty(t, b.Messages()) // Peer messages are never re-relayed
+}
+
+func TestServer_Cluster_FirstSubscriberAnnounces(t *testing.T) {
+	// A topic gaining its FIRST subscriber is announced to peers exactly once, so publishers on
+	// other nodes stop skipping this node for it without waiting for the next state push.
+	s := newTestServer(t, newTestConfig(t, ""))
+	b := &fakeCluster{}
+	s.cluster = b
+	topics, err := s.topicsFromIDs(nil, "mytopic")
+	require.Nil(t, err)
+	subscriber := func(_ *visitor, _ *model.Message) error { return nil }
+	topics[0].Subscribe(subscriber, "", func() {})
+	waitFor(t, func() bool {
+		return len(b.Announced()) == 1 && b.Announced()[0] == "mytopic"
+	})
+	// A second subscriber does not re-announce
+	topics[0].Subscribe(subscriber, "", func() {})
+	time.Sleep(250 * time.Millisecond)
+	require.Len(t, b.Announced(), 1)
+}
+
+func TestServer_Cluster_ManagerPrunesOnlyOnLeader(t *testing.T) {
+	c := newTestConfig(t, "")
+	s := newTestServer(t, c)
+	cl := &fakeCluster{notLeader: true}
+	s.cluster = cl
+
+	// Publish and expire a message
+	rr := request(t, s, "POST", "/mytopic", "hi", nil)
+	require.Equal(t, 200, rr.Code)
+	m := toMessage(t, rr.Body.String())
+	require.Nil(t, s.messageCache.ExpireMessages("mytopic"))
+
+	// A non-leader node leaves shared-database pruning to the leader
+	s.execManager()
+	_, err := s.messageCache.Message(m.ID)
+	require.Nil(t, err)
+
+	// Once this node is the leader, the same run prunes
+	cl.setLeader(true)
+	s.execManager()
+	_, err = s.messageCache.Message(m.ID)
+	require.Equal(t, model.ErrMessageNotFound, err)
+}
+
+func TestServer_Cluster_StatsResetOnlyOnLeader(t *testing.T) {
+	c := newTestConfigWithAuthFile(t, "")
+	s := newTestServer(t, c)
+	cl := &fakeCluster{notLeader: true}
+	s.cluster = cl
+
+	// An anonymous visitor with an in-memory message count
+	v := newVisitor(c, s.messageCache, s.userManager, netip.MustParseAddr("1.2.3.4"), nil)
+	require.True(t, v.MessageAllowed())
+	s.mu.Lock()
+	s.visitors["ip:1.2.3.4"] = v
+	s.mu.Unlock()
+	require.Equal(t, int64(1), v.Stats().Messages)
+
+	// A user with persisted stats in the (shared) user database
+	require.Nil(t, s.userManager.AddUser("phil", "phil1234", user.RoleUser, false))
+	authDB, err := sql.Open("sqlite3", c.AuthFile)
+	require.Nil(t, err)
+	defer authDB.Close()
+	_, err = authDB.Exec(`UPDATE user SET stats_messages = 5 WHERE user = 'phil'`)
+	require.Nil(t, err)
+
+	// A non-leader node resets its own in-memory visitor stats, but leaves the user database
+	// to the leader
+	s.resetStats()
+	require.Equal(t, int64(0), v.Stats().Messages)
+	u, err := s.userManager.User("phil")
+	require.Nil(t, err)
+	require.Equal(t, int64(5), u.Stats.Messages)
+
+	// The leader resets the user database too
+	cl.setLeader(true)
+	s.resetStats()
+	u, err = s.userManager.User("phil")
+	require.Nil(t, err)
+	require.Equal(t, int64(0), u.Stats.Messages)
+}
+
+func TestServer_Cluster_FirebaseKeepaliverOnlyOnLeader(t *testing.T) {
+	// Every FCM keepalive wakes all subscribed phones, so only the leader may send them;
+	// N nodes sending N keepalives would multiply the battery cost for every user
+	c := newTestConfig(t, "")
+	c.FirebaseKeepaliveInterval = 20 * time.Millisecond
+	s := newTestServer(t, c)
+	sender := newTestFirebaseSender(100)
+	s.firebaseClient = newFirebaseClient(sender, &testAuther{Allow: true})
+	cl := &fakeCluster{notLeader: true}
+	s.cluster = cl
+	s.closeChan = make(chan bool) // Closed by Stop() in the test cleanup
+	go s.runFirebaseKeepaliver()
+
+	// A non-leader node stays silent
+	time.Sleep(150 * time.Millisecond)
+	require.Empty(t, sender.Messages())
+
+	// The leader sends keepalives
+	cl.setLeader(true)
+	waitFor(t, func() bool { return len(sender.Messages()) > 0 })
+}
+
+func TestServer_Cluster_HealthReflectsCluster(t *testing.T) {
+	// A node whose registry heartbeat went stale no longer receives forwarded messages, so
+	// health checks must pull it from rotation (the fail-open policy lives in the checker)
+	s := newTestServer(t, newTestConfig(t, ""))
+	cl := &fakeCluster{}
+	s.cluster = cl
+	rr := request(t, s, "GET", "/v1/health", "", nil)
+	require.Equal(t, 200, rr.Code)
+	require.Contains(t, rr.Body.String(), `"healthy":true`)
+	cl.setHealthy(false)
+	rr = request(t, s, "GET", "/v1/health", "", nil)
+	require.Equal(t, 503, rr.Code)
+	require.Contains(t, rr.Body.String(), `"healthy":false`)
+	// The cluster listener's health endpoint reflects the same state
+	rr2 := httptest.NewRecorder()
+	req, err := http.NewRequest("GET", "/v1/health", nil)
+	require.Nil(t, err)
+	s.clusterHandler().ServeHTTP(rr2, req)
+	require.Equal(t, 503, rr2.Code)
+}

server/server_manager.go

@@ -2,6 +2,7 @@ package server
 
 import (
 	"heckel.io/ntfy/v2/log"
+	"heckel.io/ntfy/v2/metrics"
 	"heckel.io/ntfy/v2/util"
 )
 
@@ -9,12 +10,16 @@ func (s *Server) execManager() {
 	// WARNING: Make sure to only selectively lock with the mutex, and be aware that this
 	//          there is no mutex for the entire function.
 
-	// Prune all the things
+	// Prune all the things. In-memory state is pruned on every node; jobs touching shared
+	// databases (and the web push job, which also sends expiry-warning notifications) run on
+	// the cluster leader only. In a single-node setup, IsLeader is always true.
 	s.pruneVisitors()
-	s.pruneTokens()
-	s.pruneAttachments()
-	s.pruneMessages()
-	s.pruneAndNotifyWebPushSubscriptions()
+	if s.cluster.IsLeader() {
+		s.pruneTokens()
+		s.pruneAttachments()
+		s.pruneMessages()
+		s.pruneAndNotifyWebPushSubscriptions()
+	}
 
 	// Message count
 	messagesCached, err := s.messageCache.MessagesCount()
@@ -93,13 +98,13 @@ func (s *Server) execManager() {
 			"emails_sent_failure":     sentMailFailure,
 		}).
 		Info("Server stats")
-	mset(metricMessagesCached, messagesCached)
-	mset(metricVisitors, visitorsCount)
-	mset(metricUsers, usersCount)
-	mset(metricSubscribers, subscribers)
-	mset(metricTopics, topicsCount)
+	metrics.MessagesCached.Set(float64(messagesCached))
+	metrics.Visitors.Set(float64(visitorsCount))
+	metrics.Users.Set(float64(usersCount))
+	metrics.Subscribers.Set(float64(subscribers))
+	metrics.Topics.Set(float64(topicsCount))
 	if s.attachment != nil {
-		mset(metricAttachmentsTotalSize, s.attachment.Size())
+		metrics.AttachmentsTotalSize.Set(float64(s.attachment.Size()))
 	}
 }
 

server/server_matrix.go

@@ -165,8 +165,5 @@ func writeMatrixResponse(w http.ResponseWriter, rejectedPushKey string) error {
 		Rejected: rejected,
 	}
 	w.Header().Set("Content-Type", "application/json")
-	if err := json.NewEncoder(w).Encode(response); err != nil {
-		return err
-	}
-	return nil
+	return util.EncodeJSON(w, response)
 }

server/server_metrics.go

@@ -1,132 +0,0 @@
-package server
-
-import (
-	"github.com/prometheus/client_golang/prometheus"
-)
-
-var (
-	metricMessagesPublishedSuccess     prometheus.Counter
-	metricMessagesPublishedFailure     prometheus.Counter
-	metricMessagesCached               prometheus.Gauge
-	metricMessagePublishDurationMillis prometheus.Gauge
-	metricFirebasePublishedSuccess     prometheus.Counter
-	metricFirebasePublishedFailure     prometheus.Counter
-	metricEmailsPublishedSuccess       prometheus.Counter
-	metricEmailsPublishedFailure       prometheus.Counter
-	metricEmailsReceivedSuccess        prometheus.Counter
-	metricEmailsReceivedFailure        prometheus.Counter
-	metricCallsMadeSuccess             prometheus.Counter
-	metricCallsMadeFailure             prometheus.Counter
-	metricUnifiedPushPublishedSuccess  prometheus.Counter
-	metricMatrixPublishedSuccess       prometheus.Counter
-	metricMatrixPublishedFailure       prometheus.Counter
-	metricAttachmentsTotalSize         prometheus.Gauge
-	metricVisitors                     prometheus.Gauge
-	metricSubscribers                  prometheus.Gauge
-	metricTopics                       prometheus.Gauge
-	metricUsers                        prometheus.Gauge
-	metricHTTPRequests                 *prometheus.CounterVec
-)
-
-func initMetrics() {
-	metricMessagesPublishedSuccess = prometheus.NewCounter(prometheus.CounterOpts{
-		Name: "ntfy_messages_published_success",
-	})
-	metricMessagesPublishedFailure = prometheus.NewCounter(prometheus.CounterOpts{
-		Name: "ntfy_messages_published_failure",
-	})
-	metricMessagesCached = prometheus.NewGauge(prometheus.GaugeOpts{
-		Name: "ntfy_messages_cached_total",
-	})
-	metricMessagePublishDurationMillis = prometheus.NewGauge(prometheus.GaugeOpts{
-		Name: "ntfy_message_publish_duration_ms",
-	})
-	metricFirebasePublishedSuccess = prometheus.NewCounter(prometheus.CounterOpts{
-		Name: "ntfy_firebase_published_success",
-	})
-	metricFirebasePublishedFailure = prometheus.NewCounter(prometheus.CounterOpts{
-		Name: "ntfy_firebase_published_failure",
-	})
-	metricEmailsPublishedSuccess = prometheus.NewCounter(prometheus.CounterOpts{
-		Name: "ntfy_emails_sent_success",
-	})
-	metricEmailsPublishedFailure = prometheus.NewCounter(prometheus.CounterOpts{
-		Name: "ntfy_emails_sent_failure",
-	})
-	metricEmailsReceivedSuccess = prometheus.NewCounter(prometheus.CounterOpts{
-		Name: "ntfy_emails_received_success",
-	})
-	metricEmailsReceivedFailure = prometheus.NewCounter(prometheus.CounterOpts{
-		Name: "ntfy_emails_received_failure",
-	})
-	metricCallsMadeSuccess = prometheus.NewCounter(prometheus.CounterOpts{
-		Name: "ntfy_calls_made_success",
-	})
-	metricCallsMadeFailure = prometheus.NewCounter(prometheus.CounterOpts{
-		Name: "ntfy_calls_made_failure",
-	})
-	metricUnifiedPushPublishedSuccess = prometheus.NewCounter(prometheus.CounterOpts{
-		Name: "ntfy_unifiedpush_published_success",
-	})
-	metricMatrixPublishedSuccess = prometheus.NewCounter(prometheus.CounterOpts{
-		Name: "ntfy_matrix_published_success",
-	})
-	metricMatrixPublishedFailure = prometheus.NewCounter(prometheus.CounterOpts{
-		Name: "ntfy_matrix_published_failure",
-	})
-	metricAttachmentsTotalSize = prometheus.NewGauge(prometheus.GaugeOpts{
-		Name: "ntfy_attachments_total_size",
-	})
-	metricVisitors = prometheus.NewGauge(prometheus.GaugeOpts{
-		Name: "ntfy_visitors_total",
-	})
-	metricUsers = prometheus.NewGauge(prometheus.GaugeOpts{
-		Name: "ntfy_users_total",
-	})
-	metricSubscribers = prometheus.NewGauge(prometheus.GaugeOpts{
-		Name: "ntfy_subscribers_total",
-	})
-	metricTopics = prometheus.NewGauge(prometheus.GaugeOpts{
-		Name: "ntfy_topics_total",
-	})
-	metricHTTPRequests = prometheus.NewCounterVec(prometheus.CounterOpts{
-		Name: "ntfy_http_requests_total",
-	}, []string{"http_code", "ntfy_code", "http_method"})
-	prometheus.MustRegister(
-		metricMessagesPublishedSuccess,
-		metricMessagesPublishedFailure,
-		metricMessagesCached,
-		metricMessagePublishDurationMillis,
-		metricFirebasePublishedSuccess,
-		metricFirebasePublishedFailure,
-		metricEmailsPublishedSuccess,
-		metricEmailsPublishedFailure,
-		metricEmailsReceivedSuccess,
-		metricEmailsReceivedFailure,
-		metricCallsMadeSuccess,
-		metricCallsMadeFailure,
-		metricUnifiedPushPublishedSuccess,
-		metricMatrixPublishedSuccess,
-		metricMatrixPublishedFailure,
-		metricAttachmentsTotalSize,
-		metricVisitors,
-		metricUsers,
-		metricSubscribers,
-		metricTopics,
-		metricHTTPRequests,
-	)
-}
-
-// minc increments a prometheus.Counter if it is non-nil
-func minc(counter prometheus.Counter) {
-	if counter != nil {
-		counter.Inc()
-	}
-}
-
-// mset sets a prometheus.Gauge if it is non-nil
-func mset[T int | int64 | float64](gauge prometheus.Gauge, value T) {
-	if gauge != nil {
-		gauge.Set(float64(value))
-	}
-}

server/server_middleware.go

@@ -3,6 +3,7 @@ package server
 import (
 	"net/http"
 
+	"heckel.io/ntfy/v2/user"
 	"heckel.io/ntfy/v2/util"
 )
 
@@ -12,6 +13,7 @@ const (
 	contextRateVisitor contextKey = iota + 2586
 	contextTopic
 	contextMatrixPushKey
+	contextVisitorIP // Client IP extracted in maybeAuthenticate; reused by the abuse ban-feed (see ban.Service.Record)
 )
 
 func (s *Server) limitRequests(next handleFunc) handleFunc {
@@ -139,3 +141,31 @@ func (s *Server) withAccountSync(next handleFunc) handleFunc {
 		return err
 	}
 }
+
+func (s *Server) authorizeTopicWrite(next handleFunc) handleFunc {
+	return s.authorizeTopic(next, user.PermissionWrite)
+}
+
+func (s *Server) authorizeTopicRead(next handleFunc) handleFunc {
+	return s.authorizeTopic(next, user.PermissionRead)
+}
+
+func (s *Server) authorizeTopic(next handleFunc, perm user.Permission) handleFunc {
+	return func(w http.ResponseWriter, r *http.Request, v *visitor) error {
+		if s.userManager == nil {
+			return next(w, r, v)
+		}
+		topics, _, err := s.topicsFromPath(v, r.URL.Path)
+		if err != nil {
+			return err
+		}
+		u := v.User()
+		for _, t := range topics {
+			if err := s.userManager.Authorize(u, t.ID, perm); err != nil {
+				logvr(v, r).With(t).Err(err).Debug("Access to topic %s not authorized", t.ID)
+				return errHTTPForbidden.With(t)
+			}
+		}
+		return next(w, r, v)
+	}
+}

server/server_payments_email_test.go

@@ -72,7 +72,7 @@ func TestPayments_Checkout_SendsBillingEmailVerification(t *testing.T) {
 
 		emails, err := s.userManager.Emails(u.ID)
 		require.Nil(t, err)
-		require.Equal(t, []string{"billing@example.com"}, emails)
+		require.Equal(t, []string{"billing@example.com"}, emails.Strings())
 		primary, err := s.userManager.PrimaryEmail(u.ID)
 		require.Nil(t, err)
 		require.Equal(t, "billing@example.com", primary)

server/server_template.go

@@ -0,0 +1,240 @@
+package server
+
+import (
+	"bytes"
+	"context"
+	"embed"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"text/template/parse"
+	"time"
+
+	"gopkg.in/yaml.v2"
+	"heckel.io/ntfy/v2/model"
+	"heckel.io/ntfy/v2/template/gotext"
+	"heckel.io/ntfy/v2/util"
+	"heckel.io/ntfy/v2/util/sprig"
+)
+
+var (
+	//go:embed templates
+	templatesFs  embed.FS // Contains template config files (e.g. grafana.yml, github.yml, ...)
+	templatesDir = "templates"
+
+	templateNameRegex = regexp.MustCompile(`^[-_A-Za-z0-9]+$`)
+
+	// templatePrintfLargeSizeRegex matches a printf directive whose width or precision is a star
+	// (taken from an argument) or has four or more digits, i.e. is at least 1000. It deliberately
+	// scans the flag/width/precision characters after a % without requiring a well-formed
+	// directive: fmt pads even malformed ones (e.g. "%000 9999999#" emits 10 MB), so anything
+	// unrecognized must still be caught.
+	templatePrintfLargeSizeRegex = regexp.MustCompile(`%[-+# 0-9.*\[\]]*(\*|[0-9]{4})`)
+
+	// templateMaxExecutionTime is the wall-clock deadline for a single template render, a DoS guard
+	// (GHSA-rhwf-xgc9-m9fp). It is a var (not a const) solely so tests can raise it; it is never
+	// mutated in production.
+	templateMaxExecutionTime = 100 * time.Millisecond
+)
+
+const (
+	templateMaxOutputBytes   = 1024 * 1024 // Maximum number of bytes a template can output, used to prevent DoS attacks
+	templateMaxTemplateBytes = 32 * 1024   // Maximum size of a template (inline or from a template file), used to prevent DoS attacks
+	templateFileExtension    = ".yml"      // Template files must end with this extension
+)
+
+func (s *Server) handleBodyAsTemplatedTextMessage(ctx context.Context, m *model.Message, template templateMode, body *util.PeekedReadCloser, priorityStr string) error {
+	body, err := util.Peek(body, max(s.config.MessageSizeLimit, jsonBodyBytesLimit))
+	if err != nil {
+		return err
+	} else if body.LimitReached {
+		return errHTTPEntityTooLargeJSONBody
+	}
+	peekedBody := strings.TrimSpace(string(body.PeekedBytes))
+	if template.FileMode() {
+		if err := s.renderTemplateFromFile(ctx, m, template.FileName(), peekedBody); err != nil {
+			return err
+		}
+	} else {
+		if err := s.renderTemplateFromParams(ctx, m, peekedBody, priorityStr); err != nil {
+			return err
+		}
+	}
+	if len(m.Title) > s.config.MessageSizeLimit || len(m.Message) > s.config.MessageSizeLimit {
+		return errHTTPBadRequestTemplateMessageTooLarge
+	}
+	return nil
+}
+
+// renderTemplateFromFile transforms the JSON message body according to a template from the filesystem.
+// The template file must be in the templates directory, or in the configured template directory.
+func (s *Server) renderTemplateFromFile(ctx context.Context, m *model.Message, templateName, peekedBody string) error {
+	if !templateNameRegex.MatchString(templateName) {
+		return errHTTPBadRequestTemplateFileNotFound
+	}
+	templateContent, _ := templatesFs.ReadFile(filepath.Join(templatesDir, templateName+templateFileExtension)) // Read from the embedded filesystem first
+	if s.config.TemplateDir != "" {
+		if b, _ := os.ReadFile(filepath.Join(s.config.TemplateDir, templateName+templateFileExtension)); len(b) > 0 {
+			templateContent = b
+		}
+	}
+	if len(templateContent) == 0 {
+		return errHTTPBadRequestTemplateFileNotFound
+	}
+	var tpl templateFile
+	if err := yaml.Unmarshal(templateContent, &tpl); err != nil {
+		return errHTTPBadRequestTemplateFileInvalid
+	}
+	var err error
+	if tpl.Message != nil {
+		if m.Message, err = s.renderTemplate(ctx, templateName+" (message)", *tpl.Message, peekedBody); err != nil {
+			return err
+		}
+	}
+	if tpl.Title != nil {
+		if m.Title, err = s.renderTemplate(ctx, templateName+" (title)", *tpl.Title, peekedBody); err != nil {
+			return err
+		}
+	}
+	if tpl.Priority != nil {
+		renderedPriority, err := s.renderTemplate(ctx, templateName+" (priority)", *tpl.Priority, peekedBody)
+		if err != nil {
+			return err
+		}
+		if m.Priority, err = util.ParsePriority(renderedPriority); err != nil {
+			return errHTTPBadRequestPriorityInvalid
+		}
+	}
+	return nil
+}
+
+// renderTemplateFromParams transforms the JSON message body according to the inline template in the
+// message, title, and priority parameters.
+func (s *Server) renderTemplateFromParams(ctx context.Context, m *model.Message, peekedBody string, priorityStr string) error {
+	var err error
+	if m.Message, err = s.renderTemplate(ctx, "priority query parameter", m.Message, peekedBody); err != nil {
+		return err
+	}
+	if m.Title, err = s.renderTemplate(ctx, "title query parameter", m.Title, peekedBody); err != nil {
+		return err
+	}
+	if priorityStr != "" {
+		renderedPriority, err := s.renderTemplate(ctx, "priority query parameter", priorityStr, peekedBody)
+		if err != nil {
+			return err
+		}
+		if m.Priority, err = util.ParsePriority(renderedPriority); err != nil {
+			return errHTTPBadRequestPriorityInvalid
+		}
+	}
+	return nil
+}
+
+// renderTemplate renders a template with the given JSON source data.
+func (s *Server) renderTemplate(ctx context.Context, name, tpl, source string) (string, error) {
+	if len(tpl) > templateMaxTemplateBytes {
+		return "", errHTTPBadRequestTemplateTooLarge
+	}
+	var data any
+	if err := json.Unmarshal([]byte(source), &data); err != nil {
+		return "", errHTTPBadRequestTemplateMessageNotJSON
+	}
+	t, err := gotext.New("").Funcs(sprig.TxtFuncMap()).Funcs(gotext.FuncMap{"printf": templatePrintf}).Parse(tpl)
+	if err != nil {
+		return "", errHTTPBadRequestTemplateInvalid.Wrap("%s", err.Error())
+	}
+	if templateUsesDisallowedFeatures(t) {
+		return "", errHTTPBadRequestTemplateDisallowedFunctionCalls
+	}
+	// Bail out of runaway templates (GHSA-rhwf-xgc9-m9fp). The deadline starts here, after the body
+	// has already been read, so a slow upload is not counted against it. Deriving from the request
+	// context means a client disconnect aborts the render too.
+	execCtx, cancel := context.WithTimeout(ctx, templateMaxExecutionTime)
+	defer cancel()
+	var buf bytes.Buffer
+	limitWriter := util.NewLimitWriter(&buf, util.NewFixedLimiter(templateMaxOutputBytes))
+	if err := t.ExecuteContext(execCtx, limitWriter, data); err != nil {
+		if errors.Is(err, context.DeadlineExceeded) {
+			return "", errHTTPBadRequestTemplateExecutionTimeout
+		}
+		return "", errHTTPBadRequestTemplateExecuteFailed.Wrap("template %s: %s", name, err.Error())
+	}
+	return strings.TrimSpace(strings.ReplaceAll(buf.String(), "\\n", "\n")), nil // replace any remaining "\n" (those outside of template curly braces) with newlines
+}
+
+// templateUsesDisallowedFeatures reports whether the parsed template defines or invokes a
+// sub-template ({{define}}/{{block}}/{{template}}) or uses the {{call}} builtin. None are useful for
+// ntfy's JSON-data templates. Checking the parse tree (rather than the raw string) catches every
+// syntactic form -- e.g. {{if call .x}} or {{$y := call .x}} -- that a regex would miss.
+func templateUsesDisallowedFeatures(t *gotext.Template) bool {
+	if len(t.Templates()) > 1 { // {{define}}/{{block}} create additional associated templates
+		return true
+	}
+	return treeContainsDisallowedNode(t.Root)
+}
+
+// treeContainsDisallowedNode reports whether the parse tree contains a {{template}}/{{block}}
+// invocation or a {{call}} builtin, descending into pipes and command arguments (where {{call}} can
+// appear anywhere a function is allowed).
+func treeContainsDisallowedNode(node parse.Node) bool {
+	switch n := node.(type) {
+	case *parse.ListNode:
+		if n == nil {
+			return false
+		}
+		for _, child := range n.Nodes {
+			if treeContainsDisallowedNode(child) {
+				return true
+			}
+		}
+	case *parse.ActionNode:
+		return treeContainsDisallowedNode(n.Pipe)
+	case *parse.RangeNode:
+		return treeContainsDisallowedNode(n.Pipe) || treeContainsDisallowedNode(n.List) || treeContainsDisallowedNode(n.ElseList)
+	case *parse.IfNode:
+		return treeContainsDisallowedNode(n.Pipe) || treeContainsDisallowedNode(n.List) || treeContainsDisallowedNode(n.ElseList)
+	case *parse.WithNode:
+		return treeContainsDisallowedNode(n.Pipe) || treeContainsDisallowedNode(n.List) || treeContainsDisallowedNode(n.ElseList)
+	case *parse.TemplateNode: // {{template}} or {{block}} invocation
+		return true
+	case *parse.ChainNode: // A term followed by field accesses, e.g. (call .x).y
+		return treeContainsDisallowedNode(n.Node)
+	case *parse.PipeNode:
+		if n == nil {
+			return false
+		}
+		for _, cmd := range n.Cmds {
+			if treeContainsDisallowedNode(cmd) {
+				return true
+			}
+		}
+	case *parse.CommandNode:
+		for _, arg := range n.Args {
+			if treeContainsDisallowedNode(arg) {
+				return true
+			}
+		}
+	case *parse.IdentifierNode: // a function name; {{call}} is the disallowed builtin
+		return n.Ident == "call"
+	}
+	return false
+}
+
+// templatePrintf is the template builtin printf, guarded against memory amplification: fmt
+// allows widths and precisions up to 1e6 per verb, so a small template like
+// {{printf "%999999d%999999d..." ...}} can allocate gigabytes inside a single fmt call -- and the
+// executor's cancellation context is only checked between template nodes, never inside one.
+// Widths and precisions of 1000 or more are therefore rejected, as is the star (*) form, which
+// takes the width from an argument. Combined with the template size limit, this bounds a single
+// render to a few MB. Registered via Funcs, which takes precedence over the builtin, and checked
+// at call time so a format string assembled during execution is covered too.
+func templatePrintf(format string, args ...any) (string, error) {
+	if templatePrintfLargeSizeRegex.MatchString(strings.ReplaceAll(format, "%%", "")) { // Strip escaped percent signs, they take no width
+		return "", errors.New("printf width or precision too large")
+	}
+	return fmt.Sprintf(format, args...), nil
+}

server/server_template_test.go

@@ -0,0 +1,131 @@
+package server
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestServer_MessageTemplate_TooLarge(t *testing.T) {
+	forEachBackend(t, func(t *testing.T, databaseURL string) {
+		t.Parallel()
+		s := newTestServer(t, newTestConfig(t, databaseURL))
+		response := request(t, s, "PUT", "/mytopic", `{"foo":"bar"}`, map[string]string{
+			"X-Message":  "{{.foo}}" + strings.Repeat("x", 33*1024),
+			"X-Template": "1",
+		})
+		require.Equal(t, 400, response.Code)
+		require.Equal(t, 40056, toHTTPError(t, response.Body.String()).Code)
+	})
+}
+
+func TestServer_MessageTemplate_PrintfWidthTooLarge(t *testing.T) {
+	forEachBackend(t, func(t *testing.T, databaseURL string) {
+		t.Parallel()
+		s := newTestServer(t, newTestConfig(t, databaseURL))
+		// A handful of 1MB-wide verbs would allocate several MB inside a single fmt call, where
+		// the executor's context is never checked; the printf guard must reject the call before
+		// fmt runs, not after the limit writer sees the output
+		response := request(t, s, "PUT", "/mytopic", `{"n":1}`, map[string]string{
+			"X-Message":  `{{printf "%1000000d%1000000d%1000000d" .n .n .n}}`,
+			"X-Template": "1",
+		})
+		require.Equal(t, 400, response.Code)
+		require.Equal(t, 40045, toHTTPError(t, response.Body.String()).Code)
+		require.Contains(t, response.Body.String(), "printf width or precision too large")
+	})
+}
+
+func TestServer_MessageTemplate_PrintfWidthTooLarge_DynamicFormat(t *testing.T) {
+	forEachBackend(t, func(t *testing.T, databaseURL string) {
+		t.Parallel()
+		s := newTestServer(t, newTestConfig(t, databaseURL))
+		// The format string is assembled at execution time, so the guard must inspect the actual
+		// argument, not the template source
+		response := request(t, s, "PUT", "/mytopic", `{"n":1}`, map[string]string{
+			"X-Message":  `{{$f := print "%" "999999" "d" "%" "999999" "d"}}{{printf $f .n .n}}`,
+			"X-Template": "1",
+		})
+		require.Equal(t, 400, response.Code)
+		require.Contains(t, response.Body.String(), "printf width or precision too large")
+	})
+}
+
+func TestServer_MessageTemplate_PrintfStarWidthTooLarge(t *testing.T) {
+	forEachBackend(t, func(t *testing.T, databaseURL string) {
+		t.Parallel()
+		s := newTestServer(t, newTestConfig(t, databaseURL))
+		// Star widths take the width from an argument; sprig's math functions (int64 results)
+		// make large integer arguments reachable from a template
+		response := request(t, s, "PUT", "/mytopic", `{"n":1}`, map[string]string{
+			"X-Message":  `{{printf "%*d" (mul 1000 2000) 1}}`,
+			"X-Template": "1",
+		})
+		require.Equal(t, 400, response.Code)
+		require.Contains(t, response.Body.String(), "printf width or precision too large")
+	})
+}
+
+func TestServer_MessageTemplate_PrintfSmallWidthStillWorks(t *testing.T) {
+	forEachBackend(t, func(t *testing.T, databaseURL string) {
+		t.Parallel()
+		s := newTestServer(t, newTestConfig(t, databaseURL))
+		response := request(t, s, "PUT", "/mytopic", `{"n":7}`, map[string]string{
+			"X-Message":  `{{printf "%05d" 7}}`,
+			"X-Template": "1",
+		})
+		require.Equal(t, 200, response.Code)
+		require.Equal(t, "00007", toMessage(t, response.Body.String()).Message)
+	})
+}
+
+func Test_templatePrintf(t *testing.T) {
+	tests := []struct {
+		format string
+		args   []any
+		want   string // Empty means the call must be rejected
+	}{
+		{"%d", []any{5}, "5"},
+		{"%05d", []any{5}, "00005"},
+		{"%-8.3f|", []any{1.5}, "1.500   |"},
+		{"%1000d", []any{1}, ""}, // Rejected: four digits
+		{"%.1000s", []any{"x"}, ""},
+		{"%*d", []any{500, 1}, ""},                           // Rejected: star width
+		{"%.*s", []any{400, "x"}, ""},                        // Rejected: star precision
+		{"%[1]1000000d", []any{1}, ""},                       // Rejected: explicit arg index does not hide the width
+		{"%[2]*[1]d", []any{6, 12}, ""},                      // Rejected: star width behind an arg index
+		{"100%% of 2024 values", nil, "100% of 2024 values"}, // Literal digits are not a width
+	}
+	for _, test := range tests {
+		out, err := templatePrintf(test.format, test.args...)
+		if test.want == "" {
+			require.Error(t, err, "format %q must be rejected", test.format)
+			require.Contains(t, err.Error(), "too large")
+		} else {
+			require.Nil(t, err, "format %q", test.format)
+			require.Equal(t, test.want, out)
+		}
+	}
+
+	// The largest allowed width still produces bounded output
+	out, err := templatePrintf("%999d", 1)
+	require.Nil(t, err)
+	require.Len(t, out, 999)
+}
+
+func TestServer_MessageTemplate_DisallowedCallInChain(t *testing.T) {
+	forEachBackend(t, func(t *testing.T, databaseURL string) {
+		t.Parallel()
+		s := newTestServer(t, newTestConfig(t, databaseURL))
+		// {{call}} behind a field access parses into a ChainNode. JSON data cannot produce a
+		// function value, so this cannot be exploited today, but the ban must catch every
+		// syntactic form rather than relying on the call failing at runtime.
+		response := request(t, s, "PUT", "/mytopic", `{"fn":1}`, map[string]string{
+			"X-Message":  `{{(call .fn).x}}`,
+			"X-Template": "1",
+		})
+		require.Equal(t, 400, response.Code)
+		require.Equal(t, 40044, toHTTPError(t, response.Body.String()).Code)
+	})
+}

server/server_test.go

@@ -22,6 +22,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/prometheus/client_golang/prometheus/promhttp"
 	"github.com/stretchr/testify/require"
 	"golang.org/x/crypto/bcrypt"
 	dbtest "heckel.io/ntfy/v2/db/test"
@@ -323,6 +324,40 @@ func TestServer_WebEnabled(t *testing.T) {
 		require.Equal(t, 200, rr.Code)
 	})
 }
+
+// TestServer_MetricsEnabled ensures that the /metrics endpoint serves the registered ntfy metrics
+// once the metrics handler is set (as Serve does when enable-metrics is configured).
+func TestServer_MetricsEnabled(t *testing.T) {
+	forEachBackend(t, func(t *testing.T, databaseURL string) {
+		s := newTestServer(t, newTestConfig(t, databaseURL))
+		s.metricsHandler = promhttp.Handler() // Serve sets this when enable-metrics is configured
+
+		// Count at least one request first: Prometheus only reports a CounterVec such as
+		// ntfy_http_requests_total once it has children
+		request(t, s, "GET", "/v1/health", "", nil)
+
+		rr := request(t, s, "GET", "/metrics", "", nil)
+		require.Equal(t, 200, rr.Code)
+		require.Contains(t, rr.Body.String(), "ntfy_messages_published_success")
+		require.Contains(t, rr.Body.String(), "ntfy_http_requests_total")
+	})
+}
+
+// TestServer_MetricsDisabled ensures that the ntfy metrics are not exposed when the metrics handler
+// is unset (the default). The collectors are always registered with the Prometheus registry, so a
+// nil metrics handler is the only thing keeping them off the wire.
+func TestServer_MetricsDisabled(t *testing.T) {
+	forEachBackend(t, func(t *testing.T, databaseURL string) {
+		conf := newTestConfig(t, databaseURL)
+		conf.WebRoot = "" // Disable the web app, so its catch-all does not mask the /metrics route
+		s := newTestServer(t, conf)
+
+		rr := request(t, s, "GET", "/metrics", "", nil)
+		require.Equal(t, 404, rr.Code)
+		require.NotContains(t, rr.Body.String(), "ntfy_messages_published_success")
+	})
+}
+
 func TestServer_PublishLargeMessage(t *testing.T) {
 	forEachBackend(t, func(t *testing.T, databaseURL string) {
 		c := newTestConfig(t, databaseURL)
@@ -1684,6 +1719,7 @@ func TestServer_PublishEmailVerify_BoolValueUsesPrimary(t *testing.T) {
 			"Authorization": util.BasicAuth("phil", "phil"),
 		})
 		require.Equal(t, 200, response.Code)
+		waitFor(t, func() bool { return mailer.LastTo() != "" }) // E-Mail publishing happens in a Go routine
 		require.Equal(t, "zzz@example.com", mailer.LastTo())
 	})
 }
@@ -1710,6 +1746,7 @@ func TestServer_PublishEmailVerify_BoolValueNoVerifyUsesPrimary(t *testing.T) {
 			"Authorization": util.BasicAuth("phil", "phil"),
 		})
 		require.Equal(t, 200, response.Code)
+		waitFor(t, func() bool { return mailer.LastTo() != "" }) // E-Mail publishing happens in a Go routine
 		require.Equal(t, "zzz@example.com", mailer.LastTo())
 	})
 }
@@ -1751,6 +1788,7 @@ func TestServer_PublishEmailVerify_BoolValueProvisionedUsesPrimary(t *testing.T)
 			"Authorization": util.BasicAuth("prov", "provpass"),
 		})
 		require.Equal(t, 200, response.Code)
+		waitFor(t, func() bool { return mailer.LastTo() != "" }) // E-Mail publishing happens in a Go routine
 		require.Equal(t, "zzz@example.com", mailer.LastTo())
 	})
 }
@@ -2851,7 +2889,7 @@ func TestServer_Visitor_XForwardedFor_None(t *testing.T) {
 		r, _ := http.NewRequest("GET", "/bla", nil)
 		r.RemoteAddr = "8.9.10.11:1234"
 		r.Header.Set("X-Forwarded-For", "  ") // Spaces, not empty!
-		v, err := s.maybeAuthenticate(r)
+		_, v, err := s.maybeAuthenticate(r)
 		require.Nil(t, err)
 		require.Equal(t, "8.9.10.11", v.ip.String())
 	})
@@ -2865,7 +2903,7 @@ func TestServer_Visitor_XForwardedFor_Single(t *testing.T) {
 		r, _ := http.NewRequest("GET", "/bla", nil)
 		r.RemoteAddr = "8.9.10.11:1234"
 		r.Header.Set("X-Forwarded-For", "1.1.1.1")
-		v, err := s.maybeAuthenticate(r)
+		_, v, err := s.maybeAuthenticate(r)
 		require.Nil(t, err)
 		require.Equal(t, "1.1.1.1", v.ip.String())
 	})
@@ -2879,7 +2917,7 @@ func TestServer_Visitor_XForwardedFor_Multiple(t *testing.T) {
 		r, _ := http.NewRequest("GET", "/bla", nil)
 		r.RemoteAddr = "8.9.10.11:1234"
 		r.Header.Set("X-Forwarded-For", "1.2.3.4 , 2.4.4.2,234.5.2.1 ")
-		v, err := s.maybeAuthenticate(r)
+		_, v, err := s.maybeAuthenticate(r)
 		require.Nil(t, err)
 		require.Equal(t, "234.5.2.1", v.ip.String())
 	})
@@ -2894,7 +2932,7 @@ func TestServer_Visitor_Custom_ClientIP_Header(t *testing.T) {
 		r, _ := http.NewRequest("GET", "/bla", nil)
 		r.RemoteAddr = "8.9.10.11:1234"
 		r.Header.Set("X-Client-IP", "1.2.3.4")
-		v, err := s.maybeAuthenticate(r)
+		_, v, err := s.maybeAuthenticate(r)
 		require.Nil(t, err)
 		require.Equal(t, "1.2.3.4", v.ip.String())
 	})
@@ -2909,7 +2947,7 @@ func TestServer_Visitor_Custom_ClientIP_Header_IPv6(t *testing.T) {
 		r, _ := http.NewRequest("GET", "/bla", nil)
 		r.RemoteAddr = "[2001:db8:9999::1]:1234"
 		r.Header.Set("X-Client-IP", "2001:db8:7777::1")
-		v, err := s.maybeAuthenticate(r)
+		_, v, err := s.maybeAuthenticate(r)
 		require.Nil(t, err)
 		require.Equal(t, "2001:db8:7777::1", v.ip.String())
 	})
@@ -2925,7 +2963,7 @@ func TestServer_Visitor_Custom_Forwarded_Header(t *testing.T) {
 		r, _ := http.NewRequest("GET", "/bla", nil)
 		r.RemoteAddr = "8.9.10.11:1234"
 		r.Header.Set("Forwarded", " for=5.6.7.8, by=example.com;for=1.2.3.4")
-		v, err := s.maybeAuthenticate(r)
+		_, v, err := s.maybeAuthenticate(r)
 		require.Nil(t, err)
 		require.Equal(t, "5.6.7.8", v.ip.String())
 	})
@@ -2941,7 +2979,7 @@ func TestServer_Visitor_Custom_Forwarded_Header_IPv6(t *testing.T) {
 		r, _ := http.NewRequest("GET", "/bla", nil)
 		r.RemoteAddr = "[2001:db8:2222::1]:1234"
 		r.Header.Set("Forwarded", " for=[2001:db8:1111::1], by=example.com;for=[2001:db8:3333::1]")
-		v, err := s.maybeAuthenticate(r)
+		_, v, err := s.maybeAuthenticate(r)
 		require.Nil(t, err)
 		require.Equal(t, "2001:db8:3333::1", v.ip.String())
 	})
@@ -3635,6 +3673,184 @@ func TestServer_MessageTemplate_Range(t *testing.T) {
 	})
 }
 
+func TestServer_MessageTemplate_ExecutionTimeout(t *testing.T) {
+	forEachBackend(t, func(t *testing.T, databaseURL string) {
+		t.Parallel()
+		s := newTestServer(t, newTestConfig(t, databaseURL))
+		// Nested range over a 1000-element JSON field with a no-output body: no Write ever happens,
+		// so the write-triggered TimeoutWriter never fires. Must be bounded by the executor's
+		// wall-clock deadline instead (GHSA-rhwf-xgc9-m9fp).
+		elems := make([]string, 1000)
+		for i := range elems {
+			elems[i] = "0"
+		}
+		jsonBody := `{"a":[` + strings.Join(elems, ",") + `]}`
+		msg := `{{range .a}}{{range $.a}}` + strings.Repeat(`{{$x := .}}`, 100) + `{{end}}{{end}}done`
+		start := time.Now()
+		response := request(t, s, "POST", "/mytopic", jsonBody, map[string]string{
+			"X-Message":  msg,
+			"X-Template": "1",
+		})
+		elapsed := time.Since(start)
+		require.Equal(t, 400, response.Code)
+		require.Equal(t, 40055, toHTTPError(t, response.Body.String()).Code)
+		require.Less(t, elapsed, 500*time.Millisecond, "template must be interrupted by the deadline, not run to completion (took %s)", elapsed)
+	})
+}
+
+// TestServer_MessageTemplate_DataDrivenNestedRange_TimesOut is the regression for the exact hole the
+// old write-triggered TimeoutWriter missed: a nested {{range}} over a JSON array field with a
+// no-output body calls no function, so only the executor's wall-clock deadline can stop it
+// (GHSA-rhwf-xgc9-m9fp).
+func TestServer_MessageTemplate_DataDrivenNestedRange_TimesOut(t *testing.T) {
+	forEachBackend(t, func(t *testing.T, databaseURL string) {
+		t.Parallel()
+		s := newTestServer(t, newTestConfig(t, databaseURL))
+		elems := make([]string, 1000)
+		for i := range elems {
+			elems[i] = "0"
+		}
+		jsonBody := `{"a":[` + strings.Join(elems, ",") + `]}`
+		msg := `{{range .a}}{{range $.a}}{{range $.a}}{{$x := .}}{{end}}{{end}}{{end}}done`
+		start := time.Now()
+		response := request(t, s, "POST", "/mytopic", jsonBody, map[string]string{
+			"X-Message":  msg,
+			"X-Template": "1",
+		})
+		elapsed := time.Since(start)
+		require.Equal(t, 400, response.Code)
+		require.Equal(t, 40055, toHTTPError(t, response.Body.String()).Code)
+		require.Less(t, elapsed, 500*time.Millisecond, "data-driven nested range should be cut off by the deadline (took %s)", elapsed)
+	})
+}
+
+// TestServer_MessageTemplate_ExpensiveFunctionLoop_TimesOut ensures the deadline also bounds loops
+// whose body calls an expensive function (hashing a large string), where a single call between
+// deadline checks could otherwise overshoot (GHSA-rhwf-xgc9-m9fp).
+func TestServer_MessageTemplate_ExpensiveFunctionLoop_TimesOut(t *testing.T) {
+	forEachBackend(t, func(t *testing.T, databaseURL string) {
+		t.Parallel()
+		s := newTestServer(t, newTestConfig(t, databaseURL))
+		msg := `{{$big := repeat 990 "0123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789"}}{{range until 1000}}{{range until 1000}}{{$h := sha512sum $big}}{{end}}{{end}}`
+		start := time.Now()
+		response := request(t, s, "POST", "/mytopic", `{}`, map[string]string{
+			"X-Message":  msg,
+			"X-Template": "1",
+		})
+		elapsed := time.Since(start)
+		require.Equal(t, 400, response.Code)
+		require.Equal(t, 40055, toHTTPError(t, response.Body.String()).Code)
+		require.Less(t, elapsed, 1500*time.Millisecond, "expensive-function loop should be cut off by the deadline (took %s)", elapsed)
+	})
+}
+
+// TestServer_MessageTemplate_NestedLoopPoC_TimesOut is the exact proof-of-concept from the advisory:
+// a range over a runtime-computed slice, nested, must be bounded by the deadline (GHSA-rhwf-xgc9-m9fp).
+func TestServer_MessageTemplate_NestedLoopPoC_TimesOut(t *testing.T) {
+	forEachBackend(t, func(t *testing.T, databaseURL string) {
+		t.Parallel()
+		s := newTestServer(t, newTestConfig(t, databaseURL))
+		start := time.Now()
+		response := request(t, s, "POST", "/mytopic", `{}`, map[string]string{
+			"X-Message":  `{{$x := until 10000}}{{range $x}}{{range $x}}{{end}}{{end}}done`,
+			"X-Template": "1",
+		})
+		elapsed := time.Since(start)
+		require.Equal(t, 400, response.Code)
+		require.Equal(t, 40055, toHTTPError(t, response.Body.String()).Code)
+		require.Less(t, elapsed, 500*time.Millisecond, "advisory PoC should be cut off by the deadline (took %s)", elapsed)
+	})
+}
+
+func TestServer_MessageTemplate_GenuineError_NotTimeout(t *testing.T) {
+	forEachBackend(t, func(t *testing.T, databaseURL string) {
+		t.Parallel()
+		s := newTestServer(t, newTestConfig(t, databaseURL))
+		// A real runtime error (len of an int) must map to execute-failed, not the timeout code.
+		response := request(t, s, "POST", "/mytopic", `{}`, map[string]string{
+			"X-Message":  `{{ len 5 }}`,
+			"X-Template": "1",
+		})
+		require.Equal(t, 400, response.Code)
+		require.Equal(t, 40045, toHTTPError(t, response.Body.String()).Code)
+	})
+}
+
+// slowBody delivers its data after a delay, simulating a slow client upload of the request body.
+type slowBody struct {
+	data  []byte
+	delay time.Duration
+	done  bool
+}
+
+func (b *slowBody) Read(p []byte) (int, error) {
+	if b.done {
+		return 0, io.EOF
+	}
+	time.Sleep(b.delay)
+	n := copy(p, b.data)
+	b.done = true
+	return n, nil
+}
+
+func (b *slowBody) Close() error { return nil }
+
+// TestServer_MessageTemplate_SlowUpload_NotCountedAgainstDeadline verifies that a slow request-body
+// upload does not consume the template execution deadline: the body is fully read (util.Peek)
+// before the deadline starts, so a trivial template still renders even when the upload alone took
+// longer than the deadline (GHSA-rhwf-xgc9-m9fp).
+func TestServer_MessageTemplate_SlowUpload_NotCountedAgainstDeadline(t *testing.T) {
+	s := newTestServer(t, newTestConfig(t, ""))
+	start := time.Now()
+	// The template runs in ~1ms, far under the deadline, so on correct code it renders fine; the
+	// point is that the deadline starts at execution, not when the (slow) upload began.
+	response := request(t, s, "POST", "/mytopic", `{"foo":"bar"}`, map[string]string{
+		"Template":  "yes",
+		"X-Message": `{{range until 5000}}{{$x := .}}{{end}}hello {{.foo}}`,
+	}, func(r *http.Request) {
+		r.Body = &slowBody{data: []byte(`{"foo":"bar"}`), delay: 3 * templateMaxExecutionTime}
+	})
+	elapsed := time.Since(start)
+	require.Greater(t, elapsed, templateMaxExecutionTime, "the slow upload must outlast the exec deadline for this test to be meaningful")
+	require.Equal(t, 200, response.Code) // Would be 40055 if upload time counted against the deadline
+	m := toMessage(t, response.Body.String())
+	require.Equal(t, "hello bar", m.Message)
+}
+
+// TestServer_MessageTemplate_ClientDisconnect_CancelsRender verifies that canceling the request
+// context (e.g. the client disconnecting) aborts an in-progress template render. The execution
+// deadline is raised well above the cancel delay for this test so that cancellation -- not the
+// deadline -- is what stops the render: a runaway template is canceled 500ms in and must abort
+// shortly after (well under the raised deadline), yielding the generic execute-failed code (40045),
+// not the timeout code (40055).
+//
+// Not parallel: it temporarily raises the package-global templateMaxExecutionTime. Non-parallel
+// tests run in their own phase (parallel tests are paused), so the override is race-free.
+func TestServer_MessageTemplate_ClientDisconnect_CancelsRender(t *testing.T) {
+	origDeadline := templateMaxExecutionTime
+	templateMaxExecutionTime = 30 * time.Second // large enough that only the cancel can stop the render
+	defer func() { templateMaxExecutionTime = origDeadline }()
+
+	s := newTestServer(t, newTestConfig(t, ""))
+	ctx, cancel := context.WithCancel(context.Background())
+	go func() {
+		time.Sleep(500 * time.Millisecond)
+		cancel()
+	}()
+	start := time.Now()
+	response := request(t, s, "POST", "/mytopic", `{}`, map[string]string{
+		"X-Message":  `{{$x := until 10000}}{{range $x}}{{range $x}}{{end}}{{end}}done`,
+		"X-Template": "1",
+	}, func(r *http.Request) {
+		*r = *r.WithContext(ctx)
+	})
+	elapsed := time.Since(start)
+	require.Equal(t, 400, response.Code)
+	require.Equal(t, 40045, toHTTPError(t, response.Body.String()).Code, "a canceled render should map to execute-failed, not the timeout code 40055")
+	require.Greater(t, elapsed, 500*time.Millisecond, "render must still be running when the cancel fires (took %s)", elapsed)
+	require.Less(t, elapsed, 700*time.Millisecond, "request-context cancel should abort the render promptly after firing (took %s)", elapsed)
+}
+
 func TestServer_MessageTemplate_ExceedMessageSize_TemplatedMessageOK(t *testing.T) {
 	forEachBackend(t, func(t *testing.T, databaseURL string) {
 		t.Parallel()
@@ -3729,11 +3945,18 @@ func TestServer_MessageTemplate_DisallowedCalls(t *testing.T) {
 			`{{- template ""}}`,
 			`{{-
 template ""}}`,
-			`{{      call abc}}`,
-			`{{      define "aa"}}`,
-			`We cannot {{define "aa"}}`,
+			`{{ call "aa"}}`,
+			`{{define "aa"}}hi{{end}}`,
+			`We cannot {{define "aa"}}hi{{end}}`,
 			`We cannot {{ call "aa"}}`,
 			`We cannot {{- template "aa"}}`,
+			`{{block "aa" .}}hi{{end}}`,
+			`We cannot {{- block "aa" .}}hi{{end}}`,
+			// call is a function, not a keyword, so it can hide in non-leading positions that a
+			// raw-string regex misses -- the parse-tree walk catches all of them.
+			`{{if call .x}}x{{end}}`,
+			`{{$y := call .x}}`,
+			`{{index (call .x) 0}}`,
 		}
 		for _, disallowedTemplate := range disallowedTemplates {
 			messageTemplate := disallowedTemplate
@@ -4139,6 +4362,40 @@ func TestServer_DeleteMessage(t *testing.T) {
 	})
 }
 
+func TestServer_DeleteMessage_GET(t *testing.T) {
+	forEachBackend(t, func(t *testing.T, databaseURL string) {
+		t.Parallel()
+		s := newTestServer(t, newTestConfig(t, databaseURL))
+
+		// Publish a message with a sequence ID
+		response := request(t, s, "PUT", "/mytopic/seq123", "original message", nil)
+		require.Equal(t, 200, response.Code)
+		msg := toMessage(t, response.Body.String())
+		require.Equal(t, "seq123", msg.SequenceID)
+		require.Equal(t, "message", msg.Event)
+
+		// Delete the message using GET method (/topic/seq/delete)
+		response = request(t, s, "GET", "/mytopic/seq123/delete", "", nil)
+		require.Equal(t, 200, response.Code)
+		deleteMsg := toMessage(t, response.Body.String())
+		require.Equal(t, "seq123", deleteMsg.SequenceID)
+		require.Equal(t, "message_delete", deleteMsg.Event)
+
+		// Poll and verify both messages are returned
+		response = request(t, s, "GET", "/mytopic/json?poll=1", "", nil)
+		require.Equal(t, 200, response.Code)
+		lines := strings.Split(strings.TrimSpace(response.Body.String()), "\n")
+		require.Equal(t, 2, len(lines))
+
+		msg1 := toMessage(t, lines[0])
+		msg2 := toMessage(t, lines[1])
+		require.Equal(t, "message", msg1.Event)
+		require.Equal(t, "message_delete", msg2.Event)
+		require.Equal(t, "seq123", msg1.SequenceID)
+		require.Equal(t, "seq123", msg2.SequenceID)
+	})
+}
+
 func TestServer_ClearMessage(t *testing.T) {
 	forEachBackend(t, func(t *testing.T, databaseURL string) {
 		t.Parallel()
@@ -4192,6 +4449,33 @@ func TestServer_ClearMessage_ReadEndpoint(t *testing.T) {
 	})
 }
 
+func TestServer_ClearMessage_GET(t *testing.T) {
+	forEachBackend(t, func(t *testing.T, databaseURL string) {
+		t.Parallel()
+		s := newTestServer(t, newTestConfig(t, databaseURL))
+
+		// 1. Test GET /topic/seq-id/clear
+		response := request(t, s, "PUT", "/mytopic/seq456", "original message 1", nil)
+		require.Equal(t, 200, response.Code)
+
+		response = request(t, s, "GET", "/mytopic/seq456/clear", "", nil)
+		require.Equal(t, 200, response.Code)
+		clearMsg1 := toMessage(t, response.Body.String())
+		require.Equal(t, "seq456", clearMsg1.SequenceID)
+		require.Equal(t, "message_clear", clearMsg1.Event)
+
+		// 2. Test GET /topic/seq-id/read
+		response = request(t, s, "PUT", "/mytopic/seq789", "original message 2", nil)
+		require.Equal(t, 200, response.Code)
+
+		response = request(t, s, "GET", "/mytopic/seq789/read", "", nil)
+		require.Equal(t, 200, response.Code)
+		clearMsg2 := toMessage(t, response.Body.String())
+		require.Equal(t, "seq789", clearMsg2.SequenceID)
+		require.Equal(t, "message_clear", clearMsg2.Event)
+	})
+}
+
 func TestServer_UpdateMessage(t *testing.T) {
 	forEachBackend(t, func(t *testing.T, databaseURL string) {
 		t.Parallel()
@@ -4399,6 +4683,41 @@ func TestServer_DeleteScheduledMessage(t *testing.T) {
 	})
 }
 
+func TestServer_DeleteScheduledMessage_GET(t *testing.T) {
+	forEachBackend(t, func(t *testing.T, databaseURL string) {
+		t.Parallel()
+		s := newTestServer(t, newTestConfig(t, databaseURL))
+
+		// Publish a scheduled message (future delivery)
+		response := request(t, s, "PUT", "/mytopic/delete-sched-seq?delay=1h", "scheduled message to delete", nil)
+		require.Equal(t, 200, response.Code)
+		msg := toMessage(t, response.Body.String())
+		require.Equal(t, "delete-sched-seq", msg.SequenceID)
+
+		// Verify scheduled message exists
+		response = request(t, s, "GET", "/mytopic/json?poll=1&scheduled=1", "", nil)
+		require.Equal(t, 200, response.Code)
+		messages := toMessages(t, response.Body.String())
+		require.Equal(t, 1, len(messages))
+		require.Equal(t, "scheduled message to delete", messages[0].Message)
+
+		// Delete the scheduled message using GET method (/topic/seq/delete)
+		response = request(t, s, "GET", "/mytopic/delete-sched-seq/delete", "", nil)
+		require.Equal(t, 200, response.Code)
+		deleteMsg := toMessage(t, response.Body.String())
+		require.Equal(t, "delete-sched-seq", deleteMsg.SequenceID)
+		require.Equal(t, "message_delete", deleteMsg.Event)
+
+		// Verify scheduled message was deleted, only delete event remains
+		response = request(t, s, "GET", "/mytopic/json?poll=1&scheduled=1", "", nil)
+		require.Equal(t, 200, response.Code)
+		messages = toMessages(t, response.Body.String())
+		require.Equal(t, 1, len(messages))
+		require.Equal(t, "message_delete", messages[0].Event)
+		require.Equal(t, "delete-sched-seq", messages[0].SequenceID)
+	})
+}
+
 func TestServer_UpdateScheduledMessage_TopicScoped(t *testing.T) {
 	forEachBackend(t, func(t *testing.T, databaseURL string) {
 		t.Parallel()
@@ -4899,3 +5218,46 @@ func TestServer_Publish_InvalidUTF8WithFirebase(t *testing.T) {
 	require.Equal(t, "\uFFFDclipse", sender.Messages()[0].Data["title"])
 	require.Equal(t, "probl\uFFFDme", sender.Messages()[0].Data["tags"])
 }
+
+func TestServer_BanFeed_RateLimitedIPBanned(t *testing.T) {
+	// Real requests: exhaust the visitor request limit so ntfy returns 429s, and confirm the
+	// client IP is written to the ban file after it breaches the per-status ban limit.
+	banFile := filepath.Join(t.TempDir(), "ntfy-ban.log")
+	c := newTestConfig(t, "")
+	c.BanFile = banFile
+	c.BanWindow = time.Minute
+	c.BanThreshold = 2                    // Ban after the weighted budget of 2 is exhausted
+	c.BanWeights = map[string]int{"*": 1} // Every rejection costs 1 strike
+	c.VisitorRequestLimitBurst = 2        // 429 quickly
+	s := newTestServer(t, c)
+	got429 := 0
+	for i := 0; i < 10; i++ {
+		rr := request(t, s, "PUT", "/mytopic", "x", nil)
+		if rr.Code == 429 {
+			got429++
+		}
+	}
+	require.Greater(t, got429, 2)
+	s.ban.Close() // Writes are async (runWriteLoop); Close flushes the buffer before we read
+	data, err := os.ReadFile(banFile)
+	require.NoError(t, err)
+	require.Contains(t, string(data), "9.9.9.9 9.9.9.9/32 429 42901") // <ip> <prefix> <http> <ntfy-code>
+}
+
+func TestServer_BanFeed_SuccessfulRequestsNotBanned(t *testing.T) {
+	// Real requests that all succeed (200) must never trigger a ban, even with a low "*" fallback.
+	banFile := filepath.Join(t.TempDir(), "ntfy-ban.log")
+	c := newTestConfig(t, "")
+	c.BanFile = banFile
+	c.BanWindow = time.Minute
+	c.BanThreshold = 3                    // Low threshold that would catch 200s if 2xx were not skipped
+	c.BanWeights = map[string]int{"*": 1} // Every rejection costs 1 strike
+	c.VisitorRequestLimitBurst = 100      // Stay under the request limit so every request is 200
+	s := newTestServer(t, c)
+	for i := 0; i < 10; i++ {
+		rr := request(t, s, "PUT", "/mytopic", fmt.Sprintf("m%d", i), nil)
+		require.Equal(t, 200, rr.Code)
+	}
+	s.ban.Close() // Flush any buffered bans (there should be none) before asserting no file
+	require.NoFileExists(t, banFile)
+}

server/server_twilio.go

@@ -1,54 +1,13 @@
 package server
 
 import (
-	"bytes"
-	"encoding/xml"
-	"fmt"
-	"io"
-	"net/http"
-	"net/url"
-	"strings"
-	"text/template"
-
-	"heckel.io/ntfy/v2/log"
+	"heckel.io/ntfy/v2/metrics"
 	"heckel.io/ntfy/v2/model"
+	"heckel.io/ntfy/v2/twilio"
 	"heckel.io/ntfy/v2/user"
 	"heckel.io/ntfy/v2/util"
 )
 
-// defaultTwilioCallFormatTemplate is the default TwiML template used for Twilio calls.
-// It can be overridden in the server configuration's twilio-call-format field.
-//
-// The format uses Go template syntax with the following fields:
-// {{.Topic}}, {{.Title}}, {{.Message}}, {{.Priority}}, {{.Tags}}, {{.Sender}}
-// String fields are automatically XML-escaped.
-var defaultTwilioCallFormatTemplate = template.Must(template.New("twiml").Parse(`
-<Response>
-	<Pause length="1"/>
-	<Say loop="3">
-		You have a message from notify on topic {{.Topic}}. Message:
-		<break time="1s"/>
-		{{.Message}}
-		<break time="1s"/>
-		End of message.
-		<break time="1s"/>
-		This message was sent by user {{.Sender}}. It will be repeated three times.
-		To unsubscribe from calls like this, remove your phone number in the notify web app.
-		<break time="3s"/>
-	</Say>
-	<Say>Goodbye.</Say>
-</Response>`))
-
-// twilioCallData holds the data passed to the Twilio call format template
-type twilioCallData struct {
-	Topic    string
-	Title    string
-	Message  string
-	Priority int
-	Tags     []string
-	Sender   string
-}
-
 // convertPhoneNumber checks if the given phone number is verified for the given user, and if so, returns the verified
 // phone number. It also converts a boolean string ("yes", "1", "true") to the first verified phone number.
 // If the user is anonymous, it will return an error.
@@ -67,149 +26,29 @@ func (s *Server) convertPhoneNumber(u *user.User, phoneNumber string) (string, *
 	} else if util.Contains(phoneNumbers, phoneNumber) {
 		return phoneNumber, nil
 	}
-	for _, p := range phoneNumbers {
-		if p == phoneNumber {
-			return phoneNumber, nil
-		}
-	}
 	return "", errHTTPBadRequestPhoneNumberNotVerified
 }
 
 // callPhone calls the Twilio API to make a phone call to the given phone number, using the given message.
 // Failures will be logged, but not returned to the caller.
-func (s *Server) callPhone(v *visitor, r *http.Request, m *model.Message, to string) {
+func (s *Server) callPhone(v *visitor, m *model.Message, to string) {
 	u, sender := v.User(), m.Sender.String()
 	if u != nil {
 		sender = u.Name
 	}
-	tmpl := defaultTwilioCallFormatTemplate
-	if s.config.TwilioCallFormat != nil {
-		tmpl = s.config.TwilioCallFormat
-	}
-	tags := make([]string, len(m.Tags))
-	for i, tag := range m.Tags {
-		tags[i] = xmlEscapeText(tag)
-	}
-	templateData := &twilioCallData{
-		Topic:    xmlEscapeText(m.Topic),
-		Title:    xmlEscapeText(m.Title),
-		Message:  xmlEscapeText(m.Message),
+	logvm(v, m).Tag(tagTwilio).Field("twilio_to", to).Info("Making phone call to %s", to)
+	err := s.twilio.Call(to, &twilio.CallData{
+		Topic:    m.Topic,
+		Title:    m.Title,
+		Message:  m.Message,
 		Priority: m.Priority,
-		Tags:     tags,
-		Sender:   xmlEscapeText(sender),
-	}
-	var bodyBuf bytes.Buffer
-	if err := tmpl.Execute(&bodyBuf, templateData); err != nil {
-		logvrm(v, r, m).Tag(tagTwilio).Err(err).Warn("Error executing Twilio call format template")
-		minc(metricCallsMadeFailure)
+		Tags:     m.Tags,
+		Sender:   sender,
+	})
+	if err != nil {
+		logvm(v, m).Tag(tagTwilio).Field("twilio_to", to).Err(err).Warn("Unable to call phone %s: %v", to, err.Error())
+		metrics.CallsMadeFailure.Inc()
 		return
 	}
-	body := bodyBuf.String()
-	data := url.Values{}
-	data.Set("From", s.config.TwilioPhoneNumber)
-	data.Set("To", to)
-	data.Set("Twiml", body)
-	ev := logvrm(v, r, m).Tag(tagTwilio).Field("twilio_to", to).FieldIf("twilio_body", body, log.TraceLevel).Debug("Sending Twilio request")
-	response, err := s.callPhoneInternal(data)
-	if err != nil {
-		ev.Field("twilio_response", response).Err(err).Warn("Error sending Twilio request")
-		minc(metricCallsMadeFailure)
-		return
-	}
-	ev.FieldIf("twilio_response", response, log.TraceLevel).Debug("Received successful Twilio response")
-	minc(metricCallsMadeSuccess)
-}
-
-func (s *Server) callPhoneInternal(data url.Values) (string, error) {
-	requestURL := fmt.Sprintf("%s/2010-04-01/Accounts/%s/Calls.json", s.config.TwilioCallsBaseURL, s.config.TwilioAccount)
-	req, err := http.NewRequest(http.MethodPost, requestURL, strings.NewReader(data.Encode()))
-	if err != nil {
-		return "", err
-	}
-	req.Header.Set("User-Agent", "ntfy/"+s.config.BuildVersion)
-	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
-	req.Header.Set("Authorization", util.BasicAuth(s.config.TwilioAccount, s.config.TwilioAuthToken))
-	resp, err := http.DefaultClient.Do(req)
-	if err != nil {
-		return "", err
-	}
-	response, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return "", err
-	}
-	return string(response), nil
-}
-
-func (s *Server) verifyPhoneNumber(v *visitor, r *http.Request, phoneNumber, channel string) error {
-	ev := logvr(v, r).Tag(tagTwilio).Field("twilio_to", phoneNumber).Field("twilio_channel", channel).Debug("Sending phone verification")
-	data := url.Values{}
-	data.Set("To", phoneNumber)
-	data.Set("Channel", channel)
-	requestURL := fmt.Sprintf("%s/v2/Services/%s/Verifications", s.config.TwilioVerifyBaseURL, s.config.TwilioVerifyService)
-	req, err := http.NewRequest(http.MethodPost, requestURL, strings.NewReader(data.Encode()))
-	if err != nil {
-		return err
-	}
-	req.Header.Set("User-Agent", "ntfy/"+s.config.BuildVersion)
-	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
-	req.Header.Set("Authorization", util.BasicAuth(s.config.TwilioAccount, s.config.TwilioAuthToken))
-	resp, err := http.DefaultClient.Do(req)
-	if err != nil {
-		return err
-	}
-	response, err := io.ReadAll(resp.Body)
-	if err != nil {
-		ev.Err(err).Warn("Error sending Twilio phone verification request")
-		return err
-	}
-	ev.FieldIf("twilio_response", string(response), log.TraceLevel).Debug("Received Twilio phone verification response")
-	return nil
-}
-
-func (s *Server) verifyPhoneNumberCheck(v *visitor, r *http.Request, phoneNumber, code string) error {
-	ev := logvr(v, r).Tag(tagTwilio).Field("twilio_to", phoneNumber).Debug("Checking phone verification")
-	data := url.Values{}
-	data.Set("To", phoneNumber)
-	data.Set("Code", code)
-	requestURL := fmt.Sprintf("%s/v2/Services/%s/VerificationCheck", s.config.TwilioVerifyBaseURL, s.config.TwilioVerifyService)
-	req, err := http.NewRequest(http.MethodPost, requestURL, strings.NewReader(data.Encode()))
-	if err != nil {
-		return err
-	}
-	req.Header.Set("User-Agent", "ntfy/"+s.config.BuildVersion)
-	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
-	req.Header.Set("Authorization", util.BasicAuth(s.config.TwilioAccount, s.config.TwilioAuthToken))
-	resp, err := http.DefaultClient.Do(req)
-	if err != nil {
-		return err
-	} else if resp.StatusCode != http.StatusOK {
-		if ev.IsTrace() {
-			response, err := io.ReadAll(resp.Body)
-			if err != nil {
-				return err
-			}
-			ev.Field("twilio_response", string(response))
-		}
-		ev.Warn("Twilio phone verification failed with status code %d", resp.StatusCode)
-		if resp.StatusCode == http.StatusNotFound {
-			return errHTTPGonePhoneVerificationExpired
-		}
-		return errHTTPInternalError
-	}
-	response, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return err
-	}
-	if ev.IsTrace() {
-		ev.Field("twilio_response", string(response)).Trace("Received successful Twilio phone verification response")
-	} else if ev.IsDebug() {
-		ev.Debug("Received successful Twilio phone verification response")
-	}
-	return nil
-}
-
-func xmlEscapeText(text string) string {
-	var buf bytes.Buffer
-	_ = xml.EscapeText(&buf, []byte(text))
-	return buf.String()
+	metrics.CallsMadeSuccess.Inc()
 }

server/server_web.go

@@ -0,0 +1,94 @@
+package server
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+
+	"heckel.io/ntfy/v2/util"
+)
+
+// handleWebApp serves the embedded web app's index for client-side (SPA) routes that the
+// browser router resolves, so the app shell loads and the client-side router takes over.
+func (s *Server) handleWebApp(w http.ResponseWriter, r *http.Request, v *visitor) error {
+	r.URL.Path = webAppIndex
+	return s.handleStatic(w, r, v)
+}
+
+// handleWebAppNoIndex serves the web app index for the magic-link landing pages, whose path
+// carries a one-time token. The response is marked no-referrer (so the token can't leak to third
+// parties via the Referer header) and noindex (so it never gets indexed).
+func (s *Server) handleWebAppNoIndex(w http.ResponseWriter, r *http.Request, v *visitor) error {
+	w.Header().Set("Referrer-Policy", "no-referrer")
+	w.Header().Set("X-Robots-Tag", "noindex")
+	return s.handleWebApp(w, r, v)
+}
+
+func (s *Server) handleConfig(w http.ResponseWriter, _ *http.Request, _ *visitor) error {
+	w.Header().Set("Cache-Control", "no-cache")
+	return s.writeJSON(w, s.configResponse())
+}
+
+func (s *Server) handleWebConfig(w http.ResponseWriter, _ *http.Request, _ *visitor) error {
+	b, err := json.MarshalIndent(s.configResponse(), "", "  ")
+	if err != nil {
+		return err
+	}
+	w.Header().Set("Content-Type", "text/javascript")
+	w.Header().Set("Cache-Control", "no-cache")
+	_, err = io.WriteString(w, fmt.Sprintf("// Generated server configuration\nvar config = %s;\n", string(b)))
+	return err
+}
+
+// handleWebManifest serves the web app manifest for the progressive web app (PWA)
+func (s *Server) handleWebManifest(w http.ResponseWriter, _ *http.Request, _ *visitor) error {
+	response := &webManifestResponse{
+		Name:            "ntfy",
+		Description:     "ntfy lets you send push notifications via scripts from any computer or phone",
+		ShortName:       "ntfy",
+		Scope:           "/",
+		StartURL:        s.config.WebRoot,
+		Display:         "standalone",
+		BackgroundColor: "#ffffff",
+		ThemeColor:      "#317f6f",
+		Icons: []*webManifestIcon{
+			{SRC: "/static/images/pwa-192x192.png", Sizes: "192x192", Type: "image/png"},
+			{SRC: "/static/images/pwa-512x512.png", Sizes: "512x512", Type: "image/png"},
+		},
+	}
+	return s.writeJSONWithContentType(w, response, "application/manifest+json")
+}
+
+// handleStatic returns all static resources (excluding the docs), including the web app
+func (s *Server) handleStatic(w http.ResponseWriter, r *http.Request, _ *visitor) error {
+	r.URL.Path = webSiteDir + r.URL.Path
+	util.Gzip(http.FileServer(http.FS(webFsCached))).ServeHTTP(w, r)
+	return nil
+}
+
+// handleDocs returns static resources related to the docs
+func (s *Server) handleDocs(w http.ResponseWriter, r *http.Request, _ *visitor) error {
+	util.Gzip(http.FileServer(http.FS(docsStaticCached))).ServeHTTP(w, r)
+	return nil
+}
+
+func (s *Server) configResponse() *apiConfigResponse {
+	return &apiConfigResponse{
+		BaseURL:             "", // Will translate to window.location.origin
+		AppRoot:             s.config.WebRoot,
+		EnableLogin:         s.config.EnableLogin,
+		RequireLogin:        s.config.RequireLogin,
+		EnableSignup:        s.config.EnableSignup,
+		EnablePayments:      s.config.StripeSecretKey != "",
+		EnableCalls:         s.config.TwilioAccount != "",
+		EnableEmails:        s.config.SMTPSenderFrom != "",
+		EnableResetPassword: s.config.SMTPSenderFrom != "" && s.config.BaseURL != "", // Reset links need SMTP + an absolute base-url
+		EnableReservations:  s.config.EnableReservations,
+		EnableWebPush:       s.config.WebPushPublicKey != "",
+		BillingContact:      s.config.BillingContact,
+		WebPushPublicKey:    s.config.WebPushPublicKey,
+		DisallowedTopics:    s.config.DisallowedTopics,
+		ConfigHash:          s.config.Hash(),
+	}
+}

server/smtp_server.go

@@ -19,6 +19,7 @@ import (
 
 	"github.com/emersion/go-smtp"
 	"github.com/microcosm-cc/bluemonday"
+	"heckel.io/ntfy/v2/metrics"
 	"heckel.io/ntfy/v2/model"
 )
 
@@ -180,7 +181,7 @@ func (s *smtpSession) Data(r io.Reader) error {
 		s.backend.mu.Lock()
 		s.backend.success++
 		s.backend.mu.Unlock()
-		minc(metricEmailsReceivedSuccess)
+		metrics.EmailsReceivedSuccess.Inc()
 		return nil
 	})
 }
@@ -238,7 +239,7 @@ func (s *smtpSession) withFailCount(fn func() error) error {
 		// We do not want to spam the log with WARN messages.
 		logem(s.conn).Err(err).Debug("Incoming mail error")
 		s.backend.failure++
-		minc(metricEmailsReceivedFailure)
+		metrics.EmailsReceivedFailure.Inc()
 	}
 	return err
 }

server/topic.go

@@ -20,11 +20,12 @@ const (
 // topic represents a channel to which subscribers can subscribe, and publishers
 // can publish a message
 type topic struct {
-	ID          string
-	subscribers map[int]*topicSubscriber
-	rateVisitor *visitor
-	lastAccess  time.Time
-	mu          sync.RWMutex
+	ID                string
+	subscribers       map[int]*topicSubscriber
+	rateVisitor       *visitor
+	lastAccess        time.Time
+	onFirstSubscriber func() // Fired (async) when the subscriber count goes 0 -> 1; may be nil
+	mu                sync.RWMutex
 }
 
 type topicSubscriber struct {
@@ -56,6 +57,10 @@ func (t *topic) Subscribe(s subscriber, userID string, cancel func()) (subscribe
 			break
 		}
 	}
+	if len(t.subscribers) == 0 && t.onFirstSubscriber != nil {
+		// Fired async so cluster announcements never run under the topic lock
+		go t.onFirstSubscriber()
+	}
 	t.subscribers[subscriberID] = &topicSubscriber{
 		userID:     userID, // May be empty
 		subscriber: s,

server/types.go

@@ -29,6 +29,17 @@ type publishMessage struct {
 	Delay      string         `json:"delay"`
 }
 
+// dispatchOpts selects which delivery targets fire for a published message, beyond delivery
+// to local subscribers and the cross-node forward, which always happen (see Server.dispatch)
+type dispatchOpts struct {
+	firebase bool   // Send to Firebase (if configured)
+	email    string // Send an email to this address (if a mailer is configured)
+	call     string // Call this phone number (if Twilio is configured)
+	upstream bool   // Forward a poll request to the upstream server (if configured)
+	webPush  bool   // Publish to web push endpoints (if configured)
+	async    bool   // Deliver to local subscribers in a goroutine, logging errors instead of returning them
+}
+
 // messageEncoder is a function that knows how to encode a message
 type messageEncoder func(msg *model.Message) (string, error)
 
@@ -217,6 +228,14 @@ type apiAccountTokenResponse struct {
 	Provisioned bool   `json:"provisioned,omitempty"` // True if this token was provisioned by the server config
 }
 
+// apiAccountLoginResponse is the body of POST /v1/account/login: it authenticates a
+// username-or-email + password, mints a session token, and returns the token together with the
+// canonical username (which may differ from the identifier the user typed, e.g. a primary email).
+type apiAccountLoginResponse struct {
+	Token    string `json:"token"`
+	Username string `json:"username"`
+}
+
 type apiAccountPhoneNumberVerifyRequest struct {
 	Number  string `json:"number"`
 	Channel string `json:"channel"`
@@ -312,6 +331,8 @@ type apiAccountResponse struct {
 	SyncTopic     string                     `json:"sync_topic,omitempty"`
 	Provisioned   bool                       `json:"provisioned,omitempty"`
 	Language      string                     `json:"language,omitempty"`
+	DateFormat    string                     `json:"date_format,omitempty"`
+	TimeFormat    string                     `json:"time_format,omitempty"`
 	Notification  *user.NotificationPrefs    `json:"notification,omitempty"`
 	Subscriptions []*user.Subscription       `json:"subscriptions,omitempty"`
 	Reservations  []*apiAccountReservation   `json:"reservations,omitempty"`

template/gotext/GENERATED_FROM

@@ -0,0 +1 @@
+go1.26.5

template/gotext/README.md

@@ -0,0 +1,109 @@
+# `template/gotext/` -- vendored `text/template` with context cancellation
+
+This directory is a **verbatim copy of Go's standard-library `text/template` package**, plus one
+small patch that adds context-aware execution (`ExecuteContext`). It exists for exactly one reason:
+to stop **user-supplied** message templates (`Template: yes`, see the [templating docs](https://ntfy.sh/docs/publish/#message-templating))
+from burning CPU.
+
+- **Source:** Go stdlib `text/template` (+ `internal/fmtsort`), `$(go env GOROOT)/src`
+- **Version:** pinned in the repo-root [`.go-version`](../../.go-version); recorded in `GENERATED_FROM`
+- **Local modifications:** `patches/` (see [The patch](#the-patch))
+- **Update mechanism:** Manual -- `make update-template`, then commit (never autorolled; see [Updating](#updating-when-bumping-the-go-toolchain))
+
+## Why this exists
+
+ntfy lets users send a Go template that is rendered against a JSON body. Go's `text/template`
+**cannot be interrupted mid-execution** -- there is no context, no deadline, no cancellation
+([golang/go#31107](https://github.com/golang/go/issues/31107) proposed `ExecuteContext` but was
+declined, over a bundled context-*values* feature, not cancellation itself). So a crafted template
+with a tight or nested `{{range}}` (e.g. ranging over a large JSON array with a big loop body that
+writes no output) can run for tens of seconds on a single request. That is a CPU denial of service
+(GHSA-rhwf-xgc9-m9fp).
+
+There is no way to add an interrupt from the outside -- the executor's per-node `walk` loop is
+unexported. The only robust fix is to patch the executor itself. Rather than reach for fragile
+heuristics (guessing iteration counts, wrapping every function, etc.), we vendor the package and add
+the cancellation half of #31107 as a patch: `ExecuteContext(ctx, ...)` that aborts with `ctx.Err()`
+when `ctx` is canceled or its deadline passes. The check is a **single poll inside `walk`** of an
+atomic flag that a `context.AfterFunc` watcher flips -- so it bounds CPU for *any* template shape
+(cheap loops and expensive functions alike), it is exact (observed within one node), and it adds no
+measurable overhead. If #31107's cancellation half ever lands upstream, this fork can be deleted and
+the call site keeps compiling unchanged.
+
+The one user-facing execution site (`server/server_template.go` `renderTemplate`) wraps execution in
+`context.WithTimeout` and calls `ExecuteContext`, mapping `context.DeadlineExceeded` to a `400`.
+Trusted templates (operator config: Twilio, `cmd/serve.go`) keep using the standard library -- they
+are not user-supplied.
+
+## What's here
+
+| File | Origin |
+|------|--------|
+| `*.go` (`exec.go`, `funcs.go`, `template.go`, `option.go`, `helper.go`, `doc.go`) | verbatim from `$(go env GOROOT)/src/text/template/`, enumerated with `go list` so files added/removed upstream are picked up automatically |
+| `fmtsort/sort.go` | verbatim from `$(go env GOROOT)/src/internal/fmtsort/` -- `exec.go` needs it, and `internal/...` packages can't be imported from outside GOROOT, so it comes along |
+| `patches/0001-exec-context.patch` | our only real change (see below) |
+| `GENERATED_FROM` | the exact Go version `make update-template` last regenerated this copy from; provenance, written by that target |
+
+The Go toolchain version this copy is pinned to lives in the repo-root [`.go-version`](../../.go-version)
+file (the single source of truth, also consumed by CI and the `make` targets below). `GENERATED_FROM`
+must equal it -- `make check` fails otherwise (see below).
+
+We do **not** vendor `text/template/parse` -- it's a normal importable stdlib package and stays a
+plain import.
+
+## The patch
+
+`patches/` is a quilt-style ordered series (apply `0001-*`, then `0002-*`, ...). Today there is just
+`0001-exec-context.patch` -- small, purely additive, and touching only `exec.go`:
+
+- adds `ctx context.Context` and a shared `cancelled *atomic.Bool` to the executor `state`
+- adds `ExecuteContext` / `ExecuteTemplateContext`; `Execute` / `ExecuteTemplate` become
+  `context.Background()` wrappers, so their behavior and cost are unchanged
+- when `ctx.Done() != nil`, arms one `context.AfterFunc` watcher that flips the flag; `walk` polls it
+  per node and aborts via a `cancelError` that `errRecover` strips to the bare `ctx.Err()`
+  (`errors.Is(err, context.DeadlineExceeded)`)
+
+The flag is a `*atomic.Bool` (not a value) because `walkTemplate` copies `state` for nested
+`{{template}}` invocations; a shared pointer keeps one flag across all copies and avoids `go vet`
+copylocks. `template.go` is unchanged -- the context is per-call, not stored on the `Template`.
+
+Two *mechanical* transforms are applied by `make update-template` with `sed`, **not** the patch --
+renaming the package to `gotext`, and rewriting the `internal/fmtsort` import to
+`heckel.io/ntfy/v2/template/gotext/fmtsort`. Keeping them out of the patch means they apply to
+whatever files `go list` returns, so they survive upstream files being added or removed. (These two
+transforms are also the only difference between our patch and the upstream `text/template` diff.)
+
+Keeping the patch tiny (cancellation only, on one stable file) is deliberate: it makes re-basing
+onto a new Go release cheap.
+
+## Updating (when bumping the Go toolchain)
+
+The copy is **pinned to the Go version in the root `.go-version`**, so it's not frozen -- re-syncing
+on a Go bump pulls in all upstream fixes for free. `.go-version` is authoritative and hand-edited; to
+bump the toolchain: edit `.go-version`, install that toolchain
+(`go install golang.org/dl/<version>@latest && <version> download`), then re-sync:
+
+```
+make update-template   # copies the files from your GOROOT and re-applies patches/*.patch
+```
+
+`make update-template` **errors** unless your local Go matches `.go-version` -- it validates against
+the pin, it never writes it. If the patch hunks no longer apply against the new release, refresh the
+patch as part of the bump.
+
+`make template-check` (wired into `make check`) has two layers:
+
+1. **Marker check (ungated, runs on any toolchain):** fails if `GENERATED_FROM` != `.go-version`, i.e.
+   someone bumped the pin but forgot `make update-template` (or vice versa). This catches the common
+   mistake locally, on any developer's Go.
+2. **Content check (gated to the pinned Go):** re-derives the copy from `GOROOT + patches` and diffs it
+   against what's committed, catching hand-edits and patch problems. It no-ops on a non-pinned
+   toolchain so it never fails spuriously.
+
+CI installs exactly `.go-version` (`go-version-file`), so both layers run there. `make release`
+additionally refuses to run off the pinned Go, so the content check is never skipped for a release.
+
+## License
+
+These files are copyright The Go Authors, under the BSD-3-Clause license (headers preserved in each
+file). That is compatible with ntfy's Apache-2.0 / GPLv2 licensing.

template/gotext/doc.go

@@ -0,0 +1,502 @@
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/*
+Package template implements data-driven templates for generating textual output.
+
+To generate HTML output, see [html/template], which has the same interface
+as this package but automatically secures HTML output against certain attacks.
+
+Templates are executed by applying them to a data structure. Annotations in the
+template refer to elements of the data structure (typically a field of a struct
+or a key in a map) to control execution and derive values to be displayed.
+Execution of the template walks the structure and sets the cursor, represented
+by a period '.' and called "dot", to the value at the current location in the
+structure as execution proceeds.
+
+The security model used by this package assumes that template authors are
+trusted. The package does not auto-escape output, so injecting code into
+a template can lead to arbitrary code execution if the template is executed
+by an untrusted source.
+
+The input text for a template is UTF-8-encoded text in any format.
+"Actions"--data evaluations or control structures--are delimited by
+"{{" and "}}"; all text outside actions is copied to the output unchanged.
+
+Once parsed, a template may be executed safely in parallel, although if parallel
+executions share a Writer the output may be interleaved.
+
+Here is a trivial example that prints "17 items are made of wool".
+
+	type Inventory struct {
+		Material string
+		Count    uint
+	}
+	sweaters := Inventory{"wool", 17}
+	tmpl, err := template.New("test").Parse("{{.Count}} items are made of {{.Material}}")
+	if err != nil { panic(err) }
+	err = tmpl.Execute(os.Stdout, sweaters)
+	if err != nil { panic(err) }
+
+More intricate examples appear below.
+
+Text and spaces
+
+By default, all text between actions is copied verbatim when the template is
+executed. For example, the string " items are made of " in the example above
+appears on standard output when the program is run.
+
+However, to aid in formatting template source code, if an action's left
+delimiter (by default "{{") is followed immediately by a minus sign and white
+space, all trailing white space is trimmed from the immediately preceding text.
+Similarly, if the right delimiter ("}}") is preceded by white space and a minus
+sign, all leading white space is trimmed from the immediately following text.
+In these trim markers, the white space must be present:
+"{{- 3}}" is like "{{3}}" but trims the immediately preceding text, while
+"{{-3}}" parses as an action containing the number -3.
+
+For instance, when executing the template whose source is
+
+	"{{23 -}} < {{- 45}}"
+
+the generated output would be
+
+	"23<45"
+
+For this trimming, the definition of white space characters is the same as in Go:
+space, horizontal tab, carriage return, and newline.
+
+Actions
+
+Here is the list of actions. "Arguments" and "pipelines" are evaluations of
+data, defined in detail in the corresponding sections that follow.
+
+*/
+//	{{/* a comment */}}
+//	{{- /* a comment with white space trimmed from preceding and following text */ -}}
+//		A comment; discarded. May contain newlines.
+//		Comments do not nest and must start and end at the
+//		delimiters, as shown here.
+/*
+
+	{{pipeline}}
+		The default textual representation (the same as would be
+		printed by fmt.Print) of the value of the pipeline is copied
+		to the output.
+
+	{{if pipeline}} T1 {{end}}
+		If the value of the pipeline is empty, no output is generated;
+		otherwise, T1 is executed. The empty values are false, 0, any
+		nil pointer or interface value, and any array, slice, map, or
+		string of length zero.
+		Dot is unaffected.
+
+	{{if pipeline}} T1 {{else}} T0 {{end}}
+		If the value of the pipeline is empty, T0 is executed;
+		otherwise, T1 is executed. Dot is unaffected.
+
+	{{if pipeline}} T1 {{else if pipeline}} T0 {{end}}
+		To simplify the appearance of if-else chains, the else action
+		of an if may include another if directly; the effect is exactly
+		the same as writing
+			{{if pipeline}} T1 {{else}}{{if pipeline}} T0 {{end}}{{end}}
+
+	{{range pipeline}} T1 {{end}}
+		The value of the pipeline must be an array, slice, map, iter.Seq,
+		iter.Seq2, integer or channel.
+		If the value of the pipeline has length zero, nothing is output;
+		otherwise, dot is set to the successive elements of the array,
+		slice, or map and T1 is executed. If the value is a map and the
+		keys are of basic type with a defined order, the elements will be
+		visited in sorted key order.
+
+	{{range pipeline}} T1 {{else}} T0 {{end}}
+		The value of the pipeline must be an array, slice, map, iter.Seq,
+		iter.Seq2, integer or channel.
+		If the value of the pipeline has length zero, dot is unaffected and
+		T0 is executed; otherwise, dot is set to the successive elements
+		of the array, slice, or map and T1 is executed.
+
+	{{break}}
+		The innermost {{range pipeline}} loop is ended early, stopping the
+		current iteration and bypassing all remaining iterations.
+
+	{{continue}}
+		The current iteration of the innermost {{range pipeline}} loop is
+		stopped, and the loop starts the next iteration.
+
+	{{template "name"}}
+		The template with the specified name is executed with nil data.
+
+	{{template "name" pipeline}}
+		The template with the specified name is executed with dot set
+		to the value of the pipeline.
+
+	{{block "name" pipeline}} T1 {{end}}
+		A block is shorthand for defining a template
+			{{define "name"}} T1 {{end}}
+		and then executing it in place
+			{{template "name" pipeline}}
+		The typical use is to define a set of root templates that are
+		then customized by redefining the block templates within.
+
+	{{with pipeline}} T1 {{end}}
+		If the value of the pipeline is empty, no output is generated;
+		otherwise, dot is set to the value of the pipeline and T1 is
+		executed.
+
+	{{with pipeline}} T1 {{else}} T0 {{end}}
+		If the value of the pipeline is empty, dot is unaffected and T0
+		is executed; otherwise, dot is set to the value of the pipeline
+		and T1 is executed.
+
+	{{with pipeline}} T1 {{else with pipeline}} T0 {{end}}
+		To simplify the appearance of with-else chains, the else action
+		of a with may include another with directly; the effect is exactly
+		the same as writing
+			{{with pipeline}} T1 {{else}}{{with pipeline}} T0 {{end}}{{end}}
+
+
+Arguments
+
+An argument is a simple value, denoted by one of the following.
+
+	- A boolean, string, character, integer, floating-point, imaginary
+	  or complex constant in Go syntax. These behave like Go's untyped
+	  constants. Note that, as in Go, whether a large integer constant
+	  overflows when assigned or passed to a function can depend on whether
+	  the host machine's ints are 32 or 64 bits.
+	- The keyword nil, representing an untyped Go nil.
+	- The character '.' (period):
+
+		.
+
+	  The result is the value of dot.
+	- A variable name, which is a (possibly empty) alphanumeric string
+	  preceded by a dollar sign, such as
+
+		$piOver2
+
+	  or
+
+		$
+
+	  The result is the value of the variable.
+	  Variables are described below.
+	- The name of a field of the data, which must be a struct, preceded
+	  by a period, such as
+
+		.Field
+
+	  The result is the value of the field. Field invocations may be
+	  chained:
+
+	    .Field1.Field2
+
+	  Fields can also be evaluated on variables, including chaining:
+
+	    $x.Field1.Field2
+	- The name of a key of the data, which must be a map, preceded
+	  by a period, such as
+
+		.Key
+
+	  The result is the map element value indexed by the key.
+	  Key invocations may be chained and combined with fields to any
+	  depth:
+
+	    .Field1.Key1.Field2.Key2
+
+	  Although the key must be an alphanumeric identifier, unlike with
+	  field names they do not need to start with an upper case letter.
+	  Keys can also be evaluated on variables, including chaining:
+
+	    $x.key1.key2
+	- The name of a niladic method of the data, preceded by a period,
+	  such as
+
+		.Method
+
+	  The result is the value of invoking the method with dot as the
+	  receiver, dot.Method(). Such a method must have one return value (of
+	  any type) or two return values, the second of which is an error.
+	  If it has two and the returned error is non-nil, execution terminates
+	  and an error is returned to the caller as the value of Execute.
+	  Method invocations may be chained and combined with fields and keys
+	  to any depth:
+
+	    .Field1.Key1.Method1.Field2.Key2.Method2
+
+	  Methods can also be evaluated on variables, including chaining:
+
+	    $x.Method1.Field
+	- The name of a niladic function, such as
+
+		fun
+
+	  The result is the value of invoking the function, fun(). The return
+	  types and values behave as in methods. Functions and function
+	  names are described below.
+	- A parenthesized instance of one the above, for grouping. The result
+	  may be accessed by a field or map key invocation.
+
+		print (.F1 arg1) (.F2 arg2)
+		(.StructValuedMethod "arg").Field
+
+Arguments may evaluate to any type; if they are pointers the implementation
+automatically indirects to the base type when required.
+If an evaluation yields a function value, such as a function-valued
+field of a struct, the function is not invoked automatically, but it
+can be used as a truth value for an if action and the like. To invoke
+it, use the call function, defined below.
+
+Pipelines
+
+A pipeline is a possibly chained sequence of "commands". A command is a simple
+value (argument) or a function or method call, possibly with multiple arguments:
+
+	Argument
+		The result is the value of evaluating the argument.
+	.Method [Argument...]
+		The method can be alone or the last element of a chain but,
+		unlike methods in the middle of a chain, it can take arguments.
+		The result is the value of calling the method with the
+		arguments:
+			dot.Method(Argument1, etc.)
+	functionName [Argument...]
+		The result is the value of calling the function associated
+		with the name:
+			function(Argument1, etc.)
+		Functions and function names are described below.
+
+A pipeline may be "chained" by separating a sequence of commands with pipeline
+characters '|'. In a chained pipeline, the result of each command is
+passed as the last argument of the following command. The output of the final
+command in the pipeline is the value of the pipeline.
+
+The output of a command will be either one value or two values, the second of
+which has type error. If that second value is present and evaluates to
+non-nil, execution terminates and the error is returned to the caller of
+Execute.
+
+Variables
+
+A pipeline inside an action may initialize a variable to capture the result.
+The initialization has syntax
+
+	$variable := pipeline
+
+where $variable is the name of the variable. An action that declares a
+variable produces no output.
+
+Variables previously declared can also be assigned, using the syntax
+
+	$variable = pipeline
+
+If a "range" action initializes a variable, the variable is set to the
+successive elements of the iteration. Also, a "range" may declare two
+variables, separated by a comma:
+
+	range $index, $element := pipeline
+
+in which case $index and $element are set to the successive values of the
+array/slice index or map key and element, respectively. Note that if there is
+only one variable, it is assigned the element; this is opposite to the
+convention in Go range clauses.
+
+A variable's scope extends to the "end" action of the control structure ("if",
+"with", or "range") in which it is declared, or to the end of the template if
+there is no such control structure. A template invocation does not inherit
+variables from the point of its invocation.
+
+When execution begins, $ is set to the data argument passed to Execute, that is,
+to the starting value of dot.
+
+Examples
+
+Here are some example one-line templates demonstrating pipelines and variables.
+All produce the quoted word "output":
+
+	{{"\"output\""}}
+		A string constant.
+	{{`"output"`}}
+		A raw string constant.
+	{{printf "%q" "output"}}
+		A function call.
+	{{"output" | printf "%q"}}
+		A function call whose final argument comes from the previous
+		command.
+	{{printf "%q" (print "out" "put")}}
+		A parenthesized argument.
+	{{"put" | printf "%s%s" "out" | printf "%q"}}
+		A more elaborate call.
+	{{"output" | printf "%s" | printf "%q"}}
+		A longer chain.
+	{{with "output"}}{{printf "%q" .}}{{end}}
+		A with action using dot.
+	{{with $x := "output" | printf "%q"}}{{$x}}{{end}}
+		A with action that creates and uses a variable.
+	{{with $x := "output"}}{{printf "%q" $x}}{{end}}
+		A with action that uses the variable in another action.
+	{{with $x := "output"}}{{$x | printf "%q"}}{{end}}
+		The same, but pipelined.
+
+Functions
+
+During execution functions are found in two function maps: first in the
+template, then in the global function map. By default, no functions are defined
+in the template but the Funcs method can be used to add them.
+
+Predefined global functions are named as follows.
+
+	and
+		Returns the boolean AND of its arguments by returning the
+		first empty argument or the last argument. That is,
+		"and x y" behaves as "if x then y else x."
+		Evaluation proceeds through the arguments left to right
+		and returns when the result is determined.
+	call
+		Returns the result of calling the first argument, which
+		must be a function, with the remaining arguments as parameters.
+		Thus "call .X.Y 1 2" is, in Go notation, dot.X.Y(1, 2) where
+		Y is a func-valued field, map entry, or the like.
+		The first argument must be the result of an evaluation
+		that yields a value of function type (as distinct from
+		a predefined function such as print). The function must
+		return either one or two result values, the second of which
+		is of type error. If the arguments don't match the function
+		or the returned error value is non-nil, execution stops.
+	html
+		Returns the escaped HTML equivalent of the textual
+		representation of its arguments. This function is unavailable
+		in html/template, with a few exceptions.
+	index
+		Returns the result of indexing its first argument by the
+		following arguments. Thus "index x 1 2 3" is, in Go syntax,
+		x[1][2][3]. Each indexed item must be a map, slice, or array.
+	slice
+		slice returns the result of slicing its first argument by the
+		remaining arguments. Thus "slice x 1 2" is, in Go syntax, x[1:2],
+		while "slice x" is x[:], "slice x 1" is x[1:], and "slice x 1 2 3"
+		is x[1:2:3]. The first argument must be a string, slice, or array.
+	js
+		Returns the escaped JavaScript equivalent of the textual
+		representation of its arguments.
+	len
+		Returns the integer length of its argument.
+	not
+		Returns the boolean negation of its single argument.
+	or
+		Returns the boolean OR of its arguments by returning the
+		first non-empty argument or the last argument, that is,
+		"or x y" behaves as "if x then x else y".
+		Evaluation proceeds through the arguments left to right
+		and returns when the result is determined.
+	print
+		An alias for fmt.Sprint
+	printf
+		An alias for fmt.Sprintf
+	println
+		An alias for fmt.Sprintln
+	urlquery
+		Returns the escaped value of the textual representation of
+		its arguments in a form suitable for embedding in a URL query.
+		This function is unavailable in html/template, with a few
+		exceptions.
+
+The boolean functions take any zero value to be false and a non-zero
+value to be true.
+
+There is also a set of binary comparison operators defined as
+functions:
+
+	eq
+		Returns the boolean truth of arg1 == arg2
+	ne
+		Returns the boolean truth of arg1 != arg2
+	lt
+		Returns the boolean truth of arg1 < arg2
+	le
+		Returns the boolean truth of arg1 <= arg2
+	gt
+		Returns the boolean truth of arg1 > arg2
+	ge
+		Returns the boolean truth of arg1 >= arg2
+
+For simpler multi-way equality tests, eq (only) accepts two or more
+arguments and compares the second and subsequent to the first,
+returning in effect
+
+	arg1==arg2 || arg1==arg3 || arg1==arg4 ...
+
+(Unlike with || in Go, however, eq is a function call and all the
+arguments will be evaluated.)
+
+The comparison functions work on any values whose type Go defines as
+comparable. For basic types such as integers, the rules are relaxed:
+size and exact type are ignored, so any integer value, signed or unsigned,
+may be compared with any other integer value. (The arithmetic value is compared,
+not the bit pattern, so all negative integers are less than all unsigned integers.)
+However, as usual, one may not compare an int with a float32 and so on.
+
+Associated templates
+
+Each template is named by a string specified when it is created. Also, each
+template is associated with zero or more other templates that it may invoke by
+name; such associations are transitive and form a name space of templates.
+
+A template may use a template invocation to instantiate another associated
+template; see the explanation of the "template" action above. The name must be
+that of a template associated with the template that contains the invocation.
+
+Nested template definitions
+
+When parsing a template, another template may be defined and associated with the
+template being parsed. Template definitions must appear at the top level of the
+template, much like global variables in a Go program.
+
+The syntax of such definitions is to surround each template declaration with a
+"define" and "end" action.
+
+The define action names the template being created by providing a string
+constant. Here is a simple example:
+
+	{{define "T1"}}ONE{{end}}
+	{{define "T2"}}TWO{{end}}
+	{{define "T3"}}{{template "T1"}} {{template "T2"}}{{end}}
+	{{template "T3"}}
+
+This defines two templates, T1 and T2, and a third T3 that invokes the other two
+when it is executed. Finally it invokes T3. If executed this template will
+produce the text
+
+	ONE TWO
+
+By construction, a template may reside in only one association. If it's
+necessary to have a template addressable from multiple associations, the
+template definition must be parsed multiple times to create distinct *Template
+values, or must be copied with [Template.Clone] or [Template.AddParseTree].
+
+Parse may be called multiple times to assemble the various associated templates;
+see [ParseFiles], [ParseGlob], [Template.ParseFiles] and [Template.ParseGlob]
+for simple ways to parse related templates stored in files.
+
+A template may be executed directly or through [Template.ExecuteTemplate], which executes
+an associated template identified by name. To invoke our example above, we
+might write,
+
+	err := tmpl.Execute(os.Stdout, "no data needed")
+	if err != nil {
+		log.Fatalf("execution failed: %s", err)
+	}
+
+or to invoke a particular template explicitly by name,
+
+	err := tmpl.ExecuteTemplate(os.Stdout, "T2", "no data needed")
+	if err != nil {
+		log.Fatalf("execution failed: %s", err)
+	}
+
+*/
+package gotext

template/gotext/fmtsort/sort.go

@@ -0,0 +1,154 @@
+// Copyright 2018 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package fmtsort provides a general stable ordering mechanism
+// for maps, on behalf of the fmt and text/template packages.
+// It is not guaranteed to be efficient and works only for types
+// that are valid map keys.
+package fmtsort
+
+import (
+	"cmp"
+	"reflect"
+	"slices"
+)
+
+// Note: Throughout this package we avoid calling reflect.Value.Interface as
+// it is not always legal to do so and it's easier to avoid the issue than to face it.
+
+// SortedMap is a slice of KeyValue pairs that simplifies sorting
+// and iterating over map entries.
+//
+// Each KeyValue pair contains a map key and its corresponding value.
+type SortedMap []KeyValue
+
+// KeyValue holds a single key and value pair found in a map.
+type KeyValue struct {
+	Key, Value reflect.Value
+}
+
+// Sort accepts a map and returns a SortedMap that has the same keys and
+// values but in a stable sorted order according to the keys, modulo issues
+// raised by unorderable key values such as NaNs.
+//
+// The ordering rules are more general than with Go's < operator:
+//
+//   - when applicable, nil compares low
+//   - ints, floats, and strings order by <
+//   - NaN compares less than non-NaN floats
+//   - bool compares false before true
+//   - complex compares real, then imag
+//   - pointers compare by machine address
+//   - channel values compare by machine address
+//   - structs compare each field in turn
+//   - arrays compare each element in turn.
+//     Otherwise identical arrays compare by length.
+//   - interface values compare first by reflect.Type describing the concrete type
+//     and then by concrete value as described in the previous rules.
+func Sort(mapValue reflect.Value) SortedMap {
+	if mapValue.Type().Kind() != reflect.Map {
+		return nil
+	}
+	// Note: this code is arranged to not panic even in the presence
+	// of a concurrent map update. The runtime is responsible for
+	// yelling loudly if that happens. See issue 33275.
+	n := mapValue.Len()
+	sorted := make(SortedMap, 0, n)
+	iter := mapValue.MapRange()
+	for iter.Next() {
+		sorted = append(sorted, KeyValue{iter.Key(), iter.Value()})
+	}
+	slices.SortStableFunc(sorted, func(a, b KeyValue) int {
+		return compare(a.Key, b.Key)
+	})
+	return sorted
+}
+
+// compare compares two values of the same type. It returns -1, 0, 1
+// according to whether a > b (1), a == b (0), or a < b (-1).
+// If the types differ, it returns -1.
+// See the comment on Sort for the comparison rules.
+func compare(aVal, bVal reflect.Value) int {
+	aType, bType := aVal.Type(), bVal.Type()
+	if aType != bType {
+		return -1 // No good answer possible, but don't return 0: they're not equal.
+	}
+	switch aVal.Kind() {
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		return cmp.Compare(aVal.Int(), bVal.Int())
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
+		return cmp.Compare(aVal.Uint(), bVal.Uint())
+	case reflect.String:
+		return cmp.Compare(aVal.String(), bVal.String())
+	case reflect.Float32, reflect.Float64:
+		return cmp.Compare(aVal.Float(), bVal.Float())
+	case reflect.Complex64, reflect.Complex128:
+		a, b := aVal.Complex(), bVal.Complex()
+		if c := cmp.Compare(real(a), real(b)); c != 0 {
+			return c
+		}
+		return cmp.Compare(imag(a), imag(b))
+	case reflect.Bool:
+		a, b := aVal.Bool(), bVal.Bool()
+		switch {
+		case a == b:
+			return 0
+		case a:
+			return 1
+		default:
+			return -1
+		}
+	case reflect.Pointer, reflect.UnsafePointer:
+		return cmp.Compare(aVal.Pointer(), bVal.Pointer())
+	case reflect.Chan:
+		if c, ok := nilCompare(aVal, bVal); ok {
+			return c
+		}
+		return cmp.Compare(aVal.Pointer(), bVal.Pointer())
+	case reflect.Struct:
+		for i := 0; i < aVal.NumField(); i++ {
+			if c := compare(aVal.Field(i), bVal.Field(i)); c != 0 {
+				return c
+			}
+		}
+		return 0
+	case reflect.Array:
+		for i := 0; i < aVal.Len(); i++ {
+			if c := compare(aVal.Index(i), bVal.Index(i)); c != 0 {
+				return c
+			}
+		}
+		return 0
+	case reflect.Interface:
+		if c, ok := nilCompare(aVal, bVal); ok {
+			return c
+		}
+		c := compare(reflect.ValueOf(aVal.Elem().Type()), reflect.ValueOf(bVal.Elem().Type()))
+		if c != 0 {
+			return c
+		}
+		return compare(aVal.Elem(), bVal.Elem())
+	default:
+		// Certain types cannot appear as keys (maps, funcs, slices), but be explicit.
+		panic("bad type in compare: " + aType.String())
+	}
+}
+
+// nilCompare checks whether either value is nil. If not, the boolean is false.
+// If either value is nil, the boolean is true and the integer is the comparison
+// value. The comparison is defined to be 0 if both are nil, otherwise the one
+// nil value compares low. Both arguments must represent a chan, func,
+// interface, map, pointer, or slice.
+func nilCompare(aVal, bVal reflect.Value) (int, bool) {
+	if aVal.IsNil() {
+		if bVal.IsNil() {
+			return 0, true
+		}
+		return -1, true
+	}
+	if bVal.IsNil() {
+		return 1, true
+	}
+	return 0, false
+}

template/gotext/funcs.go

@@ -0,0 +1,774 @@
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package gotext
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"net/url"
+	"reflect"
+	"strings"
+	"sync"
+	"unicode"
+	"unicode/utf8"
+)
+
+// FuncMap is the type of the map defining the mapping from names to functions.
+// Each function must have either a single return value, or two return values of
+// which the second has type error. In that case, if the second (error)
+// return value evaluates to non-nil during execution, execution terminates and
+// Execute returns that error.
+//
+// Errors returned by Execute wrap the underlying error; call [errors.AsType] to
+// unwrap them.
+//
+// When template execution invokes a function with an argument list, that list
+// must be assignable to the function's parameter types. Functions meant to
+// apply to arguments of arbitrary type can use parameters of type interface{} or
+// of type [reflect.Value]. Similarly, functions meant to return a result of arbitrary
+// type can return interface{} or [reflect.Value].
+type FuncMap map[string]any
+
+// builtins returns the FuncMap.
+// It is not a global variable so the linker can dead code eliminate
+// more when this isn't called. See golang.org/issue/36021.
+// TODO: revert this back to a global map once golang.org/issue/2559 is fixed.
+func builtins() FuncMap {
+	return FuncMap{
+		"and":      and,
+		"call":     emptyCall,
+		"html":     HTMLEscaper,
+		"index":    index,
+		"slice":    slice,
+		"js":       JSEscaper,
+		"len":      length,
+		"not":      not,
+		"or":       or,
+		"print":    fmt.Sprint,
+		"printf":   fmt.Sprintf,
+		"println":  fmt.Sprintln,
+		"urlquery": URLQueryEscaper,
+
+		// Comparisons
+		"eq": eq, // ==
+		"ge": ge, // >=
+		"gt": gt, // >
+		"le": le, // <=
+		"lt": lt, // <
+		"ne": ne, // !=
+	}
+}
+
+// builtinFuncs lazily computes & caches the builtinFuncs map.
+var builtinFuncs = sync.OnceValue(func() map[string]reflect.Value {
+	funcMap := builtins()
+	m := make(map[string]reflect.Value, len(funcMap))
+	addValueFuncs(m, funcMap)
+	return m
+})
+
+// addValueFuncs adds to values the functions in funcs, converting them to reflect.Values.
+func addValueFuncs(out map[string]reflect.Value, in FuncMap) {
+	for name, fn := range in {
+		if !goodName(name) {
+			panic(fmt.Errorf("function name %q is not a valid identifier", name))
+		}
+		v := reflect.ValueOf(fn)
+		if v.Kind() != reflect.Func {
+			panic("value for " + name + " not a function")
+		}
+		if err := goodFunc(name, v.Type()); err != nil {
+			panic(err)
+		}
+		out[name] = v
+	}
+}
+
+// addFuncs adds to values the functions in funcs. It does no checking of the input -
+// call addValueFuncs first.
+func addFuncs(out, in FuncMap) {
+	for name, fn := range in {
+		out[name] = fn
+	}
+}
+
+// goodFunc reports whether the function or method has the right result signature.
+func goodFunc(name string, typ reflect.Type) error {
+	// We allow functions with 1 result or 2 results where the second is an error.
+	switch numOut := typ.NumOut(); {
+	case numOut == 1:
+		return nil
+	case numOut == 2 && typ.Out(1) == errorType:
+		return nil
+	case numOut == 2:
+		return fmt.Errorf("invalid function signature for %s: second return value should be error; is %s", name, typ.Out(1))
+	default:
+		return fmt.Errorf("function %s has %d return values; should be 1 or 2", name, typ.NumOut())
+	}
+}
+
+// goodName reports whether the function name is a valid identifier.
+func goodName(name string) bool {
+	if name == "" {
+		return false
+	}
+	for i, r := range name {
+		switch {
+		case r == '_':
+		case i == 0 && !unicode.IsLetter(r):
+			return false
+		case !unicode.IsLetter(r) && !unicode.IsDigit(r):
+			return false
+		}
+	}
+	return true
+}
+
+// findFunction looks for a function in the template, and global map.
+func findFunction(name string, tmpl *Template) (v reflect.Value, isBuiltin, ok bool) {
+	if tmpl != nil && tmpl.common != nil {
+		tmpl.muFuncs.RLock()
+		defer tmpl.muFuncs.RUnlock()
+		if fn := tmpl.execFuncs[name]; fn.IsValid() {
+			return fn, false, true
+		}
+	}
+	if fn := builtinFuncs()[name]; fn.IsValid() {
+		return fn, true, true
+	}
+	return reflect.Value{}, false, false
+}
+
+// prepareArg checks if value can be used as an argument of type argType, and
+// converts an invalid value to appropriate zero if possible.
+func prepareArg(value reflect.Value, argType reflect.Type) (reflect.Value, error) {
+	if !value.IsValid() {
+		if !canBeNil(argType) {
+			return reflect.Value{}, fmt.Errorf("value is nil; should be of type %s", argType)
+		}
+		value = reflect.Zero(argType)
+	}
+	if value.Type().AssignableTo(argType) {
+		return value, nil
+	}
+	if intLike(value.Kind()) && intLike(argType.Kind()) && value.Type().ConvertibleTo(argType) {
+		value = value.Convert(argType)
+		return value, nil
+	}
+	return reflect.Value{}, fmt.Errorf("value has type %s; should be %s", value.Type(), argType)
+}
+
+func intLike(typ reflect.Kind) bool {
+	switch typ {
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		return true
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
+		return true
+	}
+	return false
+}
+
+// indexArg checks if a reflect.Value can be used as an index, and converts it to int if possible.
+func indexArg(index reflect.Value, cap int) (int, error) {
+	var x int64
+	switch index.Kind() {
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		x = index.Int()
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
+		x = int64(index.Uint())
+	case reflect.Invalid:
+		return 0, fmt.Errorf("cannot index slice/array with nil")
+	default:
+		return 0, fmt.Errorf("cannot index slice/array with type %s", index.Type())
+	}
+	if x < 0 || int(x) < 0 || int(x) > cap {
+		return 0, fmt.Errorf("index out of range: %d", x)
+	}
+	return int(x), nil
+}
+
+// Indexing.
+
+// index returns the result of indexing its first argument by the following
+// arguments. Thus "index x 1 2 3" is, in Go syntax, x[1][2][3]. Each
+// indexed item must be a map, slice, or array.
+func index(item reflect.Value, indexes ...reflect.Value) (reflect.Value, error) {
+	item = indirectInterface(item)
+	if !item.IsValid() {
+		return reflect.Value{}, fmt.Errorf("index of untyped nil")
+	}
+	for _, index := range indexes {
+		index = indirectInterface(index)
+		var isNil bool
+		if item, isNil = indirect(item); isNil {
+			return reflect.Value{}, fmt.Errorf("index of nil pointer")
+		}
+		switch item.Kind() {
+		case reflect.Array, reflect.Slice, reflect.String:
+			x, err := indexArg(index, item.Len())
+			if err != nil {
+				return reflect.Value{}, err
+			}
+			item = item.Index(x)
+		case reflect.Map:
+			index, err := prepareArg(index, item.Type().Key())
+			if err != nil {
+				return reflect.Value{}, err
+			}
+			if x := item.MapIndex(index); x.IsValid() {
+				item = x
+			} else {
+				item = reflect.Zero(item.Type().Elem())
+			}
+		case reflect.Invalid:
+			// the loop holds invariant: item.IsValid()
+			panic("unreachable")
+		default:
+			return reflect.Value{}, fmt.Errorf("can't index item of type %s", item.Type())
+		}
+	}
+	return item, nil
+}
+
+// Slicing.
+
+// slice returns the result of slicing its first argument by the remaining
+// arguments. Thus "slice x 1 2" is, in Go syntax, x[1:2], while "slice x"
+// is x[:], "slice x 1" is x[1:], and "slice x 1 2 3" is x[1:2:3]. The first
+// argument must be a string, slice, or array.
+func slice(item reflect.Value, indexes ...reflect.Value) (reflect.Value, error) {
+	item = indirectInterface(item)
+	if !item.IsValid() {
+		return reflect.Value{}, fmt.Errorf("slice of untyped nil")
+	}
+	var isNil bool
+	if item, isNil = indirect(item); isNil {
+		return reflect.Value{}, fmt.Errorf("slice of nil pointer")
+	}
+	if len(indexes) > 3 {
+		return reflect.Value{}, fmt.Errorf("too many slice indexes: %d", len(indexes))
+	}
+	var cap int
+	switch item.Kind() {
+	case reflect.String:
+		if len(indexes) == 3 {
+			return reflect.Value{}, fmt.Errorf("cannot 3-index slice a string")
+		}
+		cap = item.Len()
+	case reflect.Array, reflect.Slice:
+		cap = item.Cap()
+	default:
+		return reflect.Value{}, fmt.Errorf("can't slice item of type %s", item.Type())
+	}
+	// set default values for cases item[:], item[i:].
+	idx := [3]int{0, item.Len()}
+	for i, index := range indexes {
+		x, err := indexArg(index, cap)
+		if err != nil {
+			return reflect.Value{}, err
+		}
+		idx[i] = x
+	}
+	// given item[i:j], make sure i <= j.
+	if idx[0] > idx[1] {
+		return reflect.Value{}, fmt.Errorf("invalid slice index: %d > %d", idx[0], idx[1])
+	}
+	if len(indexes) < 3 {
+		return item.Slice(idx[0], idx[1]), nil
+	}
+	// given item[i:j:k], make sure i <= j <= k.
+	if idx[1] > idx[2] {
+		return reflect.Value{}, fmt.Errorf("invalid slice index: %d > %d", idx[1], idx[2])
+	}
+	return item.Slice3(idx[0], idx[1], idx[2]), nil
+}
+
+// Length
+
+// length returns the length of the item, with an error if it has no defined length.
+func length(item reflect.Value) (int, error) {
+	item, isNil := indirect(item)
+	if isNil {
+		return 0, fmt.Errorf("len of nil pointer")
+	}
+	switch item.Kind() {
+	case reflect.Array, reflect.Chan, reflect.Map, reflect.Slice, reflect.String:
+		return item.Len(), nil
+	}
+	return 0, fmt.Errorf("len of type %s", item.Type())
+}
+
+// Function invocation
+
+func emptyCall(fn reflect.Value, args ...reflect.Value) reflect.Value {
+	panic("unreachable") // implemented as a special case in evalCall
+}
+
+// call returns the result of evaluating the first argument as a function.
+// The function must return 1 result, or 2 results, the second of which is an error.
+func call(name string, fn reflect.Value, args ...reflect.Value) (reflect.Value, error) {
+	fn = indirectInterface(fn)
+	if !fn.IsValid() {
+		return reflect.Value{}, fmt.Errorf("call of nil")
+	}
+	typ := fn.Type()
+	if typ.Kind() != reflect.Func {
+		return reflect.Value{}, fmt.Errorf("non-function %s of type %s", name, typ)
+	}
+
+	if err := goodFunc(name, typ); err != nil {
+		return reflect.Value{}, err
+	}
+	numIn := typ.NumIn()
+	var dddType reflect.Type
+	if typ.IsVariadic() {
+		if len(args) < numIn-1 {
+			return reflect.Value{}, fmt.Errorf("wrong number of args for %s: got %d want at least %d", name, len(args), numIn-1)
+		}
+		dddType = typ.In(numIn - 1).Elem()
+	} else {
+		if len(args) != numIn {
+			return reflect.Value{}, fmt.Errorf("wrong number of args for %s: got %d want %d", name, len(args), numIn)
+		}
+	}
+	argv := make([]reflect.Value, len(args))
+	for i, arg := range args {
+		arg = indirectInterface(arg)
+		// Compute the expected type. Clumsy because of variadics.
+		argType := dddType
+		if !typ.IsVariadic() || i < numIn-1 {
+			argType = typ.In(i)
+		}
+
+		var err error
+		if argv[i], err = prepareArg(arg, argType); err != nil {
+			return reflect.Value{}, fmt.Errorf("arg %d: %w", i, err)
+		}
+	}
+	return safeCall(fn, argv)
+}
+
+// safeCall runs fun.Call(args), and returns the resulting value and error, if
+// any. If the call panics, the panic value is returned as an error.
+func safeCall(fun reflect.Value, args []reflect.Value) (val reflect.Value, err error) {
+	defer func() {
+		if r := recover(); r != nil {
+			if e, ok := r.(error); ok {
+				err = e
+			} else {
+				err = fmt.Errorf("%v", r)
+			}
+		}
+	}()
+	ret := fun.Call(args)
+	if len(ret) == 2 && !ret[1].IsNil() {
+		return ret[0], ret[1].Interface().(error)
+	}
+	return ret[0], nil
+}
+
+// Boolean logic.
+
+func truth(arg reflect.Value) bool {
+	t, _ := isTrue(indirectInterface(arg))
+	return t
+}
+
+// and computes the Boolean AND of its arguments, returning
+// the first false argument it encounters, or the last argument.
+func and(arg0 reflect.Value, args ...reflect.Value) reflect.Value {
+	panic("unreachable") // implemented as a special case in evalCall
+}
+
+// or computes the Boolean OR of its arguments, returning
+// the first true argument it encounters, or the last argument.
+func or(arg0 reflect.Value, args ...reflect.Value) reflect.Value {
+	panic("unreachable") // implemented as a special case in evalCall
+}
+
+// not returns the Boolean negation of its argument.
+func not(arg reflect.Value) bool {
+	return !truth(arg)
+}
+
+// Comparison.
+
+// TODO: Perhaps allow comparison between signed and unsigned integers.
+
+var (
+	errBadComparisonType = errors.New("invalid type for comparison")
+	errNoComparison      = errors.New("missing argument for comparison")
+)
+
+type kind int
+
+const (
+	invalidKind kind = iota
+	boolKind
+	complexKind
+	intKind
+	floatKind
+	stringKind
+	uintKind
+)
+
+func basicKind(v reflect.Value) (kind, error) {
+	switch v.Kind() {
+	case reflect.Bool:
+		return boolKind, nil
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		return intKind, nil
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
+		return uintKind, nil
+	case reflect.Float32, reflect.Float64:
+		return floatKind, nil
+	case reflect.Complex64, reflect.Complex128:
+		return complexKind, nil
+	case reflect.String:
+		return stringKind, nil
+	}
+	return invalidKind, errBadComparisonType
+}
+
+// isNil returns true if v is the zero reflect.Value, or nil of its type.
+func isNil(v reflect.Value) bool {
+	if !v.IsValid() {
+		return true
+	}
+	switch v.Kind() {
+	case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice:
+		return v.IsNil()
+	}
+	return false
+}
+
+// canCompare reports whether v1 and v2 are both the same kind, or one is nil.
+// Called only when dealing with nillable types, or there's about to be an error.
+func canCompare(v1, v2 reflect.Value) bool {
+	k1 := v1.Kind()
+	k2 := v2.Kind()
+	if k1 == k2 {
+		return true
+	}
+	// We know the type can be compared to nil.
+	return k1 == reflect.Invalid || k2 == reflect.Invalid
+}
+
+// eq evaluates the comparison a == b || a == c || ...
+func eq(arg1 reflect.Value, arg2 ...reflect.Value) (bool, error) {
+	arg1 = indirectInterface(arg1)
+	if len(arg2) == 0 {
+		return false, errNoComparison
+	}
+	k1, _ := basicKind(arg1)
+	for _, arg := range arg2 {
+		arg = indirectInterface(arg)
+		k2, _ := basicKind(arg)
+		truth := false
+		if k1 != k2 {
+			// Special case: Can compare integer values regardless of type's sign.
+			switch {
+			case k1 == intKind && k2 == uintKind:
+				truth = arg1.Int() >= 0 && uint64(arg1.Int()) == arg.Uint()
+			case k1 == uintKind && k2 == intKind:
+				truth = arg.Int() >= 0 && arg1.Uint() == uint64(arg.Int())
+			default:
+				if arg1.IsValid() && arg.IsValid() {
+					return false, fmt.Errorf("incompatible types for comparison: %v and %v", arg1.Type(), arg.Type())
+				}
+			}
+		} else {
+			switch k1 {
+			case boolKind:
+				truth = arg1.Bool() == arg.Bool()
+			case complexKind:
+				truth = arg1.Complex() == arg.Complex()
+			case floatKind:
+				truth = arg1.Float() == arg.Float()
+			case intKind:
+				truth = arg1.Int() == arg.Int()
+			case stringKind:
+				truth = arg1.String() == arg.String()
+			case uintKind:
+				truth = arg1.Uint() == arg.Uint()
+			default:
+				if !canCompare(arg1, arg) {
+					return false, fmt.Errorf("non-comparable types %s: %v, %s: %v", arg1, arg1.Type(), arg.Type(), arg)
+				}
+				if isNil(arg1) || isNil(arg) {
+					truth = isNil(arg) == isNil(arg1)
+				} else {
+					if !arg.Type().Comparable() {
+						return false, fmt.Errorf("non-comparable type %s: %v", arg, arg.Type())
+					}
+					truth = arg1.Interface() == arg.Interface()
+				}
+			}
+		}
+		if truth {
+			return true, nil
+		}
+	}
+	return false, nil
+}
+
+// ne evaluates the comparison a != b.
+func ne(arg1, arg2 reflect.Value) (bool, error) {
+	// != is the inverse of ==.
+	equal, err := eq(arg1, arg2)
+	return !equal, err
+}
+
+// lt evaluates the comparison a < b.
+func lt(arg1, arg2 reflect.Value) (bool, error) {
+	arg1 = indirectInterface(arg1)
+	k1, err := basicKind(arg1)
+	if err != nil {
+		return false, err
+	}
+	arg2 = indirectInterface(arg2)
+	k2, err := basicKind(arg2)
+	if err != nil {
+		return false, err
+	}
+	truth := false
+	if k1 != k2 {
+		// Special case: Can compare integer values regardless of type's sign.
+		switch {
+		case k1 == intKind && k2 == uintKind:
+			truth = arg1.Int() < 0 || uint64(arg1.Int()) < arg2.Uint()
+		case k1 == uintKind && k2 == intKind:
+			truth = arg2.Int() >= 0 && arg1.Uint() < uint64(arg2.Int())
+		default:
+			return false, fmt.Errorf("incompatible types for comparison: %v and %v", arg1.Type(), arg2.Type())
+		}
+	} else {
+		switch k1 {
+		case boolKind, complexKind:
+			return false, errBadComparisonType
+		case floatKind:
+			truth = arg1.Float() < arg2.Float()
+		case intKind:
+			truth = arg1.Int() < arg2.Int()
+		case stringKind:
+			truth = arg1.String() < arg2.String()
+		case uintKind:
+			truth = arg1.Uint() < arg2.Uint()
+		default:
+			panic("invalid kind")
+		}
+	}
+	return truth, nil
+}
+
+// le evaluates the comparison <= b.
+func le(arg1, arg2 reflect.Value) (bool, error) {
+	// <= is < or ==.
+	lessThan, err := lt(arg1, arg2)
+	if lessThan || err != nil {
+		return lessThan, err
+	}
+	return eq(arg1, arg2)
+}
+
+// gt evaluates the comparison a > b.
+func gt(arg1, arg2 reflect.Value) (bool, error) {
+	// > is the inverse of <=.
+	lessOrEqual, err := le(arg1, arg2)
+	if err != nil {
+		return false, err
+	}
+	return !lessOrEqual, nil
+}
+
+// ge evaluates the comparison a >= b.
+func ge(arg1, arg2 reflect.Value) (bool, error) {
+	// >= is the inverse of <.
+	lessThan, err := lt(arg1, arg2)
+	if err != nil {
+		return false, err
+	}
+	return !lessThan, nil
+}
+
+// HTML escaping.
+
+var (
+	htmlQuot = []byte("&#34;") // shorter than "&quot;"
+	htmlApos = []byte("&#39;") // shorter than "&apos;" and apos was not in HTML until HTML5
+	htmlAmp  = []byte("&amp;")
+	htmlLt   = []byte("&lt;")
+	htmlGt   = []byte("&gt;")
+	htmlNull = []byte("\uFFFD")
+)
+
+// HTMLEscape writes to w the escaped HTML equivalent of the plain text data b.
+func HTMLEscape(w io.Writer, b []byte) {
+	last := 0
+	for i, c := range b {
+		var html []byte
+		switch c {
+		case '\000':
+			html = htmlNull
+		case '"':
+			html = htmlQuot
+		case '\'':
+			html = htmlApos
+		case '&':
+			html = htmlAmp
+		case '<':
+			html = htmlLt
+		case '>':
+			html = htmlGt
+		default:
+			continue
+		}
+		w.Write(b[last:i])
+		w.Write(html)
+		last = i + 1
+	}
+	w.Write(b[last:])
+}
+
+// HTMLEscapeString returns the escaped HTML equivalent of the plain text data s.
+func HTMLEscapeString(s string) string {
+	// Avoid allocation if we can.
+	if !strings.ContainsAny(s, "'\"&<>\000") {
+		return s
+	}
+	var b strings.Builder
+	HTMLEscape(&b, []byte(s))
+	return b.String()
+}
+
+// HTMLEscaper returns the escaped HTML equivalent of the textual
+// representation of its arguments.
+func HTMLEscaper(args ...any) string {
+	return HTMLEscapeString(evalArgs(args))
+}
+
+// JavaScript escaping.
+
+var (
+	jsLowUni = []byte(`\u00`)
+	hex      = []byte("0123456789ABCDEF")
+
+	jsBackslash = []byte(`\\`)
+	jsApos      = []byte(`\'`)
+	jsQuot      = []byte(`\"`)
+	jsLt        = []byte(`\u003C`)
+	jsGt        = []byte(`\u003E`)
+	jsAmp       = []byte(`\u0026`)
+	jsEq        = []byte(`\u003D`)
+)
+
+// JSEscape writes to w the escaped JavaScript equivalent of the plain text data b.
+func JSEscape(w io.Writer, b []byte) {
+	last := 0
+	for i := 0; i < len(b); i++ {
+		c := b[i]
+
+		if !jsIsSpecial(rune(c)) {
+			// fast path: nothing to do
+			continue
+		}
+		w.Write(b[last:i])
+
+		if c < utf8.RuneSelf {
+			// Quotes, slashes and angle brackets get quoted.
+			// Control characters get written as \u00XX.
+			switch c {
+			case '\\':
+				w.Write(jsBackslash)
+			case '\'':
+				w.Write(jsApos)
+			case '"':
+				w.Write(jsQuot)
+			case '<':
+				w.Write(jsLt)
+			case '>':
+				w.Write(jsGt)
+			case '&':
+				w.Write(jsAmp)
+			case '=':
+				w.Write(jsEq)
+			default:
+				w.Write(jsLowUni)
+				t, b := c>>4, c&0x0f
+				w.Write(hex[t : t+1])
+				w.Write(hex[b : b+1])
+			}
+		} else {
+			// Unicode rune.
+			r, size := utf8.DecodeRune(b[i:])
+			if unicode.IsPrint(r) {
+				w.Write(b[i : i+size])
+			} else {
+				fmt.Fprintf(w, "\\u%04X", r)
+			}
+			i += size - 1
+		}
+		last = i + 1
+	}
+	w.Write(b[last:])
+}
+
+// JSEscapeString returns the escaped JavaScript equivalent of the plain text data s.
+func JSEscapeString(s string) string {
+	// Avoid allocation if we can.
+	if strings.IndexFunc(s, jsIsSpecial) < 0 {
+		return s
+	}
+	var b strings.Builder
+	JSEscape(&b, []byte(s))
+	return b.String()
+}
+
+func jsIsSpecial(r rune) bool {
+	switch r {
+	case '\\', '\'', '"', '<', '>', '&', '=':
+		return true
+	}
+	return r < ' ' || utf8.RuneSelf <= r
+}
+
+// JSEscaper returns the escaped JavaScript equivalent of the textual
+// representation of its arguments.
+func JSEscaper(args ...any) string {
+	return JSEscapeString(evalArgs(args))
+}
+
+// URLQueryEscaper returns the escaped value of the textual representation of
+// its arguments in a form suitable for embedding in a URL query.
+func URLQueryEscaper(args ...any) string {
+	return url.QueryEscape(evalArgs(args))
+}
+
+// evalArgs formats the list of arguments into a string. It is therefore equivalent to
+//
+//	fmt.Sprint(args...)
+//
+// except that each argument is indirected (if a pointer), as required,
+// using the same rules as the default string evaluation during template
+// execution.
+func evalArgs(args []any) string {
+	ok := false
+	var s string
+	// Fast path for simple common case.
+	if len(args) == 1 {
+		s, ok = args[0].(string)
+	}
+	if !ok {
+		for i, arg := range args {
+			a, ok := printableValue(reflect.ValueOf(arg))
+			if ok {
+				args[i] = a
+			} // else let fmt do its thing
+		}
+		s = fmt.Sprint(args...)
+	}
+	return s
+}

template/gotext/helper.go

@@ -0,0 +1,178 @@
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Helper functions to make constructing templates easier.
+
+package gotext
+
+import (
+	"fmt"
+	"io/fs"
+	"os"
+	"path"
+	"path/filepath"
+)
+
+// Functions and methods to parse templates.
+
+// Must is a helper that wraps a call to a function returning ([*Template], error)
+// and panics if the error is non-nil. It is intended for use in variable
+// initializations such as
+//
+//	var t = template.Must(template.New("name").Parse("text"))
+func Must(t *Template, err error) *Template {
+	if err != nil {
+		panic(err)
+	}
+	return t
+}
+
+// ParseFiles creates a new [Template] and parses the template definitions from
+// the named files. The returned template's name will have the base name and
+// parsed contents of the first file. There must be at least one file.
+// If an error occurs, parsing stops and the returned *Template is nil.
+//
+// When parsing multiple files with the same name in different directories,
+// the last one mentioned will be the one that results.
+// For instance, ParseFiles("a/foo", "b/foo") stores "b/foo" as the template
+// named "foo", while "a/foo" is unavailable.
+func ParseFiles(filenames ...string) (*Template, error) {
+	return parseFiles(nil, readFileOS, filenames...)
+}
+
+// ParseFiles parses the named files and associates the resulting templates with
+// t. If an error occurs, parsing stops and the returned template is nil;
+// otherwise it is t. There must be at least one file.
+// Since the templates created by ParseFiles are named by the base
+// (see [filepath.Base]) names of the argument files, t should usually have the
+// name of one of the (base) names of the files. If it does not, depending on
+// t's contents before calling ParseFiles, t.Execute may fail. In that
+// case use t.ExecuteTemplate to execute a valid template.
+//
+// When parsing multiple files with the same name in different directories,
+// the last one mentioned will be the one that results.
+func (t *Template) ParseFiles(filenames ...string) (*Template, error) {
+	t.init()
+	return parseFiles(t, readFileOS, filenames...)
+}
+
+// parseFiles is the helper for the method and function. If the argument
+// template is nil, it is created from the first file.
+func parseFiles(t *Template, readFile func(string) (string, []byte, error), filenames ...string) (*Template, error) {
+	if len(filenames) == 0 {
+		// Not really a problem, but be consistent.
+		return nil, fmt.Errorf("template: no files named in call to ParseFiles")
+	}
+	for _, filename := range filenames {
+		name, b, err := readFile(filename)
+		if err != nil {
+			return nil, err
+		}
+		s := string(b)
+		// First template becomes return value if not already defined,
+		// and we use that one for subsequent New calls to associate
+		// all the templates together. Also, if this file has the same name
+		// as t, this file becomes the contents of t, so
+		//  t, err := New(name).Funcs(xxx).ParseFiles(name)
+		// works. Otherwise we create a new template associated with t.
+		var tmpl *Template
+		if t == nil {
+			t = New(name)
+		}
+		if name == t.Name() {
+			tmpl = t
+		} else {
+			tmpl = t.New(name)
+		}
+		_, err = tmpl.Parse(s)
+		if err != nil {
+			return nil, err
+		}
+	}
+	return t, nil
+}
+
+// ParseGlob creates a new [Template] and parses the template definitions from
+// the files identified by the pattern. The files are matched according to the
+// semantics of [filepath.Match], and the pattern must match at least one file.
+// The returned template will have the [filepath.Base] name and (parsed)
+// contents of the first file matched by the pattern. ParseGlob is equivalent to
+// calling [ParseFiles] with the list of files matched by the pattern.
+//
+// When parsing multiple files with the same name in different directories,
+// the last one mentioned will be the one that results.
+func ParseGlob(pattern string) (*Template, error) {
+	return parseGlob(nil, pattern)
+}
+
+// ParseGlob parses the template definitions in the files identified by the
+// pattern and associates the resulting templates with t. The files are matched
+// according to the semantics of [filepath.Match], and the pattern must match at
+// least one file. ParseGlob is equivalent to calling [Template.ParseFiles] with
+// the list of files matched by the pattern.
+//
+// When parsing multiple files with the same name in different directories,
+// the last one mentioned will be the one that results.
+func (t *Template) ParseGlob(pattern string) (*Template, error) {
+	t.init()
+	return parseGlob(t, pattern)
+}
+
+// parseGlob is the implementation of the function and method ParseGlob.
+func parseGlob(t *Template, pattern string) (*Template, error) {
+	filenames, err := filepath.Glob(pattern)
+	if err != nil {
+		return nil, err
+	}
+	if len(filenames) == 0 {
+		return nil, fmt.Errorf("template: pattern matches no files: %#q", pattern)
+	}
+	return parseFiles(t, readFileOS, filenames...)
+}
+
+// ParseFS is like [Template.ParseFiles] or [Template.ParseGlob] but reads from the file system fsys
+// instead of the host operating system's file system.
+// It accepts a list of glob patterns (see [path.Match]).
+// (Note that most file names serve as glob patterns matching only themselves.)
+func ParseFS(fsys fs.FS, patterns ...string) (*Template, error) {
+	return parseFS(nil, fsys, patterns)
+}
+
+// ParseFS is like [Template.ParseFiles] or [Template.ParseGlob] but reads from the file system fsys
+// instead of the host operating system's file system.
+// It accepts a list of glob patterns (see [path.Match]).
+// (Note that most file names serve as glob patterns matching only themselves.)
+func (t *Template) ParseFS(fsys fs.FS, patterns ...string) (*Template, error) {
+	t.init()
+	return parseFS(t, fsys, patterns)
+}
+
+func parseFS(t *Template, fsys fs.FS, patterns []string) (*Template, error) {
+	var filenames []string
+	for _, pattern := range patterns {
+		list, err := fs.Glob(fsys, pattern)
+		if err != nil {
+			return nil, err
+		}
+		if len(list) == 0 {
+			return nil, fmt.Errorf("template: pattern matches no files: %#q", pattern)
+		}
+		filenames = append(filenames, list...)
+	}
+	return parseFiles(t, readFileFS(fsys), filenames...)
+}
+
+func readFileOS(file string) (name string, b []byte, err error) {
+	name = filepath.Base(file)
+	b, err = os.ReadFile(file)
+	return
+}
+
+func readFileFS(fsys fs.FS) func(string) (string, []byte, error) {
+	return func(file string) (name string, b []byte, err error) {
+		name = path.Base(file)
+		b, err = fs.ReadFile(fsys, file)
+		return
+	}
+}

template/gotext/option.go

@@ -0,0 +1,72 @@
+// Copyright 2015 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// This file contains the code to handle template options.
+
+package gotext
+
+import "strings"
+
+// missingKeyAction defines how to respond to indexing a map with a key that is not present.
+type missingKeyAction int
+
+const (
+	mapInvalid   missingKeyAction = iota // Return an invalid reflect.Value.
+	mapZeroValue                         // Return the zero value for the map element.
+	mapError                             // Error out
+)
+
+type option struct {
+	missingKey missingKeyAction
+}
+
+// Option sets options for the template. Options are described by
+// strings, either a simple string or "key=value". There can be at
+// most one equals sign in an option string. If the option string
+// is unrecognized or otherwise invalid, Option panics.
+//
+// Known options:
+//
+// missingkey: Control the behavior during execution if a map is
+// indexed with a key that is not present in the map.
+//
+//	"missingkey=default" or "missingkey=invalid"
+//		The default behavior: Do nothing and continue execution.
+//		If printed, the result of the index operation is the string
+//		"<no value>".
+//	"missingkey=zero"
+//		The operation returns the zero value for the map type's element.
+//	"missingkey=error"
+//		Execution stops immediately with an error.
+func (t *Template) Option(opt ...string) *Template {
+	t.init()
+	for _, s := range opt {
+		t.setOption(s)
+	}
+	return t
+}
+
+func (t *Template) setOption(opt string) {
+	if opt == "" {
+		panic("empty option string")
+	}
+	// key=value
+	if key, value, ok := strings.Cut(opt, "="); ok {
+		switch key {
+		case "missingkey":
+			switch value {
+			case "invalid", "default":
+				t.option.missingKey = mapInvalid
+				return
+			case "zero":
+				t.option.missingKey = mapZeroValue
+				return
+			case "error":
+				t.option.missingKey = mapError
+				return
+			}
+		}
+	}
+	panic("unrecognized option: " + opt)
+}

template/gotext/patches/0001-exec-context.patch

@@ -0,0 +1,149 @@
+--- a/exec.go	2026-07-10 01:31:35.188129862 +0200
++++ b/exec.go	2026-07-10 01:31:35.189129894 +0200
+@@ -5,14 +5,17 @@
+ package gotext
+ 
+ import (
++	"context"
+ 	"errors"
+ 	"fmt"
+-	"heckel.io/ntfy/v2/template/gotext/fmtsort"
+ 	"io"
+ 	"reflect"
+ 	"runtime"
+ 	"strings"
++	"sync/atomic"
+ 	"text/template/parse"
++
++	"heckel.io/ntfy/v2/template/gotext/fmtsort"
+ )
+ 
+ // maxExecDepth specifies the maximum stack depth of templates within
+@@ -32,11 +35,13 @@
+ // template so that multiple executions of the same template
+ // can execute in parallel.
+ type state struct {
+-	tmpl  *Template
+-	wr    io.Writer
+-	node  parse.Node // current node, for errors
+-	vars  []variable // push-down stack of variable values.
+-	depth int        // the height of the stack of executing templates.
++	tmpl      *Template
++	ctx       context.Context // ctx-ex: execution context; Execute uses context.Background.
++	wr        io.Writer
++	node      parse.Node   // current node, for errors
++	vars      []variable   // push-down stack of variable values.
++	depth     int          // the height of the stack of executing templates.
++	cancelled *atomic.Bool // ctx-ex: shared flag set by the context.AfterFunc watcher; nil if ctx cannot be canceled
+ }
+ 
+ // variable holds the dynamic value of a variable such as $, $x etc.
+@@ -160,6 +165,14 @@
+ 	})
+ }
+ 
++// cancelError is the wrapper type used internally when execution is aborted
++// because the context is done. Like writeError, it is stripped in errRecover
++// so the caller receives the original ctx.Err(). It is not an implementation
++// of error, so it cannot escape from the package as an error value.
++type cancelError struct {
++	Err error // Original context error.
++}
++
+ // errRecover is the handler that turns panics into returns from the top
+ // level of Parse.
+ func errRecover(errp *error) {
+@@ -170,6 +183,8 @@
+ 			panic(e)
+ 		case writeError:
+ 			*errp = err.Err // Strip the wrapper.
++		case cancelError:
++			*errp = err.Err // Strip the wrapper; return the context error.
+ 		case ExecError:
+ 			*errp = err // Keep the wrapper.
+ 		default:
+@@ -186,11 +201,19 @@
+ // A template may be executed safely in parallel, although if parallel
+ // executions share a Writer the output may be interleaved.
+ func (t *Template) ExecuteTemplate(wr io.Writer, name string, data any) error {
++	return t.ExecuteTemplateContext(context.Background(), wr, name, data)
++}
++
++// ExecuteTemplateContext is like [Template.ExecuteTemplate], but aborts and
++// returns ctx.Err() if ctx is canceled or its deadline is exceeded before
++// execution completes. See [Template.ExecuteContext] for the cancellation
++// semantics.
++func (t *Template) ExecuteTemplateContext(ctx context.Context, wr io.Writer, name string, data any) error {
+ 	tmpl := t.Lookup(name)
+ 	if tmpl == nil {
+ 		return fmt.Errorf("template: no template %q associated with template %q", name, t.name)
+ 	}
+-	return tmpl.Execute(wr, data)
++	return tmpl.ExecuteContext(ctx, wr, data)
+ }
+ 
+ // Execute applies a parsed template to the specified data object,
+@@ -204,10 +227,27 @@
+ // If data is a [reflect.Value], the template applies to the concrete
+ // value that the reflect.Value holds, as in [fmt.Print].
+ func (t *Template) Execute(wr io.Writer, data any) error {
+-	return t.execute(wr, data)
++	return t.executeContext(context.Background(), wr, data)
+ }
+ 
+-func (t *Template) execute(wr io.Writer, data any) (err error) {
++// ExecuteContext is like [Template.Execute], but aborts and returns ctx.Err()
++// (either [context.Canceled] or [context.DeadlineExceeded], retrievable with
++// [errors.Is]) if ctx is canceled or its deadline is exceeded before execution
++// completes.
++//
++// Cancellation is observed between node evaluations as the template is walked,
++// so long-running renders -- including tight or nested {{range}} loops that
++// write no output -- are aborted promptly. A template blocked inside a single
++// function call is not interrupted until that call returns. Partial results may
++// already have been written to wr.
++func (t *Template) ExecuteContext(ctx context.Context, wr io.Writer, data any) error {
++	if err := ctx.Err(); err != nil {
++		return err
++	}
++	return t.executeContext(ctx, wr, data)
++}
++
++func (t *Template) executeContext(ctx context.Context, wr io.Writer, data any) (err error) {
+ 	defer errRecover(&err)
+ 	value, ok := data.(reflect.Value)
+ 	if !ok {
+@@ -215,9 +255,20 @@
+ 	}
+ 	state := &state{
+ 		tmpl: t,
++		ctx:  ctx,
+ 		wr:   wr,
+ 		vars: []variable{{"$", value}},
+ 	}
++	// If the context can be canceled, watch it with a single context.AfterFunc
++	// callback that flips an atomic flag; walk polls that flag per node (a cheap
++	// monomorphic atomic load) instead of calling ctx.Err() every node.
++	// Contexts that can never be canceled (Background, TODO) have a nil Done
++	// channel, so the default Execute path installs nothing and pays nothing.
++	if ctx.Done() != nil {
++		state.cancelled = new(atomic.Bool)
++		stop := context.AfterFunc(ctx, func() { state.cancelled.Store(true) })
++		defer stop()
++	}
+ 	if t.Tree == nil || t.Root == nil {
+ 		state.errorf("%q is an incomplete or empty template", t.Name())
+ 	}
+@@ -260,6 +311,12 @@
+ // generating output as they go.
+ func (s *state) walk(dot reflect.Value, node parse.Node) {
+ 	s.at(node)
++	// Abort if the context has been canceled or its deadline has passed. The
++	// flag is set by the watcher installed in executeContext; observing it here
++	// interrupts any template shape, including loops that write no output.
++	if s.cancelled != nil && s.cancelled.Load() {
++		panic(cancelError{s.ctx.Err()})
++	}
+ 	switch node := node.(type) {
+ 	case *parse.ActionNode:
+ 		// Do not pop variables so they persist until next end.

template/gotext/template.go

@@ -0,0 +1,236 @@
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package gotext
+
+import (
+	"maps"
+	"reflect"
+	"sync"
+	"text/template/parse"
+)
+
+// common holds the information shared by related templates.
+type common struct {
+	tmpl   map[string]*Template // Map from name to defined templates.
+	muTmpl sync.RWMutex         // protects tmpl
+	option option
+	// We use two maps, one for parsing and one for execution.
+	// This separation makes the API cleaner since it doesn't
+	// expose reflection to the client.
+	muFuncs    sync.RWMutex // protects parseFuncs and execFuncs
+	parseFuncs FuncMap
+	execFuncs  map[string]reflect.Value
+}
+
+// Template is the representation of a parsed template. The *parse.Tree
+// field is exported only for use by [html/template] and should be treated
+// as unexported by all other clients.
+type Template struct {
+	name string
+	*parse.Tree
+	*common
+	leftDelim  string
+	rightDelim string
+}
+
+// New allocates a new, undefined template with the given name.
+func New(name string) *Template {
+	t := &Template{
+		name: name,
+	}
+	t.init()
+	return t
+}
+
+// Name returns the name of the template.
+func (t *Template) Name() string {
+	return t.name
+}
+
+// New allocates a new, undefined template associated with the given one and with the same
+// delimiters. The association, which is transitive, allows one template to
+// invoke another with a {{template}} action.
+//
+// Because associated templates share underlying data, template construction
+// cannot be done safely in parallel. Once the templates are constructed, they
+// can be executed in parallel.
+func (t *Template) New(name string) *Template {
+	t.init()
+	nt := &Template{
+		name:       name,
+		common:     t.common,
+		leftDelim:  t.leftDelim,
+		rightDelim: t.rightDelim,
+	}
+	return nt
+}
+
+// init guarantees that t has a valid common structure.
+func (t *Template) init() {
+	if t.common == nil {
+		c := new(common)
+		c.tmpl = make(map[string]*Template)
+		c.parseFuncs = make(FuncMap)
+		c.execFuncs = make(map[string]reflect.Value)
+		t.common = c
+	}
+}
+
+// Clone returns a duplicate of the template, including all associated
+// templates. The actual representation is not copied, but the name space of
+// associated templates is, so further calls to [Template.Parse] in the copy will add
+// templates to the copy but not to the original. Clone can be used to prepare
+// common templates and use them with variant definitions for other templates
+// by adding the variants after the clone is made.
+func (t *Template) Clone() (*Template, error) {
+	nt := t.copy(nil)
+	nt.init()
+	if t.common == nil {
+		return nt, nil
+	}
+	nt.option = t.option
+	t.muTmpl.RLock()
+	defer t.muTmpl.RUnlock()
+	for k, v := range t.tmpl {
+		if k == t.name {
+			nt.tmpl[t.name] = nt
+			continue
+		}
+		// The associated templates share nt's common structure.
+		tmpl := v.copy(nt.common)
+		nt.tmpl[k] = tmpl
+	}
+	t.muFuncs.RLock()
+	defer t.muFuncs.RUnlock()
+	maps.Copy(nt.parseFuncs, t.parseFuncs)
+	maps.Copy(nt.execFuncs, t.execFuncs)
+	return nt, nil
+}
+
+// copy returns a shallow copy of t, with common set to the argument.
+func (t *Template) copy(c *common) *Template {
+	return &Template{
+		name:       t.name,
+		Tree:       t.Tree,
+		common:     c,
+		leftDelim:  t.leftDelim,
+		rightDelim: t.rightDelim,
+	}
+}
+
+// AddParseTree associates the argument parse tree with the template t, giving
+// it the specified name. If the template has not been defined, this tree becomes
+// its definition. If it has been defined and already has that name, the existing
+// definition is replaced; otherwise a new template is created, defined, and returned.
+func (t *Template) AddParseTree(name string, tree *parse.Tree) (*Template, error) {
+	t.init()
+	t.muTmpl.Lock()
+	defer t.muTmpl.Unlock()
+	nt := t
+	if name != t.name {
+		nt = t.New(name)
+	}
+	// Even if nt == t, we need to install it in the common.tmpl map.
+	if t.associate(nt, tree) || nt.Tree == nil {
+		nt.Tree = tree
+	}
+	return nt, nil
+}
+
+// Templates returns a slice of defined templates associated with t.
+func (t *Template) Templates() []*Template {
+	if t.common == nil {
+		return nil
+	}
+	// Return a slice so we don't expose the map.
+	t.muTmpl.RLock()
+	defer t.muTmpl.RUnlock()
+	m := make([]*Template, 0, len(t.tmpl))
+	for _, v := range t.tmpl {
+		m = append(m, v)
+	}
+	return m
+}
+
+// Delims sets the action delimiters to the specified strings, to be used in
+// subsequent calls to [Template.Parse], [Template.ParseFiles], or [Template.ParseGlob]. Nested template
+// definitions will inherit the settings. An empty delimiter stands for the
+// corresponding default: {{ or }}.
+// The return value is the template, so calls can be chained.
+func (t *Template) Delims(left, right string) *Template {
+	t.init()
+	t.leftDelim = left
+	t.rightDelim = right
+	return t
+}
+
+// Funcs adds the elements of the argument map to the template's function map.
+// It must be called before the template is parsed.
+// It panics if a value in the map is not a function with appropriate return
+// type or if the name cannot be used syntactically as a function in a template.
+// It is legal to overwrite elements of the map. The return value is the template,
+// so calls can be chained.
+func (t *Template) Funcs(funcMap FuncMap) *Template {
+	t.init()
+	t.muFuncs.Lock()
+	defer t.muFuncs.Unlock()
+	addValueFuncs(t.execFuncs, funcMap)
+	addFuncs(t.parseFuncs, funcMap)
+	return t
+}
+
+// Lookup returns the template with the given name that is associated with t.
+// It returns nil if there is no such template or the template has no definition.
+func (t *Template) Lookup(name string) *Template {
+	if t.common == nil {
+		return nil
+	}
+	t.muTmpl.RLock()
+	defer t.muTmpl.RUnlock()
+	return t.tmpl[name]
+}
+
+// Parse parses text as a template body for t.
+// Named template definitions ({{define ...}} or {{block ...}} statements) in text
+// define additional templates associated with t and are removed from the
+// definition of t itself.
+//
+// Templates can be redefined in successive calls to Parse.
+// A template definition with a body containing only white space and comments
+// is considered empty and will not replace an existing template's body.
+// This allows using Parse to add new named template definitions without
+// overwriting the main template body.
+func (t *Template) Parse(text string) (*Template, error) {
+	t.init()
+	t.muFuncs.RLock()
+	trees, err := parse.Parse(t.name, text, t.leftDelim, t.rightDelim, t.parseFuncs, builtins())
+	t.muFuncs.RUnlock()
+	if err != nil {
+		return nil, err
+	}
+	// Add the newly parsed trees, including the one for t, into our common structure.
+	for name, tree := range trees {
+		if _, err := t.AddParseTree(name, tree); err != nil {
+			return nil, err
+		}
+	}
+	return t, nil
+}
+
+// associate installs the new template into the group of templates associated
+// with t. The two are already known to share the common structure.
+// The boolean return value reports whether to store this tree as t.Tree.
+func (t *Template) associate(new *Template, tree *parse.Tree) bool {
+	if new.common != t.common {
+		panic("internal error: associate not common")
+	}
+	if old := t.tmpl[new.name]; old != nil && parse.IsEmptyTree(tree.Root) && old.Tree != nil {
+		// If a template by that name exists,
+		// don't replace it with an empty template.
+		return false
+	}
+	t.tmpl[new.name] = new
+	return true
+}

twilio/client.go

@@ -0,0 +1,169 @@
+// Package twilio talks to the Twilio API to make phone calls (for the "Call" feature) and to
+// verify phone numbers. It holds the Twilio configuration, so that this functionality is
+// decoupled from the ntfy server.
+package twilio
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+
+	"heckel.io/ntfy/v2/log"
+	"heckel.io/ntfy/v2/util"
+)
+
+const (
+	tagTwilio = "twilio"
+)
+
+// Client is the Twilio API client
+type Client struct {
+	config *Config
+}
+
+// NewClient creates a new Twilio Client with the given config
+func NewClient(config *Config) *Client {
+	return &Client{config: config}
+}
+
+// Call calls the Twilio API to make a phone call to the given phone number, using the given data
+func (c *Client) Call(to string, data *CallData) error {
+	tmpl := defaultCallFormatTemplate
+	if c.config.CallFormat != nil {
+		tmpl = c.config.CallFormat
+	}
+	var bodyBuf bytes.Buffer
+	if err := tmpl.Execute(&bodyBuf, data.escaped()); err != nil {
+		log.Tag(tagTwilio).Err(err).Warn("Error executing Twilio call format template")
+		return err
+	}
+	body := bodyBuf.String()
+	form := url.Values{}
+	form.Set("From", c.config.PhoneNumber)
+	form.Set("To", to)
+	form.Set("Twiml", body)
+	ev := log.Tag(tagTwilio).
+		Field("twilio_to", to).
+		FieldIf("twilio_body", body, log.TraceLevel).
+		Debug("Sending Twilio request")
+	requestURL := fmt.Sprintf("%s/2010-04-01/Accounts/%s/Calls.json", c.config.CallsBaseURL, c.config.Account)
+	response, code, err := c.request(requestURL, form)
+	if err != nil {
+		ev.Field("twilio_response", response).Err(err).Warn("Error sending Twilio request")
+		return err
+	} else if !success(code) {
+		// Twilio rejects calls with a 4xx, e.g. for an invalid phone number, or if the account
+		// is out of funds. Without this check, a rejected call would be counted as a success.
+		ev.Field("twilio_status", code).Field("twilio_response", response).Warn("Twilio call failed with status code %d", code)
+		return fmt.Errorf("twilio call failed with status code %d", code)
+	}
+	ev.FieldIf("twilio_response", response, log.TraceLevel).Debug("Received successful Twilio response")
+	return nil
+}
+
+// Verify calls the Twilio Verify API to send a verification code to the given phone
+// number, via the given channel ("sms" or "call")
+func (c *Client) Verify(phoneNumber, channel string) error {
+	ev := log.Tag(tagTwilio).Field("twilio_to", phoneNumber).Field("twilio_channel", channel).Debug("Sending phone verification")
+	form := url.Values{}
+	form.Set("To", phoneNumber)
+	form.Set("Channel", channel)
+	requestURL := fmt.Sprintf("%s/v2/Services/%s/Verifications", c.config.VerifyBaseURL, c.config.VerifyService)
+	response, code, err := c.request(requestURL, form)
+	if err != nil {
+		ev.Err(err).Warn("Error sending Twilio phone verification request")
+		return err
+	} else if !success(code) {
+		// Without this check, a rejected verification would look like a success to the caller,
+		// and the user would be told to wait for an SMS that was never sent.
+		ev.Field("twilio_status", code).Field("twilio_response", response).Warn("Twilio phone verification request failed with status code %d", code)
+		return fmt.Errorf("twilio phone verification request failed with status code %d", code)
+	}
+	ev.FieldIf("twilio_response", response, log.TraceLevel).Debug("Received Twilio phone verification response")
+	return nil
+}
+
+// CheckVerify calls the Twilio Verify API to check the verification code for the given
+// phone number. It returns ErrVerificationExpired if the code has expired or never existed.
+func (c *Client) CheckVerify(phoneNumber, code string) error {
+	ev := log.Tag(tagTwilio).Field("twilio_to", phoneNumber).Debug("Checking phone verification")
+	form := url.Values{}
+	form.Set("To", phoneNumber)
+	form.Set("Code", code)
+	requestURL := fmt.Sprintf("%s/v2/Services/%s/VerificationCheck", c.config.VerifyBaseURL, c.config.VerifyService)
+	req, err := c.newRequest(requestURL, form)
+	if err != nil {
+		return err
+	}
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		if ev.IsTrace() {
+			response, err := io.ReadAll(resp.Body)
+			if err != nil {
+				return err
+			}
+			ev.Field("twilio_response", string(response))
+		}
+		ev.Warn("Twilio phone verification failed with status code %d", resp.StatusCode)
+		if resp.StatusCode == http.StatusNotFound {
+			return ErrVerificationExpired
+		}
+		return fmt.Errorf("twilio phone verification failed with status code %d", resp.StatusCode)
+	}
+	response, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return err
+	}
+	if ev.IsTrace() {
+		ev.Field("twilio_response", string(response)).Trace("Received successful Twilio phone verification response")
+	} else if ev.IsDebug() {
+		ev.Debug("Received successful Twilio phone verification response")
+	}
+	return nil
+}
+
+// request POSTs the given form to the given Twilio API URL, and returns the raw response body
+// and status code. It does not treat a non-2xx status code as an error; that is up to the
+// caller. The response body is returned even if the request failed, so that it can be logged.
+func (c *Client) request(requestURL string, form url.Values) (string, int, error) {
+	req, err := c.newRequest(requestURL, form)
+	if err != nil {
+		return "", 0, err
+	}
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return "", 0, err
+	}
+	defer resp.Body.Close()
+	response, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", resp.StatusCode, err
+	}
+	return string(response), resp.StatusCode, nil
+}
+
+// success reports whether the given HTTP status code indicates success. Note that the Twilio
+// Calls API returns 201 Created (not 200 OK) for a successfully queued call.
+func success(code int) bool {
+	return code >= 200 && code <= 299
+}
+
+// newRequest creates a form-encoded POST request against the Twilio API, with the auth and
+// User-Agent headers set
+func (c *Client) newRequest(requestURL string, form url.Values) (*http.Request, error) {
+	req, err := http.NewRequest(http.MethodPost, requestURL, strings.NewReader(form.Encode()))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("User-Agent", "ntfy/"+c.config.BuildVersion)
+	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
+	req.Header.Set("Authorization", util.BasicAuth(c.config.Account, c.config.AuthToken))
+	return req, nil
+}

twilio/client_test.go

@@ -0,0 +1,301 @@
+package twilio
+
+import (
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"testing"
+	"text/template"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestClient_Call_Success(t *testing.T) {
+	var body string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		require.Equal(t, "/2010-04-01/Accounts/AC1234567890/Calls.json", r.URL.Path)
+		require.Equal(t, "Basic QUMxMjM0NTY3ODkwOkFBRUFBMTIzNDU2Nzg5MA==", r.Header.Get("Authorization"))
+		require.Equal(t, "application/x-www-form-urlencoded", r.Header.Get("Content-Type"))
+		require.Equal(t, "ntfy/1.2.3", r.Header.Get("User-Agent"))
+		b, err := io.ReadAll(r.Body)
+		require.Nil(t, err)
+		body = string(b)
+	}))
+	defer server.Close()
+
+	c := NewClient(testConfig(server.URL))
+	require.Nil(t, c.Call("+11122233344", &CallData{Topic: "mytopic", Message: "hi there", Sender: "phil"}))
+
+	form, err := url.ParseQuery(body)
+	require.Nil(t, err)
+	require.Equal(t, "+1234567890", form.Get("From"))
+	require.Equal(t, "+11122233344", form.Get("To"))
+	require.Contains(t, form.Get("Twiml"), "You have a message from notify on topic mytopic. Message:")
+	require.Contains(t, form.Get("Twiml"), "hi there")
+	require.Contains(t, form.Get("Twiml"), "This message was sent by user phil.")
+}
+
+// TestClient_Call_EscapesXML ensures that user-controlled fields cannot break out of the
+// TwiML document, i.e. that a message containing XML is escaped rather than interpreted
+func TestClient_Call_EscapesXML(t *testing.T) {
+	var body string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		b, err := io.ReadAll(r.Body)
+		require.Nil(t, err)
+		body = string(b)
+	}))
+	defer server.Close()
+
+	c := NewClient(testConfig(server.URL))
+	data := &CallData{
+		Topic:   "mytopic",
+		Message: `</Say><Say>evil</Say>`,
+		Tags:    []string{"<tag>"},
+		Sender:  `phil & "friends"`,
+	}
+	require.Nil(t, c.Call("+11122233344", data))
+
+	form, err := url.ParseQuery(body)
+	require.Nil(t, err)
+	twiml := form.Get("Twiml")
+	require.NotContains(t, twiml, "<Say>evil</Say>")
+	require.Contains(t, twiml, "&lt;/Say&gt;&lt;Say&gt;evil&lt;/Say&gt;")
+	require.Contains(t, twiml, "phil &amp; &#34;friends&#34;")
+	// The caller's data must not be modified by the escaping
+	require.Equal(t, `</Say><Say>evil</Say>`, data.Message)
+	require.Equal(t, []string{"<tag>"}, data.Tags)
+}
+
+func TestClient_Call_CustomCallFormat(t *testing.T) {
+	var body string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		b, err := io.ReadAll(r.Body)
+		require.Nil(t, err)
+		body = string(b)
+	}))
+	defer server.Close()
+
+	conf := testConfig(server.URL)
+	conf.CallFormat = template.Must(template.New("twiml").Parse(`<Response><Say>{{.Message}} von {{.Sender}}</Say></Response>`))
+	c := NewClient(conf)
+	require.Nil(t, c.Call("+11122233344", &CallData{Topic: "mytopic", Message: "hi there", Sender: "phil"}))
+
+	form, err := url.ParseQuery(body)
+	require.Nil(t, err)
+	require.Equal(t, "<Response><Say>hi there von phil</Say></Response>", form.Get("Twiml"))
+}
+
+// TestClient_Call_RendersAllFields covers the fields that the default TwiML template does not
+// use, i.e. Title, Priority and Tags, including the escaping of every tag
+func TestClient_Call_RendersAllFields(t *testing.T) {
+	var body string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		b, err := io.ReadAll(r.Body)
+		require.Nil(t, err)
+		body = string(b)
+	}))
+	defer server.Close()
+
+	conf := testConfig(server.URL)
+	conf.CallFormat = template.Must(template.New("twiml").Parse(`<Response><Say>{{.Title}}/{{.Priority}}{{range .Tags}}/{{.}}{{end}}</Say></Response>`))
+	c := NewClient(conf)
+	data := &CallData{
+		Topic:    "mytopic",
+		Title:    "a <title>",
+		Priority: 5,
+		Tags:     []string{"<one>", "two & three"},
+	}
+	require.Nil(t, c.Call("+11122233344", data))
+
+	form, err := url.ParseQuery(body)
+	require.Nil(t, err)
+	require.Equal(t, "<Response><Say>a &lt;title&gt;/5/&lt;one&gt;/two &amp; three</Say></Response>", form.Get("Twiml"))
+}
+
+func TestClient_Call_TemplateError(t *testing.T) {
+	conf := testConfig("http://dummy.invalid")
+	conf.CallFormat = template.Must(template.New("twiml").Parse(`{{.DoesNotExist}}`))
+	c := NewClient(conf)
+	require.Error(t, c.Call("+11122233344", &CallData{Topic: "mytopic"}))
+}
+
+// TestClient_Call_Created ensures that a 201 Created is treated as a success. The Twilio Calls
+// API returns 201 (not 200) for a successfully queued call, so this must not be an error.
+func TestClient_Call_Created(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusCreated)
+		w.Write([]byte(`{"status":"queued"}`))
+	}))
+	defer server.Close()
+
+	c := NewClient(testConfig(server.URL))
+	require.Nil(t, c.Call("+11122233344", &CallData{Topic: "mytopic", Message: "hi there"}))
+}
+
+// TestClient_Call_TwilioError ensures that a non-2xx response from Twilio is returned as an
+// error, so that the server counts it as a failure instead of a success. Twilio rejects calls
+// with a 4xx, e.g. for an invalid "To" number, or when the account is out of funds.
+func TestClient_Call_TwilioError(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusBadRequest)
+		w.Write([]byte(`{"code":21211,"message":"Invalid 'To' Phone Number: +invalid"}`))
+	}))
+	defer server.Close()
+
+	c := NewClient(testConfig(server.URL))
+	err := c.Call("+invalid", &CallData{Topic: "mytopic", Message: "hi there"})
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "400")
+}
+
+func TestClient_Call_TwilioServerError(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	defer server.Close()
+
+	c := NewClient(testConfig(server.URL))
+	require.Error(t, c.Call("+11122233344", &CallData{Topic: "mytopic", Message: "hi there"}))
+}
+
+// TestClient_Call_TransportError ensures that a call to an unreachable Twilio API returns an
+// error, so that the server can count it as a failure
+func TestClient_Call_TransportError(t *testing.T) {
+	c := NewClient(testConfig(closedServerURL(t)))
+	require.Error(t, c.Call("+11122233344", &CallData{Topic: "mytopic", Message: "hi there"}))
+}
+
+func TestClient_Call_InvalidBaseURL(t *testing.T) {
+	c := NewClient(testConfig("://invalid"))
+	require.Error(t, c.Call("+11122233344", &CallData{Topic: "mytopic", Message: "hi there"}))
+}
+
+// TestClient_Verify_Created ensures that a 201 Created is treated as a success. The Twilio
+// Verify API returns 201 (not 200) when it creates a verification, so this must not be an error.
+func TestClient_Verify_Created(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusCreated)
+		w.Write([]byte(`{"status":"pending"}`))
+	}))
+	defer server.Close()
+
+	c := NewClient(testConfig(server.URL))
+	require.Nil(t, c.Verify("+12223334444", "sms"))
+}
+
+// TestClient_Verify_TwilioError ensures that a non-2xx response from Twilio is returned as an
+// error. Without this, no SMS is sent, but the user is still told to check their phone.
+func TestClient_Verify_TwilioError(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusBadRequest)
+		w.Write([]byte(`{"code":60200,"message":"Invalid parameter"}`))
+	}))
+	defer server.Close()
+
+	c := NewClient(testConfig(server.URL))
+	err := c.Verify("+12223334444", "sms")
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "400")
+}
+
+func TestClient_Verify_Unauthorized(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusUnauthorized)
+	}))
+	defer server.Close()
+
+	c := NewClient(testConfig(server.URL))
+	require.Error(t, c.Verify("+12223334444", "sms"))
+}
+
+func TestClient_Verify_TransportError(t *testing.T) {
+	c := NewClient(testConfig(closedServerURL(t)))
+	require.Error(t, c.Verify("+12223334444", "sms"))
+}
+
+func TestClient_CheckVerify_TransportError(t *testing.T) {
+	c := NewClient(testConfig(closedServerURL(t)))
+	err := c.CheckVerify("+12223334444", "123456")
+	require.Error(t, err)
+	require.False(t, errors.Is(err, ErrVerificationExpired))
+}
+
+func TestClient_Verify_Success(t *testing.T) {
+	var body string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		require.Equal(t, "/v2/Services/VA1234567890/Verifications", r.URL.Path)
+		require.Equal(t, "Basic QUMxMjM0NTY3ODkwOkFBRUFBMTIzNDU2Nzg5MA==", r.Header.Get("Authorization"))
+		b, err := io.ReadAll(r.Body)
+		require.Nil(t, err)
+		body = string(b)
+	}))
+	defer server.Close()
+
+	c := NewClient(testConfig(server.URL))
+	require.Nil(t, c.Verify("+12223334444", "sms"))
+	require.Equal(t, "Channel=sms&To=%2B12223334444", body)
+}
+
+func TestClient_CheckVerify_Success(t *testing.T) {
+	var body string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		require.Equal(t, "/v2/Services/VA1234567890/VerificationCheck", r.URL.Path)
+		b, err := io.ReadAll(r.Body)
+		require.Nil(t, err)
+		body = string(b)
+	}))
+	defer server.Close()
+
+	c := NewClient(testConfig(server.URL))
+	require.Nil(t, c.CheckVerify("+12223334444", "123456"))
+	require.Equal(t, "Code=123456&To=%2B12223334444", body)
+}
+
+// TestClient_CheckVerify_Expired ensures that a 404 from the Twilio Verify API is
+// mapped to ErrVerificationExpired, which the server turns into an HTTP 410
+func TestClient_CheckVerify_Expired(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	defer server.Close()
+
+	c := NewClient(testConfig(server.URL))
+	err := c.CheckVerify("+12223334444", "123456")
+	require.True(t, errors.Is(err, ErrVerificationExpired))
+}
+
+func TestClient_CheckVerify_OtherError(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	defer server.Close()
+
+	c := NewClient(testConfig(server.URL))
+	err := c.CheckVerify("+12223334444", "123456")
+	require.Error(t, err)
+	require.False(t, errors.Is(err, ErrVerificationExpired))
+}
+
+// closedServerURL returns the URL of a server that is not listening anymore, to simulate an
+// unreachable Twilio API
+func closedServerURL(t *testing.T) string {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatal("Should not be called")
+	}))
+	server.Close()
+	return server.URL
+}
+
+func testConfig(baseURL string) *Config {
+	return &Config{
+		Account:       "AC1234567890",
+		AuthToken:     "AAEAA1234567890",
+		PhoneNumber:   "+1234567890",
+		CallsBaseURL:  baseURL,
+		VerifyBaseURL: baseURL,
+		VerifyService: "VA1234567890",
+		BuildVersion:  "1.2.3",
+	}
+}

twilio/types.go

@@ -0,0 +1,80 @@
+package twilio
+
+import (
+	"bytes"
+	"encoding/xml"
+	"errors"
+	"text/template"
+)
+
+// ErrVerificationExpired is returned by CheckVerify if the verification code has
+// expired, or if it never existed in the first place
+var ErrVerificationExpired = errors.New("phone number verification expired or does not exist")
+
+// Config holds the Twilio configuration for the client
+type Config struct {
+	Account       string             // Twilio account SID, e.g. AC123...
+	AuthToken     string             // Twilio auth token
+	PhoneNumber   string             // Twilio number to use for outgoing calls
+	CallsBaseURL  string             // Base URL of the Twilio Calls API
+	VerifyBaseURL string             // Base URL of the Twilio Verify API
+	VerifyService string             // Twilio Verify service ID, e.g. VA123...
+	CallFormat    *template.Template // TwiML template for calls; if nil, defaultCallFormatTemplate is used
+	BuildVersion  string             // ntfy version, used for the User-Agent header
+}
+
+// defaultCallFormatTemplate is the default TwiML template used for Twilio calls.
+// It can be overridden in the server configuration's twilio-call-format field.
+//
+// The format uses Go template syntax with the following fields:
+// {{.Topic}}, {{.Title}}, {{.Message}}, {{.Priority}}, {{.Tags}}, {{.Sender}}
+// String fields are automatically XML-escaped.
+var defaultCallFormatTemplate = template.Must(template.New("twiml").Parse(`
+<Response>
+	<Pause length="1"/>
+	<Say loop="3">
+		You have a message from notify on topic {{.Topic}}. Message:
+		<break time="1s"/>
+		{{.Message}}
+		<break time="1s"/>
+		End of message.
+		<break time="1s"/>
+		This message was sent by user {{.Sender}}. It will be repeated three times.
+		To unsubscribe from calls like this, remove your phone number in the notify web app.
+		<break time="3s"/>
+	</Say>
+	<Say>Goodbye.</Say>
+</Response>`))
+
+// CallData holds the data passed to the Twilio call format template. String fields are
+// XML-escaped before the template is executed, so callers pass them unescaped.
+type CallData struct {
+	Topic    string
+	Title    string
+	Message  string
+	Priority int
+	Tags     []string
+	Sender   string
+}
+
+// escaped returns a copy of the call data with all string fields XML-escaped
+func (d *CallData) escaped() *CallData {
+	tags := make([]string, len(d.Tags))
+	for i, tag := range d.Tags {
+		tags[i] = xmlEscapeText(tag)
+	}
+	return &CallData{
+		Topic:    xmlEscapeText(d.Topic),
+		Title:    xmlEscapeText(d.Title),
+		Message:  xmlEscapeText(d.Message),
+		Priority: d.Priority,
+		Tags:     tags,
+		Sender:   xmlEscapeText(d.Sender),
+	}
+}
+
+func xmlEscapeText(text string) string {
+	var buf bytes.Buffer
+	_ = xml.EscapeText(&buf, []byte(text))
+	return buf.String()
+}