Changeset 96c714f in Klonkt for README.md

Timestamp:

07/22/2026 07:12:11 AM (7 weeks ago)

Author:

Robin <roboburr@…>

Branches:

main

Children:

9a00f28

Parents:

8240e80

git-author:

Robin <roboburr@…> (07/22/2026 07:11:54 AM)

git-committer:

Robin <roboburr@…> (07/22/2026 07:12:11 AM)

Message:

Feature: web push slice 4, burst throttle + docs

• Burst throttle: a wave of likes or a mass-follow becomes one ping, not a wave of pushes. Per (user, type) at most one push per window (like/boost 300s, follow 60s, reply/dm 30s, test never throttled); extras drop silently — the events themselves still land in Berichten, only the ping is deduped. In-memory (one process; a restart costs at most one extra ping). Pure throttled() exported and pinned by test.
• README: push notifications feature bullet, VAPID_* in the config table, storage/.vapid in the auto-generated-secrets + backup section (restoring without it silently breaks every subscription).
• .env.example: VAPID block in the SESSION_SECRET/PAID_SECRET style.

Pruning (404/410 → row deleted) and the iOS install hint already landed in
slices 1-2; this closes the plan from docs/webpush-design.md.

Changed files:
src/services/PushService.js

• throttled() + window table; notifyUser checks it first

test/push.test.js

• throttle windows, per-type/per-user independence, test bypass

README.md

• feature bullet, VAPID config row, backup warning

.env.example

• VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY / VAPID_SUBJECT

-robo
Co-Authored-By: Claude Opus 4.8 <noreply@…>

File:

• README.md (modified) (4 diffs)

README.md

@@ -22 +22 @@
   sites, Mastodon, PeerTube — any fediverse server) and their public posts appear in your
   Circle. Decentralized, no central platform — built on ActivityPub.
+- **Push notifications** — a browser/PWA notification for new followers, replies,
+  mentions, likes, boosts and private messages, even with the site closed.
+  Self-hosted Web Push (VAPID): payloads are encrypted end-to-end to your
+  browser, and private messages never carry their text in the push.
 - **Themes & languages** — multiple palettes (light + dark), interface in EN/NL/DE.
 - **Installable (PWA)**, **privacy-first** (self-hosted fonts, no tracking).
@@ -168 +172 @@
 | `PUBLIC_BASE_URL` | ✅ | Canonical URL (e.g. `https://yourdomain.com`) |
 | `PAID_SECRET` | auto | Encrypts the stored Patreon secrets for **paid posts**. Leave empty to auto-generate on first use (`storage/.paid-secret`), or set your own ≥16-char string. |
+| `VAPID_PUBLIC_KEY` / `VAPID_PRIVATE_KEY` / `VAPID_SUBJECT` | auto | Identify this server to browser push services (**push notifications**). Leave empty to auto-generate on first use (`storage/.vapid`). |
 | `SMTP_HOST` / `_PORT` / `_USER` / `_PASS` / `_FROM` | — | Email for password reset + newsletter |
 | `KLONKT_DEFAULT_LANG` | — | Default language for visitors (`en`/`nl`/`de`) |
@@ -182 +187 @@
 - `PAID_SECRET` → `storage/.paid-secret` (encrypts the stored Patreon secrets for
   paid posts)
+- `VAPID_*` → `storage/.vapid` (identifies this server to browser push services;
+  regenerating it would silently break every existing push subscription)
 
 The paid-posts key lives **outside** the database on purpose: encrypting the
@@ -189 +196 @@
 **Back up the whole `storage/` directory** (database, media *and* these key
 files). Restoring the database without `storage/.paid-secret` leaves the stored
-Patreon secrets unreadable — you'd have to reconnect Patreon.
+Patreon secrets unreadable — you'd have to reconnect Patreon. Restoring without
+`storage/.vapid` breaks push subscriptions — every device would have to re-enable
+notifications.
 
 ## Stack