feat: public flood notifications over self-hosted ntfy

Anyone can now get push alerts on their phone without an account: the
monitor publishes to an ntfy server (one Go binary, ~30 MB RSS) and
subscribers pick topics in the free iOS/Android/web app.

Semantics are transitions, never state. One message when a gauge crosses
its warning or danger threshold, one all-clear when it drops back (0.10 m
hysteresis), nothing while it sits above. A three-day flood is two
messages; a quiet season is zero. Topics: ping-warning / ping-danger
(basin digest), ping-<station>-warning / -danger, ping-p1-outlook (opt-in:
model P(warning within 24 h) at P.1 rises through 50 %, clears below 25 %,
message says it is experimental), ping-status (feed stale >= 3 h /
recovered). Priority 5 on danger so it rings through Do Not Disturb.

src/notify.py runs once per collection cycle in the API process (leader
only, after the forecast precompute, same data the dashboard shows).
Last-sent state lives in a notification_state table so a restart never
re-sends; a failed publish leaves state untouched so the crossing is
retried next cycle instead of lost. Off unless NTFY_SERVER is set.

Dashboard: a "Get alerts" button (only when configured) opens a panel
with the server, per-topic cards, ntfy:// deep links and web links, app
store links and a disclaimer. EN + TH. GET /api/notifications feeds it.

scripts/install_ntfy.sh: .deb install, server.yml (loopback listen,
anonymous read, token-only write scoped to ping-*, 72 h cache, signup/
login/metrics off, tight visitor limits), systemd, user + token, .env.
Verified against ntfy 2.28.0: anon publish 403, token publish 200, token
on foreign topic 403, anon read 200, and a seeded crossing through the
real _notify_transitions path arrived in the topic with priority, tags,
click and action button. docs/NOTIFICATIONS.md has the deployment and
reverse-proxy notes. Tests: 10 for the state machine (159 total).

scripts/e2e_notify.py

@@ -0,0 +1,132 @@
+"""Drive the production notify path in-process: startup init -> seeded readings
+-> forecast cache -> _notify_transitions -> sqlite state -> real ntfy."""
+
+import asyncio
+import datetime
+import json
+import os
+import sys
+
+import requests
+
+os.environ.update(
+    DB_TYPE="sqlite",
+    WATER_DB_PATH=os.path.join(os.environ["LOCALAPPDATA"], "Temp", "smoke3.db"),
+    NTFY_SERVER="http://127.0.0.1:2586",
+    NTFY_TOKEN=os.environ.get("NTFY_TOKEN", ""),
+    NTFY_TOPIC_PREFIX="ping",
+)
+for f in ("smoke3.db",):
+    p = os.path.join(os.environ["LOCALAPPDATA"], "Temp", f)
+    if os.path.exists(p):
+        os.remove(p)
+
+from src import web_api  # noqa: E402
+from src.config import Config  # noqa: E402
+
+assert Config.NTFY_SERVER
+
+
+async def main():
+    # what the lifespan does at startup, minus the scheduler
+    from src import notify as notify_mod
+    from src.forecast_history import ForecastHistoryStore
+    from src.water_scraper_v3 import EnhancedWaterMonitorScraper
+
+    db_config = Config.get_database_config()
+    web_api.app_state["scraper"] = EnhancedWaterMonitorScraper(db_config)
+    store = ForecastHistoryStore(db_config["connection_string"], db_config["type"])
+    store.connect()
+    web_api.app_state["forecast_store"] = store
+    state = notify_mod.NotificationState(store.engine, store.db_type)
+    pub = notify_mod.NtfyPublisher(
+        Config.NTFY_SERVER, prefix=Config.NTFY_TOPIC_PREFIX, token=Config.NTFY_TOKEN
+    )
+    web_api.app_state["notify"] = (pub, state)
+
+    scraper = web_api.app_state["scraper"]
+    now = datetime.datetime.now().replace(minute=0, second=0, microsecond=0)
+
+    def seed(level_p1, level_p103, ts):
+        rows = [
+            {
+                "station_code": "P.1",
+                "station_id": 1,
+                "timestamp": ts,
+                "water_level": level_p1,
+                "discharge": 400.0,
+                "station_name_en": "Nawarat Bridge",
+                "station_name_th": "สะพานนวรัฐ",
+                "discharge_percent": 30.0,
+                "status": "active",
+            },
+            {
+                "station_code": "P.103",
+                "station_id": 2,
+                "timestamp": ts,
+                "water_level": level_p103,
+                "discharge": 300.0,
+                "station_name_en": "Ring Road 3",
+                "station_name_th": "วงแหวน 3",
+                "discharge_percent": 20.0,
+                "status": "active",
+            },
+        ]
+        scraper.db_adapter.save_measurements(rows)
+
+    def forecast(p):
+        with web_api.FORECAST_CACHE_LOCK:
+            web_api.FORECAST_CACHE["all"] = (
+                0,
+                [
+                    {
+                        "station_code": "P.1",
+                        "horizon_hours": 24,
+                        "p_warning": p,
+                        "predicted_max_level": 3.9,
+                        "source": "model",
+                    }
+                ],
+            )
+
+    def poll(topic):
+        out = []
+        for line in (
+            requests.get(f"{Config.NTFY_SERVER}/{topic}/json?poll=1", timeout=5)
+            .text.strip()
+            .splitlines()
+        ):
+            m = json.loads(line)
+            if m.get("event") == "message":
+                out.append(m.get("title") or m.get("message", "")[:40])
+        return out
+
+    # cycle 1: quiet
+    seed(1.6, 3.2, now - datetime.timedelta(hours=2))
+    forecast(0.02)
+    await web_api._notify_transitions()
+    # cycle 2: P.1 crosses warning, model outlook on
+    seed(3.75, 3.3, now - datetime.timedelta(hours=1))
+    forecast(0.7)
+    await web_api._notify_transitions()
+    # cycle 3: same state -> silence
+    seed(3.80, 3.3, now)
+    forecast(0.65)
+    await web_api._notify_transitions()
+
+    print("ping-p1-warning:", poll("ping-p1-warning"))
+    print("ping-warning:   ", poll("ping-warning"))
+    print("ping-p1-outlook:", poll("ping-p1-outlook"))
+    print("ping-p103-warning:", poll("ping-p103-warning"))
+    from sqlalchemy import text
+
+    with store.engine.connect() as c:
+        print(
+            "state table:",
+            c.execute(
+                text("SELECT key, state, value FROM notification_state ORDER BY key")
+            ).fetchall(),
+        )
+
+
+asyncio.run(main())

scripts/install_ntfy.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# Install ntfy (https://ntfy.sh) as the public notification server for the
+# Ping River Monitor. Run as root on the monitor VPS. Idempotent.
+#
+#   NTFY_DOMAIN=ntfy.buildfor.life bash scripts/install_ntfy.sh
+#
+# What it does:
+#   - installs the ntfy .deb from the official GitHub release (single Go
+#     binary, ~30 MB RSS, sqlite message cache)
+#   - writes /etc/ntfy/server.yml: listens on 127.0.0.1:2586 only (put it
+#     behind your existing reverse proxy / Cloudflare tunnel), anonymous
+#     READ on all topics, WRITE only with a token
+#   - creates the `monitor` publishing user + token, writes NTFY_SERVER /
+#     NTFY_TOKEN into /opt/thailand-water-monitor/.env if not present
+#
+# Reverse proxy: forward https://$NTFY_DOMAIN -> http://127.0.0.1:2586 with
+# websockets enabled and a long/no read timeout (subscribers hold the
+# connection open). Caddy: `reverse_proxy 127.0.0.1:2586`. Cloudflare
+# tunnel: add a public hostname pointing at http://127.0.0.1:2586.
+set -euo pipefail
+
+NTFY_DOMAIN="${NTFY_DOMAIN:?set NTFY_DOMAIN, e.g. ntfy.buildfor.life}"
+NTFY_VERSION="${NTFY_VERSION:-2.28.0}"
+MONITOR_DIR="${MONITOR_DIR:-/opt/thailand-water-monitor}"
+LISTEN="${NTFY_LISTEN:-127.0.0.1:2586}"
+
+if ! command -v ntfy >/dev/null || [[ "$(ntfy --version 2>/dev/null | awk '{print $3}')" != "$NTFY_VERSION" ]]; then
+    tmp=$(mktemp -d)
+    curl -fsSL -o "$tmp/ntfy.deb" \
+        "https://github.com/binwiederhier/ntfy/releases/download/v${NTFY_VERSION}/ntfy_${NTFY_VERSION}_linux_amd64.deb"
+    dpkg -i "$tmp/ntfy.deb"
+    rm -rf "$tmp"
+fi
+
+install -d -m 755 /var/cache/ntfy /var/lib/ntfy
+cat > /etc/ntfy/server.yml <<EOF
+# Ping River Monitor notification server. Managed by scripts/install_ntfy.sh.
+base-url: "https://${NTFY_DOMAIN}"
+listen-http: "${LISTEN}"
+behind-proxy: true
+
+# Messages are kept so a phone that was offline still gets the crossing.
+cache-file: "/var/cache/ntfy/cache.db"
+cache-duration: "72h"
+
+# Everyone may subscribe; only the monitor (token) may publish.
+auth-file: "/var/lib/ntfy/user.db"
+auth-default-access: "read-only"
+
+# The monitor publishes a handful of messages per flood; be strict with
+# everything else so the box cannot be used as a free relay.
+visitor-request-limit-burst: 30
+visitor-request-limit-replenish: "10s"
+visitor-subscription-limit: 60
+visitor-message-daily-limit: 200
+attachment-cache-dir: ""
+enable-signup: false
+enable-login: false
+enable-metrics: false
+EOF
+
+systemctl enable --now ntfy
+systemctl restart ntfy
+sleep 1
+curl -fsS "http://${LISTEN}/v1/health" >/dev/null && echo "ntfy up on ${LISTEN}"
+
+# Publishing identity for the monitor
+if ! ntfy user list 2>/dev/null | grep -q '^user monitor (role'; then
+    NTFY_PASSWORD="$(openssl rand -base64 24)" ntfy user add --role=user monitor
+fi
+ntfy access monitor 'ping-*' write-only >/dev/null
+# 'ping-*' read stays anonymous via auth-default-access
+
+token=$(ntfy token list monitor 2>/dev/null | awk '/^- tk_/{print $2; exit}')  # '- tk_xxx (label), ...'
+if [[ -z "$token" ]]; then
+    token=$(ntfy token add --label "water-monitor" monitor | grep -oE 'tk_[A-Za-z0-9]+' | head -1)  # 'token tk_xxx created for user monitor'
+fi
+
+env_file="${MONITOR_DIR}/.env"
+if [[ -f "$env_file" ]] && ! grep -q '^NTFY_SERVER=' "$env_file"; then
+    {
+        echo ""
+        echo "# ntfy public notifications (scripts/install_ntfy.sh)"
+        echo "NTFY_SERVER=https://${NTFY_DOMAIN}"
+        echo "NTFY_TOPIC_PREFIX=ping"
+        echo "NTFY_TOKEN=${token}"
+    } >> "$env_file"
+    echo "wrote NTFY_* to ${env_file}; restart water-monitor to enable"
+else
+    echo "NTFY_TOKEN=${token}"
+fi
+
+echo
+echo "Subscribe test (anonymous read):  curl -s 'http://${LISTEN}/ping-status/json?poll=1'"
+echo "Publish test (needs token):       curl -s -H 'Authorization: Bearer ${token}' -d 'hello' http://${LISTEN}/ping-status"