Module push 

Web Push (kernel spec §6; plan 10a): the VAPID key pair in <data>/vapid.key and the tokens it signs, the owner’s push subscriptions, and each hat’s push policy. Delivery and its triggers are plan 10b’s. The subscriptions and the policies share the host registry’s connection and owner, as hats do, and every query names the owner (kernel spec §1).

Structs

NewSubscription

A subscription as the browser sent it (PushSubscription.toJSON()).

Notice

A notification for the owner’s devices, before the hat’s policy is applied (kernel spec §6; plan 10b decision 1). The modules that own a trigger fill it in (ACP core §10, gateway §7); delivery applies the policy, so no caller re-implements it:

Notices

The queue’s reading end, for delivery. Dropping it makes notify drop everything.

Push

Where notices go to be delivered (kernel spec §6): a queue that delivery (plan 10b-ii) drains. Cheap to clone; notify never waits and never fails, so a trigger can call it from any thread, async or not.

PushPolicy

A hat’s push policy (kernel spec §6). The default, for a hat with no row: not muted, no details, the session title shown.

Subscription

One stored subscription.

VapidKey

The collector’s VAPID key pair (RFC 8292): a P-256 key generated on the first start and kept in vapid.key (kernel spec §6). Every push subscription is bound to its public key, so the file is never replaced: one that cannot be read stops the start (decision 1). The private key leaves this type only as signatures.

Enums

Subscribed

The outcome of Hosts::subscribe and Hosts::rotate.

Urgency

How soon a push service should deliver a notification (RFC 8030 §5.3): high for “needs your answer”, normal otherwise (kernel spec §6).

Constants

MAX_CONTACT

The longest contact address accepted (RFC 5321’s path limit).

MAX_ENDPOINT

The longest endpoint accepted (decision 3). The push services’ own are a few hundred bytes.

MAX_SUBSCRIPTIONS

The subscriptions an owner may have at once (decision 5): each is a request per notification.

NOTICE_QUEUE

The tags waiting to be delivered, at most (plan 10b-i decision 5). A tag holds one notice, its latest, so one session cannot fill the queue for the others (10b-i’s review, A2).

VAPID_KEY_FILE

The VAPID private key’s file in the collector’s data directory (kernel spec §1).

VAPID_TOKEN_SECS

How long a VAPID token is valid. RFC 8292 §2 allows at most 24 hours.

Functions

audience

A VAPID token’s aud (RFC 8292 §2): the endpoint’s origin, scheme://host, with :port only when it is not the scheme’s default.

contact_problem

Why contact cannot be the owner’s push contact, or None: a plain e-mail address, which the VAPID token names as mailto: (kernel spec §6; plan 10a decision 7). Letters, digits and .+_- before the @; a domain name with a dot after it.

parse_endpoint

endpoint as a push subscription’s (decision 3), in the form it is stored, looked up and sent to (the review’s A2), or why it cannot be one. The push services’ endpoints are https URLs on their own domain names at the default port; anything else is refused before it is stored, and the address it resolves to is checked again on every send (kernel spec §7.1).

parse_keys

The subscription’s public key and secret (base64url, padded or not), in the form they are stored: base64url without padding, so delivery decodes them one way. Err unless they are a P-256 point, uncompressed, and 16 bytes (RFC 8291 §3.2).

subject

A VAPID token’s sub (kernel spec §6; maintainer decision 6b): mailto: the owner’s contact (contact_problem keeps it free of anything mailto: would need escaped), else the public_url origin when it is https. None for an http one (loopback): kernel §6 never sends a non-routable sub, and Apple refuses anything but mailto: or https: (the review’s N1), so the token carries none.

Type Aliases

NoticeGuard

Modules may revoke queued notification attempts without changing delivery policy.