SPB Git

Repository Public

PUSH.md 12.1 KB 121 lines markdown

1# SP Mail Next — push notifications (operator guide)23Scope: APNs push for the native Apple apps, plus the server-side snooze / reminder notifications that ride the same queue. Contract: `ARCHITECTURE-NEXT.md` §3 D-N1, D-N2, D-N4 and §4.2, §4.3. Code: `server/src/next/apns.ts` (APNs client and pure functions), `server/src/next/push.ts` (routes, watcher hook, dispatcher), `server/src/next/snooze.ts` (snoozes and reminders), migration `db/migrations/004_push_snooze.sql`.45## 1. Configuration67| Variable | Meaning |8|---|---|9| `SPMAIL_APNS_KEY_FILE` | Path of the APNs authentication key (`AuthKey_XXXXXXXXXX.p8`, ES256 / P-256) downloaded once from the Apple Developer account (Certificates, Identifiers & Profiles → Keys → Apple Push Notifications service). Keep it outside the repository, mode `600`, readable by the backend user only |10| `SPMAIL_APNS_KEY_ID` | The 10-character key identifier shown next to the key |11| `SPMAIL_APNS_TEAM_ID` | The Apple Developer team identifier (`3YM54G49SN` for the SP Mail apps) |12| `SPMAIL_PUSH_BACKOFF` | Retry delays in seconds, default `5,30,120,600,3600` |13| `SPMAIL_APNS_HOST_OVERRIDE` | **Tests only.** Origin of a fake APNs server (`http://127.0.0.1:<port>`, cleartext HTTP/2). The backend refuses to start with this variable on an `https` origin |1415One key serves both environments and every bundle identifier of the team. The APNs host is chosen per device from the `environment` it registered with: `production` → `api.push.apple.com`, `sandbox` → `api.sandbox.push.apple.com` (port 443). The `apns-topic` is the device's `bundle_id`.1617Without the three `SPMAIL_APNS_*` values (or if the key file cannot be read or is not a P-256 key) push is **disabled**: the watcher hook enqueues nothing, the dispatcher does nothing, `POST /api/next/push/test` answers `{ "queued": 0 }` and `GET /api/next/push/status` answers `configured: false` with the reason in `last_error`. Nothing is ever simulated. Devices can still register; they start receiving once push is configured. A missing key file is re-read at most once per minute, a loaded key is kept until restart (restart the backend after rotating the key).1819Network: the backend node needs outbound TCP 443 to `api.push.apple.com` and `api.sandbox.push.apple.com` (17.0.0.0/8). Nothing inbound.2021## 2. Pipeline22231. The app registers its token: `POST /api/push/register { apns_token, environment, bundle_id, device_name?, locale?, app_version? }` → `{ ok, device_id }` (native sessions only). Registering the same token again updates the row and re-enables it. A token that moves to another user loses its per-device preferences and anything still queued for the previous user.242. The inbound watcher (`workers/inbound.ts`) calls the `push` hook inside its transaction. For each received message that is in an Inbox and not `$seen`, the hook inserts one `push_outbox` row per enabled device of every user who can read the mailbox (owner and `mailbox_grants.can_read`). `dedup_key = new:<device>:<mailbox>:<email>` is unique: replaying a watcher batch cannot produce a second alert. Messages received more than 24 hours ago (import, watcher stopped for a long time) are not announced.253. The dispatcher (`push dispatcher` worker, every `SPMAIL_WORKER_TICK_MS`) claims rows with `FOR UPDATE SKIP LOCKED` and a one-minute lease, computes the badge, signs the provider token (ES256, cached 50 minutes) and posts over a persistent HTTP/2 session per host.264. Result handling:2728| APNs answer | Classification | Effect |29|---|---|---|30| `200` | ok | row `sent`, `apns_id` recorded, device `last_push_at` updated, `last_error` cleared |31| `429`, `5xx`, network error or timeout (10 s), `403 ExpiredProviderToken` | retry | next attempt after 5 s, 30 s, 2 min, 10 min, 1 h; `failed` after 6 attempts or when the row is older than 24 h; the error is visible in the device's `last_error` |32| `410`, `400 BadDeviceToken`, `400 DeviceTokenNotForTopic`, `Unregistered` | drop-token | the device row is deleted (its queued rows go with it); the app registers again on next launch |33| any other `4xx` | fail | row `failed`, device `last_error` and `failure_count` updated |3435Rows that are no longer `pending` are pruned after 7 days.3637A device stops receiving as soon as its session ends: revoking the session (`DELETE /api/sessions/:id`), logging out, removing the passkey that opened it, or `DELETE /api/next/push/devices/:id` delete the token. As a safety net the dispatcher also deletes the device instead of sending when it finds the session revoked or expired (for example after `cli revoke-sessions`).3839## 3. Preferences4041User level (`GET` / `PUT /api/next/push/prefs`; `PUT` applies only the keys present in the body):4243| Key | Default | Effect |44|---|---|---|45| `enabled` | `true` | `false`: nothing is queued for this user |46| `preview` | `"sender"` | `none`: title `SP Mail`, generic body; `sender`: sender name, generic body; `full`: sender, subject (subtitle), start of the text |47| `quiet_hours` | `null` | `{ start: "22:00", end: "07:00", tz: "America/Toronto" }`, evaluated on the server in the IANA time zone (the range may span midnight). During quiet hours a new message produces a silent badge-only push instead of an alert |48| `priority_senders` | `[]` | addresses or `@domain` (exact domain); they bypass quiet hours and `priority_only`, and their alerts are `time-sensitive`. Contacts flagged `vip` are implicitly priority senders (when the contacts tables exist) |49| `priority_only` | `false` | only priority senders alert; everything else is a silent badge-only push |50| `mailboxes` | `{}` | `{ "<mailbox_id>": false }` mutes a mailbox: no alert, and it is left out of the badge |51| `badge` | `"inbox"` | `none`: no badge key in any payload and no silent badge pushes |5253Device level (`PATCH /api/next/push/devices/:id`): `enabled`, `prefs.mailboxes` (mute a mailbox on this device only), `prefs.sound` (`false` removes the sound). The generic texts follow the device `locale` (French when it starts with `fr`, otherwise English).5455## 4. Payloads5657Alert (`apns-push-type: alert`, `apns-priority: 10`, `apns-expiration`: now + 24 h, `apns-collapse-id`: 40 hex characters derived from the dedup key):5859```json60{ "aps": { "alert": { "title": "Alice Martin", "subtitle": "Budget 2027", "body": "Voici les chiffres…" },61           "badge": 4, "sound": "default", "thread-id": "<mailbox_id>:<thread_id>", "category": "MAIL_NEW",62           "mutable-content": 1, "interruption-level": "active" },63  "mb": "<mailbox_id>", "email": "<jmap email id>", "thread": "<jmap thread id>", "kind": "new" }64```6566`subtitle` exists only at preview level `full`. `interruption-level` is `time-sensitive` for a priority sender. `mb`, `email`, `thread` are opaque identifiers: the app fetches the message over its authenticated session.6768Silent badge update (`apns-push-type: background`, `apns-priority: 5`, `apns-collapse-id: badge`, expiration now + 1 h):6970```json71{ "aps": { "content-available": 1, "badge": 3 }, "kind": "badge" }72```7374Sent when mail is read, moved out of the Inbox or deleted from another client. Changes are debounced: one row per device (`dedup_key = badge:<device>`), re-armed by each change and sent 2 seconds after the first one, so a burst produces one push. The dispatcher skips the push when the computed badge equals the last badge sent to that device.7576Snooze and reminder (`kind: "snooze"` or `"reminder"`, `category: "MAIL_REMINDER"`): same shape as an alert; title = sender (snooze) or counterpart (reminder), body = subject (or the reminder's note). The `preview` preference applies: `sender` keeps the title only, `none` shows generic text. `kind: "test"` is the notification of `POST /api/next/push/test`; `kind: "alert"` is reserved for operator alerts (`enqueueUserPush`).7778Badge = sum of `unreadEmails` of the Inbox folder of every mailbox the user can read (muted mailboxes excluded), read from the mail server at send time.7980## 5. Monitoring8182`GET /api/next/push/status` (any device session; figures are those of the calling user):8384```json85{ "configured": true, "environment_hosts": { "production": "api.push.apple.com", "sandbox": "api.sandbox.push.apple.com" },86  "queue": { "pending": 0, "failed_24h": 0, "sent_24h": 12 }, "last_error": null }87```8889Whole-installation view, in SQL:9091```sql92select status, kind, count(*) from push_outbox where created_at > now() - interval '24 hours' group by 1, 2 order by 1, 2;93select id, device_name, bundle_id, environment, enabled, last_registered_at, last_push_at, last_error, failure_count from push_devices order by last_registered_at desc;94select id, kind, attempts, next_attempt_at, last_status, last_error from push_outbox where status = 'pending' order by next_attempt_at limit 50;95```9697Neither device tokens nor payloads are written to the logs. `push_outbox.payload` holds only the text already reduced to the user's preview level (`{"silent": true}` for a quiet-hours row).9899## 6. Troubleshooting100101| Symptom | Likely cause and action |102|---|---|103| `configured: false`, `last_error: "APNs is not configured…"` | one of the three variables is missing in the backend environment |104| `last_error: "the APNs key file cannot be read"` | wrong path or permissions; fix, the file is re-read within a minute |105| `last_error: "the APNs key is not a P-256 key"` | the file is not the `.p8` from Apple |106| device `last_error: "403 InvalidProviderToken"` | wrong key identifier or team identifier, or the key was revoked at Apple; rows end `failed` |107| device `last_error: "403 ExpiredProviderToken"` | the server clock is wrong (the token is re-signed and the row retried); check NTP |108| device `last_error: "400 TopicDisallowed"` / `"403 BadCertificateEnvironment"` | the bundle identifier is not covered by the key's team, or APNs is not enabled for the App ID |109| devices disappear right after a push | `BadDeviceToken`: a sandbox token registered as `production` or the reverse (debug builds must register `sandbox`); `DeviceTokenNotForTopic`: the app registers a `bundle_id` that is not its own |110| device `last_error: "0 network"` or `"0 timeout"`, rows stay `pending` | no route to APNs on 443 from the backend node; rows retry with backoff and fail after 6 attempts |111| alerts arrive without a badge | the mail server was unreachable when the alert was sent (the alert is not delayed for the badge) |112| a user gets only silent pushes | quiet hours are active in the configured time zone, or `priority_only` is on |113| nothing is queued for a new message | the message is not in the Inbox (Sieve filed it), is already `$seen`, the mailbox is muted, the user has no enabled device with a valid session, or push is not configured |114| a snoozed message did not come back | `select id, status, until, attempts, locked_until, last_error from snoozes where status = 'active' and until < now()`; a `last_error` means the mail server refused or was unreachable, the worker retries with a growing delay (10 minutes at most) |115116## 7. Snoozes and reminders (server state)117118- Snooze: the message is moved to a folder named `Snoozed` at the root of its mailbox (created on first use, no role) and gets the keyword `$snoozed`; the row keeps the folders it came from. At the due time the `snooze waker` worker moves it back (Inbox when the origin no longer exists), removes `$snoozed`, makes it unread and queues a `snooze` push. `DELETE /api/next/snoozes/:id` brings it back immediately without touching the read state and without a push (`cancelled`). A message deleted meanwhile ends `missing`; a message the user moved out of `Snoozed` by hand ends `done` with no push.119- Reminder: at the due time the `reminder evaluator` worker sets `$followup` on the message, marks the row `due` and queues a `reminder` push. With `only_if_no_reply`, it first reads the thread: a message that was not in the thread when the reminder was created (the row keeps the thread's message ids, so no clock is compared) and whose `From` is not one of the user's own addresses makes the reminder `resolved`, silently. A reminder on a deleted message ends `cancelled`.120- Both workers take a two-minute lease per row and write the final state and the push row in one transaction; the push `dedup_key` carries the snooze or reminder identifier, so a restart or a second instance cannot notify twice.121
Files main
Menu

Theme