Changeset 96c714f in Klonkt

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@…>

Files:

• .env.example (modified) (1 diff)
• README.md (modified) (4 diffs)
• src/services/PushService.js (modified) (2 diffs)
• test/push.test.js (modified) (1 diff)

.env.example

@@ -15 +15 @@
 # so a database dump alone stays useless). Or set your own: openssl rand -base64 32
 PAID_SECRET=
+# Web-push (notificaties) VAPID keys. Leave EMPTY to auto-generate on first use
+# (saved to storage/.vapid). Do NOT rotate: new keys break every subscription.
+VAPID_PUBLIC_KEY=
+VAPID_PRIVATE_KEY=
+VAPID_SUBJECT=
 DATABASE_PATH=./storage/database.sqlite
 MEDIA_PATH=./storage/media

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

src/services/PushService.js

@@ -118 +118 @@
 }
 
+// Burst throttle: a wave of likes or a mass-follow must not become a wave of
+// pushes. Per (user, type) at most one push per window; extras drop silently
+// (the events themselves are still in Berichten — only the ping is deduped).
+// In-memory is fine: one process, and a restart just means one extra ping.
+const THROTTLE_SECONDS = { follow: 60, reply: 30, dm: 30, like: 300, boost: 300, test: 0 };
+const _lastPush = new Map();
+export function throttled(userId, type, nowSeconds = Math.floor(Date.now() / 1000)) {
+  const windowS = THROTTLE_SECONDS[type] ?? 60;
+  if (!windowS) return false;
+  const key = `${userId}:${type}`;
+  const prev = _lastPush.get(key) || 0;
+  if (nowSeconds - prev < windowS) return true;
+  _lastPush.set(key, nowSeconds);
+  return false;
+}
+
 // Notify one user on all their devices, honouring per-type preferences.
 // type ∈ {follow, reply, like, boost, dm, test}. Fire-and-forget at call sites.
 export async function notifyUser(userId, { type, title, body, url }) {
   if (!(await pushReady())) return 0;
+  if (throttled(userId, type)) return 0;
   const rows = db.prepare('SELECT * FROM push_subscriptions WHERE user_id = ?').all(userId);
   let sent = 0;
@@ -143 +160 @@
 
 export default {
-  publicKey, pushReady, DEFAULT_ALERTS,
+  publicKey, pushReady, DEFAULT_ALERTS, throttled,
   saveSubscription, deleteSubscription, listSubscriptions, updateAlerts,
   notifyUser, notifySite,

test/push.test.js

@@ -65 +65 @@
 });
 
+test('burst throttle: one ping per window per (user,type); test type never throttles', () => {
+  assert.equal(Push.throttled('tu1', 'like', 1000), false);   // first passes
+  assert.equal(Push.throttled('tu1', 'like', 1100), true);    // within 300s window
+  assert.equal(Push.throttled('tu1', 'like', 1301), false);   // window elapsed
+  assert.equal(Push.throttled('tu1', 'boost', 1000), false);  // other type independent
+  assert.equal(Push.throttled('tu2', 'like', 1000), false);   // other user independent
+  assert.equal(Push.throttled('tu1', 'test', 1000), false);   // test bypasses
+  assert.equal(Push.throttled('tu1', 'test', 1001), false);
+});
+
 test('incomplete subscription payloads are refused', () => {
   assert.equal(Push.saveSubscription({ endpoint: '', userId: 'u1', p256dh: 'x', auth: 'y' }), false);