From 483c24b565e4b1cc1a36f33d08e24bfd9b09ab0c Mon Sep 17 00:00:00 2001 From: Phil Date: Tue, 10 Nov 2026 14:17:30 -0700 Subject: [PATCH] docs: ADR-074 notifications through Apprise (proposed) Co-Authored-By: Claude Opus 5.5 --- docs/decisions/ADR-074-notifications.md | 144 ++++++++++++++++++++++++ docs/decisions/INDEX.md | 7 +- docs/projectplan/BACKLOG.md | 5 + 3 files changed, 153 insertions(+), 3 deletions(-) create mode 100644 docs/decisions/ADR-074-notifications.md diff --git a/docs/decisions/ADR-074-notifications.md b/docs/decisions/ADR-074-notifications.md new file mode 100644 index 0000000..0ae468b --- /dev/null +++ b/docs/decisions/ADR-074-notifications.md @@ -0,0 +1,144 @@ +# ADR-074: Notifications through Apprise + +## Status + +Proposed (2026-11-10, for v2.14.0) + +## Context + +Responses now reach a note from two places: received webmentions +(ADR-063) and backfeed from the crossposts (ADR-073). The owner only finds +out about them by opening the site or the admin. Crossposts that finally +fail, and silos that refuse a backfeed credential, are just as invisible. + +Owners use different notification services. The production site uses +Gotify (read on iOS through iGotify). Others use ntfy, Pushover, email, +Matrix, Discord and so on. [Apprise](https://github.com/caronc/apprise) +covers about 100 of them behind one URL syntax (`gotifys://host/token`, +`ntfys://topic`, `mailtos://…`), both as a Python library and as a +separate HTTP server (apprise-api). + +Options considered: + +1. **Gotify only.** Simplest for this site, no use to anyone else. +2. **Post to an apprise-api server.** Standard, but every owner needs one + running, and messages take an extra hop. +3. **Embed the Apprise library.** Sends straight to each service; an owner + who prefers a central apprise-api can still use its `apprise://` / + `apprises://` URL. +4. **Gotify plus a generic JSON webhook, hand-written.** No dependency, but + every other service needs glue the owner has to write. + +## Decision + +### 1. Embed Apprise + +StarPunk depends on the `apprise` package and sends with it directly. +`NOTIFY_URLS` holds one or more Apprise URLs (space- or comma-separated); +each message goes to all of them. With no URLs, notifications are off and +nothing else changes. + +### 2. What can be notified + +`NOTIFY_EVENTS` is a comma-separated list. Default: +`reply,mention,quote,problems`. + +| Event | Sent when | +|---|---| +| `reply`, `mention`, `quote`, `like`, `repost`, `bookmark` | a response of that type is first shown on a note, or first awaits moderation (received webmention or backfeed alike) | +| `problems` | a crosspost fails for good (permanent error or last attempt), or a silo refuses the backfeed credential (ADR-073 Decision 9) | + +### 3. Messages + +Markdown, so services that render it (Gotify, iGotify, ntfy, Matrix…) +show links; others get the text. + +- **Replies, mentions, quotes:** one message each. Title "↩ Reply from Ana + Lima via Bluesky" (or "💬 Mention from …", "❝ Quote from …"); body the + response text (plain, up to 300 characters), then a link to the note's + responses (`#responses`). Normal priority. +- **Likes, reposts, bookmarks:** grouped per note and type in each pass: + "♥ 3 new likes on 'Starpunk now supports…'", with up to five names and a + link to the note. Low priority. +- **Awaiting moderation:** when `WEBMENTION_AUTO_APPROVE` is off, the title + says so and the link goes to the admin webmention page instead. +- **Problems:** "⚠ Crosspost to Bluesky failed" / "⚠ Backfeed for Threads + stopped" with the error and a link to the note's edit page or the + Webmentions page. High priority. + +Priority is passed per message where the service supports it (Gotify maps +low/normal/high to 0/5/8). Apprise's Gotify plugin has no click-through +link, so the link is in the text. + +### 4. Delivery + +- New column `webmentions.notified_at`. A sweep finds responses with + `notified_at IS NULL`, `validation_status = 'valid'`, a moderation status + of `approved` or `pending`, and a type in `NOTIFY_EVENTS`, sends them, + and sets `notified_at`. Types not selected are marked without sending. +- The sweep runs in the webmention worker loop, which already runs in one + process at a time (its file lock), so nothing is sent twice by several + gunicorn workers. It handles received and backfed responses alike. +- A failed send leaves `notified_at` empty, so the next pass (about 10 + seconds later) retries, with backoff up to 15 minutes. Responses older + than 24 hours that still haven't gone out are marked and dropped, with a + warning, so an outage doesn't end in a flood. The last error is shown on + the admin Webmentions page. +- Problems are sent at the moment they happen (from the syndication and + backfeed workers) and not retried: they are also in the log and admin. +- Sending never blocks or breaks validation, crossposting or backfeed. + +### 5. No floods from history + +- Migration 021 sets `notified_at` on every existing response. +- Responses stored by a backfill check (ADR-073 Decision 8) are stored with + `notified_at` set. +- So are responses found on a crosspost's first check when its note is more + than a day old (copies linked after the fact). +- Grouping (Decision 3) keeps a busy note to one like message per pass. + +### 6. Admin + +- **Send test notification** on the admin Webmentions page sends a test + message to every URL and reports each result. +- The page shows whether notifications are on, which events are selected, + and the last send error. + +### 7. Configuration + +| Setting | Default | Meaning | +|---|---|---| +| `NOTIFY_URLS` | empty (off) | Apprise URLs, space- or comma-separated | +| `NOTIFY_EVENTS` | `reply,mention,quote,problems` | which events are sent | + +Settings stay in the environment, like the rest of StarPunk's (ADR-052). +URLs contain tokens and belong with the other secrets. + +## Consequences + +- One new dependency, `apprise`, with its own (requests, PyYAML, click, + Markdown, certifi). It must install on Python 3.14 in the container + image; this is checked before the release. +- Owners can send to almost any service without writing glue, directly or + through apprise-api. +- Each response is notified at most once, a few seconds after it appears, + and only if its type is selected. +- Apprise opens outbound connections to whatever URLs the owner configures, + outside the SSRF-safe fetcher. That is intended: the owner chooses these + URLs, as with the crosspost targets. A service behind the same reverse + proxy as StarPunk may need the deployment's internal-address entry + (`extra_hosts`), as GoToSocial does. +- Notification text includes other people's names and words, sent to the + owner's own services only. + +## Alternatives considered + +- **Gotify only / hand-written webhook.** See Context, options 1 and 4: no + dependency, but each service beyond Gotify needs glue the owner writes. +- **apprise-api only.** See option 2. Still possible through an + `apprises://` URL. +- **Sending from where responses are stored** (webmention worker, + backfeed) instead of a sweep. Two code paths, no retry, and backfeed + runs in every gunicorn worker. Rejected. +- **Choosing events in the admin UI.** Possible later; the environment is + where StarPunk's settings live today. diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md index 99c2d29..bc38266 100644 --- a/docs/decisions/INDEX.md +++ b/docs/decisions/INDEX.md @@ -5,8 +5,8 @@ records one decision: its context, what was decided, and the consequences. Superseded ADRs are kept as history; their Status line names the ADR that replaced them. -**Total ADR files**: 69 (68 numbers: ADR-001 to ADR-044 and ADR-050 to -ADR-073, with two files numbered ADR-012). See [Numbering](#numbering). +**Total ADR files**: 70 (69 numbers: ADR-001 to ADR-044 and ADR-050 to +ADR-074, with two files numbered ADR-012). See [Numbering](#numbering). Status values: **Accepted** (in force), **Superseded** (replaced by a later ADR), **Deprecated** (withdrawn, nothing replaces it; none at present), @@ -85,6 +85,7 @@ See also [IndieWeb protocols](../architecture/indieweb-protocols.md). | [066](ADR-066-bluesky-syndication.md) | Crossposting to Bluesky | Accepted | Bluesky as a second crosspost target (v2.2.0). | | [069](ADR-069-threads-syndication.md) | Crossposting to Threads | Accepted | Threads as a third target, with automatic token refresh (v2.6.0). | | [070](ADR-070-crosspost-links-and-cards.md) | Links and link cards in crossposts | Accepted | Keep note links in crossposts and build link cards for the linked page (v2.6.3). | +| [074](ADR-074-notifications.md) | Notifications through Apprise | Proposed | Notify the owner of new responses and crosspost/backfeed problems via the embedded Apprise library (planned v2.14.0). | | [073](ADR-073-backfeed.md) | Backfeed of responses to crossposts | Accepted | Poll GoToSocial, Bluesky and Threads for responses to crossposts and store them as webmentions; admin backfill (v2.13.0). | ### Authentication (current) @@ -168,7 +169,7 @@ was carried out and is not itself superseded. ## How to create a new ADR -1. Use the next number after the highest existing one (currently ADR-074). +1. Use the next number after the highest existing one (currently ADR-075). 2. Name it `ADR-NNN-brief-descriptive-title.md`. 3. Follow the format of recent ADRs (e.g. ADR-070, ADR-071): diff --git a/docs/projectplan/BACKLOG.md b/docs/projectplan/BACKLOG.md index f7b3ff9..e371904 100644 --- a/docs/projectplan/BACKLOG.md +++ b/docs/projectplan/BACKLOG.md @@ -74,6 +74,11 @@ None open. - **Where**: `templates/base.html` - **Source**: Documentation refresh 2026-11-03 +### Notifications +- **Description**: Notify the owner of new replies, mentions, quotes (and optionally likes, reposts, bookmarks) and of crosspost/backfeed problems, through the embedded Apprise library (`NOTIFY_URLS`, `NOTIFY_EVENTS`). Decided in ADR-074 (Proposed). +- **Where**: new `starpunk/notifications.py`, `starpunk/webmention_worker.py`, `starpunk/backfeed.py`, `starpunk/syndication.py`, migration 021 +- **Source**: Owner request 2026-11-10; ADR-074 + ### Tag-filtered feeds - **Description**: Tag pages are h-feeds and WebSub topics, but there are no RSS, Atom or JSON feeds per tag (for example `/tag/python/feed.atom`). Tag pages also have no pagination, and the editor has no tag autocomplete. - **Where**: `starpunk/routes/public.py`, `starpunk/feeds/`, `templates/admin/`