devplacepy/devplacepy/push/CLAUDE.md

This file documents devplacepy/push/ - push notification delivery and its provider architecture. Claude Code loads it automatically whenever a file under this directory is read or edited.

What this package is

One delivery library behind one public surface. devplacepy.push exports notify_user, register, ensure_certificates, public_key_standard_b64 and the Web Push crypto helpers; every caller in the codebase (main.py, utils/notifications.py, routers/push.py) imports only those names. Everything else is internal to the package.

Module	Role
providers/base.py	PushProvider protocol, the Delivery outcome and the three outcome constants
providers/webpush.py	VAPID key material, aesgcm payload encryption, the Web Push provider
providers/apns.py	Apple Push Notification service provider (token based, HTTP/2)
providers/__init__.py	PROVIDERS registry, get, active, is_active, admin_fields, client_config
store.py	Every push_registration read and write
delivery.py	notify_user: group by provider, one shared client, one prepared body per provider

The admin configuration surface lives in devplacepy/services/push/service.py (PushService), not here.

Adding a provider

1. Write providers/<name>.py with a PushProvider subclass: name, label, config_fields, is_configured, parse_registration, prepare, deliver, optionally client_config.
2. Add one entry to PROVIDERS in providers/__init__.py.

That is the whole change. The registration route, the delivery loop, the admin page, the audit record, the metrics and the docs are written against the protocol and need no edit. The Enabled toggle (push_<name>_enabled) comes from the base class, so a provider never declares its own.

Invariants

• Zero cost for the request. Delivery is reached only through utils/notifications.py _schedule_push, a fire-and-forget task. Never make a route await notify_user, and never add a queue or a table to this path.
• deliver never raises. Return Delivery(REJECTED, detail) instead. delivery.py guards anyway, but a raising provider costs a log line per subscription.
• A provider that is not configured is inert, never an error. is_configured() is false, is_active() is false, the delivery loop skips it, and POST /push.json refuses a registration for it with 400. Nothing else in the platform notices.
• DEAD is the only outcome that touches the database. It soft-deletes the registration (deleted_at), exactly like a 404/410 Web Push endpoint always did. REJECTED keeps the row.
• Every insert writes deleted_at: None, and every read filters deleted_at IS NULL. push_registration deliberately stays out of SOFT_DELETE_TABLES (no deleted_by, not restorable from Trash) - a dead device token has no owner action to undo.
• A row without a provider is a Web Push row. store.provider_of resolves None/"" to DEFAULT_PROVIDER, so a row written by an old worker during a deploy still delivers. init_db backfills the column once with a single converging UPDATE.

Storage

push_registration columns are ensured in init_db (database/schema.py) because dataset only creates the columns of a table's first insert, and find(provider=...) against a missing column matches nothing.

Column	webpush	apns
provider	webpush	apns
endpoint, key_auth, key_p256dh	set	NULL
token	NULL	device token

Deduplication is generic: store.register looks up user_uid + provider + exactly the fields the provider's parse_registration returned, so a provider never writes its own identity rule.

APNs specifics

• POST https://{host}/3/device/{token} over HTTP/2, host from push_apns_environment (api.push.apple.com or api.sandbox.push.apple.com; an unrecognised value falls back to production). HTTP/2 comes from stealth_async_client because the origin is https - the cleartext downgrade in curl_transport does not apply.
• Provider token: ES256, header kid = key id, claims iss = team id and iat. Cached per credential fingerprint for 45 minutes, so a worker signs at most one token per 45 minutes; Apple refuses tokens regenerated faster than every 20 minutes. Editing any credential changes the fingerprint and takes effect on the next delivery, with no restart.
• A .p8 that does not parse is cached as a failure for the same window, so a misconfiguration costs one error log per window rather than one parse per notification.
• 410, or any status carrying reason BadDeviceToken, Unregistered, ExpiredToken, DeviceTokenNotForTopic or TopicDisallowed, is DEAD. Everything else is REJECTED.
• The shared payload dict (title, message, icon, url) is translated once per batch into aps.alert plus the custom url/icon keys, mirroring what service-worker.js does for Web Push. thread-id mirrors the service worker's notification tag.