Documentation
¶
Overview ¶
Package webpush implements gateway.OfflineChannel over the Web Push protocol (RFC 8291 encryption, RFC 8292 VAPID). When Registry.SendToGroup finds an identity offline everywhere in the cluster, the Registry hands the payload to Channel.Deliver, which encrypts and POSTs it to every push subscription the application holds for that group.
It is a separate package specifically so that importing the root gateway package never pulls in github.com/SherClockHolmes/webpush-go and its crypto dependencies for applications that do not use offline delivery.
Expired subscriptions ¶
A push service answers 404 or 410 for an endpoint whose subscription the browser has revoked. Deliver treats those two statuses as authoritative removal signals and calls SubscriptionStore.Remove so the application can drop the dead subscription, rather than retrying it forever.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Channel ¶
type Channel struct {
// contains filtered or unexported fields
}
Channel is a gateway.OfflineChannel backed by Web Push. Construct it with New. It is safe for concurrent use: it holds only immutable configuration and delegates all mutable state to the SubscriptionStore and the HTTP client.
func New ¶
func New(vapidPublic, vapidPrivate, subject string, store SubscriptionStore, opts ...Option) *Channel
New builds a Channel that signs notifications with the given VAPID key pair. subject is the VAPID "sub" claim identifying the application server to the push service, typically a "mailto:" or "https:" URL. store supplies the push subscriptions per group and receives removal of subscriptions the push service reports as gone.
func (*Channel) Deliver ¶
Deliver encrypts payload and POSTs it to every push subscription registered for group. It attempts every subscription regardless of individual failures and joins the resulting errors, so one dead endpoint does not suppress delivery to the rest. A subscription the push service answers 404 or 410 for is removed via SubscriptionStore.Remove and is not counted as a delivery error.
Deliver satisfies gateway.OfflineChannel.
type Option ¶
type Option func(*Channel)
Option customizes a Channel at construction time.
func WithHTTPClient ¶
func WithHTTPClient(c webpushgo.HTTPClient) Option
WithHTTPClient sets the HTTP client used to POST notifications to push services. The default is http.DefaultClient. Supplying a client is the seam tests use to redirect delivery to an httptest server, and lets applications impose their own timeouts and transport.
func WithRecordSize ¶
WithRecordSize caps the encrypted record size in bytes. Zero (the default) lets the underlying library pick its maximum.
func WithTTL ¶
WithTTL sets the seconds a push service should retain an undelivered notification for an offline client. The default is 60 seconds.
func WithUrgency ¶
WithUrgency sets the Urgency header a push service uses to decide how eagerly to wake a device. The default is webpushgo.UrgencyNormal.
type Subscription ¶
type Subscription struct {
// Endpoint is the push service URL the encrypted notification is POSTed to.
Endpoint string
// P256dh is the base64url-encoded P-256 ECDH public key of the subscription.
P256dh string
// Auth is the base64url-encoded authentication secret of the subscription.
Auth string
}
Subscription is a single browser Web Push subscription: the push service endpoint URL plus the two client public keys needed to encrypt the payload for it. These map directly onto the fields a browser's PushSubscription exposes (endpoint, keys.p256dh, keys.auth).
type SubscriptionStore ¶
type SubscriptionStore interface {
// Get returns every push subscription currently registered for group. An
// empty slice means the group has no push subscriptions and Deliver becomes
// a no-op for it.
Get(ctx context.Context, group string) ([]Subscription, error)
// Remove drops the subscription identified by endpoint from group. Deliver
// calls it when the push service answers 404 or 410 for that endpoint, i.e.
// the browser has revoked the subscription. Remove of an endpoint that is
// already absent must not error.
Remove(ctx context.Context, group string, endpoint string) error
}
SubscriptionStore is the application-owned mapping from an identity group to the Web Push subscriptions registered for it. The application populates it as clients subscribe; the Channel only reads from it and asks it to remove subscriptions the push service has reported as gone.
Source Files