PWA and Web Push
PWA and Web Push
public/manifest.webmanifest and public/sw.js make the app installable. The service worker caches the app shell and static assets, never /api/, and handles push and notificationclick.
How Web Push works
Web Push works in three parts:
- The client asks for browser permission, registers the service worker and subscribes with the VAPID public key.
push_subscriptionsandpush_prefspersist the subscription and per-account/folder preferences.- The
worker/cron Worker runs every 5 minutes and callsPOST /api/cron/notificationswithCRON_SECRET. That endpoint syncs the selected folders, detects new UIDs and sends encrypted Web Push messages with VAPID.
Setup
Generate a VAPID key pair:
npm run vapid
Add the secrets to the Pages project:
npx wrangler pages secret put VAPID_PUBLIC_KEY --project-name whelkmail
npx wrangler pages secret put VAPID_PRIVATE_KEY --project-name whelkmail
npx wrangler pages secret put CRON_SECRET --project-name whelkmail
VAPID_SUBJECT can be a plain variable such as mailto:[email protected].
Copy the cron worker template, set your Pages URL and deploy:
cp worker/wrangler.toml.example worker/wrangler.toml
# set APP_URL in worker/wrangler.toml to https://<your-project>.pages.dev
npx wrangler secret put CRON_SECRET -c worker/wrangler.toml
npm run cron:deploy
npm run cron:deploy creates the file from the template when it is missing and stops with a clear error while APP_URL is still empty or a placeholder.
The worker needs APP_URL and the same CRON_SECRET shared with the Pages app.
What the cron worker does
Every 5 minutes, in the same run, it:
- sends Web Push notifications for new messages;
- applies automatic forwarding rules;
- runs the optional provider cleanup;
- advances the per-account automatic background sync.
Enable notifications from Settings → Push notifications, background sync per account in Settings, and forwarding/deletion in the account/filter sections.
PWA assets
public/notification-badge.png (96x96) and public/notification-icon.png (192x192) are generated from the shell mark in public/whelkmail-logo.svg:
npm run icons
Android masks badge into a monochrome silhouette in the status bar and does not render SVG there, which is why both files are PNG and why the badge is white on a transparent background. The badge drops the thin decorative strokes of the logo: at status bar size they only add noise. After changing the files, bump CACHE in public/sw.js so installed clients pick up the new assets.
Release check
GET /api/update compares APP_VERSION (shared/version.ts, mirrored in package.json) with the latest release on WhelkMail/WhelkMail.
- The GitHub call runs in the Worker with an 8-second timeout, never in the browser, so no visitor IP or mailbox data leaves the deployment.
UPDATE_CHECK=offdisables it andGITHUB_TOKENoptionally raises the rate limit.- The check reads
/releases/latestfrom the API and falls back to the releases Atom feed when the API fails, so it does not depend on the API alone. - The answer is cached in
app_settings.update_checkfor 24 hours (15 minutes after a failure or when no release exists yet), so each deployment makes at most one request per day. - A cached copy is still served when GitHub is unreachable, and
GET /api/update?refresh=1(Settings → System → Check again) bypasses the cache. - Failures are logged from the Worker.
When the latest release is newer, the client shows a dismissible banner with the upgrade steps and a link to the upgrade guide; the dismissal is stored server-side (update_notice_dismissed) per release version. POST /api/update records it. GET /api/health exposes version too, so a tab left open on an older bundle can offer a reload when it sees a newer server.
The check is informational: it cannot update a deployment.