Merge branch 'main' into cluster2

Revert "add tzdata to docker arm build"

.github/dependabot.yml

@@ -0,0 +1,26 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/web"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7
+
+  - package-ecosystem: "gomod"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7
+    groups:
+      all:
+        patterns:
+          - "*"

.github/workflows/build.yaml

@@ -1,19 +1,22 @@
 name: build
-on: [ push, pull_request ]
+on:
+  push:
+    branches: [ main ]
+  pull_request:
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Install Go
-        uses: actions/setup-go@v4
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
-          go-version: '1.24.x'
+          go-version-file: '.go-version'
       - name: Install node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
-          node-version: '20'
+          node-version: '24'
           cache: 'npm'
           cache-dependency-path: './web/package-lock.json'
       - name: Install dependencies

.github/workflows/docs.yaml

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

.github/workflows/release.yaml

@@ -22,21 +22,22 @@ jobs:
           --health-retries 5
     env:
       NTFY_TEST_DATABASE_URL: "postgres://ntfy:ntfy@localhost:5432/ntfy_test?sslmode=disable"
+      NTFY_TEST_S3_URL: ${{ secrets.NTFY_TEST_S3_URL }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Install Go
-        uses: actions/setup-go@v4
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
-          go-version: '1.24.x'
+          go-version-file: '.go-version'
       - name: Install node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
-          node-version: '20'
+          node-version: '24'
           cache: 'npm'
           cache-dependency-path: './web/package-lock.json'
       - name: Docker login
-        uses: docker/login-action@v2
+        uses: docker/login-action@371161bbe7024a29a25c5e19bfcbc0804fe9ad2c # v4.5.2
         with:
           username: ${{ github.repository_owner }}
           password: ${{ secrets.DOCKER_HUB_TOKEN }}

.github/workflows/test.yaml

@@ -1,5 +1,8 @@
 name: test
-on: [ push, pull_request ]
+on:
+  push:
+    branches: [ main ]
+  pull_request:
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -19,17 +22,18 @@ jobs:
           --health-retries 5
     env:
       NTFY_TEST_DATABASE_URL: "postgres://ntfy:ntfy@localhost:5432/ntfy_test?sslmode=disable"
+      NTFY_TEST_S3_URL: ${{ secrets.NTFY_TEST_S3_URL }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Install Go
-        uses: actions/setup-go@v4
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
-          go-version: '1.24.x'
+          go-version-file: '.go-version'
       - name: Install node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
-          node-version: '20'
+          node-version: '24'
           cache: 'npm'
           cache-dependency-path: './web/package-lock.json'
       - name: Install dependencies

.gitignore

@@ -9,6 +9,7 @@ server/site/
 tools/fbsend/fbsend
 tools/pgimport/pgimport
 tools/loadtest/loadtest
+tools/s3cli/s3cli
 playground/
 secrets/
 *.iml

.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

@@ -1,8 +1,8 @@
-FROM golang:1.24-bullseye as builder
+FROM golang:1.25-bookworm AS builder
 
 ARG VERSION=dev
 ARG COMMIT=unknown
-ARG NODE_MAJOR=18
+ARG NODE_MAJOR=24
 
 RUN apt-get update && apt-get install -y \
        build-essential ca-certificates curl gnupg \
@@ -21,14 +21,14 @@ ADD Makefile .
 
 # docs
 ADD ./requirements.txt .
-RUN make docs-deps
+RUN --mount=type=cache,target=/root/.cache/pip make docs-deps
 ADD ./mkdocs.yml .
 ADD ./docs ./docs
 RUN make docs-build
 
 # web
 ADD ./web/package.json ./web/package-lock.json ./web/
-RUN make web-deps
+RUN --mount=type=cache,target=/root/.npm make web-deps
 ADD ./web ./web
 RUN make web-build
 
@@ -41,7 +41,17 @@ ADD ./server ./server
 ADD ./user ./user
 ADD ./util ./util
 ADD ./payments ./payments
-RUN make VERSION=$VERSION COMMIT=$COMMIT cli-linux-server
+ADD ./db ./db
+ADD ./message ./message
+ADD ./model ./model
+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)
 
 
@@ -146,11 +151,13 @@ web-build:
 			../server/site/config.js
 
 web-deps:
-	cd web && $(NPM) install
+	cd web && $(NPM) ci
+	# Use "npm ci" so that we don't change the package lock file
 	# If this fails for .svg files, optimize them with svgo
 
 web-deps-update:
-	cd web && $(NPM) update
+	cd web && $(NPM) update --before="$(shell date -d '7 days ago' +%Y-%m-%d)"
+	cd web && $(NPM) install
 
 web-fmt:
 	cd web && $(NPM) run format
@@ -161,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
@@ -263,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:
@@ -303,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
@@ -324,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)")
 
 }

attachment/backend.go

@@ -0,0 +1,23 @@
+package attachment
+
+import (
+	"io"
+	"time"
+)
+
+// backendObject represents an object stored in a backend.
+type object struct {
+	ID           string
+	Size         int64
+	LastModified time.Time
+}
+
+// backend is a minimal I/O interface for storing and retrieving attachment files.
+// It has no knowledge of size tracking, limiting, or ID validation.
+type backend interface {
+	Put(id string, reader io.Reader, untrustedLength int64) error
+	Get(id string) (io.ReadCloser, int64, error)
+	List() ([]object, error)
+	Delete(ids ...string) error
+	DeleteIncomplete(cutoff time.Time) error
+}

attachment/backend_file.go

@@ -0,0 +1,94 @@
+package attachment
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+type fileBackend struct {
+	dir string
+}
+
+var _ backend = (*fileBackend)(nil)
+
+func newFileBackend(dir string) (*fileBackend, error) {
+	if err := os.MkdirAll(dir, 0700); err != nil {
+		return nil, err
+	}
+	return &fileBackend{dir: dir}, nil
+}
+
+func (b *fileBackend) Put(id string, reader io.Reader, untrustedLength int64) error {
+	if untrustedLength > 0 {
+		reader = io.LimitReader(reader, untrustedLength)
+	}
+	file := filepath.Join(b.dir, id)
+	f, err := os.OpenFile(file, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0600)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	n, err := io.Copy(f, reader)
+	if err != nil {
+		os.Remove(file)
+		return err
+	} else if untrustedLength > 0 && n != untrustedLength {
+		os.Remove(file)
+		return fmt.Errorf("content length mismatch: claimed %d, got %d", untrustedLength, n)
+	}
+	if err := f.Close(); err != nil {
+		os.Remove(file)
+		return err
+	}
+	return nil
+}
+
+func (b *fileBackend) List() ([]object, error) {
+	entries, err := os.ReadDir(b.dir)
+	if err != nil {
+		return nil, err
+	}
+	objects := make([]object, 0, len(entries))
+	for _, e := range entries {
+		info, err := e.Info()
+		if err != nil {
+			return nil, err
+		}
+		objects = append(objects, object{
+			ID:           e.Name(),
+			Size:         info.Size(),
+			LastModified: info.ModTime(),
+		})
+	}
+	return objects, nil
+}
+
+func (b *fileBackend) Get(id string) (io.ReadCloser, int64, error) {
+	file := filepath.Join(b.dir, id)
+	stat, err := os.Stat(file)
+	if err != nil {
+		return nil, 0, err
+	}
+	f, err := os.Open(file)
+	if err != nil {
+		return nil, 0, err
+	}
+	return f, stat.Size(), nil
+}
+
+func (b *fileBackend) Delete(ids ...string) error {
+	for _, id := range ids {
+		file := filepath.Join(b.dir, id)
+		if err := os.Remove(file); err != nil && !os.IsNotExist(err) {
+			return err
+		}
+	}
+	return nil
+}
+
+func (b *fileBackend) DeleteIncomplete(_ time.Time) error {
+	return nil
+}

attachment/backend_s3.go

@@ -0,0 +1,51 @@
+package attachment
+
+import (
+	"context"
+	"io"
+	"time"
+
+	"heckel.io/ntfy/v2/s3"
+)
+
+type s3Backend struct {
+	client *s3.Client
+}
+
+var _ backend = (*s3Backend)(nil)
+
+func newS3Backend(client *s3.Client) *s3Backend {
+	return &s3Backend{client: client}
+}
+
+func (b *s3Backend) Put(id string, reader io.Reader, untrustedLength int64) error {
+	return b.client.PutObject(context.Background(), id, reader, untrustedLength)
+}
+
+func (b *s3Backend) Get(id string) (io.ReadCloser, int64, error) {
+	return b.client.GetObject(context.Background(), id)
+}
+
+func (b *s3Backend) List() ([]object, error) {
+	objects, err := b.client.ListObjectsV2(context.Background())
+	if err != nil {
+		return nil, err
+	}
+	result := make([]object, 0, len(objects))
+	for _, obj := range objects {
+		result = append(result, object{
+			ID:           obj.Key,
+			Size:         obj.Size,
+			LastModified: obj.LastModified,
+		})
+	}
+	return result, nil
+}
+
+func (b *s3Backend) Delete(ids ...string) error {
+	return b.client.DeleteObjects(context.Background(), ids)
+}
+
+func (b *s3Backend) DeleteIncomplete(cutoff time.Time) error {
+	return b.client.AbortIncompleteUploads(context.Background(), cutoff)
+}

attachment/store.go

@@ -0,0 +1,246 @@
+package attachment
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"sync"
+	"time"
+
+	"heckel.io/ntfy/v2/log"
+	"heckel.io/ntfy/v2/model"
+	"heckel.io/ntfy/v2/s3"
+	"heckel.io/ntfy/v2/util"
+)
+
+const (
+	tagStore     = "attachment_store"
+	syncInterval = 15 * time.Minute // How often to run the background sync loop
+)
+
+var errInvalidFileID = errors.New("invalid file ID")
+
+// Store manages attachment storage with shared logic for size tracking, limiting,
+// ID validation, and background sync to reconcile storage with the database.
+type Store struct {
+	backend              backend
+	limit                int64                            // Defined limit of the store in bytes
+	size                 int64                            // Current size of the store in bytes
+	sizes                map[string]int64                 // File ID -> size, for subtracting on Remove
+	attachmentsWithSizes func() (map[string]int64, error) // Returns file ID -> size for active attachments
+	orphanGracePeriod    time.Duration                    // Don't delete orphaned objects younger than this
+	closeChan            chan struct{}
+	doneChan             chan struct{}
+	mu                   sync.RWMutex // Protects size and sizes
+}
+
+// NewFileStore creates a new file-system backed attachment cache
+func NewFileStore(dir string, totalSizeLimit int64, orphanGracePeriod time.Duration, attachmentsWithSizes func() (map[string]int64, error)) (*Store, error) {
+	b, err := newFileBackend(dir)
+	if err != nil {
+		return nil, err
+	}
+	return newStore(b, totalSizeLimit, orphanGracePeriod, attachmentsWithSizes)
+}
+
+// NewS3Store creates a new S3-backed attachment cache. The s3URL must be in the format:
+//
+//	s3://ACCESS_KEY:SECRET_KEY@BUCKET[/PREFIX]?region=REGION[&endpoint=ENDPOINT][&disable_http2=true]
+func NewS3Store(s3URL string, totalSizeLimit int64, orphanGracePeriod time.Duration, attachmentsWithSizes func() (map[string]int64, error)) (*Store, error) {
+	config, err := s3.ParseURL(s3URL)
+	if err != nil {
+		return nil, err
+	}
+	return newStore(newS3Backend(s3.New(config)), totalSizeLimit, orphanGracePeriod, attachmentsWithSizes)
+}
+
+func newStore(backend backend, totalSizeLimit int64, orphanGracePeriod time.Duration, attachmentsWithSizes func() (map[string]int64, error)) (*Store, error) {
+	c := &Store{
+		backend:              backend,
+		limit:                totalSizeLimit,
+		sizes:                make(map[string]int64),
+		attachmentsWithSizes: attachmentsWithSizes,
+		orphanGracePeriod:    orphanGracePeriod,
+		closeChan:            make(chan struct{}),
+		doneChan:             make(chan struct{}),
+	}
+	// Hydrate sizes from the database immediately so that Size()/Remaining()/Remove()
+	// are accurate from the start, without waiting for the first sync() call.
+	if attachmentsWithSizes != nil {
+		attachments, err := attachmentsWithSizes()
+		if err != nil {
+			return nil, fmt.Errorf("attachment store: failed to load existing attachments: %w", err)
+		}
+		for id, size := range attachments {
+			c.sizes[id] = size
+			c.size += size
+		}
+		go c.syncLoop()
+	} else {
+		close(c.doneChan)
+	}
+	return c, nil
+}
+
+// Write stores an attachment file. The id is validated, and the write is subject to
+// the total size limit and any additional limiters. The untrustedLength is a hint
+// from the client's Content-Length header; backends may use it to optimize uploads (e.g.
+// streaming directly to S3 without buffering).
+func (c *Store) Write(id string, reader io.Reader, untrustedLength int64, limiters ...util.Limiter) (int64, error) {
+	if !model.ValidMessageID(id) {
+		return 0, errInvalidFileID
+	}
+	log.Tag(tagStore).Field("message_id", id).Debug("Writing attachment")
+	limiters = append(limiters, util.NewFixedLimiter(c.Remaining()))
+	countingReader := util.NewCountingReader(reader)
+	limitReader := util.NewLimitReader(countingReader, limiters...)
+	if err := c.backend.Put(id, limitReader, untrustedLength); err != nil {
+		c.backend.Delete(id) //nolint:errcheck
+		return 0, err
+	}
+	size := countingReader.Total()
+	c.mu.Lock()
+	c.size += size
+	c.sizes[id] = size
+	c.mu.Unlock()
+	return size, nil
+}
+
+// Read retrieves an attachment file by ID
+func (c *Store) Read(id string) (io.ReadCloser, int64, error) {
+	if !model.ValidMessageID(id) {
+		return nil, 0, errInvalidFileID
+	}
+	return c.backend.Get(id)
+}
+
+// Remove deletes attachment files by ID and subtracts their known sizes from
+// the total. Sizes for objects not tracked (e.g. written before this process
+// started and before the first sync) are corrected by the next sync() call.
+func (c *Store) Remove(ids ...string) error {
+	for _, id := range ids {
+		if !model.ValidMessageID(id) {
+			return errInvalidFileID
+		}
+	}
+	// Remove from backend
+	for _, id := range ids {
+		log.Tag(tagStore).Field("message_id", id).Debug("Removing attachment")
+	}
+	if err := c.backend.Delete(ids...); err != nil {
+		return err
+	}
+	// Update total cache size
+	c.mu.Lock()
+	for _, id := range ids {
+		if size, ok := c.sizes[id]; ok {
+			c.size -= size
+			delete(c.sizes, id)
+		}
+	}
+	if c.size < 0 {
+		c.size = 0
+	}
+	c.mu.Unlock()
+	return nil
+}
+
+// Sync triggers an immediate reconciliation of storage with the database.
+func (c *Store) Sync() error {
+	return c.sync()
+}
+
+// sync reconciles the backend storage with the database. It lists all objects,
+// deletes orphans (not in the valid ID set and older than the grace period), and
+// recomputes the total size from the existing attachments in the database.
+func (c *Store) sync() error {
+	if c.attachmentsWithSizes == nil {
+		return nil
+	}
+	attachmentsWithSizes, err := c.attachmentsWithSizes()
+	if err != nil {
+		return fmt.Errorf("attachment sync: failed to get existing attachments: %w", err)
+	}
+	remoteObjects, err := c.backend.List()
+	if err != nil {
+		return fmt.Errorf("attachment sync: failed to list objects: %w", err)
+	}
+	// Calculate total cache size and collect orphaned attachments, excluding objects younger
+	// than the grace period to account for races, and skipping objects with invalid IDs.
+	cutoff := time.Now().Add(-c.orphanGracePeriod)
+	var orphanIDs []string
+	var count, totalSize int64
+	sizes := make(map[string]int64, len(remoteObjects))
+	for _, obj := range remoteObjects {
+		if !model.ValidMessageID(obj.ID) {
+			continue
+		}
+		if _, ok := attachmentsWithSizes[obj.ID]; !ok && obj.LastModified.Before(cutoff) {
+			orphanIDs = append(orphanIDs, obj.ID)
+		} else {
+			count++
+			totalSize += attachmentsWithSizes[obj.ID]
+			sizes[obj.ID] = attachmentsWithSizes[obj.ID]
+		}
+	}
+	log.Tag(tagStore).Debug("Attachment store updated: %d attachment(s), %s", count, util.FormatSizeHuman(totalSize))
+	c.mu.Lock()
+	c.size = totalSize
+	c.sizes = sizes
+	c.mu.Unlock()
+	// Delete orphaned attachments
+	if len(orphanIDs) > 0 {
+		log.Tag(tagStore).Debug("Deleting %d orphaned attachment(s)", len(orphanIDs))
+		if err := c.backend.Delete(orphanIDs...); err != nil {
+			return fmt.Errorf("attachment sync: failed to delete orphaned objects: %w", err)
+		}
+	}
+	// Clean up incomplete uploads (S3 only)
+	if err := c.backend.DeleteIncomplete(cutoff); err != nil {
+		log.Tag(tagStore).Err(err).Warn("Failed to abort incomplete uploads from attachment cache")
+	}
+	return nil
+}
+
+// Size returns the current total size of all attachments
+func (c *Store) Size() int64 {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	return c.size
+}
+
+// Remaining returns the remaining capacity for attachments
+func (c *Store) Remaining() int64 {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	remaining := c.limit - c.size
+	if remaining < 0 {
+		return 0
+	}
+	return remaining
+}
+
+// Close stops the background sync goroutine and waits for it to finish
+func (c *Store) Close() {
+	close(c.closeChan)
+	<-c.doneChan
+}
+
+func (c *Store) syncLoop() {
+	defer close(c.doneChan)
+	if err := c.sync(); err != nil {
+		log.Tag(tagStore).Err(err).Warn("Attachment sync failed")
+	}
+	ticker := time.NewTicker(syncInterval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ticker.C:
+			if err := c.sync(); err != nil {
+				log.Tag(tagStore).Err(err).Warn("Attachment sync failed")
+			}
+		case <-c.closeChan:
+			return
+		}
+	}
+}

attachment/store_file_test.go

@@ -0,0 +1,17 @@
+package attachment
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func newTestFileStore(t *testing.T, totalSizeLimit int64) (dir string, cache *Store) {
+	t.Helper()
+	dir = t.TempDir()
+	cache, err := NewFileStore(dir, totalSizeLimit, time.Hour, nil)
+	require.Nil(t, err)
+	t.Cleanup(func() { cache.Close() })
+	return dir, cache
+}

attachment/store_s3_test.go

@@ -0,0 +1,120 @@
+package attachment
+
+import (
+	"context"
+	"io"
+	"os"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"heckel.io/ntfy/v2/s3"
+)
+
+func TestS3Store_WriteWithPrefix(t *testing.T) {
+	s3URL := os.Getenv("NTFY_TEST_S3_URL")
+	if s3URL == "" {
+		t.Skip("NTFY_TEST_S3_URL not set")
+	}
+	cfg, err := s3.ParseURL(s3URL)
+	require.Nil(t, err)
+	cfg.Prefix = "test-prefix"
+	client := s3.New(cfg)
+	deleteAllObjects(t, client)
+	backend := newS3Backend(client)
+	cache, err := newStore(backend, 10*1024, time.Hour, nil)
+	require.Nil(t, err)
+	t.Cleanup(func() {
+		deleteAllObjects(t, client)
+		cache.Close()
+	})
+
+	size, err := cache.Write("abcdefghijkl", strings.NewReader("test"), 0)
+	require.Nil(t, err)
+	require.Equal(t, int64(4), size)
+
+	reader, _, err := cache.Read("abcdefghijkl")
+	require.Nil(t, err)
+	data, err := io.ReadAll(reader)
+	reader.Close()
+	require.Nil(t, err)
+	require.Equal(t, "test", string(data))
+}
+
+// --- Helpers ---
+
+func newTestRealS3Store(t *testing.T, totalSizeLimit int64) (*Store, *modTimeOverrideBackend) {
+	t.Helper()
+	s3URL := os.Getenv("NTFY_TEST_S3_URL")
+	if s3URL == "" {
+		t.Skip("NTFY_TEST_S3_URL not set")
+	}
+	cfg, err := s3.ParseURL(s3URL)
+	require.Nil(t, err)
+	if cfg.Prefix != "" {
+		cfg.Prefix = cfg.Prefix + "/testpkg-attachment"
+	} else {
+		cfg.Prefix = "testpkg-attachment"
+	}
+	client := s3.New(cfg)
+	inner := newS3Backend(client)
+	wrapper := &modTimeOverrideBackend{backend: inner, modTimes: make(map[string]time.Time)}
+	deleteAllObjects(t, client)
+	store, err := newStore(wrapper, totalSizeLimit, time.Hour, nil)
+	require.Nil(t, err)
+	t.Cleanup(func() {
+		deleteAllObjects(t, client)
+		store.Close()
+	})
+	return store, wrapper
+}
+
+func deleteAllObjects(t *testing.T, client *s3.Client) {
+	t.Helper()
+	for i := 0; i < 20; i++ {
+		objects, err := client.ListObjectsV2(context.Background())
+		require.Nil(t, err)
+		if len(objects) == 0 {
+			return
+		}
+		keys := make([]string, len(objects))
+		for j, obj := range objects {
+			keys[j] = obj.Key
+		}
+		require.Nil(t, client.DeleteObjects(context.Background(), keys))
+		time.Sleep(200 * time.Millisecond)
+	}
+	t.Fatal("timed out waiting for bucket to be empty")
+}
+
+// modTimeOverrideBackend wraps a backend and allows overriding LastModified times returned by List().
+// This is used in tests to simulate old objects on backends (like real S3) where
+// LastModified cannot be set directly.
+type modTimeOverrideBackend struct {
+	backend
+	mu       sync.Mutex
+	modTimes map[string]time.Time // object ID -> override time
+}
+
+func (b *modTimeOverrideBackend) List() ([]object, error) {
+	objects, err := b.backend.List()
+	if err != nil {
+		return nil, err
+	}
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	for i, obj := range objects {
+		if t, ok := b.modTimes[obj.ID]; ok {
+			objects[i].LastModified = t
+		}
+	}
+	return objects, nil
+}
+
+func (b *modTimeOverrideBackend) setModTime(id string, t time.Time) {
+	b.mu.Lock()
+	b.modTimes[id] = t
+	b.mu.Unlock()
+}

attachment/store_test.go

@@ -0,0 +1,352 @@
+package attachment
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"heckel.io/ntfy/v2/util"
+)
+
+const testSizeLimit = 10 * 1024
+
+func TestStore_WriteReadRemove(t *testing.T) {
+	forEachBackend(t, testSizeLimit, func(t *testing.T, s *Store, _ func(string)) {
+		// Write
+		size, err := s.Write("abcdefghijkl", strings.NewReader("hello world"), 0)
+		require.Nil(t, err)
+		require.Equal(t, int64(11), size)
+		require.Equal(t, int64(11), s.Size())
+
+		// Read back
+		reader, readSize, err := s.Read("abcdefghijkl")
+		require.Nil(t, err)
+		require.Equal(t, int64(11), readSize)
+		data, err := io.ReadAll(reader)
+		reader.Close()
+		require.Nil(t, err)
+		require.Equal(t, "hello world", string(data))
+
+		// Remove
+		require.Nil(t, s.Remove("abcdefghijkl"))
+		require.Equal(t, int64(0), s.Size())
+
+		// Read after remove should fail
+		_, _, err = s.Read("abcdefghijkl")
+		require.Error(t, err)
+	})
+}
+
+func TestStore_WriteRemoveMultiple(t *testing.T) {
+	forEachBackend(t, testSizeLimit, func(t *testing.T, s *Store, _ func(string)) {
+		for i := 0; i < 5; i++ {
+			_, err := s.Write(fmt.Sprintf("abcdefghijk%d", i), bytes.NewReader(make([]byte, 100)), 0)
+			require.Nil(t, err)
+		}
+		require.Equal(t, int64(500), s.Size())
+
+		require.Nil(t, s.Remove("abcdefghijk1", "abcdefghijk3"))
+		require.Equal(t, int64(300), s.Size())
+
+		// Removed files should not be readable
+		_, _, err := s.Read("abcdefghijk1")
+		require.Error(t, err)
+		_, _, err = s.Read("abcdefghijk3")
+		require.Error(t, err)
+
+		// Remaining files should still be readable
+		for _, id := range []string{"abcdefghijk0", "abcdefghijk2", "abcdefghijk4"} {
+			reader, _, err := s.Read(id)
+			require.Nil(t, err)
+			reader.Close()
+		}
+	})
+}
+
+func TestStore_WriteTotalSizeLimit(t *testing.T) {
+	forEachBackend(t, 100, func(t *testing.T, s *Store, _ func(string)) {
+		// First write fits
+		_, err := s.Write("abcdefghijk0", bytes.NewReader(make([]byte, 80)), 0)
+		require.Nil(t, err)
+		require.Equal(t, int64(80), s.Size())
+		require.Equal(t, int64(20), s.Remaining())
+
+		// Second write exceeds total limit
+		_, err = s.Write("abcdefghijk1", bytes.NewReader(make([]byte, 50)), 0)
+		require.ErrorIs(t, err, util.ErrLimitReached)
+	})
+}
+
+func TestStore_WriteAdditionalLimiter(t *testing.T) {
+	forEachBackend(t, testSizeLimit, func(t *testing.T, s *Store, _ func(string)) {
+		_, err := s.Write("abcdefghijkl", bytes.NewReader(make([]byte, 200)), 0, util.NewFixedLimiter(100))
+		require.ErrorIs(t, err, util.ErrLimitReached)
+
+		// File should not be readable (was cleaned up)
+		_, _, err = s.Read("abcdefghijkl")
+		require.Error(t, err)
+	})
+}
+
+func TestStore_WriteWithLimiter(t *testing.T) {
+	forEachBackend(t, testSizeLimit, func(t *testing.T, s *Store, _ func(string)) {
+		size, err := s.Write("abcdefghijkl", strings.NewReader("normal file"), 0, util.NewFixedLimiter(999))
+		require.Nil(t, err)
+		require.Equal(t, int64(11), size)
+		require.Equal(t, int64(11), s.Size())
+	})
+}
+
+func TestStore_WriteOverwriteSameID(t *testing.T) {
+	forEachBackend(t, testSizeLimit, func(t *testing.T, s *Store, _ func(string)) {
+		// Write 100 bytes
+		_, err := s.Write("abcdefghijkl", bytes.NewReader(make([]byte, 100)), 0)
+		require.Nil(t, err)
+		require.Equal(t, int64(100), s.Size())
+
+		// Overwrite with 50 bytes
+		_, err = s.Write("abcdefghijkl", bytes.NewReader(make([]byte, 50)), 0)
+		require.Nil(t, err)
+		require.Equal(t, int64(150), s.Size()) // Store tracks both writes
+
+		// Read back should return the latest content
+		reader, readSize, err := s.Read("abcdefghijkl")
+		require.Nil(t, err)
+		require.Equal(t, int64(50), readSize)
+		reader.Close()
+	})
+}
+
+func TestStore_WriteAfterFailure(t *testing.T) {
+	forEachBackend(t, testSizeLimit, func(t *testing.T, s *Store, _ func(string)) {
+		// Failed write: limiter rejects it
+		_, err := s.Write("abcdefghijkl", bytes.NewReader(make([]byte, 200)), 0, util.NewFixedLimiter(100))
+		require.ErrorIs(t, err, util.ErrLimitReached)
+		require.Equal(t, int64(0), s.Size())
+
+		// Subsequent write with a different ID should succeed
+		size, err := s.Write("abcdefghijk2", strings.NewReader("hello"), 0)
+		require.Nil(t, err)
+		require.Equal(t, int64(5), size)
+		require.Equal(t, int64(5), s.Size())
+
+		// The failed ID should not be readable
+		_, _, err = s.Read("abcdefghijkl")
+		require.Error(t, err)
+
+		// The successful ID should be readable
+		reader, _, err := s.Read("abcdefghijk2")
+		require.Nil(t, err)
+		reader.Close()
+	})
+}
+
+func TestStore_SyncRecomputesSize(t *testing.T) {
+	forEachBackend(t, testSizeLimit, func(t *testing.T, s *Store, makeOld func(string)) {
+		// Write two files
+		_, err := s.Write("abcdefghijk0", bytes.NewReader(make([]byte, 100)), 0)
+		require.Nil(t, err)
+		_, err = s.Write("abcdefghijk1", bytes.NewReader(make([]byte, 200)), 0)
+		require.Nil(t, err)
+		require.Equal(t, int64(300), s.Size())
+
+		// Corrupt the in-memory size tracking
+		s.mu.Lock()
+		s.size = 999
+		s.mu.Unlock()
+		require.Equal(t, int64(999), s.Size())
+
+		// Set attachmentsWithSizes to include both files so nothing gets deleted
+		s.attachmentsWithSizes = func() (map[string]int64, error) {
+			return map[string]int64{"abcdefghijk0": 100, "abcdefghijk1": 200}, nil
+		}
+
+		// Sync should recompute size from the backend
+		require.Nil(t, s.sync())
+		require.Equal(t, int64(300), s.Size())
+	})
+}
+
+func TestStore_ReadNotFound(t *testing.T) {
+	forEachBackend(t, testSizeLimit, func(t *testing.T, s *Store, _ func(string)) {
+		_, _, err := s.Read("abcdefghijkl")
+		require.Error(t, err)
+	})
+}
+
+func TestStore_InvalidID(t *testing.T) {
+	forEachBackend(t, testSizeLimit, func(t *testing.T, s *Store, _ func(string)) {
+		_, err := s.Write("bad", strings.NewReader("x"), 0)
+		require.Equal(t, errInvalidFileID, err)
+
+		_, _, err = s.Read("bad")
+		require.Equal(t, errInvalidFileID, err)
+
+		err = s.Remove("bad")
+		require.Equal(t, errInvalidFileID, err)
+	})
+}
+
+func TestStore_WriteLargeObjects(t *testing.T) {
+	sizes := map[string]int64{
+		"100B": 100,
+		"6MB":  6 * 1024 * 1024,
+		"12MB": 12 * 1024 * 1024,
+	}
+	for name, sz := range sizes {
+		t.Run(name, func(t *testing.T) {
+			forEachBackend(t, sz+1024, func(t *testing.T, s *Store, _ func(string)) {
+				data := make([]byte, sz)
+				for i := range data {
+					data[i] = byte(i % 251)
+				}
+
+				size, err := s.Write("abcdefghijkl", bytes.NewReader(data), 0)
+				require.Nil(t, err)
+				require.Equal(t, sz, size)
+				require.Equal(t, sz, s.Size())
+
+				reader, readSize, err := s.Read("abcdefghijkl")
+				require.Nil(t, err)
+				require.Equal(t, sz, readSize)
+				got, err := io.ReadAll(reader)
+				reader.Close()
+				require.Nil(t, err)
+				require.Equal(t, data, got)
+			})
+		})
+	}
+}
+
+func TestStore_WriteUntrustedLengthExact(t *testing.T) {
+	forEachBackend(t, testSizeLimit, func(t *testing.T, s *Store, _ func(string)) {
+		size, err := s.Write("abcdefghijkl", strings.NewReader("hello world"), 11)
+		require.Nil(t, err)
+		require.Equal(t, int64(11), size)
+
+		reader, _, err := s.Read("abcdefghijkl")
+		require.Nil(t, err)
+		data, err := io.ReadAll(reader)
+		reader.Close()
+		require.Nil(t, err)
+		require.Equal(t, "hello world", string(data))
+	})
+}
+
+func TestStore_WriteUntrustedLengthBodyLonger(t *testing.T) {
+	forEachBackend(t, testSizeLimit, func(t *testing.T, s *Store, _ func(string)) {
+		// Body has 11 bytes, but we claim 5 — only first 5 bytes should be stored
+		size, err := s.Write("abcdefghijkl", strings.NewReader("hello world"), 5)
+		require.Nil(t, err)
+		require.Equal(t, int64(5), size)
+
+		reader, _, err := s.Read("abcdefghijkl")
+		require.Nil(t, err)
+		data, err := io.ReadAll(reader)
+		reader.Close()
+		require.Nil(t, err)
+		require.Equal(t, "hello", string(data))
+	})
+}
+
+func TestStore_WriteUntrustedLengthBodyShorter(t *testing.T) {
+	forEachBackend(t, testSizeLimit, func(t *testing.T, s *Store, _ func(string)) {
+		// Body has 5 bytes, but we claim 100 — should fail
+		_, err := s.Write("abcdefghijkl", strings.NewReader("hello"), 100)
+		require.Error(t, err)
+
+		// File should not be readable (was cleaned up)
+		_, _, err = s.Read("abcdefghijkl")
+		require.Error(t, err)
+	})
+}
+
+func TestStore_Sync(t *testing.T) {
+	forEachBackend(t, testSizeLimit, func(t *testing.T, s *Store, makeOld func(string)) {
+		// Write some files
+		_, err := s.Write("abcdefghijk0", strings.NewReader("file0"), 0)
+		require.Nil(t, err)
+		_, err = s.Write("abcdefghijk1", strings.NewReader("file1"), 0)
+		require.Nil(t, err)
+		_, err = s.Write("abcdefghijk2", strings.NewReader("file2"), 0)
+		require.Nil(t, err)
+
+		require.Equal(t, int64(15), s.Size())
+
+		// Set the ID provider to only know about file 0 and 2
+		s.attachmentsWithSizes = func() (map[string]int64, error) {
+			return map[string]int64{"abcdefghijk0": 5, "abcdefghijk2": 5}, nil
+		}
+
+		// Make file 1 old enough to be cleaned up
+		makeOld("abcdefghijk1")
+
+		// Run sync
+		require.Nil(t, s.sync())
+
+		// File 1 should be deleted (orphan, old enough)
+		_, _, err = s.Read("abcdefghijk1")
+		require.Error(t, err)
+
+		// Files 0 and 2 should still be readable
+		r, _, err := s.Read("abcdefghijk0")
+		require.Nil(t, err)
+		r.Close()
+		r, _, err = s.Read("abcdefghijk2")
+		require.Nil(t, err)
+		r.Close()
+
+		// Size should be updated
+		require.Equal(t, int64(10), s.Size())
+	})
+}
+
+func TestStore_Sync_SkipsRecentFiles(t *testing.T) {
+	forEachBackend(t, testSizeLimit, func(t *testing.T, s *Store, _ func(string)) {
+		// Write a file
+		_, err := s.Write("abcdefghijk0", strings.NewReader("file0"), 0)
+		require.Nil(t, err)
+
+		// Set the ID provider to return empty (no valid IDs)
+		s.attachmentsWithSizes = func() (map[string]int64, error) {
+			return map[string]int64{}, nil
+		}
+
+		// File was just created, so it should NOT be deleted (< 1 hour old)
+		require.Nil(t, s.sync())
+
+		// File should still exist
+		reader, _, err := s.Read("abcdefghijk0")
+		require.Nil(t, err)
+		reader.Close()
+	})
+}
+
+// forEachBackend runs f against both the file and S3 backends. It also provides a makeOld
+// callback that makes a specific object's timestamp old enough for orphan cleanup (> 1 hour).
+// For the file backend, this uses os.Chtimes; for the S3 backend, it overrides the object's
+// LastModified time via a modTimeOverrideBackend wrapper. Objects start with recent timestamps
+// by default. The S3 subtest is skipped if NTFY_TEST_S3_URL is not set.
+func forEachBackend(t *testing.T, totalSizeLimit int64, f func(t *testing.T, s *Store, makeOld func(string))) {
+	t.Run("file", func(t *testing.T) {
+		dir, s := newTestFileStore(t, totalSizeLimit)
+		makeOld := func(id string) {
+			oldTime := time.Unix(1, 0)
+			os.Chtimes(filepath.Join(dir, id), oldTime, oldTime)
+		}
+		f(t, s, makeOld)
+	})
+	t.Run("s3", func(t *testing.T) {
+		s, wrapper := newTestRealS3Store(t, totalSizeLimit)
+		makeOld := func(id string) {
+			wrapper.setModTime(id, time.Unix(1, 0))
+		}
+		f(t, s, makeOld)
+	})
+}

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/app.go

@@ -44,7 +44,7 @@ func New() *cli.App {
 		Name:                   "ntfy",
 		Usage:                  "Simple pub-sub notification service",
 		UsageText:              "ntfy [OPTION..]",
-		HideVersion:            true,
+		HideVersion:            false,
 		UseShortOptionHandling: true,
 		Reader:                 os.Stdin,
 		Writer:                 os.Stdout,

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)"}),
@@ -52,7 +60,8 @@ var flagsServe = append(
 	altsrc.NewStringSliceFlag(&cli.StringSliceFlag{Name: "auth-users", Aliases: []string{"auth_users"}, EnvVars: []string{"NTFY_AUTH_USERS"}, Usage: "pre-provisioned declarative users"}),
 	altsrc.NewStringSliceFlag(&cli.StringSliceFlag{Name: "auth-access", Aliases: []string{"auth_access"}, EnvVars: []string{"NTFY_AUTH_ACCESS"}, Usage: "pre-provisioned declarative access control entries"}),
 	altsrc.NewStringSliceFlag(&cli.StringSliceFlag{Name: "auth-tokens", Aliases: []string{"auth_tokens"}, EnvVars: []string{"NTFY_AUTH_TOKENS"}, Usage: "pre-provisioned declarative access tokens"}),
-	altsrc.NewStringFlag(&cli.StringFlag{Name: "attachment-cache-dir", Aliases: []string{"attachment_cache_dir"}, EnvVars: []string{"NTFY_ATTACHMENT_CACHE_DIR"}, Usage: "cache directory for attached files"}),
+	altsrc.NewBoolFlag(&cli.BoolFlag{Name: "auth-access-cache", Aliases: []string{"auth_access_cache"}, EnvVars: []string{"NTFY_AUTH_ACCESS_CACHE"}, Value: user.DefaultAccessCacheEnabled, Usage: "enables the in-memory ACL cache (high-volume servers only)"}),
+	altsrc.NewStringFlag(&cli.StringFlag{Name: "attachment-cache-dir", Aliases: []string{"attachment_cache_dir"}, EnvVars: []string{"NTFY_ATTACHMENT_CACHE_DIR"}, Usage: "cache directory for attached files, or S3 URL (s3://ACCESS_KEY:SECRET_KEY@BUCKET[/PREFIX]?region=REGION[&endpoint=ENDPOINT])"}),
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "attachment-total-size-limit", Aliases: []string{"attachment_total_size_limit", "A"}, EnvVars: []string{"NTFY_ATTACHMENT_TOTAL_SIZE_LIMIT"}, Value: util.FormatSize(server.DefaultAttachmentTotalSizeLimit), Usage: "limit of the on-disk attachment cache"}),
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "attachment-file-size-limit", Aliases: []string{"attachment_file_size_limit", "Y"}, EnvVars: []string{"NTFY_ATTACHMENT_FILE_SIZE_LIMIT"}, Value: util.FormatSize(server.DefaultAttachmentFileSizeLimit), Usage: "per-file attachment size limit (e.g. 300k, 2M, 100M)"}),
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "attachment-expiry-duration", Aliases: []string{"attachment_expiry_duration", "X"}, EnvVars: []string{"NTFY_ATTACHMENT_EXPIRY_DURATION"}, Value: util.FormatDuration(server.DefaultAttachmentExpiryDuration), Usage: "duration after which uploaded attachments will be deleted (e.g. 3h, 20h)"}),
@@ -71,6 +80,7 @@ var flagsServe = append(
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "smtp-sender-user", Aliases: []string{"smtp_sender_user"}, EnvVars: []string{"NTFY_SMTP_SENDER_USER"}, Usage: "SMTP user (if e-mail sending is enabled)"}),
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "smtp-sender-pass", Aliases: []string{"smtp_sender_pass"}, EnvVars: []string{"NTFY_SMTP_SENDER_PASS"}, Usage: "SMTP password (if e-mail sending is enabled)"}),
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "smtp-sender-from", Aliases: []string{"smtp_sender_from"}, EnvVars: []string{"NTFY_SMTP_SENDER_FROM"}, Usage: "SMTP sender address (if e-mail sending is enabled)"}),
+	altsrc.NewBoolFlag(&cli.BoolFlag{Name: "smtp-sender-verify", Aliases: []string{"smtp_sender_verify"}, EnvVars: []string{"NTFY_SMTP_SENDER_VERIFY"}, Value: false, Usage: "require verified email addresses for sending email notifications"}),
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "smtp-server-listen", Aliases: []string{"smtp_server_listen"}, EnvVars: []string{"NTFY_SMTP_SERVER_LISTEN"}, Usage: "SMTP server address (ip:port) for incoming emails, e.g. :25"}),
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "smtp-server-domain", Aliases: []string{"smtp_server_domain"}, EnvVars: []string{"NTFY_SMTP_SERVER_DOMAIN"}, Usage: "SMTP domain for incoming e-mail, e.g. ntfy.sh"}),
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "smtp-server-addr-prefix", Aliases: []string{"smtp_server_addr_prefix"}, EnvVars: []string{"NTFY_SMTP_SERVER_ADDR_PREFIX"}, Usage: "SMTP email address prefix for topics to prevent spam (e.g. 'ntfy-')"}),
@@ -92,8 +102,14 @@ var flagsServe = append(
 	altsrc.NewIntFlag(&cli.IntFlag{Name: "visitor-message-daily-limit", Aliases: []string{"visitor_message_daily_limit"}, EnvVars: []string{"NTFY_VISITOR_MESSAGE_DAILY_LIMIT"}, Value: server.DefaultVisitorMessageDailyLimit, Usage: "max messages per visitor per day, derived from request limit if unset"}),
 	altsrc.NewIntFlag(&cli.IntFlag{Name: "visitor-email-limit-burst", Aliases: []string{"visitor_email_limit_burst"}, EnvVars: []string{"NTFY_VISITOR_EMAIL_LIMIT_BURST"}, Value: server.DefaultVisitorEmailLimitBurst, Usage: "initial limit of e-mails per visitor"}),
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "visitor-email-limit-replenish", Aliases: []string{"visitor_email_limit_replenish"}, EnvVars: []string{"NTFY_VISITOR_EMAIL_LIMIT_REPLENISH"}, Value: util.FormatDuration(server.DefaultVisitorEmailLimitReplenish), Usage: "interval at which burst limit is replenished (one per x)"}),
+	altsrc.NewIntFlag(&cli.IntFlag{Name: "visitor-topic-creation-limit-burst", Aliases: []string{"visitor_topic_creation_limit_burst"}, EnvVars: []string{"NTFY_VISITOR_TOPIC_CREATION_LIMIT_BURST"}, Value: server.DefaultVisitorTopicCreationLimitBurst, Usage: "burst of new topic creations per visitor (0 = disabled)"}),
+	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"}),
@@ -147,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")
@@ -165,6 +186,7 @@ func execServe(c *cli.Context) error {
 	authUsersRaw := c.StringSlice("auth-users")
 	authAccessRaw := c.StringSlice("auth-access")
 	authTokensRaw := c.StringSlice("auth-tokens")
+	authAccessCacheEnabled := c.Bool("auth-access-cache")
 	attachmentCacheDir := c.String("attachment-cache-dir")
 	attachmentTotalSizeLimitStr := c.String("attachment-total-size-limit")
 	attachmentFileSizeLimitStr := c.String("attachment-file-size-limit")
@@ -184,6 +206,7 @@ func execServe(c *cli.Context) error {
 	smtpSenderUser := c.String("smtp-sender-user")
 	smtpSenderPass := c.String("smtp-sender-pass")
 	smtpSenderFrom := c.String("smtp-sender-from")
+	smtpSenderVerify := c.Bool("smtp-sender-verify")
 	smtpServerListen := c.String("smtp-server-listen")
 	smtpServerDomain := c.String("smtp-server-domain")
 	smtpServerAddrPrefix := c.String("smtp-server-addr-prefix")
@@ -205,8 +228,14 @@ func execServe(c *cli.Context) error {
 	visitorMessageDailyLimit := c.Int("visitor-message-daily-limit")
 	visitorEmailLimitBurst := c.Int("visitor-email-limit-burst")
 	visitorEmailLimitReplenishStr := c.String("visitor-email-limit-replenish")
+	visitorTopicCreationLimitBurst := c.Int("visitor-topic-creation-limit-burst")
+	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"), ",")
@@ -234,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)
@@ -250,6 +283,10 @@ func execServe(c *cli.Context) error {
 	if err != nil {
 		return fmt.Errorf("invalid visitor email limit replenish: %s", visitorEmailLimitReplenishStr)
 	}
+	visitorTopicCreationLimitReplenish, err := util.ParseDuration(visitorTopicCreationLimitReplenishStr)
+	if err != nil {
+		return fmt.Errorf("invalid visitor topic creation limit replenish: %s", visitorTopicCreationLimitReplenishStr)
+	}
 	webPushExpiryDuration, err := util.ParseDuration(webPushExpiryDurationStr)
 	if err != nil {
 		return fmt.Errorf("invalid web push expiry duration: %s", webPushExpiryDurationStr)
@@ -258,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)
@@ -290,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 {
@@ -310,6 +367,8 @@ func execServe(c *cli.Context) error {
 		return errors.New("if listen-https is set, both key-file and cert-file must be set")
 	} else if smtpSenderAddr != "" && (baseURL == "" || smtpSenderFrom == "") {
 		return errors.New("if smtp-sender-addr is set, base-url, and smtp-sender-from must also be set")
+	} else if smtpSenderVerify && smtpSenderAddr == "" {
+		return errors.New("if smtp-sender-verify is set, smtp-sender-addr must also be set")
 	} else if smtpServerListen != "" && smtpServerDomain == "" {
 		return errors.New("if smtp-server-listen is set, smtp-server-domain must also be set")
 	} else if attachmentCacheDir != "" && baseURL == "" {
@@ -358,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")
 	}
@@ -456,6 +523,7 @@ func execServe(c *cli.Context) error {
 	conf.AuthUsers = authUsers
 	conf.AuthAccess = authAccess
 	conf.AuthTokens = authTokens
+	conf.AuthAccessCacheEnabled = authAccessCacheEnabled
 	conf.AttachmentCacheDir = attachmentCacheDir
 	conf.AttachmentTotalSizeLimit = attachmentTotalSizeLimit
 	conf.AttachmentFileSizeLimit = attachmentFileSizeLimit
@@ -471,6 +539,7 @@ func execServe(c *cli.Context) error {
 	conf.SMTPSenderUser = smtpSenderUser
 	conf.SMTPSenderPass = smtpSenderPass
 	conf.SMTPSenderFrom = smtpSenderFrom
+	conf.SMTPSenderVerify = smtpSenderVerify
 	conf.SMTPServerListen = smtpServerListen
 	conf.SMTPServerDomain = smtpServerDomain
 	conf.SMTPServerAddrPrefix = smtpServerAddrPrefix
@@ -492,8 +561,14 @@ func execServe(c *cli.Context) error {
 	conf.VisitorMessageDailyLimit = visitorMessageDailyLimit
 	conf.VisitorEmailLimitBurst = visitorEmailLimitBurst
 	conf.VisitorEmailLimitReplenish = visitorEmailLimitReplenish
+	conf.VisitorTopicCreationLimitBurst = visitorTopicCreationLimitBurst
+	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
@@ -509,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
@@ -687,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))

cmd/serve_unix.go

@@ -1,4 +1,4 @@
-//go:build linux || dragonfly || freebsd || netbsd || openbsd
+//go:build (darwin || linux || dragonfly || freebsd || netbsd || openbsd) && !noserver
 
 package cmd
 

cmd/user.go

@@ -8,11 +8,13 @@ import (
 	"fmt"
 	"os"
 	"strings"
+	"time"
 
 	"github.com/urfave/cli/v2"
 	"github.com/urfave/cli/v2/altsrc"
 	"heckel.io/ntfy/v2/db"
 	"heckel.io/ntfy/v2/db/pg"
+	"heckel.io/ntfy/v2/mail"
 	"heckel.io/ntfy/v2/server"
 	"heckel.io/ntfy/v2/user"
 	"heckel.io/ntfy/v2/util"
@@ -32,12 +34,17 @@ var flagsUser = append(
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "auth-file", Aliases: []string{"auth_file", "H"}, EnvVars: []string{"NTFY_AUTH_FILE"}, Usage: "auth database file used for access control"}),
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "auth-default-access", Aliases: []string{"auth_default_access", "p"}, EnvVars: []string{"NTFY_AUTH_DEFAULT_ACCESS"}, Value: "read-write", Usage: "default permissions if no matching entries in the auth database are found"}),
 	altsrc.NewStringFlag(&cli.StringFlag{Name: "database-url", Aliases: []string{"database_url"}, EnvVars: []string{"NTFY_DATABASE_URL"}, Usage: "PostgreSQL connection string for database-backed stores"}),
+	altsrc.NewStringFlag(&cli.StringFlag{Name: "base-url", Aliases: []string{"base_url", "B"}, EnvVars: []string{"NTFY_BASE_URL"}, Usage: "externally visible base URL for this host (e.g. https://ntfy.sh)"}),
+	altsrc.NewStringFlag(&cli.StringFlag{Name: "smtp-sender-addr", Aliases: []string{"smtp_sender_addr"}, EnvVars: []string{"NTFY_SMTP_SENDER_ADDR"}, Usage: "SMTP server address (host:port) for outgoing emails"}),
+	altsrc.NewStringFlag(&cli.StringFlag{Name: "smtp-sender-user", Aliases: []string{"smtp_sender_user"}, EnvVars: []string{"NTFY_SMTP_SENDER_USER"}, Usage: "SMTP user (if e-mail sending is enabled)"}),
+	altsrc.NewStringFlag(&cli.StringFlag{Name: "smtp-sender-pass", Aliases: []string{"smtp_sender_pass"}, EnvVars: []string{"NTFY_SMTP_SENDER_PASS"}, Usage: "SMTP password (if e-mail sending is enabled)"}),
+	altsrc.NewStringFlag(&cli.StringFlag{Name: "smtp-sender-from", Aliases: []string{"smtp_sender_from"}, EnvVars: []string{"NTFY_SMTP_SENDER_FROM"}, Usage: "SMTP sender address (if e-mail sending is enabled)"}),
 )
 
 var cmdUser = &cli.Command{
 	Name:      "user",
 	Usage:     "Manage/show users",
-	UsageText: "ntfy user [list|add|remove|change-pass|change-role] ...",
+	UsageText: "ntfy user [list|add|remove|change-pass|reset-pass|change-role] ...",
 	Flags:     flagsUser,
 	Before:    initConfigFileInputSourceFunc("config", flagsUser, initLogFunc),
 	Category:  categoryServer,
@@ -98,6 +105,30 @@ Example:
 
 You may set the NTFY_PASSWORD environment variable to pass the new password or NTFY_PASSWORD_HASH to pass
 directly the bcrypt hash. This is useful if you are updating users via scripts.
+`,
+		},
+		{
+			Name:      "reset-pass",
+			Aliases:   []string{"rp"},
+			Usage:     "Generates a password reset link for a user",
+			UsageText: "ntfy user reset-pass [--send-email] USERNAME",
+			Action:    execUserResetPass,
+			Flags: []cli.Flag{
+				&cli.BoolFlag{Name: "send-email", Aliases: []string{"e"}, Usage: "also email the reset link to the user's primary email"},
+			},
+			Description: `Generate a password reset link for the given user and print it to stdout.
+
+The user completes the reset by opening the link in a browser and choosing a new password;
+the admin never learns or chooses the new password. The link is single-use and expires after
+one hour. This is an admin override of the self-service reset flow -- unlike self-service, it
+does not require the user to have a verified primary email (the token is bound to the user).
+
+With --send-email, the link is additionally emailed to the user's primary email address (this
+requires SMTP to be configured and the user to have a verified primary email).
+
+Example:
+  ntfy user reset-pass phil               # Print a reset link for user phil
+  ntfy user reset-pass --send-email phil  # Print and email the reset link
 `,
 		},
 		{
@@ -257,7 +288,6 @@ func execUserDel(c *cli.Context) error {
 func execUserChangePass(c *cli.Context) error {
 	username := c.Args().Get(0)
 	password, hashed := os.LookupEnv("NTFY_PASSWORD_HASH")
-
 	if !hashed {
 		password = os.Getenv("NTFY_PASSWORD")
 	}
@@ -286,6 +316,61 @@ func execUserChangePass(c *cli.Context) error {
 	return nil
 }
 
+func execUserResetPass(c *cli.Context) error {
+	username := c.Args().Get(0)
+	sendEmail := c.Bool("send-email")
+	baseURL := strings.TrimSuffix(c.String("base-url"), "/")
+	if username == "" {
+		return errors.New("username expected, type 'ntfy user reset-pass --help' for help")
+	} else if username == userEveryone || username == user.Everyone {
+		return errors.New("username not allowed")
+	} else if baseURL == "" {
+		return errors.New("base-url must be configured to generate a reset link")
+	}
+	manager, err := createUserManager(c)
+	if err != nil {
+		return err
+	}
+	u, err := manager.User(username)
+	if errors.Is(err, user.ErrUserNotFound) {
+		return fmt.Errorf("user %s does not exist", username)
+	} else if err != nil {
+		return err
+	} else if u.Provisioned {
+		return fmt.Errorf("user %s is provisioned in the config file; its password cannot be reset", username)
+	}
+	// Resolve the primary email up front if we need to send -- fail before creating a token
+	var primaryEmail string
+	if sendEmail {
+		primaryEmail, err = manager.PrimaryEmail(u.ID)
+		if err != nil {
+			return err
+		} else if primaryEmail == "" {
+			return fmt.Errorf("user %s has no primary email; cannot send reset link (omit --send-email to just print it)", username)
+		}
+	}
+	// The reset token is bound to the user, not an email -- so this works even with no SMTP
+	token, err := manager.AddMagicLink(user.MagicLinkKindPasswordReset, u.ID, "", time.Hour)
+	if err != nil {
+		return err
+	}
+	link := baseURL + "/account/password/reset/" + token
+	fmt.Fprintln(c.App.Writer, link)
+	if sendEmail {
+		sender := mail.NewSender(&mail.Config{
+			SMTPAddr: c.String("smtp-sender-addr"),
+			SMTPUser: c.String("smtp-sender-user"),
+			SMTPPass: c.String("smtp-sender-pass"),
+			From:     c.String("smtp-sender-from"),
+		})
+		if err := sender.SendPasswordReset(primaryEmail, link); err != nil {
+			return fmt.Errorf("failed to send reset email to %s: %w", primaryEmail, err)
+		}
+		fmt.Fprintf(c.App.ErrWriter, "reset link emailed to %s\n", primaryEmail)
+	}
+	return nil
+}
+
 func execUserChangeRole(c *cli.Context) error {
 	username := c.Args().Get(0)
 	role := user.Role(c.Args().Get(1))
@@ -313,7 +398,7 @@ func execUserHash(c *cli.Context) error {
 	if err != nil {
 		return err
 	}
-	hash, err := user.HashPassword(password)
+	hash, err := user.HashPassword(password, user.DefaultUserPasswordBcryptCost)
 	if err != nil {
 		return fmt.Errorf("failed to hash password: %w", err)
 	}
@@ -378,6 +463,7 @@ func createUserManager(c *cli.Context) (*user.Manager, error) {
 		ProvisionEnabled:    false, // Hack: Do not re-provision users on manager initialization
 		BcryptCost:          user.DefaultUserPasswordBcryptCost,
 		QueueWriterInterval: user.DefaultUserStatsQueueWriterInterval,
+		AccessCacheEnabled:  false, // Do not cache for CLI commands
 	}
 	if databaseURL != "" {
 		host, dbErr := pg.Open(databaseURL)

cmd/user_test.go

@@ -1,14 +1,15 @@
 package cmd
 
 import (
+	"os"
+	"path/filepath"
+	"testing"
+
 	"github.com/stretchr/testify/require"
 	"github.com/urfave/cli/v2"
 	"heckel.io/ntfy/v2/server"
 	"heckel.io/ntfy/v2/test"
 	"heckel.io/ntfy/v2/user"
-	"os"
-	"path/filepath"
-	"testing"
 )
 
 func TestCLI_User_Add(t *testing.T) {
@@ -121,6 +122,69 @@ func TestCLI_User_Delete(t *testing.T) {
 	require.Contains(t, err.Error(), "user phil does not exist")
 }
 
+func TestCLI_User_ResetPass(t *testing.T) {
+	s, conf, port := newTestServerWithAuth(t)
+	defer test.StopServer(t, s, port)
+
+	app, stdin, _, _ := newTestApp()
+	stdin.WriteString("mypass\nmypass")
+	require.Nil(t, runUserCommand(app, conf, "add", "phil"))
+
+	// Prints a working-looking reset link when base-url is set
+	app, _, stdout, _ := newTestApp()
+	require.Nil(t, runUserCommand(app, conf, "--base-url=https://ntfy.example.com", "reset-pass", "phil"))
+	require.Contains(t, stdout.String(), "https://ntfy.example.com/account/password/reset/")
+}
+
+func TestCLI_User_ResetPass_NoBaseURL(t *testing.T) {
+	s, conf, port := newTestServerWithAuth(t)
+	defer test.StopServer(t, s, port)
+
+	app, stdin, _, _ := newTestApp()
+	stdin.WriteString("mypass\nmypass")
+	require.Nil(t, runUserCommand(app, conf, "add", "phil"))
+
+	app, _, _, _ = newTestApp()
+	err := runUserCommand(app, conf, "reset-pass", "phil")
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "base-url")
+}
+
+func TestCLI_User_ResetPass_SendEmailNoPrimary(t *testing.T) {
+	s, conf, port := newTestServerWithAuth(t)
+	defer test.StopServer(t, s, port)
+
+	app, stdin, _, _ := newTestApp()
+	stdin.WriteString("mypass\nmypass")
+	require.Nil(t, runUserCommand(app, conf, "add", "phil"))
+
+	// --send-email requires a primary email; phil has none
+	app, _, _, _ = newTestApp()
+	err := runUserCommand(app, conf, "--base-url=https://ntfy.example.com", "reset-pass", "--send-email", "phil")
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "no primary email")
+}
+
+func TestCLI_User_ResetPass_ProvisionedRejected(t *testing.T) {
+	s, conf, port := newTestServerWithAuth(t)
+	defer test.StopServer(t, s, port)
+
+	// Seed a provisioned user into the auth database via config provisioning
+	m, err := user.NewSQLiteManager(conf.AuthFile, "", &user.Config{
+		ProvisionEnabled: true,
+		Users: []*user.User{
+			{Name: "provuser", Hash: "$2a$10$YLiO8U21sX1uhZamTLJXHuxgVC0Z/GKISibrKCLohPgtG7yIxSk4C", Role: user.RoleUser},
+		},
+	})
+	require.Nil(t, err)
+	require.Nil(t, m.Close())
+
+	app, _, _, _ := newTestApp()
+	err = runUserCommand(app, conf, "--base-url=https://ntfy.example.com", "reset-pass", "provuser")
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "provisioned")
+}
+
 func newTestServerWithAuth(t *testing.T) (s *server.Server, conf *server.Config, port int) {
 	configFile := filepath.Join(t.TempDir(), "server-dummy.yml")
 	require.Nil(t, os.WriteFile(configFile, []byte(""), 0600)) // Dummy config file to avoid lookup of real server.yml
@@ -128,6 +192,7 @@ func newTestServerWithAuth(t *testing.T) (s *server.Server, conf *server.Config,
 	conf.File = configFile
 	conf.AuthFile = filepath.Join(t.TempDir(), "user.db")
 	conf.AuthDefault = user.PermissionDenyAll
+	conf.AuthAccessCacheEnabled = false
 	s, port = test.StartServerWithConfig(t, conf)
 	return
 }

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

@@ -353,6 +353,14 @@ This generator helps you configure your self-hosted ntfy instance. It's not full
 <label>SMTP password</label>
 <input type="password" data-key="smtp-sender-pass" placeholder="Password">
 </div>
+<div class="cg-field cg-inline-field">
+<label>Require email verification</label>
+<div class="cg-btn-group">
+<label><input type="radio" name="cg-smtp-sender-verify" value="no" checked><span>No</span></label>
+<label><input type="radio" name="cg-smtp-sender-verify" value="yes"><span>Yes</span></label>
+</div>
+</div>
+<input type="checkbox" data-key="smtp-sender-verify" id="cg-smtp-sender-verify-hidden" style="display:none">
 </div>
 <div id="cg-email-in-section" class="cg-hidden">
 <div class="cg-field"><label><strong>Incoming (publishing)</strong></label></div>
@@ -371,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">
@@ -409,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.
 
@@ -489,30 +497,41 @@ Subscribers can retrieve cached messaging using the [`poll=1` parameter](subscri
 
 ## Attachments
 If desired, you may allow users to upload and [attach files to notifications](publish.md#attachments). To enable
-this feature, you have to simply configure an attachment cache directory and a base URL (`attachment-cache-dir`, `base-url`). 
-Once these options are set and the directory is writable by the server user, you can upload attachments via PUT.
+this feature, you have to configure an attachment storage backend and a base URL (`base-url`). Attachments can be stored
+either on the [local filesystem](#filesystem-storage) or in an [S3-compatible object store](#s3-storage), both using the `attachment-cache-dir` option.
+Once configured, you can upload attachments via PUT.
 
-By default, attachments are stored in the disk-cache **for only 3 hours**. The main reason for this is to avoid legal issues
-and such when hosting user controlled content. Typically, this is more than enough time for the user (or the auto download 
-feature) to download the file. The following config options are relevant to attachments:
+By default, attachments are stored **for only 3 hours**. The main reason for this is to avoid legal issues
+and such when hosting user controlled content. Typically, this is more than enough time for the user (or the auto download
+feature) to download the file. You can increase this time by [purchasing ntfy Pro](https://ntfy.sh/app) via the web app.
+
+The following config options are relevant to attachments:
 
 * `base-url` is the root URL for the ntfy server; this is needed for the generated attachment URLs
-* `attachment-cache-dir` is the cache directory for attached files
-* `attachment-total-size-limit` is the size limit of the on-disk attachment cache (default: 5G)
+* `attachment-cache-dir` is the cache directory for attached files, or an S3 URL for object storage
+* `attachment-total-size-limit` is the size limit of the attachment storage (default: 5G)
 * `attachment-file-size-limit` is the per-file attachment size limit (e.g. 300k, 2M, 100M, default: 15M)
 * `attachment-expiry-duration` is the duration after which uploaded attachments will be deleted (e.g. 3h, 20h, default: 3h)
 
-Here's an example config using mostly the defaults (except for the cache directory, which is empty by default): 
+!!! warning
+    ntfy takes full control over the attachment directory or S3 bucket. Files that match the message ID format without
+    entries in the message table will be deleted. **Do not use a directory or S3 bucket that is also used for something else.** 
+
+Please also refer to the [rate limiting](#rate-limiting) settings below, specifically `visitor-attachment-total-size-limit`
+and `visitor-attachment-daily-bandwidth-limit`. Setting these conservatively is necessary to avoid abuse.
+
+### Filesystem storage
+Here's an example config using the local filesystem for attachment storage:
 
 === "/etc/ntfy/server.yml (minimal)"
     ``` yaml
-    base-url: "https://ntfy.sh"
+    base-url: "https://ntfy.example.com"
     attachment-cache-dir: "/var/cache/ntfy/attachments"
     ```
 
 === "/etc/ntfy/server.yml (all options)"
     ``` yaml
-    base-url: "https://ntfy.sh"
+    base-url: "https://ntfy.example.com"
     attachment-cache-dir: "/var/cache/ntfy/attachments"
     attachment-total-size-limit: "5G"
     attachment-file-size-limit: "15M"
@@ -521,8 +540,73 @@ Here's an example config using mostly the defaults (except for the cache directo
     visitor-attachment-daily-bandwidth-limit: "500M"
     ```
 
-Please also refer to the [rate limiting](#rate-limiting) settings below, specifically `visitor-attachment-total-size-limit`
-and `visitor-attachment-daily-bandwidth-limit`. Setting these conservatively is necessary to avoid abuse.
+### S3 storage
+As an alternative to the local filesystem, you can store attachments in an S3-compatible object store (e.g. [AWS S3](https://aws.amazon.com/s3/),
+[DigitalOcean Spaces](https://www.digitalocean.com/products/spaces)). This is useful for HA/cloud deployments where you don't want to rely on local disk storage. 
+To use an S3-compatible storage for attachments, set `attachment-cache-dir` to an S3 URL with the following format:
+
+```
+s3://ACCESS_KEY:SECRET_KEY@BUCKET[/PREFIX]?region=REGION[&endpoint=ENDPOINT][&disable_http2=true]
+```
+
+Here are a few examples:
+
+=== "/etc/ntfy/server.yml (DigitalOcean Spaces)"
+    ``` yaml
+    base-url: "https://ntfy.example.com"
+    attachment-cache-dir: "s3://ACCESS_KEY:SECRET_KEY@my-bucket/attachments?region=nyc3&endpoint=https://nyc3.digitaloceanspaces.com&disable_http2=true"
+    ```
+
+=== "/etc/ntfy/server.yml (AWS S3)"
+    ``` yaml
+    base-url: "https://ntfy.example.com"
+    attachment-cache-dir: "s3://ACCESS_KEY:SECRET_KEY@my-bucket/attachments?region=us-east-1"
+    ```
+
+=== "/etc/ntfy/server.yml (custom endpoint)"
+    ``` yaml
+    base-url: "https://ntfy.example.com"
+    attachment-cache-dir: "s3://ACCESS_KEY:SECRET_KEY@my-bucket/attachments?region=us-east-1&endpoint=https://s3.example.com"
+    ```
+
+Note that the access key and secret key may have to be URL encoded. For instance, a secret key `YmxhY+mxhYmxhC` (note the `+`) should
+be encoded as `YmxhY%2BmxhYmxhC` (note the `%2B`), so the URL would be `s3://ACCESS_KEY:YmxhY%2BmxhYmxhC@my-bucket/attachments...`.
+
+If you experience upload failures with HTTP/2 stream errors (common with DigitalOcean Spaces and some other S3-compatible providers),
+add `&disable_http2=true` to force HTTP/1.1 connections.
+
+!!! info
+    ntfy.sh is hosted and sponsored by DigitalOcean. I can highly recommend their public cloud offering. It's been rock solid
+    for 4 years. They offer an S3-compatible storage for $5/month and 250 GB of storage, with 1 TiB of bandwidth. 
+    Also, if you **use [this referral link](https://m.do.co/c/442b929528db), you can get $200 credit**.
+
+For AWS S3, the IAM user needs the following permissions on the bucket:
+
+``` json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Action": [
+                "s3:ListBucket",
+                "s3:ListBucketMultipartUploads"
+            ],
+            "Resource": "arn:aws:s3:::BUCKET_NAME"
+        },
+        {
+            "Effect": "Allow",
+            "Action": [
+                "s3:GetObject",
+                "s3:PutObject",
+                "s3:DeleteObject",
+                "s3:AbortMultipartUpload"
+            ],
+            "Resource": "arn:aws:s3:::BUCKET_NAME/*"
+        }
+    ]
+}
+```
 
 ## Access control
 By default, the ntfy server is open for everyone, meaning **everyone can read and write to any topic** (this is how
@@ -935,6 +1019,10 @@ To allow forwarding messages via e-mail, you can configure an **SMTP server for
 you can set the `X-Email` header to [send messages via e-mail](publish.md#e-mail-notifications) (e.g. 
 `curl -d "hi there" -H "X-Email: phil@example.com" ntfy.sh/mytopic`).
 
+!!! info
+    On ntfy.sh, anonymous email sending was disabled due to abuse. To use the email notification feature, 
+    you must verify your email in the web app's [Account section](https://ntfy.sh/account). 
+
 As of today, only SMTP servers with PLAIN auth and STARTLS are supported. To enable e-mail sending, you must set the 
 following settings:
 
@@ -942,6 +1030,8 @@ following settings:
 * `smtp-sender-addr` is the hostname:port of the SMTP server
 * `smtp-sender-user` and `smtp-sender-pass` are the username and password of the SMTP user
 * `smtp-sender-from` is the e-mail address of the sender
+* `smtp-sender-verify` is a flag that forces email recipient verification when enabled. If set to true, 
+  only verified email recipients can be used in the `X-Email` header.
 
 Here's an example config using [Amazon SES](https://aws.amazon.com/ses/) for outgoing mail (this is how it is 
 configured for `ntfy.sh`):
@@ -953,9 +1043,18 @@ configured for `ntfy.sh`):
     smtp-sender-user: "AKIDEADBEEFAFFE12345"
     smtp-sender-pass: "Abd13Kf+sfAk2DzifjafldkThisIsNotARealKeyOMG."
     smtp-sender-from: "ntfy@ntfy.sh"
+    smtp-sender-verify: true
     ```
 
-Please also refer to the [rate limiting](#rate-limiting) settings below, specifically `visitor-email-limit-burst` 
+By default, any user (including anonymous users) can send email notifications to any address. To require email
+address verification, set `smtp-sender-verify` to `true`. When enabled, anonymous users cannot send emails, and
+authenticated users can only send to *literal* email addresses they have verified in their account settings.
+
+Regardless of this setting, a logged-in user can pass `yes`/`true`/`1` as the `X-Email` value to send to their primary
+verified address (falling back to their first verified address if no primary is designated). `smtp-sender-verify` only
+governs whether arbitrary literal addresses are allowed.
+
+Please also refer to the [rate limiting](#rate-limiting) settings below, specifically `visitor-email-limit-burst`
 and `visitor-email-limit-burst`. Setting these conservatively is necessary to avoid abuse.
 
 ## E-mail publishing
@@ -1309,7 +1408,7 @@ or the root domain:
     }
     ```
 
-=== "Apache2"
+=== "Apache >= 2.4.47"
     ```
     # /etc/apache2/sites-*/ntfy.conf
 
@@ -1317,6 +1416,7 @@ or the root domain:
         ServerName ntfy.sh
 
         # Proxy connections to ntfy (requires "a2enmod proxy proxy_http")
+        # Use mod_proxy_http for websocket upgrade ('upgrade=websocket'), which requires Apache (httpd) >= 2.4.47.
         ProxyPass / http://127.0.0.1:2586/ upgrade=websocket
         ProxyPassReverse / http://127.0.0.1:2586/
 
@@ -1343,6 +1443,7 @@ or the root domain:
         Include /etc/letsencrypt/options-ssl-apache.conf
 
         # Proxy connections to ntfy (requires "a2enmod proxy proxy_http")
+        # Use mod_proxy_http for websocket upgrade ('upgrade=websocket'), which requires Apache (httpd) >= 2.4.47.
         ProxyPass / http://127.0.0.1:2586/ upgrade=websocket
         ProxyPassReverse / http://127.0.0.1:2586/
 
@@ -1355,6 +1456,68 @@ or the root domain:
     </VirtualHost>
     ```
 
+=== "Apache < 2.4.47"
+    ```
+    # /etc/apache2/sites-*/ntfy.conf
+
+    <VirtualHost *:80>
+        ServerName ntfy.sh
+
+        # Proxy connections to ntfy (requires "a2enmod proxy")
+        ProxyPass / http://127.0.0.1:2586/
+        ProxyPassReverse / http://127.0.0.1:2586/
+
+        # Enable mod_rewrite (requires "a2enmod rewrite")
+        RewriteEngine on
+        # WebSockets support (requires "a2enmod proxy_wstunnel")
+        # mod_proxy_wstunnel is deprecated as of Apache (httpd) 2.4.47. It also uses more resources since it relies on mod_rewrite.
+        RewriteCond %{HTTP:Upgrade} websocket [NC]
+        RewriteCond %{HTTP:Connection} upgrade [NC]
+        RewriteRule ^/?(.*) "ws://127.0.0.1:2586/$1" [P,L]
+
+        SetEnv proxy-nokeepalive 1
+        SetEnv proxy-sendchunked 1
+
+        # Higher than the max message size of 4096 bytes
+        LimitRequestBody 102400
+        
+        # Redirect HTTP to HTTPS, but only for GET topic addresses, since we want 
+        # it to work with curl without the annoying https:// prefix (requires "a2enmod alias")
+        <If "%{REQUEST_METHOD} == 'GET'">
+            RedirectMatch permanent "^/([-_A-Za-z0-9]{0,64})$" "https://%{SERVER_NAME}/$1"
+        </If>
+
+    </VirtualHost>
+    
+    <VirtualHost *:443>
+        ServerName ntfy.sh
+        
+        SSLEngine on
+        SSLCertificateFile /etc/letsencrypt/live/ntfy.sh/fullchain.pem
+        SSLCertificateKeyFile /etc/letsencrypt/live/ntfy.sh/privkey.pem
+        Include /etc/letsencrypt/options-ssl-apache.conf
+
+        # Proxy connections to ntfy (requires "a2enmod proxy")
+        ProxyPass / http://127.0.0.1:2586/
+        ProxyPassReverse / http://127.0.0.1:2586/
+
+        # Enable mod_rewrite (requires "a2enmod rewrite")
+        RewriteEngine on
+        # WebSockets support (requires "a2enmod proxy_wstunnel")
+        # mod_proxy_wstunnel is deprecated as of Apache (httpd) 2.4.47. It also uses more resources since it relies on mod_rewrite.
+        RewriteCond %{HTTP:Upgrade} websocket [NC]
+        RewriteCond %{HTTP:Connection} upgrade [NC]
+        RewriteRule ^/?(.*) "ws://127.0.0.1:2586/$1" [P,L]
+
+        SetEnv proxy-nokeepalive 1
+        SetEnv proxy-sendchunked 1
+
+        # Higher than the max message size of 4096 bytes 
+        LimitRequestBody 102400
+	
+    </VirtualHost>
+    ```
+
 === "caddy"
     ```
     # Note that this config is most certainly incomplete. Please help out and let me know what's missing
@@ -1493,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:
 
@@ -1759,6 +1922,17 @@ are enabled):
 * `visitor-email-limit-burst` is the initial bucket of emails each visitor has. This defaults to 16.
 * `visitor-email-limit-replenish` is the rate at which the bucket is refilled (one email per x). Defaults to 1h.
 
+### Topic creation limits
+To mitigate topic-enumeration / squatting attacks (where a single source pokes thousands of guessable
+topic names to inflate the server's in-memory topic map), there is a per-visitor limit on how many *new*
+topics each visitor can cause to be created. Touching topics that already exist in memory does not consume
+a token; only first-time insertions do.
+
+* `visitor-topic-creation-limit-burst` is the initial bucket of new-topic tokens. Set to 0 to disable
+  the limit entirely. Defaults to 100.
+* `visitor-topic-creation-limit-replenish` is the rate at which the bucket is refilled (one new topic per x).
+  Defaults to 1m.
+
 ### Firebase limits
 If [Firebase is configured](#firebase-fcm), all messages are also published to a Firebase topic (unless `Firebase: no` 
 is set). Firebase enforces [its own limits](https://firebase.google.com/docs/cloud-messaging/concept-options#topics_throttling)
@@ -1955,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.
 
@@ -1985,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
@@ -2094,80 +2335,88 @@ variable before running the `ntfy` command (e.g. `export NTFY_LISTEN_HTTP=:80`).
     `cache_duration` and `cache-duration` are both supported. This is to support stricter YAML parsers that do 
     not support dashes.
 
-| Config option                              | Env variable                                    | Format                                              | Default           | Description                                                                                                                                                                                                                     |
-|--------------------------------------------|-------------------------------------------------|-----------------------------------------------------|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `base-url`                                 | `NTFY_BASE_URL`                                 | *URL*                                               | -                 | Public facing base URL of the service (e.g. `https://ntfy.sh`)                                                                                                                                                                  |
-| `listen-http`                              | `NTFY_LISTEN_HTTP`                              | `[host]:port`                                       | `:80`             | Listen address for the HTTP web server                                                                                                                                                                                          |
-| `listen-https`                             | `NTFY_LISTEN_HTTPS`                             | `[host]:port`                                       | -                 | Listen address for the HTTPS web server. If set, you also need to set `key-file` and `cert-file`.                                                                                                                               |
-| `listen-unix`                              | `NTFY_LISTEN_UNIX`                              | *filename*                                          | -                 | Path to a Unix socket to listen on                                                                                                                                                                                              |
-| `listen-unix-mode`                         | `NTFY_LISTEN_UNIX_MODE`                         | *file mode*                                         | *system default*  | File mode of the Unix socket, e.g. 0700 or 0777                                                                                                                                                                                 |
-| `key-file`                                 | `NTFY_KEY_FILE`                                 | *filename*                                          | -                 | HTTPS/TLS private key file, only used if `listen-https` is set.                                                                                                                                                                 |
-| `cert-file`                                | `NTFY_CERT_FILE`                                | *filename*                                          | -                 | HTTPS/TLS certificate file, only used if `listen-https` is set.                                                                                                                                                                 |
-| `firebase-key-file`                        | `NTFY_FIREBASE_KEY_FILE`                        | *filename*                                          | -                 | If set, also publish messages to a Firebase Cloud Messaging (FCM) topic for your app. This is optional and only required to save battery when using the Android app. See [Firebase (FCM)](#firebase-fcm).                       |
+| Config option                              | Env variable                                    | Format                                              | Default           | Description                                                                                                                                                                                                                             |
+|--------------------------------------------|-------------------------------------------------|-----------------------------------------------------|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `base-url`                                 | `NTFY_BASE_URL`                                 | *URL*                                               | -                 | Public facing base URL of the service (e.g. `https://ntfy.sh`)                                                                                                                                                                          |
+| `listen-http`                              | `NTFY_LISTEN_HTTP`                              | `[host]:port`                                       | `:80`             | Listen address for the HTTP web server                                                                                                                                                                                                  |
+| `listen-https`                             | `NTFY_LISTEN_HTTPS`                             | `[host]:port`                                       | -                 | Listen address for the HTTPS web server. If set, you also need to set `key-file` and `cert-file`.                                                                                                                                       |
+| `listen-unix`                              | `NTFY_LISTEN_UNIX`                              | *filename*                                          | -                 | Path to a Unix socket to listen on                                                                                                                                                                                                      |
+| `listen-unix-mode`                         | `NTFY_LISTEN_UNIX_MODE`                         | *file mode*                                         | *system default*  | File mode of the Unix socket, e.g. 0700 or 0777                                                                                                                                                                                         |
+| `key-file`                                 | `NTFY_KEY_FILE`                                 | *filename*                                          | -                 | HTTPS/TLS private key file, only used if `listen-https` is set.                                                                                                                                                                         |
+| `cert-file`                                | `NTFY_CERT_FILE`                                | *filename*                                          | -                 | HTTPS/TLS certificate file, only used if `listen-https` is set.                                                                                                                                                                         |
+| `firebase-key-file`                        | `NTFY_FIREBASE_KEY_FILE`                        | *filename*                                          | -                 | If set, also publish messages to a Firebase Cloud Messaging (FCM) topic for your app. This is optional and only required to save battery when using the Android app. See [Firebase (FCM)](#firebase-fcm).                               |
 | `database-url`                             | `NTFY_DATABASE_URL`                             | *string (connection URL)*                           | -                 | PostgreSQL connection string (e.g. `postgres://user:pass@host:5432/ntfy`). If set, uses PostgreSQL for all database-backed stores (message cache, user manager, web push) instead of SQLite. See [database options](#database-options). |
-| `database-replica-urls`                    | `NTFY_DATABASE_REPLICA_URLS`                    | *list of strings (connection URLs)*                 | -                 | PostgreSQL read replica connection strings. Non-critical read-only queries are distributed across replicas (round-robin) with automatic fallback to primary. Requires `database-url`. See [read replicas](#read-replicas). |
-| `cache-file`                               | `NTFY_CACHE_FILE`                               | *filename*                                          | -                 | If 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. See [message cache](#message-cache).             |
-| `cache-duration`                           | `NTFY_CACHE_DURATION`                           | *duration*                                          | 12h               | Duration for which messages will be buffered before they are deleted. This is required to support the `since=...` and `poll=1` parameter. Set this to `0` to disable the cache entirely.                                        |
-| `cache-startup-queries`                    | `NTFY_CACHE_STARTUP_QUERIES`                    | *string (SQL queries)*                              | -                 | SQL queries to run during database startup; this is useful for tuning and [enabling WAL mode](#message-cache)                                                                                                                   |
-| `cache-batch-size`                         | `NTFY_CACHE_BATCH_SIZE`                         | *int*                                               | 0                 | Max size of messages to batch together when writing to message cache (if zero, writes are synchronous)                                                                                                                          |
-| `cache-batch-timeout`                      | `NTFY_CACHE_BATCH_TIMEOUT`                      | *duration*                                          | 0s                | Timeout for batched async writes to the message cache (if zero, writes are synchronous)                                                                                                                                         |
-| `auth-file`                                | `NTFY_AUTH_FILE`                                | *filename*                                          | -                 | Auth database file used for access control (SQLite). If set, enables authentication and access control. Not required if `database-url` is set. See [access control](#access-control).                                           |
-| `auth-default-access`                      | `NTFY_AUTH_DEFAULT_ACCESS`                      | `read-write`, `read-only`, `write-only`, `deny-all` | `read-write`      | Default permissions if no matching entries in the auth database are found. Default is `read-write`.                                                                                                                             |
-| `behind-proxy`                             | `NTFY_BEHIND_PROXY`                             | *bool*                                              | false             | If set, use forwarded header (e.g. X-Forwarded-For, X-Client-IP) to determine visitor IP address (for rate limiting)                                                                                                            |
-| `proxy-forwarded-header`                   | `NTFY_PROXY_FORWARDED_HEADER`                   | *string*                                            | `X-Forwarded-For` | Use specified header to determine visitor IP address (for rate limiting)                                                                                                                                                        |
-| `proxy-trusted-hosts`                      | `NTFY_PROXY_TRUSTED_HOSTS`                      | *comma-separated host/IP/CIDR list*                 | -                 | Comma-separated list of trusted IP addresses, hosts, or CIDRs to remove from forwarded header                                                                                                                                   |
-| `attachment-cache-dir`                     | `NTFY_ATTACHMENT_CACHE_DIR`                     | *directory*                                         | -                 | Cache directory for attached files. To enable attachments, this has to be set.                                                                                                                                                  |
-| `attachment-total-size-limit`              | `NTFY_ATTACHMENT_TOTAL_SIZE_LIMIT`              | *size*                                              | 5G                | Limit of the on-disk attachment cache directory. If the limits is exceeded, new attachments will be rejected.                                                                                                                   |
-| `attachment-file-size-limit`               | `NTFY_ATTACHMENT_FILE_SIZE_LIMIT`               | *size*                                              | 15M               | Per-file attachment size limit (e.g. 300k, 2M, 100M). Larger attachment will be rejected.                                                                                                                                       |
-| `attachment-expiry-duration`               | `NTFY_ATTACHMENT_EXPIRY_DURATION`               | *duration*                                          | 3h                | Duration after which uploaded attachments will be deleted (e.g. 3h, 20h). Strongly affects `visitor-attachment-total-size-limit`.                                                                                               |
-| `smtp-sender-addr`                         | `NTFY_SMTP_SENDER_ADDR`                         | `host:port`                                         | -                 | SMTP server address to allow email sending                                                                                                                                                                                      |
-| `smtp-sender-user`                         | `NTFY_SMTP_SENDER_USER`                         | *string*                                            | -                 | SMTP user; only used if e-mail sending is enabled                                                                                                                                                                               |
-| `smtp-sender-pass`                         | `NTFY_SMTP_SENDER_PASS`                         | *string*                                            | -                 | SMTP password; only used if e-mail sending is enabled                                                                                                                                                                           |
-| `smtp-sender-from`                         | `NTFY_SMTP_SENDER_FROM`                         | *e-mail address*                                    | -                 | SMTP sender e-mail address; only used if e-mail sending is enabled                                                                                                                                                              |
-| `smtp-server-listen`                       | `NTFY_SMTP_SERVER_LISTEN`                       | `[ip]:port`                                         | -                 | Defines the IP address and port the SMTP server will listen on, e.g. `:25` or `1.2.3.4:25`                                                                                                                                      |
-| `smtp-server-domain`                       | `NTFY_SMTP_SERVER_DOMAIN`                       | *domain name*                                       | -                 | SMTP server e-mail domain, e.g. `ntfy.sh`                                                                                                                                                                                       |
-| `smtp-server-addr-prefix`                  | `NTFY_SMTP_SERVER_ADDR_PREFIX`                  | *string*                                            | -                 | Optional prefix for the e-mail addresses to prevent spam, e.g. `ntfy-`                                                                                                                                                          |
-| `twilio-account`                           | `NTFY_TWILIO_ACCOUNT`                           | *string*                                            | -                 | Twilio account SID, e.g. AC12345beefbeef67890beefbeef122586                                                                                                                                                                     |
-| `twilio-auth-token`                        | `NTFY_TWILIO_AUTH_TOKEN`                        | *string*                                            | -                 | Twilio auth token, e.g. affebeef258625862586258625862586                                                                                                                                                                        |
-| `twilio-phone-number`                      | `NTFY_TWILIO_PHONE_NUMBER`                      | *string*                                            | -                 | Twilio outgoing phone number, e.g. +18775132586                                                                                                                                                                                 |
-| `twilio-verify-service`                    | `NTFY_TWILIO_VERIFY_SERVICE`                    | *string*                                            | -                 | Twilio Verify service SID, e.g. VA12345beefbeef67890beefbeef122586                                                                                                                                                              |
-| `keepalive-interval`                       | `NTFY_KEEPALIVE_INTERVAL`                       | *duration*                                          | 45s               | Interval in which keepalive messages are sent to the client. This is to prevent intermediaries closing the connection for inactivity. Note that the Android app has a hardcoded timeout at 77s, so it should be less than that. |
-| `manager-interval`                         | `NTFY_MANAGER_INTERVAL`                         | *duration*                                          | 1m                | Interval in which the manager prunes old messages, deletes topics and prints the stats.                                                                                                                                         |
-| `message-size-limit`                       | `NTFY_MESSAGE_SIZE_LIMIT`                       | *size*                                              | 4K                | The size limit for the message body. Please note that this is largely untested, and that FCM/APNS have limits around 4KB. If you increase this size limit, FCM and APNS will NOT work for large messages.                       |
-| `message-delay-limit`                      | `NTFY_MESSAGE_DELAY_LIMIT`                      | *duration*                                          | 3d                | Amount of time a message can be [scheduled](publish.md#scheduled-delivery) into the future when using the `Delay` header                                                                                                        |
-| `global-topic-limit`                       | `NTFY_GLOBAL_TOPIC_LIMIT`                       | *number*                                            | 15,000            | Rate limiting: Total number of topics before the server rejects new topics.                                                                                                                                                     |
-| `upstream-base-url`                        | `NTFY_UPSTREAM_BASE_URL`                        | *URL*                                               | `https://ntfy.sh` | Forward poll request to an upstream server, this is needed for iOS push notifications for self-hosted servers                                                                                                                   |
-| `upstream-access-token`                    | `NTFY_UPSTREAM_ACCESS_TOKEN`                    | *string*                                            | `tk_zyYLYj...`    | Access token to use for the upstream server; needed only if upstream rate limits are exceeded or upstream server requires auth                                                                                                  |
-| `visitor-attachment-total-size-limit`      | `NTFY_VISITOR_ATTACHMENT_TOTAL_SIZE_LIMIT`      | *size*                                              | 100M              | Rate limiting: Total storage limit used for attachments per visitor, for all attachments combined. Storage is freed after attachments expire. See `attachment-expiry-duration`.                                                 |
-| `visitor-attachment-daily-bandwidth-limit` | `NTFY_VISITOR_ATTACHMENT_DAILY_BANDWIDTH_LIMIT` | *size*                                              | 500M              | Rate limiting: Total daily attachment download/upload traffic limit per visitor. This is to protect your bandwidth costs from exploding.                                                                                        |
-| `visitor-email-limit-burst`                | `NTFY_VISITOR_EMAIL_LIMIT_BURST`                | *number*                                            | 16                | Rate limiting:Initial limit of e-mails per visitor                                                                                                                                                                              |
-| `visitor-email-limit-replenish`            | `NTFY_VISITOR_EMAIL_LIMIT_REPLENISH`            | *duration*                                          | 1h                | Rate limiting: Strongly related to `visitor-email-limit-burst`: The rate at which the bucket is refilled                                                                                                                        |
-| `visitor-message-daily-limit`              | `NTFY_VISITOR_MESSAGE_DAILY_LIMIT`              | *number*                                            | -                 | Rate limiting: Allowed number of messages per day per visitor, reset every day at midnight (UTC). By default, this value is unset.                                                                                              |
-| `visitor-request-limit-burst`              | `NTFY_VISITOR_REQUEST_LIMIT_BURST`              | *number*                                            | 60                | Rate limiting: Allowed GET/PUT/POST requests per second, per visitor. This setting is the initial bucket of requests each visitor has                                                                                           |
-| `visitor-request-limit-replenish`          | `NTFY_VISITOR_REQUEST_LIMIT_REPLENISH`          | *duration*                                          | 5s                | Rate limiting: Strongly related to `visitor-request-limit-burst`: The rate at which the bucket is refilled                                                                                                                      |
-| `visitor-request-limit-exempt-hosts`       | `NTFY_VISITOR_REQUEST_LIMIT_EXEMPT_HOSTS`       | *comma-separated host/IP/CIDR list*                 | -                 | Rate limiting: List of hostnames and IPs to be exempt from request rate limiting                                                                                                                                                |
-| `visitor-subscription-limit`               | `NTFY_VISITOR_SUBSCRIPTION_LIMIT`               | *number*                                            | 30                | Rate limiting: Number of subscriptions per visitor (IP address)                                                                                                                                                                 |
-| `visitor-subscriber-rate-limiting`         | `NTFY_VISITOR_SUBSCRIBER_RATE_LIMITING`         | *bool*                                              | `false`           | Rate limiting: Enables subscriber-based rate limiting                                                                                                                                                                           |
-| `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                                                                                                                                                   |
-| `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                                                                                                                                                                                  |
-| `enable-reservations`                      | `NTFY_ENABLE_RESERVATIONS`                      | *boolean* (`true` or `false`)                       | `false`           | Allows users to reserve topics (if their tier allows it)                                                                                                                                                                        |
-| `require-login`                            | `NTFY_REQUIRE_LOGIN`                            | *boolean* (`true` or `false`)                       | `false`           | All actions via the web app require a login                                                                                                                                                                        |
-| `stripe-secret-key`                        | `NTFY_STRIPE_SECRET_KEY`                        | *string*                                            | -                 | Payments: Key used for the Stripe API communication, this enables payments                                                                                                                                                      |
-| `stripe-webhook-key`                       | `NTFY_STRIPE_WEBHOOK_KEY`                       | *string*                                            | -                 | Payments: Key required to validate the authenticity of incoming webhooks from Stripe                                                                                                                                            |
-| `billing-contact`                          | `NTFY_BILLING_CONTACT`                          | *email address* or *website*                        | -                 | Payments: Email or website displayed in Upgrade dialog as a billing contact                                                                                                                                                     |
-| `web-push-public-key`                      | `NTFY_WEB_PUSH_PUBLIC_KEY`                      | *string*                                            | -                 | Web Push: Public Key. Run `ntfy webpush keys` to generate                                                                                                                                                                       |
-| `web-push-private-key`                     | `NTFY_WEB_PUSH_PRIVATE_KEY`                     | *string*                                            | -                 | Web Push: Private Key. Run `ntfy webpush keys` to generate                                                                                                                                                                      |
-| `web-push-file`                            | `NTFY_WEB_PUSH_FILE`                            | *string*                                            | -                 | Web Push: Database file that stores subscriptions                                                                                                                                                                               |
-| `web-push-email-address`                   | `NTFY_WEB_PUSH_EMAIL_ADDRESS`                   | *string*                                            | -                 | Web Push: Sender email address                                                                                                                                                                                                  |
-| `web-push-startup-queries`                 | `NTFY_WEB_PUSH_STARTUP_QUERIES`                 | *string*                                            | -                 | Web Push: SQL queries to run against subscription database at startup                                                                                                                                                           |
-| `web-push-expiry-duration`                 | `NTFY_WEB_PUSH_EXPIRY_DURATION`                 | *duration*                                          | 60d               | Web Push: Duration after which a subscription is considered stale and will be deleted. This is to prevent stale subscriptions.                                                                                                  |
-| `web-push-expiry-warning-duration`         | `NTFY_WEB_PUSH_EXPIRY_WARNING_DURATION`         | *duration*                                          | 55d               | Web Push: Duration after which a warning is sent to subscribers that their subscription will expire soon. This is to prevent stale subscriptions.                                                                               |
-| `log-format`                               | `NTFY_LOG_FORMAT`                               | *string*                                            | `text`            | Defines the output format, can be text or json                                                                                                                                                                                  |
-| `log-file`                                 | `NTFY_LOG_FILE`                                 | *string*                                            | -                 | Defines the filename to write logs to. If this is not set, ntfy logs to stderr                                                                                                                                                  |
-| `log-level`                                | `NTFY_LOG_LEVEL`                                | *string*                                            | `info`            | Defines the default log level, can be one of trace, debug, info, warn or error                                                                                                                                                  |
+| `database-replica-urls`                    | `NTFY_DATABASE_REPLICA_URLS`                    | *list of strings (connection URLs)*                 | -                 | PostgreSQL read replica connection strings. Non-critical read-only queries are distributed across replicas (round-robin) with automatic fallback to primary. Requires `database-url`.                                                   |
+| `cache-file`                               | `NTFY_CACHE_FILE`                               | *filename*                                          | -                 | If 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. See [message cache](#message-cache).                     |
+| `cache-duration`                           | `NTFY_CACHE_DURATION`                           | *duration*                                          | 12h               | Duration for which messages will be buffered before they are deleted. This is required to support the `since=...` and `poll=1` parameter. Set this to `0` to disable the cache entirely.                                                |
+| `cache-startup-queries`                    | `NTFY_CACHE_STARTUP_QUERIES`                    | *string (SQL queries)*                              | -                 | SQL queries to run during database startup; this is useful for tuning and [enabling WAL mode](#message-cache)                                                                                                                           |
+| `cache-batch-size`                         | `NTFY_CACHE_BATCH_SIZE`                         | *int*                                               | 0                 | Max size of messages to batch together when writing to message cache (if zero, writes are synchronous)                                                                                                                                  |
+| `cache-batch-timeout`                      | `NTFY_CACHE_BATCH_TIMEOUT`                      | *duration*                                          | 0s                | Timeout for batched async writes to the message cache (if zero, writes are synchronous)                                                                                                                                                 |
+| `auth-file`                                | `NTFY_AUTH_FILE`                                | *filename*                                          | -                 | Auth database file used for access control (SQLite). If set, enables authentication and access control. Not required if `database-url` is set. See [access control](#access-control).                                                   |
+| `auth-default-access`                      | `NTFY_AUTH_DEFAULT_ACCESS`                      | `read-write`, `read-only`, `write-only`, `deny-all` | `read-write`      | Default permissions if no matching entries in the auth database are found. Default is `read-write`.                                                                                                                                     |
+| `auth-access-cache`                        | `NTFY_AUTH_ACCESS_CACHE`                        | *bool*                                              | false             | Enables an in-memory ACL cache so authorization checks no longer hit the database. Only worth enabling on high-volume servers.                                                                                                          |
+| `behind-proxy`                             | `NTFY_BEHIND_PROXY`                             | *bool*                                              | false             | If set, use forwarded header (e.g. X-Forwarded-For, X-Client-IP) to determine visitor IP address (for rate limiting)                                                                                                                    |
+| `proxy-forwarded-header`                   | `NTFY_PROXY_FORWARDED_HEADER`                   | *string*                                            | `X-Forwarded-For` | Use specified header to determine visitor IP address (for rate limiting)                                                                                                                                                                |
+| `proxy-trusted-hosts`                      | `NTFY_PROXY_TRUSTED_HOSTS`                      | *comma-separated host/IP/CIDR list*                 | -                 | Comma-separated list of trusted IP addresses, hosts, or CIDRs to remove from forwarded header                                                                                                                                           |
+| `attachment-cache-dir`                     | `NTFY_ATTACHMENT_CACHE_DIR`                     | *directory or S3 URL*                               | -                 | Cache directory for attached files, or S3 URL for object storage (format: `s3://KEY:SECRET@BUCKET[/PREFIX]?region=REGION[&endpoint=ENDPOINT][&disable_http2=true]`).                                                                    |
+| `attachment-total-size-limit`              | `NTFY_ATTACHMENT_TOTAL_SIZE_LIMIT`              | *size*                                              | 5G                | Limit of the on-disk attachment cache directory. If the limits is exceeded, new attachments will be rejected.                                                                                                                           |
+| `attachment-file-size-limit`               | `NTFY_ATTACHMENT_FILE_SIZE_LIMIT`               | *size*                                              | 15M               | Per-file attachment size limit (e.g. 300k, 2M, 100M). Larger attachment will be rejected.                                                                                                                                               |
+| `attachment-expiry-duration`               | `NTFY_ATTACHMENT_EXPIRY_DURATION`               | *duration*                                          | 3h                | Duration after which uploaded attachments will be deleted (e.g. 3h, 20h). Strongly affects `visitor-attachment-total-size-limit`.                                                                                                       |
+| `smtp-sender-addr`                         | `NTFY_SMTP_SENDER_ADDR`                         | `host:port`                                         | -                 | SMTP server address to allow email sending                                                                                                                                                                                              |
+| `smtp-sender-user`                         | `NTFY_SMTP_SENDER_USER`                         | *string*                                            | -                 | SMTP user; only used if e-mail sending is enabled                                                                                                                                                                                       |
+| `smtp-sender-pass`                         | `NTFY_SMTP_SENDER_PASS`                         | *string*                                            | -                 | SMTP password; only used if e-mail sending is enabled                                                                                                                                                                                   |
+| `smtp-sender-from`                         | `NTFY_SMTP_SENDER_FROM`                         | *e-mail address*                                    | -                 | SMTP sender e-mail address; only used if e-mail sending is enabled                                                                                                                                                                      |
+| `smtp-sender-verify`                       | `NTFY_SMTP_SENDER_VERIFY`                       | *bool*                                              | `false`           | If true, require verified email addresses for email notifications; anonymous email sending is disabled                                                                                                                                  |
+| `smtp-server-listen`                       | `NTFY_SMTP_SERVER_LISTEN`                       | `[ip]:port`                                         | -                 | Defines the IP address and port the SMTP server will listen on, e.g. `:25` or `1.2.3.4:25`                                                                                                                                              |
+| `smtp-server-domain`                       | `NTFY_SMTP_SERVER_DOMAIN`                       | *domain name*                                       | -                 | SMTP server e-mail domain, e.g. `ntfy.sh`                                                                                                                                                                                               |
+| `smtp-server-addr-prefix`                  | `NTFY_SMTP_SERVER_ADDR_PREFIX`                  | *string*                                            | -                 | Optional prefix for the e-mail addresses to prevent spam, e.g. `ntfy-`                                                                                                                                                                  |
+| `twilio-account`                           | `NTFY_TWILIO_ACCOUNT`                           | *string*                                            | -                 | Twilio account SID, e.g. AC12345beefbeef67890beefbeef122586                                                                                                                                                                             |
+| `twilio-auth-token`                        | `NTFY_TWILIO_AUTH_TOKEN`                        | *string*                                            | -                 | Twilio auth token, e.g. affebeef258625862586258625862586                                                                                                                                                                                |
+| `twilio-phone-number`                      | `NTFY_TWILIO_PHONE_NUMBER`                      | *string*                                            | -                 | Twilio outgoing phone number, e.g. +18775132586                                                                                                                                                                                         |
+| `twilio-verify-service`                    | `NTFY_TWILIO_VERIFY_SERVICE`                    | *string*                                            | -                 | Twilio Verify service SID, e.g. VA12345beefbeef67890beefbeef122586                                                                                                                                                                      |
+| `keepalive-interval`                       | `NTFY_KEEPALIVE_INTERVAL`                       | *duration*                                          | 45s               | Interval in which keepalive messages are sent to the client. This is to prevent intermediaries closing the connection for inactivity. Note that the Android app has a hardcoded timeout at 77s, so it should be less than that.         |
+| `manager-interval`                         | `NTFY_MANAGER_INTERVAL`                         | *duration*                                          | 1m                | Interval in which the manager prunes old messages, deletes topics and prints the stats.                                                                                                                                                 |
+| `message-size-limit`                       | `NTFY_MESSAGE_SIZE_LIMIT`                       | *size*                                              | 4K                | The size limit for the message body. Please note that this is largely untested, and that FCM/APNS have limits around 4KB. If you increase this size limit, FCM and APNS will NOT work for large messages.                               |
+| `message-delay-limit`                      | `NTFY_MESSAGE_DELAY_LIMIT`                      | *duration*                                          | 3d                | Amount of time a message can be [scheduled](publish.md#scheduled-delivery) into the future when using the `Delay` header                                                                                                                |
+| `global-topic-limit`                       | `NTFY_GLOBAL_TOPIC_LIMIT`                       | *number*                                            | 15,000            | Rate limiting: Total number of topics before the server rejects new topics.                                                                                                                                                             |
+| `upstream-base-url`                        | `NTFY_UPSTREAM_BASE_URL`                        | *URL*                                               | `https://ntfy.sh` | Forward poll request to an upstream server, this is needed for iOS push notifications for self-hosted servers                                                                                                                           |
+| `upstream-access-token`                    | `NTFY_UPSTREAM_ACCESS_TOKEN`                    | *string*                                            | `tk_zyYLYj...`    | Access token to use for the upstream server; needed only if upstream rate limits are exceeded or upstream server requires auth                                                                                                          |
+| `visitor-attachment-total-size-limit`      | `NTFY_VISITOR_ATTACHMENT_TOTAL_SIZE_LIMIT`      | *size*                                              | 100M              | Rate limiting: Total storage limit used for attachments per visitor, for all attachments combined. Storage is freed after attachments expire. See `attachment-expiry-duration`.                                                         |
+| `visitor-attachment-daily-bandwidth-limit` | `NTFY_VISITOR_ATTACHMENT_DAILY_BANDWIDTH_LIMIT` | *size*                                              | 500M              | Rate limiting: Total daily attachment download/upload traffic limit per visitor. This is to protect your bandwidth costs from exploding.                                                                                                |
+| `visitor-email-limit-burst`                | `NTFY_VISITOR_EMAIL_LIMIT_BURST`                | *number*                                            | 16                | Rate limiting:Initial limit of e-mails per visitor                                                                                                                                                                                      |
+| `visitor-email-limit-replenish`            | `NTFY_VISITOR_EMAIL_LIMIT_REPLENISH`            | *duration*                                          | 1h                | Rate limiting: Strongly related to `visitor-email-limit-burst`: The rate at which the bucket is refilled                                                                                                                                |
+| `visitor-message-daily-limit`              | `NTFY_VISITOR_MESSAGE_DAILY_LIMIT`              | *number*                                            | -                 | Rate limiting: Allowed number of messages per day per visitor, reset every day at midnight (UTC). By default, this value is unset.                                                                                                      |
+| `visitor-request-limit-burst`              | `NTFY_VISITOR_REQUEST_LIMIT_BURST`              | *number*                                            | 60                | Rate limiting: Allowed GET/PUT/POST requests per second, per visitor. This setting is the initial bucket of requests each visitor has                                                                                                   |
+| `visitor-request-limit-replenish`          | `NTFY_VISITOR_REQUEST_LIMIT_REPLENISH`          | *duration*                                          | 5s                | Rate limiting: Strongly related to `visitor-request-limit-burst`: The rate at which the bucket is refilled                                                                                                                              |
+| `visitor-request-limit-exempt-hosts`       | `NTFY_VISITOR_REQUEST_LIMIT_EXEMPT_HOSTS`       | *comma-separated host/IP/CIDR list*                 | -                 | Rate limiting: List of hostnames and IPs to be exempt from request rate limiting                                                                                                                                                        |
+| `visitor-subscription-limit`               | `NTFY_VISITOR_SUBSCRIPTION_LIMIT`               | *number*                                            | 30                | Rate limiting: Number of subscriptions per visitor (IP address)                                                                                                                                                                         |
+| `visitor-subscriber-rate-limiting`         | `NTFY_VISITOR_SUBSCRIBER_RATE_LIMITING`         | *bool*                                              | `false`           | Rate limiting: Enables subscriber-based rate limiting                                                                                                                                                                                   |
+| `visitor-topic-creation-limit-burst`       | `NTFY_VISITOR_TOPIC_CREATION_LIMIT_BURST`       | *number*                                            | 100               | Rate limiting: Initial bucket of new topic creations per visitor. 0 disables the limit.                                                                                                                                                 |
+| `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                                                                                                                                                                                          |
+| `enable-reservations`                      | `NTFY_ENABLE_RESERVATIONS`                      | *boolean* (`true` or `false`)                       | `false`           | Allows users to reserve topics (if their tier allows it)                                                                                                                                                                                |
+| `require-login`                            | `NTFY_REQUIRE_LOGIN`                            | *boolean* (`true` or `false`)                       | `false`           | All actions via the web app require a login                                                                                                                                                                                             |
+| `stripe-secret-key`                        | `NTFY_STRIPE_SECRET_KEY`                        | *string*                                            | -                 | Payments: Key used for the Stripe API communication, this enables payments                                                                                                                                                              |
+| `stripe-webhook-key`                       | `NTFY_STRIPE_WEBHOOK_KEY`                       | *string*                                            | -                 | Payments: Key required to validate the authenticity of incoming webhooks from Stripe                                                                                                                                                    |
+| `billing-contact`                          | `NTFY_BILLING_CONTACT`                          | *email address* or *website*                        | -                 | Payments: Email or website displayed in Upgrade dialog as a billing contact                                                                                                                                                             |
+| `web-push-public-key`                      | `NTFY_WEB_PUSH_PUBLIC_KEY`                      | *string*                                            | -                 | Web Push: Public Key. Run `ntfy webpush keys` to generate                                                                                                                                                                               |
+| `web-push-private-key`                     | `NTFY_WEB_PUSH_PRIVATE_KEY`                     | *string*                                            | -                 | Web Push: Private Key. Run `ntfy webpush keys` to generate                                                                                                                                                                              |
+| `web-push-file`                            | `NTFY_WEB_PUSH_FILE`                            | *string*                                            | -                 | Web Push: Database file that stores subscriptions                                                                                                                                                                                       |
+| `web-push-email-address`                   | `NTFY_WEB_PUSH_EMAIL_ADDRESS`                   | *string*                                            | -                 | Web Push: Sender email address                                                                                                                                                                                                          |
+| `web-push-startup-queries`                 | `NTFY_WEB_PUSH_STARTUP_QUERIES`                 | *string*                                            | -                 | Web Push: SQL queries to run against subscription database at startup                                                                                                                                                                   |
+| `web-push-expiry-duration`                 | `NTFY_WEB_PUSH_EXPIRY_DURATION`                 | *duration*                                          | 60d               | Web Push: Duration after which a subscription is considered stale and will be deleted. This is to prevent stale subscriptions.                                                                                                          |
+| `web-push-expiry-warning-duration`         | `NTFY_WEB_PUSH_EXPIRY_WARNING_DURATION`         | *duration*                                          | 55d               | Web Push: Duration after which a warning is sent to subscribers that their subscription will expire soon. This is to prevent stale subscriptions.                                                                                       |
+| `log-format`                               | `NTFY_LOG_FORMAT`                               | *string*                                            | `text`            | Defines the output format, can be text or json                                                                                                                                                                                          |
+| `log-file`                                 | `NTFY_LOG_FILE`                                 | *string*                                            | -                 | Defines the filename to write logs to. If this is not set, ntfy logs to stderr                                                                                                                                                          |
+| `log-level`                                | `NTFY_LOG_LEVEL`                                | *string*                                            | `info`            | Defines the default log level, can be one of trace, debug, info, warn or error                                                                                                                                                          |
 
 The format for a *duration* is: `<number>(smhd)`, e.g. 30s, 20m, 1h or 3d.   
 The format for a *size* is: `<number>(GMK)`, e.g. 1G, 200M or 4000k.
@@ -2218,7 +2467,8 @@ OPTIONS:
    --auth-file value, --auth_file value, -H value                                                                         auth database file used for access control [$NTFY_AUTH_FILE]
    --auth-startup-queries value, --auth_startup_queries value                                                             queries run when the auth database is initialized [$NTFY_AUTH_STARTUP_QUERIES]
    --auth-default-access value, --auth_default_access value, -p value                                                     default permissions if no matching entries in the auth database are found (default: "read-write") [$NTFY_AUTH_DEFAULT_ACCESS]
-   --attachment-cache-dir value, --attachment_cache_dir value                                                             cache directory for attached files [$NTFY_ATTACHMENT_CACHE_DIR]
+   --auth-access-cache, --auth_access_cache                                                                                enables the in-memory ACL cache (high-volume servers only) (default: false) [$NTFY_AUTH_ACCESS_CACHE]
+   --attachment-cache-dir value, --attachment_cache_dir value                                                             cache directory for attached files, or S3 URL (s3://ACCESS_KEY:SECRET_KEY@BUCKET[/PREFIX]?region=REGION[&endpoint=ENDPOINT][&disable_http2=true]) [$NTFY_ATTACHMENT_CACHE_DIR]
    --attachment-total-size-limit value, --attachment_total_size_limit value, -A value                                     limit of the on-disk attachment cache (default: "5G") [$NTFY_ATTACHMENT_TOTAL_SIZE_LIMIT]
    --attachment-file-size-limit value, --attachment_file_size_limit value, -Y value                                       per-file attachment size limit (e.g. 300k, 2M, 100M) (default: "15M") [$NTFY_ATTACHMENT_FILE_SIZE_LIMIT]
    --attachment-expiry-duration value, --attachment_expiry_duration value, -X value                                       duration after which uploaded attachments will be deleted (e.g. 3h, 20h) (default: "3h") [$NTFY_ATTACHMENT_EXPIRY_DURATION]
@@ -2255,6 +2505,8 @@ OPTIONS:
    --visitor-message-daily-limit value, --visitor_message_daily_limit value                                               max messages per visitor per day, derived from request limit if unset (default: 0) [$NTFY_VISITOR_MESSAGE_DAILY_LIMIT]
    --visitor-email-limit-burst value, --visitor_email_limit_burst value                                                   initial limit of e-mails per visitor (default: 16) [$NTFY_VISITOR_EMAIL_LIMIT_BURST]
    --visitor-email-limit-replenish value, --visitor_email_limit_replenish value                                           interval at which burst limit is replenished (one per x) (default: "1h") [$NTFY_VISITOR_EMAIL_LIMIT_REPLENISH]
+   --visitor-topic-creation-limit-burst value, --visitor_topic_creation_limit_burst value                                 burst of new topic creations per visitor (0 = disabled) (default: 100) [$NTFY_VISITOR_TOPIC_CREATION_LIMIT_BURST]
+   --visitor-topic-creation-limit-replenish value, --visitor_topic_creation_limit_replenish value                         interval at which topic-creation tokens are refilled (one per x) (default: "1m") [$NTFY_VISITOR_TOPIC_CREATION_LIMIT_REPLENISH]
    --visitor-prefix-bits-ipv4 value, --visitor_prefix_bits_ipv4 value                                                     number of bits of the IPv4 address to use for rate limiting (default: 32, full address) (default: 32) [$NTFY_VISITOR_PREFIX_BITS_IPV4]
    --visitor-prefix-bits-ipv6 value, --visitor_prefix_bits_ipv6 value                                                     number of bits of the IPv6 address to use for rate limiting (default: 64, /64 subnet) (default: 64) [$NTFY_VISITOR_PREFIX_BITS_IPV6]
    --behind-proxy, --behind_proxy, -P                                                                                     if set, use forwarded header (e.g. X-Forwarded-For, X-Client-IP) to determine visitor IP address (for rate limiting) (default: false) [$NTFY_BEHIND_PROXY]

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
 ```
@@ -255,6 +257,7 @@ Reference: <https://stackoverflow.com/questions/34160509/options-for-testing-ser
     go run main.go \
       --log-level debug \
       serve \
+        --base-url http://localhost \
         --web-push-public-key KEY \
         --web-push-private-key KEY \
         --web-push-email-address <email> \

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/faq.md

@@ -71,7 +71,8 @@ The web app is a static website without a backend (other than the ntfy API). All
 cache and local storage. That means it does not need to be protected with a login screen, and it poses no additional 
 security risk. So technically, it does not need to be disabled.
 
-However, if you still want to disable it, you can do so with the `web-root: disable` option in the `server.yml` file. 
+However, if you still want, you can require login with the `require-login: true` option,
+or disable it with the `web-root: disable` option in the `server.yml` file. 
 
 Think of the ntfy web app like an Android/iOS app. It is freely available and accessible to anyone, yet useless without
 a proper backend. So as long as you secure your backend with ACLs, exposing the ntfy web app to the Internet is harmless.

docs/install.md

@@ -28,42 +28,130 @@ resources to get started. _I am not affiliated with Kris or Alex, I just liked t
 Please check out the [releases page](https://github.com/binwiederhier/ntfy/releases) for binaries and
 deb/rpm packages.
 
+### Download and run
+The steps below allow you to download ntfy server and run it in a pinch. But it won't be enough to install it permanently
+as a service starting at boot time.
+
 === "x86_64/amd64"
     ```bash
-    wget https://github.com/binwiederhier/ntfy/releases/download/v2.19.2/ntfy_2.19.2_linux_amd64.tar.gz
-    tar zxvf ntfy_2.19.2_linux_amd64.tar.gz
-    sudo cp -a ntfy_2.19.2_linux_amd64/ntfy /usr/local/bin/ntfy
-    sudo mkdir /etc/ntfy && sudo cp ntfy_2.19.2_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.19.2/ntfy_2.19.2_linux_armv6.tar.gz
-    tar zxvf ntfy_2.19.2_linux_armv6.tar.gz
-    sudo cp -a ntfy_2.19.2_linux_armv6/ntfy /usr/bin/ntfy
-    sudo mkdir /etc/ntfy && sudo cp ntfy_2.19.2_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.19.2/ntfy_2.19.2_linux_armv7.tar.gz
-    tar zxvf ntfy_2.19.2_linux_armv7.tar.gz
-    sudo cp -a ntfy_2.19.2_linux_armv7/ntfy /usr/bin/ntfy
-    sudo mkdir /etc/ntfy && sudo cp ntfy_2.19.2_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.19.2/ntfy_2.19.2_linux_arm64.tar.gz
-    tar zxvf ntfy_2.19.2_linux_arm64.tar.gz
-    sudo cp -a ntfy_2.19.2_linux_arm64/ntfy /usr/bin/ntfy
-    sudo mkdir /etc/ntfy && sudo cp ntfy_2.19.2_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
     ```
 
+### Install as a service
+If you want to install ntfy server permanently as a service, and your OS/distribution of choice doesn't offer a package,
+there are a few more steps to follow.
+
+Create the ntfy user and group:
+```bash
+useradd --system --home-dir /var/lib/ntfy --shell /bin/false --comment "User for the simple HTTP-based pub-sub notification service" ntfy
+```
+
+Depending on your init system, the following steps will diverge.
+
+#### On systemd systems
+Install the ntfy server unit file (which contains parameters to start the service at boot time):
+
+=== "x86_64/amd64"
+    ```bash
+    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.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.27.0_linux_armv7/server/ntfy.service /etc/systemd/system/
+    sudo chmod 644 /etc/systemd/system/ntfy.service
+    ```
+
+=== "arm64"
+    ```bash
+    sudo mv ntfy_2.27.0_linux_arm64/server/ntfy.service /etc/systemd/system/
+    sudo chmod 644 /etc/systemd/system/ntfy.service
+    ```
+
+Then notify systemd we have added a new service and start the service:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl start ntfy
+```
+
+#### On OpenRC systems
+Install the ntfy server service script:
+
+=== "x86_64/amd64"
+    ```bash
+    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.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.27.0_linux_armv7/server/ntfy.openrc /etc/init.d/ntfy
+    sudo chmod 755 /etc/init.d/ntfy
+    ```
+
+=== "arm64"
+    ```bash
+    sudo mv ntfy_2.27.0_linux_arm64/server/ntfy.openrc /etc/init.d/ntfy
+    sudo chmod 755 /etc/init.d/ntfy
+    ```
+
+Start the ntfy server service:
+
+```bash
+sudo rc-service ntfy start
+```
+
+Add the ntfy server service to the default runlevel (so that it starts at boot time):
+
+```bash
+sudo rc-update add ntfy default
+```
+
 ## Debian/Ubuntu repository
 
 !!! info
@@ -116,7 +204,7 @@ Manually installing the .deb file:
 
 === "x86_64/amd64"
     ```bash
-    wget https://github.com/binwiederhier/ntfy/releases/download/v2.19.2/ntfy_2.19.2_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
@@ -124,7 +212,7 @@ Manually installing the .deb file:
 
 === "armv6"
     ```bash
-    wget https://github.com/binwiederhier/ntfy/releases/download/v2.19.2/ntfy_2.19.2_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
@@ -132,7 +220,7 @@ Manually installing the .deb file:
 
 === "armv7/armhf"
     ```bash
-    wget https://github.com/binwiederhier/ntfy/releases/download/v2.19.2/ntfy_2.19.2_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
@@ -140,7 +228,7 @@ Manually installing the .deb file:
 
 === "arm64"
     ```bash
-    wget https://github.com/binwiederhier/ntfy/releases/download/v2.19.2/ntfy_2.19.2_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
@@ -150,28 +238,28 @@ Manually installing the .deb file:
 
 === "x86_64/amd64"
     ```bash
-    sudo rpm -ivh https://github.com/binwiederhier/ntfy/releases/download/v2.19.2/ntfy_2.19.2_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.19.2/ntfy_2.19.2_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.19.2/ntfy_2.19.2_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.19.2/ntfy_2.19.2_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
     ```
@@ -213,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.19.2/ntfy_2.19.2_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.19.2/ntfy_2.19.2_darwin_all.tar.gz > ntfy_2.19.2_darwin_all.tar.gz
-tar zxvf ntfy_2.19.2_darwin_all.tar.gz
-sudo cp -a ntfy_2.19.2_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.19.2_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
 ```
 
@@ -245,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.19.2/ntfy_2.19.2_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`
 
@@ -638,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,14 @@ 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
 - [ntfyr](https://github.com/haxwithaxe/ntfyr) - A simple commandline tool to send notifications to ntfy
@@ -98,6 +101,7 @@ I've added a ⭐ to projects or posts that have a significant following, or had
 - [Daily Fact Ntfy](https://github.com/thiswillbeyourgithub/Daily_Fact_Ntfy) - Generate [llm](https://github.com/simonw/llm) generated fact every day about any topic you're interested in.
 - [ntfyexec](https://github.com/alecthomas/ntfyexec) - Send a notification through ntfy.sh if a command fails
 - [Ntfy Desktop](https://github.com/emmaexe/ntfyDesktop) - Fully featured desktop client for Linux, built with Qt and C++.
+- [Ntfy App](https://github.com/rubix-studios-pty-ltd/ntfy-app) - Tauri/Rust desktop client for Windows, Linux and MacOS with push notifications.
 
 ## Projects + scripts 
 
@@ -107,6 +111,7 @@ I've added a ⭐ to projects or posts that have a significant following, or had
 - [ntfy-long-zsh-command](https://github.com/robfox92/ntfy-long-zsh-command) - Notifies you once a long-running command completes (zsh)
 - [ntfy-shellscripts](https://github.com/nickexyz/ntfy-shellscripts) - A few scripts for the ntfy project (Shell)
 - [alertmanager-ntfy-relay](https://github.com/therobbielee/alertmanager-ntfy-relay) - ntfy.sh relay for Alertmanager (Go)
+- [oci-notifications-ntfy-relay](https://github.com/Ryan02I5/oci-notifications-ntfy-relay) - Minimal OCI Notifications / Oracle Functions relay to ntfy topics (Python)
 - [QuickStatus](https://github.com/corneliusroot/QuickStatus) - A shell script to alert to any immediate problems upon login (Shell)
 - [ntfy.el](https://github.com/shombando/ntfy) - Send notifications from Emacs (Emacs)
 - [backup-projects](https://gist.github.com/anthonyaxenov/826ba65abbabd5b00196bc3e6af76002) - Stupidly simple backup script for own projects (Shell)
@@ -186,9 +191,11 @@ 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
 
+- [Push alerts for WHM using ntfy](https://rubixstudios.com.au/insights/push-alerts-for-whm-using-ntfy) - rubixstudios.com.au - 5/2026
 - [Device notifications via HTTP with ntfy](https://alistairshepherd.uk/writing/ntfy/) - alistairshepherd.uk - 6/2025
 - [Notifications about (almost) anything with ntfy.sh](https://hamatti.org/posts/notifications-about-almost-anything-with-ntfy-sh/) - hamatti.org - 6/2025
 - [I set up a self-hosted notification service for everything, and I'll never look back](https://www.xda-developers.com/set-up-self-hosted-notification-service/) ⭐ - xda-developers.com - 5/2025

docs/privacy.md

@@ -1,6 +1,6 @@
 # Privacy policy
 
-**Last updated:** January 2, 2026
+**Last updated:** June 15, 2026
 
 This privacy policy describes how ntfy ("we", "us", or "our") collects, uses, and handles your information
 when you use the ntfy.sh service, web app, and mobile applications (Android and iOS).
@@ -19,7 +19,9 @@ If you create an account on ntfy.sh, we collect:
 
 - **Username** - A unique identifier you choose
 - **Password** - Stored as a secure bcrypt hash (we never store your plaintext password)
-- **Email address** - Only if you subscribe to a paid plan (for billing purposes)
+- **Email address** - If you add an email address to your account for account recovery and password resets, for use
+  with the email notification feature, or if you subscribe to a paid plan (for billing purposes via Stripe). Email
+  addresses you add to your account are verified by sending a confirmation link.
 - **Phone number** - Only if you enable the phone call notification feature (verified via SMS/call)
 
 You can use ntfy without creating an account. Anonymous usage is fully supported.
@@ -76,9 +78,10 @@ Your phone number is shared with Twilio to deliver these services. Twilio's
 
 ### Amazon SES (email delivery)
 
-If you use the email notification feature (`X-Email` header), we use Amazon Simple Email Service (SES) to 
-deliver emails. The recipient email address and message content are transmitted through Amazon's infrastructure. 
-Amazon's [privacy policy](https://aws.amazon.com/privacy/) applies.
+If you use the email notification feature (`X-Email` header), or when ntfy sends account-related emails (email 
+address verification and password reset links), we use Amazon Simple Email Service (SES) to deliver emails. The 
+recipient email address and message content are transmitted through Amazon's infrastructure. Amazon's 
+[privacy policy](https://aws.amazon.com/privacy/) applies.
 
 ### Stripe (payments)
 
@@ -143,6 +146,7 @@ No cookies are used for tracking. The web app does not have a backend beyond the
 | Attachments            | 3 hours (configurable by server operators)        |
 | User accounts          | Until you delete your account                     |
 | Access tokens          | Until you revoke them or delete your account      |
+| Email addresses        | Until you remove them or delete your account      |
 | Phone numbers          | Until you remove them or delete your account      |
 | Web push subscriptions | 60 days of inactivity, then automatically removed |
 | Server logs            | Varies; debugging logs are typically temporary    |

docs/publish.md

@@ -1,7 +1,7 @@
 # Publishing
 Publishing messages can be done via HTTP PUT/POST or via the [ntfy CLI](subscribe/cli.md#publish-messages) ([install instructions](install.md)).
 Topics are created on the fly by subscribing or publishing to them. Because there is no sign-up, **the topic is essentially a password**, so pick 
-something that's not easily guessable.
+something that's not easily guessable (see [picking a topic](#picking-a-topic) for a handy topic name generator).
 
 Here's an example showing how to publish a simple message using a POST request:
 
@@ -308,6 +308,44 @@ an [external image attachment](#attach-file-from-a-url) and [email publishing](#
   <figcaption>Notification using a click action, a user action, with an external image attachment and forwarded via email</figcaption>
 </figure>
 
+## Picking a topic
+Since there is no sign-up, **the topic is essentially a password**, so pick something that's not easily guessable. Topic names may
+only contain letters, numbers, underscores and dashes (`[-_A-Za-z0-9]`), and may be up to 64 characters long.
+
+Not sure what to pick? Type a name below and the generator will add a random, hard-to-guess suffix for you. Everything happens locally in your browser:
+
+<div id="tg-widget" class="tg-generator">
+<div class="tg-header">
+<span class="tg-title">Topic name generator</span>
+<button type="button" id="tg-reroll" class="tg-reset" title="Generate a new random suffix">Regenerate suffix</button>
+</div>
+<div class="tg-body">
+<div class="tg-left">
+<div class="tg-field">
+<label for="tg-input">Type a topic name</label>
+<input type="text" id="tg-input" placeholder="e.g. backups, alerts, phil-home" autocomplete="off" autocapitalize="off" autocorrect="off" spellcheck="false">
+</div>
+<div class="tg-note">Spaces and characters other than letters, numbers, <code>-</code> and <code>_</code> are removed automatically as you type. Names are capped at 64 characters.</div>
+</div>
+<div class="tg-right">
+<div class="tg-output-row">
+<span class="tg-output-label">Your topic:</span>
+<div class="tg-output-line">
+<pre class="tg-output" id="tg-output-name"></pre>
+<button type="button" class="tg-btn-copy" data-copy="tg-output-name" title="Copy to clipboard"><svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path></svg></button>
+</div>
+</div>
+<div class="tg-output-row">
+<span class="tg-output-label">Your topic URL:</span>
+<div class="tg-output-line">
+<pre class="tg-output" id="tg-output-url">https://ntfy.sh/</pre>
+<button type="button" class="tg-btn-copy" data-copy="tg-output-url" title="Copy to clipboard"><svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path></svg></button>
+</div>
+</div>
+</div>
+</div>
+</div>
+
 ## Message title
 _Supported on:_ :material-android: :material-apple: :material-firefox:
 
@@ -932,7 +970,7 @@ Here's an example of how it will look on Android:
 </figure>
 
 ## Attachments
-_Supported on:_ :material-android: :material-firefox:
+_Supported on:_ :material-android: :material-apple: :material-firefox:
 
 You can **send images and other files to your phone** as attachments to a notification. The attachments are then downloaded
 onto your phone (depending on size and setting automatically), and can be used from the Downloads folder.
@@ -2777,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"
@@ -3182,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.
@@ -3215,10 +3265,21 @@ you'd like to persist longer, or to blast-notify yourself on all possible channe
 Usage is easy: Simply pass the `X-Email` header (or any of its aliases: `X-E-mail`, `Email`, `E-mail`, `Mail`, or `e`).
 Only one e-mail address is supported.
 
-Since ntfy does not provide auth (yet), the rate limiting is pretty strict (see [limitations](#limitations)). In the 
-default configuration, you get **16 e-mails per visitor** (IP address) and then after that one per hour. On top of 
+If you are logged in and have a verified email address on your account, you can pass `yes`, `true`, or `1` instead of an
+address to send to your **primary email address** (the one marked primary in the web app's
+[Account section](https://ntfy.sh/account)); if you haven't designated a primary, it falls back to your first verified
+address. This works regardless of the [`smtp-sender-verify`](config.md#e-mail-notifications) setting -- that setting only
+controls whether *literal* addresses must already be verified on your account.
+
+ntfy allows anonymous email sending (if enabled), so the rate limiting is pretty strict (see [limitations](#limitations)). In the
+default configuration, you get **16 e-mails per visitor** (IP address) and then after that one per hour. On top of
 that, your IP address appears in the e-mail body. This is to prevent abuse.
 
+!!! info
+    On ntfy.sh, anonymous email sending was disabled due to abuse. To use the email notification feature,
+    you must verify your email in the web app's [Account section](https://ntfy.sh/account). The daily limit for
+    free users is **5 emails per visitor per day**.
+
 === "Command line (curl)"
     ```
     curl \
@@ -3658,7 +3719,7 @@ all the supported fields:
 | `icon`        | -        | *string*                         | `https://example.com/icon.png`            | URL to use as notification [icon](#icons)                                                 |
 | `filename`    | -        | *string*                         | `file.jpg`                                | File name of the attachment                                                               |
 | `delay`       | -        | *string*                         | `30min`, `9am`                            | Timestamp or duration for delayed delivery                                                |
-| `email`       | -        | *e-mail address*                 | `phil@example.com`                        | E-mail address for e-mail notifications                                                   |
+| `email`       | -        | *e-mail address or 'yes'*        | `phil@example.com` or `yes`               | E-mail address for e-mail notifications, or `yes` to use your primary verified address    |
 | `call`        | -        | *phone number or 'yes'*          | `+1222334444` or `yes`                    | Phone number to use for [voice call](#phone-calls)                                        |
 | `sequence_id` | -        | *string*                         | `my-sequence-123`                         | Sequence ID for [updating/deleting notifications](#updating-deleting-notifications)   |
 
@@ -4094,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"
@@ -4148,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"
@@ -4871,7 +4962,7 @@ table in their canonical form.
 | `X-Markdown`    | `Markdown`, `md`                           | Enable [Markdown formatting](#markdown-formatting) in the notification body                   |
 | `X-Icon`        | `Icon`                                     | URL to use as notification [icon](#icons)                                                     |
 | `X-Filename`    | `Filename`, `file`, `f`                    | Optional [attachment](#attachments) filename, as it appears in the client                     |
-| `X-Email`       | `X-E-Mail`, `Email`, `E-Mail`, `mail`, `e` | E-mail address for [e-mail notifications](#e-mail-notifications)                              |
+| `X-Email`       | `X-E-Mail`, `Email`, `E-Mail`, `mail`, `e` | E-mail address (or `yes`) for [e-mail notifications](#e-mail-notifications)                   |
 | `X-Call`        | `Call`                                     | Phone number for [phone calls](#phone-calls)                                                  |
 | `X-Cache`       | `Cache`                                    | Allows disabling [message caching](#message-caching)                                          |
 | `X-Firebase`    | `Firebase`                                 | Allows disabling [sending to Firebase](#disable-firebase)                                     |

docs/releases.md

@@ -4,15 +4,295 @@ and the [ntfy Android app](https://github.com/binwiederhier/ntfy-android/release
 
 ## Current stable releases
 
-| Component        | Version | Release date |
-|------------------|---------|--------------|
-| ntfy server      | v2.19.2 | Mar 16, 2026 |
-| ntfy Android app | v1.24.0 | Mar 5, 2026  |
-| ntfy iOS app     | v1.3    | Nov 26, 2023 |
+| 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.19.2
+### 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
+on the production database. The topic authorization queries are consistently the highest ranking queries on the database,
+so this will help quite a bit. The current database load is quite low, but I'm expecting it to increase as more users join
+and use ntfy.
+
+**Security issues:**
+
+* Fix case-insensitive ACL topic matching on SQLite: an access control rule for `secret` no longer also matches a request for `SECRET`. SQLite's `LIKE` is case-insensitive for ASCII by default. PostgreSQL was unaffected. It's honestly incredible that this issue remained undetected for so long, especially while ntfy.sh was running on SQLite (it now runs on PostgreSQL).
+
+**Features:**
+
+* Add opt-in in-memory ACL cache (`auth-access-cache`) that serves topic authorization without a database round-trip; off by default, intended for high-volume servers
+* Add `ntfy --version` flag to the CLI ([#1722](https://github.com/binwiederhier/ntfy/issues/1722), [#1748](https://github.com/binwiederhier/ntfy/pull/1748), thanks to [@sskender](https://github.com/sskender) for the contribution, and [@Saucy9607](https://github.com/Saucy9607) for reporting)
+
+**Bug fixes + maintenance:**
+
+* Extend account token automatically from the PWA service worker, so installed PWAs don't get logged out ([#1669](https://github.com/binwiederhier/ntfy/pull/1669), [#1203](https://github.com/binwiederhier/ntfy/issues/1203), [#1533](https://github.com/binwiederhier/ntfy/issues/1533), thanks to [@nihalgonsalves](https://github.com/nihalgonsalves) for the contribution)
+* Fix `rel` attribute on auto-linked notification URLs so `noreferrer`/`noopener` are actually applied ([#1720](https://github.com/binwiederhier/ntfy/pull/1720), thanks to [@dmitrylyzo](https://github.com/dmitrylyzo) for the contribution)
+* Add systemd sandboxing/hardening to the `ntfy.service` unit ([#1467](https://github.com/binwiederhier/ntfy/pull/1467), thanks to [@Velocifyer](https://github.com/Velocifyer) for the contribution)
+* Fix `cmd` package build on macOS (darwin) so the server compiles from source ([#1631](https://github.com/binwiederhier/ntfy/issues/1631), [#1696](https://github.com/binwiederhier/ntfy/pull/1696), thanks to [@ShipItAndPray](https://github.com/ShipItAndPray) for the contribution, and [@XYenon](https://github.com/XYenon) for reporting)
+
+## ntfy iOS app v1.7.0
+Released May 30, 2026
+
+This release brings **image and attachment support** to the iOS app, finally closing one of the longest-standing iOS
+feature gaps. Images sent via the `Attach` header (or as a PUT body) are now previewed inline in the notification banner
+and inside the app, and other attachments can be downloaded, previewed via Quick Look, and shared from the notification
+row. There's also a new "Download attachments" setting to control auto-download by size.
+
+**Features:**
+
+* Show image previews in notifications and inline in the notification list, with tap-to-zoom Quick Look preview and share sheet ([ntfy-ios#40](https://github.com/binwiederhier/ntfy-ios/pull/40), [#276](https://github.com/binwiederhier/ntfy/issues/276), [#1226](https://github.com/binwiederhier/ntfy/issues/1226), thanks to [@am7590](https://github.com/am7590) for the contribution)
+* Download non-image attachments on demand with progress indication, persist them locally, and reuse files already fetched by the notification service extension ([ntfy-ios#40](https://github.com/binwiederhier/ntfy-ios/pull/40), thanks to [@am7590](https://github.com/am7590) for the contribution)
+* Add "Download attachments" setting with size thresholds (Never, Under 100 KB / 500 KB / 1 MB / 5 MB / 10 MB / 50 MB, Always) to control automatic attachment downloads ([ntfy-ios#40](https://github.com/binwiederhier/ntfy-ios/pull/40), thanks to [@am7590](https://github.com/am7590) for the contribution)
+
+**Bug fixes + maintenance:**
+
+* Improve background download reliability so attachments continue downloading when the app is suspended ([ntfy-ios#40](https://github.com/binwiederhier/ntfy-ios/pull/40), thanks to [@am7590](https://github.com/am7590) for the contribution)
+* Reorganize notification and subscription views into their own folders and split out `NotificationRowView` for readability ([ntfy-ios#40](https://github.com/binwiederhier/ntfy-ios/pull/40), thanks to [@am7590](https://github.com/am7590) for the contribution)
+
+## ntfy server v2.23.0
+Released May 17, 2026
+
+**Features:**
+
+* Add per-visitor rate limit on new topic creations (`visitor-topic-creation-limit-burst` / `visitor-topic-creation-limit-replenish`, defaults 100 burst / 1m replenish) to mitigate topic-enumeration / squatting attacks that inflate the in-memory topic map
+
+**Bug fixes + maintenance:**
+
+* Remove `stacktrace-js`, `stacktrace-gps`, `humanize-duration`, and `js-base64` from the web app to reduce dependency and security footprint
+* Restrict the publish dialog's local file preview to safe image types (png/jpg/gif/webp) to prevent same-origin script execution from blob URLs when previewing a crafted SVG ([GHSA-j8hr-p342-xrmh](https://github.com/binwiederhier/ntfy/security/advisories/GHSA-j8hr-p342-xrmh), thanks to [@Venukamatchi](https://github.com/Venukamatchi) for reporting)
+
+## ntfy iOS app v1.6.0
+Released May 12, 2026
+
+**Bug fixes + maintenance:**
+
+* Fix crash in iOS v1.5.1 ([#1736](https://github.com/binwiederhier/ntfy/issues/1736), thanks to [@russ-who](https://github.com/russ-who) for reporting and [@am7590](https://github.com/am7590) for fixing)
+
+**Features:**
+
+* Tap a notification to open its click URL, or copy the message text if no click URL is set; inline URLs in message text are now tappable as well ([ntfy-ios#37](https://github.com/binwiederhier/ntfy-ios/pull/37), thanks to [@am7590](https://github.com/am7590) for the contribution)
+
+## ntfy iOS app v1.5.1
+Released April 27, 2026
+
+This release continues the iOS stability push from v1.4.1, with improved background polling reliability, better error
+handling and logging, and a few small UI fixes. The minimum supported iOS version is now iOS 15.
+
+**Features:**
+
+* Bump minimum iOS version to iOS 15 ([ntfy-ios#36](https://github.com/binwiederhier/ntfy-ios/pull/36), thanks to [@am7590](https://github.com/am7590) for the contribution)
+
+**Bug fixes + maintenance:**
+
+* Improve background poll reliability by waiting for polls to finish before calling the fetch completion handler, and saving notifications on the Core Data context queue ([ntfy-ios#34](https://github.com/binwiederhier/ntfy-ios/pull/34), thanks to [@am7590](https://github.com/am7590) for the contribution)
+* Make `poll_request` parsing more tolerant and surface concrete poll errors instead of failing silently ([ntfy-ios#34](https://github.com/binwiederhier/ntfy-ios/pull/34), thanks to [@am7590](https://github.com/am7590) for the contribution)
+* Poll subscriptions when the subscribed topics list appears, for more reactive updates ([ntfy-ios#34](https://github.com/binwiederhier/ntfy-ios/pull/34), thanks to [@am7590](https://github.com/am7590) for the contribution)
+* Fix bug where tapping "Add user" a second time would briefly open and then dismiss the add user view ([ntfy-ios#35](https://github.com/binwiederhier/ntfy-ios/pull/35), thanks to [@am7590](https://github.com/am7590) for the contribution)
+* Split `SettingsView` into separate files to improve readability ([ntfy-ios#35](https://github.com/binwiederhier/ntfy-ios/pull/35), thanks to [@am7590](https://github.com/am7590) for the contribution)
+* Add Firebase subscribe/unsubscribe logging to aid debugging ([ntfy-ios#34](https://github.com/binwiederhier/ntfy-ios/pull/34), thanks to [@am7590](https://github.com/am7590) for the contribution)
+
+## ntfy server v2.22.0
+Released April 21, 2026
+
+**Bug fixes + maintenance:**
+
+* Tighten web push endpoint allow-list regex to prevent SSRF via unanchored pattern matching ([GHSA-w9hq-5jg7-q4j7](https://github.com/binwiederhier/ntfy/security/advisories/GHSA-w9hq-5jg7-q4j7), thanks to [@MightyNawaf](https://github.com/MightyNawaf) for reporting)
+* Fix web app not allowing access tokens to be changed to never expire ([#1693](https://github.com/binwiederhier/ntfy/issues/1693)/[#1694](https://github.com/binwiederhier/ntfy/pull/1694), thanks to [@lastsamurai26](https://github.com/lastsamurai26) for reporting and to [@ShipItAndPray](https://github.com/ShipItAndPray) for fixing)
+* Fix web app crashing on account page for tokens without a last access time ([#1651](https://github.com/binwiederhier/ntfy/issues/1651), [#1684](https://github.com/binwiederhier/ntfy/issues/1684), thanks to [@Pulsar7](https://github.com/Pulsar7) and [@rzhli](https://github.com/rzhli) for reporting)
+
+## ntfy iOS app v1.4.1
+Released April 14, 2026
+
+This is the first iOS release in 3 years, focusing on stability fixes as per the [iOS improvement plan](https://github.com/binwiederhier/ntfy/issues/1680).
+
+**Bug fixes + maintenance:**
+
+* Fix crash when deleting notifications ([ntfy-ios#33](https://github.com/binwiederhier/ntfy-ios/pull/33), [#1642](https://github.com/binwiederhier/ntfy/issues/1642), [#377](https://github.com/binwiederhier/ntfy/issues/377), thanks to [@am7590](https://github.com/am7590) for the contribution)
+* Fix topic normalization for base URLs and refresh list after sending test notification ([ntfy-ios#32](https://github.com/binwiederhier/ntfy-ios/pull/32), [#337](https://github.com/binwiederhier/ntfy/issues/337), thanks to [@am7590](https://github.com/am7590) for the contribution)
+
+## ntfy server v2.21.0
+Released March 30, 2026
+
+This release adds the ability to verify email addresses using the `smtp-sender-verify` flag. This is a change that is
+required because ntfy.sh was used to send unsolicited emails and the AWS SES account was suspended. Going forward,
+ntfy.sh won't be able to send emails unless the email address was verified ahead of time.
+
+**Features:**
+
+* Add verified email recipients feature with `smtp-sender-verify` config flag, allowing server admins to require email
+  address verification before sending email notifications ([#1681](https://github.com/binwiederhier/ntfy/pull/1681))
+
+## ntfy server v2.20.1
+Released March 27, 2026
+
+This is a small bugfix release that only affects high volume S3 backends that struggle with HTTP/2.
+
+**Bug fixes + maintenance:**
+
+* [Attachments](config.md#attachments): Add `disable_http2=true` S3 URL option to work around HTTP/2 stream errors with DigitalOcean Spaces and other S3-compatible providers ([#1678](https://github.com/binwiederhier/ntfy/issues/1678)/[#1679](https://github.com/binwiederhier/ntfy/pull/1679))
+
+## ntfy server v2.20.0
+Released March 26, 2026
+
+This release is another step towards making it possible to help scale ntfy up and out 🔥! With this release, you can store
+attachments in an S3-compatible object store as an alterative to the directory. See [attachment store](config.md#attachments)
+for details.
+
+!!! warning
+    With this release, ntfy will take full control over the attachment directory or S3 bucket. Files/objects in the configured `attachment-cache-dir`
+    that match the message ID format (12 chars, matching `^[A-Za-z0-9]{12}$`), and have no entries in the message database will be deleted.
+    **Do not use a directory or S3 bucket as `attachment-cache-dir` that is also used for something else.**
+
+    This is a small behavioral change that was necessary because the old logic often left attachments behind and would not clean them
+    up. Unless you have re-used the attachment directory for anything else (which is hopefully never done), this should not affect
+    you at all.
+
+**Features:**
+
+* Add S3-compatible object storage as an alternative [attachment store](config.md#attachments) via `attachment-cache-dir` config option ([#1656](https://github.com/binwiederhier/ntfy/pull/1656)/[#1672](https://github.com/binwiederhier/ntfy/pull/1672))
+
+**Bug fixes + maintenance:**
+
+* Reject invalid e-mail addresses (e.g. multiple comma-separated recipients) with HTTP 400
+* Add OpenRC init service file ([#1650](https://github.com/binwiederhier/ntfy/pull/1650), thanks to [@ageru](https://github.com/ageru) for the contribution)
+
+## ntfy server v2.19.2
 Released March 16, 2026
 
 This is another small bugfix release for PostgreSQL, avoiding races between primary and read replica, as well as to
@@ -47,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:**
@@ -59,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,
@@ -70,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:**
 
@@ -1798,4 +2078,15 @@ and the [ntfy Android app](https://github.com/binwiederhier/ntfy-android/release
 
 ## Not released yet
 
-Nothing.
+### ntfy iOS app v1.8.0 (UNRELEASED)
+
+**Features:**
+
+* Deliver priority 5 (max/urgent) notifications as critical alerts that bypass silent mode and Do Not Disturb ([ntfy-ios#44](https://github.com/binwiederhier/ntfy-ios/pull/44), thanks to [@am7590](https://github.com/am7590) for the contribution)
+* Apply the attachment auto-download size setting to all attachment types, not just images ([ntfy-ios#43](https://github.com/binwiederhier/ntfy-ios/pull/43), thanks to [@am7590](https://github.com/am7590) for the contribution)
+
+**Bug fixes + maintenance:**
+
+* Restore the native swipe-to-go-back gesture in the topic detail view ([ntfy-ios#45](https://github.com/binwiederhier/ntfy-ios/pull/45), thanks to [@am7590](https://github.com/am7590) for the contribution)
+* Fix saved attachments being left "in use" so they couldn't be deleted in the Files app ([ntfy-ios#43](https://github.com/binwiederhier/ntfy-ios/pull/43), thanks to [@am7590](https://github.com/am7590) for the contribution)
+* Improve poll request subscription matching for protected topics so notifications resolve to the real message content, with better logging ([ntfy-ios#43](https://github.com/binwiederhier/ntfy-ios/pull/43), thanks to [@am7590](https://github.com/am7590) for the contribution)

docs/static/css/topic-generator.css

@@ -0,0 +1,235 @@
+/* Topic name generator (Publishing page) */
+/* Styled to mirror the config generator (header + left form / right output panels). */
+
+.tg-generator {
+    margin: 16px 0 24px;
+    border: 1px solid #ddd;
+    border-radius: 10px;
+    background: #fff;
+    overflow: hidden;
+    font-size: 0.78rem;
+    box-shadow: 0 2px 10px rgba(0, 0, 0, 0.06);
+}
+
+/* Header (matches .cg-modal-header) */
+.tg-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 10px 16px;
+    border-bottom: 1px solid #ddd;
+}
+
+.tg-title {
+    font-weight: 600;
+    font-size: 0.9rem;
+}
+
+.tg-reset {
+    background: none;
+    border: 1px solid #ccc;
+    border-radius: 4px;
+    font-size: 0.72rem;
+    color: #777;
+    cursor: pointer;
+    padding: 4px 12px;
+    font-family: inherit;
+    transition: color 0.15s, border-color 0.15s;
+}
+
+.tg-reset:hover {
+    color: #333;
+    border-color: #999;
+}
+
+/* Body: left (form) + right (output), matches .cg-modal-body */
+.tg-body {
+    display: flex;
+    min-height: 0;
+}
+
+.tg-left {
+    flex: 1;
+    border-right: 1px solid #ddd;
+    padding: 16px 18px;
+    min-width: 0;
+}
+
+.tg-right {
+    flex: 1;
+    padding: 16px 18px;
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    min-width: 0;
+}
+
+/* One output per block: label on its own line, then value field + copy button */
+.tg-output-row {
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+}
+
+.tg-output-line {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    min-width: 0;
+}
+
+/* Form field (matches .cg-field) */
+.tg-field > label {
+    display: block;
+    font-weight: 500;
+    margin-bottom: 4px;
+    font-size: 0.78rem;
+    color: #555;
+}
+
+.tg-field input[type="text"] {
+    width: 100%;
+    padding: 6px 8px;
+    border: 1px solid #ccc;
+    border-radius: 4px;
+    font-size: 0.78rem;
+    font-family: inherit;
+    box-sizing: border-box;
+    background: #fff;
+}
+
+.tg-field input[type="text"]:focus {
+    border-color: var(--md-primary-fg-color);
+    outline: none;
+    box-shadow: 0 0 0 2px rgba(51, 133, 116, 0.15);
+}
+
+.tg-note {
+    margin-top: 10px;
+    font-size: 0.72rem;
+    color: #999;
+    line-height: 1.5;
+}
+
+.tg-note code {
+    font-size: 0.72rem;
+    padding: 1px 4px;
+}
+
+.tg-output-label {
+    margin-bottom: 4px;
+    white-space: nowrap;
+    font-weight: 500;
+    font-size: 0.78rem;
+    color: #555;
+}
+
+/* Copy button (matches .cg-btn-copy) */
+.tg-btn-copy {
+    background: none;
+    color: #777;
+    border: none;
+    padding: 2px 4px;
+    cursor: pointer;
+    line-height: 1;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: color 0.15s;
+}
+
+.tg-btn-copy:hover {
+    color: #333;
+}
+
+/* Output block (matches .cg-output-wrap pre). Scoped under .tg-generator so the margin
+   reset beats the theme's .md-typeset pre rule, which otherwise adds a stray top margin. */
+.tg-generator .tg-output {
+    flex: 1;
+    min-width: 0;
+    margin: 0;
+    padding: 6px 9px;
+    background: #f5f5f5;
+    color: var(--md-default-fg-color);
+    border: 1px solid #ddd;
+    border-radius: 6px;
+    overflow-x: auto;
+    font-family: var(--md-code-font-family, monospace);
+    font-size: 0.72rem;
+    line-height: 1.5;
+    white-space: pre-wrap;
+    word-break: break-all;
+    overflow-wrap: anywhere;
+}
+
+/* Dark mode */
+body[data-md-color-scheme="slate"] .tg-generator {
+    background: #1e1e2e;
+    border-color: #444;
+}
+
+body[data-md-color-scheme="slate"] .tg-header {
+    border-bottom-color: #444;
+}
+
+body[data-md-color-scheme="slate"] .tg-title {
+    color: #ddd;
+}
+
+body[data-md-color-scheme="slate"] .tg-reset {
+    border-color: #555;
+    color: #888;
+}
+
+body[data-md-color-scheme="slate"] .tg-reset:hover {
+    border-color: #888;
+    color: #ddd;
+}
+
+body[data-md-color-scheme="slate"] .tg-left {
+    border-right-color: #444;
+}
+
+body[data-md-color-scheme="slate"] .tg-field > label,
+body[data-md-color-scheme="slate"] .tg-output-label {
+    color: #aaa;
+}
+
+body[data-md-color-scheme="slate"] .tg-btn-copy {
+    color: #888;
+}
+
+body[data-md-color-scheme="slate"] .tg-btn-copy:hover {
+    color: #bbb;
+}
+
+body[data-md-color-scheme="slate"] .tg-field input[type="text"] {
+    background: #2a2a3a;
+    border-color: #555;
+    color: #ddd;
+}
+
+body[data-md-color-scheme="slate"] .tg-note {
+    color: #777;
+}
+
+body[data-md-color-scheme="slate"] .tg-output {
+    background: #161620;
+    border-color: #444;
+}
+
+/* Responsive: stack panels like the config generator does on mobile */
+@media (max-width: 700px) {
+    .tg-body {
+        flex-direction: column;
+    }
+
+    .tg-left {
+        border-right: none;
+        border-bottom: 1px solid #ddd;
+    }
+
+    body[data-md-color-scheme="slate"] .tg-left {
+        border-bottom-color: #444;
+    }
+}

docs/static/js/config-generator.js

@@ -125,6 +125,7 @@
     { key: "smtp-sender-from", env: "NTFY_SMTP_SENDER_FROM", section: "smtp-out" },
     { key: "smtp-sender-user", env: "NTFY_SMTP_SENDER_USER", section: "smtp-out" },
     { key: "smtp-sender-pass", env: "NTFY_SMTP_SENDER_PASS", section: "smtp-out" },
+    { key: "smtp-sender-verify", env: "NTFY_SMTP_SENDER_VERIFY", section: "smtp-out", type: "bool" },
     { key: "smtp-server-listen", env: "NTFY_SMTP_SERVER_LISTEN", section: "smtp-in" },
     { key: "smtp-server-domain", env: "NTFY_SMTP_SERVER_DOMAIN", section: "smtp-in" },
     { key: "smtp-server-addr-prefix", env: "NTFY_SMTP_SERVER_ADDR_PREFIX", section: "smtp-in" },
@@ -171,6 +172,7 @@
       requireLoginHidden: modal.querySelector("#cg-require-login-hidden"),
       signupHidden: modal.querySelector("#cg-enable-signup-hidden"),
       proxyCheckbox: modal.querySelector("#cg-behind-proxy"),
+      smtpSenderVerifyHidden: modal.querySelector("#cg-smtp-sender-verify-hidden"),
       dbStep: modal.querySelector("#cg-wizard-db"),
       navDb: modal.querySelector("#cg-nav-database"),
       navEmail: modal.querySelector("#cg-nav-email"),
@@ -743,6 +745,10 @@
     const signupYes = modal.querySelector("input[name=\"cg-enable-signup\"][value=\"yes\"]");
     if (signupYes && signupHidden) signupHidden.checked = signupYes.checked;
 
+    // SMTP sender verify radio → hidden checkbox
+    const smtpVerifyYes = modal.querySelector("input[name=\"cg-smtp-sender-verify\"][value=\"yes\"]");
+    if (smtpVerifyYes && els.smtpSenderVerifyHidden) els.smtpSenderVerifyHidden.checked = smtpVerifyYes.checked;
+
     return loginModeVal;
   }
 

docs/static/js/topic-generator.js

@@ -0,0 +1,121 @@
+// Topic name generator for the ntfy docs
+//
+// A tiny helper that lives on the "Publishing" page. The user types a memorable
+// prefix (e.g. "backups"), and the widget appends a random, hard-to-guess suffix
+// (e.g. "backups-x7Kp2mQ9"). The result is a valid, unguessable topic name.
+//
+// Topic names on the server must match ^[-_A-Za-z0-9]{1,64}$ (see server.go), so as
+// the user types we strip anything that isn't allowed (spaces, slashes, punctuation,
+// emoji, ...) live and cap the whole thing at 64 characters. The random suffix is
+// generated once on load and can be re-rolled with the "Regenerate suffix" button.
+(function () {
+  // Allowed topic characters per the server regex ^[-_A-Za-z0-9]{1,64}$
+  const ALLOWED = /[^-_A-Za-z0-9]/g;
+  const MAX_LEN = 64;
+
+  // Suffix alphabet: full base62 (letters + digits). We deliberately keep look-alikes
+  // (0/O, l/1) for maximum entropy -- this is a generated suffix, not something typed by
+  // hand. Hyphen/underscore are excluded so the "-" separator stays visually clear.
+  const SUFFIX_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  const SUFFIX_LEN = 10;
+
+  // randomSuffix returns a cryptographically random string from SUFFIX_ALPHABET.
+  // It uses rejection sampling to avoid the modulo bias that a plain `byte % 62` would
+  // introduce (256 is not a multiple of 62), keeping every character equally likely.
+  function randomSuffix() {
+    const n = SUFFIX_ALPHABET.length;
+    const limit = Math.floor(256 / n) * n; // largest multiple of n that fits in a byte
+    const buf = new Uint8Array(1);
+    let out = "";
+    while (out.length < SUFFIX_LEN) {
+      crypto.getRandomValues(buf);
+      if (buf[0] < limit) {
+        out += SUFFIX_ALPHABET[buf[0] % n];
+      }
+    }
+    return out;
+  }
+
+  // sanitize strips everything that isn't a valid topic character.
+  function sanitize(value) {
+    return value.replace(ALLOWED, "");
+  }
+
+  function initTopicGenerator() {
+    const root = document.getElementById("tg-widget");
+    if (!root) return;
+
+    const input = root.querySelector("#tg-input");
+    const outputName = root.querySelector("#tg-output-name");
+    const outputUrl = root.querySelector("#tg-output-url");
+    const reroll = root.querySelector("#tg-reroll");
+
+    let suffix = randomSuffix();
+
+    // update recomputes the live preview from the (sanitized) input + current suffix.
+    function update() {
+      // Sanitize in place so the user sees disallowed characters disappear as they type.
+      const cleaned = sanitize(input.value);
+      if (cleaned !== input.value) {
+        const pos = input.selectionStart - (input.value.length - cleaned.length);
+        // Reassigning .value and setSelectionRange make the browser scroll the field into
+        // view (there is no preventScroll option for setSelectionRange), which jumps the
+        // whole page. Capture the scroll position and restore it afterwards.
+        const scrollX = window.scrollX;
+        const scrollY = window.scrollY;
+        input.value = cleaned;
+        // Best-effort caret restore so removing a bad char doesn't jump the cursor to the end.
+        try { input.setSelectionRange(pos, pos); } catch { /* ignore */ }
+        window.scrollTo(scrollX, scrollY);
+      }
+
+      // Compose "<prefix>-<suffix>", capped at the 64-char topic limit. With no prefix,
+      // fall back to just the random suffix so the output is always a valid topic.
+      let topic;
+      if (cleaned === "") {
+        topic = suffix;
+      } else {
+        const maxPrefix = MAX_LEN - suffix.length - 1; // room for "-" + suffix
+        const prefix = cleaned.slice(0, Math.max(0, maxPrefix));
+        topic = prefix === "" ? suffix : prefix + "-" + suffix;
+      }
+
+      outputName.textContent = topic;
+      outputUrl.textContent = "https://ntfy.sh/" + topic;
+    }
+
+    input.addEventListener("input", update);
+    reroll.addEventListener("click", function () {
+      suffix = randomSuffix();
+      update();
+      input.focus();
+    });
+
+    // Copy buttons: copy the target output and briefly swap the clipboard icon for a checkmark,
+    // mirroring the config generator's copy button behavior.
+    const copyIcon = "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"14\" height=\"14\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><rect x=\"9\" y=\"9\" width=\"13\" height=\"13\" rx=\"2\" ry=\"2\"></rect><path d=\"M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1\"></path></svg>";
+    const checkIcon = "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"14\" height=\"14\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><polyline points=\"20 6 9 17 4 12\"></polyline></svg>";
+    root.querySelectorAll(".tg-btn-copy").forEach(function (btn) {
+      btn.addEventListener("click", function () {
+        const target = root.querySelector("#" + btn.dataset.copy);
+        if (!target || !target.textContent) return;
+        navigator.clipboard.writeText(target.textContent).then(function () {
+          btn.innerHTML = checkIcon;
+          btn.style.color = "var(--md-primary-fg-color)";
+          setTimeout(function () {
+            btn.innerHTML = copyIcon;
+            btn.style.color = "";
+          }, 2000);
+        });
+      });
+    });
+
+    update();
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initTopicGenerator);
+  } else {
+    initTopicGenerator();
+  }
+})();

go.mod

@@ -1,25 +1,25 @@
 module heckel.io/ntfy/v2
 
-go 1.25.0
+go 1.25.8
 
 require (
-	cloud.google.com/go/firestore v1.21.0 // indirect
-	cloud.google.com/go/storage v1.61.3 // 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.18.0
-	github.com/gabriel-vasile/mimetype v1.4.13
+	github.com/emersion/go-smtp v0.24.0
+	github.com/gabriel-vasile/mimetype v1.4.15
 	github.com/gorilla/websocket v1.5.3
-	github.com/mattn/go-sqlite3 v1.14.34
+	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.49.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.41.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.271.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.19.0
+	firebase.google.com/go/v4 v4.21.0
 	github.com/SherClockHolmes/webpush-go v1.4.0
-	github.com/jackc/pgx/v5 v5.8.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.42.0
-	golang.org/x/text v0.35.0
+	golang.org/x/sys v0.47.0
+	golang.org/x/text v0.40.0
 )
 
 require (
-	cel.dev/expr v0.25.1 // indirect
+	cel.dev/expr v0.25.2 // indirect
 	cloud.google.com/go v0.123.0 // indirect
-	cloud.google.com/go/auth v0.18.3-0.20260310051336-87cdcc9f7568 // 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.5.3 // indirect
-	cloud.google.com/go/longrunning v0.8.0 // indirect
-	cloud.google.com/go/monitoring v1.24.3 // 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.31.0 // indirect
-	github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/metric v0.55.0 // indirect
-	github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/resourcemapping v0.55.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/go-jose/go-jose/v4 v4.1.3 // indirect
-	github.com/go-logr/logr v1.4.3 // 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.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.14 // indirect
-	github.com/googleapis/gax-go/v2 v2.18.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,28 +79,27 @@ 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.67.5 // 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.6.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
-	go.opentelemetry.io/contrib/detectors/gcp v1.42.0 // indirect
-	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.67.0 // indirect
-	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0 // indirect
-	go.opentelemetry.io/otel v1.42.0 // indirect
-	go.opentelemetry.io/otel/metric v1.42.0 // indirect
-	go.opentelemetry.io/otel/sdk v1.42.0 // indirect
-	go.opentelemetry.io/otel/sdk/metric v1.42.0 // indirect
-	go.opentelemetry.io/otel/trace v1.42.0 // indirect
-	go.yaml.in/yaml/v2 v2.4.4 // indirect
-	golang.org/x/net v0.52.0 // indirect
+	go.opentelemetry.io/contrib/detectors/gcp v1.44.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.69.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0 // indirect
+	go.opentelemetry.io/otel v1.44.0 // indirect
+	go.opentelemetry.io/otel/metric v1.44.0 // indirect
+	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.57.0 // indirect
 	google.golang.org/appengine/v2 v2.0.6 // indirect
-	google.golang.org/genproto v0.0.0-20260311181403-84a4fc48630c // indirect
-	google.golang.org/genproto/googleapis/api v0.0.0-20260311181403-84a4fc48630c // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20260311181403-84a4fc48630c // indirect
-	google.golang.org/grpc v1.79.2 // 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

@@ -1,41 +1,41 @@
-cel.dev/expr v0.25.1 h1:1KrZg61W6TWSxuNZ37Xy49ps13NUovb66QLprthtwi4=
-cel.dev/expr v0.25.1/go.mod h1:hrXvqGP6G6gyx8UAHSHJ5RGk//1Oj5nXQ2NI02Nrsg4=
+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.18.3-0.20260310051336-87cdcc9f7568 h1:PJt3KrySfZkKdcEV2wlyNkfAPbMZGjtnv5oLrT4tWPg=
-cloud.google.com/go/auth v0.18.3-0.20260310051336-87cdcc9f7568/go.mod h1:/Tt0rLCp4FHXEBtdyYqvIZPcJzbpJ/fmqtgIaXseDK4=
+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.21.0 h1:BhopUsx7kh6NFx77ccRsHhrtkbJUmDAxNY3uapWdjcM=
-cloud.google.com/go/firestore v1.21.0/go.mod h1:1xH6HNcnkf/gGyR8udd6pFO4Z7GWJSwLKQMx/u6UrP4=
-cloud.google.com/go/iam v1.5.3 h1:+vMINPiDF2ognBJ97ABAYYwRgsaqxPbQDlMnbHMjolc=
-cloud.google.com/go/iam v1.5.3/go.mod h1:MR3v9oLkZCTlaqljW6Eb2d3HGDGK5/bDv93jhfISFvU=
-cloud.google.com/go/logging v1.13.2 h1:qqlHCBvieJT9Cdq4QqYx1KPadCQ2noD4FK02eNqHAjA=
-cloud.google.com/go/logging v1.13.2/go.mod h1:zaybliM3yun1J8mU2dVQ1/qDzjbOqEijZCn6hSBtKak=
-cloud.google.com/go/longrunning v0.8.0 h1:LiKK77J3bx5gDLi4SMViHixjD2ohlkwBi+mKA7EhfW8=
-cloud.google.com/go/longrunning v0.8.0/go.mod h1:UmErU2Onzi+fKDg2gR7dusz11Pe26aknR4kHmJJqIfk=
-cloud.google.com/go/monitoring v1.24.3 h1:dde+gMNc0UhPZD1Azu6at2e79bfdztVDS5lvhOdsgaE=
-cloud.google.com/go/monitoring v1.24.3/go.mod h1:nYP6W0tm3N9H/bOw8am7t62YTzZY+zUeQ+Bi6+2eonI=
-cloud.google.com/go/storage v1.61.3 h1:VS//ZfBuPGDvakfD9xyPW1RGF1Vy3BWUoVZXgW1KMOg=
-cloud.google.com/go/storage v1.61.3/go.mod h1:JtqK8BBB7TWv0HVGHubtUdzYYrakOQIsMLffZ2Z/HWk=
-cloud.google.com/go/trace v1.11.7 h1:kDNDX8JkaAG3R2nq1lIdkb7FCSi1rCmsEtKVsty7p+U=
-cloud.google.com/go/trace v1.11.7/go.mod h1:TNn9d5V3fQVf6s4SCveVMIBS2LJUqo73GACmq/Tky0s=
-firebase.google.com/go/v4 v4.19.0 h1:f5NMlC2YHFsncz00c2+ecBr+ZYlRMhKIhj1z8Iz0lD8=
-firebase.google.com/go/v4 v4.19.0/go.mod h1:P7UfBpzc8+Z3MckX79+zsWzKVfpGryr6HLbAe7gCWfs=
+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.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.31.0 h1:DHa2U07rk8syqvCge0QIGMCE1WxGj9njT44GH7zNJLQ=
-github.com/GoogleCloudPlatform/opentelemetry-operations-go/detectors/gcp v1.31.0/go.mod h1:P4WPRUkOhJC13W//jWpyfJNDAIpvRbAUIYLX/4jtlE0=
-github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/metric v0.55.0 h1:UnDZ/zFfG1JhH/DqxIZYU/1CUAlTUScoXD/LcM2Ykk8=
-github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/metric v0.55.0/go.mod h1:IA1C1U7jO/ENqm/vhi7V9YYpBsp+IMyqNrEN94N7tVc=
-github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/cloudmock v0.55.0 h1:7t/qx5Ost0s0wbA/VDrByOooURhp+ikYwv20i9Y07TQ=
-github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/cloudmock v0.55.0/go.mod h1:vB2GH9GAYYJTO3mEn8oYwzEdhlayZIdQz6zdzgUIRvA=
-github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/resourcemapping v0.55.0 h1:0s6TxfCu2KHkkZPnBfsQ2y5qia0jl3MMrmBhu3nCOYk=
-github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/resourcemapping v0.55.0/go.mod h1:Mf6O40IAyB9zR/1J8nGDDPirZQQPbYJni8Yisy7NTMc=
+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/go-jose/go-jose/v4 v4.1.3 h1:CVLmWDhDVRa6Mi/IgCgaopNosCaHz7zrMeF9MlZRkrs=
-github.com/go-jose/go-jose/v4 v4.1.3/go.mod h1:x4oUasVrzR7071A4TnHLGSPpNOm2a21K9Kf04k1rs08=
+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.14 h1:yh8ncqsbUY4shRD5dA6RlzjJaT4hi3kII+zYw8wmLb8=
-github.com/googleapis/enterprise-certificate-proxy v0.3.14/go.mod h1:vqVt9yG9480NtzREnTlmGSBmFrA+bzb0yl0TxoBQXOg=
-github.com/googleapis/gax-go/v2 v2.18.0 h1:jxP5Uuo3bxm3M6gGtV94P4lliVetoCB4Wk2x8QA86LI=
-github.com/googleapis/gax-go/v2 v2.18.0/go.mod h1:uSzZN4a356eRG985CzJ3WfbFSpqkLTjsnhWGJR6EwrE=
+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=
@@ -108,20 +108,20 @@ github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsI
 github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
 github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
 github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
-github.com/jackc/pgx/v5 v5.8.0 h1:TYPDoleBBme0xGSAX3/+NujXXtpZn9HBONkQC7IEZSo=
-github.com/jackc/pgx/v5 v5.8.0/go.mod h1:QVeDInX2m9VyzvNeiCJVjCkNFqzsNb43204HshNSZKw=
+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.34 h1:3NtcvcUnFBPsuRcno8pUtupspG/GM+9nZ88zgJcp6Zk=
-github.com/mattn/go-sqlite3 v1.14.34/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
+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.67.5 h1:pIgK94WWlQt1WLwAC5j2ynLaBRDiinoAb86HZHTUGI4=
-github.com/prometheus/common v0.67.5/go.mod h1:SjE/0MzDEEAyrdr5Gqc6G+sXI67maCxzaT3A2+HqjUw=
-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.6.0 h1:l+DolpxNWYgruGQVV0xsfeya3CsC7m8iBzDnMpsbLuo=
-github.com/spiffe/go-spiffe/v2 v2.6.0/go.mod h1:gm2SeUoMZEtpnzPNs2Csc0D/gX33k1xIx7lEzqblHEs=
+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=
@@ -165,24 +165,26 @@ github.com/xrash/smetrics v0.0.0-20250705151800-55b8f293f342/go.mod h1:Ohn+xnUBi
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
 go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
 go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
-go.opentelemetry.io/contrib/detectors/gcp v1.42.0 h1:kpt2PEJuOuqYkPcktfJqWWDjTEd/FNgrxcniL7kQrXQ=
-go.opentelemetry.io/contrib/detectors/gcp v1.42.0/go.mod h1:W9zQ439utxymRrXsUOzZbFX4JhLxXU4+ZnCt8GG7yA8=
-go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.67.0 h1:yI1/OhfEPy7J9eoa6Sj051C7n5dvpj0QX8g4sRchg04=
-go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.67.0/go.mod h1:NoUCKYWK+3ecatC4HjkRktREheMeEtrXoQxrqYFeHSc=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0 h1:OyrsyzuttWTSur2qN/Lm0m2a8yqyIjUVBZcxFPuXq2o=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0/go.mod h1:C2NGBr+kAB4bk3xtMXfZ94gqFDtg/GkI7e9zqGh5Beg=
-go.opentelemetry.io/otel v1.42.0 h1:lSQGzTgVR3+sgJDAU/7/ZMjN9Z+vUip7leaqBKy4sho=
-go.opentelemetry.io/otel v1.42.0/go.mod h1:lJNsdRMxCUIWuMlVJWzecSMuNjE7dOYyWlqOXWkdqCc=
-go.opentelemetry.io/otel/exporters/stdout/stdoutmetric v1.40.0 h1:ZrPRak/kS4xI3AVXy8F7pipuDXmDsrO8Lg+yQjBLjw0=
-go.opentelemetry.io/otel/exporters/stdout/stdoutmetric v1.40.0/go.mod h1:3y6kQCWztq6hyW8Z9YxQDDm0Je9AJoFar2G0yDcmhRk=
-go.opentelemetry.io/otel/metric v1.42.0 h1:2jXG+3oZLNXEPfNmnpxKDeZsFI5o4J+nz6xUlaFdF/4=
-go.opentelemetry.io/otel/metric v1.42.0/go.mod h1:RlUN/7vTU7Ao/diDkEpQpnz3/92J9ko05BIwxYa2SSI=
-go.opentelemetry.io/otel/sdk v1.42.0 h1:LyC8+jqk6UJwdrI/8VydAq/hvkFKNHZVIWuslJXYsDo=
-go.opentelemetry.io/otel/sdk v1.42.0/go.mod h1:rGHCAxd9DAph0joO4W6OPwxjNTYWghRWmkHuGbayMts=
-go.opentelemetry.io/otel/sdk/metric v1.42.0 h1:D/1QR46Clz6ajyZ3G8SgNlTJKBdGp84q9RKCAZ3YGuA=
-go.opentelemetry.io/otel/sdk/metric v1.42.0/go.mod h1:Ua6AAlDKdZ7tdvaQKfSmnFTdHx37+J4ba8MwVCYM5hc=
-go.opentelemetry.io/otel/trace v1.42.0 h1:OUCgIPt+mzOnaUTpOQcBiM/PLQ/Op7oq6g4LenLmOYY=
-go.opentelemetry.io/otel/trace v1.42.0/go.mod h1:f3K9S+IFqnumBkKhRJMeaZeNk9epyhnCmQh/EysQCdc=
+go.opentelemetry.io/contrib/detectors/gcp v1.44.0 h1:NmLfL734pJhM0JKaYd2Y28+nY9dPRWYAAbxhRCrKXPw=
+go.opentelemetry.io/contrib/detectors/gcp v1.44.0/go.mod h1:tNAsgd8avTGke1+MndXlU5Cru4PQ9Ai/cCNWQv/ZJ/s=
+go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.69.0 h1:2yEATaop1/a1I4psnSLgWVPLWwCzkqWakgJy7xTDVy0=
+go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.69.0/go.mod h1:D7J12YRapIekYyPWgGPlA/23pRmpSEZC5xJC/TTLI9U=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0 h1:8tvICD4vSTOOsNrsI4Ljf6C+6UKvpTEH5XY3JMoyPoo=
+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.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=
+go.opentelemetry.io/otel/metric/x v0.66.0/go.mod h1:d1+BDj9t96do0/1LoU1ayfCv79ZgNE41qbhBvnMOBZk=
+go.opentelemetry.io/otel/sdk v1.44.0 h1:nHYwb9lK+fJPU/dnT6s7W7Z8itMWyqrnVfbheVYrZ58=
+go.opentelemetry.io/otel/sdk v1.44.0/go.mod h1:Osuydd3Se74nqjAKxid74N5eC+jfEqfTegHRnq58oK0=
+go.opentelemetry.io/otel/sdk/metric v1.44.0 h1:3LlKgI+VjbVsjNRFZJZAJ30WjXC5VkNRks6si09iEfI=
+go.opentelemetry.io/otel/sdk/metric v1.44.0/go.mod h1:5B5pMARnXxKhltooO4xUuCBorl65a4EpnTalObqOigA=
+go.opentelemetry.io/otel/trace v1.44.0 h1:jxF5CsGYCe74MCRx2X4g7WsY/VBKRqqpNvXlX/6gtIk=
+go.opentelemetry.io/otel/trace v1.44.0/go.mod h1:oLl1jrMQAVo6v3GAggN+1VH9VIz9iUSvW53sW1Q8PIE=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
 go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
 go.yaml.in/yaml/v2 v2.4.4 h1:tuyd0P+2Ont/d6e2rl3be67goVK4R6deVxCUX5vyPaQ=
@@ -193,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.49.0 h1:+Ng2ULVvLHnJ/ZFEq4KdcDd/cfjrrjjNSXNzxg0Y4U4=
-golang.org/x/crypto v0.49.0/go.mod h1:ErX4dUh2UM+CFYiXZRTcMpEcN8b/1gxEuv3nODoYtCA=
+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=
@@ -209,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.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0=
-golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw=
+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=
@@ -220,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=
@@ -234,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.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
-golang.org/x/sys v0.42.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=
@@ -245,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.41.0 h1:QCgPso/Q3RTJx2Th4bDLqML4W6iJiaXFq2/ftQF13YU=
-golang.org/x/term v0.41.0/go.mod h1:3pfBgksrReYfZ5lvYM0kSO0LIkAl4Yl2bXOkKP7Ec2A=
+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=
@@ -258,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.35.0 h1:JOVx6vVDFokkpaq1AEptVzLTpDe9KGpj5tR4/X+ybL8=
-golang.org/x/text v0.35.0/go.mod h1:khi/HExzZJ2pGnjenulevKNX1W67CUy0AsXcNubPGCA=
+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=
@@ -270,20 +272,20 @@ golang.org/x/tools v0.13.0/go.mod h1:HvlwmtVNQAhOuCjW7xxvovg8wbNq7LwfXh/k7wXUl58
 golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
-gonum.org/v1/gonum v0.16.0 h1:5+ul4Swaf3ESvrOnidPp4GZbzf0mxVQpDCYUQE7OJfk=
-gonum.org/v1/gonum v0.16.0/go.mod h1:fef3am4MQ93R2HHpKnLk4/Tbh/s0+wqD5nfa6Pnwy4E=
-google.golang.org/api v0.271.0 h1:cIPN4qcUc61jlh7oXu6pwOQqbJW2GqYh5PS6rB2C/JY=
-google.golang.org/api v0.271.0/go.mod h1:CGT29bhwkbF+i11qkRUJb2KMKqcJ1hdFceEIRd9u64Q=
+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.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-20260311181403-84a4fc48630c h1:ZhFDeBMmFc/4g8/GwxnJ4rzB3O4GwQVNr+8Mh7Y5z4g=
-google.golang.org/genproto v0.0.0-20260311181403-84a4fc48630c/go.mod h1:hf4r/rBuzaTkLUWRO03771Xvcs6P5hwdQK3UUEJjqo0=
-google.golang.org/genproto/googleapis/api v0.0.0-20260311181403-84a4fc48630c h1:OyQPd6I3pN/9gDxz6L13kYGJgqkpdrAohJRBeXyxlgI=
-google.golang.org/genproto/googleapis/api v0.0.0-20260311181403-84a4fc48630c/go.mod h1:X2gu9Qwng7Nn009s/r3RUxqkzQNqOrAy79bluY7ojIg=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260311181403-84a4fc48630c h1:xgCzyF2LFIO/0X2UAoVRiXKU5Xg6VjToG4i2/ecSswk=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260311181403-84a4fc48630c/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
-google.golang.org/grpc v1.79.2 h1:fRMD94s2tITpyJGtBBn7MkMseNpOZU8ZxgC3MMBaXRU=
-google.golang.org/grpc v1.79.2/go.mod h1:KmT0Kjez+0dde/v2j9vzwoAScgEPx/Bw1CYChhHLrHQ=
+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=

mail/format.go

@@ -1,80 +1,29 @@
-package server
+package mail
 
 import (
 	_ "embed" // required by go:embed
 	"encoding/json"
 	"fmt"
 	"mime"
-	"net"
-	"net/smtp"
 	"strings"
-	"sync"
 	"time"
 
-	"heckel.io/ntfy/v2/log"
 	"heckel.io/ntfy/v2/model"
 	"heckel.io/ntfy/v2/util"
 )
 
-type mailer interface {
-	Send(v *visitor, m *model.Message, to string) error
-	Counts() (total int64, success int64, failure int64)
-}
+var (
+	//go:embed "mailer_emoji_map.json"
+	emojisJSON string
 
-type smtpSender struct {
-	config  *Config
-	success int64
-	failure int64
-	mu      sync.Mutex
-}
+	// emojiMap maps ntfy tag names to emoji, parsed once from the embedded JSON in init
+	emojiMap map[string]string
+)
 
-func (s *smtpSender) Send(v *visitor, m *model.Message, to string) error {
-	return s.withCount(v, m, func() error {
-		host, _, err := net.SplitHostPort(s.config.SMTPSenderAddr)
-		if err != nil {
-			return err
-		}
-		message, err := formatMail(s.config.BaseURL, v.ip.String(), s.config.SMTPSenderFrom, to, m)
-		if err != nil {
-			return err
-		}
-		var auth smtp.Auth
-		if s.config.SMTPSenderUser != "" {
-			auth = smtp.PlainAuth("", s.config.SMTPSenderUser, s.config.SMTPSenderPass, host)
-		}
-		ev := logvm(v, m).
-			Tag(tagEmail).
-			Fields(log.Context{
-				"email_via":  s.config.SMTPSenderAddr,
-				"email_user": s.config.SMTPSenderUser,
-				"email_to":   to,
-			})
-		if ev.IsTrace() {
-			ev.Field("email_body", message).Trace("Sending email")
-		} else if ev.IsDebug() {
-			ev.Debug("Sending email")
-		}
-		return smtp.SendMail(s.config.SMTPSenderAddr, auth, s.config.SMTPSenderFrom, []string{to}, []byte(message))
-	})
-}
-
-func (s *smtpSender) Counts() (total int64, success int64, failure int64) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	return s.success + s.failure, s.success, s.failure
-}
-
-func (s *smtpSender) withCount(v *visitor, m *model.Message, fn func() error) error {
-	err := fn()
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	if err != nil {
-		logvm(v, m).Err(err).Debug("Sending mail failed")
-		s.failure++
-	} else {
-		s.success++
+func init() {
+	if err := json.Unmarshal([]byte(emojisJSON), &emojiMap); err != nil {
+		panic("mail: invalid embedded emoji map: " + err.Error())
 	}
-	return err
 }
 
 func formatMail(baseURL, senderIP, from, to string, m *model.Message) (string, error) {
@@ -87,10 +36,7 @@ func formatMail(baseURL, senderIP, from, to string, m *model.Message) (string, e
 	message := m.Message
 	trailer := ""
 	if len(m.Tags) > 0 {
-		emojis, tags, err := toEmojis(m.Tags)
-		if err != nil {
-			return "", err
-		}
+		emojis, tags := toEmojis(m.Tags)
 		if len(emojis) > 0 {
 			subject = strings.Join(emojis, " ") + " " + subject
 		}
@@ -135,16 +81,7 @@ This message was sent by {ip} at {time} via {topicURL}`
 	return body, nil
 }
 
-var (
-	//go:embed "mailer_emoji_map.json"
-	emojisJSON string
-)
-
-func toEmojis(tags []string) (emojisOut []string, tagsOut []string, err error) {
-	var emojiMap map[string]string
-	if err = json.Unmarshal([]byte(emojisJSON), &emojiMap); err != nil {
-		return nil, nil, err
-	}
+func toEmojis(tags []string) (emojisOut []string, tagsOut []string) {
 	tagsOut = make([]string, 0)
 	emojisOut = make([]string, 0)
 	for _, t := range tags {

mail/format_test.go

@@ -1,4 +1,4 @@
-package server
+package mail
 
 import (
 	"testing"

mail/sender.go

@@ -0,0 +1,140 @@
+package mail
+
+import (
+	"fmt"
+	"mime"
+	"net"
+	"net/smtp"
+	"strings"
+	"sync"
+	"time"
+
+	"heckel.io/ntfy/v2/log"
+	"heckel.io/ntfy/v2/model"
+)
+
+const (
+	tagMail = "mail"
+
+	emailVerificationSubject = "Verify your email for ntfy"
+	passwordResetSubject     = "Reset your ntfy password"
+)
+
+// Config holds the SMTP configuration for the mail sender
+type Config struct {
+	BaseURL  string // ntfy base URL, used to build topic URLs in notification emails
+	SMTPAddr string // SMTP server address (host:port)
+	SMTPUser string // SMTP auth username
+	SMTPPass string // SMTP auth password
+	From     string // Sender email address
+}
+
+// Sender sends all of ntfy's outgoing email: notification emails (the email-on-publish feature)
+// as well as the magic-link emails for email verification and password reset. realSender is the
+// SMTP-backed implementation; tests inject a fake.
+type Sender interface {
+	SendNotification(to string, m *model.Message, senderIP string) error
+	NotificationCounts() (total int64, success int64, failure int64)
+	SendEmailVerification(to, link string) error
+	SendPasswordReset(to, link string) error
+}
+
+// realSender is the SMTP-backed implementation of Sender. Pending verification/reset state lives
+// in the database (see user.Manager), not in this struct.
+type realSender struct {
+	config  *Config
+	success int64
+	failure int64
+	mu      sync.Mutex
+}
+
+// NewSender creates a new mail Sender with the given SMTP config
+func NewSender(config *Config) Sender {
+	return &realSender{config: config}
+}
+
+// SendNotification formats a ntfy message into a notification email and sends it via SMTP. It
+// tracks success/failure counts, exposed via Counts (used for the server stats).
+func (s *realSender) SendNotification(to string, m *model.Message, senderIP string) error {
+	message, err := formatMail(s.config.BaseURL, senderIP, s.config.From, to, m)
+	if err != nil {
+		s.count(false)
+		return err
+	}
+	log.Tag(tagMail).Field("email_to", to).Debug("Sending notification email")
+	err = s.sendRaw(to, []byte(message))
+	s.count(err == nil)
+	return err
+}
+
+// NotificationCounts returns the number of notification emails sent, broken down into total, success and failure
+func (s *realSender) NotificationCounts() (total int64, success int64, failure int64) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.success + s.failure, s.success, s.failure
+}
+
+// SendEmailVerification sends an email containing a magic link to verify ownership of the
+// recipient address. The link carries a one-time token validated against the database.
+func (s *realSender) SendEmailVerification(to, link string) error {
+	body := fmt.Sprintf(`Click the link below to verify this email address for your ntfy account:
+
+%s
+
+This link expires in 24 hours. If you did not request this, you can safely ignore this email.`, link)
+	return s.send(to, emailVerificationSubject, body)
+}
+
+// SendPasswordReset sends an email containing a magic link to set a new password. The link
+// carries a one-time token validated against the database.
+func (s *realSender) SendPasswordReset(to, link string) error {
+	body := fmt.Sprintf(`Click the link below to set a new password for your ntfy account:
+
+%s
+
+This link expires in 1 hour. If you did not request this, you can safely ignore this email -- your password will not change.`, link)
+	return s.send(to, passwordResetSubject, body)
+}
+
+// send sends a plain text email via SMTP
+func (s *realSender) send(to, subject, body string) error {
+	date := time.Now().UTC().Format(time.RFC1123Z)
+	encodedSubject := mime.BEncoding.Encode("utf-8", subject)
+	message := `From: ntfy <{from}>
+To: {to}
+Date: {date}
+Subject: {subject}
+Content-Type: text/plain; charset="utf-8"
+
+{body}`
+	message = strings.ReplaceAll(message, "{from}", s.config.From)
+	message = strings.ReplaceAll(message, "{to}", to)
+	message = strings.ReplaceAll(message, "{date}", date)
+	message = strings.ReplaceAll(message, "{subject}", encodedSubject)
+	message = strings.ReplaceAll(message, "{body}", body)
+	log.Tag(tagMail).Field("email_to", to).Debug("Sending email")
+	return s.sendRaw(to, []byte(message))
+}
+
+// sendRaw sends a raw email message via SMTP
+func (s *realSender) sendRaw(to string, message []byte) error {
+	host, _, err := net.SplitHostPort(s.config.SMTPAddr)
+	if err != nil {
+		return err
+	}
+	var auth smtp.Auth
+	if s.config.SMTPUser != "" {
+		auth = smtp.PlainAuth("", s.config.SMTPUser, s.config.SMTPPass, host)
+	}
+	return smtp.SendMail(s.config.SMTPAddr, auth, s.config.From, []string{to}, message)
+}
+
+func (s *realSender) count(ok bool) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if ok {
+		s.success++
+	} else {
+		s.failure++
+	}
+}

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")
@@ -24,7 +25,6 @@ var errNoRows = errors.New("no rows found")
 // queries holds the database-specific SQL queries
 type queries struct {
 	insertMessage                    string
-	deleteMessage                    string
 	selectScheduledMessageIDsBySeqID string
 	deleteScheduledBySequenceID      string
 	updateMessagesForTopicExpiry     string
@@ -35,14 +35,15 @@ type queries struct {
 	selectMessagesSinceIDScheduled   string
 	selectMessagesLatest             string
 	selectMessagesDue                string
-	selectMessagesExpired            string
+	selectMessagesDueForUpdate       string // Postgres-only: claims due rows via FOR UPDATE SKIP LOCKED; empty for SQLite/mem
+	deleteExpiredMessages            string
 	updateMessagePublished           string
 	selectMessagesCount              string
 	selectTopics                     string
-	updateAttachmentDeleted          string
-	selectAttachmentsExpired         string
+	markExpiredAttachmentsDeleted    string
 	selectAttachmentsSizeBySender    string
 	selectAttachmentsSizeByUserID    string
+	selectAttachmentsWithSizes       string
 	selectStats                      string
 	updateStats                      string
 	updateMessageTime                string
@@ -238,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
@@ -245,25 +255,42 @@ func (c *Cache) MessagesDue() ([]*model.Message, error) {
 	return readMessages(rows)
 }
 
-// MessagesExpired returns a list of IDs for messages that have expired (should be deleted)
-func (c *Cache) MessagesExpired() ([]string, error) {
-	rows, err := c.db.Query(c.queries.selectMessagesExpired, time.Now().Unix())
+// 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 rows.Close()
-	ids := make([]string, 0)
-	for rows.Next() {
-		var id string
-		if err := rows.Scan(&id); err != nil {
-			return nil, err
-		}
-		ids = append(ids, id)
-	}
-	if err := rows.Err(); err != nil {
+	defer tx.Rollback()
+	rows, err := tx.Query(c.queries.selectMessagesDueForUpdate, time.Now().Unix())
+	if err != nil {
 		return nil, err
 	}
-	return ids, nil
+	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) {
+	c.maybeLock()
+	defer c.maybeUnlock()
+	result, err := c.db.Exec(c.queries.deleteExpiredMessages, time.Now().Unix(), limit)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
 }
 
 // Message returns the message with the given ID, or ErrMessageNotFound if not found
@@ -272,10 +299,10 @@ func (c *Cache) Message(id string) (*model.Message, error) {
 	if err != nil {
 		return nil, err
 	}
+	defer rows.Close()
 	if !rows.Next() {
 		return nil, model.ErrMessageNotFound
 	}
-	defer rows.Close()
 	return readMessage(rows)
 }
 
@@ -319,32 +346,7 @@ func (c *Cache) Topics() ([]string, error) {
 		return nil, err
 	}
 	defer rows.Close()
-	topics := make([]string, 0)
-	for rows.Next() {
-		var id string
-		if err := rows.Scan(&id); err != nil {
-			return nil, err
-		}
-		topics = append(topics, id)
-	}
-	if err := rows.Err(); err != nil {
-		return nil, err
-	}
-	return topics, nil
-}
-
-// DeleteMessages deletes the messages with the given IDs
-func (c *Cache) DeleteMessages(ids ...string) error {
-	c.maybeLock()
-	defer c.maybeUnlock()
-	return db.ExecTx(c.db, func(tx *sql.Tx) error {
-		for _, id := range ids {
-			if _, err := tx.Exec(c.queries.deleteMessage, id); err != nil {
-				return err
-			}
-		}
-		return nil
-	})
+	return readStrings(rows)
 }
 
 // DeleteScheduledBySequenceID deletes unpublished (scheduled) messages with the given topic and sequence ID.
@@ -358,15 +360,8 @@ func (c *Cache) DeleteScheduledBySequenceID(topic, sequenceID string) ([]string,
 			return nil, err
 		}
 		defer rows.Close()
-		ids := make([]string, 0)
-		for rows.Next() {
-			var id string
-			if err := rows.Scan(&id); err != nil {
-				return nil, err
-			}
-			ids = append(ids, id)
-		}
-		if err := rows.Err(); err != nil {
+		ids, err := readStrings(rows)
+		if err != nil {
 			return nil, err
 		}
 		rows.Close() // Close rows before executing delete in same transaction
@@ -391,39 +386,16 @@ func (c *Cache) ExpireMessages(topics ...string) error {
 	})
 }
 
-// AttachmentsExpired returns message IDs with expired attachments that have not been deleted
-func (c *Cache) AttachmentsExpired() ([]string, error) {
-	rows, err := c.db.Query(c.queries.selectAttachmentsExpired, time.Now().Unix())
-	if err != nil {
-		return nil, err
-	}
-	defer rows.Close()
-	ids := make([]string, 0)
-	for rows.Next() {
-		var id string
-		if err := rows.Scan(&id); err != nil {
-			return nil, err
-		}
-		ids = append(ids, id)
-	}
-	if err := rows.Err(); err != nil {
-		return nil, err
-	}
-	return ids, nil
-}
-
-// MarkAttachmentsDeleted marks the attachments for the given message IDs as deleted
-func (c *Cache) MarkAttachmentsDeleted(ids ...string) error {
+// MarkExpiredAttachmentsDeleted marks up to `limit` expired attachments as deleted in a single
+// query and returns the number of updated rows.
+func (c *Cache) MarkExpiredAttachmentsDeleted(limit int) (int64, error) {
 	c.maybeLock()
 	defer c.maybeUnlock()
-	return db.ExecTx(c.db, func(tx *sql.Tx) error {
-		for _, id := range ids {
-			if _, err := tx.Exec(c.queries.updateAttachmentDeleted, id); err != nil {
-				return err
-			}
-		}
-		return nil
-	})
+	result, err := c.db.Exec(c.queries.markExpiredAttachmentsDeleted, time.Now().Unix(), limit)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
 }
 
 // AttachmentBytesUsedBySender returns the total size of active attachments sent by the given sender
@@ -444,6 +416,30 @@ func (c *Cache) AttachmentBytesUsedByUser(userID string) (int64, error) {
 	return c.readAttachmentBytesUsed(rows)
 }
 
+// AttachmentsWithSizes returns a map of message ID to attachment size for all active
+// (non-expired, non-deleted) attachments. This is used to hydrate the attachment store's
+// size tracking on startup and during periodic sync.
+func (c *Cache) AttachmentsWithSizes() (map[string]int64, error) {
+	rows, err := c.db.ReadOnly().Query(c.queries.selectAttachmentsWithSizes, time.Now().Unix())
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	attachments := make(map[string]int64)
+	for rows.Next() {
+		var id string
+		var size int64
+		if err := rows.Scan(&id, &size); err != nil {
+			return nil, err
+		}
+		attachments[id] = size
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return attachments, nil
+}
+
 func (c *Cache) readAttachmentBytesUsed(rows *sql.Rows) (int64, error) {
 	defer rows.Close()
 	var size int64
@@ -590,3 +586,18 @@ func readMessage(rows *sql.Rows) (*model.Message, error) {
 		Encoding:    encoding,
 	}, nil
 }
+
+func readStrings(rows *sql.Rows) ([]string, error) {
+	strs := make([]string, 0)
+	for rows.Next() {
+		var s string
+		if err := rows.Scan(&s); err != nil {
+			return nil, err
+		}
+		strs = append(strs, s)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return strs, nil
+}

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
@@ -12,7 +13,6 @@ const (
 		INSERT INTO message (mid, sequence_id, time, event, expires, topic, message, title, priority, tags, click, icon, actions, attachment_name, attachment_type, attachment_size, attachment_expires, attachment_url, attachment_deleted, sender, user_id, content_type, encoding, published)
 		VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20, $21, $22, $23, $24)
 	`
-	postgresDeleteMessageQuery                    = `DELETE FROM message WHERE mid = $1`
 	postgresSelectScheduledMessageIDsBySeqIDQuery = `SELECT mid FROM message WHERE topic = $1 AND sequence_id = $2 AND published = FALSE`
 	postgresDeleteScheduledBySequenceIDQuery      = `DELETE FROM message WHERE topic = $1 AND sequence_id = $2 AND published = FALSE`
 	postgresUpdateMessagesForTopicExpiryQuery     = `UPDATE message SET expires = $1 WHERE topic = $2`
@@ -61,15 +61,22 @@ const (
 		WHERE time <= $1 AND published = FALSE
 		ORDER BY time, id
 	`
-	postgresSelectMessagesExpiredQuery  = `SELECT mid FROM message WHERE expires <= $1 AND published = TRUE`
+	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`
 
-	postgresUpdateAttachmentDeletedQuery       = `UPDATE message SET attachment_deleted = TRUE WHERE mid = $1`
-	postgresSelectAttachmentsExpiredQuery      = `SELECT mid FROM message WHERE attachment_expires > 0 AND attachment_expires <= $1 AND attachment_deleted = FALSE`
+	postgresDeleteExpiredMessagesQuery         = `DELETE FROM message WHERE mid IN (SELECT mid FROM message WHERE expires <= $1 AND published = TRUE LIMIT $2)`
+	postgresMarkExpiredAttachmentsDeletedQuery = `UPDATE message SET attachment_deleted = TRUE WHERE mid IN (SELECT mid FROM message WHERE attachment_expires > 0 AND attachment_expires <= $1 AND attachment_deleted = FALSE LIMIT $2)`
 	postgresSelectAttachmentsSizeBySenderQuery = `SELECT COALESCE(SUM(attachment_size), 0) FROM message WHERE user_id = '' AND sender = $1 AND attachment_expires >= $2`
 	postgresSelectAttachmentsSizeByUserIDQuery = `SELECT COALESCE(SUM(attachment_size), 0) FROM message WHERE user_id = $1 AND attachment_expires >= $2`
+	postgresSelectAttachmentsWithSizesQuery    = `SELECT mid, attachment_size FROM message WHERE attachment_expires > $1 AND attachment_deleted = FALSE`
 
 	postgresSelectStatsQuery       = `SELECT value FROM message_stats WHERE key = 'messages'`
 	postgresUpdateStatsQuery       = `UPDATE message_stats SET value = $1 WHERE key = 'messages'`
@@ -78,7 +85,6 @@ const (
 
 var postgresQueries = queries{
 	insertMessage:                    postgresInsertMessageQuery,
-	deleteMessage:                    postgresDeleteMessageQuery,
 	selectScheduledMessageIDsBySeqID: postgresSelectScheduledMessageIDsBySeqIDQuery,
 	deleteScheduledBySequenceID:      postgresDeleteScheduledBySequenceIDQuery,
 	updateMessagesForTopicExpiry:     postgresUpdateMessagesForTopicExpiryQuery,
@@ -89,14 +95,15 @@ var postgresQueries = queries{
 	selectMessagesSinceIDScheduled:   postgresSelectMessagesSinceIDIncludeScheduledQuery,
 	selectMessagesLatest:             postgresSelectMessagesLatestQuery,
 	selectMessagesDue:                postgresSelectMessagesDueQuery,
-	selectMessagesExpired:            postgresSelectMessagesExpiredQuery,
+	selectMessagesDueForUpdate:       postgresSelectMessagesDueForUpdateQuery,
+	deleteExpiredMessages:            postgresDeleteExpiredMessagesQuery,
 	updateMessagePublished:           postgresUpdateMessagePublishedQuery,
 	selectMessagesCount:              postgresSelectMessagesCountQuery,
 	selectTopics:                     postgresSelectTopicsQuery,
-	updateAttachmentDeleted:          postgresUpdateAttachmentDeletedQuery,
-	selectAttachmentsExpired:         postgresSelectAttachmentsExpiredQuery,
+	markExpiredAttachmentsDeleted:    postgresMarkExpiredAttachmentsDeletedQuery,
 	selectAttachmentsSizeBySender:    postgresSelectAttachmentsSizeBySenderQuery,
 	selectAttachmentsSizeByUserID:    postgresSelectAttachmentsSizeByUserIDQuery,
+	selectAttachmentsWithSizes:       postgresSelectAttachmentsWithSizesQuery,
 	selectStats:                      postgresSelectStatsQuery,
 	updateStats:                      postgresUpdateStatsQuery,
 	updateMessageTime:                postgresUpdateMessageTimeQuery,
@@ -104,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,15 +1,13 @@
 package message
 
 import (
-	"database/sql"
-	"fmt"
-
-	"heckel.io/ntfy/v2/db"
+	"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,
@@ -41,6 +39,7 @@ const (
 		CREATE INDEX IF NOT EXISTS idx_message_sequence_id ON message (sequence_id);
 		CREATE INDEX IF NOT EXISTS idx_message_topic_published_time ON message (topic, published, time, id);
 		CREATE INDEX IF NOT EXISTS idx_message_published_expires ON message (published, expires);
+		CREATE INDEX IF NOT EXISTS idx_message_attachment_expires ON message (attachment_expires) WHERE attachment_deleted = FALSE;
 		CREATE INDEX IF NOT EXISTS idx_message_sender_attachment_expires ON message (sender, attachment_expires) WHERE user_id = '';
 		CREATE INDEX IF NOT EXISTS idx_message_user_id_attachment_expires ON message (user_id, attachment_expires);
 		CREATE TABLE IF NOT EXISTS message_stats (
@@ -48,38 +47,23 @@ 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
+// PostgreSQL schema migrations
 const (
-	postgresCurrentSchemaVersion     = 14
-	postgresInsertSchemaVersionQuery = `INSERT INTO schema_version (store, version) VALUES ('message', $1)`
-	postgresSelectSchemaVersionQuery = `SELECT version FROM schema_version WHERE store = 'message'`
+	// 14 -> 15
+	postgresMigrate14To15CreateIndexQuery = `
+		CREATE INDEX IF NOT EXISTS idx_message_attachment_expires ON message (attachment_expires) WHERE attachment_deleted = FALSE;
+	`
 )
 
-func setupPostgres(db *sql.DB) error {
-	var schemaVersion int
-	if err := db.QueryRow(postgresSelectSchemaVersionQuery).Scan(&schemaVersion); err != nil {
-		return setupNewPostgresDB(db)
-	} else if schemaVersion > postgresCurrentSchemaVersion {
-		return fmt.Errorf("unexpected schema version: version %d is higher than current version %d", schemaVersion, postgresCurrentSchemaVersion)
-	}
-	return nil
-}
+var (
+	postgresCreateTables = schema.AsMigrateFunc(postgresCreateTablesQuery)
 
-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
-	})
-}
+	// 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),
+	}
+)

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"
 )
 
@@ -18,7 +19,6 @@ const (
 		INSERT INTO messages (mid, sequence_id, time, event, expires, topic, message, title, priority, tags, click, icon, actions, attachment_name, attachment_type, attachment_size, attachment_expires, attachment_url, attachment_deleted, sender, user, content_type, encoding, published)
 		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 	`
-	sqliteDeleteMessageQuery                    = `DELETE FROM messages WHERE mid = ?`
 	sqliteSelectScheduledMessageIDsBySeqIDQuery = `SELECT mid FROM messages WHERE topic = ? AND sequence_id = ? AND published = 0`
 	sqliteDeleteScheduledBySequenceIDQuery      = `DELETE FROM messages WHERE topic = ? AND sequence_id = ? AND published = 0`
 	sqliteUpdateMessagesForTopicExpiryQuery     = `UPDATE messages SET expires = ? WHERE topic = ?`
@@ -64,15 +64,15 @@ const (
 		WHERE time <= ? AND published = 0
 		ORDER BY time, id
 	`
-	sqliteSelectMessagesExpiredQuery  = `SELECT mid FROM messages WHERE expires <= ? AND published = 1`
 	sqliteUpdateMessagePublishedQuery = `UPDATE messages SET published = 1 WHERE mid = ?`
 	sqliteSelectMessagesCountQuery    = `SELECT COUNT(*) FROM messages`
 	sqliteSelectTopicsQuery           = `SELECT topic FROM messages GROUP BY topic`
 
-	sqliteUpdateAttachmentDeletedQuery       = `UPDATE messages SET attachment_deleted = 1 WHERE mid = ?`
-	sqliteSelectAttachmentsExpiredQuery      = `SELECT mid FROM messages WHERE attachment_expires > 0 AND attachment_expires <= ? AND attachment_deleted = 0`
+	sqliteDeleteExpiredMessagesQuery         = `DELETE FROM messages WHERE mid IN (SELECT mid FROM messages WHERE expires <= ? AND published = 1 LIMIT ?)`
+	sqliteMarkExpiredAttachmentsDeletedQuery = `UPDATE messages SET attachment_deleted = 1 WHERE mid IN (SELECT mid FROM messages WHERE attachment_expires > 0 AND attachment_expires <= ? AND attachment_deleted = 0 LIMIT ?)`
 	sqliteSelectAttachmentsSizeBySenderQuery = `SELECT IFNULL(SUM(attachment_size), 0) FROM messages WHERE user = '' AND sender = ? AND attachment_expires >= ?`
 	sqliteSelectAttachmentsSizeByUserIDQuery = `SELECT IFNULL(SUM(attachment_size), 0) FROM messages WHERE user = ? AND attachment_expires >= ?`
+	sqliteSelectAttachmentsWithSizesQuery    = `SELECT mid, attachment_size FROM messages WHERE attachment_expires > ? AND attachment_deleted = 0`
 
 	sqliteSelectStatsQuery       = `SELECT value FROM stats WHERE key = 'messages'`
 	sqliteUpdateStatsQuery       = `UPDATE stats SET value = ? WHERE key = 'messages'`
@@ -81,7 +81,6 @@ const (
 
 var sqliteQueries = queries{
 	insertMessage:                    sqliteInsertMessageQuery,
-	deleteMessage:                    sqliteDeleteMessageQuery,
 	selectScheduledMessageIDsBySeqID: sqliteSelectScheduledMessageIDsBySeqIDQuery,
 	deleteScheduledBySequenceID:      sqliteDeleteScheduledBySequenceIDQuery,
 	updateMessagesForTopicExpiry:     sqliteUpdateMessagesForTopicExpiryQuery,
@@ -92,14 +91,14 @@ var sqliteQueries = queries{
 	selectMessagesSinceIDScheduled:   sqliteSelectMessagesSinceIDIncludeScheduledQuery,
 	selectMessagesLatest:             sqliteSelectMessagesLatestQuery,
 	selectMessagesDue:                sqliteSelectMessagesDueQuery,
-	selectMessagesExpired:            sqliteSelectMessagesExpiredQuery,
+	deleteExpiredMessages:            sqliteDeleteExpiredMessagesQuery,
 	updateMessagePublished:           sqliteUpdateMessagePublishedQuery,
 	selectMessagesCount:              sqliteSelectMessagesCountQuery,
 	selectTopics:                     sqliteSelectTopicsQuery,
-	updateAttachmentDeleted:          sqliteUpdateAttachmentDeletedQuery,
-	selectAttachmentsExpired:         sqliteSelectAttachmentsExpiredQuery,
+	markExpiredAttachmentsDeleted:    sqliteMarkExpiredAttachmentsDeletedQuery,
 	selectAttachmentsSizeBySender:    sqliteSelectAttachmentsSizeBySenderQuery,
 	selectAttachmentsSizeByUserID:    sqliteSelectAttachmentsSizeByUserIDQuery,
+	selectAttachmentsWithSizes:       sqliteSelectAttachmentsWithSizesQuery,
 	selectStats:                      sqliteSelectStatsQuery,
 	updateStats:                      sqliteUpdateStatsQuery,
 	updateMessageTime:                sqliteUpdateMessageTimeQuery,
@@ -115,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          = 14
-	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,66 +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,
-	}
+	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 {
@@ -263,191 +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
-	})
-}

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()
@@ -209,7 +183,7 @@ func TestSqliteStore_Migration_From9(t *testing.T) {
 	require.True(t, rows.Next())
 	var version int
 	require.Nil(t, rows.Scan(&version))
-	require.Equal(t, 14, version)
+	require.Equal(t, 15, version)
 	require.Nil(t, rows.Close())
 
 	messages, err := s.Messages("mytopic", model.SinceAllMessages, false)
@@ -287,6 +261,6 @@ func checkSqliteSchemaVersion(t *testing.T, filename string) {
 	require.True(t, rows.Next())
 	var schemaVersion int
 	require.Nil(t, rows.Scan(&schemaVersion))
-	require.Equal(t, 14, schemaVersion)
+	require.Equal(t, 15, schemaVersion)
 	require.Nil(t, rows.Close())
 }

message/cache_test.go

@@ -1,9 +1,9 @@
 package message_test
 
 import (
+	"fmt"
 	"net/netip"
 	"path/filepath"
-	"sort"
 	"sync"
 	"testing"
 	"time"
@@ -274,9 +274,9 @@ func TestStore_Prune(t *testing.T) {
 		require.Nil(t, err)
 		require.Equal(t, 3, count)
 
-		expiredMessageIDs, err := s.MessagesExpired()
+		deleted, err := s.DeleteExpiredMessages(10)
 		require.Nil(t, err)
-		require.Nil(t, s.DeleteMessages(expiredMessageIDs...))
+		require.Equal(t, int64(2), deleted)
 
 		count, err = s.MessagesCount()
 		require.Nil(t, err)
@@ -414,10 +414,9 @@ func TestStore_AttachmentsExpired(t *testing.T) {
 		}
 		require.Nil(t, s.AddMessage(m))
 
-		ids, err := s.AttachmentsExpired()
+		count, err := s.MarkExpiredAttachmentsDeleted(10)
 		require.Nil(t, err)
-		require.Equal(t, 1, len(ids))
-		require.Equal(t, "m4", ids[0])
+		require.Equal(t, int64(1), count)
 	})
 }
 
@@ -558,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
@@ -583,13 +619,9 @@ func TestStore_ExpireMessages(t *testing.T) {
 		require.Nil(t, s.ExpireMessages("topic1"))
 
 		// topic1 messages should now be expired (expires set to past)
-		expiredIDs, err := s.MessagesExpired()
+		deleted, err := s.DeleteExpiredMessages(100)
 		require.Nil(t, err)
-		require.Equal(t, 2, len(expiredIDs))
-		sort.Strings(expiredIDs)
-		expectedIDs := []string{m1.ID, m2.ID}
-		sort.Strings(expectedIDs)
-		require.Equal(t, expectedIDs, expiredIDs)
+		require.Equal(t, int64(2), deleted)
 
 		// topic2 should be unaffected
 		messages, err = s.Messages("topic2", model.SinceAllMessages, false)
@@ -629,27 +661,15 @@ func TestStore_MarkAttachmentsDeleted(t *testing.T) {
 		}
 		require.Nil(t, s.AddMessage(m2))
 
-		// Both should show as expired attachments needing cleanup
-		ids, err := s.AttachmentsExpired()
+		// Both should be marked as deleted in one batch
+		count, err := s.MarkExpiredAttachmentsDeleted(10)
 		require.Nil(t, err)
-		require.Equal(t, 2, len(ids))
-
-		// Mark msg1's attachment as deleted (file cleaned up)
-		require.Nil(t, s.MarkAttachmentsDeleted("msg1"))
-
-		// Now only msg2 should show as needing cleanup
-		ids, err = s.AttachmentsExpired()
-		require.Nil(t, err)
-		require.Equal(t, 1, len(ids))
-		require.Equal(t, "msg2", ids[0])
-
-		// Mark msg2 too
-		require.Nil(t, s.MarkAttachmentsDeleted("msg2"))
+		require.Equal(t, int64(2), count)
 
 		// No more expired attachments to clean up
-		ids, err = s.AttachmentsExpired()
+		count, err = s.MarkExpiredAttachmentsDeleted(10)
 		require.Nil(t, err)
-		require.Equal(t, 0, len(ids))
+		require.Equal(t, int64(0), count)
 
 		// Messages themselves still exist
 		messages, err := s.Messages("mytopic", model.SinceAllMessages, false)

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()
+}

mkdocs.yml

@@ -44,9 +44,11 @@ extra_javascript:
   - static/js/extra.js
   - static/js/bcrypt.js
   - static/js/config-generator.js
+  - static/js/topic-generator.js
 extra_css:
   - static/css/extra.css
   - static/css/config-generator.css
+  - static/css/topic-generator.css
 
 markdown_extensions:
   - admonition

model/model.go

@@ -19,8 +19,8 @@ const (
 	PollRequestEvent   = "poll_request"
 )
 
-// MessageIDLength is the length of a randomly generated message ID
-const MessageIDLength = 12
+// messageIDLength is the length of a randomly generated message ID
+const messageIDLength = 12
 
 // Errors for message operations
 var (
@@ -133,10 +133,20 @@ func NewAction() *Action {
 	}
 }
 
+// GenerateMessageID creates a new random message ID
+func GenerateMessageID() string {
+	return util.RandomString(messageIDLength)
+}
+
+// ValidMessageID returns true if the given string is a valid message ID
+func ValidMessageID(s string) bool {
+	return util.ValidRandomString(s, messageIDLength)
+}
+
 // NewMessage creates a new message with the current timestamp
 func NewMessage(event, topic, msg string) *Message {
 	return &Message{
-		ID:      util.RandomString(MessageIDLength),
+		ID:      GenerateMessageID(),
 		Time:    time.Now().Unix(),
 		Event:   event,
 		Topic:   topic,
@@ -173,11 +183,6 @@ func NewPollRequestMessage(topic, pollID string) *Message {
 	return m
 }
 
-// ValidMessageID returns true if the given string is a valid message ID
-func ValidMessageID(s string) bool {
-	return util.ValidRandomString(s, MessageIDLength)
-}
-
 // SinceMarker represents a point in time or message ID from which to retrieve messages
 type SinceMarker struct {
 	time time.Time

s3/client.go

@@ -0,0 +1,324 @@
+package s3
+
+import (
+	"bytes"
+	"context"
+	"crypto/md5" //nolint:gosec // MD5 is required by the S3 protocol for Content-MD5 headers
+	"crypto/tls"
+	"encoding/base64"
+	"encoding/xml"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"heckel.io/ntfy/v2/log"
+)
+
+const (
+	tagS3Client = "s3_client"
+)
+
+// Client is a minimal S3-compatible client. It supports PutObject, GetObject, DeleteObjects,
+// and ListObjectsV2 operations using AWS Signature V4 signing. The bucket and optional key prefix
+// are fixed at construction time. All operations target the same bucket and prefix.
+//
+// The following IAM policy is required for AWS S3:
+//
+//	{
+//	    "Version": "2012-10-17",
+//	    "Statement": [
+//	        {
+//	            "Effect": "Allow",
+//	            "Action": [
+//	                "s3:ListBucket",
+//	                "s3:ListBucketMultipartUploads"
+//	            ],
+//	            "Resource": "arn:aws:s3:::BUCKET_NAME"
+//	        },
+//	        {
+//	            "Effect": "Allow",
+//	            "Action": [
+//	                "s3:GetObject",
+//	                "s3:PutObject",
+//	                "s3:DeleteObject",
+//	                "s3:AbortMultipartUpload"
+//	            ],
+//	            "Resource": "arn:aws:s3:::BUCKET_NAME/*"
+//	        }
+//	    ]
+//	}
+//
+// Fields must not be modified after the Client is passed to any method or goroutine.
+type Client struct {
+	config *Config
+	http   *http.Client
+}
+
+// New creates a new S3 client from the given Config.
+func New(config *Config) *Client {
+	httpClient := config.HTTPClient
+	if httpClient == nil {
+		if config.DisableHTTP2 {
+			httpClient = newHTTP1Client()
+		} else {
+			httpClient = http.DefaultClient
+		}
+	}
+	return &Client{
+		config: config,
+		http:   httpClient,
+	}
+}
+
+// PutObject uploads body to the given key. The key is automatically prefixed with the client's
+// configured prefix.
+//
+// If untrustedLength is between 1 and 5 GB, the body is streamed directly to S3 via a
+// single PUT request without buffering. The read is limited to untrustedLength bytes;
+// any extra data in the body is ignored. If the body is shorter than claimed, the upload fails.
+//
+// Otherwise (untrustedLength <= 0 or > 5 GB), the first 5 MB are buffered to decide
+// between a simple PUT and multipart upload.
+//
+// See https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html
+// and https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html
+func (c *Client) PutObject(ctx context.Context, key string, body io.Reader, untrustedLength int64) error {
+	if untrustedLength > 0 && untrustedLength <= maxSinglePutSize {
+		// Stream directly: Content-Length is known (but untrusted). LimitReader ensures we send at most
+		// untrustedLength bytes, and any extra data in body is ignored.
+		return c.putObject(ctx, key, io.LimitReader(body, untrustedLength), untrustedLength)
+	}
+	// Buffered path: read first 5 MB to decide simple vs multipart
+	first := make([]byte, partSize)
+	n, err := io.ReadFull(body, first)
+	if errors.Is(err, io.ErrUnexpectedEOF) || err == io.EOF {
+		return c.putObject(ctx, key, bytes.NewReader(first[:n]), int64(n))
+	} else if err != nil {
+		return fmt.Errorf("error reading object %s from client: %w", key, err)
+	}
+	return c.putObjectMultipart(ctx, key, io.MultiReader(bytes.NewReader(first), body))
+}
+
+// putObject uploads a body with known size using a simple PUT with UNSIGNED-PAYLOAD.
+func (c *Client) putObject(ctx context.Context, key string, body io.Reader, size int64) error {
+	log.Tag(tagS3Client).Debug("Uploading object %s (%d bytes)", key, size)
+	req, err := http.NewRequestWithContext(ctx, http.MethodPut, c.config.ObjectURL(key), body)
+	if err != nil {
+		return fmt.Errorf("creating upload request object %s failed: %w", key, err)
+	}
+	req.ContentLength = size
+	c.signV4(req, unsignedPayload)
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return fmt.Errorf("uploading object %s failed: %w", key, err)
+	}
+	defer resp.Body.Close()
+	if !isHTTPSuccess(resp) {
+		return parseError(resp)
+	}
+	return nil
+}
+
+// GetObject downloads an object. The key is automatically prefixed with the client's configured
+// prefix. The caller must close the returned ReadCloser.
+//
+// See https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html
+func (c *Client) GetObject(ctx context.Context, key string) (io.ReadCloser, int64, error) {
+	log.Tag(tagS3Client).Debug("Fetching object %s", key)
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.config.ObjectURL(key), nil)
+	if err != nil {
+		return nil, 0, fmt.Errorf("error creating HTTP GET request for %s: %w", key, err)
+	}
+	c.signV4(req, emptyPayloadHash)
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return nil, 0, fmt.Errorf("error fetching object %s: %w", key, err)
+	} else if !isHTTPSuccess(resp) {
+		err := parseError(resp)
+		resp.Body.Close()
+		return nil, 0, err
+	}
+	return resp.Body, resp.ContentLength, nil
+}
+
+// ListObjectsV2 returns all objects under the client's configured prefix by paginating through
+// ListObjectsV2 results automatically. Keys in the returned objects have the prefix stripped,
+// so they match the keys used with PutObject/GetObject/DeleteObjects. It stops after 10,000
+// pages as a safety valve.
+//
+// See https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html
+func (c *Client) ListObjectsV2(ctx context.Context) ([]*Object, error) {
+	var all []*Object
+	var token string
+	for page := 0; page < maxPages; page++ {
+		result, err := c.listObjectsV2(ctx, token)
+		if err != nil {
+			return nil, err
+		}
+		for _, obj := range result.Contents {
+			var lastModified time.Time
+			if obj.LastModified != "" {
+				lastModified, _ = time.Parse(time.RFC3339, obj.LastModified)
+			}
+			all = append(all, &Object{
+				Key:          c.config.StripPrefix(obj.Key),
+				Size:         obj.Size,
+				LastModified: lastModified,
+			})
+		}
+		if !result.IsTruncated {
+			return all, nil
+		}
+		token = result.NextContinuationToken
+	}
+	return nil, fmt.Errorf("listing objects exceeded %d pages", maxPages)
+}
+
+// listObjectsV2 performs a single ListObjectsV2 request using the client's configured prefix.
+func (c *Client) listObjectsV2(ctx context.Context, continuationToken string) (*listObjectsV2Result, error) {
+	if continuationToken == "" {
+		log.Tag(tagS3Client).Debug("Listing remote objects")
+	} else {
+		log.Tag(tagS3Client).Debug("Listing remote objects, continuing with token '%s'", continuationToken)
+	}
+	query := url.Values{"list-type": {"2"}}
+	if prefix := c.config.ListPrefix(); prefix != "" {
+		query.Set("prefix", prefix)
+	}
+	if continuationToken != "" {
+		query.Set("continuation-token", continuationToken)
+	}
+	respBody, err := c.do(ctx, "ListObjects", http.MethodGet, c.config.BucketURL()+"?"+query.Encode(), nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	var result listObjectsV2Result
+	if err := xml.Unmarshal(respBody, &result); err != nil {
+		return nil, fmt.Errorf("failed to unmarshal list object response: %w", err)
+	}
+	return &result, nil
+}
+
+// DeleteObjects removes multiple objects in a single batch request. Keys are automatically
+// prefixed with the client's configured prefix. S3 supports up to 1000 keys per call; the
+// caller is responsible for batching if needed.
+//
+// Even when S3 returns HTTP 200, individual keys may fail. If any per-key errors are present
+// in the response, they are returned as a combined error.
+//
+// See https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html
+func (c *Client) DeleteObjects(ctx context.Context, keys []string) error {
+	// S3 DeleteObjects supports up to 1000 keys per call
+	for i := 0; i < len(keys); i += maxDeleteBatchSize {
+		end := i + maxDeleteBatchSize
+		if end > len(keys) {
+			end = len(keys)
+		}
+		if err := c.deleteObjects(ctx, keys[i:end]); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (c *Client) deleteObjects(ctx context.Context, keys []string) error {
+	log.Tag(tagS3Client).Debug("Deleting %d object(s)", len(keys))
+	req := &deleteObjectsRequest{
+		Quiet: true,
+	}
+	for _, key := range keys {
+		req.Objects = append(req.Objects, &deleteObject{Key: c.config.ObjectKey(key)})
+	}
+	body, err := xml.Marshal(req)
+	if err != nil {
+		return fmt.Errorf("error marshalling XML for deleting objects: %w", err)
+	}
+
+	// Content-MD5 is required by the S3 protocol for DeleteObjects requests.
+	md5Sum := md5.Sum(body) //nolint:gosec
+	headers := map[string]string{
+		"Content-MD5": base64.StdEncoding.EncodeToString(md5Sum[:]),
+	}
+	reqURL := c.config.BucketURL() + "?delete"
+	respBody, err := c.do(ctx, "DeleteObjects", http.MethodPost, reqURL, body, headers)
+	if err != nil {
+		return fmt.Errorf("error deleting objects: %w", err)
+	}
+
+	// S3 may return HTTP 200 with per-key errors in the response body
+	var result deleteObjectsResult
+	if err := xml.Unmarshal(respBody, &result); err != nil {
+		return nil // If we can't parse, assume success (Quiet mode returns empty body on success)
+	}
+	if len(result.Errors) > 0 {
+		var msgs []string
+		for _, e := range result.Errors {
+			msgs = append(msgs, fmt.Sprintf("%s: %s", e.Key, e.Message))
+		}
+		return fmt.Errorf("error deleting objects, partial failure: %s", strings.Join(msgs, "; "))
+	}
+	return nil
+}
+
+// do creates a signed request, executes it, reads the response body, and checks for errors.
+// If body is nil, the request is sent with an empty payload. If body is non-nil, it is sent
+// with a computed SHA-256 payload hash and Content-Type: application/xml.
+func (c *Client) do(ctx context.Context, op, method, reqURL string, body []byte, headers map[string]string) ([]byte, error) {
+	log.Tag(tagS3Client).Trace("Performing request %s %s %s (body: %d bytes)", op, method, reqURL, len(body))
+	var reader io.Reader
+	var hash string
+	if body != nil {
+		reader = bytes.NewReader(body)
+		hash = sha256Hex(body)
+	} else {
+		hash = emptyPayloadHash
+	}
+	req, err := http.NewRequestWithContext(ctx, method, reqURL, reader)
+	if err != nil {
+		return nil, fmt.Errorf("s3: %s request: %w", op, err)
+	}
+	if body != nil {
+		req.ContentLength = int64(len(body))
+		req.Header.Set("Content-Type", "application/xml")
+	} else {
+		req.ContentLength = 0
+	}
+	for k, v := range headers {
+		req.Header.Set(k, v)
+	}
+	c.signV4(req, hash)
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("s3: %s: %w", op, err)
+	}
+	respBody, err := io.ReadAll(io.LimitReader(resp.Body, maxResponseBytes))
+	resp.Body.Close()
+	if err != nil {
+		return nil, fmt.Errorf("s3: %s read: %w", op, err)
+	}
+	if !isHTTPSuccess(resp) {
+		return nil, parseErrorFromBytes(resp.StatusCode, respBody)
+	}
+	return respBody, nil
+}
+
+// newHTTP1Client creates an HTTP client that forces HTTP/1.1 by disabling HTTP/2
+// ALPN negotiation. This works around HTTP/2 stream errors with some S3-compatible
+// providers (e.g. DigitalOcean Spaces) that can cause non-retryable failures on
+// streaming uploads when the server resets the stream mid-transfer.
+// See https://github.com/rclone/rclone/issues/4673, https://github.com/golang/go/issues/42777
+func newHTTP1Client() *http.Client {
+	return &http.Client{
+		Transport: &http.Transport{
+			TLSClientConfig: &tls.Config{
+				MinVersion: tls.VersionTLS12,
+			},
+			ForceAttemptHTTP2: false,
+			TLSNextProto:      make(map[string]func(string, *tls.Conn) http.RoundTripper),
+		},
+	}
+}

s3/client_auth.go

@@ -0,0 +1,71 @@
+package s3
+
+import (
+	"encoding/hex"
+	"fmt"
+	"net/http"
+	"sort"
+	"strings"
+	"time"
+)
+
+// signV4 signs req in place using AWS Signature V4. payloadHash is the hex-encoded SHA-256
+// of the request body, or the literal string "UNSIGNED-PAYLOAD" for streaming uploads.
+//
+// See https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html
+func (c *Client) signV4(req *http.Request, hash string) {
+	now := time.Now().UTC()
+	datestamp := now.Format("20060102")
+	amzDate := now.Format("20060102T150405Z")
+
+	// Required headers
+	req.Header.Set("Host", c.config.HostHeader())
+	req.Header.Set("X-Amz-Date", amzDate)
+	req.Header.Set("X-Amz-Content-Sha256", hash)
+
+	// Canonical headers (all headers we set, sorted by lowercase key)
+	signedKeys := make([]string, 0, len(req.Header))
+	canonHeaders := make(map[string]string, len(req.Header))
+	for k := range req.Header {
+		lk := strings.ToLower(k)
+		signedKeys = append(signedKeys, lk)
+		canonHeaders[lk] = strings.TrimSpace(req.Header.Get(k))
+	}
+	sort.Strings(signedKeys)
+	signedHeadersStr := strings.Join(signedKeys, ";")
+	var chBuf strings.Builder
+	for _, k := range signedKeys {
+		chBuf.WriteString(k)
+		chBuf.WriteByte(':')
+		chBuf.WriteString(canonHeaders[k])
+		chBuf.WriteByte('\n')
+	}
+
+	// Canonical request
+	canonicalRequest := strings.Join([]string{
+		req.Method,
+		canonicalURI(req.URL),
+		canonicalQueryString(req.URL.Query()),
+		chBuf.String(),
+		signedHeadersStr,
+		hash,
+	}, "\n")
+
+	// String to sign
+	credentialScope := datestamp + "/" + c.config.Region + "/s3/aws4_request"
+	stringToSign := "AWS4-HMAC-SHA256\n" + amzDate + "\n" + credentialScope + "\n" + sha256Hex([]byte(canonicalRequest))
+
+	// Signing key
+	signingKey := hmacSHA256(hmacSHA256(hmacSHA256(hmacSHA256(
+		[]byte("AWS4"+c.config.SecretKey), []byte(datestamp)),
+		[]byte(c.config.Region)),
+		[]byte("s3")),
+		[]byte("aws4_request"))
+
+	signature := hex.EncodeToString(hmacSHA256(signingKey, []byte(stringToSign)))
+	header := fmt.Sprintf(
+		"AWS4-HMAC-SHA256 Credential=%s/%s, SignedHeaders=%s, Signature=%s",
+		c.config.AccessKey, credentialScope, signedHeadersStr, signature,
+	)
+	req.Header.Set("Authorization", header)
+}

s3/client_multipart.go

@@ -0,0 +1,187 @@
+package s3
+
+import (
+	"bytes"
+	"context"
+	"encoding/xml"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"time"
+
+	"heckel.io/ntfy/v2/log"
+)
+
+// AbortIncompleteUploads lists all in-progress multipart uploads and aborts those initiated
+// before the given cutoff time. This cleans up orphaned upload parts from interrupted uploads.
+//
+// See https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html
+// and https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html
+func (c *Client) AbortIncompleteUploads(ctx context.Context, cutoff time.Time) error {
+	uploads, err := c.listMultipartUploads(ctx)
+	if err != nil {
+		return err
+	}
+	for _, u := range uploads {
+		if !u.Initiated.IsZero() && u.Initiated.Before(cutoff) {
+			c.abortMultipartUpload(ctx, u.Key, u.UploadID)
+		}
+	}
+	return nil
+}
+
+// listMultipartUploads returns in-progress multipart uploads for the client's prefix.
+// It paginates automatically, stopping after 10,000 pages as a safety valve.
+func (c *Client) listMultipartUploads(ctx context.Context) ([]*multipartUpload, error) {
+	var all []*multipartUpload
+	var keyMarker, uploadIDMarker string
+	for page := 0; page < maxPages; page++ {
+		query := url.Values{"uploads": {""}}
+		if prefix := c.config.ListPrefix(); prefix != "" {
+			query.Set("prefix", prefix)
+		}
+		if keyMarker != "" {
+			query.Set("key-marker", keyMarker)
+			query.Set("upload-id-marker", uploadIDMarker)
+		}
+		respBody, err := c.do(ctx, "ListMultipartUploads", http.MethodGet, c.config.BucketURL()+"?"+query.Encode(), nil, nil)
+		if err != nil {
+			return nil, err
+		}
+		var result listMultipartUploadsResult
+		if err := xml.Unmarshal(respBody, &result); err != nil {
+			return nil, fmt.Errorf("error unmarshalling multipart upload result: %w", err)
+		}
+		for _, u := range result.Uploads {
+			var initiated time.Time
+			if u.Initiated != "" {
+				initiated, _ = time.Parse(time.RFC3339, u.Initiated)
+			}
+			all = append(all, &multipartUpload{
+				Key:       u.Key,
+				UploadID:  u.UploadID,
+				Initiated: initiated,
+			})
+		}
+		if !result.IsTruncated {
+			return all, nil
+		}
+		keyMarker = result.NextKeyMarker
+		uploadIDMarker = result.NextUploadIDMarker
+	}
+	return nil, fmt.Errorf("error listing multipart uploads, exceeded %d pages", maxPages)
+}
+
+// abortMultipartUpload cancels an in-progress multipart upload. Called on error to clean up.
+func (c *Client) abortMultipartUpload(ctx context.Context, key, uploadID string) {
+	log.Tag(tagS3Client).Info("Aborting multipart upload for object %s", key)
+	reqURL := fmt.Sprintf("%s?uploadId=%s", c.config.ObjectURL(key), url.QueryEscape(uploadID))
+	req, err := http.NewRequestWithContext(ctx, http.MethodDelete, reqURL, nil)
+	if err != nil {
+		return
+	}
+	c.signV4(req, emptyPayloadHash)
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return
+	}
+	resp.Body.Close()
+}
+
+// putObjectMultipart uploads body using S3 multipart upload. It reads the body in partSize
+// chunks, uploading each as a separate part. This allows uploading without knowing the total
+// body size in advance.
+func (c *Client) putObjectMultipart(ctx context.Context, key string, body io.Reader) error {
+	log.Tag(tagS3Client).Debug("Uploading multipart object %s", key)
+
+	// Step 1: Initiate multipart upload
+	uploadID, err := c.initiateMultipartUpload(ctx, key)
+	if err != nil {
+		return err
+	}
+
+	// Step 2: Upload parts
+	partNumber := 1
+	buf := make([]byte, partSize)
+	var parts []*completedPart
+	for {
+		n, err := io.ReadFull(body, buf)
+		if n > 0 {
+			etag, uploadErr := c.uploadPart(ctx, key, uploadID, partNumber, buf[:n])
+			if uploadErr != nil {
+				c.abortMultipartUpload(ctx, key, uploadID)
+				return uploadErr
+			}
+			parts = append(parts, &completedPart{
+				PartNumber: partNumber,
+				ETag:       etag,
+			})
+			partNumber++
+		}
+		if err == io.EOF || errors.Is(err, io.ErrUnexpectedEOF) {
+			break
+		} else if err != nil {
+			c.abortMultipartUpload(ctx, key, uploadID)
+			return fmt.Errorf("error uploading object %s, reading from client failed: %w", key, err)
+		}
+	}
+
+	// Step 3: Complete multipart upload
+	return c.completeMultipartUpload(ctx, key, uploadID, parts)
+}
+
+// initiateMultipartUpload starts a new multipart upload and returns the upload ID.
+func (c *Client) initiateMultipartUpload(ctx context.Context, key string) (string, error) {
+	respBody, err := c.do(ctx, "InitiateMultipartUpload", http.MethodPost, c.config.ObjectURL(key)+"?uploads", nil, nil)
+	if err != nil {
+		return "", err
+	}
+	var result initiateMultipartUploadResult
+	if err := xml.Unmarshal(respBody, &result); err != nil {
+		return "", fmt.Errorf("error unmarshalling initiate multipart upload response: %w", err)
+	}
+	return result.UploadID, nil
+}
+
+// uploadPart uploads a single part of a multipart upload and returns the ETag.
+func (c *Client) uploadPart(ctx context.Context, key, uploadID string, partNumber int, data []byte) (string, error) {
+	log.Tag(tagS3Client).Debug("Uploading multipart part for object %s, part %d, size %d", key, partNumber, len(data))
+	reqURL := fmt.Sprintf("%s?partNumber=%d&uploadId=%s", c.config.ObjectURL(key), partNumber, url.QueryEscape(uploadID))
+	req, err := http.NewRequestWithContext(ctx, http.MethodPut, reqURL, bytes.NewReader(data))
+	if err != nil {
+		return "", fmt.Errorf("error creating multipart upload part request for object %s: %w", key, err)
+	}
+	req.ContentLength = int64(len(data))
+	c.signV4(req, unsignedPayload)
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("error uploading multipart part for object %s: %w", key, err)
+	}
+	defer resp.Body.Close()
+	if !isHTTPSuccess(resp) {
+		return "", parseError(resp)
+	}
+	return resp.Header.Get("ETag"), nil
+}
+
+// completeMultipartUpload finalizes a multipart upload with the given parts.
+func (c *Client) completeMultipartUpload(ctx context.Context, key, uploadID string, parts []*completedPart) error {
+	log.Tag(tagS3Client).Debug("Completing multipart upload for object %s, %d parts", key, len(parts))
+	bodyBytes, err := xml.Marshal(&completeMultipartUploadRequest{Parts: parts})
+	if err != nil {
+		return fmt.Errorf("error marshalling complete multipart upload request: %w", err)
+	}
+	reqURL := fmt.Sprintf("%s?uploadId=%s", c.config.ObjectURL(key), url.QueryEscape(uploadID))
+	respBody, err := c.do(ctx, "CompleteMultipartUpload", http.MethodPost, reqURL, bodyBytes, nil)
+	if err != nil {
+		return err
+	}
+	// Check if the response contains an error (S3 can return 200 with an error body)
+	var errResp errorResponse
+	if xml.Unmarshal(respBody, &errResp) == nil && errResp.Code != "" {
+		return &errResp
+	}
+	return nil
+}

s3/client_test.go

@@ -0,0 +1,455 @@
+package s3
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestParseURL_Success(t *testing.T) {
+	cfg, err := ParseURL("s3://AKID:SECRET@my-bucket/attachments?region=us-east-1")
+	require.Nil(t, err)
+	require.Equal(t, "my-bucket", cfg.Bucket)
+	require.Equal(t, "attachments", cfg.Prefix)
+	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)
+}
+
+func TestParseURL_NoPrefix(t *testing.T) {
+	cfg, err := ParseURL("s3://AKID:SECRET@my-bucket?region=us-east-1")
+	require.Nil(t, err)
+	require.Equal(t, "my-bucket", cfg.Bucket)
+	require.Equal(t, "", cfg.Prefix)
+}
+
+func TestParseURL_WithEndpoint(t *testing.T) {
+	cfg, err := ParseURL("s3://AKID:SECRET@my-bucket/prefix?region=us-east-1&endpoint=https://s3.example.com")
+	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)
+}
+
+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)
+	require.Equal(t, "s3.example.com", cfg.Endpoint)
+}
+
+func TestParseURL_NestedPrefix(t *testing.T) {
+	cfg, err := ParseURL("s3://AKID:SECRET@my-bucket/a/b/c?region=us-east-1")
+	require.Nil(t, err)
+	require.Equal(t, "my-bucket", cfg.Bucket)
+	require.Equal(t, "a/b/c", cfg.Prefix)
+}
+
+func TestParseURL_MissingRegion(t *testing.T) {
+	_, err := ParseURL("s3://AKID:SECRET@my-bucket")
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "region")
+}
+
+func TestParseURL_MissingCredentials(t *testing.T) {
+	_, err := ParseURL("s3://my-bucket?region=us-east-1")
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "access key")
+}
+
+func TestParseURL_MissingSecretKey(t *testing.T) {
+	_, err := ParseURL("s3://AKID@my-bucket?region=us-east-1")
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "secret key")
+}
+
+func TestParseURL_WrongScheme(t *testing.T) {
+	_, err := ParseURL("http://AKID:SECRET@my-bucket?region=us-east-1")
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "scheme")
+}
+
+func TestParseURL_EmptyBucket(t *testing.T) {
+	_, err := ParseURL("s3://AKID:SECRET@?region=us-east-1")
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "bucket")
+}
+
+func TestParseURL_DisableHTTP2(t *testing.T) {
+	cfg, err := ParseURL("s3://AKID:SECRET@my-bucket?region=us-east-1&disable_http2=true")
+	require.Nil(t, err)
+	require.True(t, cfg.DisableHTTP2)
+}
+
+func TestParseURL_DisableHTTP2_NotSet(t *testing.T) {
+	cfg, err := ParseURL("s3://AKID:SECRET@my-bucket?region=us-east-1")
+	require.Nil(t, err)
+	require.False(t, cfg.DisableHTTP2)
+}
+
+// --- Unit tests: URL construction ---
+
+func TestConfig_BucketURL_PathStyle(t *testing.T) {
+	c := &Config{Endpoint: "s3.example.com", Bucket: "my-bucket", PathStyle: true}
+	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())
+}
+
+func TestConfig_ObjectURL_PathStyle(t *testing.T) {
+	c := &Config{Endpoint: "s3.example.com", Bucket: "my-bucket", Prefix: "prefix", PathStyle: true}
+	require.Equal(t, "https://s3.example.com/my-bucket/prefix/obj", c.ObjectURL("obj"))
+}
+
+func TestConfig_ObjectURL_VirtualHosted(t *testing.T) {
+	c := &Config{Endpoint: "s3.us-east-1.amazonaws.com", Bucket: "my-bucket", Prefix: "prefix", PathStyle: false}
+	require.Equal(t, "https://my-bucket.s3.us-east-1.amazonaws.com/prefix/obj", c.ObjectURL("obj"))
+}
+
+func TestConfig_HostHeader_PathStyle(t *testing.T) {
+	c := &Config{Endpoint: "s3.example.com", Bucket: "my-bucket", PathStyle: true}
+	require.Equal(t, "s3.example.com", c.HostHeader())
+}
+
+func TestConfig_HostHeader_VirtualHosted(t *testing.T) {
+	c := &Config{Endpoint: "s3.us-east-1.amazonaws.com", Bucket: "my-bucket", PathStyle: false}
+	require.Equal(t, "my-bucket.s3.us-east-1.amazonaws.com", c.HostHeader())
+}
+
+func TestConfig_ObjectKey(t *testing.T) {
+	c := &Config{Prefix: "attachments"}
+	require.Equal(t, "attachments/file123", c.ObjectKey("file123"))
+
+	c2 := &Config{Prefix: ""}
+	require.Equal(t, "file123", c2.ObjectKey("file123"))
+}
+
+func TestConfig_ListPrefix(t *testing.T) {
+	c := &Config{Prefix: "attachments"}
+	require.Equal(t, "attachments/", c.ListPrefix())
+
+	c2 := &Config{Prefix: ""}
+	require.Equal(t, "", c2.ListPrefix())
+}
+
+// --- Integration tests using real S3 ---
+
+func TestClient_PutGetObject(t *testing.T) {
+	client := newTestClient(t)
+	ctx := context.Background()
+
+	// Put
+	err := client.PutObject(ctx, "test-key", strings.NewReader("hello world"), 0)
+	require.Nil(t, err)
+
+	// Get
+	reader, size, err := client.GetObject(ctx, "test-key")
+	require.Nil(t, err)
+	require.Equal(t, int64(11), size)
+	data, err := io.ReadAll(reader)
+	reader.Close()
+	require.Nil(t, err)
+	require.Equal(t, "hello world", string(data))
+}
+
+func TestClient_GetObject_NotFound(t *testing.T) {
+	client := newTestClient(t)
+
+	_, _, err := client.GetObject(context.Background(), "nonexistent")
+	require.Error(t, err)
+}
+
+func TestClient_DeleteObjects(t *testing.T) {
+	client := newTestClient(t)
+	ctx := context.Background()
+
+	// Put several objects
+	for i := 0; i < 5; i++ {
+		err := client.PutObject(ctx, fmt.Sprintf("del-%d", i), bytes.NewReader([]byte("data")), 0)
+		require.Nil(t, err)
+	}
+	waitForCount(t, client, 5)
+
+	// Delete some
+	err := client.DeleteObjects(ctx, []string{"del-1", "del-3"})
+	require.Nil(t, err)
+	waitForCount(t, client, 3)
+
+	// Verify deleted ones are gone
+	_, _, err = client.GetObject(ctx, "del-1")
+	require.Error(t, err)
+	_, _, err = client.GetObject(ctx, "del-3")
+	require.Error(t, err)
+
+	// Verify remaining ones are still there
+	for _, key := range []string{"del-0", "del-2", "del-4"} {
+		reader, _, err := client.GetObject(ctx, key)
+		require.Nil(t, err)
+		reader.Close()
+	}
+}
+
+func TestClient_ListObjects(t *testing.T) {
+	client := newTestClient(t)
+	ctx := context.Background()
+
+	for i := 0; i < 3; i++ {
+		err := client.PutObject(ctx, fmt.Sprintf("list-%d", i), bytes.NewReader([]byte("x")), 0)
+		require.Nil(t, err)
+	}
+	waitForCount(t, client, 3)
+}
+
+func TestClient_ListObjects_Pagination(t *testing.T) {
+	client := newTestClient(t)
+	ctx := context.Background()
+
+	// Create 1010 objects in parallel (5 goroutines)
+	const total = 1010
+	const workers = 5
+	var wg sync.WaitGroup
+	errs := make(chan error, total)
+	for w := 0; w < workers; w++ {
+		wg.Add(1)
+		go func(start int) {
+			defer wg.Done()
+			for i := start; i < total; i += workers {
+				if err := client.PutObject(ctx, fmt.Sprintf("pg-%04d", i), bytes.NewReader([]byte("x")), 0); err != nil {
+					errs <- err
+					return
+				}
+			}
+		}(w)
+	}
+	wg.Wait()
+	close(errs)
+	for err := range errs {
+		require.Nil(t, err)
+	}
+	waitForCount(t, client, total)
+}
+
+func TestClient_PutObject_LargeBody(t *testing.T) {
+	client := newTestClient(t)
+	ctx := context.Background()
+
+	// 1 MB object
+	data := make([]byte, 1024*1024)
+	for i := range data {
+		data[i] = byte(i % 256)
+	}
+	err := client.PutObject(ctx, "large", bytes.NewReader(data), 0)
+	require.Nil(t, err)
+
+	reader, size, err := client.GetObject(ctx, "large")
+	require.Nil(t, err)
+	require.Equal(t, int64(1024*1024), size)
+	got, err := io.ReadAll(reader)
+	reader.Close()
+	require.Nil(t, err)
+	require.Equal(t, data, got)
+}
+
+func TestClient_PutObject_ChunkedUpload(t *testing.T) {
+	client := newTestClient(t)
+	ctx := context.Background()
+
+	// 12 MB object, exceeds 5 MB partSize, triggers multipart upload path
+	data := make([]byte, 12*1024*1024)
+	for i := range data {
+		data[i] = byte(i % 256)
+	}
+	err := client.PutObject(ctx, "multipart", bytes.NewReader(data), 0)
+	require.Nil(t, err)
+
+	reader, size, err := client.GetObject(ctx, "multipart")
+	require.Nil(t, err)
+	require.Equal(t, int64(12*1024*1024), size)
+	got, err := io.ReadAll(reader)
+	reader.Close()
+	require.Nil(t, err)
+	require.Equal(t, data, got)
+}
+
+func TestClient_PutObject_ExactPartSize(t *testing.T) {
+	client := newTestClient(t)
+	ctx := context.Background()
+
+	// Exactly 5 MB (partSize), should use the simple put path (ReadFull succeeds fully)
+	data := make([]byte, 5*1024*1024)
+	for i := range data {
+		data[i] = byte(i % 256)
+	}
+	err := client.PutObject(ctx, "exact", bytes.NewReader(data), 0)
+	require.Nil(t, err)
+
+	reader, size, err := client.GetObject(ctx, "exact")
+	require.Nil(t, err)
+	require.Equal(t, int64(5*1024*1024), size)
+	got, err := io.ReadAll(reader)
+	reader.Close()
+	require.Nil(t, err)
+	require.Equal(t, data, got)
+}
+
+func TestClient_PutObject_StreamingExactLength(t *testing.T) {
+	client := newTestClient(t)
+	ctx := context.Background()
+
+	// untrustedLength matches body exactly — streams directly via putObject
+	err := client.PutObject(ctx, "stream-exact", strings.NewReader("hello world"), 11)
+	require.Nil(t, err)
+
+	reader, size, err := client.GetObject(ctx, "stream-exact")
+	require.Nil(t, err)
+	require.Equal(t, int64(11), size)
+	got, err := io.ReadAll(reader)
+	reader.Close()
+	require.Nil(t, err)
+	require.Equal(t, "hello world", string(got))
+}
+
+func TestClient_PutObject_StreamingBodyLongerThanClaimed(t *testing.T) {
+	client := newTestClient(t)
+	ctx := context.Background()
+
+	// Body has 11 bytes, but we claim 5 — only first 5 bytes should be stored
+	err := client.PutObject(ctx, "stream-long", strings.NewReader("hello world"), 5)
+	require.Nil(t, err)
+
+	reader, size, err := client.GetObject(ctx, "stream-long")
+	require.Nil(t, err)
+	require.Equal(t, int64(5), size)
+	got, err := io.ReadAll(reader)
+	reader.Close()
+	require.Nil(t, err)
+	require.Equal(t, "hello", string(got))
+}
+
+func TestClient_PutObject_StreamingBodyShorterThanClaimed(t *testing.T) {
+	client := newTestClient(t)
+	ctx := context.Background()
+
+	// Body has 5 bytes, but we claim 100 — should fail
+	err := client.PutObject(ctx, "stream-short", strings.NewReader("hello"), 100)
+	require.Error(t, err)
+
+	// Object should not exist
+	_, _, err = client.GetObject(ctx, "stream-short")
+	require.Error(t, err)
+}
+
+func TestClient_PutObject_NestedKey(t *testing.T) {
+	client := newTestClient(t)
+	ctx := context.Background()
+
+	err := client.PutObject(ctx, "deep/nested/prefix/file.txt", strings.NewReader("nested"), 0)
+	require.Nil(t, err)
+
+	reader, _, err := client.GetObject(ctx, "deep/nested/prefix/file.txt")
+	require.Nil(t, err)
+	data, _ := io.ReadAll(reader)
+	reader.Close()
+	require.Equal(t, "nested", string(data))
+}
+
+func newTestClient(t *testing.T) *Client {
+	t.Helper()
+	s3URL := os.Getenv("NTFY_TEST_S3_URL")
+	if s3URL == "" {
+		t.Skip("NTFY_TEST_S3_URL not set")
+	}
+	cfg, err := ParseURL(s3URL)
+	require.Nil(t, err)
+	// Use per-test prefix to isolate objects between tests
+	if cfg.Prefix != "" {
+		cfg.Prefix = cfg.Prefix + "/testpkg-s3/" + t.Name()
+	} else {
+		cfg.Prefix = "testpkg-s3/" + t.Name()
+	}
+	client := New(cfg)
+	deleteAllObjects(t, client)
+	t.Cleanup(func() { deleteAllObjects(t, client) })
+	return client
+}
+
+func deleteAllObjects(t *testing.T, client *Client) {
+	t.Helper()
+	for i := 0; i < 60; i++ {
+		objects, err := client.ListObjectsV2(context.Background())
+		require.Nil(t, err)
+		if len(objects) == 0 {
+			return
+		}
+		keys := make([]string, len(objects))
+		for j, obj := range objects {
+			keys[j] = obj.Key
+		}
+		require.Nil(t, client.DeleteObjects(context.Background(), keys))
+		time.Sleep(500 * time.Millisecond)
+	}
+	t.Fatal("timed out waiting for bucket to be empty")
+}
+
+func waitForCount(t *testing.T, client *Client, expected int) {
+	t.Helper()
+	for i := 0; i < 60; i++ {
+		objects, err := client.ListObjectsV2(context.Background())
+		require.Nil(t, err)
+		if len(objects) == expected {
+			return
+		}
+		time.Sleep(500 * time.Millisecond)
+	}
+	objects, _ := client.ListObjectsV2(context.Background())
+	t.Fatalf("timed out waiting for %d objects, got %d", expected, len(objects))
+}

s3/types.go

@@ -0,0 +1,171 @@
+package s3
+
+import (
+	"encoding/xml"
+	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+// 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
+	Prefix       string
+	Region       string
+	AccessKey    string
+	SecretKey    string
+	DisableHTTP2 bool         // Force HTTP/1.1 to work around HTTP/2 issues with some S3-compatible providers
+	HTTPClient   *http.Client // if nil, a default client is created (respecting DisableHTTP2)
+}
+
+// BucketURL returns the base URL for bucket-level operations.
+func (c *Config) BucketURL() string {
+	scheme := "https"
+	if c.Scheme != "" {
+		scheme = c.Scheme
+	}
+	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.
+func (c *Config) HostHeader() string {
+	if c.PathStyle {
+		return c.Endpoint
+	}
+	return c.Bucket + "." + c.Endpoint
+}
+
+// ListPrefix returns the prefix to use in ListObjectsV2 requests,
+// with a trailing slash so that only objects under the prefix directory are returned.
+func (c *Config) ListPrefix() string {
+	if c.Prefix != "" {
+		return c.Prefix + "/"
+	}
+	return ""
+}
+
+// StripPrefix removes the configured prefix from a key returned by ListObjectsV2,
+// so keys match what was passed to PutObject/GetObject/DeleteObjects.
+func (c *Config) StripPrefix(key string) string {
+	if c.Prefix != "" {
+		return strings.TrimPrefix(key, c.Prefix+"/")
+	}
+	return key
+}
+
+// ObjectKey prepends the configured prefix to the given key.
+func (c *Config) ObjectKey(key string) string {
+	if c.Prefix != "" {
+		return c.Prefix + "/" + key
+	}
+	return key
+}
+
+// ObjectURL returns the full URL for an object, automatically prepending the configured prefix.
+func (c *Config) ObjectURL(key string) string {
+	u, _ := url.JoinPath(c.BucketURL(), c.ObjectKey(key))
+	return u
+}
+
+// Object represents an S3 object returned by list operations.
+type Object struct {
+	Key          string
+	Size         int64
+	LastModified time.Time
+}
+
+// errorResponse is returned when S3 responds with a non-2xx status code.
+type errorResponse struct {
+	StatusCode int
+	Code       string `xml:"Code"`
+	Message    string `xml:"Message"`
+	Body       string `xml:"-"` // raw response body
+}
+
+func (e *errorResponse) Error() string {
+	if e.Code != "" {
+		return fmt.Sprintf("s3: %s (HTTP %d): %s", e.Code, e.StatusCode, e.Message)
+	}
+	return fmt.Sprintf("s3: HTTP %d: %s", e.StatusCode, e.Body)
+}
+
+// listObjectsV2Result is the XML response from S3 ListObjectsV2
+type listObjectsV2Result struct {
+	Contents              []*listObject `xml:"Contents"`
+	IsTruncated           bool          `xml:"IsTruncated"`
+	NextContinuationToken string        `xml:"NextContinuationToken"`
+}
+
+type listObject struct {
+	Key          string `xml:"Key"`
+	Size         int64  `xml:"Size"`
+	LastModified string `xml:"LastModified"`
+}
+
+// deleteObjectsRequest is the XML request body for S3 DeleteObjects
+type deleteObjectsRequest struct {
+	XMLName xml.Name        `xml:"Delete"`
+	Quiet   bool            `xml:"Quiet"`
+	Objects []*deleteObject `xml:"Object"`
+}
+
+type deleteObject struct {
+	Key string `xml:"Key"`
+}
+
+// deleteObjectsResult is the XML response from S3 DeleteObjects
+type deleteObjectsResult struct {
+	Errors []*deleteError `xml:"Error"`
+}
+
+type deleteError struct {
+	Key     string `xml:"Key"`
+	Code    string `xml:"Code"`
+	Message string `xml:"Message"`
+}
+
+// listMultipartUploadsResult is the XML response from S3 listMultipartUploads
+type listMultipartUploadsResult struct {
+	Uploads            []*listUpload `xml:"Upload"`
+	IsTruncated        bool          `xml:"IsTruncated"`
+	NextKeyMarker      string        `xml:"NextKeyMarker"`
+	NextUploadIDMarker string        `xml:"NextUploadIdMarker"`
+}
+
+type listUpload struct {
+	Key       string `xml:"Key"`
+	UploadID  string `xml:"UploadId"`
+	Initiated string `xml:"Initiated"`
+}
+
+// multipartUpload represents an in-progress multipart upload returned by listMultipartUploads.
+type multipartUpload struct {
+	Key       string
+	UploadID  string
+	Initiated time.Time
+}
+
+// initiateMultipartUploadResult is the XML response from S3 InitiateMultipartUpload
+type initiateMultipartUploadResult struct {
+	UploadID string `xml:"UploadId"`
+}
+
+// completeMultipartUploadRequest is the XML request body for S3 CompleteMultipartUpload
+type completeMultipartUploadRequest struct {
+	XMLName xml.Name         `xml:"CompleteMultipartUpload"`
+	Parts   []*completedPart `xml:"Part"`
+}
+
+// completedPart represents a successfully uploaded part for CompleteMultipartUpload
+type completedPart struct {
+	PartNumber int    `xml:"PartNumber"`
+	ETag       string `xml:"ETag"`
+}

s3/util.go

@@ -0,0 +1,194 @@
+package s3
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/xml"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+const (
+	// SHA-256 hash of the empty string, used as the payload hash for bodiless requests
+	emptyPayloadHash = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+
+	// Sent as the payload hash for streaming uploads where the body is not buffered in memory
+	unsignedPayload = "UNSIGNED-PAYLOAD"
+
+	// maxResponseBytes caps the size of S3 response bodies we read into memory
+	maxResponseBytes = 2 * 1024 * 1024
+
+	// partSize is the size of each part for multipart uploads (5 MB). This is also the threshold
+	// above which PutObject switches from a simple PUT to multipart upload. S3 requires a minimum
+	// part size of 5 MB for all parts except the last.
+	partSize = 5 * 1024 * 1024
+
+	// maxSinglePutSize is the maximum size for a single PUT upload (5 GB).
+	// Objects larger than this must use multipart upload.
+	maxSinglePutSize = 5 * 1024 * 1024 * 1024
+
+	// maxPages is the max number of pages to iterate through when listing objects
+	maxPages = 500
+
+	// maxDeleteBatchSize is the maximum number of keys per S3 DeleteObjects call
+	maxDeleteBatchSize = 1000
+)
+
+// ParseURL parses an S3 URL of the form:
+//
+//	s3://ACCESS_KEY:SECRET_KEY@BUCKET[/PREFIX]?region=REGION[&endpoint=ENDPOINT][&disable_http2=true]
+//
+// When endpoint is specified, path-style addressing is enabled automatically.
+// When disable_http2=true is set, the client forces HTTP/1.1 to work around
+// HTTP/2 stream errors with some S3-compatible providers (e.g. DigitalOcean Spaces).
+func ParseURL(s3URL string) (*Config, error) {
+	u, err := url.Parse(s3URL)
+	if err != nil {
+		return nil, fmt.Errorf("s3: invalid URL: %w", err)
+	}
+	if u.Scheme != "s3" {
+		return nil, fmt.Errorf("s3: URL scheme must be 's3', got '%s'", u.Scheme)
+	}
+	if u.Host == "" {
+		return nil, fmt.Errorf("s3: bucket name must be specified as host")
+	}
+	bucket := u.Host
+	prefix := strings.TrimPrefix(u.Path, "/")
+	accessKey := u.User.Username()
+	secretKey, _ := u.User.Password()
+	if accessKey == "" || secretKey == "" {
+		return nil, fmt.Errorf("s3: access key and secret key must be specified in URL")
+	}
+	region := u.Query().Get("region")
+	if region == "" {
+		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: 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,
+		Prefix:       prefix,
+		Region:       region,
+		AccessKey:    accessKey,
+		SecretKey:    secretKey,
+		DisableHTTP2: disableHTTP2,
+	}, nil
+}
+
+// parseError reads an S3 error response and returns an *errorResponse.
+func parseError(resp *http.Response) error {
+	body, err := io.ReadAll(io.LimitReader(resp.Body, maxResponseBytes))
+	if err != nil {
+		return fmt.Errorf("error reading S3 error response: %w", err)
+	}
+	return parseErrorFromBytes(resp.StatusCode, body)
+}
+
+func parseErrorFromBytes(statusCode int, body []byte) error {
+	errResp := &errorResponse{
+		StatusCode: statusCode,
+		Body:       string(body),
+	}
+	// Try to parse XML error; if it fails, we still have StatusCode and Body
+	_ = xml.Unmarshal(body, errResp)
+	return errResp
+}
+
+// canonicalURI returns the URI-encoded path for the canonical request. Each path segment is
+// percent-encoded per RFC 3986; forward slashes are preserved.
+func canonicalURI(u *url.URL) string {
+	p := u.Path
+	if p == "" {
+		return "/"
+	}
+	segments := strings.Split(p, "/")
+	for i, seg := range segments {
+		segments[i] = uriEncode(seg)
+	}
+	return strings.Join(segments, "/")
+}
+
+// canonicalQueryString builds the query string for the canonical request. Keys and values
+// are URI-encoded per RFC 3986 (using %20, not +) and sorted lexically by key.
+func canonicalQueryString(values url.Values) string {
+	if len(values) == 0 {
+		return ""
+	}
+	keys := make([]string, 0, len(values))
+	for k := range values {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	var pairs []string
+	for _, k := range keys {
+		ek := uriEncode(k)
+		vs := make([]string, len(values[k]))
+		copy(vs, values[k])
+		sort.Strings(vs)
+		for _, v := range vs {
+			pairs = append(pairs, ek+"="+uriEncode(v))
+		}
+	}
+	return strings.Join(pairs, "&")
+}
+
+// uriEncode percent-encodes a string per RFC 3986, encoding everything except unreserved
+// characters (A-Z a-z 0-9 - _ . ~).
+func uriEncode(s string) string {
+	var buf strings.Builder
+	for i := 0; i < len(s); i++ {
+		b := s[i]
+		if (b >= 'A' && b <= 'Z') || (b >= 'a' && b <= 'z') || (b >= '0' && b <= '9') ||
+			b == '-' || b == '_' || b == '.' || b == '~' {
+			buf.WriteByte(b)
+		} else {
+			fmt.Fprintf(&buf, "%%%02X", b)
+		}
+	}
+	return buf.String()
+}
+
+func isHTTPSuccess(resp *http.Response) bool {
+	return resp.StatusCode/100 == 2
+}
+
+func sha256Hex(data []byte) string {
+	h := sha256.Sum256(data)
+	return hex.EncodeToString(h[:])
+}
+
+func hmacSHA256(key, data []byte) []byte {
+	h := hmac.New(sha256.New, key)
+	h.Write(data)
+	return h.Sum(nil)
+}

s3/util_test.go

@@ -0,0 +1,181 @@
+package s3
+
+import (
+	"net/http"
+	"net/url"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestURIEncode(t *testing.T) {
+	// Unreserved characters are not encoded
+	require.Equal(t, "abcdefghijklmnopqrstuvwxyz", uriEncode("abcdefghijklmnopqrstuvwxyz"))
+	require.Equal(t, "ABCDEFGHIJKLMNOPQRSTUVWXYZ", uriEncode("ABCDEFGHIJKLMNOPQRSTUVWXYZ"))
+	require.Equal(t, "0123456789", uriEncode("0123456789"))
+	require.Equal(t, "-_.~", uriEncode("-_.~"))
+
+	// Spaces use %20, not +
+	require.Equal(t, "hello%20world", uriEncode("hello world"))
+
+	// Slashes are encoded (canonicalURI handles slash splitting separately)
+	require.Equal(t, "a%2Fb", uriEncode("a/b"))
+
+	// Special characters
+	require.Equal(t, "%2B", uriEncode("+"))
+	require.Equal(t, "%3D", uriEncode("="))
+	require.Equal(t, "%26", uriEncode("&"))
+	require.Equal(t, "%40", uriEncode("@"))
+	require.Equal(t, "%23", uriEncode("#"))
+
+	// Mixed
+	require.Equal(t, "test~file-name_1.txt", uriEncode("test~file-name_1.txt"))
+	require.Equal(t, "key%20with%20spaces%2Fand%2Fslashes", uriEncode("key with spaces/and/slashes"))
+
+	// Empty string
+	require.Equal(t, "", uriEncode(""))
+}
+
+func TestCanonicalURI(t *testing.T) {
+	// Simple path
+	u, _ := url.Parse("https://example.com/bucket/key")
+	require.Equal(t, "/bucket/key", canonicalURI(u))
+
+	// Root path
+	u, _ = url.Parse("https://example.com/")
+	require.Equal(t, "/", canonicalURI(u))
+
+	// Empty path
+	u, _ = url.Parse("https://example.com")
+	require.Equal(t, "/", canonicalURI(u))
+
+	// Path with special characters
+	u, _ = url.Parse("https://example.com/bucket/key%20with%20spaces")
+	require.Equal(t, "/bucket/key%20with%20spaces", canonicalURI(u))
+
+	// Nested path
+	u, _ = url.Parse("https://example.com/bucket/a/b/c/file.txt")
+	require.Equal(t, "/bucket/a/b/c/file.txt", canonicalURI(u))
+}
+
+func TestCanonicalQueryString(t *testing.T) {
+	// Multiple keys sorted alphabetically
+	vals := url.Values{
+		"prefix":    {"test/"},
+		"list-type": {"2"},
+	}
+	require.Equal(t, "list-type=2&prefix=test%2F", canonicalQueryString(vals))
+
+	// Empty values
+	require.Equal(t, "", canonicalQueryString(url.Values{}))
+
+	// Single key
+	require.Equal(t, "key=value", canonicalQueryString(url.Values{"key": {"value"}}))
+
+	// Key with multiple values (sorted)
+	vals = url.Values{"key": {"b", "a"}}
+	require.Equal(t, "key=a&key=b", canonicalQueryString(vals))
+
+	// Keys requiring encoding
+	vals = url.Values{"continuation-token": {"abc+def"}}
+	require.Equal(t, "continuation-token=abc%2Bdef", canonicalQueryString(vals))
+}
+
+func TestSHA256Hex(t *testing.T) {
+	// SHA-256 of empty string
+	require.Equal(t, emptyPayloadHash, sha256Hex([]byte("")))
+
+	// SHA-256 of known value
+	require.Equal(t, "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824", sha256Hex([]byte("hello")))
+}
+
+func TestHmacSHA256(t *testing.T) {
+	// Known test vector: HMAC-SHA256("key", "message")
+	result := hmacSHA256([]byte("key"), []byte("message"))
+	require.Len(t, result, 32) // SHA-256 produces 32 bytes
+	require.NotEqual(t, make([]byte, 32), result)
+
+	// Same inputs should produce same output
+	result2 := hmacSHA256([]byte("key"), []byte("message"))
+	require.Equal(t, result, result2)
+
+	// Different inputs should produce different output
+	result3 := hmacSHA256([]byte("different-key"), []byte("message"))
+	require.NotEqual(t, result, result3)
+}
+
+func TestSignV4_SetsRequiredHeaders(t *testing.T) {
+	c := &Client{config: &Config{
+		AccessKey: "AKID",
+		SecretKey: "SECRET",
+		Region:    "us-east-1",
+		Endpoint:  "s3.us-east-1.amazonaws.com",
+		Bucket:    "my-bucket",
+	}}
+
+	req, _ := http.NewRequest(http.MethodGet, "https://my-bucket.s3.us-east-1.amazonaws.com/test-key", nil)
+	c.signV4(req, emptyPayloadHash)
+
+	// All required SigV4 headers must be set
+	require.NotEmpty(t, req.Header.Get("Host"))
+	require.NotEmpty(t, req.Header.Get("X-Amz-Date"))
+	require.Equal(t, emptyPayloadHash, req.Header.Get("X-Amz-Content-Sha256"))
+
+	// Authorization header must have correct format
+	auth := req.Header.Get("Authorization")
+	require.Contains(t, auth, "AWS4-HMAC-SHA256")
+	require.Contains(t, auth, "Credential=AKID/")
+	require.Contains(t, auth, "/us-east-1/s3/aws4_request")
+	require.Contains(t, auth, "SignedHeaders=")
+	require.Contains(t, auth, "Signature=")
+}
+
+func TestSignV4_UnsignedPayload(t *testing.T) {
+	c := &Client{config: &Config{
+		AccessKey: "AKID",
+		SecretKey: "SECRET",
+		Region:    "us-east-1",
+		Endpoint:  "s3.us-east-1.amazonaws.com",
+		Bucket:    "my-bucket",
+	}}
+
+	req, _ := http.NewRequest(http.MethodPut, "https://my-bucket.s3.us-east-1.amazonaws.com/test-key", nil)
+	c.signV4(req, unsignedPayload)
+
+	require.Equal(t, unsignedPayload, req.Header.Get("X-Amz-Content-Sha256"))
+}
+
+func TestSignV4_DifferentRegions(t *testing.T) {
+	c1 := &Client{config: &Config{AccessKey: "AKID", SecretKey: "SECRET", Region: "us-east-1", Endpoint: "s3.us-east-1.amazonaws.com", Bucket: "b"}}
+	c2 := &Client{config: &Config{AccessKey: "AKID", SecretKey: "SECRET", Region: "eu-west-1", Endpoint: "s3.eu-west-1.amazonaws.com", Bucket: "b"}}
+
+	req1, _ := http.NewRequest(http.MethodGet, "https://b.s3.us-east-1.amazonaws.com/key", nil)
+	c1.signV4(req1, emptyPayloadHash)
+
+	req2, _ := http.NewRequest(http.MethodGet, "https://b.s3.eu-west-1.amazonaws.com/key", nil)
+	c2.signV4(req2, emptyPayloadHash)
+
+	// Different regions should produce different signatures
+	require.NotEqual(t, req1.Header.Get("Authorization"), req2.Header.Get("Authorization"))
+}
+
+func TestParseError_XMLResponse(t *testing.T) {
+	xmlBody := []byte(`<?xml version="1.0" encoding="UTF-8"?><Error><Code>NoSuchKey</Code><Message>The specified key does not exist.</Message></Error>`)
+	err := parseErrorFromBytes(404, xmlBody)
+
+	var errResp *errorResponse
+	require.ErrorAs(t, err, &errResp)
+	require.Equal(t, 404, errResp.StatusCode)
+	require.Equal(t, "NoSuchKey", errResp.Code)
+	require.Equal(t, "The specified key does not exist.", errResp.Message)
+}
+
+func TestParseError_NonXMLResponse(t *testing.T) {
+	err := parseErrorFromBytes(500, []byte("internal server error"))
+
+	var errResp *errorResponse
+	require.ErrorAs(t, err, &errResp)
+	require.Equal(t, 500, errResp.StatusCode)
+	require.Equal(t, "", errResp.Code) // XML parsing failed, no code
+	require.Contains(t, errResp.Body, "internal server error")
+}

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"
 )
 
@@ -20,6 +23,7 @@ const (
 	DefaultCacheBatchTimeout                    = time.Duration(0)
 	DefaultKeepaliveInterval                    = 45 * time.Second // Not too frequently to save battery (Android read timeout used to be 77s!)
 	DefaultManagerInterval                      = time.Minute
+	DefaultManagerBatchSize                     = 30000
 	DefaultDelayedSenderInterval                = 10 * time.Second
 	DefaultMessageDelayMin                      = 10 * time.Second
 	DefaultMessageDelayMax                      = 3 * 24 * time.Hour
@@ -41,16 +45,36 @@ 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
 // - various attachment limits
 const (
-	DefaultMessageSizeLimit         = 4096 // Bytes; note that FCM/APNS have a limit of ~4 KB for the entire message
-	DefaultTotalTopicLimit          = 15000
-	DefaultAttachmentTotalSizeLimit = int64(5 * 1024 * 1024 * 1024) // 5 GB
-	DefaultAttachmentFileSizeLimit  = int64(15 * 1024 * 1024)       // 15 MB
-	DefaultAttachmentExpiryDuration = 3 * time.Hour
+	DefaultMessageSizeLimit            = 4096 // Bytes; note that FCM/APNS have a limit of ~4 KB for the entire message
+	DefaultTotalTopicLimit             = 15000
+	DefaultAttachmentTotalSizeLimit    = int64(5 * 1024 * 1024 * 1024) // 5 GB
+	DefaultAttachmentFileSizeLimit     = int64(15 * 1024 * 1024)       // 15 MB
+	DefaultAttachmentExpiryDuration    = 3 * time.Hour
+	DefaultAttachmentOrphanGracePeriod = time.Hour // Don't delete orphaned objects younger than this to avoid races with in-flight uploads
+
 )
 
 // Defines all per-visitor limits
@@ -66,7 +90,9 @@ const (
 	DefaultVisitorMessageDailyLimit             = 0
 	DefaultVisitorEmailLimitBurst               = 16
 	DefaultVisitorEmailLimitReplenish           = time.Hour
-	DefaultVisitorAccountCreationLimitBurst     = 3
+	DefaultVisitorTopicCreationLimitBurst       = 100
+	DefaultVisitorTopicCreationLimitReplenish   = time.Minute
+	DefaultVisitorAccountCreationLimitBurst     = 6 // Shared by signup and password-reset requests (same per-visitor bucket)
 	DefaultVisitorAccountCreationLimitReplenish = 24 * time.Hour
 	DefaultVisitorAuthFailureLimitBurst         = 30
 	DefaultVisitorAuthFailureLimitReplenish     = time.Minute
@@ -95,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
@@ -106,18 +137,22 @@ 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)
+	AuthAccessCacheReloadInterval        time.Duration // Reload interval for access cache, relevant for ACL writes from CLI
 	AttachmentCacheDir                   string
 	AttachmentTotalSizeLimit             int64
 	AttachmentFileSizeLimit              int64
 	AttachmentExpiryDuration             time.Duration
+	AttachmentOrphanGracePeriod          time.Duration
 	TemplateDir                          string // Directory to load named templates from
 	KeepaliveInterval                    time.Duration
 	ManagerInterval                      time.Duration
+	ManagerBatchSize                     int
 	DisallowedTopics                     []string
 	WebRoot                              string // empty to disable
 	DelayedSenderInterval                time.Duration
@@ -125,22 +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
@@ -157,6 +192,8 @@ type Config struct {
 	VisitorMessageDailyLimit             int
 	VisitorEmailLimitBurst               int
 	VisitorEmailLimitReplenish           time.Duration
+	VisitorTopicCreationLimitBurst       int           // Burst of new topic creations per visitor
+	VisitorTopicCreationLimitReplenish   time.Duration // Interval at which topic-creation tokens are refilled
 	VisitorAccountCreationLimitBurst     int
 	VisitorAccountCreationLimitReplenish time.Duration
 	VisitorAuthFailureLimitBurst         int
@@ -168,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
@@ -178,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
@@ -202,6 +243,11 @@ func NewConfig() *Config {
 		KeyFile:                              "",
 		CertFile:                             "",
 		DatabaseURL:                          "",
+		ClusterNodeID:                        "",
+		ClusterListen:                        "",
+		ClusterAdvertiseURL:                  "",
+		ClusterSecret:                        "",
+		ClusterBatchLinger:                   cluster.DefaultBatchLinger,
 		FirebaseKeyFile:                      "",
 		CacheFile:                            "",
 		CacheDuration:                        DefaultCacheDuration,
@@ -213,13 +259,17 @@ func NewConfig() *Config {
 		AuthDefault:                          user.PermissionReadWrite,
 		AuthBcryptCost:                       user.DefaultUserPasswordBcryptCost,
 		AuthStatsQueueWriterInterval:         user.DefaultUserStatsQueueWriterInterval,
+		AuthAccessCacheEnabled:               user.DefaultAccessCacheEnabled,
+		AuthAccessCacheReloadInterval:        user.DefaultAccessCacheReloadInterval,
 		AttachmentCacheDir:                   "",
 		AttachmentTotalSizeLimit:             DefaultAttachmentTotalSizeLimit,
 		AttachmentFileSizeLimit:              DefaultAttachmentFileSizeLimit,
 		AttachmentExpiryDuration:             DefaultAttachmentExpiryDuration,
+		AttachmentOrphanGracePeriod:          DefaultAttachmentOrphanGracePeriod,
 		TemplateDir:                          DefaultTemplateDir,
 		KeepaliveInterval:                    DefaultKeepaliveInterval,
 		ManagerInterval:                      DefaultManagerInterval,
+		ManagerBatchSize:                     DefaultManagerBatchSize,
 		DisallowedTopics:                     DefaultDisallowedTopics,
 		WebRoot:                              "/",
 		DelayedSenderInterval:                DefaultDelayedSenderInterval,
@@ -232,6 +282,7 @@ func NewConfig() *Config {
 		SMTPSenderUser:                       "",
 		SMTPSenderPass:                       "",
 		SMTPSenderFrom:                       "",
+		SMTPSenderVerify:                     false,
 		SMTPServerListen:                     "",
 		SMTPServerDomain:                     "",
 		SMTPServerAddrPrefix:                 "",
@@ -257,6 +308,8 @@ func NewConfig() *Config {
 		VisitorMessageDailyLimit:             DefaultVisitorMessageDailyLimit,
 		VisitorEmailLimitBurst:               DefaultVisitorEmailLimitBurst,
 		VisitorEmailLimitReplenish:           DefaultVisitorEmailLimitReplenish,
+		VisitorTopicCreationLimitBurst:       DefaultVisitorTopicCreationLimitBurst,
+		VisitorTopicCreationLimitReplenish:   DefaultVisitorTopicCreationLimitReplenish,
 		VisitorAccountCreationLimitBurst:     DefaultVisitorAccountCreationLimitBurst,
 		VisitorAccountCreationLimitReplenish: DefaultVisitorAccountCreationLimitReplenish,
 		VisitorAuthFailureLimitBurst:         DefaultVisitorAuthFailureLimitBurst,
@@ -281,6 +334,10 @@ func NewConfig() *Config {
 		WebPushEmailAddress:                  "",
 		WebPushExpiryDuration:                DefaultWebPushExpiryDuration,
 		WebPushExpiryWarningDuration:         DefaultWebPushExpiryWarningDuration,
+		BanFile:                              "",
+		BanWindow:                            DefaultBanWindow,
+		BanThreshold:                         DefaultBanThreshold,
+		BanWeights:                           nil,
 		BuildVersion:                         "",
 		BuildDate:                            "",
 		BuildCommit:                          "",
@@ -297,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,12 +136,19 @@ 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}
 	errHTTPBadRequestSequenceIDInvalid               = &errHTTP{40049, http.StatusBadRequest, "invalid request: sequence ID invalid", "https://ntfy.sh/docs/publish/#updating-deleting-notifications", nil}
+	errHTTPBadRequestEmailAddressInvalid             = &errHTTP{40050, http.StatusBadRequest, "invalid request: invalid e-mail address", "https://ntfy.sh/docs/publish/#e-mail-notifications", nil}
+	errHTTPBadRequestEmailVerificationLinkInvalid    = &errHTTP{40051, http.StatusBadRequest, "invalid request: email verification link invalid or expired", "", nil}
+	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}
@@ -151,6 +158,8 @@ var (
 	errHTTPConflictPhoneNumberExists                 = &errHTTP{40904, http.StatusConflict, "conflict: phone number already exists", "", nil}
 	errHTTPConflictProvisionedUserChange             = &errHTTP{40905, http.StatusConflict, "conflict: cannot change or delete provisioned user", "", nil}
 	errHTTPConflictProvisionedTokenChange            = &errHTTP{40906, http.StatusConflict, "conflict: cannot change or delete provisioned token", "", nil}
+	errHTTPConflictEmailExists                       = &errHTTP{40907, http.StatusConflict, "conflict: email address already exists", "", nil}
+	errHTTPConflictEmailPrimaryElsewhere             = &errHTTP{40908, http.StatusConflict, "conflict: email address is the primary email on another account", "", nil}
 	errHTTPGonePhoneVerificationExpired              = &errHTTP{41001, http.StatusGone, "phone number verification expired or does not exist", "", nil}
 	errHTTPEntityTooLargeAttachment                  = &errHTTP{41301, http.StatusRequestEntityTooLarge, "attachment too large, or bandwidth limit reached", "https://ntfy.sh/docs/publish/#limitations", nil}
 	errHTTPEntityTooLargeMatrixRequest               = &errHTTP{41302, http.StatusRequestEntityTooLarge, "Matrix request is larger than the max allowed length", "", nil}
@@ -160,11 +169,12 @@ var (
 	errHTTPTooManyRequestsLimitSubscriptions         = &errHTTP{42903, http.StatusTooManyRequests, "limit reached: too many active subscriptions", "https://ntfy.sh/docs/publish/#limitations", nil}
 	errHTTPTooManyRequestsLimitTotalTopics           = &errHTTP{42904, http.StatusTooManyRequests, "limit reached: the total number of topics on the server has been reached, please contact the admin", "https://ntfy.sh/docs/publish/#limitations", nil}
 	errHTTPTooManyRequestsLimitAttachmentBandwidth   = &errHTTP{42905, http.StatusTooManyRequests, "limit reached: daily bandwidth reached", "https://ntfy.sh/docs/publish/#limitations", nil}
-	errHTTPTooManyRequestsLimitAccountCreation       = &errHTTP{42906, http.StatusTooManyRequests, "limit reached: too many accounts created", "https://ntfy.sh/docs/publish/#limitations", nil} // FIXME document limit
+	errHTTPTooManyRequestsLimitAccountActions        = &errHTTP{42906, http.StatusTooManyRequests, "limit reached: too many account requests", "https://ntfy.sh/docs/publish/#limitations", nil} // FIXME document limit
 	errHTTPTooManyRequestsLimitReservations          = &errHTTP{42907, http.StatusTooManyRequests, "limit reached: too many topic reservations for this user", "", nil}
 	errHTTPTooManyRequestsLimitMessages              = &errHTTP{42908, http.StatusTooManyRequests, "limit reached: daily message quota reached", "https://ntfy.sh/docs/publish/#limitations", nil}
 	errHTTPTooManyRequestsLimitAuthFailure           = &errHTTP{42909, http.StatusTooManyRequests, "limit reached: too many auth failures", "https://ntfy.sh/docs/publish/#limitations", nil} // FIXME document limit
 	errHTTPTooManyRequestsLimitCalls                 = &errHTTP{42910, http.StatusTooManyRequests, "limit reached: daily phone call quota reached", "https://ntfy.sh/docs/publish/#limitations", nil}
+	errHTTPTooManyRequestsLimitTopicCreation         = &errHTTP{42911, http.StatusTooManyRequests, "limit reached: too many new topics, please wait", "https://ntfy.sh/docs/publish/#limitations", nil}
 	errHTTPInternalError                             = &errHTTP{50001, http.StatusInternalServerError, "internal server error", "", nil}
 	errHTTPInternalErrorInvalidPath                  = &errHTTP{50002, http.StatusInternalServerError, "internal server error: invalid path", "", nil}
 	errHTTPInternalErrorMissingBaseURL               = &errHTTP{50003, http.StatusInternalServerError, "internal server error: base-url must be be configured for this feature", "https://ntfy.sh/docs/config/", nil}

server/file_cache.go

@@ -1,128 +0,0 @@
-package server
-
-import (
-	"errors"
-	"fmt"
-	"heckel.io/ntfy/v2/log"
-	"heckel.io/ntfy/v2/model"
-	"heckel.io/ntfy/v2/util"
-	"io"
-	"os"
-	"path/filepath"
-	"regexp"
-	"sync"
-)
-
-var (
-	fileIDRegex      = regexp.MustCompile(fmt.Sprintf(`^[-_A-Za-z0-9]{%d}$`, model.MessageIDLength))
-	errInvalidFileID = errors.New("invalid file ID")
-	errFileExists    = errors.New("file exists")
-)
-
-type fileCache struct {
-	dir              string
-	totalSizeCurrent int64
-	totalSizeLimit   int64
-	mu               sync.Mutex
-}
-
-func newFileCache(dir string, totalSizeLimit int64) (*fileCache, error) {
-	if err := os.MkdirAll(dir, 0700); err != nil {
-		return nil, err
-	}
-	size, err := dirSize(dir)
-	if err != nil {
-		return nil, err
-	}
-	return &fileCache{
-		dir:              dir,
-		totalSizeCurrent: size,
-		totalSizeLimit:   totalSizeLimit,
-	}, nil
-}
-
-func (c *fileCache) Write(id string, in io.Reader, limiters ...util.Limiter) (int64, error) {
-	if !fileIDRegex.MatchString(id) {
-		return 0, errInvalidFileID
-	}
-	log.Tag(tagFileCache).Field("message_id", id).Debug("Writing attachment")
-	file := filepath.Join(c.dir, id)
-	if _, err := os.Stat(file); err == nil {
-		return 0, errFileExists
-	}
-	f, err := os.OpenFile(file, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0600)
-	if err != nil {
-		return 0, err
-	}
-	defer f.Close()
-	limiters = append(limiters, util.NewFixedLimiter(c.Remaining()))
-	limitWriter := util.NewLimitWriter(f, limiters...)
-	size, err := io.Copy(limitWriter, in)
-	if err != nil {
-		os.Remove(file)
-		return 0, err
-	}
-	if err := f.Close(); err != nil {
-		os.Remove(file)
-		return 0, err
-	}
-	c.mu.Lock()
-	c.totalSizeCurrent += size
-	mset(metricAttachmentsTotalSize, c.totalSizeCurrent)
-	c.mu.Unlock()
-	return size, nil
-}
-
-func (c *fileCache) Remove(ids ...string) error {
-	for _, id := range ids {
-		if !fileIDRegex.MatchString(id) {
-			return errInvalidFileID
-		}
-		log.Tag(tagFileCache).Field("message_id", id).Debug("Deleting attachment")
-		file := filepath.Join(c.dir, id)
-		if err := os.Remove(file); err != nil {
-			log.Tag(tagFileCache).Field("message_id", id).Err(err).Debug("Error deleting attachment")
-		}
-	}
-	size, err := dirSize(c.dir)
-	if err != nil {
-		return err
-	}
-	c.mu.Lock()
-	c.totalSizeCurrent = size
-	c.mu.Unlock()
-	mset(metricAttachmentsTotalSize, size)
-	return nil
-}
-
-func (c *fileCache) Size() int64 {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	return c.totalSizeCurrent
-}
-
-func (c *fileCache) Remaining() int64 {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	remaining := c.totalSizeLimit - c.totalSizeCurrent
-	if remaining < 0 {
-		return 0
-	}
-	return remaining
-}
-
-func dirSize(dir string) (int64, error) {
-	entries, err := os.ReadDir(dir)
-	if err != nil {
-		return 0, err
-	}
-	var size int64
-	for _, e := range entries {
-		info, err := e.Info()
-		if err != nil {
-			return 0, err
-		}
-		size += info.Size()
-	}
-	return size, nil
-}

server/file_cache_test.go

@@ -1,76 +0,0 @@
-package server
-
-import (
-	"bytes"
-	"fmt"
-	"github.com/stretchr/testify/require"
-	"heckel.io/ntfy/v2/util"
-	"os"
-	"strings"
-	"testing"
-)
-
-var (
-	oneKilobyteArray = make([]byte, 1024)
-)
-
-func TestFileCache_Write_Success(t *testing.T) {
-	dir, c := newTestFileCache(t)
-	size, err := c.Write("abcdefghijkl", strings.NewReader("normal file"), util.NewFixedLimiter(999))
-	require.Nil(t, err)
-	require.Equal(t, int64(11), size)
-	require.Equal(t, "normal file", readFile(t, dir+"/abcdefghijkl"))
-	require.Equal(t, int64(11), c.Size())
-	require.Equal(t, int64(10229), c.Remaining())
-}
-
-func TestFileCache_Write_Remove_Success(t *testing.T) {
-	dir, c := newTestFileCache(t) // max = 10k (10240), each = 1k (1024)
-	for i := 0; i < 10; i++ {     // 10x999 = 9990
-		size, err := c.Write(fmt.Sprintf("abcdefghijk%d", i), bytes.NewReader(make([]byte, 999)))
-		require.Nil(t, err)
-		require.Equal(t, int64(999), size)
-	}
-	require.Equal(t, int64(9990), c.Size())
-	require.Equal(t, int64(250), c.Remaining())
-	require.FileExists(t, dir+"/abcdefghijk1")
-	require.FileExists(t, dir+"/abcdefghijk5")
-
-	require.Nil(t, c.Remove("abcdefghijk1", "abcdefghijk5"))
-	require.NoFileExists(t, dir+"/abcdefghijk1")
-	require.NoFileExists(t, dir+"/abcdefghijk5")
-	require.Equal(t, int64(7992), c.Size())
-	require.Equal(t, int64(2248), c.Remaining())
-}
-
-func TestFileCache_Write_FailedTotalSizeLimit(t *testing.T) {
-	dir, c := newTestFileCache(t)
-	for i := 0; i < 10; i++ {
-		size, err := c.Write(fmt.Sprintf("abcdefghijk%d", i), bytes.NewReader(oneKilobyteArray))
-		require.Nil(t, err)
-		require.Equal(t, int64(1024), size)
-	}
-	_, err := c.Write("abcdefghijkX", bytes.NewReader(oneKilobyteArray))
-	require.Equal(t, util.ErrLimitReached, err)
-	require.NoFileExists(t, dir+"/abcdefghijkX")
-}
-
-func TestFileCache_Write_FailedAdditionalLimiter(t *testing.T) {
-	dir, c := newTestFileCache(t)
-	_, err := c.Write("abcdefghijkl", bytes.NewReader(make([]byte, 1001)), util.NewFixedLimiter(1000))
-	require.Equal(t, util.ErrLimitReached, err)
-	require.NoFileExists(t, dir+"/abcdefghijkl")
-}
-
-func newTestFileCache(t *testing.T) (dir string, cache *fileCache) {
-	dir = t.TempDir()
-	cache, err := newFileCache(dir, 10*1024)
-	require.Nil(t, err)
-	return dir, cache
-}
-
-func readFile(t *testing.T, f string) string {
-	b, err := os.ReadFile(f)
-	require.Nil(t, err)
-	return string(b)
-}

server/log.go

@@ -16,23 +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"
-	tagFileCache    = "file_cache"
-	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/ntfy.openrc

@@ -0,0 +1,49 @@
+#!/sbin/openrc-run
+
+# OpenRC service configuration for ntfy Server. 
+# Should be placed in /etc/init.d/ as "ntfy" or "ntfy-server" (no extension), owned by root:root and with permissions 755.
+# Assumes an ntfy system user and group have been created, for example using this command:
+# useradd --system --home-dir /var/lib/ntfy --shell /bin/false --comment "User for the simple HTTP-based pub-sub notification service" ntfy
+
+name=$RC_SVCNAME
+description="ntfy server"
+
+command="/usr/local/bin/ntfy"
+command_background=true
+command_args="serve"
+command_user="ntfy:ntfy"
+extra_started_commands="reload"
+
+pidfile="/run/${RC_SVCNAME}/${RC_SVCNAME}.pid"
+
+# Changes the hard number of open files (nofile) limit to 2048 for the service.
+rc_ulimit="-n 2048"
+
+# Allows the service to bind to privileged ports (<1024).
+capabilities="^cap_net_bind_service"
+
+error_log="/var/log/ntfy.log"
+
+# Service dependencies
+depend() {
+	use net
+	after firewall
+}
+
+# Check for - and if necessary - create required files and folders. Might require some adjustment dependings on the content of the server.yml file.
+start_pre() {
+	checkpath -f --owner "$command_user" --mode 0644 \
+		/var/log/ntfy.log
+	checkpath -d --owner "$command_user" --mode 0750 \
+		/run/ntfy/
+	checkpath -d --owner "$command_user" --mode 0755 \
+		/var/lib/ntfy/
+	checkpath -d --owner "$command_user" --mode 0750 \
+		/var/cache/ntfy/
+}
+
+reload() {
+	ebegin "Reloading $RC_SVCNAME's configuration"
+	start-stop-daemon --signal SIGHUP --pidfile "${pidfile}"
+	eend $? "Failed to reload $RC_SVCNAME's configuration"
+}

server/ntfy.service

@@ -10,6 +10,18 @@ ExecReload=/bin/kill --signal HUP $MAINPID
 Restart=on-failure
 AmbientCapabilities=CAP_NET_BIND_SERVICE
 LimitNOFILE=10000
+PrivateDevices=true
+ProtectClock=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectKernelLogs=true
+RestrictRealtime=true
+ProtectHostname=true
+
+# These will be added in a future update.
+# ProtectSystem=full
+# PrivateTmp=true
+
 
 [Install]
 WantedBy=multi-user.target