Skip to main content
tavrn Docs

Web push

The node sends web push notifications (RFC 8030 push, RFC 8291 message encryption, RFC 8292 VAPID; protocol: PROTOCOL.md §6d, capability push.webpush in the discovery document) to browsers and installed web apps (PWAs), so users learn about new messages, mentions and calls while no tab of the web client is open.

VariableDefaultMeaning
TAVRN_PUSHonoff switches web push off.
TAVRN_PUSH_CONTACTthe node’s public URL (TAVRN_PUBLIC_URL)The VAPID contact (a mailto: address or an https:// URL, at most 256 characters) that push services may use to reach the operator, e.g. mailto:admin@example.org.
TAVRN_PUSH_MAX_PER_MINUTE10Pushes per user and minute (1–1000).

How it behaves:

  • When: a push is only sent when the user has no open connection to the node, except for incoming calls: call rings are pushed also while a connection is open (a phone keeps the connection of a frozen background tab open), and the web client’s service worker shows them only while no page of the client is visible. Besides TAVRN_PUSH_MAX_PER_MINUTE there is at most one push per conversation and user every 30 seconds (call rings excepted).
  • Content: push payloads are encrypted end-to-end to the browser (RFC 8291); the push services only see ciphertext. For encrypted conversations a push never contains message content, only the conversation, its name and the sender’s display name. For unencrypted conversations it carries a text preview (at most 120 characters) only when the user turned on “show message text in push notifications” (default off).
  • The VAPID key <data>/keys/vapid.key (a P-256 private key, PKCS#8 PEM, mode 0600) is created at the first start. Back it up with the other key files. If it is lost or replaced, every browser subscription becomes invalid and users must re-enable push on each device; nothing else is lost.
  • Outbound traffic: the node sends HTTPS POST requests to the push services of the browser vendors. The endpoints are chosen by the browsers (hosts of Google, Mozilla, Apple, Microsoft and others), so egress HTTPS to the internet must be allowed. Endpoints on private or loopback addresses are refused.
  • Remote conversations: notifications for rooms on other nodes arrive through the federation notify hint at the user’s home node, which sends the push (only DMs, group DMs, mentions and calls for remote conversations). A channel set to “all messages” in a room on another node therefore does not push for ordinary messages; the client says so in the notification settings. This is a design decision: subscriptions stay with the home node, which holds the settings (PROTOCOL.md §6d).
  • Reports: room moderators and node admins without an open connection get a push for every new report (its kind and room only, at most one per room every 30 seconds); each of them can turn it off (“Reports” in the notification settings).
  • Several instances: any instance sends; the rate counters live in Valkey.
  • Load: pushes are queued and sent in the background, never on the request path. Ordinary channel messages have a queue of their own, so a busy channel never delays or drops the pushes of DMs, mentions, calls and reports. A message’s recipients are loaded together (a few statements per message, whatever the room’s size), members who were pushed for the conversation within the last 30 seconds are skipped first, and the deliveries to different users run in parallel. A user’s subscriptions are sent to at once and given 10 seconds together, and while a push to a user is still under way the next one for them is skipped, so endpoints that never answer cannot hold the senders. An endpoint that fails is held back (30 seconds, doubling up to 6 hours) and deleted after 30 failures in a row; registering it again keeps its count.
  • iPhone and iPad: users have to add the web app to the home screen (install it as a PWA) before Safari allows push.
  • Monitoring: tavrn_push_sent_total and tavrn_push_failed_total (Metrics and health). Many failures usually mean blocked egress or a replaced vapid.key.

This page is generated from tavrn-node/docs/HANDBOOK.md (AGPL-3.0-only) when the website is built; its links were adapted for this site.