M2: Web Push sender (VAPID) (ENG-255) · Pull Request #19 · demi.dev/pneumo

Linear: https://linear.app/engineereddev/issue/ENG-255

What's in this PR:

webpush/sender.ts: subscribes to the event bus push event. For every web device with a subscription, except the source, and only the target when there is one, it enqueues a send. Payload { t: "push", push } when the UTF-8 JSON is ≤ 3,000 bytes, else { t: "ref", id }. TTL 86,400 s, urgency high.
Queue: 1,000 waiting entries (drop oldest + warn), 4 workers, 10 s timeout per send; never awaited by the request path. Pushes from the 30 s reconcile notify once (10 min dedupe by push id).
404/410 clears the device's webPush (persisted through the registry); other errors warn without endpoint URLs or keys.
The VAPID keypair still comes from webpush/vapid.ts (ENG-250); the subject is read from config at send time.
DeviceRegistry.getWebPush(): registry DTOs omit subscriptions, so the sender reads them through this accessor.

Verify (lead, rebased on 3594894):

pnpm install --frozen-lockfile → exit 0
mise run check:server → exit 0 (Tests 229 passed (229))
mise run e2e:server → exit 0 (5 files, 15 tests; includes a sender e2e)
No pneumo-e2e-* containers left.

Deviations:

A VAPID subject that isn't https:/mailto: (e.g. the http dev PUBLIC_URL) disables delivery with one sanitized warning, instead of failing boot or push creation. .env.example now shows VAPID_SUBJECT=mailto:owner@example.test (commented, fake).
devices/registry.ts gains getWebPush() (outside the issue's Touches).

🤖 Generated with Claude Code

pneumo-reviewer: round 1, APPROVE #

The sender (webpush/sender.ts) matches §8 effect 3 and §10: targeting rules, payload vs ref at 3,000 UTF-8 bytes, TTL 86,400 and urgency high, a bounded drop-oldest queue (1,000 waiting, 4 workers, 10 s hard deadline) never awaited by the request path, 404/410 clearing, 10-minute dedupe, and a clean shutdown. The tests would catch the obvious mutations (source/target/platform checks, <= vs < at 3,000, drop-newest, clearing on 500, the dedupe and timeout boundaries). MinIO e2e covers 404/410/500 persistence and the reconciled-push path. No FIX findings.

Findings #

FILE (often 2 × bad 2 = 4), sender.ts:75-80: an explicitly set but invalid VAPID_SUBJECT (e.g. a bare email) passes config validation; delivery is silently off until one warning at the first push. Candidate: validate an explicit VAPID_SUBJECT in the config schema, or log the disabled state at sender start.
FILE (often 3 × bad 1 = 3), .env.example:22-23: the fake mailto: subject is commented out, so local dev has Web Push off by default. Relevant to the service-worker issue.
FILE (1), sender.ts:155-157: the payload object isn't typed against WebPushPayload from @pneumo/protocol (ws/hub.ts types its frames). Today's shape is correct and tested.

FILE items are recorded on ENG-275; code left alone.

Spec checks #

§10 OK (keypair reused from ENG-250; subject VAPID_SUBJECT ?? PUBLIC_URL read at send time; an invalid subject can't crash boot or POST and logs one warning without the value). §8 effect 3 OK (201 not delayed). §5.3 OK. §12.3 OK (see finding 1). §12.4 OK (logs carry only deviceId and statusCode; asserted).

DoD checks #

Unit tests with fake timers and clock, POST 201 with hanging sends, 401 without auth, MinIO e2e for storage effects, and redaction assertions (endpoint, p256dh, auth, private key, subject, error text, response body): all present. Edits outside Touches (registry.getWebPush, README, .env.example) are justified; no other branch touches them.

Tests run by the reviewer on 0763356: mise run check:server exit 0 (229 tests); mise run e2e:server exit 0 (15 tests); webpush tests 3× with no flakes. Pipeline for 0763356: 3/3 green.

Versions

pneumo-reviewer: round 1, APPROVE #

Findings #

Spec checks #

DoD checks #