Merge branch 'docs/v2.14.0-notifications-adr': ADR-074 notifications

This commit is contained in:
Phil committed 2026-11-10 14:25:58 -07:00
commit 815aff5443
3 files changed
+164 -3

No files matched your search

+155
View File
@@ -0,0 +1,155 @@
# ADR-074: Notifications through Apprise
## Status
Accepted (v2.14.0, 2026-11-10)
## 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 (`<permalink>#responses`).
- **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.
- **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.
Apprise's Gotify plugin has no click-through link, so the link is in the
text.
### 3a. Priority
Every message is sent with the same priority, `NOTIFY_PRIORITY` (default
`normal`). Apprise takes priority as a `priority` argument in each service
URL, with values that differ by service, so StarPunk adds
`priority=<NOTIFY_PRIORITY>` to each URL in `NOTIFY_URLS` that doesn't set
one itself; a URL can still set its own. Apprise's names (`low`,
`moderate`, `normal`, `high`, `emergency`) work for most services; Gotify
also takes 0–10 (it maps the names to 0, 3, 5, 8, 10). Different
priorities per event can come later.
### 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 |
| `NOTIFY_PRIORITY` | `normal` | priority of every message, added to URLs that don't set one |
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.
+4 -3
View File
@@ -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 | Accepted | Notify the owner of new responses and crosspost/backfeed problems via the embedded Apprise library (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):
+5
View File
@@ -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/`