docs: add a Role in the framework section to every module README

Each module README now says where the module sits in the dependency
graph, why it is its own module, and lists use cases for application
developers.
This commit is contained in:
2026-10-11 00:58:17 +02:00
parent 87953f68bf
commit 602e0412f3
24 changed files with 240 additions and 0 deletions

View File

@@ -19,6 +19,16 @@ The application owns the subscriptions. When a browser subscribes, the frontend
Endpoints come from browsers, so they are untrusted URLs. The driver only sends to `https` endpoints whose host is in `push.allowed_hosts`, checks this before it opens a connection, and never follows a redirect.
## Role in the framework
A leaf service module on `backpack`, `compass` and `bonfire`; the summer CLI uses it for VAPID key commands. It has no database dependency: the application stores subscriptions and hands them to the pusher. It is separate from `lighthouse` because Web Push reaches devices while the page is closed, while `lighthouse` serves live, subscribed browsers.
Use cases:
- Notify users on their devices when something they follow changes, even with the site closed.
- Generate VAPID keys from the command line.
- Clean up dead subscriptions when the push service reports them gone.
## Features
- `flare.Pusher` with one method, `Send(ctx, sub, payload, opts)`. `flare.SendOptions` sets the `TTL` (default `push.ttl`), `Urgency` and `Topic` headers.